annotate website/src/manual.html @ 383:4118eb51c816 0.4

minor
author Franklin Schmidt <fschmidt@gmail.com>
date Wed, 22 Apr 2015 20:46:59 -0600
parents 8557581740db
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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 &copy; 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">&sect;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">&sect;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">&sect;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">&sect;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">&sect;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">&sect;3.2</a> and <a href="#3.3.3">&sect;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">&sect;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">&sect;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
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
302 <p><tt><pre>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
303 raw_get(get_metatable(obj) or {}, "__" .. event_name)
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
304 </pre></tt></p>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
305
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
306 <p>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
307 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
308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
309 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
310
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
311 <li><b>"add": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
312 the <tt>+</tt> operation.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
313
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
314 If any operand for an addition is a table,
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
315 Luan will try to call a metamethod.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
316 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
317 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
318 then Luan will check the second operand.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
319 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
320 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
321 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
322 (adjusted to one value)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
323 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
324 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
325 it raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
326 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
327
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
328 <li><b>"sub": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
329 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
330
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
331 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
332 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
333
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
334 <li><b>"mul": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
335 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
336
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
337 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
338 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
340 <li><b>"div": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
341 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
342
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
343 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
344 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
345
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
346 <li><b>"mod": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
347 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
348
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
349 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
350 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
351
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
352 <li><b>"pow": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
353 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
354
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
355 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
356 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
357
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
358 <li><b>"unm": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
359 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
360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
361 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
362 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
364 <li><b>"concat": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
365 the <tt>..</tt> (concatenation) operation.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
366
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
367 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
368 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
369
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
370 <li><b>"len": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
371 the <tt>#</tt> (length) operation.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
372
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
373 If there is a metamethod,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
374 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
375 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
376 (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
377 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
378 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
379 then Luan uses the table length operation (see <a href="#3.4.7">&sect;3.4.7</a>).
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
380 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
381 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
382
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
383 <li><b>"eq": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
384 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
385
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
386 Behavior similar to the "add" operation,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
387 except that Luan will try a metamethod only when the values
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
388 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
389 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
390 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
391 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
392
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
393 <li><b>"lt": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
394 the <tt>&lt;</tt> (less than) operation.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
395
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
396 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
397 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
398 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
399
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
400 <li><b>"le": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
401 the <tt>&lt;=</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
402
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
403 Unlike other operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
404 The less-equal operation can use two different events.
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
405 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
406 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
407 If it cannot find such a metamethod,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
408 then it will try the "<tt>__lt</tt>" event,
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
409 assuming that <tt>a &lt;= b</tt> is equivalent to <tt>not (b &lt; a)</tt>.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
410 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
411 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
412 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
414 <li><b>"index": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
415 The indexing access <tt>table[key]</tt>.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
416
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
417 This event happens
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
418 when <tt>key</tt> is not present in <tt>table</tt>.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
419 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
420
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
423 Despite the name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
424 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
425 If it is a function,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
426 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
427 If it is a table,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
428 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
429 (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
430 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
431 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
432
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
433 <li><b>"newindex": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
434 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
435
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
436 Like the index event,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
437 this event happens when
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
438 when <tt>key</tt> is not present in <tt>table</tt>.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
439 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
440
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
443 Like with indexing,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
444 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
445 If it is a function,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
446 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
447 If it is a table,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
448 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
449 (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
450 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
451
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
454 Whenever there is a "newindex" metamethod,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
455 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
456 (If necessary,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
457 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
458 to do the assignment.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
459 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
460
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
461 <li><b>"call": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
462 The call operation <tt>func(args)</tt>.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
463
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
464 This event happens when Luan tries to call a table.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
465 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
466 If present,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
467 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
468 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
469 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
470
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
471 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
472
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
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
476 <h3 margin-top="1em"><a name="gc">Garbage Collection</a></h3>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
477
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
478 <p>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
479 Luan uses Java's garbage collection.
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
480
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 <h2 margin-top="1em"><a name="lang">The Language</a></h2>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
486
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
487 <p>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
488 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
489 In other words,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
490 this section describes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
491 which tokens are valid,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
492 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
493 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
494
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
497 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
498 in which
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
499 {<i>a</i>}&nbsp;means&nbsp;0 or more <i>a</i>'s, and
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
500 [<i>a</i>]&nbsp;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
501 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
502 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
503 and other terminal symbols are shown like &lsquo;<b>=</b>&rsquo;.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
504 The complete syntax of Luan can be found in <a href="#9">&sect;9</a>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
505 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
506
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
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
509 <h3 margin-top="1em"><a name="lex">Lexical Conventions</a></h3>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
510
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
511 <p>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
512 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
513 between lexical elements (tokens),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
514 except as delimiters between names and keywords.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
515 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
516
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
517 <p>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
518 <i>Names</i>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
519 (also called <i>identifiers</i>)
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
520 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
521 digits, and underscores,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
522 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
523 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
524
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
525
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
526 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
527 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
528 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
529
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
530
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
531 <p><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
532 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
533 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
534 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
535 then true until while
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
536 </pre></p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
537
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
538 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
539 Luan is a case-sensitive language:
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
540 <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
541 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
542
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
545 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
546
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
547 <p><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
548 + - * / % ^ #
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
549 &amp; ~ | &lt;&lt; &gt;&gt; //
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
550 == ~= &lt;= &gt;= &lt; &gt; =
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 ; : , . .. ...
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
553 </pre></p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
554
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
555 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
556 <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
557 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
558 and can contain the following C-like escape sequences:
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
559 '<tt>\a</tt>' (bell),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
560 '<tt>\b</tt>' (backspace),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
561 '<tt>\f</tt>' (form feed),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
562 '<tt>\n</tt>' (newline),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
563 '<tt>\r</tt>' (carriage return),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
564 '<tt>\t</tt>' (horizontal tab),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
565 '<tt>\v</tt>' (vertical tab),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
566 '<tt>\\</tt>' (backslash),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
567 '<tt>\"</tt>' (quotation mark [double quote]),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
568 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
569 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
570 results in a newline in the string.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
571 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
572 of white-space characters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
573 including line breaks;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
574 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
575 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
576 into the string contents.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
577
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
578
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
579 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
580 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
581 This can be done
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
582 with the escape sequence <tt>\x<i>XX</i></tt>,
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
583 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
584 or with the escape sequence <tt>\<i>ddd</i></tt>,
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
585 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
586 (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
587 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
588
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
589
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
590 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
591 Literal strings can also be defined using a long format
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
592 enclosed by <i>long brackets</i>.
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
593 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
594 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
595 opening square bracket.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
596 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
597 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
598 and so on.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
599 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
600 for instance,
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
601 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
602 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
603 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
604 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
605 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
606 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
607 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
608 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
609 (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
610 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
611 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
612
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
613
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
614 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
615 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
616 explicitly affected by the previous rules represents itself.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
617 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
618 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
619 some control characters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
620 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
621 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
622 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
623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
624
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
625 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
626 For convenience,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
627 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
628 the newline is not included in the string.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
629 As an example
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
630 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
631
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
632 <p><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
633 a = 'alo\n123"'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
634 a = "alo\n123\""
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
635 a = '\97lo\10\04923"'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
636 a = [[alo
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
637 123"]]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
638 a = [==[
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
639 alo
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
640 123"]==]
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
641 </pre></p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
642
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
643 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
644 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
645 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
646 and an optional decimal exponent,
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
647 marked by a letter '<tt>e</tt>' or '<tt>E</tt>'.
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
648 Luan also accepts hexadecimal constants,
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
649 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
650 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
651 plus an optional binary exponent,
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
652 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
653 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
654 denotes a float;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
655 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
656 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
657
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
658 <p><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
659 3 345 0xff 0xBEBADA
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
660 </pre></p>
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
661
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
662 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
663 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
664
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
665 <p><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
666 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
667 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
668 </pre></p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
669
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
670 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
671 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
672 anywhere outside a string.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
673 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
674 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
675 which runs until the end of the line.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
676 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
677 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
678 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
679
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
680
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
681
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
682
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
683
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
684 <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
685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
686 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
687 Variables are places that store values.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
688 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
689 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
690
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
692 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
693 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
694 (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
695 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
696
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
697 <p><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
698 var ::= Name
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
699 </pre></p>
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
700
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
701 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
702 Name denotes identifiers, as defined in <a href="#3.1">&sect;3.1</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
703
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
704
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
705 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
706 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
707 as a local (see <a href="#3.3.7">&sect;3.3.7</a>).
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
708 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
709 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
710 defined inside their scope (see <a href="#3.5">&sect;3.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
712
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
713 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
714 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
715
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
716
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
717 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
718 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
719
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
720 <p><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
721 var ::= prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo;
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
722 </pre></p>
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
723
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
724 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
725 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
726 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
727 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
728 (See <a href="#2.4">&sect;2.4</a> for a complete description of the
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
729 <tt>gettable_event</tt> function.
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
730 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
731 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
732
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 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
735 The syntax <tt>var.Name</tt> is just syntactic sugar for
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
736 <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
737
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
738 <p><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
739 var ::= prefixexp &lsquo;<b>.</b>&rsquo; Name
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
740 </pre></p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
741
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
742 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
743 An access to a global variable <tt>x</tt>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
744 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
745 Due to the way that chunks are compiled,
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
746 <tt>_ENV</tt> is never a global name (see <a href="#2.2">&sect;2.2</a>).
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
747
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
748
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 <h2>3.3 &ndash; <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
753
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
754 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
755 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
756 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
757 This set includes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
758 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
759 and variable declarations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
761
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 <h3>3.3.1 &ndash; <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
764
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
765 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
766 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
767 which are executed sequentially:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
768
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
769 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
770 block ::= {stat}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
771 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
772 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
773 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
774 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
775 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
776
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
777 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
778 stat ::= &lsquo;<b>;</b>&rsquo;
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
781 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
782 Function calls and assignments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
783 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
784 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
785 Consider the following fragment:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
786
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
787 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
788 a = b + c
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
789 (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
790 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
791 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
792
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
793 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
794 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
795
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 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
798 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
799 in the first way,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
800 interpreting the open parenthesis
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
801 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
802 To avoid this ambiguity,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
803 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
804 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
805
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
806 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
807 ;(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
808 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
809
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
810 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
811 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
812
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
813 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
814 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
815 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
816 Explicit blocks are useful
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
817 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
818 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
819 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
820 of another block (see <a href="#3.3.4">&sect;3.3.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
821
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
822
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
823
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 <h3>3.3.2 &ndash; <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
827
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
828 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
829 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
830 Syntactically,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
831 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
832
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
833 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
834 chunk ::= block
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
837 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
838 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
839 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
840 (see <a href="#3.4.11">&sect;3.4.11</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
841 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
842 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
843 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
844 scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">&sect;2.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
845 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
846 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
847
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
848
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
849 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
850 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
851 To execute a chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
852 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
853 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
854 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
855 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
856
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
858 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
859 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
860 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
861 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
862 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
863
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
864
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 <h3>3.3.3 &ndash; <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
869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
870 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
871 Lua allows multiple assignments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
872 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
873 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
874 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
875 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
876
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
877 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
878 stat ::= varlist &lsquo;<b>=</b>&rsquo; explist
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
879 varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
880 explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
881 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
882 Expressions are discussed in <a href="#3.4">&sect;3.4</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
883
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
884
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
885 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
886 Before the assignment,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
887 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
888 the list of variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
889 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
890 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
891 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
892 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
893 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
894 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
895 before the adjustment
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
896 (except when the call is enclosed in parentheses; see <a href="#3.4">&sect;3.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
897
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
899 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
900 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
901 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
902 Thus the code
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
903
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
904 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
905 i = 3
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
906 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
907 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
908 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
909 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
910 before it is assigned&nbsp;4.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
911 Similarly, the line
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
912
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
913 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
914 x, y = y, x
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
915 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
916 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
917 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
918
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
919 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
920 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
921 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
922 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
923
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
924
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
925 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
926 The 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
927 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
928 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
929 <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
930 (See <a href="#2.4">&sect;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
931 <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
932 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
933 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
934
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
935
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
936 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
937 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
938 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
939 <code>_ENV.x = val</code> (see <a href="#2.2">&sect;2.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
940
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
941
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 <h3>3.3.4 &ndash; <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
946 The control structures
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
947 <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
948 familiar syntax:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
949
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
950
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 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
954 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
955 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
956 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
957 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
958 Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">&sect;3.3.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
959
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
960
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
961 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
962 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
963 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
964 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
965 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
966 (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
967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
969 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
970 In the <b>repeat</b>&ndash;<b>until</b> loop,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
971 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
972 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
973 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
974 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
975
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
976
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
977 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
978 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
979 For syntactical reasons,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
980 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
981
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
982
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 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
985 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
986 stat ::= label
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
987 label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
988 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
989
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
990 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
991 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
992 except
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
993 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
994 inside nested functions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
995 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
996 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
997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
998
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
999 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1000 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
1001 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
1002
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1003
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1004 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1005 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
1006 <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
1007 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
1008
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1009
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1010 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1011 stat ::= <b>break</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1012 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1013 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
1014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1016 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1017 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
1018 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
1019 (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
1020
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1021 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
1022 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
1023
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1024 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1025 stat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1028 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1029 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
1030 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
1031 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
1032 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
1033 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
1034 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
1035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1036
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 <h3>3.3.5 &ndash; <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
1041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1042 <p>
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 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
1045 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
1046
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1047
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1048 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1049 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
1050 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
1051 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
1052
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1053 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1054 stat ::= <b>for</b> Name &lsquo;<b>=</b>&rsquo; exp &lsquo;<b>,</b>&rsquo; exp [&lsquo;<b>,</b>&rsquo; exp] <b>do</b> block <b>end</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1055 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1056 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
1057 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
1058 third <em>exp</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1059 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
1060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1061 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1062 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
1063 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1064 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
1065
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1066 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1067 do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1068 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
1069 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
1070 <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
1071 while true do
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 if (<em>step</em> &gt;= 0 and <em>var</em> &gt; <em>limit</em>) or (<em>step</em> &lt; 0 and <em>var</em> &lt; <em>limit</em>) then
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1074 break
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1075 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1076 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
1077 <em>block</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1078 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1079 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1080 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1081
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1082 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1083 Note the following:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1084
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1085 <ul>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1088 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
1089 before the loop starts.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1090 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
1091 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1092
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 <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
1095 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
1096 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1097
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 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
1100 then a step of&nbsp;1 is used.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1101 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1102
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1103 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1104 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
1105 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1106
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 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
1109 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
1110 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
1111 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1113 </ul>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1116 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
1117 called <em>iterators</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1118 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
1119 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
1120 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
1121
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1122 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1123 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
1124 namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1125 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1126 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
1127
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1128 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1129 for <em>var_1</em>, &middot;&middot;&middot;, <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
1130 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1131 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
1132
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1133 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1134 do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1135 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
1136 while true do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1137 local <em>var_1</em>, &middot;&middot;&middot;, <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
1138 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
1139 <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
1140 <em>block</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1141 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1142 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1143 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1144 Note the following:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1145
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1146 <ul>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1149 <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
1150 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
1151 a <em>state</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1152 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
1153 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1154
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 <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
1157 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
1158 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1159
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 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
1162 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1163
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1164 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1165 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
1166 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
1167 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
1168 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
1169 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1170
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1171 </ul>
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
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 <h3>3.3.6 &ndash; <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
1177 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
1178 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
1179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1180 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1181 stat ::= functioncall
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1182 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1183 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
1184 Function calls are explained in <a href="#3.4.10">&sect;3.4.10</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1185
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1186
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 <h3>3.3.7 &ndash; <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
1191 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
1192 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
1193
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1194 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1195 stat ::= <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1196 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1197 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
1198 of a multiple assignment (see <a href="#3.3.3">&sect;3.3.3</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1199 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
1200
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1201
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1202 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1203 A chunk is also a block (see <a href="#3.3.2">&sect;3.3.2</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1204 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
1205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1206
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1207 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1208 The visibility rules for local variables are explained in <a href="#3.5">&sect;3.5</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1210
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 <h2>3.4 &ndash; <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
1217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1218 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1219 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
1220
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1221 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1222 exp ::= prefixexp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1223 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
1224 exp ::= Numeral
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1225 exp ::= LiteralString
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1226 exp ::= functiondef
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1227 exp ::= tableconstructor
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1228 exp ::= &lsquo;<b>...</b>&rsquo;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1229 exp ::= exp binop exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1230 exp ::= unop exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1231 prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1232 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1233
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1234 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1235 Numerals and literal strings are explained in <a href="#3.1">&sect;3.1</a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1236 variables are explained in <a href="#3.2">&sect;3.2</a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1237 function definitions are explained in <a href="#3.4.11">&sect;3.4.11</a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1238 function calls are explained in <a href="#3.4.10">&sect;3.4.10</a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1239 table constructors are explained in <a href="#3.4.9">&sect;3.4.9</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1240 Vararg expressions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1241 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
1242 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
1243 they are explained in <a href="#3.4.11">&sect;3.4.11</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1244
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1245
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1246 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1247 Binary operators comprise arithmetic operators (see <a href="#3.4.1">&sect;3.4.1</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1248 bitwise operators (see <a href="#3.4.2">&sect;3.4.2</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1249 relational operators (see <a href="#3.4.4">&sect;3.4.4</a>), logical operators (see <a href="#3.4.5">&sect;3.4.5</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1250 and the concatenation operator (see <a href="#3.4.6">&sect;3.4.6</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1251 Unary operators comprise the unary minus (see <a href="#3.4.1">&sect;3.4.1</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1252 the unary bitwise not (see <a href="#3.4.2">&sect;3.4.2</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1253 the unary logical <b>not</b> (see <a href="#3.4.5">&sect;3.4.5</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1254 and the unary <em>length operator</em> (see <a href="#3.4.7">&sect;3.4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1255
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1256
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1257 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1258 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
1259 If a function call is used as a statement (see <a href="#3.3.6">&sect;3.3.6</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1260 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
1261 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
1262 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
1263 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
1264 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
1265 (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
1266 In all other contexts,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1267 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
1268 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
1269 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
1270
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1271
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1272 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1273 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1274
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1275 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1276 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
1277 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
1278 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
1279 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
1280 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
1281 -- 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
1282 -- 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
1283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1284 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
1285 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
1286 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
1287 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
1288 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
1289 {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
1290 {...} -- 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
1291 {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
1292 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1293
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1294 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1295 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
1296 Thus,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1297 <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
1298 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
1299 (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
1300 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
1301
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1302
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 <h3>3.4.1 &ndash; <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
1305 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
1306
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1307 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1308 <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
1309 <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
1310 <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
1311 <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
1312 <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
1313 <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
1314 <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
1315 <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
1316 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1317
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1318 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1319 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
1320 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
1321 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
1322 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
1323 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
1324 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
1325 numbers (see <a href="#3.4.3">&sect;3.4.3</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1326 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
1327 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
1328 for floating-point arithmetic
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1329 (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
1330 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
1331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1332
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1333 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1334 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
1335 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
1336 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
1337 Exponentiation uses the ISO&nbsp;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
1338 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
1339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1341 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1342 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
1343 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
1344 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
1345
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1346
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1347 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1348 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
1349 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
1350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1351
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1352 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1353 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
1354 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
1355 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
1356 (In other words,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1357 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
1358 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
1359
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1361
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1362 <h3>3.4.2 &ndash; <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
1363 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
1364
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1365 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1366 <li><b><code>&amp;</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
1367 <li><b><code>&#124;</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
1368 <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
1369 <li><b><code>&gt;&gt;</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
1370 <li><b><code>&lt;&lt;</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
1371 <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
1372 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1373
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1374 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1375 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
1376 (see <a href="#3.4.3">&sect;3.4.3</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1377 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
1378 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
1379
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1380
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1381 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1382 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
1383 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
1384 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
1385 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
1386 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
1387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1388
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 <h3>3.4.3 &ndash; <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
1393 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
1394 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
1395 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
1396 Exponentiation and float division
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1397 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
1398 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
1399 (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
1400 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
1401 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
1402 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
1403 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
1404 besides strings.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1405
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1406
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1407 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1408 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
1409 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
1410
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1412 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1413 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
1414 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
1415 that is the result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1416 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1417 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
1418 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
1419 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
1420
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1421
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1422 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1423 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
1424 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
1425 (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
1426 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
1427 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
1428 Otherwise, the conversion fails.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1429
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1430
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1431 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1432 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
1433 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
1434 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
1435 (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
1436 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
1437 (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
1438
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1439
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1440 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1441 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
1442 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
1443 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
1444 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
1445 (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
1446
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1447
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 <h3>3.4.4 &ndash; <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
1452 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
1453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1454 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1455 <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
1456 <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
1457 <li><b><code>&lt;</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
1458 <li><b><code>&gt;</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
1459 <li><b><code>&lt;=</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
1460 <li><b><code>&gt;=</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
1461 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1462 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
1463
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1465 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1466 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
1467 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
1468 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
1469 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
1470 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
1471 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
1472 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
1473 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
1474 and compared as such.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1475
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1476
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1477 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1478 Tables, userdata, and threads
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1479 are compared by reference:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1480 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
1481 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
1482 (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
1483 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
1484 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
1485 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
1486 (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
1487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1488
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1489 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1490 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
1491 by using the "eq" metamethod (see <a href="#2.4">&sect;2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1492
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1493
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1494 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1495 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
1496 or vice versa.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1497 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
1498 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
1499 entries in a table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1502 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1503 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
1504
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1505
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1506 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1507 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
1508 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
1509 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
1510 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
1511 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
1512 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
1513 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
1514 metamethod (see <a href="#2.4">&sect;2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1515 A comparison <code>a &gt; b</code> is translated to <code>b &lt; a</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1516 and <code>a &gt;= b</code> is translated to <code>b &lt;= a</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1517
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1518
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 <h3>3.4.5 &ndash; <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
1523 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
1524 <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
1525 Like the control structures (see <a href="#3.3.4">&sect;3.3.4</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1526 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
1527 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
1528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1529
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1530 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1531 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
1532 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
1533 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
1534 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
1535 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
1536 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
1537 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
1538 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
1539 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1540 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
1541 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1543 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1544 10 or 20 --&gt; 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1545 10 or error() --&gt; 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1546 nil or "a" --&gt; "a"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1547 nil and 10 --&gt; nil
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1548 false and error() --&gt; false
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1549 false and nil --&gt; false
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1550 false or nil --&gt; nil
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1551 10 and 20 --&gt; 20
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1552 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1553 (In this manual,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1554 <code>--&gt;</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
1555
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1556
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 <h3>3.4.6 &ndash; <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
1561 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
1562 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
1563 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
1564 strings according to the rules described in <a href="#3.4.3">&sect;3.4.3</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1565 Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">&sect;2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1566
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1567
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 <h3>3.4.7 &ndash; <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
1572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1573 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1574 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
1575 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
1576 (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
1577 character is one byte).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1578
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1580 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1581 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
1582 any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">&sect;2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1583
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1584
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1585 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1586 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
1587 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
1588 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
1589 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1590 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
1591 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
1592 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
1593 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
1594
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1595 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1596 {10, 20, nil, 40}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1597 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1598 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
1599 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
1600 (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
1601 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
1602 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
1603 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
1604
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1605
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 <h3>3.4.8 &ndash; <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
1610 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
1611 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
1612
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1613 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1614 or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1615 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1616 &lt; &gt; &lt;= &gt;= ~= ==
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1617 |
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 &amp;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1620 &lt;&lt; &gt;&gt;
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 unary operators (not # - ~)
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 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1627 As usual,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1628 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
1629 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
1630 operators are right associative.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1631 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
1632
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1633
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1634
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 <h3>3.4.9 &ndash; <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
1638 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
1639 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
1640 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
1641 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
1642 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
1643
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1644 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1645 tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1646 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
1647 field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1648 fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1649 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1650
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1651 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1652 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
1653 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
1654 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
1655 <code>["name"] = exp</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1656 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
1657 <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
1658 starting with 1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1659 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
1660 For example,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1661
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1662 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1663 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
1664 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1665 is equivalent to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1667 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1668 do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1669 local t = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1670 t[f(1)] = g
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1671 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
1672 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
1673 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
1674 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
1675 t[30] = 23
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1676 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
1677 a = t
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1678 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1679 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1680
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1681 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1682 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
1683 (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
1684
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1686 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1687 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
1688 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
1689 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
1690 (see <a href="#3.4.10">&sect;3.4.10</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1692
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1693 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1694 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
1695 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
1696
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1697
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 <h3>3.4.10 &ndash; <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
1702 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
1703
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1704 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1705 functioncall ::= prefixexp args
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1706 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1707 In a function call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1708 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
1709 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
1710 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
1711 with the given arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1712 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
1713 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
1714 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
1715 (see <a href="#2.4">&sect;2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1716
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1718 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1719 The form
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1720
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1721 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1722 functioncall ::= prefixexp &lsquo;<b>:</b>&rsquo; Name args
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1723 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1724 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
1725 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
1726 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
1727 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
1728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1730 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1731 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
1732
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1733 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1734 args ::= &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1735 args ::= tableconstructor
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1736 args ::= LiteralString
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1737 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1738 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
1739 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
1740 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
1741 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
1742 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
1743 (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
1744 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
1745 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
1746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1747
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1748 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1749 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
1750 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
1751 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
1752 (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
1753 in a tail call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1754 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
1755 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
1756 a program can execute.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1757 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
1758 calling function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1759 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
1760 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
1761 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
1762 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
1763 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
1764
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1765 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1766 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
1767 return 2 * f(x)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1768 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
1769 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
1770 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
1771 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1772
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1773
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 <h3>3.4.11 &ndash; <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
1777
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1778 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1779 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
1780
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1781 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1782 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
1783 funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1784 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1785
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1786 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1787 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
1788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1789 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1790 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
1791 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
1792 funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1793 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1794 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1795
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1796 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1797 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
1798 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1799 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1800
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1801 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1802 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
1803 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1804 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1805
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1806 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1807 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
1808 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1809 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1811 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1812 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
1813 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1814 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1816 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1817 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
1818 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1819 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1820
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1821 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1822 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
1823 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1824 not to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1826 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1827 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
1828 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1829 (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
1830 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
1831
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1832
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1833 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1834 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
1835 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
1836 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
1837 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
1838 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
1839 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
1840 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
1841 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
1842
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1843
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1844 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1845 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
1846 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
1847
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1848 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1849 parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1850 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1851 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
1852 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
1853 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
1854 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
1855 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
1856 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
1857 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
1858 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
1859 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
1860 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
1861 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
1862 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
1863 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
1864 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
1865 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
1866 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
1867 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
1868 (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
1869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1870
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1871 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1872 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
1873
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1874 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1875 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
1876 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
1877 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
1878 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1879 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
1880 to the vararg expression:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1881
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1882 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1883 CALL PARAMETERS
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1884
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1885 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
1886 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
1887 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
1888 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
1889 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
1890
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1891 g(3) a=3, b=nil, ... --&gt; (nothing)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1892 g(3, 4) a=3, b=4, ... --&gt; (nothing)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1893 g(3, 4, 5, 8) a=3, b=4, ... --&gt; 5 8
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1894 g(5, r()) a=5, b=1, ... --&gt; 2 3
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1895 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1896
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1897 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1898 Results are returned using the <b>return</b> statement (see <a href="#3.3.4">&sect;3.3.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1899 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
1900 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
1901 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
1902
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1903
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1904 <p>
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 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
1907 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
1908 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
1909
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1910
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1911 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1912 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
1913 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
1914 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
1915 Thus, the statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1916
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1917 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1918 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
1919 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1920 is syntactic sugar for
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1921
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1922 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1923 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
1924 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1925
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1926
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 <h2>3.5 &ndash; <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
1932
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1933 <p>
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 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
1936 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
1937 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
1938 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
1939 Consider the following example:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1940
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1941 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1942 x = 10 -- global variable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1943 do -- new block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1944 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
1945 print(x) --&gt; 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1946 x = x+1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1947 do -- another block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1948 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
1949 print(x) --&gt; 12
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1950 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1951 print(x) --&gt; 11
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) --&gt; 10 (the global one)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1954 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1955
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1956 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1957 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
1958 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
1959 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
1960
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1961
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1962 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1963 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
1964 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
1965 defined inside their scope.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1966 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
1967 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
1968 inside the inner function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1970
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1971 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1972 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
1973 defines new local variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1974 Consider the following example:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1975
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1976 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1977 a = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1978 local x = 20
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1979 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
1980 local y = 0
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1981 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
1982 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1983 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1984 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
1985 (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
1986 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
1987 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
1988
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1989
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 <h1>4 &ndash; <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
1994
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1995 <p>
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 This section describes the C&nbsp;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
1998 the set of C&nbsp;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
1999 with Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2000 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
2001 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
2002
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2003
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2004 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2005 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
2006 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
2007 Except where stated otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2008 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
2009 (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
2010 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
2011
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2012
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2013 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2014 As in most C&nbsp;libraries,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2015 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
2016 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
2017 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
2018
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2019
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 <h2>4.1 &ndash; <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
2022
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2023 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2024 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
2025 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
2026 (<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
2027
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2028
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2029 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2030 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
2031 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
2032 C&nbsp;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
2033 This stack initially contains any arguments to the C&nbsp;function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2034 and it is where the C&nbsp;function pushes its results
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2035 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
2036
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2037
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2038 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2039 For convenience,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2040 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
2041 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
2042 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
2043 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
2044 (starting at&nbsp;1);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2045 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
2046 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
2047 then index&nbsp;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
2048 (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
2049 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2050 index&nbsp;<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
2051 index&nbsp;-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
2052 (that is, the element at the&nbsp;top)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2053 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
2054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2055
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 <h2>4.2 &ndash; <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
2060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2061 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2062 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
2063 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
2064 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2065 <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
2066 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
2067 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
2068
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2069
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2070 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2071 Whenever Lua calls C,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2072 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
2073 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
2074 <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
2075 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
2076 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
2077
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2078
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2079 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2080 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
2081 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
2082 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
2083 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
2084 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
2085 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
2086
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2087
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2088
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 <h2>4.3 &ndash; <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
2092
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2093 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2094 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
2095 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
2096
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2097
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2098 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2099 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
2100 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
2101 its position lies between&nbsp;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
2102 (<code>1 &le; abs(index) &le; top</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2103
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2104 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
2105 require valid indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2106
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2107
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2108 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2109 Unless otherwise noted,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2110 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
2111 which represent some Lua values that are accessible to C&nbsp;code
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2112 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
2113 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
2114 and the upvalues of a C&nbsp;function (see <a href="#4.4">&sect;4.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2115
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2116
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2117 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2118 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
2119 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
2120 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
2121 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
2122 including the pseudo-indices,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2123 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
2124 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
2125 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
2126 (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
2127 Except when noted otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2128 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
2129
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2130
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2131 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2132 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
2133 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
2134 For instance, a C&nbsp;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
2135 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
2136 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
2137
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2138
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2139 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2140 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
2141 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
2142 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
2143 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
2144
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2145
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2146
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 <h2>4.4 &ndash; <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
2150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2151 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2152 When a C&nbsp;function is created,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2153 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
2154 thus creating a <em>C&nbsp;closure</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2155 (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
2156 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
2157 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
2158
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2159
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2160 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2161 Whenever a C&nbsp;function is called,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2162 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
2163 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
2164 <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
2165 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
2166 <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
2167 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
2168 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
2169 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
2170 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
2171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2172
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2173
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 <h2>4.5 &ndash; <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
2177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2178 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2179 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
2180 a predefined table that can be used by any C&nbsp;code to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2181 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
2182 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
2183 <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
2184 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
2185 Any C&nbsp;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
2186 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
2187 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
2188 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
2189 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
2190 or a light userdata with the address of a C&nbsp;object in your code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2191 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
2192 As with variable names,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2193 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
2194 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
2195
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2196
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2197 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2198 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
2199 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
2200 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
2201 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
2202
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2203
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2204 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2205 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
2206 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
2207 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
2208 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
2209 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
2210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2211 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2212 <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
2213 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
2214 (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
2215 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2216
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2217 <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
2218 the global environment.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2219 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2220 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2221
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2222
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 <h2>4.6 &ndash; <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
2226
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2227 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2228 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
2229 (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
2230 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
2231 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
2232 (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
2233 and runtime errors)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2234 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
2235 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
2236 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
2237 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
2238 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
2239
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2241 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2242 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
2243 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
2244 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
2245 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
2246 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
2247 never returning
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2248 (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
2249
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2250
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2251 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2252 The panic function runs as if it were a message handler (see <a href="#2.3">&sect;2.3</a>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2253 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
2254 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
2255 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
2256 the panic function must first check the available space (see <a href="#4.2">&sect;4.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2257
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2259 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2260 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
2261 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
2262 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
2263 it can raise errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2264
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2265
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2266 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2267 Inside a C&nbsp;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
2268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2270
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2271
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 <h2>4.7 &ndash; <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
2274
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2275 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2276 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
2277 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
2278 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
2279 (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
2280 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
2281 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
2282
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2284 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2285 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
2286 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
2287 except for three functions:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2288 <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
2289 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
2290 (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
2291
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2293 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2294 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
2295 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
2296 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
2297 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
2298 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
2299 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
2300 (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
2301 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
2302 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
2303
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2305 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2306 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
2307 After the thread resumes,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2308 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
2309 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2310 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
2311 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
2312 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
2313 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
2314 As the name implies,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2315 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
2316 of the original function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2317
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2318
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2319 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2320 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
2321
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2322 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2323 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
2324 ... /* code 1 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2325 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
2326 ... /* code 2 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2327 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2328 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2329 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
2330 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
2331 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
2332
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2333 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2334 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
2335 ... /* code 2 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2336 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2338 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
2339 ... /* code 1 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2340 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
2341 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2342 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2343 In the above code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2344 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
2345 <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
2346 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
2347 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
2348 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
2349 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
2350 (errors or yielding),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2351 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
2352 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
2353
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2354 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2355 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
2356 ... /* code 1 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2357 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
2358 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2359 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2360 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
2361 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
2362 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
2363 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
2364 <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
2365 (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
2366 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
2367
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2368
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2369 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2370 Besides the Lua state,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2371 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
2372 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
2373 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
2374 (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
2375 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
2376 continuation function.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2377 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
2378 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
2379 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
2380 (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
2381 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
2382 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
2383 (For these two functions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2384 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
2385 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
2386 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
2387 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
2388 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
2389 (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
2390 directly the continuation function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2391 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
2392
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2393
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2394 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2395 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
2396 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
2397 from the original function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2398 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
2399 (For instance,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2400 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
2401 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
2402 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
2403 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
2404 of the original function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2405
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2406
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 <h2>4.8 &ndash; <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
2411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2412 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2413 Here we list all functions and types from the C&nbsp;API in
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2414 alphabetical order.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2415 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
2416 <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
2417
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2418
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2419 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2420 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
2421 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
2422 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
2423 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
2424 (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
2425 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
2426 <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
2427 depending on the situation;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2428 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
2429 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
2430 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
2431 (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
2432 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
2433 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
2434 '<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
2435 '<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
2436 '<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
2437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2438
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 <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
2441 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2442 <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
2443
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2444 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2445 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
2446 (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
2447
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2448
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 <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
2453 <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
2454 void *ptr,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2455 size_t osize,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2456 size_t nsize);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2457
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2458 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2459 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
2460 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
2461 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
2462 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
2463 Its arguments are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2464 <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
2465 <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
2466 <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
2467 is being allocated;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2468 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
2469
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2470
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2471 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2472 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
2473 <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
2474 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
2475
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2476
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2477 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2478 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
2479 <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
2480 <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
2481 <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
2482 <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
2483 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
2484 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
2485 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
2486
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2488 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2489 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
2490
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2491
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2492 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2493 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
2494 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
2495 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
2496
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2497
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2498 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2499 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
2500 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
2501 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
2502 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
2503 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
2504 <code>osize &gt;= nsize</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2505
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2506
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2507 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2508 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
2509 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
2510
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2511 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2512 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
2513 size_t nsize) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2514 (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
2515 if (nsize == 0) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2516 free(ptr);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2517 return NULL;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2518 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2519 else
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2520 return realloc(ptr, nsize);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2521 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2522 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2523 Note that Standard&nbsp;C ensures
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2524 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
2525 <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
2526 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
2527 (Although Standard&nbsp;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
2528 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
2529
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2530
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 <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
2535 <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
2536 <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
2537
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2538 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2539 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
2540 (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
2541 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
2542 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
2543 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
2544 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
2545 (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
2546
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2547
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2548 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2549 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
2550
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2551 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2552
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2553 <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
2554 <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
2555 <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
2556 <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
2557 <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
2558 <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
2559 <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
2560 <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
2561 <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
2562 <li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise and (<code>&amp;</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_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
2564 <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
2565 <li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code>&lt;&lt;</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_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>&gt;&gt;</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2567
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2568 </ul>
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
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 <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
2574 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2575 <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
2576
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2577 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2578 Sets a new panic function and returns the old one (see <a href="#4.6">&sect;4.6</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2581
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 <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
2585 <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
2586 <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
2587
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2588 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2589 Calls a function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2590
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2591
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2592 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2593 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
2594 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
2595 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
2596 in direct order;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2597 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
2598 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
2599 <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
2600 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
2601 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
2602 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
2603 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
2604 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
2605 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
2606 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
2607 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
2608 (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
2609 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
2610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2611
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2612 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2613 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
2614 (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
2615
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2616
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2617 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2618 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
2619 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
2620
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2621 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2622 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
2623 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2624 Here it is in&nbsp;C:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2625
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2626 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2627 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
2628 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
2629 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
2630 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
2631 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
2632 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
2633 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
2634 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
2635 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2636 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
2637 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
2638 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
2639
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2640
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 <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
2645 <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
2646 <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
2647 int nargs,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2648 int nresults,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2649 lua_KContext ctx,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2650 lua_KFunction k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2651
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2652 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2653 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
2654 but allows the called function to yield (see <a href="#4.7">&sect;4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2655
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2656
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 <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
2661 <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
2662
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2663 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2664 Type for C&nbsp;functions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2667 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2668 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
2669 a C&nbsp;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
2670 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
2671 a C&nbsp;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
2672 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
2673 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
2674 <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
2675 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
2676 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
2677 To return values to Lua, a C&nbsp;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
2678 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
2679 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
2680 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
2681 discarded by Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2682 Like a Lua function, a C&nbsp;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
2683 many results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2684
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2686 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2687 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
2688 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
2689
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2690 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2691 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
2692 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
2693 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
2694 int i;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2695 for (i = 1; i &lt;= n; i++) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2696 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
2697 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
2698 lua_error(L);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2699 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2700 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
2701 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2702 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
2703 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
2704 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
2705 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2706 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2709
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 <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
2712 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2713 <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
2714
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2715 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2716 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
2717 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
2718 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
2719 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
2720 (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
2721 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
2722 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
2723 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
2724 it is left unchanged.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2725
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2726
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 <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
2731 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2732 <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
2733
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2734 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2735 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
2736 (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
2737 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
2738 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
2739 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
2740 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
2741 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
2742 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
2743
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2744
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 <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
2749 <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
2750 <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
2751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2752 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2753 Compares two Lua values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2754 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
2755 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
2756 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
2757 (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
2758 Otherwise returns&nbsp;0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2759 Also returns&nbsp;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
2760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2762 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2763 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
2764
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2765 <ul>
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 <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
2768 <li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code>&lt;</code>)</li>
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_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code>&lt;=</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2770
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2771 </ul>
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
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 <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
2777 <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
2778 <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
2779
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2780 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2781 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
2782 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
2783 If <code>n</code>&nbsp;is&nbsp;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
2784 (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
2785 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
2786 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
2787 (see <a href="#3.4.6">&sect;3.4.6</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2789
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2790
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2791
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2792
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2793 <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
2794 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2795 <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
2796
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2797 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2798 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
2799 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
2800 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
2801 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
2802
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2803
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 <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
2808 <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
2809 <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
2810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2811 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2812 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
2813 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
2814 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
2815 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
2816 the table will have.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2817 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
2818 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
2819 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
2820 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
2821
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2822
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 <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
2827 <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
2828 <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
2829 lua_Writer writer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2830 void *data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2831 int strip);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2832
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2833 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2834 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
2835 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
2836 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
2837 if loaded again,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2838 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
2839 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
2840 <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
2841 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
2842 to write them.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2843
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2844
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2845 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2846 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
2847 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
2848 about the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2849
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2850
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2851 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2852 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
2853 call to the writer;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2854 0&nbsp;means no errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2855
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2856
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2857 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2858 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
2859
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2860
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 <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
2865 <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
2866 <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
2867
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2868 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2869 Generates a Lua error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2870 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
2871 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
2872 and therefore never returns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2873 (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
2874
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2875
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 <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
2880 <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
2881 <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
2882
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2883 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2884 Controls the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2885
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2886
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2887 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2888 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
2889 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
2890
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2891 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2892
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2893 <li><b><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
2894 stops the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2895 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2896
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2897 <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
2898 restarts the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2899 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2900
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2901 <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
2902 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
2903 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2904
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2905 <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
2906 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
2907 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2908
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2909 <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
2910 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
2911 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
2912 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2913
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2914 <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
2915 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
2916 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2917
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2918 <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
2919 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
2920 for the <em>pause</em> of the collector (see <a href="#2.5">&sect;2.5</a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2921 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
2922 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2923
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2924 <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
2925 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
2926 the collector (see <a href="#2.5">&sect;2.5</a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2927 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
2928 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2929
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2930 <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
2931 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
2932 (i.e., not stopped).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2933 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2934
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2935 </ul>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2938 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
2939 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
2940
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2941
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 <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
2946 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2947 <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
2948
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2949 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2950 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
2951 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
2952 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
2953
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2954
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 <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
2959 <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
2960 <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
2961
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2962 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2963 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
2964 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
2965 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
2966 for the "index" event (see <a href="#2.4">&sect;2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2969 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2970 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
2971
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2972
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 <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
2977 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2978 <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
2979
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2980 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2981 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
2982 given Lua state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2983 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
2984 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
2985
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2986
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2987 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2988 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
2989 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
2990
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2992 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2993 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
2994 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
2995 (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
2996
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2998
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2999
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3001 <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
3002 <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
3003 <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
3004
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3005 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3006 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
3007 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
3008
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3009
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 <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
3014 <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
3015 <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
3016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3017 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3018 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
3019 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
3020 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
3021 for the "index" event (see <a href="#2.4">&sect;2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3022
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3023
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3024 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3025 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
3026
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3027
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 <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
3032 <span class="apii">[-0, +(0|1), &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3033 <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
3034
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3035 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3036 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
3037 the function pushes that metatable onto the stack and returns&nbsp;1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3038 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3039 the function returns&nbsp;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
3040
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3042
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 <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
3046 <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
3047 <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
3048
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3049 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3050 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
3051 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
3052 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
3053
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3055 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3056 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
3057 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
3058 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
3059 for the "index" event (see <a href="#2.4">&sect;2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3062 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3063 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
3064
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3065
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3066
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3067
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3068
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3069 <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
3070 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3071 <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
3072
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3073 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3074 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
3075 Because indices start at&nbsp;1,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3076 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
3077 in particular, 0&nbsp;means an empty stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3078
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3079
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 <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
3084 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3085 <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
3086
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3087 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3088 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
3089 at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3090
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3091
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3092 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3093 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
3094
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3095
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 <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
3100 <span class="apii">[-1, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3101 <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
3102
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3103 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3104 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
3105 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
3106 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
3107 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
3108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3109
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 <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
3114 <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
3115
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3116 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3117 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
3118
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3119
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3120 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3121 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
3122 (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
3123 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
3124 (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
3125 (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
3126
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3127
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3128 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3129 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
3130 <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
3131 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
3132
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3133
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 <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
3138 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3139 <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
3140
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3141 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3142 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
3143 and 0&nbsp;otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3144
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3145
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3146
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3147
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 <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
3150 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3151 <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
3152
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3153 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3154 Returns 1 if the value at the given index is a C&nbsp;function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3155 and 0&nbsp;otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3156
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3157
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 <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
3162 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3163 <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
3164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3165 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3166 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
3167 (either C or Lua), and 0&nbsp;otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3168
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3169
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 <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
3174 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3175 <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
3176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3177 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3178 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
3179 (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
3180 and 0&nbsp;otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3181
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3182
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 <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
3187 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3188 <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
3189
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3190 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3191 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
3192 and 0&nbsp;otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3193
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3194
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 <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
3199 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3200 <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
3201
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3202 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3203 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
3204 and 0&nbsp;otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3206
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 <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
3211 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3212 <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
3213
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3214 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3215 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
3216 and 0&nbsp;otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3218
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3219
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 <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
3223 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3224 <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
3225
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3226 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3227 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
3228 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
3229 and 0&nbsp;otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3230
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3231
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 <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
3236 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3237 <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
3238
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3239 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3240 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
3241 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
3242 and 0&nbsp;otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3243
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3244
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3245
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 <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
3249 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3250 <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
3251
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3252 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3253 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
3254 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
3255 and 0&nbsp;otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3256
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3257
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3258
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 <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
3262 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3263 <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
3264
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3265 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3266 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
3267 and 0&nbsp;otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3270
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 <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
3274 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3275 <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
3276
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3277 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3278 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
3279 and 0&nbsp;otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3281
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3282
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3285 <hr><h3><a name="lua_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
3286 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3287 <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
3288
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3289 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3290 Returns 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
3291 (either full or light), and 0&nbsp;otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3293
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3294
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3295
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3297 <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
3298 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3299 <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
3300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3301 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3302 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
3303 and 0&nbsp;otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3305
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 <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
3310 <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
3311
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3312 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3313 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
3314 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
3315 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
3316 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
3317 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
3318 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
3319
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3320
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 <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
3325 <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
3326
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3327 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3328 Type for continuation functions (see <a href="#4.7">&sect;4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3330
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3332
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 <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
3335 <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
3336 <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
3337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3338 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3339 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
3340 It is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">&sect;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
3341 may trigger a metamethod for the "length" event (see <a href="#2.4">&sect;2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3342 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
3343
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3344
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3345
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 <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
3349 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3350 <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
3351 lua_Reader reader,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3352 void *data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3353 const char *chunkname,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3354 const char *mode);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3355
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3356 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3357 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
3358 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
3359 <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
3360 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
3361 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
3362
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3364 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3365 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
3366
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3367 <ul>
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 <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
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 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
3372 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
3373
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3374 <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
3375 memory allocation error;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3376
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3377 <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
3378 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
3379 (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
3380 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
3381 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3382
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3383 </ul>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3386 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
3387 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
3388 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
3389
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3391 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3392 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
3393 which is used for error messages and in debug information (see <a href="#4.9">&sect;4.9</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3394
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3395
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3396 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3397 <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
3398 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
3399 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
3400 with the addition that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3401 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
3402
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3403
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3404 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3405 <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
3406 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
3407 unmodified when returning.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3408
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3409
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3410 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3411 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
3412 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
3413 stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">&sect;4.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3414 When loading main chunks,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3415 this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">&sect;2.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3416 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
3417
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3418
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3419
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3420
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3421
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3422 <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
3423 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3424 <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
3425
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3426 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3427 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
3428 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
3429 (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
3430 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
3431 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
3432 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
3433 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
3434
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3435
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3436
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3438
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3439 <hr><h3><a name="lua_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
3440 <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
3441 <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
3442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3443 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3444 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
3445 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
3446
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3447
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 <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
3452 <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
3453 <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
3454
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3455 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3456 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
3457 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
3458 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
3459 its global environment,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3460 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
3461
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3462
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3463 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3464 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
3465 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
3466 like any Lua object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3467
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3468
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 <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
3473 <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
3474 <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
3475
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3476 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3477 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
3478 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
3479 and returns this address.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3480 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
3481
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3482
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 <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
3487 <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
3488 <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
3489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3490 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3491 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
3492 and pushes a key&ndash;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
3493 (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
3494 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
3495 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
3496
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3497
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3498 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3499 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
3500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3501 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3502 /* 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
3503 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
3504 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
3505 /* 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
3506 printf("%s - %s\n",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3507 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
3508 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
3509 /* 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
3510 lua_pop(L, 1);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3511 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3512 </pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3515 While traversing a table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3516 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
3517 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
3518 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
3519 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
3520 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
3521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3523 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3524 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
3525 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
3526
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3527
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 <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
3532 <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
3533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3534 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3535 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
3536
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3537
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3538 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3539 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
3540 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
3541 (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
3542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3543
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 <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
3548 <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
3549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3550 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3551 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
3552 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
3553 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
3554 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
3555 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
3556 conversion was successful.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3557 (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
3558 correctly without this macro,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3559 due to roundings.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3560
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3561
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3562 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3563 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
3564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3565
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3566
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 <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
3570 <span class="apii">[-(nargs + 1), +(nresults|1), &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3571 <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
3572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3573 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3574 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
3575
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3576
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3577 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3578 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
3579 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
3580 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
3581 <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
3582 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
3583 <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
3584 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
3585 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
3586 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
3587 <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
3588 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
3589
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3590
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3591 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3592 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
3593 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
3594 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
3595 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
3596 <em>message handler</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3597 (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
3598 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
3599 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
3600 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
3601 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
3602
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3603
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3604 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3605 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
3606 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
3607 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
3608 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
3609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3611 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3612 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
3613 (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
3614
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3615 <ul>
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 <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
3618 success.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3619
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3620 <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
3621 a runtime error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3622 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3624 <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
3625 memory allocation error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3626 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
3627 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3628
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3629 <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
3630 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
3631 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3632
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3633 <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
3634 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
3635 (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
3636 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3637
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3638 </ul>
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
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 <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
3644 <span class="apii">[-(nargs + 1), +(nresults|1), &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3645 <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
3646 int nargs,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3647 int nresults,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3648 int msgh,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3649 lua_KContext ctx,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3650 lua_KFunction k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3651
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3652 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3653 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
3654 but allows the called function to yield (see <a href="#4.7">&sect;4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3655
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3656
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 <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
3661 <span class="apii">[-n, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3662 <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
3663
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3664 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3665 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
3666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3667
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 <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
3672 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3673 <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
3674
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3675 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3676 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
3677
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3678
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 <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
3683 <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
3684 <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
3685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3686 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3687 Pushes a new C&nbsp;closure onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3688
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3689
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3690 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3691 When a C&nbsp;function is created,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3692 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
3693 thus creating a C&nbsp;closure (see <a href="#4.4">&sect;4.4</a>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3694 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
3695 To associate values with a C&nbsp;function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3696 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
3697 (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
3698 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
3699 is called to create and push the C&nbsp;function onto the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3700 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
3701 associated with the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3702 <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
3703
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3704
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3705 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3706 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
3707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3709 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3710 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
3711 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
3712 which is just a pointer to the C&nbsp;function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3713 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
3714
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3715
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 <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
3720 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3721 <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
3722
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3723 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3724 Pushes a C&nbsp;function onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3725 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
3726 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
3727 when called, invokes the corresponding C&nbsp;function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3730 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3731 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
3732 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
3733 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
3734
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3736 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3737 <code>lua_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
3738
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3739 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3740 #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
3741 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3742 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
3743
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3744
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 <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
3749 <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
3750 <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
3751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3752 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3753 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
3754 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
3755 It is similar to the ISO&nbsp;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
3756 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
3757
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3758 <ul>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3761 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
3762 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
3763 (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
3764 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3766 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3767 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
3768 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
3769 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
3770 '<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
3771 '<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
3772 '<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
3773 '<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
3774 '<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
3775 '<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
3776 '<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
3777 '<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
3778 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3779
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3780 </ul>
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
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 <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
3786 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3787 <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
3788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3789 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3790 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
3791
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3792
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 <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
3797 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3798 <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
3799
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3800 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3801 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
3802
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3803
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 <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
3808 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3809 <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
3810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3811 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3812 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
3813
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3814
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3815 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3816 Userdata represent C&nbsp;values in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3817 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
3818 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
3819 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
3820 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
3821 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
3822 light userdata with the same C&nbsp;address.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3826
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 <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
3829 <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
3830 <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
3831
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3832 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3833 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
3834 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
3835 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
3836
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3837
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3838
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 <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
3842 <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
3843 <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
3844
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3845 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3846 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
3847 onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3848 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
3849 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
3850 the function returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3851 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
3852 including embedded zeros.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3853
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3854
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3855 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3856 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
3857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3858
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 <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
3863 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3864 <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
3865
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3866 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3867 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
3868
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3870
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3871
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 <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
3874 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3875 <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
3876
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3877 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3878 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
3879
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3880
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 <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
3885 <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
3886 <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
3887
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3888 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3889 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
3890 onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3891 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
3892 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
3893 the function returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3894
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3895
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3896 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3897 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
3898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3899
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3900 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3901 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
3902
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3903
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 <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
3908 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3909 <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
3910
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3911 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3912 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
3913 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
3914
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3915
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3916
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3917
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 <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
3920 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3921 <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
3922
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3923 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3924 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
3925 onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3926
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3927
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 <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
3932 <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
3933 <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
3934 const char *fmt,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3935 va_list argp);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3936
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3937 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3938 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
3939 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
3940
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3941
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 <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
3946 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3947 <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
3948
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3949 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3950 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
3951 <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
3952 (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
3953 Otherwise returns&nbsp;0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3954 Also returns&nbsp;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
3955
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3956
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3957
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 <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
3961 <span class="apii">[-1, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3962 <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
3963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3964 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3965 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
3966 (i.e., without metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3969
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 <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
3973 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3974 <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
3975
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3976 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3977 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
3978 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
3979 The access is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3980 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
3981
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3982
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3983 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3984 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
3985
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3986
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 <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
3991 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3992 <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
3993
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3994 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3995 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
3996 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
3997 <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
3998 The access is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3999 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
4000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4001
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4002 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4003 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
4004
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4005
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 <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
4010 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4011 <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
4012
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4013 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4014 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
4015 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
4016 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
4017 with no metamethods;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4018 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
4019 for the userdata;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4020 for other values, it is&nbsp;0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4021
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4022
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 <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
4027 <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
4028 <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
4029
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4030 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4031 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
4032 (i.e., without metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4033
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4034
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 <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
4039 <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
4040 <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
4041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4042 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4043 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
4044 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
4045 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
4046
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4047
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4048 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4049 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
4050 The assignment is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4051 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
4052
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4053
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 <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
4058 <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
4059 <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
4060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4061 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4062 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
4063 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
4064 <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
4065 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
4066
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4067
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4068 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4069 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
4070 The assignment is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4071 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
4072
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4073
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 <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
4078 <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
4079 void *data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4080 size_t *size);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4081
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4082 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4083 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
4084 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
4085 <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
4086 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
4087 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
4088 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
4089 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
4090 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
4091 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
4092 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
4093 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
4094
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4095
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 <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
4100 <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
4101 <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
4102
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4103 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4104 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
4105 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
4106
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4107 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4108 #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
4109 (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
4110 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4111
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4112
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 <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
4116 <span class="apii">[-1, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4117 <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
4118
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4119 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4120 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
4121 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
4122 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
4123 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
4124
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4125
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 <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
4130 <span class="apii">[-1, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4131 <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
4132
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4133 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4134 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
4135 without shifting any element
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4136 (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
4137 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
4138
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4139
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4140
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 <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
4144 <span class="apii">[-?, +?, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4145 <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
4146
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4147 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4148 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
4149
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4151 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4152 To start a coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4153 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
4154 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
4155 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
4156 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
4157 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
4158 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
4159 <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
4160 <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
4161 <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
4162 without errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4163 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
4164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4166 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4167 In case of errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4168 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
4169 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
4170 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
4171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4172
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4173 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4174 To resume a coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4175 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
4176 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
4177 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
4178 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
4179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4180
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4181 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4182 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
4183 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
4184 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
4185
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4186
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 <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
4191 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4192 <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
4193
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4194 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4195 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
4196 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
4197 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
4198 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
4199 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
4200 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
4201
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4202
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 <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
4207 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4208 <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
4209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4210 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4211 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
4212 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
4213
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4214
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 <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
4219 <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
4220 <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
4221
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4222 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4223 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
4224 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
4225 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
4226
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4227
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4228 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4229 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
4230 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
4231 for the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4233
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 <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
4238 <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
4239 <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
4240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4241 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4242 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
4243 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
4244
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4245
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4247
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 <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
4250 <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
4251 <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
4252
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4253 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4254 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
4255 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
4256 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
4257
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4259 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4260 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
4261 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
4262 for the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4263
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4264
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 <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
4269 <span class="apii">[-1, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4270 <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
4271
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4272 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4273 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
4274 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
4275
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4276
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4277
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 <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
4281 <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
4282 <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
4283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4284 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4285 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
4286 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
4287 <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
4288 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
4289
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4290
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4291 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4292 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
4293 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
4294 for the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4295
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4297
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4298
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4299
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4300 <hr><h3><a name="lua_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
4301 <span class="apii">[-?, +?, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4302 <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
4303
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4304 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4305 Accepts any index, or&nbsp;0,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4306 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
4307 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
4308 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
4309 If <code>index</code> is&nbsp;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
4310
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4311
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4312
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 <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
4316 <span class="apii">[-1, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4317 <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
4318
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4319 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4320 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
4321 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
4322
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4323
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 <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
4328 <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
4329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4330 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4331 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
4332 (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
4333 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
4334 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
4335 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
4336
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4338 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4339 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
4340 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
4341 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
4342
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4343
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 <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
4348 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4349 <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
4350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4351 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4352 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
4353
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4354
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4355 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4356 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
4357 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
4358 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
4359 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
4360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4361
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4362 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4363 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
4364 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
4365 (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
4366 (to resume a coroutine).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4367
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4368
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 <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
4373 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4374 <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
4375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4376 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4377 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
4378 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
4379 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
4380 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
4381 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
4382 according to the lexical conventions of Lua (see <a href="#3.1">&sect;3.1</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4383 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
4384 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
4385 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
4386 (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
4387 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
4388
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4389
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 <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
4394 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4395 <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
4396
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4397 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4398 Converts the Lua value at the given index to a C&nbsp;boolean
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4399 value (0&nbsp;or&nbsp;1).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4400 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
4401 <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
4402 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
4403 otherwise it returns false.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4404 (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
4405 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
4406
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4407
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4408
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 <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
4412 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4413 <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
4414
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4415 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4416 Converts a value at the given index to a C&nbsp;function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4417 That value must be a C&nbsp;function;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4418 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
4419
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4420
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 <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
4425 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4426 <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
4427
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4428 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4429 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
4430
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4431
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 <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
4436 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4437 <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
4438
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4439 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4440 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
4441 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
4442 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
4443 or a number or string convertible to an integer (see <a href="#3.4.3">&sect;3.4.3</a>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4444 otherwise, <code>lua_tointegerx</code> returns&nbsp;0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4445
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4446
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4447 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4448 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
4449 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
4450 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
4451
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4454
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4455
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4456 <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
4457 <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
4458 <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
4459
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4460 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4461 Converts the Lua value at the given index to a C&nbsp;string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4462 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
4463 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
4464 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
4465 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
4466 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
4467 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
4468 <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
4469 (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
4470 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
4471
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4473 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4474 <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
4475 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
4476 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
4477 after its last character (as in&nbsp;C),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4478 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
4479
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4480
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4481 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4482 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
4483 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
4484 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
4485
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4486
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4487
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 <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
4491 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4492 <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
4493
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4494 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4495 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
4496
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4497
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 <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
4502 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4503 <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
4504
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4505 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4506 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
4507 to the C&nbsp;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
4508 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
4509 (see <a href="#3.4.3">&sect;3.4.3</a>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4510 otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns&nbsp;0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4511
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4513 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4514 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
4515 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
4516 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
4517
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4518
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 <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
4523 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4524 <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
4525
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4526 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4527 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
4528 C&nbsp;pointer (<code>void*</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4529 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
4530 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
4531 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
4532 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
4533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4534
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4535 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4536 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
4537
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4538
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 <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
4543 <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
4544 <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
4545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4546 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4547 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
4548
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4550
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 <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
4554 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4555 <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
4556
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4557 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4558 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
4559 (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
4560 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
4561 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
4562
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4563
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 <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
4568 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4569 <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
4570
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4571 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4572 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
4573 returns its block address.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4574 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
4575 returns its pointer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4576 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
4577
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4578
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 <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
4583 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4584 <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
4585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4586 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4587 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
4588 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
4589 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
4590 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
4591 <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
4592 <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
4593 <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
4594 <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
4595 <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
4596 <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
4597 <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
4598 <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
4599 and
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_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
4601
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4602
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 <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
4607 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4608 <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
4609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4610 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4611 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
4612 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
4613
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4614
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 <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
4619 <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
4620
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4621 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4622 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
4623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4624
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 <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
4629 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4630 <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
4631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4632 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4633 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
4634 the running function (see <a href="#4.4">&sect;4.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4635
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4636
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4637
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4638
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4639
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4640 <hr><h3><a name="lua_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
4641 <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
4642 <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
4643
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4644 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4645 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
4646 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
4647 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
4648 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
4649 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
4650
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4651
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4652
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4653
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4654
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4655 <hr><h3><a name="lua_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
4656 <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
4657 const void* p,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4658 size_t sz,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4659 void* ud);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4660
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4661 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4662 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
4663 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
4664 <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
4665 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
4666 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
4667 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
4668
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4669
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4670 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4671 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
4672 0&nbsp;means no errors;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4673 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
4674 calling the writer again.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4676
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4677
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4678
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 <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
4681 <span class="apii">[-?, +?, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4682 <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
4683
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4684 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4685 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
4686
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4687
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4688 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4689 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
4690 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
4691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4692
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 <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
4697 <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
4698 <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
4699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4700 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4701 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
4702 but it has no continuation (see <a href="#4.7">&sect;4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4703 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
4704 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
4705 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
4706
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4709
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4710
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4711 <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
4712 <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
4713 <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
4714 int nresults,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4715 lua_KContext ctx,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4716 lua_KFunction k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4718 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4719 Yields a coroutine (thread).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4720
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4721
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4722 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4723 When a C&nbsp;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
4724 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
4725 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
4726 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
4727 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
4728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4730 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4731 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
4732 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
4733 the execution of the C function that yielded (see <a href="#4.7">&sect;4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4734 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
4735 from the previous function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4736 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
4737 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
4738 Moreover,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4739 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
4740 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
4741
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4743 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4744 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
4745 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
4746 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
4747 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
4748 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
4749 from inside a line hook (see <a href="#4.9">&sect;4.9</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4750 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
4751 (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
4752 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
4753 Lua will yield and,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4754 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
4755 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
4756 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
4757
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4758
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4759 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4760 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
4761 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
4762 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
4763 (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
4764
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4765
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 <h2>4.9 &ndash; <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
4772
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4773 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4774 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
4775 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
4776 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
4777 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
4778 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
4779 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
4780
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4781
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 <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
4784 <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
4785 int event;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4786 const char *name; /* (n) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4787 const char *namewhat; /* (n) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4788 const char *what; /* (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4789 const char *source; /* (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4790 int currentline; /* (l) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4791 int linedefined; /* (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4792 int lastlinedefined; /* (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4793 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
4794 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
4795 char isvararg; /* (u) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4796 char istailcall; /* (t) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4797 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
4798 /* private part */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4799 <em>other fields</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4800 } lua_Debug;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4801
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4802 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4803 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
4804 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
4805 <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
4806 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
4807 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
4808 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
4809
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4811 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4812 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
4813
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4814 <ul>
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 <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
4817 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
4818 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
4819 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
4820 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
4821 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
4822 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
4823 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4824 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
4825 <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
4826 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4827
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4828 <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
4829 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
4830 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4831
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4832 <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
4833 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
4834 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4835
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4836 <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
4837 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
4838 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4839
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4840 <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
4841 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
4842 <code>"C"</code> if it is a C&nbsp;function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4843 <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
4844 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4845
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4846 <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
4847 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
4848 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
4849 <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
4850 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4851
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4852 <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
4853 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
4854 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
4855 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
4856 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
4857 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
4858 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
4859 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
4860 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
4861 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
4862 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4863
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4864 <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
4865 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
4866 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
4867 <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
4868 <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
4869 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
4870 (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
4871 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4872
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4873 <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
4874 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
4875 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
4876 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4877
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4878 <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
4879 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
4880 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4881
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4882 <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
4883 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
4884 (always 0&nbsp;for C&nbsp;functions).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4885 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4886
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4887 <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
4888 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
4889 (always true for C&nbsp;functions).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4890 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4891
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4892 </ul>
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
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 <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
4898 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4899 <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
4900
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4901 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4902 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
4903
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4904
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4905
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4906
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4907
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4908 <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
4909 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4910 <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
4911
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4912 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4913 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
4914
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4915
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 <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
4920 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4921 <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
4922
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4923 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4924 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
4925
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4926
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 <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
4931 <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
4932 <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
4933
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4934 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4935 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
4936
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4937
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4938 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4939 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
4940 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
4941 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
4942 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
4943
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4944
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4945 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4946 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
4947 and start the <code>what</code> string with the character '<code>&gt;</code>'.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4948 (In that case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4949 <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
4950 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
4951 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
4952
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4953 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4954 lua_Debug ar;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4955 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
4956 lua_getinfo(L, "&gt;S", &amp;ar);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4957 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
4958 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4959
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4960 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4961 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
4962 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
4963 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
4964
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4965 <ul>
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 <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
4968 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4970 <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
4971 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
4972 <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
4973 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4974
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4975 <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
4976 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4978 <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
4979 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4981 <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
4982 <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
4983 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4984
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4985 <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
4986 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
4987 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
4988 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4989
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4990 <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
4991 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
4992 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
4993 (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
4994 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
4995 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
4996
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4998 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4999 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
5000 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
5001 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5002
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5003 </ul>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5006 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
5007 (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
5008
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5009
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5010
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 <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
5014 <span class="apii">[-0, +(0|1), &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5015 <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
5016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5017 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5018 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
5019 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
5020
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5021
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5022 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5023 In the first case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5024 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
5025 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
5026 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
5027 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
5028 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
5029 and names.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5030
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5032 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5033 <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
5034 and returns its name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5036
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5037 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5038 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
5039 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
5040 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
5041 (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
5042 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
5043
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5044
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5045 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5046 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
5047 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
5048 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
5049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5050
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5051
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 <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
5055 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5056 <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
5057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5058 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5059 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
5060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5062 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5063 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
5064 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
5065 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
5066 Level&nbsp;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
5067 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
5068 (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
5069 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
5070 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
5071 it returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5072
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5073
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 <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
5078 <span class="apii">[-0, +(0|1), &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5079 <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
5080
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5081 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5082 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
5083 (For Lua functions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5084 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
5085 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
5086 <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
5087 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
5088 and returns its name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5089 <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
5090 (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
5091 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
5092 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
5093
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5094
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5095 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5096 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
5097 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
5098 For C&nbsp;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
5099 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
5100
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5101
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 <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
5106 <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
5107
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5108 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5109 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
5110
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5111
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5112 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5113 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
5114 <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
5115 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
5116 <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
5117 <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
5118 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
5119 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
5120 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
5121 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
5122
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5123
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5124 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5125 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
5126 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
5127 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
5128
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5129
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5130 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5131 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
5132 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
5133 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
5134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5135
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5136 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5137 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
5138 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
5139 <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
5140
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5141
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5142 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5143 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
5144 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
5145 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
5146 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
5147 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
5148
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5149
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5151
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 <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
5154 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5155 <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
5156
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5157 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5158 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
5159
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5160
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5161 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5162 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
5163 <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
5164 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
5165 <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
5166 <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
5167 <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
5168 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
5169 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
5170 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
5171 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
5172
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5173 <ul>
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 <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
5176 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
5177 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
5178 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5180 <li><b>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
5181 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
5182 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
5183 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
5184 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5185
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5186 <li><b>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
5187 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
5188 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
5189 (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
5190 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5191
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5192 <li><b>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
5193 <code>count</code> instructions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5194 (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
5195 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5196
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5197 </ul>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5200 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
5201
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5202
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 <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
5207 <span class="apii">[-(0|1), +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5208 <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
5209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5210 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5211 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
5212 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
5213 (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
5214 <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
5215 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
5216 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
5217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5218
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5219 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5220 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
5221 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
5222 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
5223
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5224
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 <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
5229 <span class="apii">[-(0|1), +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5230 <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
5231
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5232 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5233 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
5234 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
5235 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
5236 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
5237 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
5238 (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
5239
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5241 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5242 Returns <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
5243 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
5244
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5245
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5247
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5248
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5249 <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
5250 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5251 <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
5252
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5253 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5254 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
5255 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
5256 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
5257 (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
5258 (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
5259
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5261 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5262 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
5263 closures share upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5264 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
5265 (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
5266 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
5267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5270
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 <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
5273 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5274 <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
5275 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
5276
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5277 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5278 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
5279 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
5280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5281
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 <h1>5 &ndash; <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
5288
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5289 <p>
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 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
5292 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
5293 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
5294 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
5295 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
5296 common tasks.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5297
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5298
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5299 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5300 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
5301 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
5302 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
5303
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5305 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5306 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
5307 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
5308 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
5309 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
5310 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
5311
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5312
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5313 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5314 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
5315 extra stack slots.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5316 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
5317 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
5318 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
5319
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5320
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5321 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5322 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
5323 check C&nbsp;function arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5324 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
5325 (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
5326 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
5327
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5328
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5329 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5330 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
5331 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
5332
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5333
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 <h2>5.1 &ndash; <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
5336
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5337 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5338 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
5339 in alphabetical order.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5341
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 <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
5344 <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
5345 <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
5346
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5347 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5348 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
5349 (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
5350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5351
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5352
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5353
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 <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
5356 <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
5357 <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
5358
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5359 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5360 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
5361 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
5362 (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
5363 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
5364
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5365
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 <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
5370 <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
5371 <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
5372
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5373 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5374 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
5375 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
5376 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
5377
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5378
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 <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
5383 <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
5384 <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
5385
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5386 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5387 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
5388 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
5389 (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
5390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5391
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5392
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5393
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5394
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5395 <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
5396 <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
5397 <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
5398
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5399 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5400 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
5401 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
5402 (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
5403 Pops the value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5404
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5405
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5406 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5407 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
5408 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
5409 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
5410
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5411
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 <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
5416 <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
5417 <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
5418 int cond,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5419 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5420 const char *extramsg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5421
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5422 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5423 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
5424 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
5425
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5426
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 <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
5431 <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
5432 <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
5433
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5434 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5435 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
5436 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
5437 using a standard message
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5438 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
5439
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5440 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5441 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
5442 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5443 This function never returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5444
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5445
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 <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
5450 <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
5451
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5452 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5453 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
5454
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5455
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5456 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5457 A string buffer allows C&nbsp;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
5458 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
5459
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5460 <ul>
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 <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
5463
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5464 <li>Then initialize it with a call <code>luaL_buffinit(L, &amp;b)</code>.</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>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5467 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
5468 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
5469 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5470
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 Finish by calling <code>luaL_pushresult(&amp;b)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5473 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
5474 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5475
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5476 </ul>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5479 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
5480 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
5481
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5482 <ul>
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 <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
5485
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5486 <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
5487 size <code>sz</code> with a call <code>luaL_buffinitsize(L, &amp;b, sz)</code>.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5488
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5489 <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
5490
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5491 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5492 Finish by calling <code>luaL_pushresultsize(&amp;b, sz)</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5493 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
5494 copied into that space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5495 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5496
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5497 </ul>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5500 During its normal operation,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5501 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
5502 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
5503 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
5504 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
5505 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
5506 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5507 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
5508 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
5509 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
5510 (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
5511 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
5512 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
5513 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
5514
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5515
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 <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
5520 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5521 <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
5522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5523 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5524 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
5525 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
5526 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
5527 (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
5528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5529
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 <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
5534 <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
5535 <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
5536
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5537 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5538 Equivalent to the sequence
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5539 <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
5540
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5543
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5544
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5545 <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
5546 <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
5547 <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
5548
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5549 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5550 Calls a metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5551
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5552
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5553 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5554 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
5555 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
5556 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
5557 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
5558 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
5559 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
5560 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
5561
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5562
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 <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
5567 <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
5568 <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
5569
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5570 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5571 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
5572 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
5573
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5574
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 <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
5579 <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
5580 <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
5581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5582 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5583 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
5584 (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
5585 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
5586
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5587
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5588
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5589
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 <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
5592 <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
5593 <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
5594
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5595 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5596 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
5597 and returns this string;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5598 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
5599 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
5600
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5601
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5602 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5603 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
5604 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
5605
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5606
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 <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
5611 <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
5612 <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
5613
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5614 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5615 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
5616 and returns this number.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5617
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5618
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 <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
5623 <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
5624 <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
5625 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5626 const char *def,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5627 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
5628
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5629 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5630 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
5631 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
5632 (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
5633 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
5634 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
5635 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
5636
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5637
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5638 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5639 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
5640 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
5641 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
5642
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5643
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5644 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5645 This is a useful function for mapping strings to C&nbsp;enums.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5646 (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
5647 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
5648
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5649
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 <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
5654 <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
5655 <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
5656
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5657 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5658 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
5659 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
5660 <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
5661 (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
5662
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5663
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 <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
5668 <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
5669 <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
5670
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5671 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5672 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
5673 and returns this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5674
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5676 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5677 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
5678 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
5679
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5680
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5681
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5682
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5683
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5684 <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
5685 <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
5686 <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
5687
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5688 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5689 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
5690 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
5691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5692
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5694
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5695
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5696 <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
5697 <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
5698 <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
5699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5700 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5701 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
5702 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
5703 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
5704
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5705
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5706
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5709 <hr><h3><a name="luaL_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
5710 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5711 <pre>void luaL_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
5712
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5713 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5714 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
5715 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
5716 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
5717 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
5718 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
5719 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
5720
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5721
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5722
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 <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
5726 <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
5727 <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
5728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5729 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5730 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
5731 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
5732
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5733 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5734 (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
5735 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5736 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
5737 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
5738
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5739
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 <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
5744 <span class="apii">[-0, +?, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5745 <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
5746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5747 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5748 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
5749 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
5750
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5751 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5752 (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
5753 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5754 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
5755 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
5756
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5757
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 <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
5762 <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
5763 <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
5764
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5765 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5766 Raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5767 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
5768 plus any extra arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5769 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
5770 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
5771 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
5772 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
5773
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5775 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5776 This function never returns,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5777 but it is an idiom to use it in C&nbsp;functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5778 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
5779
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5780
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 <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
5785 <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
5786 <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
5787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5788 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5789 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
5790 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
5791 (<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
5792
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5793
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 <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
5798 <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
5799 <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
5800
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5801 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5802 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
5803 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
5804 (<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
5805
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5806
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 <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
5811 <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
5812 <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
5813
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5814 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5815 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
5816 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
5817 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
5818 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
5819 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
5820
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5821
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5822
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 <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
5826 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5827 <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
5828
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5829 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5830 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
5831 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
5832 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
5833 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
5834
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5835
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 <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
5840 <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
5841 <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
5842
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5843 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5844 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
5845 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
5846 is a table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5847 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
5848 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
5849 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
5850
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5851
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 <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
5856 <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
5857 <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
5858 const char *s,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5859 const char *p,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5860 const char *r);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5861
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5862 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5863 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
5864 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
5865 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
5866 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
5867
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5868
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5870
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5871
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5872 <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
5873 <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
5874 <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
5875
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5876 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5877 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
5878 as a number;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5879 it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">&sect;3.4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5880 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
5881 (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
5882
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5883
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5884
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5885
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 <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
5888 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5889 <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
5890 const char *buff,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5891 size_t sz,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5892 const char *name);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5893
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5894 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5895 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
5896
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5897
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 <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
5902 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5903 <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
5904 const char *buff,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5905 size_t sz,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5906 const char *name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5907 const char *mode);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5908
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5909 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5910 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
5911 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
5912 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
5913
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5914
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5915 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5916 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
5917 <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
5918 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
5919 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
5920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5921
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5922
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 <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
5926 <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
5927 <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
5928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5929 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5930 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
5931
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5932
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 <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
5937 <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
5938 <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
5939 const char *mode);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5940
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5941 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5942 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
5943 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
5944 named <code>filename</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5945 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
5946 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
5947 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
5948
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5949
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5950 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5951 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
5952
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5953
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5954 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5955 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
5956 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
5957 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
5958
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5959
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5960 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5961 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
5962 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
5963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5964
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 <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
5969 <span class="apii">[-0, +1, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5970 <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
5971
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5972 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5973 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
5974 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
5975 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
5976
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5978 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5979 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
5980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5981
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5982 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5983 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
5984 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
5985
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5986
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 <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
5991 <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
5992 <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
5993
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5994 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5995 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
5996 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
5997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5998
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5999 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6000 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
6001
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6002 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6003 (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
6004 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6005 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
6006 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
6007
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6008
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 <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
6013 <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
6014 <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
6015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6016 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6017 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
6018 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
6019 (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
6020 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
6021 (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
6022
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6023
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6024 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6025 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
6026 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
6027 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
6028
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6029
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 <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
6034 <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
6035 <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
6036
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6037 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6038 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
6039 returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6040 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6041 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
6042 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
6043 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
6044 and returns 1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6045 (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
6046
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6047
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6048 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6049 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
6050 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
6051
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6052
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6053
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 <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
6057 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6058 <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
6059
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6060 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6061 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
6062 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
6063 allocator based on the standard&nbsp;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
6064 and then sets a panic function (see <a href="#4.6">&sect;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
6065 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
6066 errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6067
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6068
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6069 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6070 Returns the new state,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6071 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
6072
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6073
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 <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
6078 <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
6079 <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
6080
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6081 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6082 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
6083
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6084
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 <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
6089 <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
6090 <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
6091 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6092 lua_Integer d);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6093
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6094 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6095 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
6096 (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
6097 returns this integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6098 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
6099 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6100 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6101
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6102
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 <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
6107 <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
6108 <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
6109 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6110 const char *d,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6111 size_t *l);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6113 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6114 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
6115 returns this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6116 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
6117 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6118 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6119
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6120
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6121 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6122 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
6123 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
6124
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6125
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 <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
6130 <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
6131 <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
6132
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6133 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6134 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
6135 returns this number.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6136 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
6137 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6138 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6139
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6140
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6141
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 <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
6145 <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
6146 <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
6147 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6148 const char *d);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6149
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6150 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6151 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
6152 returns this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6153 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
6154 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6155 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6156
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6157
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 <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
6162 <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
6163 <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
6164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6165 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6166 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
6167 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
6168
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6169
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 <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
6174 <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
6175 <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
6176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6177 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6178 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
6179 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
6180 (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
6181 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
6182 <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
6183 it to the buffer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6184
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6185
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 <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
6190 <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
6191 <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
6192
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6193 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6194 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
6195 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
6196
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6197
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 <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
6202 <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
6203 <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
6204
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6205 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6206 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
6207
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6208
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6212 <hr><h3><a name="luaL_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
6213 <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
6214 <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
6215
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6216 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6217 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
6218 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
6219 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
6220
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6221
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6222 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6223 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
6224 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
6225 <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
6226 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
6227 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
6228 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
6229
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6230
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6231 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6232 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
6233 <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
6234 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
6235 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
6236
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6237
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6238
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6239
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6241 <hr><h3><a name="luaL_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
6242 <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
6243 const char *name;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6244 lua_CFunction func;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6245 } luaL_Reg;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6247 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6248 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
6249 <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
6250 <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
6251 the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6252 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
6253 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
6254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6255
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 <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
6260 <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
6261 <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
6262 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
6263
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6264 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6265 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
6266 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
6267 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
6268 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
6269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6270
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6271 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6272 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
6273 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
6274
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6275
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6276 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6277 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
6278
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6279
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 <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
6284 <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
6285 <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
6286
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6287 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6288 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
6289 (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
6290 (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
6291
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6293 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6294 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
6295 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
6296 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
6297 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
6298 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
6299
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6300
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 <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
6305 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6306 <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
6307
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6308 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6309 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
6310 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
6311 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
6312
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6313
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 <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
6318 <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
6319 FILE *f;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6320 lua_CFunction closef;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6321 } luaL_Stream;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6322
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6323 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6324 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
6325 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
6326
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6327
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6328 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6329 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
6330 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
6331 (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
6332 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
6333 (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
6334
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6335
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6336 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6337 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
6338 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
6339 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
6340 (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
6341 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
6342 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
6343 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
6344 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
6345 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
6346 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
6347 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
6348 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
6349 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
6350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6351
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6352
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 <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
6356 <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
6357 <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
6358
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6359 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6360 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
6361 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
6362 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
6363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6364
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 <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
6369 <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
6370 <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
6371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6372 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6373 Converts any Lua value at the given index to a C&nbsp;string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6374 in a reasonable format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6375 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
6376 returned by the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6377 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
6378 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
6379
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6380
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6381 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6382 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
6383 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
6384 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
6385 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
6386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6388
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 <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
6392 <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
6393 <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
6394 int level);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6395
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6396 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6397 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
6398 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
6399 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
6400 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
6401 to start the traceback.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6402
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6403
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 <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
6408 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6409 <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
6410
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6411 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6412 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
6413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6414
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6415
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6416
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6417
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6418 <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
6419 <span class="apii">[-0, +0, &ndash;]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6420 <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
6421
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6422 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6423 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
6424 (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
6425 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
6426 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
6427 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
6428
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6429
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6430 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6431 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
6432 <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
6433
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6434
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 <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
6439 <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
6440 <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
6441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6442 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6443 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
6444 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
6445 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
6446
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6447 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6448 <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
6449 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6450 Level&nbsp;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
6451 level&nbsp;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
6452 etc.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6454
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6455 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6456 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
6457
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6458
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 <h1>6 &ndash; <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
6465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6466 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6467 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
6468 that are implemented directly through the C&nbsp;API.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6469 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
6470 (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
6471 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
6472 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
6473 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
6474 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
6475
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6476
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6477 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6478 All libraries are implemented through the official C&nbsp;API
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6479 and are provided as separate C&nbsp;modules.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6480 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
6481
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6482 <ul>
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 <li>basic library (<a href="#6.1">&sect;6.1</a>);</li>
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>coroutine library (<a href="#6.2">&sect;6.2</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>package library (<a href="#6.3">&sect;6.3</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>string manipulation (<a href="#6.4">&sect;6.4</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>basic UTF-8 support (<a href="#6.5">&sect;6.5</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>table manipulation (<a href="#6.6">&sect;6.6</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>mathematical functions (<a href="#6.7">&sect;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
6497
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6498 <li>input and output (<a href="#6.8">&sect;6.8</a>);</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>operating system facilities (<a href="#6.9">&sect;6.9</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>debug facilities (<a href="#6.10">&sect;6.10</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 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6505 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
6506 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
6507 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
6508
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6509
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6510 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6511 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
6512 the C&nbsp;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
6513 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
6514 Alternatively,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6515 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
6516 <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
6517 <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
6518 <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
6519 <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
6520 <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
6521 <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
6522 <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
6523 <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
6524 <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
6525 <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
6526 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
6527 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
6528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6529
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 <h2>6.1 &ndash; <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
6532
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6533 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6534 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
6535 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
6536 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
6537 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
6538
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6539
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6540 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6541 <hr><h3><a name="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
6542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6543
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6544 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6545 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
6546 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
6547 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
6548 In case of error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6549 <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
6550 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
6551
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6552
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6556 <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
6557
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6558
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6559 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6560 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
6561 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
6562
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6563 <ul>
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 <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
6566 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
6567 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
6568 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6569
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6570 <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
6571 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
6572 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
6573 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
6574 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6575
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6576 <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
6577 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
6578 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6580 <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
6581 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
6582 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
6583 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
6584 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
6585 (except for overflows).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6586 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6587
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6588 <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
6589 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
6590 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
6591 With a zero value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6592 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
6593 For non-zero values,
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 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
6595 (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
6596 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
6597 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6598
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6599 <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
6600 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
6601 the collector (see <a href="#2.5">&sect;2.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6602 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
6603 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6604
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6605 <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
6606 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
6607 the collector (see <a href="#2.5">&sect;2.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6608 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
6609 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6611 <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
6612 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
6613 (i.e., not stopped).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6614 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6615
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6616 </ul>
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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6621 <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
6622 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
6623 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6624 <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
6625 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
6626 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
6627 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
6628
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6629
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6633 <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
6634 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
6635 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
6636 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
6637
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6638
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6639 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6640 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
6641 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
6642 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
6643 With level&nbsp;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
6644 <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
6645 Level&nbsp;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
6646 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
6647 Passing a level&nbsp;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
6648 to the message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6649
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6650
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6654 <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
6655 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
6656 holds the global environment (see <a href="#2.2">&sect;2.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6657 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
6658 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
6659 nor vice versa.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6660
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6661
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6665 <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
6666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6667
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6668 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6669 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
6670 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6671 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
6672 returns the associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6673 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
6674
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6676
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6679 <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
6680
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6681
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6682 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6683 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
6684 so that the construction
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6686 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6687 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
6688 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6689 will iterate over the key&ndash;value pairs
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6690 (<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
6691 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
6692
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6694
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6695
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6696 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6697 <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
6698
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6700 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6701 Loads a chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6702
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6703
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6704 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6705 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
6706 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
6707 <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
6708 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
6709 with previous results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6710 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
6711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6712
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6713 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6714 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
6715 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
6716 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
6717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6718
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6719 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6720 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
6721 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
6722 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
6723 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
6724 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
6725 (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
6726 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
6727 the <code>_ENV</code> variable (see <a href="#2.2">&sect;2.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6728 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6729 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
6730 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
6731 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
6732 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
6733
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6734
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6735 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6736 <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
6737 and debug information (see <a href="#4.9">&sect;4.9</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6738 When absent,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6739 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
6740 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
6741
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6743 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6744 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
6745 (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
6746 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
6747 "<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
6748 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
6749 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
6750
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6752 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6753 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
6754 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
6755 the interpreter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6756
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6757
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6758
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6761 <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
6762
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6763
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6764 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6765 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
6766 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
6767 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
6768 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
6769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6770
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6774 <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
6775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6776
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6777 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6778 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
6779 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
6780 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
6781 <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
6782 and its associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6783 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
6784 <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
6785 and its associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6786 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
6787 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
6788 <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
6789 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
6790 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6791 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
6792
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6793
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6794 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6795 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
6796 <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
6797 (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
6798 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
6799
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6800
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6801 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6802 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
6803 during the traversal,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6804 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
6805 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
6806 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
6807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6808
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6812 <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
6813
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6814
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6815 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6816 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
6817 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
6818 results from the call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6819
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6820
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6821 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6822 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6823 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
6824 so that the construction
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6826 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6827 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
6828 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6829 will iterate over all key&ndash;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
6830
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6831
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6832 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6833 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
6834 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
6835
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6836
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6840 <hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, &middot;&middot;&middot;])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6841
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6842
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6843 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6844 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
6845 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
6846 This means that any error inside&nbsp;<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
6847 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
6848 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
6849 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
6850 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
6851 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
6852 after this first result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6853 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
6854
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6855
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6859 <hr><h3><a name="pdf-print"><code>print (&middot;&middot;&middot;)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6860 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
6861 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
6862 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
6863 <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
6864 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
6865 for instance for debugging.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6866 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
6867 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
6868
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6870
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6871
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6872 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6873 <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
6874 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
6875 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6876 Returns a boolean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6877
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6878
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6879
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6880
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6881 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6882 <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
6883 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
6884 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6885 <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
6886 <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
6887
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6888
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6892 <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
6893 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
6894 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
6895 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6896 Returns an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6897
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6899
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6902 <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
6903 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
6904 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6905 <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
6906 <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
6907 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
6908
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6909
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6910 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6911 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
6912
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6913
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6917 <hr><h3><a name="pdf-select"><code>select (index, &middot;&middot;&middot;)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6918
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6919
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6920 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6921 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
6922 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
6923 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
6924 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
6925 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
6926
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6927
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6928
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6931 <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
6932
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6933
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6934 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6935 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
6936 (You cannot change the metatable of other types from Lua, only from&nbsp;C.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6937 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
6938 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
6939 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
6940 raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6941
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6943 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6944 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
6945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6946
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6950 <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
6951
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6952
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6953 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6954 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
6955 <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
6956 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
6957 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
6958 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
6959 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
6960
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6961
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6962 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6963 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
6964 according to the lexical conventions of Lua (see <a href="#3.1">&sect;3.1</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6965 (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
6966
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6968 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6969 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
6970 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
6971 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
6972 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
6973 In bases above&nbsp;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
6974 represents&nbsp;10, '<code>B</code>' represents&nbsp;11, and so forth,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6975 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
6976 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
6977 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
6978
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6979
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6983 <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
6984 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
6985 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
6986 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
6987 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
6988 (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
6989 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
6990
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6992 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6993 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
6994 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
6995 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
6996 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
6997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
6998
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7002 <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
7003 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
7004 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
7005 "<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
7006 "<code>number</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7007 "<code>string</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7008 "<code>boolean</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7009 "<code>table</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7010 "<code>function</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7011 "<code>thread</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7012 and "<code>userdata</code>".
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7013
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7017 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7018 <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
7019 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
7020 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
7021 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
7022
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7023
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7027 <hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, &middot;&middot;&middot;])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7028
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7029
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7030 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7031 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
7032 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
7033
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7034
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7036
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 <h2>6.2 &ndash; <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
7041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7042 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7043 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
7044 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
7045 See <a href="#2.6">&sect;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
7046
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7047
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7048 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7049 <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
7050
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7051
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7052 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7053 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
7054 <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
7055 Returns this new coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7056 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
7057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7058
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7059
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7062 <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
7063
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7064
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7065 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7066 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
7067
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7068
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7069 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7070 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
7071 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
7072
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7073
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7075
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7076 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7077 <hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, &middot;&middot;&middot;])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7078
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7079
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7080 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7081 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
7082 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
7083 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
7084 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
7085 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
7086 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
7087 <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
7088 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
7089 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
7090
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7091
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7092 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7093 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
7094 <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
7095 (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
7096 (when the coroutine terminates).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7097 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
7098 <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
7099
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7100
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7104 <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
7105
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7106
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7107 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7108 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
7109 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
7110
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7111
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7113
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7114 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7115 <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
7116
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7117
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7118 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7119 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
7120 <code>"running"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7121 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
7122 <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
7123 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
7124 <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
7125 (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
7126 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
7127 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
7128
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7129
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7133 <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
7134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7135
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7136 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7137 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
7138 <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
7139 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
7140 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
7141 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
7142 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
7143 except the first boolean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7144 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
7145
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7146
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7150 <hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (&middot;&middot;&middot;)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7151
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7152
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7153 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7154 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
7155 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
7156
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7157
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 <h2>6.3 &ndash; <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
7164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7165 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7166 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
7167 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
7168 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
7169 <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
7170 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
7171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7172
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7173 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7174 <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
7175
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7177 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7178 Loads the given module.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7179 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
7180 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
7181 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
7182 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
7183 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
7184
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7185
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7186 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7187 To find a loader,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7188 <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
7189 By changing this sequence,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7190 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
7191 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
7192 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
7193
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7194
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7195 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7196 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
7197 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
7198 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
7199 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
7200 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
7201 If that also fails, it searches for a C&nbsp;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.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
7203 If that also fails,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7204 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
7205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7206
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7207 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7208 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
7209 <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
7210 <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
7211 (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
7212 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
7213 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
7214 <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
7215 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
7216 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
7217 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
7218 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
7219 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
7220
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7221
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7222 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7223 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
7224 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
7225 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
7226
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7227
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7228
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7229
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7230 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7231 <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
7232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7233
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7234 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7235 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
7236 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
7237
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7238 <ul>
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 <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
7241 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
7242
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7243 <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
7244 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
7245
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7246 <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
7247 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
7248 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
7249
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7250 <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
7251 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
7252 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
7253
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7254 <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
7255 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
7256 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
7257
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7258 </ul>
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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7263 <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
7264
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7265
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7266 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7267 The path used by <a href="#pdf-require"><code>require</code></a> to search for a C&nbsp;loader.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7270 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7271 Lua initializes the C&nbsp;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
7272 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
7273 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
7274 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
7275 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
7276
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7277
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7281 <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
7282
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7284 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7285 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
7286 modules are already loaded.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7287 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
7288 <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
7289 <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
7290
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7291
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7292 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7293 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
7294 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
7295 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
7296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7297
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7301 <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
7302
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7303
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7304 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7305 Dynamically links the host program with the C&nbsp;library <code>libname</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7306
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7307
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7308 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7309 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
7310 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
7311 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
7312 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
7313 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7314 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
7315 and returns this function as a C&nbsp;function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7316 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
7317 (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
7318
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7319
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7320 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7321 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
7322 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
7323 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
7324 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
7325 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
7326 <code>libname</code> must be the complete file name of the C&nbsp;library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7327 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
7328 <code>funcname</code> must be the exact name exported by the C&nbsp;library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7329 (which may depend on the C&nbsp;compiler and linker used).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7330
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7332 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7333 This function is not supported by Standard&nbsp;C.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7334 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
7335 (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
7336 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
7337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7341 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7342 <hr><h3><a name="pdf-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
7343
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7344
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7345 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7346 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
7347
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7348
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7349 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7350 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
7351 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
7352 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
7353 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
7354 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
7355 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
7356 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
7357
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7358
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7362 <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
7363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7364
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7365 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7366 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
7367 (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
7368
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7369
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7370 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7371 This 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
7372 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
7373 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
7374
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7376
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7377
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7378 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7379 <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
7380
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7382 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7383 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
7384
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7385
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7386 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7387 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
7388 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
7389 <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
7390 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
7391 sole parameter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7392 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
7393 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
7394 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
7395 (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
7396
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7397
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7398 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7399 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
7400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7401
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7402 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7403 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
7404 <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
7405
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7406
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7407 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7408 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
7409 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
7410 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
7411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7413 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7414 The third searcher looks for a loader as a C&nbsp;library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7415 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
7416 Again,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7417 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
7418 For instance,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7419 if the C&nbsp;path is the string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7420
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7421 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7422 "./?.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
7423 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7424 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
7425 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
7426 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
7427 Once it finds a C&nbsp;library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7428 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
7429 application with the library.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7430 Then it tries to find a C&nbsp;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
7431 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
7432 The name of this C&nbsp;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
7433 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
7434 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
7435 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
7436 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
7437 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
7438 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
7439
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7440
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7441 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7442 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
7443 It searches the C&nbsp;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
7444 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
7445 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
7446 it will search for a C&nbsp;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
7447 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
7448 the submodule;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7449 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
7450 With this facility, a package can pack several C&nbsp;submodules
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7451 into one single library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7452 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
7453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7454
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7455 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7456 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
7457 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
7458 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
7459 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
7460
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7461
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7465 <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
7466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7467
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7468 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7469 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
7470
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7471
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7472 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7473 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
7474 <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
7475 For each template,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7476 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
7477 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
7478 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
7479 (a dot, by default)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7480 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
7481 (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
7482 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
7483
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7484
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7485 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7486 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
7487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7488 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7489 "./?.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
7490 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7491 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
7492 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
7493 <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
7494 <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
7495
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7496
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7497 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7498 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
7499 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
7500 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
7501 (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
7502
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7503
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 <h2>6.4 &ndash; <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
7510
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7511 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7512 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
7513 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
7514 When indexing a string in Lua, the first character is at position&nbsp;1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7515 (not at&nbsp;0, as in C).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7516 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
7517 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
7518 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
7519
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7520
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7521 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7522 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
7523 <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
7524 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
7525 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
7526 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
7527 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
7528 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
7529
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7530
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7531 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7532 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
7533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7534
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7535 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7536 <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
7537 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
7538 <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
7539 The default value for <code>i</code> is&nbsp;1;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7540 the default value for <code>j</code> is&nbsp;<code>i</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7541 These indices are corrected
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7542 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
7543
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7544
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7545 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7546 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
7547
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7548
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7552 <hr><h3><a name="pdf-string.char"><code>string.char (&middot;&middot;&middot;)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7553 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
7554 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
7555 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
7556 to its corresponding argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7557
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7558
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7559 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7560 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
7561
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7562
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7566 <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
7567
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7568
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7569 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7570 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
7571 (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
7572 of the given function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7573 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
7574 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
7575 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
7576 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
7577 about the function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7578 (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
7579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7581 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7582 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
7583 When (re)loaded,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7584 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
7585 (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
7586 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
7587 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
7588
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7589
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7590
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7593 <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
7594
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7595
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7596 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7597 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
7598 <code>pattern</code> (see <a href="#6.4.1">&sect;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
7599 If it finds a match, then <code>find</code> returns the indices of&nbsp;<code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7600 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
7601 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
7602 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
7603 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
7604 its default value is&nbsp;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
7605 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
7606 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
7607 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
7608 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
7609 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
7610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7611
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7612 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7613 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
7614 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
7615 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
7616 after the two indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7617
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7618
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7619
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7620
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7621 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7622 <hr><h3><a name="pdf-string.format"><code>string.format (formatstring, &middot;&middot;&middot;)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7624
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7625 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7626 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
7627 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
7628 The format string follows the same rules as the ISO&nbsp;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
7629 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
7630 <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
7631 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
7632 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
7633 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
7634 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
7635 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
7636 For instance, the call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7637
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7638 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7639 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
7640 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7641 may produce the string:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7642
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7643 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7644 "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
7645 new line"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7646 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7647
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7648 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7649 Options
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7650 <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
7651 <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
7652 <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
7653 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
7654 <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
7655 expect an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7656 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
7657 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
7658 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
7659 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
7660
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7661
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7665 <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
7666 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
7667 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
7668 returns the next captures from <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7669 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
7670 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
7671 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
7672
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7673
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7674 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7675 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
7676 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
7677 printing one per line:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7678
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7679 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7680 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
7681 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
7682 print(w)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7683 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7684 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7685 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
7686 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
7687
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7688 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7689 t = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7690 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
7691 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
7692 t[k] = v
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7693 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7694 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7695
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7696 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7697 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
7698 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
7699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7700
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7701
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7704 <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
7705 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
7706 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
7707 occurrences of the <code>pattern</code> (see <a href="#6.4.1">&sect;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
7708 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
7709 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
7710 <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
7711 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
7712 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
7713
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7714
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7715 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7716 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
7717 The character&nbsp;<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
7718 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
7719 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
7720 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
7721 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
7722 The sequence <code>%%</code> stands for a single&nbsp;<code>%</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7723
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7724
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7725 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7726 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
7727 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
7728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7730 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7731 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
7732 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
7733 in order.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7734
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7736 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7737 In any case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7738 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
7739 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
7740
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7741
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7742 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7743 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
7744 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
7745 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
7746 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
7747 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
7748 (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
7749
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7750
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7751 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7752 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7753
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7754 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7755 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
7756 --&gt; 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
7757
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7758 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
7759 --&gt; x="hello hello world"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7761 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
7762 --&gt; 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
7763
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7764 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
7765 --&gt; 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
7766
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7767 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
7768 return load(s)()
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7769 end)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7770 --&gt; x="4+5 = 9"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7771
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7772 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
7773 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
7774 --&gt; 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
7775 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7776
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7777
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7780 <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
7781 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
7782 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
7783 Embedded zeros are counted,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7784 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
7785
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7786
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7790 <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
7791 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
7792 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
7793 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
7794 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
7795
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7796
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7800 <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
7801 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
7802 <code>pattern</code> (see <a href="#6.4.1">&sect;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
7803 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
7804 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
7805 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
7806 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
7807 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
7808 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
7809 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
7810 its default value is&nbsp;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
7811
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7812
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7816 <hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, &middot;&middot;&middot;)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7817
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7818
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7819 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7820 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
7821 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
7822 according to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;6.4.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7825
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7828 <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
7829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7830
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7831 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7832 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
7833 with the given format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7834 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
7835 '<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">&sect;6.4.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7836
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7837
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7841 <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
7842 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
7843 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
7844 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
7845 (that is, no separator).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7846 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
7847
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7848
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7849
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7850
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7851 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7852 <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
7853 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
7854
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7855
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7859 <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
7860 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
7861 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
7862 <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
7863 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
7864 (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
7865 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7866 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
7867 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
7868 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
7869 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
7870
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7871
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7872 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7873 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
7874 <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
7875 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
7876 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
7877 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
7878 If, after these corrections,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7879 <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
7880 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
7881
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7882
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7883
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7884
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7885 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7886 <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
7887
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7888
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7889 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7890 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
7891 according to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;6.4.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7892 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
7893 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
7894 After the read values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7895 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
7896
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7897
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7899
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7900 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7901 <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
7902 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
7903 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
7904 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
7905 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
7906
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7907
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7908
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7909
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 <h3>6.4.1 &ndash; <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
7912
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7913 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7914 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
7915 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
7916 <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
7917 <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
7918 <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
7919 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
7920 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
7921 (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
7922
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7923
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 <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
7926 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
7927 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
7928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7929 <ul>
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 <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
7932 (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
7933 <code>^$()%.[]*+-?</code>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7934 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
7935 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7936
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7937 <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
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>%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
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>%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
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>%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
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>%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
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>%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
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>%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
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>%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
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>%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
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>%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
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>%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
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>%<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
7960 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
7961 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
7962 Any non-alphanumeric character
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7963 (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
7964 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
7965 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
7966 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7968 <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
7969 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
7970 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
7971 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
7972 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
7973 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
7974 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
7975 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
7976 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
7977 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
7978 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
7979 <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
7980 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
7981 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
7982
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7983
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7984 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7985 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
7986 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
7987 have no meaning.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7988 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7989
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7990 <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
7991 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
7992 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
7993 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7994
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7995 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
7996 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
7997 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
7998 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
7999
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8001 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8002 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
8003 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
8004 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
8005
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8006
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 <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
8011 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
8012
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8013 <ul>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8016 a single character class,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8017 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
8018 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8019
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 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
8022 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
8023 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
8024 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8025
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 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
8028 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
8029 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
8030 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8031
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 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
8034 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
8035 Unlike '<code>*</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8036 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
8037 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8038
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 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
8041 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
8042 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
8043 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8044
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 <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
8047 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
8048 (see below);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8049 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8050
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 <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
8053 such item matches strings that start with&nbsp;<em>x</em>, end with&nbsp;<em>y</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8054 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
8055 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
8056 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
8057 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
8058 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
8059 balanced parentheses.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8060 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8061
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 <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
8064 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
8065 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
8066 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
8067 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
8068 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
8069 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
8070 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8071
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8072 </ul>
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
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 <h4>Pattern:</h4><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8078 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
8079 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
8080 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
8081 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
8082 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
8083 At other positions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8084 '<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
8085
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8086
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 <h4>Captures:</h4><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8091 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
8092 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
8093 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
8094 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
8095 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
8096 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
8097 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
8098 stored as the first capture (and therefore has number&nbsp;1);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8099 the character matching "<code>.</code>" is captured with number&nbsp;2,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8100 and the part matching "<code>%s*</code>" has number&nbsp;3.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8101
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8102
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8103 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8104 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
8105 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
8106 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
8107 string <code>"flaaap"</code>, there will be two captures: 3&nbsp;and&nbsp;5.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8109
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 <h3>6.4.2 &ndash; <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
8116
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8117 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8118 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
8119 <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
8120 is a format string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8121 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
8122
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8123
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8124 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8125 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
8126 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
8127
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8128 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8129 <li><b><code>&lt;</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
8130 <li><b><code>&gt;</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
8131 <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
8132 <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
8133 (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
8134 <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
8135 <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
8136 <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
8137 <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
8138 <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
8139 <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
8140 <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
8141 <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
8142 <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
8143 <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
8144 (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
8145 <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
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>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
8148 <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
8149 <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
8150 <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
8151 <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
8152 <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
8153 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
8154 (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
8155 <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
8156 <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
8157 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
8158 (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
8159 <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
8160 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8161 (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
8162 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
8163 (options "<code>xX &lt;=&gt;!</code>"),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8164 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
8165 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
8166
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8167
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8168 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8169 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
8170 <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
8171 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
8172 <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
8173 <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
8174
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8175
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8176 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8177 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
8178 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8179 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
8180 and native endianness.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8181
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8182
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8183 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8184 Alignment works as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8185 For each option,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8186 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
8187 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
8188 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
8189 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
8190 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
8191 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
8192
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8193
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8194 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8195 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
8196 (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
8197
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8198
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 <h2>6.5 &ndash; <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
8205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8206 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8207 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
8208 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
8209 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
8210 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
8211 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
8212 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
8213
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8214
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8215 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8216 Unless stated otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8217 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
8218 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
8219 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
8220 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
8221 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
8222
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8223
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8224 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8225 <hr><h3><a name="pdf-utf8.char"><code>utf8.char (&middot;&middot;&middot;)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8226 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
8227 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
8228 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
8229
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8230
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8234 <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
8235 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
8236 (see <a href="#6.4.1">&sect;6.4.1</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8237 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
8238 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
8239
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8240
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8244 <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
8245
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8247 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8248 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
8249
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8250 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8251 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
8252 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8253 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
8254 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
8255 of each character.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8256 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
8257
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8258
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8262 <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
8263 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
8264 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
8265 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
8266 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
8267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8269
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8272 <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
8273 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
8274 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
8275 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
8276 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
8277 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
8278
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8279
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8283 <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
8284 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
8285 <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
8286 (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
8287 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
8288 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
8289 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
8290 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
8291 <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
8292 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
8293 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
8294 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
8295
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8297 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8298 As a special case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8299 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
8300 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
8301
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8302
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8303 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8304 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
8305
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8306
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 <h2>6.6 &ndash; <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
8313
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8314 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8315 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
8316 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
8317
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8318
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8319 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8320 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
8321 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
8322 or have a <code>__len</code> metamethod (see <a href="#3.4.7">&sect;3.4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8323 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
8324 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
8325
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8326
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8327 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8328 <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
8329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8330
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8331 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8332 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
8333 returns the string <code>list[i]..sep..list[i+1] &middot;&middot;&middot; sep..list[j]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8334 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
8335 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
8336 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
8337 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
8338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8341
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8342 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8343 <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
8344
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8345
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8346 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8347 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
8348 shifting up the elements
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8349 <code>list[pos], list[pos+1], &middot;&middot;&middot;, list[#list]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8350 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
8351 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
8352 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
8353
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8354
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8355
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8358 <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
8359
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8361 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8362 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
8363 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
8364 multiple assignment:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8365 <code>a2[t],&middot;&middot;&middot; = a1[f],&middot;&middot;&middot;,a1[e]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8366 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
8367 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
8368 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
8369
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8370
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8374 <hr><h3><a name="pdf-table.pack"><code>table.pack (&middot;&middot;&middot;)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8376
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8377 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8378 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
8379 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
8380 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
8381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8382
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8386 <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
8387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8388
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8389 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8390 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
8391 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
8392 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
8393 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
8394 <code>list[pos+1], list[pos+2], &middot;&middot;&middot;, list[#list]</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8395 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
8396 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
8397 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
8398 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
8399
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8401 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8402 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
8403 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
8404 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
8405
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8406
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8410 <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
8411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8413 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8414 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
8415 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
8416 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
8417 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
8418 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
8419 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
8420 (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
8421 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
8422 then the standard Lua operator <code>&lt;</code> is used instead.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8423
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8424
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8425 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8426 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
8427 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
8428 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
8429
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8430
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8434 <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
8435
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8436
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8437 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8438 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
8439 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
8440
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8441 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8442 return list[i], list[i+1], &middot;&middot;&middot;, list[j]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8443 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8444 By default, <code>i</code> is&nbsp;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
8445
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8446
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 <h2>6.7 &ndash; <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
8453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8454 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8455 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
8456 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
8457 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
8458 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
8459 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
8460 Rounding functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8461 (<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
8462 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
8463 or a float otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8466 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8467 <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
8468
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8469
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8470 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8471 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
8472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8473
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8477 <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
8478
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8479
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8480 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8481 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
8482
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8483
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8487 <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
8488
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8490 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8491 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
8492
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8493
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8497 <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
8498
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8500 <p>
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 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
8503 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
8504 quadrant of the result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8505 (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
8506
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8507
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8508 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8509 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
8510 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
8511 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
8512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8514
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8515
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8516 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8517 <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
8518
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8519
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8520 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8521 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
8522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8523
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8527 <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
8528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8529
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8530 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8531 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
8532
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8534
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8537 <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
8538
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8539
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8540 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8541 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
8542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8543
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8544
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8546 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8547 <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
8548
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8550 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8551 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
8552 (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
8553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8554
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8555
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8558 <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
8559
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8560
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8561 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8562 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
8563
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8564
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8568 <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
8569
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8570
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8571 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8572 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
8573 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
8574
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8575
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8579 <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
8580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8582 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8583 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
8584 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
8585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8586
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8587
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8590 <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
8591
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8592
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8593 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8594 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
8595 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
8596 (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
8597
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8598
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8599
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8600
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8601 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8602 <hr><h3><a name="pdf-math.max"><code>math.max (x, &middot;&middot;&middot;)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8603
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8604
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8605 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8606 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
8607 according to the Lua operator <code>&lt;</code>. (integer/float)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8608
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8611
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8612 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8613 <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
8614 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
8615
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8616
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8620 <hr><h3><a name="pdf-math.min"><code>math.min (x, &middot;&middot;&middot;)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8621
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8622
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8623 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8624 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
8625 according to the Lua operator <code>&lt;</code>. (integer/float)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8626
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8627
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8631 <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
8632 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
8633
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8634
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8635
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8636
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8637 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8638 <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
8639
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8640
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8641 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8642 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
8643 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
8644
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8645
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8646
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8647
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8648 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8649 <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
8650
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8651
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8652 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8653 The value of <em>&pi;</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8654
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8655
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8659 <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
8660
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8661
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8662 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8663 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
8664
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8667
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8668 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8669 <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
8670
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8671
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8672 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8673 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8674 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
8675 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
8676 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
8677 <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
8678 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
8679 (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
8680 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
8681
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8682
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8683 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8684 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
8685 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
8686 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
8687
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8688
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8692 <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
8693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8694
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8695 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8696 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
8697 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
8698 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
8699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8700
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8701
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8704 <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
8705
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8706
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8707 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8708 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
8709
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8710
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8712
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8713 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8714 <hr><h3><a name="pdf-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
8715
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8716
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8717 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8718 Returns 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
8719 (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
8720
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8721
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8722
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8723
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8724 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8725 <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
8726
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8727
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8728 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8729 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
8730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8731
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8735 <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
8736
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8737
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8738 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8739 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
8740 returns that integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8741 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
8742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8743
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8747 <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
8748
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8749
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8750 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8751 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
8752 "<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
8753 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
8754
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8755
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8759 <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
8760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8762 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8763 Returns a boolean,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8764 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
8765 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
8766
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8767
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 <h2>6.8 &ndash; <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
8774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8775 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8776 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
8777 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
8778 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
8779 default output file,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8780 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
8781 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
8782
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8783
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8784 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8785 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
8786 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
8787 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
8788 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
8789 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
8790
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8791
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8792 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8793 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
8794 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
8795 <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
8796 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
8797
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8798
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8799 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8800 Unless otherwise stated,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8801 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
8802 (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
8803 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
8804 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
8805 On non-POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8806 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
8807 in case of errors
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8808 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
8809 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
8810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8811
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8812 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8813 <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
8814
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8816 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8817 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
8818 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
8819
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8820
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8824 <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
8825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8826
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8827 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8828 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
8829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8830
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8834 <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
8835
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8836
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8837 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8838 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
8839 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
8840 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
8841 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
8842 When called without parameters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8843 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
8844
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8845
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8846 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8847 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
8848 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
8849
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8850
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8854 <hr><h3><a name="pdf-io.lines"><code>io.lines ([filename &middot;&middot;&middot;])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8855
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8856
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8857 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8858 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
8859 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
8860 works like <code>file:lines(&middot;&middot;&middot;)</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
8861 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
8862 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
8863
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8864
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8865 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8866 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
8867 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
8868 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
8869 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
8870
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8871
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8872 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8873 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
8874 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
8875
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8876
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8880 <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
8881
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8882
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8883 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8884 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
8885 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
8886 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
8887 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
8888
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8889
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8890 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8891 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
8892
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8893 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8894 <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
8895 <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
8896 <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
8897 <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
8898 <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
8899 <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
8900 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
8901 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8902 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
8903 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
8904
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8905
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8906
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8907
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8908 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8909 <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
8910
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8911
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8912 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8913 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
8914
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8915
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8916
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8917
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8918 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8919 <hr><h3><a name="pdf-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
8920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8921
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8922 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8923 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
8924 on all platforms.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8925
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8926
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8927 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8928 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
8929 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
8930 (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
8931 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
8932 (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
8933
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8934
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8938 <hr><h3><a name="pdf-io.read"><code>io.read (&middot;&middot;&middot;)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8939
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8940
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8941 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8942 Equivalent to <code>io.input():read(&middot;&middot;&middot;)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8943
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8944
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8945
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8948 <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
8949
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8951 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8952 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
8953 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
8954 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
8955
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8956
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8957
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8958
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8959 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8960 <hr><h3><a name="pdf-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
8961
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8962
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8963 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8964 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
8965 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
8966 <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
8967 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
8968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8970
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8973 <hr><h3><a name="pdf-io.write"><code>io.write (&middot;&middot;&middot;)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8974
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8975
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8976 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8977 Equivalent to <code>io.output():write(&middot;&middot;&middot;)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8978
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8979
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8981
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8982 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8983 <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
8984
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8985
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8986 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8987 Closes <code>file</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8988 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
8989 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
8990 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
8991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8993 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8994 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
8995 <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
8996 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
8997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
8998
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9002 <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
9003
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9004
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9005 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9006 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
9007
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9008
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9012 <hr><h3><a name="pdf-file:lines"><code>file:lines (&middot;&middot;&middot;)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9013
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9015 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9016 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
9017 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
9018 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
9019 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
9020 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
9021 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
9022
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9023 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9024 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
9025 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9026 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
9027 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
9028 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
9029 when the loop ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9030
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9032 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9033 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
9034 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
9035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9036
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9040 <hr><h3><a name="pdf-file:read"><code>file:read (&middot;&middot;&middot;)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9042
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9043 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9044 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
9045 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
9046 For each format,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9047 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
9048 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
9049 (In this latter case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9050 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
9051 When called without formats,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9052 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
9053 (see below).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9055
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9056 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9057 The available formats are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9058
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9059 <ul>
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 <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
9062 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
9063 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
9064 (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
9065 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
9066 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
9067 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
9068 (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
9069 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
9070 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9071
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9072 <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
9073 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
9074 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9075
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9076 <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
9077 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
9078 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
9079 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9080
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9081 <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
9082 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
9083 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
9084 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
9085 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9086
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9087 <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
9088 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
9089 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
9090 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9091
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9092 <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
9093 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
9094 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
9095 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
9096 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
9097 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
9098 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9099
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9100 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9101 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
9102
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9103
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9107 <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
9108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9110 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9111 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
9112 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
9113 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
9114 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
9115
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9116 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9117 <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
9118 <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
9119 <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
9120 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9121 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
9122 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
9123 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
9124 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
9125
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9126
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9127 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9128 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
9129 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
9130 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
9131 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
9132 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
9133 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
9134 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
9135 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
9136
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9137
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9138
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9139
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9140 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9141 <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
9142
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9143
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9144 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9145 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
9146 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
9147
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9148 <ul>
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 <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
9151 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
9152 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9153
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9154 <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
9155 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
9156 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
9157 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
9158 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9159
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9160 <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
9161 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
9162 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
9163 (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
9164 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9166 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9167 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
9168 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
9169 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
9170
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9172
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9173
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9174 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9175 <hr><h3><a name="pdf-file:write"><code>file:write (&middot;&middot;&middot;)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9178 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9179 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
9180 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
9181
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9182
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9183 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9184 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
9185 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
9186
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9187
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 <h2>6.9 &ndash; <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
9194
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9195 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9196 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
9197
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9198
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9199 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9200 <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
9201
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9202
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9203 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9204 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
9205 used by the program.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9206
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9207
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9211 <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
9212
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9213
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9214 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9215 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
9216 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
9217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9218
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9219 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9220 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
9221 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
9222 (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
9223 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
9224
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9225
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9226 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9227 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
9228 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
9229 After this optional character,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9230 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
9231 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
9232 <code>year</code> (four digits), <code>month</code> (1&ndash;12), <code>day</code> (1&ndash;31),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9233 <code>hour</code> (0&ndash;23), <code>min</code> (0&ndash;59), <code>sec</code> (0&ndash;61),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9234 <code>wday</code> (weekday, Sunday is&nbsp;1),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9235 <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
9236 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
9237 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
9238 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
9239
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9241 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9242 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
9243 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
9244 formatted according to the same rules as the ISO&nbsp;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
9245
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9247 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9248 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9249 <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
9250 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
9251 (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
9252
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9253
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9254 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9255 On non-POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9256 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
9257 because of its reliance on C&nbsp;function <code>gmtime</code> and C&nbsp;function <code>localtime</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9259
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9261
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9262 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9263 <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
9264
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9265
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9266 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9267 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
9268 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
9269 (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
9270 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
9271 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
9272
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9273
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9274
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9275
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9276 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9277 <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
9278
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9279
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9280 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9281 This function is equivalent to the ISO&nbsp;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
9282 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
9283 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
9284 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
9285 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
9286 After this first result
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9287 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
9288 as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9289
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9290 <ul>
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 <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
9293 the command terminated normally;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9294 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
9295 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9297 <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
9298 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
9299 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
9300 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9301
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9302 </ul>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9305 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
9306 <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
9307
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9310
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9311 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9312 <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
9313
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9314
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9315 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9316 Calls the ISO&nbsp;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
9317 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
9318 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
9319 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
9320 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
9321 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
9322 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
9323 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
9324
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9325
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9326 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9327 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
9328 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
9329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9330
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9332
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9333 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9334 <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
9335
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9336
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9337 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9338 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
9339 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
9340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9341
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9345 <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
9346
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9347
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9348 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9349 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
9350 with the given name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9351 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
9352 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
9353
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9354
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9355
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9358 <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
9359
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9361 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9362 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
9363 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
9364 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
9365
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9366
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9370 <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
9371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9372
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9373 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9374 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
9375 <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
9376 <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
9377 <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
9378 <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
9379 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
9380 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
9381 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
9382
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9383
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9384 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9385 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
9386 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
9387 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
9388 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
9389
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9391 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9392 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
9393 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
9394 for the given category.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9395
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9396
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9397 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9398 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
9399 because of its reliance on C&nbsp;function <code>setlocale</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9401
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9405 <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
9406
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9407
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9408 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9409 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
9410 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
9411 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
9412 and may have fields
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9413 <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
9414 <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
9415 <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
9416 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
9417 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
9418
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9419
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9420 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9421 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
9422 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
9423 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
9424 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
9425 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
9426 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
9427 <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
9428
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9429
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9433 <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
9434
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9435
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9436 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9437 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
9438 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
9439 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
9440 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
9441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9443 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9444 On POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9445 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
9446 to avoid security risks.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9447 (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
9448 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
9449 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
9450 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
9451
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9453 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9454 When possible,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9455 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
9456 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
9457
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9458
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 <h2>6.10 &ndash; <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
9465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9466 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9467 This library provides
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9468 the functionality of the debug interface (<a href="#4.9">&sect;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
9469 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
9470 Several of its functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9471 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
9472 (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
9473 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
9474 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
9475 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
9476 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
9477 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
9478
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9479
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9480 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9481 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
9482 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
9483 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
9484 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
9485 thread to operate over.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9486 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
9487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9488
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9489 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9490 <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
9491
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9492
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9493 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9494 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
9495 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
9496 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
9497 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
9498 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
9499 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
9500 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
9501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9502
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9503 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9504 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
9505 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
9506
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9507
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9511 <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
9512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9514 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9515 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
9516 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
9517 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
9518 (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
9519
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9520
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9523 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9524 <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
9525
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9526
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9527 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9528 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
9529 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
9530 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
9531 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
9532 of the given thread:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9533 level&nbsp;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
9534 level&nbsp;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
9535 (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
9536 and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9537 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
9538 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
9539
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9540
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9541 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9542 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
9543 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
9544 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
9545 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
9546 If present,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9547 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
9548 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
9549 If present,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9550 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
9551 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
9552 valid lines.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9554
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9555 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9556 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
9557 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
9558 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
9559 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
9560 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
9561 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
9562
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9563
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9565
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9566 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9567 <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
9568
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9569
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9570 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9571 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
9572 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
9573 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
9574 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
9575
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9576
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9577 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9578 The first parameter or local variable has index&nbsp;1, and so on,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9579 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
9580 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
9581 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
9582 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
9583 -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
9584 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
9585 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
9586 (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
9587
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9588
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9589 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9590 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
9591 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
9592 (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
9593 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
9594
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9595
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9596 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9597 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
9598 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
9599
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9600
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9601
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9602
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9603 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9604 <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
9605
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9606
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9607 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9608 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
9609 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
9610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9611
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9615 <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
9616
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9617
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9618 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9619 Returns the registry table (see <a href="#4.5">&sect;4.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9620
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9621
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9625 <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
9626
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9627
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9628 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9629 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
9630 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
9631 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
9632
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9633
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9634 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9635 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
9636 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
9637 (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
9638
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9639
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9643 <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
9644
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9645
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9646 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9647 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
9648 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
9649 returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9650
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9651
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9655 <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
9656
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9657
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9658 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9659 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
9660 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
9661 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
9662 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
9663 with the given meaning:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9664
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9665 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9666 <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
9667 <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
9668 <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
9669 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9670 Moreover,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9671 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
9672 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
9673
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9674
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9675 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9676 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9677 <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
9678
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9679
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9680 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9681 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
9682 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
9683 <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
9684 <code>"return"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9685 <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
9686 For line events,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9687 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
9688 Inside a hook,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9689 you can call <code>getinfo</code> with level&nbsp;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
9690 the running function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9691 (level&nbsp;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
9692 and level&nbsp;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
9693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9694
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9695
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9696
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9697 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9698 <hr><h3><a name="pdf-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
9699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9700
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9701 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9702 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
9703 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
9704 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
9705 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
9706 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
9707 (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
9708 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
9709
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9710
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9711 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9712 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
9713 variable indices and names.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9714
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9715
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9719 <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
9720
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9721
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9722 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9723 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
9724 (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
9725 Returns <code>value</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9726
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9727
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9731 <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
9732
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9733
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9734 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9735 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
9736 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
9737 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
9738 with the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9739 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
9740
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9741
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9743
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9744 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9745 <hr><h3><a name="pdf-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
9746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9747
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9748 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9749 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
9750 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
9751 <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
9752
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9753
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9754 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9755 Returns <code>udata</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9756
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9757
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9758
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9759
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9760 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9761 <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
9762
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9763
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9764 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9765 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
9766 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
9767 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9768 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
9769 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
9770 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
9771 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
9772 to start the traceback
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9773 (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
9774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9776
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9779 <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
9780
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9781
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9782 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9783 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
9784 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
9785 from the given function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9786
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9788 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9789 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
9790 closures share upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9791 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
9792 (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
9793 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
9794
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9795
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9799 <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
9800
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9801
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9802 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9803 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
9804 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
9805
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9806
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 <h1>7 &ndash; <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
9813
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9814 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9815 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
9816 to be embedded in a host C&nbsp;program,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9817 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
9818 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
9819 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
9820 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
9821 The standalone interpreter includes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9822 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
9823 Its usage is:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9825 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9826 lua [options] [script [args]]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9827 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9828 The options are:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9830 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9831 <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
9832 <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
9833 <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
9834 <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
9835 <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
9836 <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
9837 <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
9838 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9839 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
9840 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9841 <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
9842 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
9843 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
9844
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9845
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9846 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9847 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
9848 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
9849 (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
9850 before running any argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9851 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
9852 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
9853 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
9854
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9855
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9856 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9857 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
9858 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
9859 Lua also ignores
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9860 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
9861 setting the values of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9862 <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
9863 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
9864
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9865
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9866 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9867 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
9868 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
9869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9870 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9871 $ 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
9872 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9873 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
9874 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
9875 (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
9876
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9877
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9878 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9879 Before running any code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9880 <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
9881 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
9882 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
9883 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
9884 and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9885 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
9886 (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
9887 go to negative indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9888 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
9889
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9890 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9891 $ 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
9892 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9893 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
9894
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9895 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9896 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
9897 [0] = "b.lua",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9898 [1] = "t1", [2] = "t2" }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9899 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9900 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
9901 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
9902 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
9903 For instance, the call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9904
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9905 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9906 $ 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
9907 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9908 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
9909 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
9910 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
9911 <code>arg[1]</code>, &middot;&middot;&middot;, <code>arg[#arg]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9912 (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
9913 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
9914
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9915
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9916 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9917 In interactive mode,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9918 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
9919 After reading a line,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9920 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
9921 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
9922 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
9923 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
9924 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
9925 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
9926
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9927
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9928 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9929 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
9930 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
9931 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
9932 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
9933 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
9934 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
9935 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
9936
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9937
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9938 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9939 When finishing normally,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9940 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
9941 (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
9942 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
9943 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
9944
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9946 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9947 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
9948 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
9949 the standalone interpreter skips
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9950 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
9951 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
9952 by using <code>chmod +x</code> and the&nbsp;<code>#!</code> form,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9953 as in
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9954
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9955 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9956 #!/usr/local/bin/lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9957 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9958 (Of course,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9959 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
9960 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
9961 then
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9962
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9963 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9964 #!/usr/bin/env lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9965 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9966 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
9967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9968
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 <h1>8 &ndash; <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
9971
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9972 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9973 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
9974 from Lua&nbsp;5.2 to Lua&nbsp;5.3.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9975 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
9976 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
9977 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9978 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
9979
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9981 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9982 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
9983 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
9984 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
9985 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
9986 Therefore,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9987 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
9988 different Lua versions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9989 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
9990 using a new version.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9993 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9994 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
9995 of precompiled chunks;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9996 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
9997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9998
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
9999 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10000 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
10001 change between versions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10002
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10003
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 <h2>8.1 &ndash; <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
10006 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10007
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10008 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10009 The main difference between Lua&nbsp;5.2 and Lua&nbsp;5.3 is the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10010 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
10011 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
10012 some computations
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10013 (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
10014 can give different results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10017 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10018 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
10019 (in Lua&nbsp;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
10020 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
10021 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
10022 (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
10023 for an occasional incompatibility;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10024 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
10025 For good programming,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10026 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
10027 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
10028 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10029
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 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
10032 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
10033 (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
10034 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
10035 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
10036 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
10037
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10038
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10039 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10040 (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
10041 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
10042 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
10043 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10044
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 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
10047 (It was an experimental feature in Lua&nbsp;5.2.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10048 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10050 </ul>
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
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 <h2>8.2 &ndash; <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
10056 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10058 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10059 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
10060 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
10061 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
10062 (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
10063 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
10064 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10065
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 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
10068 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
10069 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10070
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 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
10073 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
10074 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10075
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 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
10078 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
10079 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10080
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10081 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10082 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
10083 <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
10084 <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
10085 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
10086 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
10087 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
10088 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
10089 For the other operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10090 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
10091 implement them in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10092 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10093
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10094 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10095 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
10096 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
10097 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
10098 (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
10099 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
10100 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
10101 (Lua&nbsp;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
10102 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
10103 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10105 </ul>
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
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 <h2>8.3 &ndash; <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
10111
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10113 <ul>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10116 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
10117 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
10118 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
10119 Adapt your code accordingly.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10120 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10121
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10122 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10123 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
10124 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
10125 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10126
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10127 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10128 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
10129 (<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
10130 <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
10131 were deprecated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10132 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
10133 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10135 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10136 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
10137 (<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
10138 were deprecated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10139 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
10140 (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
10141 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10142
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10143 </ul>
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
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 <h1>9 &ndash; <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
10149
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10150 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10151 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
10152 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
10153 {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
10154 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
10155 (For operator precedences, see <a href="#3.4.8">&sect;3.4.8</a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10156 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
10157 Name, Numeral,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10158 and LiteralString, see <a href="#3.1">&sect;3.1</a>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10159
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10160
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 <pre>
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 chunk ::= block
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 block ::= {stat} [retstat]
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 stat ::= &lsquo;<b>;</b>&rsquo; |
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10170 varlist &lsquo;<b>=</b>&rsquo; explist |
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10171 functioncall |
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10172 label |
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10173 <b>break</b> |
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10174 <b>goto</b> Name |
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10175 <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
10176 <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
10177 <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
10178 <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
10179 <b>for</b> Name &lsquo;<b>=</b>&rsquo; exp &lsquo;<b>,</b>&rsquo; exp [&lsquo;<b>,</b>&rsquo; exp] <b>do</b> block <b>end</b> |
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10180 <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
10181 <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
10182 <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
10183 <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10184
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10185 retstat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
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 label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
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 funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
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 varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
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 var ::= Name | prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; | prefixexp &lsquo;<b>.</b>&rsquo; Name
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 namelist ::= Name {&lsquo;<b>,</b>&rsquo; 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 explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
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 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | &lsquo;<b>...</b>&rsquo; | functiondef |
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10200 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
10201
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10202 prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
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 functioncall ::= prefixexp args | prefixexp &lsquo;<b>:</b>&rsquo; Name args
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 args ::= &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo; | tableconstructor | LiteralString
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 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
10209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10210 funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
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 parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
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 tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
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 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
10217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10218 field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
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 fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
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 binop ::= &lsquo;<b>+</b>&rsquo; | &lsquo;<b>-</b>&rsquo; | &lsquo;<b>*</b>&rsquo; | &lsquo;<b>/</b>&rsquo; | &lsquo;<b>//</b>&rsquo; | &lsquo;<b>^</b>&rsquo; | &lsquo;<b>%</b>&rsquo; |
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10223 &lsquo;<b>&amp;</b>&rsquo; | &lsquo;<b>~</b>&rsquo; | &lsquo;<b>|</b>&rsquo; | &lsquo;<b>&gt;&gt;</b>&rsquo; | &lsquo;<b>&lt;&lt;</b>&rsquo; | &lsquo;<b>..</b>&rsquo; |
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10224 &lsquo;<b>&lt;</b>&rsquo; | &lsquo;<b>&lt;=</b>&rsquo; | &lsquo;<b>&gt;</b>&rsquo; | &lsquo;<b>&gt;=</b>&rsquo; | &lsquo;<b>==</b>&rsquo; | &lsquo;<b>~=</b>&rsquo; |
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10225 <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
10226
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10227 unop ::= &lsquo;<b>-</b>&rsquo; | <b>not</b> | &lsquo;<b>#</b>&rsquo; | &lsquo;<b>~</b>&rsquo;
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 </pre>
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 <p>
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
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 <HR>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10241 <SMALL CLASS="footer">
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10242 Last update:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10243 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
10244 </SMALL>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10245 <!--
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
10246 Last change: minor edit
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
372
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
10249 </div>
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
10250 </body>
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
10251 </html>