annotate website/src/manual.html.luan @ 459:30544d1a9cbf

better stack overflow handling
author Franklin Schmidt <fschmidt@gmail.com>
date Wed, 06 May 2015 12:58:06 -0600
parents e3a6d9dbd694
children eddf7c73373b
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
386
db23f654f87d make all of website use luan
Franklin Schmidt <fschmidt@gmail.com>
parents: 382
diff changeset
1 local Io = require "luan:Io"
db23f654f87d make all of website use luan
Franklin Schmidt <fschmidt@gmail.com>
parents: 382
diff changeset
2 local Html = require "luan:Html"
db23f654f87d make all of website use luan
Franklin Schmidt <fschmidt@gmail.com>
parents: 382
diff changeset
3 local Http = require "luan:web/Http"
387
23d075ce1e48 add website/src/Shared.luan
Franklin Schmidt <fschmidt@gmail.com>
parents: 386
diff changeset
4 local Shared = require "site:/Shared"
386
db23f654f87d make all of website use luan
Franklin Schmidt <fschmidt@gmail.com>
parents: 382
diff changeset
5
db23f654f87d make all of website use luan
Franklin Schmidt <fschmidt@gmail.com>
parents: 382
diff changeset
6
db23f654f87d make all of website use luan
Franklin Schmidt <fschmidt@gmail.com>
parents: 382
diff changeset
7 function service()
db23f654f87d make all of website use luan
Franklin Schmidt <fschmidt@gmail.com>
parents: 382
diff changeset
8 Io.stdout = Http.response.text_writer()
391
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom
Franklin Schmidt <fschmidt@gmail.com>
parents: 389
diff changeset
9 %>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom
Franklin Schmidt <fschmidt@gmail.com>
parents: 389
diff changeset
10 <html>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom
Franklin Schmidt <fschmidt@gmail.com>
parents: 389
diff changeset
11 <head>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom
Franklin Schmidt <fschmidt@gmail.com>
parents: 389
diff changeset
12 <% Html.simply_html_head() %>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom
Franklin Schmidt <fschmidt@gmail.com>
parents: 389
diff changeset
13 <title>Luan Reference Manual</title>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom
Franklin Schmidt <fschmidt@gmail.com>
parents: 389
diff changeset
14 </head>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom
Franklin Schmidt <fschmidt@gmail.com>
parents: 389
diff changeset
15 <body>
386
db23f654f87d make all of website use luan
Franklin Schmidt <fschmidt@gmail.com>
parents: 382
diff changeset
16
372
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
17 <div container>
387
23d075ce1e48 add website/src/Shared.luan
Franklin Schmidt <fschmidt@gmail.com>
parents: 386
diff changeset
18 <% Shared.header() %>
372
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
19
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
20 <h1>Luan Reference Manual</h1>
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
21
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
22 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
23 <small>
372
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
24 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
25 Freely available under the terms of the
372
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
26 <a href="http://www.lua.org/license.html">Lua license</a>.
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
27 Modified for Luan.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
28 </small>
372
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
29 </p>
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
30
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
31 <hr/>
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
32
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
33 <h2>Contents</h2>
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
34
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
35 <div margin-bottom="1em"><a href="#intro">Introduction</a></div>
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
36
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
37 <div margin-bottom="1em">
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
38 <a href="#basic">Basic Concepts</a>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
39 <ul>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
40 <li><a href="#types">Values and Types</a></li>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
41 <li><a href="#env">Environments</a></li>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
42 <li><a href="#error">Error Handling</a></li>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
43 <li><a href="#meta">Metatables and Metamethods</a></li>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
44 <li><a href="#gc">Garbage Collection</a></li>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
45 </ul>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
46 </div>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
47
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
48 <div margin-bottom="1em">
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
49 <a href="#lang">The Language</a>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
50 <ul>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
51 <li><a href="#lex">Lexical Conventions</a></li>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
52 <li><a href="#vars">Variables</a></li>
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
53 <li>
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
54 <a href="#stmts">Statements</a>
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
55 <ul>
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
56 <li><a href="#blocks">Blocks</a></li>
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
57 <li><a href="#chunks">Chunks</a></li>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
58 <li><a href="#assignment">Assignment</a></li>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
59 <li><a href="#control">Control Structures</a></li>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
60 <li><a href="#for">For Statement</a></li>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
61 <li><a href="#fn_stmt">Function Calls as Statements</a></li>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
62 <li><a href="#local_stmt">Local Declarations</a></li>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
63 </ul>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
64 </li>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
65 <li>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
66 <a href="#expressions">Expressions</a>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
67 <ul>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
68 <li><a href="#arithmetic">Arithmetic Operators</a></li>
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
69 <li><a href="#conversions">Coercions and Conversions</a></li>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
70 <li><a href="#relational">Relational Operators</a></li>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
71 <li><a href="#logical_ops">Logical Operators</a></li>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
72 <li><a href="#concatenation">Concatenation</a></li>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
73 <li><a href="#length">The Length Operator</a></li>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
74 <li><a href="#precedence">Precedence</a></li>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
75 <li><a href="#constructors">Table Constructors</a></li>
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
76 <li><a href="#fn_calls">Function Calls</a></li>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
77 <li><a href="#fn_def">Function Definitions</a></li>
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
78 </ul>
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
79 </li>
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
80 <li><a href="#visibility">>Visibility Rules</a></li>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
81 </ul>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
82 </div>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
83
372
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
84 <hr/>
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
85
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
86
372
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
87 <h2 margin-top="1em"><a name="intro">Introduction</a></h2>
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
88
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
89 <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
90
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
91 <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
92
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
93 <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
94
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
95
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
96 <h2 margin-top="1em"><a name="basic">Basic Concepts</a></h2>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
97
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
98 <p>This section describes the basic concepts of the language.</p>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
99
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
100 <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
101
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
102 <p>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
103 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
104 This means that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
105 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
106 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
107 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
108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
110 <p>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
111 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
112 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
113 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
114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
115
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
116 <p>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
117 There are eight basic types in Luan:
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
118 <i>nil</i>, <i>boolean</i>, <i>number</i>,
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
119 <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
120 and <i>table</i>.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
121 <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
122 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
123 it usually represents the absence of a useful value.
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
124 <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
125 <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
126 <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
127 <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
128 integer numbers and real (floating-point) numbers.
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
129 <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
130 the underlying Java implementation.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
131
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
132 <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
133 <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
134
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
135
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
136 <p>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
137 Luan can call (and manipulate) functions written in Luan and
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
138 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
139 Both are represented by the type <i>function</i>.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
140
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
141
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
142 <p>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
143 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
144 be stored in Luan variables.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
145 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
146 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
147 except assignment and identity test.
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
148 Userdata is useful then Java access is enabled in Luan
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
149
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
150
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
151
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
152 <p>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
153 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
154 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
155 but with any Luan value except <b>nil</b>.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
156 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
157 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
158 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
159 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
160 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
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>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
164 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
165 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
166 symbol tables, sets, records, graphs, trees, etc.
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
167 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
168 The language supports this representation by
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
169 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
170 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
171 (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
172
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
173
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
174 <p>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
175 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
176 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
177 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
178 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
179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
180
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
181 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
182 Like indices,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
183 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
184 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
185 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
186 table fields can contain functions.
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
187 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
191 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
192 the definition of raw equality in the language.
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
193 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
194 denote the same table element
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
195 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
196 (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
197 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
198 are equal to their respective integers
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
199 (e.g., <tt>1.0 == 1</tt>).
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
200
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
201
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
202 <p>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
203 Luan values are <i>objects</i>:
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
204 variables do not actually <i>contain</i> values,
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
205 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
206 Assignment, parameter passing, and function returns
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
207 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
208 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
209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
211 <p>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
212 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
213 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
214
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
215
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
216
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
218
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
219 <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
220
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
221 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
222 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
223 any reference to a free name
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
224 (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
225 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
226 Moreover, every chunk is compiled in the scope of
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
227 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
228 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
229
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 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
233 the translation of free names,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
234 <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
235 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
236 you can define new variables and parameters with that name.
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
237 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
238 visible at that point in the program,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
239 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
240
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
241
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
242 <p>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
243 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
244
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
245
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
246 <p>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
247 When Luan loads a chunk,
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
248 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
249
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
250 <p>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
251 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
252
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
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
255
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
256 <h3 margin-top="1em"><a name="error">Error Handling</a></h3>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
257
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
258 <p>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
259 Luan code can explicitly generate an error by calling the
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
260 <a href="#pdf-error"><tt>error</tt></a> function.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
261 If you need to catch errors in Luan,
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
262 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
263 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
264
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
265
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
266 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
267 Whenever there is an error,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
268 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
269 is propagated with information about the error.
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
270 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
271 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
272 any value as the error object.
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
273 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
274
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
275
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
276
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
277
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
278
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
279 <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
280
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
281 <p>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
282 Every table in Luan can have a <i>metatable</i>.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
283 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
284 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
285 under certain special operations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
286 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
287 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
288 For instance, when a table is the operand of an addition,
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
289 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
290 If it finds one,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
291 Luan calls this function to perform the addition.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
292
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
293
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
294 <p>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
295 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
296 the corresponding values are called <ii>metamethods</i>.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
297 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
298 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
299
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
301 <p>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
302 You can query the metatable of any table
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
303 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
304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
305
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
306 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
307 You can replace the metatable of tables
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
308 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
309
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
310
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
311 <p>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
312 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
313 arithmetic operations, bitwise operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
314 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
315
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
316
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
317 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
318 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
319 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
320 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
321 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
322 for instance, the key for operation "add" is the
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
323 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
324 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
325 the access to a metamethod does not invoke other metamethods.
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
326 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
327 with the following code:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
328
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
329 <p><tt><pre>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
330 raw_get(get_metatable(obj) or {}, "__" .. event_name)
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
331 </pre></tt></p>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
332
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
333 <p>
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
334 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
335
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
336 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
338 <li><b>"add": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
339 the <tt>+</tt> operation.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
340
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
341 If any operand for an addition is a table,
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
342 Luan will try to call a metamethod.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
343 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
344 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
345 then Luan will check the second operand.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
346 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
347 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
348 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
349 (adjusted to one value)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
350 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
351 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
352 it raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
353 </li>
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 <li><b>"sub": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
356 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
357
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
358 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
359 </li>
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 <li><b>"mul": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
362 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
363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
364 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
365 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
366
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
367 <li><b>"div": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
368 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
369
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
370 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
371 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
372
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
373 <li><b>"mod": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
374 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
375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
376 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
377 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
378
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
379 <li><b>"pow": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
380 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
381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
382 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
383 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
384
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
385 <li><b>"unm": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
386 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
387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
388 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
389 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
391 <li><b>"concat": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
392 the <tt>..</tt> (concatenation) operation.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
393
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
394 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
395 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
396
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
397 <li><b>"len": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
398 the <tt>#</tt> (length) operation.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
399
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
400 If there is a metamethod,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
401 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
402 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
403 (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
404 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
405 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
406 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
407 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
408 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
409
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
410 <li><b>"eq": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
411 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
412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
413 Behavior similar to the "add" operation,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
414 except that Luan will try a metamethod only when the values
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
415 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
416 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
417 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
418 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
419
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
420 <li><b>"lt": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
421 the <tt>&lt;</tt> (less than) operation.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
422
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
423 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
424 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
425 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
426
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
427 <li><b>"le": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
428 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
429
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
430 Unlike other operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
431 The less-equal operation can use two different events.
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
432 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
433 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
434 If it cannot find such a metamethod,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
435 then it will try the "<tt>__lt</tt>" event,
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
436 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
437 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
438 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
439 </li>
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 <li><b>"index": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
442 The indexing access <tt>table[key]</tt>.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
443
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
444 This event happens
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
445 when <tt>key</tt> is not present in <tt>table</tt>.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
446 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
447
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
448
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
449 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
450 Despite the name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
451 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
452 If it is a function,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
453 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
454 If it is a table,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
455 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
456 (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
457 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
458 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
459
428
df95199ca4c0 rename __newindex to __new_index
Franklin Schmidt <fschmidt@gmail.com>
parents: 418
diff changeset
460 <li><b>"new_index": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
461 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
462
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
463 Like the index event,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
464 this event happens when
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
465 when <tt>key</tt> is not present in <tt>table</tt>.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
466 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
467
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
468
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
469 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
470 Like with indexing,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
471 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
472 If it is a function,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
473 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
474 If it is a table,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
475 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
476 (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
477 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
478
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
479
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
480 <p>
428
df95199ca4c0 rename __newindex to __new_index
Franklin Schmidt <fschmidt@gmail.com>
parents: 418
diff changeset
481 Whenever there is a "new_index" metamethod,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
482 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
483 (If necessary,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
484 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
485 to do the assignment.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
486 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
488 <li><b>"call": </b>
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
489 The call operation <tt>func(args)</tt>.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
490
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
491 This event happens when Luan tries to call a table.
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
492 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
493 If present,
373
571057b1666b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 372
diff changeset
494 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
495 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
496 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
497
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
498 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
502
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
503 <h3 margin-top="1em"><a name="gc">Garbage Collection</a></h3>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
504
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
505 <p>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
506 Luan uses Java's garbage collection.
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
507
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
508
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
509
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
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
512 <h2 margin-top="1em"><a name="lang">The Language</a></h2>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
513
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
514 <p>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
515 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
516 In other words,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
517 this section describes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
518 which tokens are valid,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
519 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
520 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
521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
523 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
524 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
525 in which
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
526 {<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
527 [<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
528 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
529 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
530 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
531 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
532 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
533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
534
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
535
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
536 <h3 margin-top="1em"><a name="lex">Lexical Conventions</a></h3>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
537
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
538 <p>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
539 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
540 between lexical elements (tokens),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
541 except as delimiters between names and keywords.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
542 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
543
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
544 <p>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
545 <i>Names</i>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
546 (also called <i>identifiers</i>)
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
547 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
548 digits, and underscores,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
549 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
550 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
551
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
552
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
553 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
554 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
555 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
556
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
557
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
558 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
559 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
560 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
561 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
562 then true until while
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
563 </pre></tt></p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
565 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
566 Luan is a case-sensitive language:
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
567 <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
568 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
569
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
570
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
571 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
572 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
573
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
574 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
575 + - * / % ^ #
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
576 &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
577 == ~= &lt;= &gt;= &lt; &gt; =
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 ; : , . .. ...
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
580 </pre></tt></p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
582 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
583 <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
584 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
585 and can contain the following C-like escape sequences:
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
586 '<tt>\a</tt>' (bell),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
587 '<tt>\b</tt>' (backspace),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
588 '<tt>\f</tt>' (form feed),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
589 '<tt>\n</tt>' (newline),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
590 '<tt>\r</tt>' (carriage return),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
591 '<tt>\t</tt>' (horizontal tab),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
592 '<tt>\v</tt>' (vertical tab),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
593 '<tt>\\</tt>' (backslash),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
594 '<tt>\"</tt>' (quotation mark [double quote]),
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
595 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
596 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
597 results in a newline in the string.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
598 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
599 of white-space characters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
600 including line breaks;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
601 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
602 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
603 into the string contents.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
604
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
605
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
606 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
607 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
608 This can be done
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
609 with the escape sequence <tt>\x<i>XX</i></tt>,
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
610 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
611 or with the escape sequence <tt>\<i>ddd</i></tt>,
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
612 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
613 (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
614 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
615
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
616
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
617 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
618 Literal strings can also be defined using a long format
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
619 enclosed by <i>long brackets</i>.
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
620 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
621 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
622 opening square bracket.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
623 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
624 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
625 and so on.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
626 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
627 for instance,
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
628 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
629 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
630 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
631 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
632 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
633 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
634 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
635 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
636 (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
637 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
638 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
639
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
640
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
641 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
642 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
643 explicitly affected by the previous rules represents itself.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
644 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
645 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
646 some control characters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
647 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
648 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
649 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
650
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
651
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
652 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
653 For convenience,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
654 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
655 the newline is not included in the string.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
656 As an example
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
657 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
658
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
659 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
660 a = 'alo\n123"'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
661 a = "alo\n123\""
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
662 a = '\97lo\10\04923"'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
663 a = [[alo
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
664 123"]]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
665 a = [==[
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
666 alo
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
667 123"]==]
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
668 </pre></tt></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>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
672 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
673 and an optional decimal exponent,
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
674 marked by a letter '<tt>e</tt>' or '<tt>E</tt>'.
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
675 Luan also accepts hexadecimal constants,
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
676 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
677 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
678 plus an optional binary exponent,
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
679 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
680 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
681 denotes a float;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
682 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
683 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
684
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
685 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
686 3 345 0xff 0xBEBADA
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
687 </pre></tt></p>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
688
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
689 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
690 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
691
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
692 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
693 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
694 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
695 </pre></tt></p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
696
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
697 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
698 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
699 anywhere outside a string.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
700 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
701 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
702 which runs until the end of the line.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
703 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
704 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
705 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
706
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
709
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
710
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
711 <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
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 Variables are places that store values.
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
715 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
716 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
717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
718
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
719 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
720 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
721 (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
722 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
723
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
724 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
725 var ::= Name
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
726 </pre></tt></p>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
727
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
728 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
729 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
730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
731
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
732 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
733 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
734 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
735 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
736 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
737 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
738
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
739
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
740 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
741 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
742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
743
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
744 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
745 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
746
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
747 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
748 var ::= prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo;
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
749 </pre></tt></p>
382
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
750
8557581740db added tutorial
Franklin Schmidt <fschmidt@gmail.com>
parents: 380
diff changeset
751 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
752 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
753 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
754 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
755 (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
756 <tt>gettable_event</tt> function.
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
757 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
758 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
759
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 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
762 The syntax <tt>var.Name</tt> is just syntactic sugar for
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
763 <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
764
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
765 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
766 var ::= prefixexp &lsquo;<b>.</b>&rsquo; Name
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
767 </pre></tt></p>
371
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 <p>
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
770 An access to a global variable <tt>x</tt>
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
771 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
772 Due to the way that chunks are compiled,
380
6c6c3537035e work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 373
diff changeset
773 <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
774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
776
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
777
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
778
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
779 <h3 margin-top="1em"><a name="stmts">Statements</a></h3>
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
780
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
781 <p>
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
782 Luan supports an almost conventional set of statements,
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
783 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
784 This set includes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
785 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
786 and variable declarations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
789
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
790 <h4 margin-top="1em"><a name="blocks">Blocks</a></h4>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
791
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
792 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
793 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
794 which are executed sequentially:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
795
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
796 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
797 block ::= {stat}
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
798 </pre></tt></p>
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
799
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
800 <p>
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
801 Luan has <i>empty statements</i>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
802 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
803 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
804 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
805
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
806 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
807 stat ::= &lsquo;<b>;</b>&rsquo;
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
808 </pre></tt></p>
371
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
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
813 <p><tt><pre>
371
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>
389
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
815 </pre></tt></p>
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
816
497d4ef0a89f documentation work
Franklin Schmidt <fschmidt@gmail.com>
parents: 387
diff changeset
817 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
818 Explicit blocks are useful
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
819 to control the scope of variable declarations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
820 Explicit blocks are also sometimes used to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
821 add a <b>return</b> statement in the middle
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
822 of another block (see <a href="#3.3.4">&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
823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
826
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
827
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
828 <h4 margin-top="1em"><a name="chunks">Chunks</a></h4>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
829
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
830 <p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
831 The unit of compilation of Luan is called a <i>chunk</i>.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
832 Syntactically,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
833 a chunk is simply a block:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
834
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
835 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
836 chunk ::= block
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
837 </pre></tt></p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
838
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
839 <p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
840 Luan handles a chunk as the body of an anonymous function
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
841 with a variable number of arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
842 (see <a href="#3.4.11">&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
843 As such, chunks can define local variables,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
844 receive arguments, and return values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
845
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
846
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
847 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
848 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
849 To execute a chunk,
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
850 Luan first <i>loads</i> it,
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
851 compiling the chunk's code,
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
852 and then Luan executes the compiled code.
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
853
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
854
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
855
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
856
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
857
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
858 <h4 margin-top="1em"><a name="assignment">Assignment</a></h4>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
859
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
860 <p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
861 Luan allows multiple assignments.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
862 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
863 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
864 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
865 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
866
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
867 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
868 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
869 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
870 explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
871 </pre></tt></p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
872
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
873 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
874 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
875
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
878 Before the assignment,
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
879 the list of values is <i>adjusted</i> to the length of
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
880 the list of variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
881 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
882 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
883 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
884 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
885 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
886 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
887 before the adjustment
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
888 (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
889
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
890
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
891 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
892 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
893 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
894 Thus the code
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
895
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
896 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
897 i = 3
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
898 i, a[i] = i+1, 20
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
899 </pre></tt></p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
900
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
901 <p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
902 sets <tt>a[3]</tt> to 20, without affecting <tt>a[4]</tt>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
903 because the <tt>i</tt> in <tt>a[i]</tt> is evaluated (to 3)
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
904 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
905 Similarly, the line
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
906
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
907 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
908 x, y = y, x
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
909 </pre></tt></p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
910
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
911 <p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
912 exchanges the values of <tt>x</tt> and <tt>y</tt>,
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
913 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
914
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
915 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
916 x, y, z = y, z, x
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
917 </pre></tt></p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
918
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
919 <p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
920 cyclically permutes the values of <tt>x</tt>, <tt>y</tt>, and <tt>z</tt>.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
921
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
922
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
923 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
924 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
925 and table fields can be changed via metatables.
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
926 An assignment to an indexed variable <tt>t[i] = val</tt> is equivalent to
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
927 <tt>settable_event(t,i,val)</tt>.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
928 (See <a href="#2.4">&sect;2.4</a> for a complete description of the
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
929 <tt>settable_event</tt> function.
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
930 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
931 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
932
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
933
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
934 <p>
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
935 An assignment to a global name <tt>x = val</tt>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
936 is equivalent to the assignment
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
937 <tt>_ENV.x = val</tt> (see <a href="#2.2">&sect;2.2</a>).
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
938
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
939
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
940
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
941
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
942 <h4 margin-top="1em"><a name="control">Control Structures</a></h4>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
943
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
944 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
945 The control structures
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
946 <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
947 familiar syntax:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
948
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
949 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
950 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
951 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
952 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b>
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
953 </pre></tt></p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
954
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
955 <p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
956 Luan also has a <b>for</b> statement (see <a href="#3.3.5">&sect;3.3.5</a>).
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
957
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
958
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
959 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
960 The condition expression of a
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
961 control structure must be a boolean.
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
962 Any other value type will produce an error.
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
963 This helps catch errors and makes code more readable.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
964
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
965
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
966 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
967 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
968 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
969 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
970 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
971 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
972
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
973
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
974 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
975 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
976 <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
977 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
978
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
979
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
980 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
981 stat ::= <b>break</b>
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
982 </pre></tt></p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
983
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
984 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
985 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
986
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
987
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
988 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
989 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
990 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
991 (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
992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
993 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
994 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
995
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
996 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
997 stat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
998 </pre></tt></p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
999
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1000
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1001
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1002
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1003 <h4 margin-top="1em"><a name="for">For Statement</a></h4>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1004
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1005 <p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1006 The <b>for</b> statement works over functions,
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1007 called <i>iterators</i>.
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1008 On each iteration, the iterator function is called to produce a new value,
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1009 stopping when this new value is <b>nil</b>.
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1010 The <b>for</b> loop has the following syntax:
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1011
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1012 <p><tt><pre>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1013 stat ::= <b>for</b> namelist <b>in</b> exp <b>do</b> block <b>end</b>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1014 namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1015 </pre></tt></p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1016
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1017 <p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1018 A <b>for</b> statement like
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1019
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1020 <p><tt><pre>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1021 for <i>var_1</i>, &middot;&middot;&middot;, <i>var_n</i> in <i>exp</i> do <i>block</i> end
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1022 </pre></tt></p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1023
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1024 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1025 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
1026
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1027 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1028 do
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1029 local <i>f</i> = <i>exp</i>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1030 while true do
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1031 local <i>var_1</i>, &middot;&middot;&middot;, <i>var_n</i> = <i>f</i>()
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1032 if <i>var_1</i> == nil then break end
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1033 <i>block</i>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1034 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1035 end
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1036 </pre></tt></p>
371
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1039 Note the following:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1040
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1041 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1042
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1043 <li>
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1044 <tt><i>exp</i></tt> is evaluated only once.
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1045 Its result is an <i>iterator</i> function.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1046 </li>
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 <li>
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1049 <tt><i>f</i></tt> is an invisible variable.
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1050 The name is here for explanatory purposes only.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1051 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1054 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
1055 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1056
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1057 <li>
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1058 The loop variables <tt><i>var_i</i></tt> are local to the loop;
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1059 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
1060 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
1061 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
1062 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1063
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1064 </ul>
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1067
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1068
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1069 <h4 margin-top="1em"><a name="fn_stmt">Function Calls as Statements</a></h4>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1070
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1071 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1072 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
1073 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
1074
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1075 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1076 stat ::= functioncall
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1077 </pre></tt></p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1078
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1079 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1080 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
1081 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
1082
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1083
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1084
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1085 <h4 margin-top="1em"><a name="local_stmt">Local Declarations</a></h4>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1086
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1087 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1088 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
1089 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
1090
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1091 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1092 stat ::= <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist]
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1093 </pre></tt></p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1094
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1095 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1096 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
1097 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
1098 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
1099
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1100
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1101 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1102 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
1103 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
1104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1105
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1106 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1107 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
1108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1110
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1111
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1112 <h3 margin-top="1em"><a name="expressions">Expressions</a></h3>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1113
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1114 <p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1115 The basic expressions in Luan are the following:
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1116
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1117 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1118 exp ::= prefixexp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1119 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
1120 exp ::= Numeral
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1121 exp ::= LiteralString
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1122 exp ::= functiondef
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1123 exp ::= tableconstructor
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1124 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
1125 exp ::= exp binop exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1126 exp ::= unop exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1127 prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1128 </pre></tt></p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1129
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1130 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1131 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
1132 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
1133 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
1134 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
1135 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
1136 Vararg expressions,
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1137 denoted by three dots ('<tt>...</tt>'), can only be used when
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1138 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
1139 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
1140
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1141
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1142 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1143 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
1144 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
1145 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
1146 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
1147 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
1148 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
1149
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1151 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1152 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
1153 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
1154 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
1155 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
1156 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
1157 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
1158 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
1159 (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
1160 In all other contexts,
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1161 Luan adjusts the result list to one element,
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1162 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
1163 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
1164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1166 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1167 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1168
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1169 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1170 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
1171 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
1172 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
1173 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
1174 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
1175 -- 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
1176 -- 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
1177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1178 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
1179 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
1180 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
1181 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
1182 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
1183 {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
1184 {...} -- 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
1185 {f(), nil} -- f() is adjusted to 1 result
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1186 </pre></tt></p>
371
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1189 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
1190 Thus,
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1191 <tt>(f(x,y,z))</tt> is always a single value,
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1192 even if <tt>f</tt> returns several values.
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1193 (The value of <tt>(f(x,y,z))</tt> is the first value returned by <tt>f</tt>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1194 or <b>nil</b> if <tt>f</tt> does not return any values.)
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1195
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1196
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1197
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1198 <h4 margin-top="1em"><a name="arithmetic">Arithmetic Operators</a></h4>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1199
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1200 <p>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1201 Luan supports the following arithmetic operators:
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1202
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1203 <ul>
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1204 <li><b><tt>+</tt>: </b>addition</li>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1205 <li><b><tt>-</tt>: </b>subtraction</li>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1206 <li><b><tt>*</tt>: </b>multiplication</li>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1207 <li><b><tt>/</tt>: </b>division</li>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1208 <li><b><tt>%</tt>: </b>modulo</li>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1209 <li><b><tt>^</tt>: </b>exponentiation</li>
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1210 <li><b><tt>-</tt>: </b>unary minus</li>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1211 </ul>
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 <p>
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1214 Addition, subtraction, multiplication, division, and unary minus are the same as these operators in Java. Exponentiation uses Java's <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Math.html#pow(double,%20double)">Math.pow</a> function.
371
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1217 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
1218 that rounds the quotient towards minus infinite (floor division).
395
a7cb58532846 work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 391
diff changeset
1219 (The Java modulo operator is not used.)
371
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1222
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1223 <h4 margin-top="1em"><a name="conversions">Coercions and Conversions</a></h4>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1224
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1225 <p>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1226 Luan provides some automatic conversions between some
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1227 types and representations at run time.
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1228 String concatenation converts all of its arguments to strings.
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1229
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1230 Luan also converts strings to numbers
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1231 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
1232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1233
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1234
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1235
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1236
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1237 <h4 margin-top="1em"><a name="relational">Relational Operators</a></h4>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1238
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1239 <p>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1240 Luan supports the following relational operators:
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1241
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1242 <ul>
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1243 <li><b><tt>==</tt>: </b>equality</li>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1244 <li><b><tt>~=</tt>: </b>inequality</li>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1245 <li><b><tt>&lt;</tt>: </b>less than</li>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1246 <li><b><tt>&gt;</tt>: </b>greater than</li>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1247 <li><b><tt>&lt;=</tt>: </b>less or equal</li>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1248 <li><b><tt>&gt;=</tt>: </b>greater or equal</li>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1249 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1250 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
1251
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1252
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1253 <p>
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1254 Equality (<tt>==</tt>) first compares the type of its operands.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1255 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
1256 Otherwise, the values of the operands are compared.
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1257 Strings, numbers, and binary values are compared in the obvious way (by value).
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1258
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1259 <p>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1260 Tables
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1261 are compared by reference:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1262 two objects are considered equal only if they are the same object.
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1263 Every time you create a new table,
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1264 it is different from any previously existing table.
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1265 Closures are also compared by reference.
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1266
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1267 <p>
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1268 You can change the way that Luan compares tables
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1269 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
1270
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1271 <p>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1272 Userdata are Java objects. They are compared for equality with the Java <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html#equals(java.lang.Object)"><tt>equals</tt></a> method.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1273
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1274 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1275 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
1276 or vice versa.
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1277 Thus, <tt>"0"==0</tt> evaluates to <b>false</b>,
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1278 and <tt>t[0]</tt> and <tt>t["0"]</tt> denote different
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1279 entries in a table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1281
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1282 <p>
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1283 The operator <tt>~=</tt> is exactly the negation of equality (<tt>==</tt>).
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1285
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1286 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1287 The order operators work as follows.
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1288
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1289 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
1290 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
1291 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
1292 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
1293 then their values are compared according to the current locale.
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1294 Otherwise, Luan tries to call the "lt" or the "le"
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1295 metamethod (see <a href="#2.4">&sect;2.4</a>).
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1296 A comparison <tt>a &gt; b</tt> is translated to <tt>b &lt; a</tt>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1297 and <tt>a &gt;= b</tt> is translated to <tt>b &lt;= a</tt>.
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1298
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1299
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1300
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1301
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1302
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1303 <h4 margin-top="1em"><a name="logical_ops">Logical Operators</a></h4>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1304
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1305 <p>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1306 The logical operators in Luan are
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1307 <b>and</b>, <b>or</b>, and <b>not</b>.
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1308 The <b>and</b> and <b>or</b> operators consider both <b>false</b> and <b>nil</b> as false
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1309 and anything else as true.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1310 Like the control structures (see <a href="#3.3.4">&sect;3.3.4</a>),
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1311 the <b>not</b> operator requires a boolean value.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1312
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1313 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1314 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
1315 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
1316 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
1317 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
1318 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
1319 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
1320 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
1321 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
1322 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1323 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
1324 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1325
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1326 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1327 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
1328 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
1329 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
1330 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
1331 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
1332 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
1333 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
1334 10 and 20 --&gt; 20
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1335 </pre></tt></p>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1336
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1337 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1338 (In this manual,
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1339 <tt>--&gt;</tt> indicates the result of the preceding expression.)
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1340
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1341
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1342
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1343 <h4 margin-top="1em"><a name="concatenation">Concatenation</a></h4>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1344
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1345 <p>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1346 The string concatenation operator in Luan is
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1347 denoted by two dots ('<tt>..</tt>').
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1348 All operands are converted to strings.
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1349
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1350
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1351
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1352 <h4 margin-top="1em"><a name="length">The Length Operator</a></h4>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1353
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1354 <p>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1355 The length operator is denoted by the unary prefix operator <tt>#</tt>.
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1356 The length of a string is its number of characters.
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1357 The length of a binary is its number of bytes.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1358
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1361 A program can modify the behavior of the length operator for
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1362 any table through the <tt>__len</tt> metamethod (see <a href="#2.4">&sect;2.4</a>).
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1363
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1364
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1365 <p>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1366 Unless a <tt>__len</tt> metamethod is given,
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1367 the length of a table <tt>t</tt> is defined
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1368 as the number of elements in <em>sequence</em>,
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1369 that is,
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1370 the size of the set of its positive numeric keys is equal to <em>{1..n}</em>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1371 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
1372 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
1373 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
1374
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1375 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1376 {10, 20, nil, 40}
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1377 </pre></tt></p>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1378
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1379 <p>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1380 has a length of <tt>2</tt>, because that is the last key in sequence.
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1381
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1382
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1383
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1384
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1385
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1386 <h4 margin-top="1em"><a name="precedence">Precedence</a></h4>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1387
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1388 <p>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1389 Operator precedence in Luan follows the table below,
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1390 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
1391
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1392 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1393 or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1394 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1395 &lt; &gt; &lt;= &gt;= ~= ==
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1396 ..
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1397 + -
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1398 * / %
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1399 unary operators (not # -)
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1400 ^
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1401 </pre></tt></p>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1402
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1403 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1404 As usual,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1405 you can use parentheses to change the precedences of an expression.
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1406 The concatenation ('<tt>..</tt>') and exponentiation ('<tt>^</tt>')
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1407 operators are right associative.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1408 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
1409
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1413
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1414 <h4 margin-top="1em"><a name="constructors">Table Constructors</a></h4>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1415
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1416 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1417 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
1418 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
1419 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
1420 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
1421 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
1422
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1423 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1424 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
1425 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
1426 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
1427 fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1428 </pre></tt></p>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1429
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1430 <p>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1431 Each field of the form <tt>[exp1] = exp2</tt> adds to the new table an entry
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1432 with key <tt>exp1</tt> and value <tt>exp2</tt>.
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1433 A field of the form <tt>name = exp</tt> is equivalent to
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1434 <tt>["name"] = exp</tt>.
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1435 Finally, fields of the form <tt>exp</tt> are equivalent to
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1436 <tt>[i] = exp</tt>, where <tt>i</tt> are consecutive integers
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1437 starting with 1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1438 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
1439 For example,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1440
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1441 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1442 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1443 </pre></tt></p>
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1444
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1445 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1446 is equivalent to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1447
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1448 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1449 do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1450 local t = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1451 t[f(1)] = g
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1452 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
1453 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
1454 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
1455 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
1456 t[30] = 23
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1457 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
1458 a = t
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1459 end
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1460 </pre></tt></p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1461
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1462 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1463 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
1464 (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
1465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1467 <p>
396
ba8b0aae6453 work on manual;
Franklin Schmidt <fschmidt@gmail.com>
parents: 395
diff changeset
1468 If the last field in the list has the form <tt>exp</tt>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1469 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
1470 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
1471 (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
1472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1473
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1474 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1475 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
1476 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
1477
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1478
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1479
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1480
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1481
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1482 <h4 margin-top="1em"><a name="fn_calls">Function Calls</a></h4>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1483
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1484 <p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1485 A function call in Luan has the following syntax:
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1486
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1487 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1488 functioncall ::= prefixexp args
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1489 </pre></tt></p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1490
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1491 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1492 In a function call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1493 first prefixexp and args are evaluated.
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1494 If the value of prefixexp has type <i>function</i>,
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1495 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
1496 with the given arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1497 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
1498 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
1499 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
1500 (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
1501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1502
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1503 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1504 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
1505
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1506 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1507 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
1508 args ::= tableconstructor
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1509 args ::= LiteralString
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1510 </pre></tt></p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1511
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1512 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1513 All argument expressions are evaluated before the call.
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1514 A call of the form <tt>f{<i>fields</i>}</tt> is
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1515 syntactic sugar for <tt>f({<i>fields</i>})</tt>;
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1516 that is, the argument list is a single new table.
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1517 A call of the form <tt>f'<i>string</i>'</tt>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1518 (or <tt>f"<i>string</i>"</tt> or <tt>f[[<i>string</i>]]</tt>)
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1519 is syntactic sugar for <tt>f('<i>string</i>')</tt>;
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1520 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
1521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1523 <p>
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1524 A call of the form <tt>return <i>functioncall</i></tt> is called
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1525 a <i>tail call</i>.
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1526 Luan implements <i>proper tail calls</i>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1527 (or <i>proper tail recursion</i>):
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1528 in a tail call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1529 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
1530 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
1531 a program can execute.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1532 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
1533 calling function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1534 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
1535 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
1536 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
1537 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
1538 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
1539
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1540 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1541 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
1542 return 2 * f(x)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1543 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
1544 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
1545 return x or f(x) -- results adjusted to 1
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1546 </pre></tt></p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1547
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1548
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1549
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1550
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1551 <h4 margin-top="1em"><a name="fn_def">Function Definitions</a></h4>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1552
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1553 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1554 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
1555
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1556 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1557 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
1558 funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1559 </pre></tt></p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1560
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1561 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1562 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
1563
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1564 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1565 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
1566 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
1567 funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1568 </pre></tt></p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1569
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1570 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1571 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1572
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1573 <p><tt><pre>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1574 function f () <i>body</i> end
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1575 </pre></tt></p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1576
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1577 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1578 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1579
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1580 <p><tt><pre>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1581 f = function () <i>body</i> end
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1582 </pre></tt></p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1583
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1584 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1585 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1586
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1587 <p><tt><pre>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1588 function t.a.b.c.f () <i>body</i> end
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1589 </pre></tt></p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1590
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1591 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1592 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1593
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1594 <p><tt><pre>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1595 t.a.b.c.f = function () <i>body</i> end
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1596 </pre></tt></p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1597
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1598 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1599 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1600
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1601 <p><tt><pre>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1602 local function f () <i>body</i> end
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1603 </pre></tt></p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1604
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1605 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1606 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1607
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1608 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1609 local f; f = function () <em>body</em> end
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1610 </pre></tt></p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1611
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1612 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1613 not to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1614
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1615 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1616 local f = function () <em>body</em> end
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1617 </pre></tt></p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1618
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1619 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1620 (This only makes a difference when the body of the function
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1621 contains references to <tt>f</tt>.)
371
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1625 A function definition is an executable expression,
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1626 whose value has type <i>function</i>.
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1627 When Luan precompiles a chunk,
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1628 all its function bodies are precompiled too.
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1629 Then, whenever Luan executes the function definition,
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1630 the function is <i>instantiated</i> (or <i>closed</i>).
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1631 This function instance (or <i>closure</i>)
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1632 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1636 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
1637 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
1638
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1639 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1640 parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1641 </pre></tt></p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1642
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1643 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1644 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
1645 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
1646 the length of the list of parameters,
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1647 unless the function is a <i>vararg function</i>,
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1648 which is indicated by three dots ('<tt>...</tt>')
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1649 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
1650 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
1651 instead, it collects all extra arguments and supplies them
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1652 to the function through a <i>vararg expression</i>,
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1653 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
1654 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
1655 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
1656 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
1657 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
1658 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
1659 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
1660 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
1661 (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
1662
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1663
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1664 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1665 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
1666
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1667 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1668 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
1669 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
1670 function r() return 1,2,3 end
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1671 </pre></tt></p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1672
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1673 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1674 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
1675 to the vararg expression:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1676
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1677 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1678 CALL PARAMETERS
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1679
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1680 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
1681 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
1682 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
1683 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
1684 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
1685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1686 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
1687 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
1688 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
1689 g(5, r()) a=5, b=1, ... --&gt; 2 3
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1690 </pre></tt></p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1692 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1693 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
1694 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
1695 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
1696 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
1697
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1698
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1699
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1700
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1701 <h3 margin-top="1em"><a name="visibility">Visibility Rules</a></h3>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1702
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1703 <p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1704 Luan is a lexically scoped language.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1705 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
1706 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
1707 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
1708 Consider the following example:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1709
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1710 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1711 x = 10 -- global variable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1712 do -- new block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1713 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
1714 print(x) --&gt; 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1715 x = x+1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1716 do -- another block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1717 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
1718 print(x) --&gt; 12
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1719 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1720 print(x) --&gt; 11
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1721 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1722 print(x) --&gt; 10 (the global one)
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1723 </pre></tt></p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1724
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1725 <p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1726 Notice that, in a declaration like <tt>local x = x</tt>,
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1727 the new <tt>x</tt> being declared is not in scope yet,
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1728 and so the second <tt>x</tt> refers to the outside variable.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1731 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1732 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
1733 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
1734 defined inside their scope.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1735 A local variable used by an inner function is called
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1736 an <i>upvalue</i>, or <i>external local variable</i>,
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1737 inside the inner function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1738
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1739
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1740 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1741 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
1742 defines new local variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1743 Consider the following example:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1744
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1745 <p><tt><pre>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1746 a = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1747 local x = 20
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1748 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
1749 local y = 0
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1750 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
1751 end
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1752 </pre></tt></p>
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1753
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1754 <p>
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1755 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
1756 (that is, ten instances of the anonymous function).
417
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1757 Each of these closures uses a different <tt>y</tt> variable,
a40e99cf0b0b work on manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 396
diff changeset
1758 while all of them share the same <tt>x</tt>.
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1759
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1762
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1763
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1764 <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
1765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1766 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1767 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
1768 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
1769 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
1770 (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
1771 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
1772 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
1773 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
1774 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
1775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1776
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1777 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1778 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
1779 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
1780 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
1781
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1782 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1783
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1784 <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
1785
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1786 <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
1787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1788 <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
1789
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1790 <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
1791
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1792 <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
1793
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1794 <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
1795
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1796 <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
1797
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1798 <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
1799
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1800 <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
1801
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1802 <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
1803
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1804 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1805 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
1806 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
1807 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
1808
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1809
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1810 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1811 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
1812 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
1813 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
1814 Alternatively,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1815 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
1816 <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
1817 <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
1818 <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
1819 <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
1820 <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
1821 <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
1822 <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
1823 <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
1824 <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
1825 <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
1826 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
1827 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
1828
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1830
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1831 <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
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 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
1835 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
1836 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
1837 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
1838
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1839
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1840 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1841 <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
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 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
1846 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
1847 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
1848 In case of error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1849 <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
1850 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
1851
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1852
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1853
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1854
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1855 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1856 <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
1857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1858
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1859 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1860 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
1861 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
1862
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1863 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1864
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1865 <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
1866 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
1867 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
1868 </li>
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 <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
1871 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
1872 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
1873 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
1874 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1875
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1876 <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
1877 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
1878 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1879
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1880 <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
1881 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
1882 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
1883 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
1884 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
1885 (except for overflows).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1886 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1887
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1888 <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
1889 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
1890 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
1891 With a zero value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1892 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
1893 For non-zero values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1894 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
1895 (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
1896 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
1897 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1899 <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
1900 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
1901 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
1902 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
1903 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1904
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1905 <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
1906 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
1907 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
1908 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
1909 </li>
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 <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
1912 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
1913 (i.e., not stopped).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1914 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1915
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1916 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1917
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1918
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1919
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1920 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1921 <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
1922 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
1923 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1924 <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
1925 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
1926 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
1927 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
1928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1929
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1931
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1932 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1933 <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
1934 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
1935 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
1936 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
1937
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1938
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1939 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1940 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
1941 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
1942 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
1943 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
1944 <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
1945 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
1946 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
1947 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
1948 to the message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1949
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1951
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1952
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1953 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1954 <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
1955 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
1956 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
1957 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
1958 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
1959 nor vice versa.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1960
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1961
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1962
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1964 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1965 <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
1966
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1968 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1969 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
1970 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1971 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
1972 returns the associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1973 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
1974
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1975
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1976
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1978 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1979 <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
1980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1981
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1982 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1983 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
1984 so that the construction
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1985
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1986 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1987 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
1988 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1989 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
1990 (<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
1991 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
1992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1993
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1994
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1995
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1996 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1997 <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
1998
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
1999
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2000 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2001 Loads a chunk.
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 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
2006 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
2007 <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
2008 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
2009 with previous results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2010 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
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 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
2015 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
2016 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
2017
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2020 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
2021 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
2022 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
2023 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
2024 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
2025 (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
2026 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
2027 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
2028 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2029 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
2030 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
2031 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
2032 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
2033
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2034
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2035 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2036 <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
2037 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
2038 When absent,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2039 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
2040 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
2041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2042
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2043 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2044 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
2045 (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
2046 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
2047 "<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
2048 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
2049 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
2050
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2051
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2052 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2053 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
2054 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
2055 the interpreter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2056
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2058
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2059
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2060 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2061 <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
2062
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2063
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2064 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2065 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
2066 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
2067 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
2068 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
2069
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2070
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2071
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2072
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2073 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2074 <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
2075
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2076
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2077 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2078 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
2079 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
2080 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
2081 <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
2082 and its associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2083 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
2084 <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
2085 and its associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2086 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
2087 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
2088 <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
2089 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
2090 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2091 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
2092
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2093
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2094 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2095 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
2096 <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
2097 (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
2098 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
2099
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2100
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2101 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2102 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
2103 during the traversal,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2104 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
2105 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
2106 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
2107
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2110
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2111 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2112 <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
2113
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2115 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2116 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
2117 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
2118 results from the call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2119
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2120
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2121 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2122 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2123 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
2124 so that the construction
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2125
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2126 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2127 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
2128 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2129 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
2130
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2131
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2132 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2133 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
2134 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
2135
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2136
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 <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
2141
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2142
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2143 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2144 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
2145 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
2146 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
2147 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
2148 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
2149 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
2150 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
2151 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
2152 after this first result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2153 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
2154
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2155
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2156
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2157
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2158 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2159 <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
2160 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
2161 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
2162 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
2163 <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
2164 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
2165 for instance for debugging.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2166 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
2167 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
2168
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2169
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2170
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2173 <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
2174 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
2175 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2176 Returns a boolean.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2180
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2181 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2182 <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
2183 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
2184 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2185 <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
2186 <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
2187
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2188
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2189
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2190
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2191 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2192 <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
2193 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
2194 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
2195 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2196 Returns an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2197
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2198
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2199
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2200
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2201 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2202 <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
2203 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
2204 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2205 <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
2206 <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
2207 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
2208
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2210 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2211 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
2212
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2213
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2214
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2215
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2216 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2217 <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
2218
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2219
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2220 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2221 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
2222 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
2223 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
2224 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
2225 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
2226
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2227
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2228
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2229
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2230 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2231 <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
2232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2233
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2234 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2235 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
2236 (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
2237 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
2238 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
2239 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
2240 raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2241
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2242
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2243 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2244 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
2245
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2247
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2248
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2249 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2250 <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
2251
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2252
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2253 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2254 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
2255 <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
2256 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
2257 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
2258 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
2259 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
2260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2261
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2262 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2263 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
2264 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
2265 (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
2266
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2268 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2269 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
2270 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
2271 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
2272 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
2273 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
2274 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
2275 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
2276 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
2277 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
2278
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2279
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2281
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2282 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2283 <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
2284 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
2285 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
2286 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
2287 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
2288 (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
2289 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
2290
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 <p>
429
e3a6d9dbd694 rename __tostring to __to_string
Franklin Schmidt <fschmidt@gmail.com>
parents: 428
diff changeset
2293 If the metatable of <code>v</code> has a <code>"__to_string"</code> field,
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2294 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
2295 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
2296 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
2297
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2298
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2299
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2301 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2302 <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
2303 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
2304 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
2305 "<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
2306 "<code>number</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2307 "<code>string</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2308 "<code>boolean</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2309 "<code>table</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2310 "<code>function</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2311 "<code>thread</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2312 and "<code>userdata</code>".
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2313
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2314
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2315
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2316
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2317 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2318 <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
2319 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
2320 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
2321 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
2322
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2323
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2324
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2325
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2326 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2327 <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
2328
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2330 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2331 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
2332 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
2333
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2334
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2335
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2340 <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
2341
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2342 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2343 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
2344 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
2345 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
2346
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2347
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2348 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2349 <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
2350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2351
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2352 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2353 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
2354 <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
2355 Returns this new coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2356 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
2357
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2358
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2359
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2361 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2362 <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
2363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2364
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2365 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2366 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
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 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
2371 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
2372
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2373
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2374
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2376 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2377 <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
2378
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2379
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2380 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2381 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
2382 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
2383 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
2384 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
2385 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
2386 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
2387 <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
2388 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
2389 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
2390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2391
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2392 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2393 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
2394 <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
2395 (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
2396 (when the coroutine terminates).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2397 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
2398 <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
2399
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2401
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2402
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2403 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2404 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2408 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
2409 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
2410
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2414 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2415 <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
2416
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2419 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
2420 <code>"running"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2421 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
2422 <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
2423 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
2424 <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
2425 (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
2426 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
2427 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
2428
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2429
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2430
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2431
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2432 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2433 <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
2434
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2435
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2436 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2437 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
2438 <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
2439 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
2440 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
2441 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
2442 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
2443 except the first boolean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2444 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
2445
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2446
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2447
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2448
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2449 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2450 <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
2451
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2453 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2454 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
2455 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
2456
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2459
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2460
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2461
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2462
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2463 <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
2464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2465 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2466 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
2467 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
2468 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
2469 <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
2470 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
2471
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2473 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2474 <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
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 Loads the given module.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2479 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
2480 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
2481 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
2482 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
2483 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
2484
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2485
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2486 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2487 To find a loader,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2488 <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
2489 By changing this sequence,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2490 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
2491 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
2492 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
2493
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2494
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2495 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2496 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
2497 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
2498 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
2499 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
2500 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
2501 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
2502 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
2503 If that also fails,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2504 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
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 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
2509 <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
2510 <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
2511 (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
2512 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
2513 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
2514 <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
2515 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
2516 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
2517 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
2518 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
2519 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
2520
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2523 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
2524 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
2525 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
2526
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2527
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2528
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2531 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2535 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
2536 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
2537
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2538 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2539
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2540 <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
2541 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
2542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2543 <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
2544 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
2545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2546 <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
2547 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
2548 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
2549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2550 <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
2551 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
2552 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
2553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2554 <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
2555 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
2556 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
2557
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2558 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2559
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2560
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2561
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2562 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2563 <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
2564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2565
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2566 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2567 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
2568
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2571 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
2572 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
2573 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
2574 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
2575 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
2576
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2577
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2578
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2580 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2581 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2585 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
2586 modules are already loaded.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2587 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
2588 <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
2589 <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
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 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
2594 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
2595 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
2596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2597
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2598
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2599
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2600 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2601 <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
2602
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2603
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2604 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2605 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
2606
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2607
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2608 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2609 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
2610 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
2611 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
2612 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
2613 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2614 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
2615 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
2616 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
2617 (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
2618
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2619
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2620 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2621 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
2622 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
2623 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
2624 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
2625 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
2626 <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
2627 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
2628 <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
2629 (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
2630
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2632 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2633 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
2634 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
2635 (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
2636 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
2637
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2638
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2642 <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
2643
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2644
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2645 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2646 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
2647
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2648
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2649 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2650 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
2651 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
2652 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
2653 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
2654 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
2655 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
2656 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
2657
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2658
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2659
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2660
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2661 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2662 <hr><h3><a name="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
2663
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2664
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2665 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2666 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
2667 (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
2668
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2669
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2670 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2671 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
2672 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
2673 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
2674
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2676
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2677
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2678 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2679 <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
2680
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2681
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2682 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2683 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
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 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
2688 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
2689 <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
2690 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
2691 sole parameter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2692 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
2693 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
2694 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
2695 (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
2696
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2697
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2698 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2699 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
2700
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2703 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
2704 <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
2705
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2706
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2707 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2708 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
2709 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
2710 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
2711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2712
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2713 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2714 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
2715 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
2716 Again,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2717 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
2718 For instance,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2719 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
2720
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2721 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2722 "./?.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
2723 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2724 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
2725 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
2726 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
2727 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
2728 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
2729 application with the library.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2730 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
2731 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
2732 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
2733 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
2734 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
2735 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
2736 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
2737 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
2738 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
2739
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2740
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2741 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2742 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
2743 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
2744 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
2745 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
2746 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
2747 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
2748 the submodule;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2749 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
2750 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
2751 into one single library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2752 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
2753
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2754
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2755 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2756 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
2757 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
2758 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
2759 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
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2763
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2764 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2765 <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
2766
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2767
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2768 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2769 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
2770
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2771
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2772 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2773 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
2774 <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
2775 For each template,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2776 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
2777 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
2778 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
2779 (a dot, by default)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2780 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
2781 (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
2782 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
2783
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2784
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2785 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2786 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
2787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2788 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2789 "./?.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
2790 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2791 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
2792 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
2793 <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
2794 <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
2795
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 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
2799 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
2800 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
2801 (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
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2808
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2809 <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
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 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
2813 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
2814 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
2815 (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
2816 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
2817 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
2818 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
2819
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2820
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2821 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2822 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
2823 <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
2824 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
2825 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
2826 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
2827 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
2828 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
2829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2830
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2831 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2832 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
2833
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2834
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2835 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2836 <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
2837 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
2838 <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
2839 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
2840 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
2841 These indices are corrected
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2842 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
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 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
2847
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2848
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 <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
2853 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
2854 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
2855 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
2856 to its corresponding argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2858
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2859 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2860 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
2861
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2862
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2863
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2864
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2865 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2866 <hr><h3><a name="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
2867
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2868
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2869 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2870 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
2871 (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
2872 of the given function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2873 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
2874 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
2875 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
2876 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
2877 about the function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2878 (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
2879
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2880
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2881 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2882 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
2883 When (re)loaded,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2884 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
2885 (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
2886 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
2887 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
2888
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2889
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2892 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2893 <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
2894
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2895
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2896 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2897 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
2898 <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
2899 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
2900 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
2901 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
2902 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
2903 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
2904 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
2905 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
2906 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
2907 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
2908 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
2909 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
2910
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2911
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2912 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2913 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
2914 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
2915 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
2916 after the two indices.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2919
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2921 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2922 <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
2923
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2924
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2925 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2926 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
2927 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
2928 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
2929 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
2930 <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
2931 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
2932 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
2933 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
2934 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
2935 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
2936 For instance, the call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2937
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2938 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2939 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
2940 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2941 may produce the string:
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 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2944 "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
2945 new line"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2946 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2947
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2948 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2949 Options
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2950 <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
2951 <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
2952 <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
2953 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
2954 <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
2955 expect an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2956 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
2957 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
2958 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
2959 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
2960
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2964 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2965 <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
2966 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
2967 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
2968 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
2969 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
2970 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
2971 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2975 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
2976 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
2977 printing one per line:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2978
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2979 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2980 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
2981 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
2982 print(w)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2983 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2984 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2985 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
2986 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
2987
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2988 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2989 t = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2990 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
2991 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
2992 t[k] = v
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2993 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2994 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2995
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2996 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
2997 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
2998 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
2999
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3001
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3002
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3003 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3004 <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
3005 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
3006 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
3007 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
3008 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
3009 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
3010 <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
3011 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
3012 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
3013
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3015 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3016 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
3017 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
3018 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
3019 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
3020 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
3021 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
3022 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
3023
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3024
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3025 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3026 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
3027 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3031 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
3032 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
3033 in order.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3036 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3037 In any case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3038 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
3039 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3043 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
3044 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
3045 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
3046 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
3047 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
3048 (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
3049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3050
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3051 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3052 Here are some examples:
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 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3055 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
3056 --&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
3057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3058 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
3059 --&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
3060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3061 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
3062 --&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
3063
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3064 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
3065 --&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
3066
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3067 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
3068 return load(s)()
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3069 end)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3070 --&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
3071
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3072 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
3073 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
3074 --&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
3075 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3076
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3077
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3080 <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
3081 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
3082 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
3083 Embedded zeros are counted,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3084 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
3085
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3086
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3087
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3088
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3089 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3090 <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
3091 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
3092 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
3093 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
3094 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3100 <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
3101 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
3102 <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
3103 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
3104 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
3105 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
3106 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
3107 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
3108 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
3109 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
3110 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
3111
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3113
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3115 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3116 <hr><h3><a name="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
3117
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3120 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
3121 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
3122 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
3123
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3124
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3125
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3128 <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
3129
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3130
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3131 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3132 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
3133 with the given format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3134 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
3135 '<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
3136
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3137
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3138
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3139
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3140 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3141 <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
3142 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
3143 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
3144 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
3145 (that is, no separator).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3146 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
3147
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3148
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3149
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3151 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3152 <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
3153 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
3154
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3155
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3159 <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
3160 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
3161 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
3162 <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
3163 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
3164 (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
3165 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3166 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
3167 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
3168 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
3169 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3173 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
3174 <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
3175 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
3176 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
3177 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
3178 If, after these corrections,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3179 <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
3180 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
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 <p>
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="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
3187
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3188
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3189 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3190 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
3191 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
3192 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
3193 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
3194 After the read values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3195 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
3196
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3197
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3198
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3199
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3200 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3201 <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
3202 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
3203 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
3204 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
3205 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
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3211 <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
3212
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3213 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3214 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
3215 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
3216 <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
3217 <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
3218 <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
3219 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
3220 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
3221 (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
3222
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3223
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3224
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3225 <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
3226 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
3227 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
3228
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3229 <ul>
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 <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
3232 (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
3233 <code>^$()%.[]*+-?</code>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3234 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
3235 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3236
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3237 <li><b><code>.</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
3238
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3239 <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
3240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3241 <li><b><code>%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
3242
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3243 <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
3244
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3245 <li><b><code>%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
3246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3247 <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
3248
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3249 <li><b><code>%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
3250
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3251 <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
3252
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3253 <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
3254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3255 <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
3256
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3257 <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
3258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3259 <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
3260 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
3261 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
3262 Any non-alphanumeric character
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3263 (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
3264 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
3265 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
3266 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3268 <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
3269 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
3270 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
3271 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
3272 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
3273 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
3274 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
3275 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
3276 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
3277 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
3278 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
3279 <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
3280 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
3281 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3285 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
3286 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
3287 have no meaning.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3288 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3289
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3290 <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
3291 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
3292 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
3293 </li>
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 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3296 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
3297 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
3298 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
3299
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 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
3303 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
3304 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
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3310 <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
3311 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
3312
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3313 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3314
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3315 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3316 a single character class,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3317 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
3318 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3321 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
3322 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
3323 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
3324 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3325
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3326 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3327 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
3328 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
3329 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
3330 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3333 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
3334 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
3335 Unlike '<code>*</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3336 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
3337 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3339 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3340 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
3341 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
3342 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
3343 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3346 <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
3347 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
3348 (see below);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3349 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3351 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3352 <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
3353 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
3354 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
3355 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
3356 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
3357 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
3358 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
3359 balanced parentheses.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3360 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3361
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3362 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3363 <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
3364 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
3365 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
3366 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
3367 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
3368 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
3369 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
3370 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3372 </ul>
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3376
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3377 <h4>Pattern:</h4><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3378 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
3379 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
3380 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
3381 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
3382 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
3383 At other positions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3384 '<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
3385
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3388
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3389
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3390 <h4>Captures:</h4><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3391 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
3392 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
3393 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
3394 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
3395 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
3396 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
3397 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
3398 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
3399 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
3400 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
3401
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3404 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
3405 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
3406 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
3407 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
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3414
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3415 <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
3416
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3417 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3418 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
3419 <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
3420 is a format string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3421 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
3422
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3423
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3424 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3425 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
3426 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
3427
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3428 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3429 <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
3430 <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
3431 <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
3432 <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
3433 (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
3434 <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
3435 <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
3436 <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
3437 <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
3438 <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
3439 <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
3440 <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
3441 <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
3442 <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
3443 <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
3444 (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
3445 <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
3446 (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
3447 <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
3448 <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
3449 <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
3450 <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
3451 <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
3452 <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
3453 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
3454 (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
3455 <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
3456 <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
3457 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
3458 (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
3459 <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
3460 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3461 (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
3462 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
3463 (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
3464 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
3465 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
3466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3467
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3468 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3469 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
3470 <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
3471 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
3472 <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
3473 <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
3474
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3475
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3476 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3477 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
3478 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3479 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
3480 and native endianness.
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3484 Alignment works as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3485 For each option,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3486 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
3487 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
3488 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
3489 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
3490 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
3491 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
3492
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3493
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3494 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3495 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
3496 (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
3497
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3498
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3502
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3503
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3504 <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
3505
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3506 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3507 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
3508 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
3509 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
3510 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
3511 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
3512 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
3513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3514
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3515 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3516 Unless stated otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3517 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
3518 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
3519 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
3520 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
3521 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
3522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3523
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3524 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3525 <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
3526 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
3527 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
3528 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
3529
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3530
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3531
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3532
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3533 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3534 <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
3535 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
3536 (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
3537 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
3538 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
3539
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3540
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3543 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3544 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3548 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
3549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3550 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3551 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
3552 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3553 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
3554 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
3555 of each character.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3556 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
3557
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3558
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3559
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3560
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3561 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3562 <hr><h3><a name="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
3563 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
3564 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
3565 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
3566 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
3567
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3568
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3569
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3570
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3571 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3572 <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
3573 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
3574 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
3575 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
3576 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
3577 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
3578
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3582 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3583 <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
3584 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
3585 <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
3586 (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
3587 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
3588 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
3589 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
3590 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
3591 <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
3592 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
3593 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
3594 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
3595
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3597 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3598 As a special case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3599 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
3600 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
3601
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3604 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
3605
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3606
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3607
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3608
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3611
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3612 <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
3613
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3614 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3615 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
3616 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
3617
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3618
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3619 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3620 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
3621 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
3622 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
3623 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
3624 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
3625
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3626
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3627 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3628 <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
3629
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3630
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3631 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3632 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
3633 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
3634 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
3635 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
3636 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
3637 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
3638
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 <p>
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="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
3644
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3645
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3646 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3647 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
3648 shifting up the elements
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3649 <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
3650 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
3651 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
3652 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
3653
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3654
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3658 <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
3659
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3660
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3661 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3662 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
3663 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
3664 multiple assignment:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3665 <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
3666 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
3667 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
3668 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
3669
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3670
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3671
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3672
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3673 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3674 <hr><h3><a name="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
3675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3676
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3677 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3678 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
3679 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
3680 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
3681
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3682
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3683
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3684
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3685 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3686 <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
3687
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3690 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
3691 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
3692 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
3693 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
3694 <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
3695 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
3696 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
3697 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
3698 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
3699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3700
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3701 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3702 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
3703 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
3704 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
3705
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3706
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3707
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 <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
3711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3712
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3713 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3714 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
3715 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
3716 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
3717 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
3718 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
3719 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
3720 (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
3721 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
3722 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
3723
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3724
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3725 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3726 The 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
3727 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
3728 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
3729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3731
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3732
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3733 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3734 <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
3735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3736
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3737 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3738 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
3739 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
3740
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3741 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3742 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
3743 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3744 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
3745
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3747
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3748
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3749
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3750
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 <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
3753
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3754 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3755 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
3756 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
3757 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
3758 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
3759 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
3760 Rounding functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3761 (<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
3762 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
3763 or a float otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3764
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3766 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3767 <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
3768
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3770 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3771 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
3772
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3773
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3776 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3777 <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
3778
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3781 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
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3786 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3787 <hr><h3><a name="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
3788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3789
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3790 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3791 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3797 <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
3798
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3802 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
3803 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
3804 quadrant of the result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3805 (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
3806
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3808 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3809 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
3810 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
3811 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
3812
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3816 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3817 <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
3818
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3819
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3820 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3821 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
3822
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3826 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3827 <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
3828
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3830 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3831 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
3832
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3833
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3834
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3835
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3836 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3837 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3841 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
3842
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3843
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3846 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3847 <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
3848
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3849
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3850 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3851 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
3852 (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
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3856
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3857 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3858 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3862 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
3863
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3864
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3867 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3868 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3872 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
3873 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
3874
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3875
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3876
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3877
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3878 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3879 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3883 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
3884 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
3885
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3886
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3887
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3888
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3889 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3890 <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
3891
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3892
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3893 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3894 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
3895 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
3896 (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
3897
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3901 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3902 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3906 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
3907 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
3908
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3909
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3912 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3913 <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
3914 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3920 <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
3921
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 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
3925 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
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 <p>
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="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
3932 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
3933
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3934
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3935
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 <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
3939
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3942 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
3943 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
3944
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3946
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3947
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3948 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3949 <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
3950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3951
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3952 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3953 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
3954
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3959 <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
3960
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3961
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3962 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3963 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
3964
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3965
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3966
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3969 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3973 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3974 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
3975 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
3976 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
3977 <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
3978 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
3979 (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
3980 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
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 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
3985 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
3986 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
3987
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3988
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3989
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3990
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3991 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3992 <hr><h3><a name="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
3993
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3994
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3995 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
3996 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
3997 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
3998 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
3999
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4003 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4004 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4008 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
4009
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4011
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 <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
4015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4017 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4018 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
4019 (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
4020
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4021
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4022
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4025 <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
4026
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4027
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4028 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4029 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
4030
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4032
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4035 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4039 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
4040 returns that integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4041 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
4042
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4043
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4044
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4045
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4046 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4047 <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
4048
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4050 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4051 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
4052 "<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
4053 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
4054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4055
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4056
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4058 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4059 <hr><h3><a name="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
4060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4062 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4063 Returns a boolean,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4064 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
4065 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
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4069
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4070
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4071
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 <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
4074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4075 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4076 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
4077 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
4078 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
4079 default output file,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4080 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
4081 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
4082
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4083
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4084 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4085 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
4086 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
4087 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
4088 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
4089 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
4090
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4091
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4092 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4093 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
4094 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
4095 <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
4096 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4100 Unless otherwise stated,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4101 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
4102 (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
4103 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
4104 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
4105 On non-POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4106 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
4107 in case of errors
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4108 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
4109 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
4110
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4113 <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
4114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4115
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4116 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4117 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
4118 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
4119
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4120
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4121
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4122
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4123 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4124 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4128 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
4129
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4130
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4131
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 <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
4135
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4136
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4137 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4138 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
4139 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
4140 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
4141 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
4142 When called without parameters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4143 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
4144
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4145
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4146 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4147 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
4148 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
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4152
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4153 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4154 <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
4155
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4156
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4157 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4158 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
4159 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
4160 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
4161 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
4162 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
4163
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4165 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4166 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
4167 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
4168 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
4169 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
4170
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4172 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4173 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
4174 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
4175
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4178
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4179 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4180 <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
4181
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4182
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4183 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4184 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
4185 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
4186 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
4187 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4191 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
4192
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4193 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4194 <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
4195 <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
4196 <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
4197 <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
4198 <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
4199 <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
4200 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
4201 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4202 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
4203 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
4204
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4206
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4207
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4208 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4209 <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
4210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4212 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4213 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4219 <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
4220
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4221
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4222 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4223 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
4224 on all platforms.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4225
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4228 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
4229 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
4230 (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
4231 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
4232 (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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4238 <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
4239
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 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
4243
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4244
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4245
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4247 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4248 <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
4249
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4250
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4251 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4252 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
4253 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
4254 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
4255
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4256
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4257
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4259 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4260 <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
4261
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4262
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4263 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4264 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
4265 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
4266 <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
4267 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
4268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4270
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4271
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 <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
4274
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4277 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
4278
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4279
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4281
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4282 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4283 <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
4284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4285
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4286 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4287 Closes <code>file</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4288 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
4289 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
4290 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
4291
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4293 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4294 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
4295 <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
4296 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
4297
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4298
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4299
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4301 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4302 <hr><h3><a name="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
4303
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4305 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4306 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
4307
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4310
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4311 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4312 <hr><h3><a name="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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4316 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
4317 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
4318 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
4319 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
4320 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
4321 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
4322
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4323 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4324 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
4325 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4326 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
4327 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
4328 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
4329 when the loop ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4330
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4332 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4333 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
4334 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
4335
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4339 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4340 <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
4341
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4344 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
4345 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
4346 For each format,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4347 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
4348 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
4349 (In this latter case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4350 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
4351 When called without formats,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4352 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
4353 (see below).
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4356 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4357 The available formats are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4358
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4359 <ul>
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 <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
4362 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
4363 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
4364 (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
4365 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
4366 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
4367 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
4368 (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
4369 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
4370 </li>
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 <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
4373 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
4374 </li>
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 <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
4377 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
4378 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
4379 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4380
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4381 <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
4382 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
4383 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
4384 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
4385 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4387 <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
4388 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
4389 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
4390 </li>
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 <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
4393 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
4394 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
4395 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
4396 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
4397 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
4398 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4399
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4400 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4401 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
4402
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4403
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4404
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4405
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4406 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4407 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4411 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
4412 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
4413 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
4414 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
4415
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4416 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4417 <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
4418 <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
4419 <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
4420 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4421 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
4422 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
4423 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
4424 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
4425
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4426
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4427 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4428 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
4429 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
4430 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
4431 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
4432 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
4433 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
4434 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
4435 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
4436
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4438
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4439
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4440 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4441 <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
4442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4443
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4444 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4445 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
4446 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
4447
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4448 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4449
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4450 <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
4451 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
4452 </li>
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 <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
4455 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
4456 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
4457 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
4458 </li>
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 <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
4461 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
4462 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
4463 (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
4464 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4466 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4467 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
4468 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
4469 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
4470
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4474 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4475 <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
4476
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4477
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4478 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4479 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
4480 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
4481
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4482
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4483 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4484 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
4485 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
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4491
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4492
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4493 <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
4494
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4495 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4496 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4500 <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
4501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4502
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4503 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4504 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
4505 used by the program.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4506
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4507
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4508
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4509
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4510 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4511 <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
4512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4514 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4515 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
4516 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4520 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
4521 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
4522 (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
4523 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
4524
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 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
4528 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
4529 After this optional character,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4530 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
4531 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
4532 <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
4533 <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
4534 <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
4535 <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
4536 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
4537 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
4538 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4542 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
4543 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
4544 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
4545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4546
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4547 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4548 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4549 <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
4550 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
4551 (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
4552
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4554 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4555 On non-POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4556 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
4557 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
4558
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4559
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4560
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4561
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4562 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4563 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4567 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
4568 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
4569 (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
4570 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
4571 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
4572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4573
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4574
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4575
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4576 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4577 <hr><h3><a name="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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4581 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
4582 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
4583 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
4584 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
4585 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
4586 After this first result
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4587 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
4588 as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4589
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4590 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4591
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4592 <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
4593 the command terminated normally;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4594 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
4595 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4597 <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
4598 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
4599 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
4600 </li>
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 </ul>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4605 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
4606 <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
4607
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4608
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4611 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4612 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4616 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
4617 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
4618 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
4619 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
4620 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
4621 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
4622 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
4623 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4627 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
4628 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
4629
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4630
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4632
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4633 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4634 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4638 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
4639 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
4640
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4641
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4642
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 <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
4646
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4647
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4648 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4649 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
4650 with the given name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4651 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
4652 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
4653
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4654
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4655
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4656
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4657 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4658 <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
4659
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 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
4663 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
4664 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
4665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4667
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4670 <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
4671
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4672
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4673 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4674 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
4675 <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
4676 <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
4677 <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
4678 <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
4679 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
4680 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
4681 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
4682
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4683
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4684 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4685 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
4686 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
4687 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
4688 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
4689
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4690
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4691 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4692 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
4693 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
4694 for the given category.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4695
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4696
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4697 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4698 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
4699 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
4700
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4701
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4702
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4703
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4704 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4705 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4709 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
4710 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
4711 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
4712 and may have fields
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4713 <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
4714 <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
4715 <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
4716 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
4717 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
4718
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4719
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4720 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4721 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
4722 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
4723 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
4724 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
4725 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
4726 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
4727 <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
4728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4731
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4732 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4733 <hr><h3><a name="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
4734
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4736 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4737 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
4738 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
4739 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
4740 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
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 On POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4745 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
4746 to avoid security risks.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4747 (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
4748 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
4749 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
4750 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
4751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4752
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4753 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4754 When possible,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4755 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
4756 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
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4762
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4763
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4764 <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
4765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4766 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4767 This library provides
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4768 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
4769 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
4770 Several of its functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4771 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
4772 (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
4773 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
4774 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
4775 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
4776 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
4777 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
4778
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4779
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4780 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4781 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
4782 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
4783 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
4784 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
4785 thread to operate over.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4786 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
4787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4789 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4790 <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
4791
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4792
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4793 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4794 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
4795 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
4796 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
4797 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
4798 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
4799 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
4800 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
4801
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4802
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4803 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4804 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
4805 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
4806
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4808
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4811 <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
4812
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4815 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
4816 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
4817 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
4818 (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
4819
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4820
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4821
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4822
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4823 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4824 <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
4825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4826
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4827 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4828 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
4829 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
4830 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
4831 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
4832 of the given thread:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4833 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
4834 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
4835 (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
4836 and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4837 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
4838 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
4839
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4840
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4841 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4842 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
4843 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
4844 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
4845 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
4846 If present,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4847 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
4848 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
4849 If present,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4850 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
4851 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
4852 valid lines.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4853
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4854
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4855 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4856 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
4857 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
4858 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
4859 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
4860 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
4861 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
4862
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4865
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4866 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4867 <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
4868
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4870 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4871 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
4872 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
4873 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
4874 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
4875
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4876
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4877 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4878 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
4879 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
4880 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
4881 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
4882 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
4883 -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
4884 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
4885 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
4886 (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
4887
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4888
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4889 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4890 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
4891 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
4892 (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
4893 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4897 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
4898 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
4899
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4902
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4903 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4904 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4908 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
4909 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
4910
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4913
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4914 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4915 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4919 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
4920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4921
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4922
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4923
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4924 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4925 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4929 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
4930 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
4931 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
4932
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 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
4936 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
4937 (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
4938
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4939
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4940
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4941
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4942 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4943 <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
4944
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4946 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4947 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
4948 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
4949 returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4951
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4954 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4955 <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
4956
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4957
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4958 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4959 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
4960 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
4961 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
4962 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
4963 with the given meaning:
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 <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
4967 <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
4968 <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
4969 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4970 Moreover,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4971 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
4972 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
4973
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4976 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4977 <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
4978
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4979
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4980 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4981 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
4982 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
4983 <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
4984 <code>"return"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4985 <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
4986 For line events,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4987 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
4988 Inside a hook,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4989 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
4990 the running function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4991 (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
4992 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
4993
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4994
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4995
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
4998 <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
4999
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5001 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5002 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
5003 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
5004 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
5005 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
5006 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
5007 (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
5008 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5012 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
5013 variable indices and names.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5017
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5018 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5019 <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
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 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
5024 (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
5025 Returns <code>value</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5026
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5027
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5028
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5029
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5030 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5031 <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
5032
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5033
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5034 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5035 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
5036 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
5037 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
5038 with the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5039 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
5040
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5042
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5045 <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
5046
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5047
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5048 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5049 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
5050 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
5051 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5055 Returns <code>udata</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5056
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5059
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5060 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5061 <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
5062
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5063
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5064 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5065 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
5066 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
5067 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5068 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
5069 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
5070 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
5071 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
5072 to start the traceback
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5073 (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
5074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5075
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5076
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5077
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5078 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5079 <hr><h3><a name="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
5080
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5081
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5082 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5083 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
5084 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
5085 from the given function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5086
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5087
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5088 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5089 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
5090 closures share upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5091 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
5092 (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
5093 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
5094
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5095
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5096
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5097
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5098 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5099 <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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5103 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
5104 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
5105
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5106
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5107
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5110
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5111
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5112 <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
5113
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5114 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5115 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
5116 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
5117 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
5118 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
5119 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
5120 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
5121 The standalone interpreter includes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5122 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
5123 Its usage is:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5124
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5125 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5126 lua [options] [script [args]]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5127 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5128 The options are:
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 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5131 <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
5132 <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
5133 <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
5134 <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
5135 <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
5136 <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
5137 <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
5138 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5139 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
5140 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5141 <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
5142 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
5143 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
5144
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5145
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5146 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5147 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
5148 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
5149 (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
5150 before running any argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5151 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
5152 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
5153 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
5154
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5155
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5156 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5157 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
5158 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
5159 Lua also ignores
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5160 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
5161 setting the values of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5162 <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
5163 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
5164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5166 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5167 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
5168 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
5169
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5170 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5171 $ 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
5172 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5173 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
5174 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
5175 (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
5176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5178 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5179 Before running any code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5180 <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
5181 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
5182 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
5183 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
5184 and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5185 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
5186 (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
5187 go to negative indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5188 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
5189
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5190 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5191 $ 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
5192 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5193 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
5194
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5195 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5196 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
5197 [0] = "b.lua",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5198 [1] = "t1", [2] = "t2" }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5199 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5200 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
5201 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
5202 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
5203 For instance, the call
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 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5206 $ 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
5207 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5208 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
5209 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
5210 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
5211 <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
5212 (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
5213 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
5214
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5215
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5216 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5217 In interactive mode,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5218 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
5219 After reading a line,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5220 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
5221 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
5222 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
5223 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
5224 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
5225 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5229 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
5230 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
5231 If the error object is not a string but
429
e3a6d9dbd694 rename __tostring to __to_string
Franklin Schmidt <fschmidt@gmail.com>
parents: 428
diff changeset
5232 has a metamethod <code>__to_string</code>,
371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5233 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
5234 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
5235 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
5236
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5237
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5238 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5239 When finishing normally,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5240 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
5241 (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
5242 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
5243 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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5247 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
5248 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
5249 the standalone interpreter skips
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5250 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
5251 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
5252 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
5253 as in
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5255 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5256 #!/usr/local/bin/lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5257 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5258 (Of course,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5259 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
5260 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
5261 then
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5262
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5263 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5264 #!/usr/bin/env lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5265 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5266 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
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 <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
5271
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5272 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5273 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
5274 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
5275 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
5276 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
5277 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5278 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
5279
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5282 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
5283 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
5284 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
5285 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
5286 Therefore,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5287 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
5288 different Lua versions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5289 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
5290 using a new version.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5291
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5293 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5294 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
5295 of precompiled chunks;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5296 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
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 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
5301 change between versions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5302
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 <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
5306 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5307
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5308 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5309 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
5310 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
5311 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
5312 some computations
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5313 (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
5314 can give different results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5315
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5316
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5317 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5318 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
5319 (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
5320 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
5321 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
5322 (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
5323 for an occasional incompatibility;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5324 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
5325 For good programming,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5326 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
5327 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
5328 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5330 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5331 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
5332 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
5333 (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
5334 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
5335 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
5336 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
5337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5339 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5340 (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
5341 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
5342 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
5343 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5344
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5345 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5346 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
5347 (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
5348 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5349
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5350 </ul>
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 <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
5356 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5357
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5358 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5359 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
5360 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
5361 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
5362 (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
5363 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
5364 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5367 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
5368 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
5369 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5370
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5371 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5372 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
5373 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
5374 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5376 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5377 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
5378 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
5379 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5382 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
5383 <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
5384 <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
5385 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
5386 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
5387 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
5388 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
5389 For the other operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5390 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
5391 implement them in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5392 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5395 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
5396 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
5397 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
5398 (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
5399 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
5400 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
5401 (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
5402 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
5403 </li>
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 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5406
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5407
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5408
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5409
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5410 <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
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 <ul>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5416 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
5417 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
5418 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
5419 Adapt your code accordingly.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5420 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5423 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
5424 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
5425 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5428 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
5429 (<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
5430 <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
5431 were deprecated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5432 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
5433 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5434
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5435 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5436 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
5437 (<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
5438 were deprecated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5439 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
5440 (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
5441 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5443 </ul>
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 <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
5449
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5450 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5451 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
5452 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
5453 {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
5454 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
5455 (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
5456 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
5457 Name, Numeral,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5458 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
5459
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5460
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5463 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5465 chunk ::= block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5467 block ::= {stat} [retstat]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5468
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5469 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
5470 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
5471 functioncall |
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5472 label |
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5473 <b>break</b> |
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5474 <b>goto</b> Name |
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5475 <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
5476 <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
5477 <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
5478 <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
5479 <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
5480 <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
5481 <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
5482 <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
5483 <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
5484
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5485 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
5486
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5487 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
5488
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5489 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
5490
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5491 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
5492
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5493 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
5494
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5495 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
5496
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5497 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
5498
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5499 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
5500 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
5501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5502 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
5503
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5504 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
5505
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5506 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
5507
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5508 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
5509
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5510 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
5511
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5512 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
5513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5514 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
5515
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5516 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
5517
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5518 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
5519
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5520 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
5521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5522 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
5523 &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
5524 &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
5525 <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
5526
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5527 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
5528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5529 </pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5532
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5534
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5535
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5538
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5539
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5540 <HR>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5541 <SMALL CLASS="footer">
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5542 Last update:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5543 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
5544 </SMALL>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5545 <!--
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5546 Last change: minor edit
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5547 -->
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual
Franklin Schmidt <fschmidt@gmail.com>
parents:
diff changeset
5548
372
f08cefa4594c start editing manual
Franklin Schmidt <fschmidt@gmail.com>
parents: 371
diff changeset
5549 </div>
386
db23f654f87d make all of website use luan
Franklin Schmidt <fschmidt@gmail.com>
parents: 382
diff changeset
5550
391
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom
Franklin Schmidt <fschmidt@gmail.com>
parents: 389
diff changeset
5551 <% Html.simply_html_body_bottom() %>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom
Franklin Schmidt <fschmidt@gmail.com>
parents: 389
diff changeset
5552 </body>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom
Franklin Schmidt <fschmidt@gmail.com>
parents: 389
diff changeset
5553 </html>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom
Franklin Schmidt <fschmidt@gmail.com>
parents: 389
diff changeset
5554 <%
386
db23f654f87d make all of website use luan
Franklin Schmidt <fschmidt@gmail.com>
parents: 382
diff changeset
5555 end