Mercurial Hosting > luan

comparison website/src/manual.html.luan @ 1670:0046c5eb3315

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
update manual.html
author Franklin Schmidt <fschmidt@gmail.com>
date Tue, 10 May 2022 17:08:50 -0600
parents website/src/m.html.luan@fdeb1879fe02
children 9ef19f5ea973
comparison
equal deleted inserted replaced
1669:fdeb1879fe02 1670:0046c5eb3315
3 local Io = require "luan:Io.luan" 3 local Io = require "luan:Io.luan"
4 local Http = require "luan:http/Http.luan" 4 local Http = require "luan:http/Http.luan"
5 local Shared = require "site:/lib/Shared.luan" 5 local Shared = require "site:/lib/Shared.luan"
6 local head = Shared.head or error() 6 local head = Shared.head or error()
7 local docs_header = Shared.docs_header or error() 7 local docs_header = Shared.docs_header or error()
8 8 local show_toc = Shared.show_toc or error()
9 9 local show_content = Shared.show_content or error()
10 return function() 10
11 Io.stdout = Http.response.text_writer() 11
12 %> 12 local content = {
13 <!doctype html> 13 intro = {
14 <html> 14 title = "Introduction"
15 <head> 15 content = function()
16 <% head() %> 16 %>
17 <title>Luan Reference Manual</title> 17 <p>
18 <style> 18 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.
19 div[contents] { 19 </p>
20 margin-bottom: 1em; 20
21 } 21 <p>
22 ul { 22 Luan is implemented in Java and is tightly coupled with Java. So it makes a great scripting language for Java programmers.
23 margin: 0; 23 </p>
24 } 24
25 [heading] { 25 <p>
26 margin-top: 2em; 26 Unlike Lua which is meant to be embedded, Luan is meant to be a full scripting language. This done not by adding features to Luan, but rather by providing a complete set of libraries.
27 } 27 </p>
28 p[keywords] { 28 <%
29 font-family: monospace; 29 end
30 margin-left: 40px; 30 }
31 max-width: 700px; 31 basic = {
32 } 32 title = "Basic Concepts"
33 p[keywords] span { 33 content = function()
34 display: inline-block; 34 %>
35 width: 100px; 35 <p>
36 } 36 This section describes the basic concepts of the language.
37 </style> 37 </p>
38 </head> 38 <%
39 <body> 39 end
40 <% docs_header() %> 40 subs = {
41 <div content> 41 types = {
42 42 title = "Values and Types"
43 <h1><a href="manual.html">Luan Reference Manual</a></h1> 43 content = function()
44 44 %>
45 <p small>
46 Original copyright &copy; 2015 Lua.org, PUC-Rio.
47 Freely available under the terms of the
48 <a href="http://www.lua.org/license.html">Lua license</a>.
49 Modified for Luan.
50 </p>
51
52 <hr/>
53
54 <h2>Contents</h2>
55
56 <div contents><a href="#intro">Introduction</a></div>
57
58 <div contents>
59 <a href="#basic">Basic Concepts</a>
60 <ul>
61 <li><a href="#types">Values and Types</a></li>
62 <li><a href="#env">Environments</a></li>
63 <li><a href="#error">Error Handling</a></li>
64 <li><a href="#meta">Metatables and Metamethods</a></li>
65 <li><a href="#gc">Garbage Collection</a></li>
66 </ul>
67 </div>
68
69 <div contents>
70 <a href="#lang">The Language</a>
71 <ul>
72 <li><a href="#lex">Lexical Conventions</a></li>
73 <li><a href="#vars">Variables</a></li>
74 <li>
75 <a href="#stmts">Statements</a>
76 <ul>
77 <li><a href="#blocks">Blocks</a></li>
78 <li><a href="#chunks">Chunks</a></li>
79 <li><a href="#assignment">Assignment</a></li>
80 <li><a href="#control">Control Structures</a></li>
81 <li><a href="#for">For Statement</a></li>
82 <li><a href="#try">Try Statement</a></li>
83 <li><a href="#fn_stmt">Function Calls as Statements</a></li>
84 <li><a href="#local_stmt">Local Declarations</a></li>
85 <li><a href="#template_stmt">Template Statements</a></li>
86 </ul>
87 </li>
88 <li>
89 <a href="#expressions">Expressions</a>
90 <ul>
91 <li><a href="#arithmetic">Arithmetic Operators</a></li>
92 <li><a href="#conversions">Coercions and Conversions</a></li>
93 <li><a href="#relational">Relational Operators</a></li>
94 <li><a href="#logical_ops">Logical Operators</a></li>
95 <li><a href="#concatenation">Concatenation</a></li>
96 <li><a href="#length">The Length Operator</a></li>
97 <li><a href="#precedence">Precedence</a></li>
98 <li><a href="#constructors">Table Constructors</a></li>
99 <li><a href="#fn_calls">Function Calls</a></li>
100 <li><a href="#fn_def">Function Definitions</a></li>
101 </ul>
102 </li>
103 <li><a href="#visibility">Visibility Rules</a></li>
104 </ul>
105 </div>
106
107 <div contents>
108 <a href="#libs">Standard Libraries</a>
109 <ul>
110 <li><a href="#default_lib">Default Environment</a></li>
111 <li><a href="#luan_lib">Basic Functions</a></li>
112 <li><a href="#package_lib">Modules</a></li>
113 <li><a href="#string_lib">String Manipulation</a></li>
114 <li><a href="#binary_lib">Binary Manipulation</a></li>
115 <li><a href="#table_lib">Table Manipulation</a></li>
116 <li><a href="#number_lib">Number Manipulation</a></li>
117 <li><a href="#math_lib">Mathematical Functions</a></li>
118 </ul>
119 </div>
120
121 <hr/>
122
123
124 <h2 heading><a name="intro" href="#intro">Introduction</a></h2>
125
126 <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>
127
128 <p>Luan is implemented in Java and is tightly coupled with Java. So it makes a great scripting language for Java programmers.</p>
129
130 <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>
131
132
133 <h2 heading><a name="basic" href="#basic">Basic Concepts</a></h2>
134
135 <p>This section describes the basic concepts of the language.</p>
136
137 <h3 heading><a name="types" href="#types">Values and Types</a></h3>
138
139 <p> 45 <p>
140 Luan is a <em>dynamically typed language</em>. 46 Luan is a <em>dynamically typed language</em>.
141 This means that 47 This means that
142 variables do not have types; only values do. 48 variables do not have types; only values do.
143 There are no type definitions in the language. 49 There are no type definitions in the language.
144 All values carry their own type. 50 All values carry their own type.
145 51 </p>
146 52
147 <p> 53 <p>
148 All values in Luan are <em>first-class values</em>. 54 All values in Luan are <em>first-class values</em>.
149 This means that all values can be stored in variables, 55 This means that all values can be stored in variables,
150 passed as arguments to other functions, and returned as results. 56 passed as arguments to other functions, and returned as results.
151 57 </p>
152 58
153 <p> 59 <p>
154 There are eight basic types in Luan: 60 There are eight basic types in Luan:
155 <em>nil</em>, <em>boolean</em>, <em>number</em>, 61 <em>nil</em>, <em>boolean</em>, <em>number</em>,
156 <em>string</em>, <em>binary</em>, <em>function</em>, <em>java</em>, 62 <em>string</em>, <em>binary</em>, <em>function</em>, <em>java</em>,
163 <em>Boolean</em> is implemented as the Java class <em>Boolean</em>. 69 <em>Boolean</em> is implemented as the Java class <em>Boolean</em>.
164 <em>Number</em> represents both 70 <em>Number</em> represents both
165 integer numbers and real (floating-point) numbers. 71 integer numbers and real (floating-point) numbers.
166 <em>Number</em> is implemented as the Java class <em>Number</em>. Any Java subclass of <em>Number</em> is allowed and this is invisible to the Luan user. Operations on numbers follow the same rules of 72 <em>Number</em> is implemented as the Java class <em>Number</em>. Any Java subclass of <em>Number</em> is allowed and this is invisible to the Luan user. Operations on numbers follow the same rules of
167 the underlying Java implementation. 73 the underlying Java implementation.
168
169 <em>String</em> is implemented as the Java class <em>String</em>. 74 <em>String</em> is implemented as the Java class <em>String</em>.
170 <em>Binary</em> is implemented as the Java type <em>byte[]</em>. 75 <em>Binary</em> is implemented as the Java type <em>byte[]</em>.
171 76 </p>
172 77
173 <p> 78 <p>
174 Luan can call (and manipulate) functions written in Luan and 79 Luan can call (and manipulate) functions written in Luan and
175 functions written in Java (see <a href="#fn_calls">Function Calls</a>). 80 functions written in Java (see <a href="#fn_calls">Function Calls</a>).
176 Both are represented by the type <em>function</em>. 81 Both are represented by the type <em>function</em>.
177 82 </p>
178 83
179 <p> 84 <p>
180 The type <em>java</em> is provided to allow arbitrary Java objects to 85 The type <em>java</em> is provided to allow arbitrary Java objects to
181 be stored in Luan variables. 86 be stored in Luan variables.
182 A <em>java</em> value is a Java object that isn't one of the standard Luan types. 87 A <em>java</em> value is a Java object that isn't one of the standard Luan types.
183 Java values have no predefined operations in Luan, 88 Java values have no predefined operations in Luan,
184 except assignment and identity test. 89 except assignment and identity test.
185 Java values are useful when Java access is enabled in Luan 90 Java values are useful when Java access is enabled in Luan.
186 91 </p>
187
188 92
189 <p> 93 <p>
190 The type <em>table</em> implements associative arrays, 94 The type <em>table</em> implements associative arrays,
191 that is, arrays that can be indexed not only with numbers, 95 that is, arrays that can be indexed not only with numbers,
192 but with any Luan value except <b>nil</b>. 96 but with any Luan value except <b>nil</b>.
193 Tables can be <em>heterogeneous</em>; 97 Tables can be <em>heterogeneous</em>;
194 that is, they can contain values of all types (except <b>nil</b>). 98 that is, they can contain values of all types (except <b>nil</b>).
195 Any key with value <b>nil</b> is not considered part of the table. 99 Any key with value <b>nil</b> is not considered part of the table.
196 Conversely, any key that is not part of a table has 100 Conversely, any key that is not part of a table has
197 an associated value <b>nil</b>. 101 an associated value <b>nil</b>.
198 102 </p>
199 103
200 <p> 104 <p>
201 Tables are the sole data-structuring mechanism in Luan; 105 Tables are the sole data-structuring mechanism in Luan;
202 they can be used to represent ordinary arrays, sequences, 106 they can be used to represent ordinary arrays, sequences,
203 symbol tables, sets, records, graphs, trees, etc. 107 symbol tables, sets, records, graphs, trees, etc.
204 To represent records, Luan uses the field name as an index. 108 To represent records, Luan uses the field name as an index.
205 The language supports this representation by 109 The language supports this representation by
206 providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. 110 providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>.
207 There are several convenient ways to create tables in Luan 111 There are several convenient ways to create tables in Luan
208 (see <a href="#constructors">Table Constructors</a>). 112 (see <a href="#constructors">Table Constructors</a>).
209 113 </p>
210 114
211 <p> 115 <p>
212 We use the term <em>sequence</em> to denote a table where 116 We use the term <em>sequence</em> to denote a table where
213 the set of all positive numeric keys is equal to {1..<em>n</em>} 117 the set of all positive numeric keys is equal to {1..<em>n</em>}
214 for some non-negative integer <em>n</em>, 118 for some non-negative integer <em>n</em>,
215 which is called the length of the sequence (see <a href="#length">The Length Operator</a>). 119 which is called the length of the sequence (see <a href="#length">The Length Operator</a>).
216 120 </p>
217 121
218 <p> 122 <p>
219 Like indices, 123 Like indices,
220 the values of table fields can be of any type. 124 the values of table fields can be of any type.
221 In particular, 125 In particular,
222 because functions are first-class values, 126 because functions are first-class values,
223 table fields can contain functions. 127 table fields can contain functions.
224 Thus tables can also carry <em>methods</em> (see <a href="#fn_def">Function Definitions</a>). 128 Thus tables can also carry <em>methods</em> (see <a href="#fn_def">Function Definitions</a>).
225 129 </p>
226 130
227 <p> 131 <p>
228 The indexing of tables follows 132 The indexing of tables follows
229 the definition of raw equality in the language. 133 the definition of raw equality in the language.
230 The expressions <code>a[i]</code> and <code>a[j]</code> 134 The expressions <code>a[i]</code> and <code>a[j]</code>
232 if and only if <code>i</code> and <code>j</code> are raw equal 136 if and only if <code>i</code> and <code>j</code> are raw equal
233 (that is, equal without metamethods). 137 (that is, equal without metamethods).
234 In particular, floats with integral values 138 In particular, floats with integral values
235 are equal to their respective integers 139 are equal to their respective integers
236 (e.g., <code>1.0 == 1</code>). 140 (e.g., <code>1.0 == 1</code>).
237 141 </p>
238 142
239 <p> 143 <p>
240 Luan values are <em>objects</em>: 144 Luan values are <em>objects</em>:
241 variables do not actually <em>contain</em> values, 145 variables do not actually <em>contain</em> values,
242 only <em>references</em> to them. 146 only <em>references</em> to them.
243 Assignment, parameter passing, and function returns 147 Assignment, parameter passing, and function returns
244 always manipulate references to values; 148 always manipulate references to values;
245 these operations do not imply any kind of copy. 149 these operations do not imply any kind of copy.
246 150 </p>
247 151
248 <p> 152 <p>
249 The library function <a href="#Luan.type"><code>Luan.type</code></a> returns a string describing the type 153 The library function <a href="#Luan.type"><code>Luan.type</code></a> returns a string describing the type
250 of a given value. 154 of a given value.
251 155 </p>
252 156 <%
253 157 end
254 158 }
255 159 env = {
256 <h3 heading><a name="env" href="#env">Environments</a></h3> 160 title = "Environments"
257 161 content = function()
162 %>
258 <p> 163 <p>
259 The environment of a chunk starts with only one local variable: <code><a href="#require">require</a></code>. This function is used to load and access libraries and other modules. All other variables must be added to the environment using <a href="http://localhost:8080/manual.html#local_stmt">local declarations</a>. 164 The environment of a chunk starts with only one local variable: <code><a href="#require">require</a></code>. This function is used to load and access libraries and other modules. All other variables must be added to the environment using <a href="http://localhost:8080/manual.html#local_stmt">local declarations</a>.
165 </p>
260 166
261 <p> 167 <p>
262 As will be discussed in <a href="#vars">Variables</a> and <a href=#assignment">Assignment</a>, 168 As will be discussed in <a href="#vars">Variables</a> and <a href=#assignment">Assignment</a>,
263 any reference to a free name 169 any reference to a free name
264 (that is, a name not bound to any declaration) <code>var</code> 170 (that is, a name not bound to any declaration) <code>var</code>
265 can be syntactically translated to <code>_ENV.var</code> if <code>_ENV</code> is defined. 171 can be syntactically translated to <code>_ENV.var</code> if <code>_ENV</code> is defined.
266 172 </p>
267 173 <%
268 <h3 heading><a name="error" href="#error">Error Handling</a></h3> 174 end
269 175 }
176 error = {
177 title = "Error Handling"
178 content = function()
179 %>
270 <p> 180 <p>
271 Luan code can explicitly generate an error by calling the 181 Luan code can explicitly generate an error by calling the
272 <a href="#Luan.error"><code>error</code></a> function. 182 <a href="#Luan.error"><code>error</code></a> function.
273 If you need to catch errors in Luan, 183 If you need to catch errors in Luan,
274 you can use the <a href="#try">Try Statement</code></a>. 184 you can use the <a href="#try">Try Statement</code></a>.
275 185 </p>
276 186
277 <p> 187 <p>
278 Whenever there is an error, 188 Whenever there is an error,
279 an <em>error table</em> 189 an <em>error table</em>
280 is propagated with information about the error. 190 is propagated with information about the error.
281 See <a href="#Luan.new_error"><code>Luan.new_error</code></a>. 191 See <a href="#Luan.new_error"><code>Luan.new_error</code></a>.
282 192 </p>
283 193 <%
284 194 end
285 <h3 heading><a name="meta" href="#meta">Metatables and Metamethods</a></h3> 195 }
286 196 meta = {
197 title = "Metatables and Metamethods"
198 content = function()
199 %>
287 <p> 200 <p>
288 Every table in Luan can have a <em>metatable</em>. 201 Every table in Luan can have a <em>metatable</em>.
289 This <em>metatable</em> is an ordinary Luan table 202 This <em>metatable</em> is an ordinary Luan table
290 that defines the behavior of the original value 203 that defines the behavior of the original value
291 under certain special operations. 204 under certain special operations.
293 of operations over a value by setting specific fields in its metatable. 206 of operations over a value by setting specific fields in its metatable.
294 For instance, when a table is the operand of an addition, 207 For instance, when a table is the operand of an addition,
295 Luan checks for a function in the field "<code>__add</code>" of the table's metatable. 208 Luan checks for a function in the field "<code>__add</code>" of the table's metatable.
296 If it finds one, 209 If it finds one,
297 Luan calls this function to perform the addition. 210 Luan calls this function to perform the addition.
298 211 </p>
299 212
300 <p> 213 <p>
301 The keys in a metatable are derived from the <em>event</em> names; 214 The keys in a metatable are derived from the <em>event</em> names;
302 the corresponding values are called <ii>metamethods</em>. 215 the corresponding values are called <ii>metamethods</em>.
303 In the previous example, the event is <code>"add"</code> 216 In the previous example, the event is <code>"add"</code>
304 and the metamethod is the function that performs the addition. 217 and the metamethod is the function that performs the addition.
305 218 </p>
306 219
307 <p> 220 <p>
308 You can query the metatable of any table 221 You can query the metatable of any table
309 using the <a href="#Luan.get_metatable"><code>get_metatable</code></a> function. 222 using the <a href="#Luan.get_metatable"><code>get_metatable</code></a> function.
310 223 </p>
311 224
312 <p> 225 <p>
313 You can replace the metatable of tables 226 You can replace the metatable of tables
314 using the <a href="#Luan.set_metatable"><code>set_metatable</code></a> function. 227 using the <a href="#Luan.set_metatable"><code>set_metatable</code></a> function.
315 228 </p>
316 229
317 <p> 230 <p>
318 A metatable controls how a table behaves in 231 A metatable controls how a table behaves in
319 arithmetic operations, bitwise operations, 232 arithmetic operations, bitwise operations,
320 order comparisons, concatenation, length operation, calls, and indexing. 233 order comparisons, concatenation, length operation, calls, and indexing.
321 234 </p>
322 235
323 <p> 236 <p>
324 A detailed list of events controlled by metatables is given next. 237 A detailed list of events controlled by metatables is given next.
325 Each operation is identified by its corresponding event name. 238 Each operation is identified by its corresponding event name.
326 The key for each event is a string with its name prefixed by 239 The key for each event is a string with its name prefixed by
329 string "<code>__add</code>". 242 string "<code>__add</code>".
330 Note that queries for metamethods are always raw; 243 Note that queries for metamethods are always raw;
331 the access to a metamethod does not invoke other metamethods. 244 the access to a metamethod does not invoke other metamethods.
332 You can emulate how Luan queries a metamethod for an object <code>obj</code> 245 You can emulate how Luan queries a metamethod for an object <code>obj</code>
333 with the following code: 246 with the following code:
247 </p>
334 248
335 <pre> 249 <pre>
336 raw_get(get_metatable(obj) or {}, "__" .. event_name) 250 raw_get(get_metatable(obj) or {}, "__" .. event_name)
337 </pre> 251 </pre>
338 252
339 <p> 253 <p>
340 Here are the events: 254 Here are the events:
255 </p>
341 256
342 <ul> 257 <ul>
343 258
344 <li><p><b>"add": </b> 259 <li><p>
260 <b>"add": </b>
345 the <code>+</code> operation. 261 the <code>+</code> operation.
346 262
347 If any operand for an addition is a table, 263 If any operand for an addition is a table,
348 Luan will try to call a metamethod. 264 Luan will try to call a metamethod.
349 First, Luan will check the first operand (even if it is valid). 265 First, Luan will check the first operand (even if it is valid).
354 and the result of the call 270 and the result of the call
355 (adjusted to one value) 271 (adjusted to one value)
356 is the result of the operation. 272 is the result of the operation.
357 Otherwise, 273 Otherwise,
358 it raises an error. 274 it raises an error.
359 </li> 275 </p></li>
360 276
361 <li><p><b>"sub": </b> 277 <li><p>
278 <b>"sub": </b>
362 the <code>-</code> operation. 279 the <code>-</code> operation.
363
364 Behavior similar to the "add" operation. 280 Behavior similar to the "add" operation.
365 </li> 281 </li>
366 282
367 <li><p><b>"mul": </b> 283 <li><p><b>"mul": </b>
368 the <code>*</code> operation. 284 the <code>*</code> operation.
369
370 Behavior similar to the "add" operation. 285 Behavior similar to the "add" operation.
371 </li> 286 </p></li>
372 287
373 <li><p><b>"div": </b> 288 <li><p>
289 <b>"div": </b>
374 the <code>/</code> operation. 290 the <code>/</code> operation.
375
376 Behavior similar to the "add" operation. 291 Behavior similar to the "add" operation.
377 </li> 292 </p></li>
378 293
379 <li><p><b>"mod": </b> 294 <li><p>
295 <b>"mod": </b>
380 the <code>%</code> operation. 296 the <code>%</code> operation.
381
382 Behavior similar to the "add" operation. 297 Behavior similar to the "add" operation.
383 </li> 298 </p></li>
384 299
385 <li><p><b>"pow": </b> 300 <li><p>
301 <b>"pow": </b>
386 the <code>^</code> (exponentiation) operation. 302 the <code>^</code> (exponentiation) operation.
387
388 Behavior similar to the "add" operation. 303 Behavior similar to the "add" operation.
389 </li> 304 </p></li>
390 305
391 <li><p><b>"unm": </b> 306 <li><p>
307 <b>"unm": </b>
392 the <code>-</code> (unary minus) operation. 308 the <code>-</code> (unary minus) operation.
393
394 Behavior similar to the "add" operation. 309 Behavior similar to the "add" operation.
395 </li> 310 </p></li>
396 311
397 <li><p><b>"concat": </b> 312 <li><p>
313 <b>"concat": </b>
398 the <code>..</code> (concatenation) operation. 314 the <code>..</code> (concatenation) operation.
399
400 Behavior similar to the "add" operation. 315 Behavior similar to the "add" operation.
401 </li> 316 </p></li>
402 317
403 <li><p><b>"len": </b> 318 <li><p>
319 <b>"len": </b>
404 the <code>#</code> (length) operation. 320 the <code>#</code> (length) operation.
405
406 If there is a metamethod, 321 If there is a metamethod,
407 Luan calls it with the object as argument, 322 Luan calls it with the object as argument,
408 and the result of the call 323 and the result of the call
409 (always adjusted to one value) 324 (always adjusted to one value)
410 is the result of the operation. 325 is the result of the operation.
411 If there is no metamethod but the object is a table, 326 If there is no metamethod but the object is a table,
412 then Luan uses the table length operation (see <a href="#length">The Length Operator</a>). 327 then Luan uses the table length operation (see <a href="#length">The Length Operator</a>).
413 Otherwise, Luan raises an error. 328 Otherwise, Luan raises an error.
414 </li> 329 </p></li>
415 330
416 <li><p><b>"eq": </b> 331 <li><p>
332 <b>"eq": </b>
417 the <code>==</code> (equal) operation. 333 the <code>==</code> (equal) operation.
418
419 Behavior similar to the "add" operation, 334 Behavior similar to the "add" operation,
420 except that Luan will try a metamethod only when the values 335 except that Luan will try a metamethod only when the values
421 being compared are both tables 336 being compared are both tables
422 and they are not primitively equal. 337 and they are not primitively equal.
423 The result of the call is always converted to a boolean. 338 The result of the call is always converted to a boolean.
424 </li> 339 </p></li>
425 340
426 <li><p><b>"lt": </b> 341 <li><p>
342 <b>"lt": </b>
427 the <code>&lt;</code> (less than) operation. 343 the <code>&lt;</code> (less than) operation.
428
429 Behavior similar to the "add" operation. 344 Behavior similar to the "add" operation.
430 The result of the call is always converted to a boolean. 345 The result of the call is always converted to a boolean.
431 </li> 346 </p></li>
432 347
433 <li><p><b>"le": </b> 348 <li><p>
349 <b>"le": </b>
434 the <code>&lt;=</code> (less equal) operation. 350 the <code>&lt;=</code> (less equal) operation.
435
436 Unlike other operations, 351 Unlike other operations,
437 The less-equal operation can use two different events. 352 The less-equal operation can use two different events.
438 First, Luan looks for the "<code>__le</code>" metamethod in both operands, 353 First, Luan looks for the "<code>__le</code>" metamethod in both operands,
439 like in the "lt" operation. 354 like in the "lt" operation.
440 If it cannot find such a metamethod, 355 If it cannot find such a metamethod,
441 then it will try the "<code>__lt</code>" event, 356 then it will try the "<code>__lt</code>" event,
442 assuming that <code>a &lt;= b</code> is equivalent to <code>not (b &lt; a)</code>. 357 assuming that <code>a &lt;= b</code> is equivalent to <code>not (b &lt; a)</code>.
443 As with the other comparison operators, 358 As with the other comparison operators,
444 the result is always a boolean. 359 the result is always a boolean.
445 </li> 360 </p></li>
446 361
447 <li><p><b>"index": </b> 362 <li>
363 <p>
364 <b>"index": </b>
448 The indexing access <code>table[key]</code>. 365 The indexing access <code>table[key]</code>.
449
450 This event happens 366 This event happens
451 when <code>key</code> is not present in <code>table</code>. 367 when <code>key</code> is not present in <code>table</code>.
452 The metamethod is looked up in <code>table</code>. 368 The metamethod is looked up in <code>table</code>.
453 369 </p>
454 370
455 <p> 371 <p>
456 Despite the name, 372 Despite the name,
457 the metamethod for this event can be any type. 373 the metamethod for this event can be any type.
458 If it is a function, 374 If it is a function,
459 it is called with <code>table</code> and <code>key</code> as arguments. 375 it is called with <code>table</code> and <code>key</code> as arguments.
460 Otherwise 376 Otherwise
461 the final result is the result of indexing this metamethod object with <code>key</code>. 377 the final result is the result of indexing this metamethod object with <code>key</code>.
462 (This indexing is regular, not raw, 378 (This indexing is regular, not raw,
463 and therefore can trigger another metamethod if the metamethod object is a table.) 379 and therefore can trigger another metamethod if the metamethod object is a table.)
380 </p>
464 </li> 381 </li>
465 382
466 <li><p><b>"new_index": </b> 383 <li>
384 <p>
385 <b>"new_index": </b>
467 The indexing assignment <code>table[key] = value</code>. 386 The indexing assignment <code>table[key] = value</code>.
468
469 Like the index event, 387 Like the index event,
470 this event happens when 388 this event happens when
471 when <code>key</code> is not present in <code>table</code>. 389 when <code>key</code> is not present in <code>table</code>.
472 The metamethod is looked up in <code>table</code>. 390 The metamethod is looked up in <code>table</code>.
473 391 </p>
474 392
475 <p> 393 <p>
476 Like with indexing, 394 Like with indexing,
477 the metamethod for this event can be either a function or a table. 395 the metamethod for this event can be either a function or a table.
478 If it is a function, 396 If it is a function,
479 it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments. 397 it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments.
480 If it is a table, 398 If it is a table,
481 Luan does an indexing assignment to this table with the same key and value. 399 Luan does an indexing assignment to this table with the same key and value.
482 (This assignment is regular, not raw, 400 (This assignment is regular, not raw,
483 and therefore can trigger another metamethod.) 401 and therefore can trigger another metamethod.)
484 402 </p>
485 403
486 <p> 404 <p>
487 Whenever there is a "new_index" metamethod, 405 Whenever there is a "new_index" metamethod,
488 Luan does not perform the primitive assignment. 406 Luan does not perform the primitive assignment.
489 (If necessary, 407 (If necessary,
490 the metamethod itself can call <a href="#Luan.raw_set"><code>raw_set</code></a> 408 the metamethod itself can call <a href="#Luan.raw_set"><code>raw_set</code></a>
491 to do the assignment.) 409 to do the assignment.)
410 </p>
492 </li> 411 </li>
493 412
494 <li><p><b>"gc":</b> 413 <li><p>
414 <b>"gc":</b>
495 This is when a table is garbage collected. When the table's <a href="https://docs.oracle.com/javase/7/docs/api/java/lang/Object.html#finalize()">finalize</a> method is called by the Java garbage collector, if there is a "<code>__gc</code>" metamethod then it is called with the table as a parameter. 415 This is when a table is garbage collected. When the table's <a href="https://docs.oracle.com/javase/7/docs/api/java/lang/Object.html#finalize()">finalize</a> method is called by the Java garbage collector, if there is a "<code>__gc</code>" metamethod then it is called with the table as a parameter.
496 416 </p></li>
497 </li>
498 417
499 </ul> 418 </ul>
500 419 <%
501 420 end
502 421 }
503 422 gc = {
504 <h3 heading><a name="gc" href="#gc">Garbage Collection</a></h3> 423 title = "Garbage Collection"
505 424 content = function()
425 %>
506 <p> 426 <p>
507 Luan uses Java's garbage collection. 427 Luan uses Java's garbage collection.
508 428 </p>
509 429 <%
510 430 end
511 431 }
512 432 }
513 <h2 heading><a name="lang" href="#lang">The Language</a></h2> 433 }
514 434 lang = {
435 title = "The Language"
436 content = function()
437 %>
515 <p> 438 <p>
516 This section describes the lexis, the syntax, and the semantics of Luan. 439 This section describes the lexis, the syntax, and the semantics of Luan.
517 In other words, 440 In other words,
518 this section describes 441 this section describes
519 which tokens are valid, 442 which tokens are valid,
520 how they can be combined, 443 how they can be combined,
521 and what their combinations mean. 444 and what their combinations mean.
522 445 </p>
523 446
524 <p> 447 <p>
525 Language constructs will be explained using the usual extended BNF notation, 448 Language constructs will be explained using the usual extended BNF notation,
526 in which 449 in which
527 {<em>a</em>}&nbsp;means&nbsp;0 or more <em>a</em>'s, and 450 {<em>a</em>}&nbsp;means&nbsp;0 or more <em>a</em>'s, and
529 Non-terminals are shown like non-terminal, 452 Non-terminals are shown like non-terminal,
530 keywords are shown like <b>kword</b>, 453 keywords are shown like <b>kword</b>,
531 and other terminal symbols are shown like &lsquo;<b>=</b>&rsquo;. 454 and other terminal symbols are shown like &lsquo;<b>=</b>&rsquo;.
532 The complete syntax of Luan can be found in <a href="#9">&sect;9</a> 455 The complete syntax of Luan can be found in <a href="#9">&sect;9</a>
533 at the end of this manual. 456 at the end of this manual.
534 457 </p>
535 458 <%
536 459 end
537 <h3 heading><a name="lex" href="#lex">Lexical Conventions</a></h3> 460 subs = {
538 461 lex = {
462 title = "Lexical Conventions"
463 content = function()
464 %>
539 <p> 465 <p>
540 Luan ignores spaces and comments 466 Luan ignores spaces and comments
541 between lexical elements (tokens), 467 between lexical elements (tokens),
542 except as delimiters between names and keywords. 468 except as delimiters between names and keywords.
543 Luan considers the end of a line to be the end of a statement. This catches errors and encourages readability. If you want to continue a statement on another line, you can use a backslash followed by a newline which will be treated as white space. 469 Luan considers the end of a line to be the end of a statement. This catches errors and encourages readability. If you want to continue a statement on another line, you can use a backslash followed by a newline which will be treated as white space.
470 </p>
544 471
545 <p> 472 <p>
546 <em>Names</em> 473 <em>Names</em>
547 (also called <em>identifiers</em>) 474 (also called <em>identifiers</em>)
548 in Luan can be any string of letters, 475 in Luan can be any string of letters,
549 digits, and underscores, 476 digits, and underscores,
550 not beginning with a digit. 477 not beginning with a digit.
551 Identifiers are used to name variables, table fields, and labels. 478 Identifiers are used to name variables, table fields, and labels.
552 479 </p>
553 480
554 <p> 481 <p>
555 The following <em>keywords</em> are reserved 482 The following <em>keywords</em> are reserved
556 and cannot be used as names: 483 and cannot be used as names:
557 484 </p>
558 485
559 <p keywords> 486 <p keywords>
560 <span>and</span> 487 <span>and</span>
561 <span>break</span> 488 <span>break</span>
562 <span>catch</span> 489 <span>catch</span>
591 518
592 <p> 519 <p>
593 Luan is a case-sensitive language: 520 Luan is a case-sensitive language:
594 <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> 521 <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
595 are two different, valid names. 522 are two different, valid names.
596 523 </p>
597 524
598 <p> 525 <p>
599 The following strings denote other tokens: 526 The following strings denote other tokens:
527 </p>
600 528
601 <pre> 529 <pre>
602 + - * / % ^ # 530 + - * / % ^ #
603 &amp; ~ | &lt;&lt; &gt;&gt; // 531 &amp; ~ | &lt;&lt; &gt;&gt; //
604 == ~= &lt;= &gt;= &lt; &gt; = 532 == ~= &lt;= &gt;= &lt; &gt; =
626 of white-space characters, 554 of white-space characters,
627 including line breaks; 555 including line breaks;
628 it is particularly useful to break and indent a long literal string 556 it is particularly useful to break and indent a long literal string
629 into multiple lines without adding the newlines and spaces 557 into multiple lines without adding the newlines and spaces
630 into the string contents. 558 into the string contents.
631 559 </p>
632 560
633 <p> 561 <p>
634 Luan can specify any character in a literal string by its numerical value. 562 Luan can specify any character in a literal string by its numerical value.
635 This can be done 563 This can be done
636 with the escape sequence <code>\x<em>XX</em></code>, 564 with the escape sequence <code>\x<em>XX</em></code>,
639 where <em>XXXX</em> is a sequence of exactly four hexadecimal digits, 567 where <em>XXXX</em> is a sequence of exactly four hexadecimal digits,
640 or with the escape sequence <code>\<em>ddd</em></code>, 568 or with the escape sequence <code>\<em>ddd</em></code>,
641 where <em>ddd</em> is a sequence of up to three decimal digits. 569 where <em>ddd</em> is a sequence of up to three decimal digits.
642 (Note that if a decimal escape sequence is to be followed by a digit, 570 (Note that if a decimal escape sequence is to be followed by a digit,
643 it must be expressed using exactly three digits.) 571 it must be expressed using exactly three digits.)
644 572 </p>
645 573
646 <p> 574 <p>
647 Literal strings can also be defined using a long format 575 Literal strings can also be defined using a long format
648 enclosed by <em>long brackets</em>. 576 enclosed by <em>long brackets</em>.
649 We define an <em>opening long bracket of level <em>n</em></em> as an opening 577 We define an <em>opening long bracket of level <em>n</em></em> as an opening
663 and ignore long brackets of any other level. 591 and ignore long brackets of any other level.
664 Any kind of end-of-line sequence 592 Any kind of end-of-line sequence
665 (carriage return, newline, carriage return followed by newline, 593 (carriage return, newline, carriage return followed by newline,
666 or newline followed by carriage return) 594 or newline followed by carriage return)
667 is converted to a simple newline. 595 is converted to a simple newline.
668 596 </p>
669 597
670 <p> 598 <p>
671 Any character in a literal string not 599 Any character in a literal string not
672 explicitly affected by the previous rules represents itself. 600 explicitly affected by the previous rules represents itself.
673 However, Luan opens files for parsing in text mode, 601 However, Luan opens files for parsing in text mode,
674 and the system file functions may have problems with 602 and the system file functions may have problems with
675 some control characters. 603 some control characters.
676 So, it is safer to represent 604 So, it is safer to represent
677 non-text data as a quoted literal with 605 non-text data as a quoted literal with
678 explicit escape sequences for non-text characters. 606 explicit escape sequences for non-text characters.
679 607 </p>
680 608
681 <p> 609 <p>
682 For convenience, 610 For convenience,
683 when the opening long bracket is immediately followed by a newline, 611 when the opening long bracket is immediately followed by a newline,
684 the newline is not included in the string. 612 the newline is not included in the string.
685 As an example 613 As an example
686 the five literal strings below denote the same string: 614 the five literal strings below denote the same string:
615 </p>
687 616
688 <pre> 617 <pre>
689 a = 'alo\n123"' 618 a = 'alo\n123"'
690 a = "alo\n123\"" 619 a = "alo\n123\""
691 a = '\97lo\10\04923"' 620 a = '\97lo\10\04923"'
708 marked by a letter '<code>p</code>' or '<code>P</code>'. 637 marked by a letter '<code>p</code>' or '<code>P</code>'.
709 A numeric constant with a fractional dot or an exponent 638 A numeric constant with a fractional dot or an exponent
710 denotes a float; 639 denotes a float;
711 otherwise it denotes an integer. 640 otherwise it denotes an integer.
712 Examples of valid integer constants are 641 Examples of valid integer constants are
642 </p>
713 643
714 <pre> 644 <pre>
715 3 345 0xff 0xBEBADA 645 3 345 0xff 0xBEBADA
716 </pre> 646 </pre>
717 647
718 <p> 648 <p>
719 Examples of valid float constants are 649 Examples of valid float constants are
650 </p>
720 651
721 <pre> 652 <pre>
722 3.0 3.1416 314.16e-2 0.31416E1 34e1 653 3.0 3.1416 314.16e-2 0.31416E1 34e1
723 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 654 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1
724 </pre> 655 </pre>
730 the comment is a <em>short comment</em>, 661 the comment is a <em>short comment</em>,
731 which runs until the end of the line. 662 which runs until the end of the line.
732 Otherwise, it is a <em>long comment</em>, 663 Otherwise, it is a <em>long comment</em>,
733 which runs until the corresponding closing long bracket. 664 which runs until the corresponding closing long bracket.
734 Long comments are frequently used to disable code temporarily. 665 Long comments are frequently used to disable code temporarily.
735 666 </p>
736 667 <%
737 668 end
738 669 }
739 670 vars = {
740 <h3 heading><a name="vars" href="#vars">Variables</a></h3> 671 title = "Variables"
741 672 content = function()
673 %>
742 <p> 674 <p>
743 Variables are places that store values. 675 Variables are places that store values.
744 There are three kinds of variables in Luan: 676 There are three kinds of variables in Luan:
745 global variables, local variables, and table fields. 677 global variables, local variables, and table fields.
678 </p>
746 679
747 <p> 680 <p>
748 A single name can denote a global variable or a local variable 681 A single name can denote a global variable or a local variable
749 (or a function's formal parameter, 682 (or a function's formal parameter,
750 which is a particular kind of local variable): 683 which is a particular kind of local variable):
684 </p>
751 685
752 <pre> 686 <pre>
753 var ::= Name 687 var ::= Name
754 </pre> 688 </pre>
755 689
756 <p> 690 <p>
757 Name denotes identifiers, as defined in <a href="#lex">Lexical Conventions</a>. 691 Name denotes identifiers, as defined in <a href="#lex">Lexical Conventions</a>.
692 </p>
758 693
759 <p> 694 <p>
760 Local variables are <em>lexically scoped</em>: 695 Local variables are <em>lexically scoped</em>:
761 local variables can be freely accessed by functions 696 local variables can be freely accessed by functions
762 defined inside their scope (see <a href="#visibility">Visibility Rules</a>). 697 defined inside their scope (see <a href="#visibility">Visibility Rules</a>).
763 698 </p>
764 699
765 <p> 700 <p>
766 Before the first assignment to a variable, its value is <b>nil</b>. 701 Before the first assignment to a variable, its value is <b>nil</b>.
702 </p>
767 703
768 <p> 704 <p>
769 Square brackets are used to index a table: 705 Square brackets are used to index a table:
706 </p>
770 707
771 <pre> 708 <pre>
772 var ::= prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; 709 var ::= prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo;
773 </pre> 710 </pre>
774 711
778 a call <code>gettable_event(t,i)</code>. 715 a call <code>gettable_event(t,i)</code>.
779 (See <a href="#meta">Metatables and Metamethods</a> for a complete description of the 716 (See <a href="#meta">Metatables and Metamethods</a> for a complete description of the
780 <code>gettable_event</code> function. 717 <code>gettable_event</code> function.
781 This function is not defined or callable in Luan. 718 This function is not defined or callable in Luan.
782 We use it here only for explanatory purposes.) 719 We use it here only for explanatory purposes.)
783 720 </p>
784 721
785 <p> 722 <p>
786 The syntax <code>var.Name</code> is just syntactic sugar for 723 The syntax <code>var.Name</code> is just syntactic sugar for
787 <code>var["Name"]</code>: 724 <code>var["Name"]</code>:
725 </p>
788 726
789 <pre> 727 <pre>
790 var ::= prefixexp &lsquo;<b>.</b>&rsquo; Name 728 var ::= prefixexp &lsquo;<b>.</b>&rsquo; Name
791 </pre> 729 </pre>
792 730
793 <p> 731 <p>
794 Global variables are not available by default. To enable global variable, you must define <code>_ENV</code> as a local variable whose value is a table. If <code>_ENV</code> is not defined, then an unrecognized variable name will produce a compile error. If <code>_ENV</code> is defined then an access to an unrecognized variable name will be consider a global variable. So then an acces to global variable <code>x</code> 732 Global variables are not available by default. To enable global variable, you must define <code>_ENV</code> as a local variable whose value is a table. If <code>_ENV</code> is not defined, then an unrecognized variable name will produce a compile error. If <code>_ENV</code> is defined then an access to an unrecognized variable name will be consider a global variable. So then an acces to global variable <code>x</code>
795 is equivalent to <code>_ENV.x</code>. 733 is equivalent to <code>_ENV.x</code>.
796 Due to the way that chunks are compiled, 734 Due to the way that chunks are compiled,
797 <code>_ENV</code> is never a global name (see <a href="#env">Environments</a>). 735 <code>_ENV</code> is never a global name (see <a href="#env">Environments</a>).
798 736 </p>
799 737 <%
800 738 end
801 739 }
802 740 stmt = {
803 <h3 heading><a name="stmts" href="#stmts">Statements</a></h3> 741 title = "Statements"
804 742 content = function()
743 %>
805 <p> 744 <p>
806 Luan supports an almost conventional set of statements, 745 Luan supports an almost conventional set of statements,
807 similar to those in Pascal or C. 746 similar to those in Pascal or C.
808 This set includes 747 This set includes
809 assignments, control structures, function calls, 748 assignments, control structures, function calls,
810 and variable declarations. 749 and variable declarations.
811 750 </p>
812 751 <%
813 752 end
814 <h4 heading><a name="blocks" href="#blocks">Blocks</a></h4> 753 subs = {
815 754 blocks = {
755 title = "Blocks"
756 content = function()
757 %>
816 <p> 758 <p>
817 A block is a list of statements, 759 A block is a list of statements,
818 which are executed sequentially: 760 which are executed sequentially:
761 </p>
819 762
820 <pre> 763 <pre>
821 block ::= {stat} 764 block ::= {stat}
822 </pre> 765 </pre>
823 766
824 <p> 767 <p>
825 Luan has <em>empty statements</em> 768 Luan has <em>empty statements</em>
826 that allow you to separate statements with semicolons, 769 that allow you to separate statements with semicolons,
827 start a block with a semicolon 770 start a block with a semicolon
828 or write two semicolons in sequence: 771 or write two semicolons in sequence:
772 </p>
829 773
830 <pre> 774 <pre>
831 stat ::= &lsquo;<b>;</b>&rsquo; 775 stat ::= &lsquo;<b>;</b>&rsquo;
832 </pre> 776 </pre>
833 777
834 <p> 778 <p>
835 A block can be explicitly delimited to produce a single statement: 779 A block can be explicitly delimited to produce a single statement:
780 </p>
836 781
837 <pre> 782 <pre>
838 stat ::= <b>do</b> block end_do 783 stat ::= <b>do</b> block end_do
839 end_do ::= <b>end_do</b> | <b>end</b> 784 end_do ::= <b>end_do</b> | <b>end</b>
840 </pre> 785 </pre>
843 Explicit blocks are useful 788 Explicit blocks are useful
844 to control the scope of variable declarations. 789 to control the scope of variable declarations.
845 Explicit blocks are also sometimes used to 790 Explicit blocks are also sometimes used to
846 add a <b>return</b> statement in the middle 791 add a <b>return</b> statement in the middle
847 of another block (see <a href="#control">Control Structures</a>). 792 of another block (see <a href="#control">Control Structures</a>).
848 793 </p>
849 794 <%
850 795 end
851 796 }
852 797 chunks = {
853 <h4 heading><a name="chunks" href="#chunks">Chunks</a></h4> 798 title = "Chunks"
854 799 content = function()
800 %>
855 <p> 801 <p>
856 The unit of compilation of Luan is called a <em>chunk</em>. 802 The unit of compilation of Luan is called a <em>chunk</em>.
857 Syntactically, 803 Syntactically,
858 a chunk is simply a block: 804 a chunk is simply a block:
805 </p>
859 806
860 <pre> 807 <pre>
861 chunk ::= block 808 chunk ::= block
862 </pre> 809 </pre>
863 810
865 Luan handles a chunk as the body of an anonymous function 812 Luan handles a chunk as the body of an anonymous function
866 with a variable number of arguments 813 with a variable number of arguments
867 (see <a href="#fn_def">Function Definitions</a>). 814 (see <a href="#fn_def">Function Definitions</a>).
868 As such, chunks can define local variables, 815 As such, chunks can define local variables,
869 receive arguments, and return values. 816 receive arguments, and return values.
870 817 </p>
871 818
872 <p> 819 <p>
873 A chunk can be stored in a file or in a string inside the host program. 820 A chunk can be stored in a file or in a string inside the host program.
874 To execute a chunk, 821 To execute a chunk,
875 Luan first <em>loads</em> it, 822 Luan first <em>loads</em> it,
876 compiling the chunk's code, 823 compiling the chunk's code,
877 and then Luan executes the compiled code. 824 and then Luan executes the compiled code.
878 825 </p>
879 826 <%
880 827 end
881 828 }
882 829 assignment = {
883 <h4 heading><a name="assignment" href="#assignment">Assignment</a></h4> 830 title = "Assignment"
884 831 content = function()
832 %>
885 <p> 833 <p>
886 Luan allows multiple assignments. 834 Luan allows multiple assignments.
887 Therefore, the syntax for assignment 835 Therefore, the syntax for assignment
888 defines a list of variables on the left side 836 defines a list of variables on the left side
889 and a list of expressions on the right side. 837 and a list of expressions on the right side.
890 The elements in both lists are separated by commas: 838 The elements in both lists are separated by commas:
839 </p>
891 840
892 <pre> 841 <pre>
893 stat ::= varlist &lsquo;<b>=</b>&rsquo; explist 842 stat ::= varlist &lsquo;<b>=</b>&rsquo; explist
894 varlist ::= var {&lsquo;<b>,</b>&rsquo; var} 843 varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
895 explist ::= exp {&lsquo;<b>,</b>&rsquo; exp} 844 explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
896 </pre> 845 </pre>
897 846
898 <p> 847 <p>
899 Expressions are discussed in <a href="#expressions">Expressions</a>. 848 Expressions are discussed in <a href="#expressions">Expressions</a>.
900 849 </p>
901 850
902 <p> 851 <p>
903 Before the assignment, 852 Before the assignment,
904 the list of values is <em>adjusted</em> to the length of 853 the list of values is <em>adjusted</em> to the length of
905 the list of variables. 854 the list of variables.
909 the list is extended with as many <b>nil</b>'s as needed. 858 the list is extended with as many <b>nil</b>'s as needed.
910 If the list of expressions ends with a function call, 859 If the list of expressions ends with a function call,
911 then all values returned by that call enter the list of values, 860 then all values returned by that call enter the list of values,
912 before the adjustment 861 before the adjustment
913 (except when the call is enclosed in parentheses; see <a href="#expressions">Expressions</a>). 862 (except when the call is enclosed in parentheses; see <a href="#expressions">Expressions</a>).
914 863 </p>
915 864
916 <p> 865 <p>
917 The assignment statement first evaluates all its expressions 866 The assignment statement first evaluates all its expressions
918 and only then the assignments are performed. 867 and only then the assignments are performed.
919 Thus the code 868 Thus the code
869 </p>
920 870
921 <pre> 871 <pre>
922 i = 3 872 i = 3
923 i, a[i] = i+1, 20 873 i, a[i] = i+1, 20
924 </pre> 874 </pre>
926 <p> 876 <p>
927 sets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 877 sets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
928 because the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 878 because the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
929 before it is assigned&nbsp;4. 879 before it is assigned&nbsp;4.
930 Similarly, the line 880 Similarly, the line
881 </p>
931 882
932 <pre> 883 <pre>
933 x, y = y, x 884 x, y = y, x
934 </pre> 885 </pre>
935 886
936 <p> 887 <p>
937 exchanges the values of <code>x</code> and <code>y</code>, 888 exchanges the values of <code>x</code> and <code>y</code>,
938 and 889 and
890 </p>
939 891
940 <pre> 892 <pre>
941 x, y, z = y, z, x 893 x, y, z = y, z, x
942 </pre> 894 </pre>
943 895
944 <p> 896 <p>
945 cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 897 cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>.
946 898 </p>
947 899
948 <p> 900 <p>
949 The meaning of assignments to global variables 901 The meaning of assignments to global variables
950 and table fields can be changed via metatables. 902 and table fields can be changed via metatables.
951 An assignment to an indexed variable <code>t[i] = val</code> is equivalent to 903 An assignment to an indexed variable <code>t[i] = val</code> is equivalent to
952 <code>settable_event(t,i,val)</code>. 904 <code>settable_event(t,i,val)</code>.
953 (See <a href="#meta">Metatables and Metamethods</a> for a complete description of the 905 (See <a href="#meta">Metatables and Metamethods</a> for a complete description of the
954 <code>settable_event</code> function. 906 <code>settable_event</code> function.
955 This function is not defined or callable in Luan. 907 This function is not defined or callable in Luan.
956 We use it here only for explanatory purposes.) 908 We use it here only for explanatory purposes.)
957 909 </p>
958 910
959 <p> 911 <p>
960 An assignment to a global name <code>x = val</code> 912 An assignment to a global name <code>x = val</code>
961 is equivalent to the assignment 913 is equivalent to the assignment
962 <code>_ENV.x = val</code> (see <a href="#env">Environments</a>). 914 <code>_ENV.x = val</code> (see <a href="#env">Environments</a>).
963 Global names are only available when <code>_ENV</code> is defined. 915 Global names are only available when <code>_ENV</code> is defined.
964 916 </p>
965 917 <%
966 918 end
967 <h4 heading><a name="control" href="#control">Control Structures</a></h4> 919 }
968 920 control = {
921 title = "Control Structures"
922 content = function()
923 %>
969 <p> 924 <p>
970 The control structures 925 The control structures
971 <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 926 <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
972 familiar syntax: 927 familiar syntax:
928 </p>
973 929
974 <pre> 930 <pre>
975 stat ::= <b>while</b> exp <b>do</b> block end_while 931 stat ::= <b>while</b> exp <b>do</b> block end_while
976 stat ::= <b>repeat</b> block <b>until</b> exp 932 stat ::= <b>repeat</b> block <b>until</b> exp
977 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] end_if 933 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] end_if
979 end_if ::= <b>end_if</b> | <b>end</b> 935 end_if ::= <b>end_if</b> | <b>end</b>
980 </pre> 936 </pre>
981 937
982 <p> 938 <p>
983 Luan also has a <b>for</b> statement (see <a href="#for">For Statement</a>). 939 Luan also has a <b>for</b> statement (see <a href="#for">For Statement</a>).
984 940 </p>
985 941
986 <p> 942 <p>
987 The condition expression of a 943 The condition expression of a
988 control structure must be a boolean. 944 control structure must be a boolean.
989 Any other value type will produce an error. 945 Any other value type will produce an error.
990 This helps catch errors and makes code more readable. 946 This helps catch errors and makes code more readable.
991 947 </p>
992 948
993 <p> 949 <p>
994 In the <b>repeat</b>&ndash;<b>until</b> loop, 950 In the <b>repeat</b>&ndash;<b>until</b> loop,
995 the inner block does not end at the <b>until</b> keyword, 951 the inner block does not end at the <b>until</b> keyword,
996 but only after the condition. 952 but only after the condition.
997 So, the condition can refer to local variables 953 So, the condition can refer to local variables
998 declared inside the loop block. 954 declared inside the loop block.
999 955 </p>
1000 956
1001 <p> 957 <p>
1002 The <b>break</b> statement terminates the execution of a 958 The <b>break</b> statement terminates the execution of a
1003 <b>while</b>, <b>repeat</b>, or <b>for</b> loop, 959 <b>while</b>, <b>repeat</b>, or <b>for</b> loop,
1004 skipping to the next statement after the loop: 960 skipping to the next statement after the loop:
961 </p>
1005 962
1006 <pre> 963 <pre>
1007 stat ::= <b>break</b> 964 stat ::= <b>break</b>
1008 </pre> 965 </pre>
1009 966
1010 <p> 967 <p>
1011 A <b>break</b> ends the innermost enclosing loop. 968 A <b>break</b> ends the innermost enclosing loop.
1012 969 </p>
1013 970
1014 <p> 971 <p>
1015 The <b>continue</b> statement jumps to the beginning of a 972 The <b>continue</b> statement jumps to the beginning of a
1016 <b>while</b>, <b>repeat</b>, or <b>for</b> loop for next iteration, 973 <b>while</b>, <b>repeat</b>, or <b>for</b> loop for next iteration,
1017 skipping the execution of statements inside the body of loop for the current iteration: 974 skipping the execution of statements inside the body of loop for the current iteration:
975 </p>
1018 976
1019 <pre> 977 <pre>
1020 stat ::= <b>continue</b> 978 stat ::= <b>continue</b>
1021 </pre> 979 </pre>
1022
1023 980
1024 <p> 981 <p>
1025 The <b>return</b> statement is used to return values 982 The <b>return</b> statement is used to return values
1026 from a function or a chunk 983 from a function or a chunk
1027 (which is an anonymous function). 984 (which is an anonymous function).
1028
1029 Functions can return more than one value, 985 Functions can return more than one value,
1030 so the syntax for the <b>return</b> statement is 986 so the syntax for the <b>return</b> statement is
987 </p>
1031 988
1032 <pre> 989 <pre>
1033 stat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;] 990 stat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
1034 </pre> 991 </pre>
1035 992 <%
1036 993 end
1037 994 }
1038 995 ["for"] = {
1039 <h4 heading><a name="for" href="#for">For Statement</a></h4> 996 title = "For Statement"
1040 997 content = function()
998 %>
1041 <p> 999 <p>
1042 The <b>for</b> statement works over functions, 1000 The <b>for</b> statement works over functions,
1043 called <em>iterators</em>. 1001 called <em>iterators</em>.
1044 On each iteration, the iterator function is called to produce a new value, 1002 On each iteration, the iterator function is called to produce a new value,
1045 stopping when this new value is <b>nil</b>. 1003 stopping when this new value is <b>nil</b>.
1046 The <b>for</b> loop has the following syntax: 1004 The <b>for</b> loop has the following syntax:
1005 </p>
1047 1006
1048 <pre> 1007 <pre>
1049 stat ::= <b>for</b> namelist <b>in</b> exp <b>do</b> block end_for 1008 stat ::= <b>for</b> namelist <b>in</b> exp <b>do</b> block end_for
1050 namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name} 1009 namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
1051 end_for ::= <b>end_for</b> | <b>end</b> 1010 end_for ::= <b>end_for</b> | <b>end</b>
1052 </pre> 1011 </pre>
1053 1012
1054 <p> 1013 <p>
1055 A <b>for</b> statement like 1014 A <b>for</b> statement like
1015 </p>
1056 1016
1057 <pre> 1017 <pre>
1058 for <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> in <em>exp</em> do <em>block</em> end 1018 for <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> in <em>exp</em> do <em>block</em> end
1059 </pre> 1019 </pre>
1060 1020
1061 <p> 1021 <p>
1062 is equivalent to the code: 1022 is equivalent to the code:
1023 </p>
1063 1024
1064 <pre> 1025 <pre>
1065 do 1026 do
1066 local <em>f</em> = <em>exp</em> 1027 local <em>f</em> = <em>exp</em>
1067 while true do 1028 while true do
1072 end 1033 end
1073 </pre> 1034 </pre>
1074 1035
1075 <p> 1036 <p>
1076 Note the following: 1037 Note the following:
1038 </p>
1077 1039
1078 <ul> 1040 <ul>
1079 1041 <li>
1080 <li> 1042 <code><em>exp</em></code> is evaluated only once.
1081 <code><em>exp</em></code> is evaluated only once. 1043 Its result is an <em>iterator</em> function.
1082 Its result is an <em>iterator</em> function. 1044 </li>
1083 </li> 1045 <li>
1084 1046 <code><em>f</em></code> is an invisible variable.
1085 <li> 1047 The name is here for explanatory purposes only.
1086 <code><em>f</em></code> is an invisible variable. 1048 </li>
1087 The name is here for explanatory purposes only. 1049 <li>
1088 </li> 1050 You can use <b>break</b> to exit a <b>for</b> loop.
1089 1051 </li>
1090 <li> 1052 <li>
1091 You can use <b>break</b> to exit a <b>for</b> loop. 1053 The loop variables <code><em>var_i</em></code> are local to the loop;
1092 </li> 1054 you cannot use their values after the <b>for</b> ends.
1093 1055 If you need these values,
1094 <li> 1056 then assign them to other variables before breaking or exiting the loop.
1095 The loop variables <code><em>var_i</em></code> are local to the loop; 1057 </li>
1096 you cannot use their values after the <b>for</b> ends.
1097 If you need these values,
1098 then assign them to other variables before breaking or exiting the loop.
1099 </li>
1100
1101 </ul> 1058 </ul>
1102 1059 <%
1103 1060 end
1104 1061 }
1105 <h4 heading><a name="try" href="#for">Try Statement</a></h4> 1062 ["try"] = {
1106 1063 title = "Try Statement"
1107 <p>The <b>try</b> statement has the same semantics as in Java.</p> 1064 content = function()
1065 %>
1066 <p>
1067 The <b>try</b> statement has the same semantics as in Java.
1068 </p>
1108 1069
1109 <pre> 1070 <pre>
1110 stat ::= <b>try</b> block [<b>catch</b> Name block] [<b>finally</b> block] end_try 1071 stat ::= <b>try</b> block [<b>catch</b> Name block] [<b>finally</b> block] end_try
1111 end_try ::= <b>end_try</b> | <b>end</b> 1072 end_try ::= <b>end_try</b> | <b>end</b>
1112 </pre> 1073 </pre>
1113 1074 <%
1114 1075 end
1115 1076 }
1116 1077 fn_stmt = {
1117 <h4 heading><a name="fn_stmt" href="#fn_stmt">Function Calls as Statements</a></h4> 1078 title = "Function Calls as Statements"
1118 1079 content = function()
1080 %>
1119 <p> 1081 <p>
1120 To allow possible side-effects, 1082 To allow possible side-effects,
1121 function calls can be executed as statements: 1083 function calls can be executed as statements:
1084 </p>
1122 1085
1123 <pre> 1086 <pre>
1124 stat ::= functioncall 1087 stat ::= functioncall
1125 </pre> 1088 </pre>
1126 1089
1127 <p> 1090 <p>
1128 In this case, all returned values are thrown away. 1091 In this case, all returned values are thrown away.
1129 Function calls are explained in <a href="#fn_calls">Function Calls</a>. 1092 Function calls are explained in <a href="#fn_calls">Function Calls</a>.
1130 1093 </p>
1131 1094 <%
1132 1095 end
1133 <h4 heading><a name="local_stmt" href="#local_stmt">Local Declarations</a></h4> 1096 }
1134 1097 logical_stmt = {
1098 title = "Logical Statement"
1099 content = function()
1100 %>
1101 <p>
1102 <a href="#logical_ops">Logical expressions</a> can be statements.
1103 This is useful in cases like this:
1104 </p>
1105
1106 <pre>
1107 x==5 or error "x should be 5"
1108 </pre>
1109 <%
1110 end
1111 }
1112 local_stmt = {
1113 title = "Local Declarations"
1114 content = function()
1115 %>
1135 <p> 1116 <p>
1136 Local variables can be declared anywhere inside a block. 1117 Local variables can be declared anywhere inside a block.
1137 The declaration can include an initial assignment: 1118 The declaration can include an initial assignment:
1119 </p>
1138 1120
1139 <pre> 1121 <pre>
1140 stat ::= <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist] 1122 stat ::= <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist]
1141 </pre> 1123 </pre>
1142 1124
1143 <p> 1125 <p>
1144 If present, an initial assignment has the same semantics 1126 If present, an initial assignment has the same semantics
1145 of a multiple assignment (see <a href="#assignment">Assignment</a>). 1127 of a multiple assignment (see <a href="#assignment">Assignment</a>).
1146 Otherwise, all variables are initialized with <b>nil</b>. 1128 Otherwise, all variables are initialized with <b>nil</b>.
1147 1129 </p>
1148 1130
1149 <p> 1131 <p>
1150 A chunk is also a block (see <a href="#chunks">Chunks</a>), 1132 A chunk is also a block (see <a href="#chunks">Chunks</a>),
1151 and so local variables can be declared in a chunk outside any explicit block. 1133 and so local variables can be declared in a chunk outside any explicit block.
1152 1134 </p>
1153 1135
1154 <p> 1136 <p>
1155 The visibility rules for local variables are explained in <a href="#visibility">Visibility Rules</a>. 1137 The visibility rules for local variables are explained in <a href="#visibility">Visibility Rules</a>.
1156 1138 </p>
1157 1139 <%
1158 <h4 heading><a name="template_stmt" href="#template_stmt">Template Statements</a></h4> 1140 end
1159 1141 }
1142 template_stmt = {
1143 title = "Template Statements"
1144 content = function()
1145 %>
1160 <p>Template statements provide the full equivalent of <a href="http://en.wikipedia.org/wiki/JavaServer_Pages">JSP</a> but in a general way. Template statements write to standard output. For example:</p> 1146 <p>Template statements provide the full equivalent of <a href="http://en.wikipedia.org/wiki/JavaServer_Pages">JSP</a> but in a general way. Template statements write to standard output. For example:</p>
1147 </p>
1161 1148
1162 <pre> 1149 <pre>
1163 local name = "Bob" 1150 local name = "Bob"
1164 %&gt; 1151 %&gt;
1165 Hello &lt;%= name %&gt;! 1152 Hello &lt;%= name %&gt;!
1166 Bye &lt;%= name %&gt;. 1153 Bye &lt;%= name %&gt;.
1167 &lt;% 1154 &lt;%
1168 </pre> 1155 </pre>
1169 1156
1170 <p>is equivalent to the code:</p> 1157 <p>
1158 is equivalent to the code:
1159 </p>
1171 1160
1172 <pre> 1161 <pre>
1173 local name = "Bob" 1162 local name = "Bob"
1174 require("luan:Io.luan").stdout.write( "Hello ", name , "!\nBye ", name , ".\n" ) 1163 require("luan:Io.luan").stdout.write( "Hello ", name , "!\nBye ", name , ".\n" )
1175 </pre> 1164 </pre>
1176 1165 <%
1177 1166 end
1178 1167 }
1179 <h3 heading><a name="expressions" href="#expressions">Expressions</a></h3> 1168 }
1180 1169 }
1170 expressions = {
1171 title = "Expressions"
1172 content = function()
1173 %>
1181 <p> 1174 <p>
1182 The basic expressions in Luan are the following: 1175 The basic expressions in Luan are the following:
1176 </p>
1183 1177
1184 <pre> 1178 <pre>
1185 exp ::= prefixexp 1179 exp ::= prefixexp
1186 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 1180 exp ::= <b>nil</b> | <b>false</b> | <b>true</b>
1187 exp ::= Numeral 1181 exp ::= Numeral
1202 table constructors are explained in <a href="#constructors">Table Constructors</a>. 1196 table constructors are explained in <a href="#constructors">Table Constructors</a>.
1203 Vararg expressions, 1197 Vararg expressions,
1204 denoted by three dots ('<code>...</code>'), can only be used when 1198 denoted by three dots ('<code>...</code>'), can only be used when
1205 directly inside a vararg function; 1199 directly inside a vararg function;
1206 they are explained in <a href="#fn_def">Function Definitions</a>. 1200 they are explained in <a href="#fn_def">Function Definitions</a>.
1207 1201 </p>
1208 1202
1209 <p> 1203 <p>
1210 Binary operators comprise arithmetic operators (see <a href="#arithmetic">Arithmetic Operators</a>), 1204 Binary operators comprise arithmetic operators (see <a href="#arithmetic">Arithmetic Operators</a>),
1211 relational operators (see <a href="#relational">Relational Operators</a>), logical operators (see <a href="#logical_ops">Logical Operators</a>), 1205 relational operators (see <a href="#relational">Relational Operators</a>), logical operators (see <a href="#logical_ops">Logical Operators</a>),
1212 and the concatenation operator (see <a href="#concatenation">Concatenation</a>). 1206 and the concatenation operator (see <a href="#concatenation">Concatenation</a>).
1213 Unary operators comprise the unary minus (see <a href="#arithmetic">Arithmetic Operators</a>), 1207 Unary operators comprise the unary minus (see <a href="#arithmetic">Arithmetic Operators</a>),
1214 the unary logical <b>not</b> (see <a href="#logical_ops">Logical Operators</a>), 1208 the unary logical <b>not</b> (see <a href="#logical_ops">Logical Operators</a>),
1215 and the unary <em>length operator</em> (see <a href="#length">The Length Operator</a>). 1209 and the unary <em>length operator</em> (see <a href="#length">The Length Operator</a>).
1216 1210 </p>
1217 1211
1218 <p> 1212 <p>
1219 Both function calls and vararg expressions can result in multiple values. 1213 Both function calls and vararg expressions can result in multiple values.
1220 If a function call is used as a statement (see <a href="#fn_stmt">Function Calls as Statements</a>), 1214 If a function call is used as a statement (see <a href="#fn_stmt">Function Calls as Statements</a>),
1221 then its return list is adjusted to zero elements, 1215 then its return list is adjusted to zero elements,
1226 (unless the expression is enclosed in parentheses). 1220 (unless the expression is enclosed in parentheses).
1227 In all other contexts, 1221 In all other contexts,
1228 Luan adjusts the result list to one element, 1222 Luan adjusts the result list to one element,
1229 either discarding all values except the first one 1223 either discarding all values except the first one
1230 or adding a single <b>nil</b> if there are no values. 1224 or adding a single <b>nil</b> if there are no values.
1231 1225 </p>
1232 1226
1233 <p> 1227 <p>
1234 Here are some examples: 1228 Here are some examples:
1229 </p>
1235 1230
1236 <pre> 1231 <pre>
1237 f() -- adjusted to 0 results 1232 f() -- adjusted to 0 results
1238 g(f(), x) -- f() is adjusted to 1 result 1233 g(f(), x) -- f() is adjusted to 1 result
1239 g(x, f()) -- g gets x plus all results from f() 1234 g(x, f()) -- g gets x plus all results from f()
1257 Thus, 1252 Thus,
1258 <code>(f(x,y,z))</code> is always a single value, 1253 <code>(f(x,y,z))</code> is always a single value,
1259 even if <code>f</code> returns several values. 1254 even if <code>f</code> returns several values.
1260 (The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> 1255 (The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code>
1261 or <b>nil</b> if <code>f</code> does not return any values.) 1256 or <b>nil</b> if <code>f</code> does not return any values.)
1262 1257 </p>
1263 1258 <%
1264 1259 end
1265 <h4 heading><a name="arithmetic" href="#arithmetic">Arithmetic Operators</a></h4> 1260 subs = {
1266 1261 arithmetic = {
1262 title = "Arithmetic Operators"
1263 content = function()
1264 %>
1267 <p> 1265 <p>
1268 Luan supports the following arithmetic operators: 1266 Luan supports the following arithmetic operators:
1267 </p>
1269 1268
1270 <ul> 1269 <ul>
1271 <li><b><code>+</code>: </b>addition</li> 1270 <li><b><code>+</code>: </b>addition</li>
1272 <li><b><code>-</code>: </b>subtraction</li> 1271 <li><b><code>-</code>: </b>subtraction</li>
1273 <li><b><code>*</code>: </b>multiplication</li> 1272 <li><b><code>*</code>: </b>multiplication</li>
1277 <li><b><code>-</code>: </b>unary minus</li> 1276 <li><b><code>-</code>: </b>unary minus</li>
1278 </ul> 1277 </ul>
1279 1278
1280 <p> 1279 <p>
1281 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. 1280 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.
1281 </p>
1282 1282
1283 <p> 1283 <p>
1284 Modulo is defined as the remainder of a division 1284 Modulo is defined as the remainder of a division
1285 that rounds the quotient towards minus infinite (floor division). 1285 that rounds the quotient towards minus infinite (floor division).
1286 (The Java modulo operator is not used.) 1286 (The Java modulo operator is not used.)
1287 1287 </p>
1288 1288 <%
1289 1289 end
1290 <h4 heading><a name="conversions" href="#conversions">Coercions and Conversions</a></h4> 1290 }
1291 1291 conversions = {
1292 title = "Coercions and Conversions"
1293 content = function()
1294 %>
1292 <p> 1295 <p>
1293 Luan generally avoids automatic conversions. 1296 Luan generally avoids automatic conversions.
1294 String concatenation automatically converts all of its arguments to strings. 1297 String concatenation automatically converts all of its arguments to strings.
1298 </p>
1295 1299
1296 <p> 1300 <p>
1297 Luan provides library functions for explicit type conversions. 1301 Luan provides library functions for explicit type conversions.
1298 1302 </p>
1299 1303 <%
1300 1304 end
1301 1305 }
1302 <h4 heading><a name="relational" href="#relational">Relational Operators</a></h4> 1306 relational = {
1303 1307 title = "Relational Operators"
1308 content = function()
1309 %>
1304 <p> 1310 <p>
1305 Luan supports the following relational operators: 1311 Luan supports the following relational operators:
1312 </p>
1306 1313
1307 <ul> 1314 <ul>
1308 <li><b><code>==</code>: </b>equality</li> 1315 <li><b><code>==</code>: </b>equality</li>
1309 <li><b><code>~=</code>: </b>inequality</li> 1316 <li><b><code>~=</code>: </b>inequality</li>
1310 <li><b><code>&lt;</code>: </b>less than</li> 1317 <li><b><code>&lt;</code>: </b>less than</li>
1311 <li><b><code>&gt;</code>: </b>greater than</li> 1318 <li><b><code>&gt;</code>: </b>greater than</li>
1312 <li><b><code>&lt;=</code>: </b>less or equal</li> 1319 <li><b><code>&lt;=</code>: </b>less or equal</li>
1313 <li><b><code>&gt;=</code>: </b>greater or equal</li> 1320 <li><b><code>&gt;=</code>: </b>greater or equal</li>
1314 </ul><p> 1321 </ul>
1322
1323 <p>
1315 These operators always result in <b>false</b> or <b>true</b>. 1324 These operators always result in <b>false</b> or <b>true</b>.
1316 1325 </p>
1317 1326
1318 <p> 1327 <p>
1319 Equality (<code>==</code>) first compares the type of its operands. 1328 Equality (<code>==</code>) first compares the type of its operands.
1320 If the types are different, then the result is <b>false</b>. 1329 If the types are different, then the result is <b>false</b>.
1321 Otherwise, the values of the operands are compared. 1330 Otherwise, the values of the operands are compared.
1322 Strings, numbers, and binary values are compared in the obvious way (by value). 1331 Strings, numbers, and binary values are compared in the obvious way (by value).
1332 </p>
1323 1333
1324 <p> 1334 <p>
1325 Tables 1335 Tables
1326 are compared by reference: 1336 are compared by reference:
1327 two objects are considered equal only if they are the same object. 1337 two objects are considered equal only if they are the same object.
1328 Every time you create a new table, 1338 Every time you create a new table,
1329 it is different from any previously existing table. 1339 it is different from any previously existing table.
1330 Closures are also compared by reference. 1340 Closures are also compared by reference.
1341 </p>
1331 1342
1332 <p> 1343 <p>
1333 You can change the way that Luan compares tables 1344 You can change the way that Luan compares tables
1334 by using the "eq" metamethod (see <a href="#meta">Metatables and Metamethods</a>). 1345 by using the "eq" metamethod (see <a href="#meta">Metatables and Metamethods</a>).
1346 </p>
1335 1347
1336 <p> 1348 <p>
1337 Java values 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)"><code>equals</code></a> method. 1349 Java values 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)"><code>equals</code></a> method.
1350 </p>
1338 1351
1339 <p> 1352 <p>
1340 Equality comparisons do not convert strings to numbers 1353 Equality comparisons do not convert strings to numbers
1341 or vice versa. 1354 or vice versa.
1342 Thus, <code>"0"==0</code> evaluates to <b>false</b>, 1355 Thus, <code>"0"==0</code> evaluates to <b>false</b>,
1343 and <code>t[0]</code> and <code>t["0"]</code> denote different 1356 and <code>t[0]</code> and <code>t["0"]</code> denote different
1344 entries in a table. 1357 entries in a table.
1345 1358 </p>
1346 1359
1347 <p> 1360 <p>
1348 The operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 1361 The operator <code>~=</code> is exactly the negation of equality (<code>==</code>).
1349 1362 </p>
1350 1363
1351 <p> 1364 <p>
1352 The order operators work as follows. 1365 The order operators work as follows.
1353
1354 If both arguments are numbers, 1366 If both arguments are numbers,
1355 then they are compared following 1367 then they are compared following
1356 the usual rule for binary operations. 1368 the usual rule for binary operations.
1357 Otherwise, if both arguments are strings, 1369 Otherwise, if both arguments are strings,
1358 then their values are compared according to the current locale. 1370 then their values are compared according to the current locale.
1359 Otherwise, Luan tries to call the "lt" or the "le" 1371 Otherwise, Luan tries to call the "lt" or the "le"
1360 metamethod (see <a href="#meta">Metatables and Metamethods</a>). 1372 metamethod (see <a href="#meta">Metatables and Metamethods</a>).
1361 A comparison <code>a &gt; b</code> is translated to <code>b &lt; a</code> 1373 A comparison <code>a &gt; b</code> is translated to <code>b &lt; a</code>
1362 and <code>a &gt;= b</code> is translated to <code>b &lt;= a</code>. 1374 and <code>a &gt;= b</code> is translated to <code>b &lt;= a</code>.
1363 1375 </p>
1364 1376 <%
1365 1377 end
1366 1378 }
1367 1379 logical_ops = {
1368 <h4 heading><a name="logical_ops" href="#logical_ops">Logical Operators</a></h4> 1380 title = "Logical Operators"
1369 1381 content = function()
1382 %>
1370 <p> 1383 <p>
1371 The logical operators in Luan are 1384 The logical operators in Luan are
1372 <b>and</b>, <b>or</b>, and <b>not</b>. 1385 <b>and</b>, <b>or</b>, and <b>not</b>.
1373 The <b>and</b> and <b>or</b> operators consider both <b>false</b> and <b>nil</b> as false 1386 The <b>and</b> and <b>or</b> operators consider both <b>false</b> and <b>nil</b> as false
1374 and anything else as true. 1387 and anything else as true.
1375 Like the control structures (see <a href="#control">Control Structures</a>), 1388 Like the control structures (see <a href="#control">Control Structures</a>),
1376 the <b>not</b> operator requires a boolean value. 1389 the <b>not</b> operator requires a boolean value.
1390 </p>
1377 1391
1378 <p> 1392 <p>
1379 The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 1393 The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>.
1380 The conjunction operator <b>and</b> returns its first argument 1394 The conjunction operator <b>and</b> returns its first argument
1381 if this value is <b>false</b> or <b>nil</b>; 1395 if this value is <b>false</b> or <b>nil</b>;
1385 otherwise, <b>or</b> returns its second argument. 1399 otherwise, <b>or</b> returns its second argument.
1386 Both <b>and</b> and <b>or</b> use short-circuit evaluation; 1400 Both <b>and</b> and <b>or</b> use short-circuit evaluation;
1387 that is, 1401 that is,
1388 the second operand is evaluated only if necessary. 1402 the second operand is evaluated only if necessary.
1389 Here are some examples: 1403 Here are some examples:
1404 </p>
1390 1405
1391 <pre> 1406 <pre>
1392 10 or 20 --&gt; 10 1407 10 or 20 --&gt; 10
1393 10 or error() --&gt; 10 1408 10 or error() --&gt; 10
1394 nil or "a" --&gt; "a" 1409 nil or "a" --&gt; "a"
1400 </pre> 1415 </pre>
1401 1416
1402 <p> 1417 <p>
1403 (In this manual, 1418 (In this manual,
1404 <code>--&gt;</code> indicates the result of the preceding expression.) 1419 <code>--&gt;</code> indicates the result of the preceding expression.)
1405 1420 </p>
1406 1421 <%
1407 1422 end
1408 <h4 heading><a name="concatenation" href="#concatenation">Concatenation</a></h4> 1423 }
1409 1424 concatenation = {
1425 title = "Concatenation"
1426 content = function()
1427 %>
1410 <p> 1428 <p>
1411 The string concatenation operator in Luan is 1429 The string concatenation operator in Luan is
1412 denoted by two dots ('<code>..</code>'). 1430 denoted by two dots ('<code>..</code>').
1413 All operands are converted to strings. 1431 All operands are converted to strings.
1414 1432 </p>
1415 1433 <%
1416 1434 end
1417 <h4 heading><a name="length" href="#length">The Length Operator</a></h4> 1435 }
1418 1436 length = {
1437 title = "The Length Operator"
1438 content = function()
1439 %>
1419 <p> 1440 <p>
1420 The length operator is denoted by the unary prefix operator <code>#</code>. 1441 The length operator is denoted by the unary prefix operator <code>#</code>.
1421 The length of a string is its number of characters. 1442 The length of a string is its number of characters.
1422 The length of a binary is its number of bytes. 1443 The length of a binary is its number of bytes.
1423 1444 </p>
1424 1445
1425 <p> 1446 <p>
1426 A program can modify the behavior of the length operator for 1447 A program can modify the behavior of the length operator for
1427 any table through the <code>__len</code> metamethod (see <a href="#meta">Metatables and Metamethods</a>). 1448 any table through the <code>__len</code> metamethod (see <a href="#meta">Metatables and Metamethods</a>).
1428 1449 </p>
1429 1450
1430 <p> 1451 <p>
1431 Unless a <code>__len</code> metamethod is given, 1452 Unless a <code>__len</code> metamethod is given,
1432 the length of a table <code>t</code> is defined 1453 the length of a table <code>t</code> is defined
1433 as the number of elements in <em>sequence</em>, 1454 as the number of elements in <em>sequence</em>,
1434 that is, 1455 that is,
1435 the size of the set of its positive numeric keys is equal to <em>{1..n}</em> 1456 the size of the set of its positive numeric keys is equal to <em>{1..n}</em>
1436 for some non-negative integer <em>n</em>. 1457 for some non-negative integer <em>n</em>.
1437 In that case, <em>n</em> is its length. 1458 In that case, <em>n</em> is its length.
1438 Note that a table like 1459 Note that a table like
1460 </p>
1439 1461
1440 <pre> 1462 <pre>
1441 {10, 20, nil, 40} 1463 {10, 20, nil, 40}
1442 </pre> 1464 </pre>
1443 1465
1444 <p> 1466 <p>
1445 has a length of <code>2</code>, because that is the last key in sequence. 1467 has a length of <code>2</code>, because that is the last key in sequence.
1446 1468 </p>
1447 1469 <%
1448 1470 end
1449 1471 }
1450 1472 precedence = {
1451 <h4 heading><a name="precedence" href="#precedence">Precedence</a></h4> 1473 title = "Precedence"
1452 1474 content = function()
1475 %>
1453 <p> 1476 <p>
1454 Operator precedence in Luan follows the table below, 1477 Operator precedence in Luan follows the table below,
1455 from lower to higher priority: 1478 from lower to higher priority:
1479 </p>
1456 1480
1457 <pre> 1481 <pre>
1458 or 1482 or
1459 and 1483 and
1460 &lt; &gt; &lt;= &gt;= ~= == 1484 &lt; &gt; &lt;= &gt;= ~= ==
1469 As usual, 1493 As usual,
1470 you can use parentheses to change the precedences of an expression. 1494 you can use parentheses to change the precedences of an expression.
1471 The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 1495 The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>')
1472 operators are right associative. 1496 operators are right associative.
1473 All other binary operators are left associative. 1497 All other binary operators are left associative.
1474 1498 </p>
1475 1499 <%
1476 1500 end
1477 1501 }
1478 1502 constructors = {
1479 <h4 heading><a name="constructors" href="#constructors">Table Constructors</a></h4> 1503 title = "Table Constructors"
1480 1504 content = function()
1505 %>
1481 <p> 1506 <p>
1482 Table constructors are expressions that create tables. 1507 Table constructors are expressions that create tables.
1483 Every time a constructor is evaluated, a new table is created. 1508 Every time a constructor is evaluated, a new table is created.
1484 A constructor can be used to create an empty table 1509 A constructor can be used to create an empty table
1485 or to create a table and initialize some of its fields. 1510 or to create a table and initialize some of its fields.
1486 The general syntax for constructors is 1511 The general syntax for constructors is
1512 </p>
1487 1513
1488 <pre> 1514 <pre>
1489 tableconstructor ::= &lsquo;<b>{</b>&rsquo; fieldlist &lsquo;<b>}</b>&rsquo; 1515 tableconstructor ::= &lsquo;<b>{</b>&rsquo; fieldlist &lsquo;<b>}</b>&rsquo;
1490 fieldlist ::= [field] {fieldsep [field]} 1516 fieldlist ::= [field] {fieldsep [field]}
1491 field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp 1517 field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
1500 Finally, fields of the form <code>exp</code> are equivalent to 1526 Finally, fields of the form <code>exp</code> are equivalent to
1501 <code>[i] = exp</code>, where <code>i</code> are consecutive integers 1527 <code>[i] = exp</code>, where <code>i</code> are consecutive integers
1502 starting with 1. 1528 starting with 1.
1503 Fields in the other formats do not affect this counting. 1529 Fields in the other formats do not affect this counting.
1504 For example, 1530 For example,
1531 </p>
1505 1532
1506 <pre> 1533 <pre>
1507 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 1534 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
1508 </pre> 1535 </pre>
1509 1536
1510 <p> 1537 <p>
1511 is equivalent to 1538 is equivalent to
1539 </p>
1512 1540
1513 <pre> 1541 <pre>
1514 do 1542 do
1515 local t = {} 1543 local t = {}
1516 t[f(1)] = g 1544 t[f(1)] = g
1525 </pre> 1553 </pre>
1526 1554
1527 <p> 1555 <p>
1528 The order of the assignments in a constructor is undefined. 1556 The order of the assignments in a constructor is undefined.
1529 (This order would be relevant only when there are repeated keys.) 1557 (This order would be relevant only when there are repeated keys.)
1530 1558 </p>
1531 1559
1532 <p> 1560 <p>
1533 If the last field in the list has the form <code>exp</code> 1561 If the last field in the list has the form <code>exp</code>
1534 and the expression is a function call or a vararg expression, 1562 and the expression is a function call or a vararg expression,
1535 then all values returned by this expression enter the list consecutively 1563 then all values returned by this expression enter the list consecutively
1536 (see <a href="#fn_calls">Function Calls</a>). 1564 (see <a href="#fn_calls">Function Calls</a>).
1537 1565 </p>
1538 1566
1539 <p> 1567 <p>
1540 The field list can have an optional trailing separator, 1568 The field list can have an optional trailing separator,
1541 as a convenience for machine-generated code. 1569 as a convenience for machine-generated code.
1542 1570 </p>
1543 1571 <%
1544 1572 end
1545 1573 }
1546 1574 fn_calls = {
1547 <h4 heading><a name="fn_calls" href="#fn_calls">Function Calls</a></h4> 1575 title = "Function Calls"
1548 1576 content = function()
1577 %>
1549 <p> 1578 <p>
1550 A function call in Luan has the following syntax: 1579 A function call in Luan has the following syntax:
1580 </p>
1551 1581
1552 <pre> 1582 <pre>
1553 functioncall ::= prefixexp args 1583 functioncall ::= prefixexp args
1554 </pre> 1584 </pre>
1555 1585
1557 In a function call, 1587 In a function call,
1558 first prefixexp and args are evaluated. 1588 first prefixexp and args are evaluated.
1559 The value of prefixexp must have type <em>function</em>. 1589 The value of prefixexp must have type <em>function</em>.
1560 This function is called 1590 This function is called
1561 with the given arguments. 1591 with the given arguments.
1562 1592 </p>
1563 1593
1564 <p> 1594 <p>
1565 Arguments have the following syntax: 1595 Arguments have the following syntax:
1596 </p>
1566 1597
1567 <pre> 1598 <pre>
1568 args ::= &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo; 1599 args ::= &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo;
1569 args ::= tableconstructor 1600 args ::= tableconstructor
1570 args ::= LiteralString 1601 args ::= LiteralString
1577 that is, the argument list is a single new table. 1608 that is, the argument list is a single new table.
1578 A call of the form <code>f'<em>string</em>'</code> 1609 A call of the form <code>f'<em>string</em>'</code>
1579 (or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 1610 (or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>)
1580 is syntactic sugar for <code>f('<em>string</em>')</code>; 1611 is syntactic sugar for <code>f('<em>string</em>')</code>;
1581 that is, the argument list is a single literal string. 1612 that is, the argument list is a single literal string.
1582 1613 </p>
1583 1614 <%
1584 1615 end
1585 1616 }
1586 <h4 heading><a name="fn_def" href="#fn_def">Function Definitions</a></h4> 1617 fn_def = {
1587 1618 title = "Function Definitions"
1619 content = function()
1620 %>
1588 <p> 1621 <p>
1589 The syntax for function definition is 1622 The syntax for function definition is
1623 </p>
1590 1624
1591 <pre> 1625 <pre>
1592 functiondef ::= <b>function</b> funcbody 1626 functiondef ::= <b>function</b> funcbody
1593 funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block end_function 1627 funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block end_function
1594 end_function ::= <b>end_function</b> | <b>end</b> 1628 end_function ::= <b>end_function</b> | <b>end</b>
1595 </pre> 1629 </pre>
1596 1630
1597 <p> 1631 <p>
1598 The following syntactic sugar simplifies function definitions: 1632 The following syntactic sugar simplifies function definitions:
1633 </p>
1599 1634
1600 <pre> 1635 <pre>
1601 stat ::= <b>function</b> funcname funcbody 1636 stat ::= <b>function</b> funcname funcbody
1602 stat ::= <b>local</b> <b>function</b> Name funcbody 1637 stat ::= <b>local</b> <b>function</b> Name funcbody
1603 funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name] 1638 funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
1604 </pre> 1639 </pre>
1605 1640
1606 <p> 1641 <p>
1607 The statement 1642 The statement
1643 </p>
1608 1644
1609 <pre> 1645 <pre>
1610 function f () <em>body</em> end 1646 function f () <em>body</em> end
1611 </pre> 1647 </pre>
1612 1648
1613 <p> 1649 <p>
1614 translates to 1650 translates to
1651 </p>
1615 1652
1616 <pre> 1653 <pre>
1617 f = function () <em>body</em> end 1654 f = function () <em>body</em> end
1618 </pre> 1655 </pre>
1619 1656
1620 <p> 1657 <p>
1621 The statement 1658 The statement
1659 <p>
1622 1660
1623 <pre> 1661 <pre>
1624 function t.a.b.c.f () <em>body</em> end 1662 function t.a.b.c.f () <em>body</em> end
1625 </pre> 1663 </pre>
1626 1664
1627 <p> 1665 <p>
1628 translates to 1666 translates to
1667 </p>
1629 1668
1630 <pre> 1669 <pre>
1631 t.a.b.c.f = function () <em>body</em> end 1670 t.a.b.c.f = function () <em>body</em> end
1632 </pre> 1671 </pre>
1633 1672
1634 <p> 1673 <p>
1635 The statement 1674 The statement
1675 </p>
1636 1676
1637 <pre> 1677 <pre>
1638 local function f () <em>body</em> end 1678 local function f () <em>body</em> end
1639 </pre> 1679 </pre>
1640 1680
1641 <p> 1681 <p>
1642 translates to 1682 translates to
1683 </p>
1643 1684
1644 <pre> 1685 <pre>
1645 local f; f = function () <em>body</em> end 1686 local f; f = function () <em>body</em> end
1646 </pre> 1687 </pre>
1647 1688
1648 <p> 1689 <p>
1649 not to 1690 not to
1691 </p>
1650 1692
1651 <pre> 1693 <pre>
1652 local f = function () <em>body</em> end 1694 local f = function () <em>body</em> end
1653 </pre> 1695 </pre>
1654 1696
1655 <p> 1697 <p>
1656 (This only makes a difference when the body of the function 1698 (This only makes a difference when the body of the function
1657 contains references to <code>f</code>.) 1699 contains references to <code>f</code>.)
1658 1700 </p>
1659 1701
1660 <p> 1702 <p>
1661 A function definition is an executable expression, 1703 A function definition is an executable expression,
1662 whose value has type <em>function</em>. 1704 whose value has type <em>function</em>.
1663 When Luan precompiles a chunk, 1705 When Luan precompiles a chunk,
1664 all its function bodies are precompiled too. 1706 all its function bodies are precompiled too.
1665 Then, whenever Luan executes the function definition, 1707 Then, whenever Luan executes the function definition,
1666 the function is <em>instantiated</em> (or <em>closed</em>). 1708 the function is <em>instantiated</em> (or <em>closed</em>).
1667 This function instance (or <em>closure</em>) 1709 This function instance (or <em>closure</em>)
1668 is the final value of the expression. 1710 is the final value of the expression.
1669 1711 </p>
1670 1712
1671 <p> 1713 <p>
1672 Parameters act as local variables that are 1714 Parameters act as local variables that are
1673 initialized with the argument values: 1715 initialized with the argument values:
1716 </p>
1674 1717
1675 <pre> 1718 <pre>
1676 parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo; 1719 parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
1677 </pre> 1720 </pre>
1678 1721
1693 or in the middle of a list of expressions, 1736 or in the middle of a list of expressions,
1694 then its return list is adjusted to one element. 1737 then its return list is adjusted to one element.
1695 If the expression is used as the last element of a list of expressions, 1738 If the expression is used as the last element of a list of expressions,
1696 then no adjustment is made 1739 then no adjustment is made
1697 (unless that last expression is enclosed in parentheses). 1740 (unless that last expression is enclosed in parentheses).
1698 1741 </p>
1699 1742
1700 <p> 1743 <p>
1701 As an example, consider the following definitions: 1744 As an example, consider the following definitions:
1702 1745 </p>
1703 <pre> 1746 <pre>
1704 function f(a, b) end 1747 function f(a, b) end
1705 function g(a, b, ...) end 1748 function g(a, b, ...) end
1706 function r() return 1,2,3 end 1749 function r() return 1,2,3 end
1707 </pre> 1750 </pre>
1708 1751
1709 <p> 1752 <p>
1710 Then, we have the following mapping from arguments to parameters and 1753 Then, we have the following mapping from arguments to parameters and
1711 to the vararg expression: 1754 to the vararg expression:
1712 1755 </p>
1713 <pre> 1756 <pre>
1714 CALL PARAMETERS 1757 CALL PARAMETERS
1715 1758
1716 f(3) a=3, b=nil 1759 f(3) a=3, b=nil
1717 f(3, 4) a=3, b=4 1760 f(3, 4) a=3, b=4
1728 <p> 1771 <p>
1729 Results are returned using the <b>return</b> statement (see <a href="#control">Control Structures</a>). 1772 Results are returned using the <b>return</b> statement (see <a href="#control">Control Structures</a>).
1730 If control reaches the end of a function 1773 If control reaches the end of a function
1731 without encountering a <b>return</b> statement, 1774 without encountering a <b>return</b> statement,
1732 then the function returns with no results. 1775 then the function returns with no results.
1733 1776 </p>
1734 1777 <%
1735 <h3 heading><a name="visibility" href="#visibility">Visibility Rules</a></h3> 1778 end
1736 1779 }
1780 }
1781 }
1782 visibility = {
1783 title = "Visibility Rules"
1784 content = function()
1785 %>
1737 <p> 1786 <p>
1738 Luan is a lexically scoped language. 1787 Luan is a lexically scoped language.
1739 The scope of a local variable begins at the first statement after 1788 The scope of a local variable begins at the first statement after
1740 its declaration and lasts until the last non-void statement 1789 its declaration and lasts until the last non-void statement
1741 of the innermost block that includes the declaration. 1790 of the innermost block that includes the declaration.
1742 Consider the following example: 1791 Consider the following example:
1743 1792 </p>
1744 <pre> 1793 <pre>
1745 x = 10 -- global variable 1794 x = 10 -- global variable
1746 do -- new block 1795 do -- new block
1747 local x = x -- new 'x', with value 10 1796 local x = x -- new 'x', with value 10
1748 print(x) --&gt; 10 1797 print(x) --&gt; 10
1758 1807
1759 <p> 1808 <p>
1760 Notice that, in a declaration like <code>local x = x</code>, 1809 Notice that, in a declaration like <code>local x = x</code>,
1761 the new <code>x</code> being declared is not in scope yet, 1810 the new <code>x</code> being declared is not in scope yet,
1762 and so the second <code>x</code> refers to the outside variable. 1811 and so the second <code>x</code> refers to the outside variable.
1763 1812 </p>
1764 1813
1765 <p> 1814 <p>
1766 Because of the lexical scoping rules, 1815 Because of the lexical scoping rules,
1767 local variables can be freely accessed by functions 1816 local variables can be freely accessed by functions
1768 defined inside their scope. 1817 defined inside their scope.
1769 A local variable used by an inner function is called 1818 A local variable used by an inner function is called
1770 an <em>upvalue</em>, or <em>external local variable</em>, 1819 an <em>upvalue</em>, or <em>external local variable</em>,
1771 inside the inner function. 1820 inside the inner function.
1772 1821 </p>
1773 1822
1774 <p> 1823 <p>
1775 Notice that each execution of a <b>local</b> statement 1824 Notice that each execution of a <b>local</b> statement
1776 defines new local variables. 1825 defines new local variables.
1777 Consider the following example: 1826 Consider the following example:
1778 1827 </p>
1779 <pre> 1828 <pre>
1780 a = {} 1829 a = {}
1781 local x = 20 1830 local x = 20
1782 for i=1,10 do 1831 for i=1,10 do
1783 local y = 0 1832 local y = 0
1788 <p> 1837 <p>
1789 The loop creates ten closures 1838 The loop creates ten closures
1790 (that is, ten instances of the anonymous function). 1839 (that is, ten instances of the anonymous function).
1791 Each of these closures uses a different <code>y</code> variable, 1840 Each of these closures uses a different <code>y</code> variable,
1792 while all of them share the same <code>x</code>. 1841 while all of them share the same <code>x</code>.
1793 1842 </p>
1794 1843 <%
1795 1844 end
1796 1845 }
1797 1846 }
1798 <h2 heading><a name="libs" href="#libs">Standard Libraries</a></h2> 1847 }
1799 1848 libs = {
1849 title = "Standard Libraries"
1850 content = function()
1851 %>
1800 <p> 1852 <p>
1801 The standard Luan libraries provide useful functions 1853 The standard Luan libraries provide useful functions
1802 that are implemented both in Java and in Luan itself. 1854 that are implemented both in Java and in Luan itself.
1803 How each function is implemented shouldn't matter to the user. 1855 How each function is implemented shouldn't matter to the user.
1804 Some of these functions provide essential services to the language 1856 Some of these functions provide essential services to the language
1805 (e.g., <a href="#Luan.type"><code>type</code></a> and <a href="#Luan.get_metatable"><code>get_metatable</code></a>); 1857 (e.g., <a href="#Luan.type"><code>type</code></a> and <a href="#Luan.get_metatable"><code>get_metatable</code></a>);
1806 others provide access to "outside" services (e.g., I/O). 1858 others provide access to "outside" services (e.g., I/O).
1807 1859 </p>
1808 1860 <%
1809 <h3 heading><a name="default_lib" href="#default_lib">Default Environment</a></h3> 1861 end
1810 1862 subs = {
1863 default_lib = {
1864 title = "Default Environment"
1865 content = function()
1866 %>
1811 <p> 1867 <p>
1812 This is provided by default as a local variable for any Luan code as described in <a href="#env">Environments</a>. 1868 This is provided by default as a local variable for any Luan code as described in <a href="#env">Environments</a>.
1813 1869 </p>
1814 1870 <%
1815 <h4 heading><a name="require" href="#require"><code>require (mod_uri)</code></a></h4> 1871 end
1816 1872 subs = {
1873 require = {
1874 title = "<code>require (mod_uri)</code>"
1875 content = function()
1876 %>
1817 <p> 1877 <p>
1818 Example use: 1878 Example use:
1819 1879 </p>
1820 <pre> 1880 <pre>
1821 local Table = require "luan:Table.luan" 1881 local Table = require "luan:Table.luan"
1822 </pre> 1882 </pre>
1823 1883
1824 <p> 1884 <p>
1825 Could be defined as: 1885 Could be defined as:
1826 1886 </p>
1827 <pre> 1887 <pre>
1828 local function require(mod_name) 1888 local function require(mod_name)
1829 return <a href="#Package.load">Package.load</a>(mod_name) or <a href="#Luan.error">Luan.error</a>("module '"..mod_name.."' not found") 1889 return <a href="#Package.load">Package.load</a>(mod_name) or <a href="#Luan.error">Luan.error</a>("module '"..mod_name.."' not found")
1830 end 1890 end
1831 </pre> 1891 </pre>
1832 1892
1833 <p> 1893 <p>
1834 A special case is: 1894 A special case is:
1835 1895 </p>
1836 <pre> 1896 <pre>
1837 require "java" 1897 require "java"
1838 </pre> 1898 </pre>
1839 1899
1840 <p> 1900 <p>
1841 This enables Java in the current chunk if that chunk has permission to use Java. If the chunk doesn't have permission to use Java, then an error is thrown. 1901 This enables Java in the current chunk if that chunk has permission to use Java. If the chunk doesn't have permission to use Java, then an error is thrown.
1842 1902 </p>
1843 1903 <%
1844 <h3 heading><a name="luan_lib" href="#luan_lib">Basic Functions</a></h3> 1904 end
1845 1905 }
1906 }
1907 }
1908 luan_lib = {
1909 title = "Basic Functions"
1910 content = function()
1911 %>
1846 <p> 1912 <p>
1847 Include this library by: 1913 Include this library by:
1848 1914 </p>
1849 <pre> 1915 <pre>
1850 local Luan = require "luan:Luan.luan" 1916 local Luan = require "luan:Luan.luan"
1851 </pre> 1917 </pre>
1852 1918
1853 <p> 1919 <p>
1854 The basic library provides basic functions to Luan that don't depend on other libaries. 1920 The basic library provides basic functions to Luan that don't depend on other libaries.
1855 1921 </p>
1856 1922 <%
1857 <h4 heading><a name="Luan.do_file" href="#Luan.do_file"><code>Luan.do_file ([uri])</code></a></h4> 1923 end
1858 1924 subs = {
1925 ["Luan.do_file"] = {
1926 title = "<code>Luan.do_file ([uri])</code>"
1927 content = function()
1928 %>
1859 <p> 1929 <p>
1860 Could be defined as: 1930 Could be defined as:
1861 1931 </p>
1862 <pre> 1932 <pre>
1863 function Luan.do_file(uri) 1933 function Luan.do_file(uri)
1864 local fn = <a href="#Luan.load_file">Luan.load_file</a>(uri) or <a href="#Luan.error">Luan.error</a>("file '"..uri.."' not found") 1934 local fn = <a href="#Luan.load_file">Luan.load_file</a>(uri) or <a href="#Luan.error">Luan.error</a>("file '"..uri.."' not found")
1865 return fn() 1935 return fn()
1866 end 1936 end
1867 </pre> 1937 </pre>
1868 1938 <%
1869 1939 end
1870 1940 }
1871 <h4 heading><a name="Luan.error" href="#Luan.error"><code>Luan.error (message)</code></a></h4> 1941 ["Luan.error"] = {
1872 1942 title = "<code>Luan.error (message)</code>"
1943 content = function()
1944 %>
1873 <p> 1945 <p>
1874 Throws an error containing the message. 1946 Throws an error containing the message.
1947 </p>
1875 1948
1876 <p> 1949 <p>
1877 Could be defined as: 1950 Could be defined as:
1878 1951 </p>
1879 <pre> 1952 <pre>
1880 function Luan.error(message) 1953 function Luan.error(message)
1881 <a href="#Luan.new_error">Luan.new_error</a>(message).throw() 1954 <a href="#Luan.new_error">Luan.new_error</a>(message).throw()
1882 end 1955 end
1883 </pre> 1956 </pre>
1884 1957 <%
1885 1958 end
1886 1959 }
1887 <h4 heading><a name="Luan.eval" href="#Luan.eval"><code>Luan.eval (text [, source_name [, env]])</code></a></h4> 1960 ["Luan.eval"] = {
1888 1961 title = "<code>Luan.eval (text [, source_name [, env]])</code>"
1962 content = function()
1963 %>
1889 <p> 1964 <p>
1890 Evaluates <code>text</code> as a Luan expression. 1965 Evaluates <code>text</code> as a Luan expression.
1966 </p>
1891 1967
1892 <p> 1968 <p>
1893 Could be defined as: 1969 Could be defined as:
1894 1970 </p>
1895 <pre> 1971 <pre>
1896 function Luan.eval(text,source_name, env) 1972 function Luan.eval(text,source_name, env)
1897 return <a href="#Luan.load">Luan.load</a>( "return "..text, source_name or "eval", env )() 1973 return <a href="#Luan.load">Luan.load</a>( "return "..text, source_name or "eval", env )()
1898 end 1974 end
1899 </pre> 1975 </pre>
1900 1976 <%
1901 1977 end
1902 1978 }
1903 <h4 heading><a name="Luan.get_metatable" href="#Luan.get_metatable"><code>Luan.get_metatable (table)</code></a></h4> 1979 ["Luan.get_metatable"] = {
1904 1980 title = "<code>Luan.get_metatable (table)</code>"
1981 content = function()
1982 %>
1905 <p> 1983 <p>
1906 If <code>table</code> does not have a metatable, returns <b>nil</b>. 1984 If <code>table</code> does not have a metatable, returns <b>nil</b>.
1907 Otherwise, 1985 Otherwise,
1908 if the table's metatable has a <code>"__metatable"</code> field, 1986 if the table's metatable has a <code>"__metatable"</code> field,
1909 returns the associated value. 1987 returns the associated value.
1910 Otherwise, returns the metatable of the given table. 1988 Otherwise, returns the metatable of the given table.
1911 1989 </p>
1912 1990 <%
1913 <h4 heading><a name="Luan.hash_code" href="#Luan.ipairs"><code>Luan.hash_code (v)</code></a></h4> 1991 end
1914 1992 }
1993 ["Luan.hash_code"] = {
1994 title = "<code>Luan.hash_code (v)</code>"
1995 content = function()
1996 %>
1915 <p> 1997 <p>
1916 Returns the hash code of <code>v</code>. 1998 Returns the hash code of <code>v</code>.
1917 1999 </p>
1918 2000 <%
1919 <h4 heading><a name="Luan.ipairs" href="#Luan.ipairs"><code>Luan.ipairs (t)</code></a></h4> 2001 end
1920 2002 }
2003 ["Luan.ipairs"] = {
2004 title = "<code>Luan.ipairs (t)</code>"
2005 content = function()
2006 %>
1921 <p> 2007 <p>
1922 Returns an iterator function 2008 Returns an iterator function
1923 so that the construction 2009 so that the construction
1924 2010 </p>
1925 <pre> 2011 <pre>
1926 for i,v in ipairs(t) do <em>body</em> end 2012 for i,v in ipairs(t) do <em>body</em> end
1927 </pre> 2013 </pre>
1928 2014
1929 <p> 2015 <p>
1930 will iterate over the key&ndash;value pairs 2016 will iterate over the key&ndash;value pairs
1931 (<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., 2017 (<code>1,t[1]</code>), (<code>2,t[2]</code>), ...,
1932 up to the first nil value. 2018 up to the first nil value.
2019 </p>
1933 2020
1934 <p> 2021 <p>
1935 Could be defined as: 2022 Could be defined as:
1936 2023 </p>
1937 <pre> 2024 <pre>
1938 function Luan.ipairs(t) 2025 function Luan.ipairs(t)
1939 local i = 0 2026 local i = 0
1940 return function() 2027 return function()
1941 if i < #t then 2028 if i < #t then
1943 return i, t[i] 2030 return i, t[i]
1944 end 2031 end
1945 end 2032 end
1946 end 2033 end
1947 </pre> 2034 </pre>
1948 2035 <%
1949 2036 end
1950 2037 }
1951 <h4 heading><a name="Luan.load" href="#Luan.load"><code>Luan.load (text, [source_name [, env [, persist]]])</code></a></h4> 2038 ["Luan.load"] = {
1952 2039 title = "<code>Luan.load (text, [source_name [, env [, persist]]])</code>"
2040 content = function()
2041 %>
1953 <p> 2042 <p>
1954 Loads a chunk. 2043 Loads a chunk.
2044 </p>
1955 2045
1956 <p> 2046 <p>
1957 The <code>text</code> is compiled. 2047 The <code>text</code> is compiled.
1958 If there are no syntactic errors, 2048 If there are no syntactic errors,
1959 returns the compiled chunk as a function; 2049 returns the compiled chunk as a function;
1960 otherwise, throws an error. 2050 otherwise, throws an error.
2051 </p>
1961 2052
1962 <p> 2053 <p>
1963 The <code>source_name</code> parameter is a string saying where the text came from. It is used to produce error messages. Defaults to "load". 2054 The <code>source_name</code> parameter is a string saying where the text came from. It is used to produce error messages. Defaults to "load".
2055 </p>
1964 2056
1965 <p> 2057 <p>
1966 If the <code>env</code> parameter is supplied, it becomes the <code>_ENV</code> of the chunk. 2058 If the <code>env</code> parameter is supplied, it becomes the <code>_ENV</code> of the chunk.
2059 </p>
1967 2060
1968 <p> 2061 <p>
1969 The <code>persist</code> parameter is a boolean which determines if the compiled code is persistently cached to a temporary file. Defaults to <code>false</code>. 2062 The <code>persist</code> parameter is a boolean which determines if the compiled code is persistently cached to a temporary file. Defaults to <code>false</code>.
1970 2063 </p>
1971 2064 <%
1972 <h4 heading><a name="Luan.load_file" href="#Luan.load_file"><code>Luan.load_file (file_uri)</code></a></h4> 2065 end
1973 2066 }
2067 ["Luan.load_file"] = {
2068 title = "<code>Luan.load_file (file_uri)</code>"
2069 content = function()
2070 %>
1974 <p> 2071 <p>
1975 Similar to <a href="#Luan.load"><code>load</code></a>, 2072 Similar to <a href="#Luan.load"><code>load</code></a>,
1976 but gets the chunk from file <code>file_uri</code>. 2073 but gets the chunk from file <code>file_uri</code>.
1977 <code>file_uri</code> can be a string or a uri table. 2074 <code>file_uri</code> can be a string or a uri table.
1978 2075 </p>
1979 2076 <%
1980 <h4 heading><a name="Luan.new_error" href="#Luan.new_error"><code>Luan.new_error (message)</code></a></h4> 2077 end
1981 2078 }
2079 ["Luan.new_error"] = {
2080 title = "<code>Luan.new_error (message)</code>"
2081 content = function()
2082 %>
1982 <p> 2083 <p>
1983 Creates a new error table containing the message assigned to "<code>message</code>". The error table also contains a <code>throw</code> function which throws the error. The table also contains a list of stack trace elements where each stack trace element is a table containing "<code>source</code>", "<code>line</code>", and possible "<code>call_to</code>". The table also has a metatable containing "<code>__to_string</code>" to render the error. 2084 Creates a new error table containing the message assigned to "<code>message</code>". The error table also contains a <code>throw</code> function which throws the error. The table also contains a list of stack trace elements where each stack trace element is a table containing "<code>source</code>", "<code>line</code>", and possible "<code>call_to</code>". The table also has a metatable containing "<code>__to_string</code>" to render the error.
2085 </p>
1984 2086
1985 <p> 2087 <p>
1986 To print the current stack trace, you could do: 2088 To print the current stack trace, you could do:
1987 2089 </p>
1988 <pre> 2090 <pre>
1989 Io.print( Luan.new_error "stack" ) 2091 Io.print( Luan.new_error "stack" )
1990 </pre> 2092 </pre>
1991 2093 <%
1992 2094 end
1993 <h4 heading><a name="Luan.pairs" href="#Luan.pairs"><code>Luan.pairs (t)</code></a></h4> 2095 }
1994 2096 ["Luan.pairs"] = {
2097 title = "<code>Luan.pairs (t)</code>"
2098 content = function()
2099 %>
1995 <p> 2100 <p>
1996 If <code>t</code> has a metamethod <code>__pairs</code>, 2101 If <code>t</code> has a metamethod <code>__pairs</code>,
1997 calls it with <code>t</code> as argument and returns the 2102 calls it with <code>t</code> as argument and returns the
1998 result from the call. 2103 result from the call.
1999 2104 </p>
2000 2105
2001 <p> 2106 <p>
2002 Otherwise, 2107 Otherwise,
2003 returns a function 2108 returns a function
2004 so that the construction 2109 so that the construction
2005 2110 </p>
2006 <pre> 2111 <pre>
2007 for k,v in pairs(t) do <em>body</em> end 2112 for k,v in pairs(t) do <em>body</em> end
2008 </pre> 2113 </pre>
2009 2114
2010 <p> 2115 <p>
2011 will iterate over all key&ndash;value pairs of table <code>t</code>. 2116 will iterate over all key&ndash;value pairs of table <code>t</code>.
2012 2117 </p>
2013 2118 <%
2014 2119 end
2015 <p> 2120 }
2016 <hr><h3><a name="pdf-print"><code>print (&middot;&middot;&middot;)</code></a></h3> 2121 ["Luan.range"] = {
2017 Receives any number of arguments 2122 title = "<code>Luan.range (start, stop [, step])</code>"
2018 and prints their values to <code>stdout</code>, 2123 content = function()
2019 using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string. 2124 %>
2020 <code>print</code> is not intended for formatted output,
2021 but only as a quick way to show a value,
2022 for instance for debugging.
2023 For complete control over the output,
2024 use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>.
2025
2026
2027
2028 <h4 heading><a name="Luan.range" href="#Luan.range"><code>Luan.range (start, stop [, step])</code></a></h4>
2029
2030 <p> 2125 <p>
2031 Based on <a href="https://docs.python.org/2/library/functions.html#range">the Python range() function</a>, this lets one iterate through a sequence of numbers. 2126 Based on <a href="https://docs.python.org/2/library/functions.html#range">the Python range() function</a>, this lets one iterate through a sequence of numbers.
2127 </p>
2032 2128
2033 <p> 2129 <p>
2034 Example use: 2130 Example use:
2035 2131 </p>
2036 <pre> 2132 <pre>
2037 for i in range(1,10) do 2133 for i in range(1,10) do
2038 Io.print("count up:",i) 2134 Io.print("count up:",i)
2039 end 2135 end
2040 for i in range(10,0,-1) do 2136 for i in range(10,0,-1) do
2042 end 2138 end
2043 </pre> 2139 </pre>
2044 2140
2045 <p> 2141 <p>
2046 Could be defined as: 2142 Could be defined as:
2047 2143 </p>
2048 <pre> 2144 <pre>
2049 function Luan.range(start, stop, step) 2145 function Luan.range(start, stop, step)
2050 step = step or 1 2146 step = step or 1
2051 step == 0 and <a href="#Luan.error">Luan.error</a> "bad argument #3 (step may not be zero)" 2147 step == 0 and <a href="#Luan.error">Luan.error</a> "bad argument #3 (step may not be zero)"
2052 local i = start 2148 local i = start
2057 return rtn 2153 return rtn
2058 end 2154 end
2059 end 2155 end
2060 end 2156 end
2061 </pre> 2157 </pre>
2062 2158 <%
2063 2159 end
2064 2160 }
2065 <h4 heading><a name="Luan.raw_equal" href="#Luan.raw_equal"><code>Luan.raw_equal (v1, v2)</code></a></h4> 2161 ["Luan.raw_equal"] = {
2066 2162 title = "<code>Luan.raw_equal (v1, v2)</code>"
2163 content = function()
2164 %>
2067 <p> 2165 <p>
2068 Checks whether <code>v1</code> is equal to <code>v2</code>, 2166 Checks whether <code>v1</code> is equal to <code>v2</code>,
2069 without invoking any metamethod. 2167 without invoking any metamethod.
2070 Returns a boolean. 2168 Returns a boolean.
2071 2169 </p>
2072 2170 <%
2073 2171 end
2074 <h4 heading><a name="Luan.raw_get" href="#Luan.raw_get"><code>Luan.raw_get (table, index)</code></a></h4> 2172 }
2075 2173 ["Luan.raw_get"] = {
2174 title = "<code>Luan.raw_get (table, index)</code>"
2175 content = function()
2176 %>
2076 <p> 2177 <p>
2077 Gets the real value of <code>table[index]</code>, 2178 Gets the real value of <code>table[index]</code>,
2078 without invoking any metamethod. 2179 without invoking any metamethod.
2079 <code>table</code> must be a table; 2180 <code>table</code> must be a table;
2080 <code>index</code> may be any value. 2181 <code>index</code> may be any value.
2081 2182 </p>
2082 2183 <%
2083 2184 end
2084 <h4 heading><a name="Luan.raw_len" href="#Luan.raw_len"><code>Luan.raw_len (v)</code></a></h4> 2185 }
2085 2186 ["Luan.raw_len"] = {
2187 title = "<code>Luan.raw_len (v)</code>"
2188 content = function()
2189 %>
2086 <p> 2190 <p>
2087 Returns the length of the object <code>v</code>, 2191 Returns the length of the object <code>v</code>,
2088 which must be a table or a string, 2192 which must be a table or a string,
2089 without invoking any metamethod. 2193 without invoking any metamethod.
2090 Returns an integer. 2194 Returns an integer.
2091 2195 </p>
2092 2196 <%
2093 2197 end
2094 <h4 heading><a name="Luan.raw_set" href="#Luan.raw_set"><code>Luan.raw_set (table, index, value)</code></a></h4> 2198 }
2095 2199 ["Luan.raw_set"] = {
2200 title = "<code>Luan.raw_set (table, index, value)</code>"
2201 content = function()
2202 %>
2096 <p> 2203 <p>
2097 Sets the real value of <code>table[index]</code> to <code>value</code>, 2204 Sets the real value of <code>table[index]</code> to <code>value</code>,
2098 without invoking any metamethod. 2205 without invoking any metamethod.
2099 <code>table</code> must be a table, 2206 <code>table</code> must be a table,
2100 <code>index</code> any value different from <b>nil</b>, 2207 <code>index</code> any value different from <b>nil</b>,
2101 and <code>value</code> any Lua value. 2208 and <code>value</code> any Luan value.
2102 2209 </p>
2103 2210 <%
2104 <h4 heading><a name="Luan.set_metatable" href="#Luan.set_metatable"><code>Luan.set_metatable (table, metatable)</code></a></h4> 2211 end
2105 2212 }
2213 ["Luan.set_metatable"] = {
2214 title = "<code>Luan.set_metatable (table, metatable)</code>"
2215 content = function()
2216 %>
2106 <p> 2217 <p>
2107 Sets the metatable for the given table. 2218 Sets the metatable for the given table.
2108 If <code>metatable</code> is <b>nil</b>, 2219 If <code>metatable</code> is <b>nil</b>,
2109 removes the metatable of the given table. 2220 removes the metatable of the given table.
2110 If the original metatable has a <code>"__metatable"</code> field, 2221 If the original metatable has a <code>"__metatable"</code> field,
2111 raises an error. 2222 raises an error.
2112 2223 </p>
2113 2224 <%
2114 <h4 heading><a name="Luan.stringify" href="#Luan.stringify"><code>Luan.stringify (v [,options])</code></a></h4> 2225 end
2115 2226 }
2227 ["Luan.stringify"] = {
2228 title = "<code>Luan.stringify (v [,options])</code>"
2229 content = function()
2230 %>
2116 <p> 2231 <p>
2117 Receives a value of any type and converts it to a string that is a Luan expression. <code>options</code> is a table. If <code>options.strict==true</code> then invalid types throw an error. Otherwise invalid types are represented but the resulting expression is invalid. If <code>options.number_types==true</code> then numbers will be wrapped in functions for their type. 2232 Receives a value of any type and converts it to a string that is a Luan expression. <code>options</code> is a table. If <code>options.strict==true</code> then invalid types throw an error. Otherwise invalid types are represented but the resulting expression is invalid. If <code>options.number_types==true</code> then numbers will be wrapped in functions for their type.
2118 2233 </p>
2119 2234 <%
2120 <h4 heading><a name="Luan.to_string" href="#Luan.to_string"><code>Luan.to_string (v)</code></a></h4> 2235 end
2121 2236 }
2237 ["Luan.to_string"] = {
2238 title = "<code>Luan.to_string (v)</code>"
2239 content = function()
2240 %>
2122 <p> 2241 <p>
2123 Receives a value of any type and 2242 Receives a value of any type and
2124 converts it to a string in a human-readable format. 2243 converts it to a string in a human-readable format.
2244 </p>
2125 2245
2126 <p> 2246 <p>
2127 If the metatable of <code>v</code> has a <code>"__to_string"</code> field, 2247 If the metatable of <code>v</code> has a <code>"__to_string"</code> field,
2128 then <code>to_string</code> calls the corresponding value 2248 then <code>to_string</code> calls the corresponding value
2129 with <code>v</code> as argument, 2249 with <code>v</code> as argument,
2130 and uses the result of the call as its result. 2250 and uses the result of the call as its result.
2131 2251 </p>
2132 2252 <%
2133 2253 end
2134 <h4 heading><a name="Luan.type" href="#Luan.type"><code>Luan.type (v)</code></a></h4> 2254 }
2135 2255 ["Luan.type"] = {
2256 title = "<code>Luan.type (v)</code>"
2257 content = function()
2258 %>
2136 <p> 2259 <p>
2137 Returns the type of its only argument, coded as a string. 2260 Returns the type of its only argument, coded as a string.
2138 The possible results of this function are 2261 The possible results of this function are
2139 "<code>nil</code>" (a string, not the value <b>nil</b>), 2262 "<code>nil</code>" (a string, not the value <b>nil</b>),
2140 "<code>number</code>", 2263 "<code>number</code>",
2142 "<code>binary</code>", 2265 "<code>binary</code>",
2143 "<code>boolean</code>", 2266 "<code>boolean</code>",
2144 "<code>table</code>", 2267 "<code>table</code>",
2145 "<code>function</code>", 2268 "<code>function</code>",
2146 and "<code>java</code>". 2269 and "<code>java</code>".
2147 2270 </p>
2148 2271 <%
2149 <h4 heading><a name="Luan.values" href="#Luan.values"><code>Luan.values (&middot;&middot;&middot;)</code></a></h4> 2272 end
2150 2273 }
2274 ["Luan.values"] = {
2275 title = "<code>Luan.values (&middot;&middot;&middot;)</code>"
2276 content = function()
2277 %>
2151 <p> 2278 <p>
2152 Returns a function so that the construction 2279 Returns a function so that the construction
2153 2280 </p>
2154 <pre> 2281 <pre>
2155 for i, v in Luan.values(&middot;&middot;&middot;) do <em>body</em> end 2282 for i, v in Luan.values(&middot;&middot;&middot;) do <em>body</em> end
2156 </pre> 2283 </pre>
2157 2284
2158 <p> 2285 <p>
2159 will iterate over all values of <code>&middot;&middot;&middot;</code>. 2286 will iterate over all values of <code>&middot;&middot;&middot;</code>.
2160 2287 </p>
2161 2288 <%
2162 2289 end
2163 <h4 heading><a name="Luan.VERSION" href="#Luan.VERSION"><code>Luan.VERSION</code></a></h4> 2290 }
2164 2291 ["Luan.VERSION"] = {
2292 title = "<code>Luan.VERSION</code>"
2293 content = function()
2294 %>
2165 <p> 2295 <p>
2166 A global variable (not a function) that 2296 A global variable (not a function) that
2167 holds a string containing the current Luan version. 2297 holds a string containing the current Luan version.
2168 2298 </p>
2169 2299 <%
2170 2300 end
2171 2301 }
2172 2302 }
2173 2303 }
2174 <h3 heading><a name="package_lib" href="#package_lib">Modules</a></h3> 2304 package_lib = {
2175 2305 title = "Modules"
2306 content = function()
2307 %>
2176 <p> 2308 <p>
2177 Include this library by: 2309 Include this library by:
2178 2310 </p>
2179 <pre> 2311 <pre>
2180 local Package = require "luan:Package.luan" 2312 local Package = require "luan:Package.luan"
2181 </pre> 2313 </pre>
2182 2314
2183 <p> 2315 <p>
2184 The package library provides basic 2316 The package library provides basic
2185 facilities for loading modules in Luan. 2317 facilities for loading modules in Luan.
2186 2318 </p>
2187 2319 <%
2188 <h4 heading><a name="Package.load" href="#Package.load"><code>Package.load (mod_uri)</code></a></h4> 2320 end
2189 2321 subs = {
2322 ["Package.load"] = {
2323 title = "<code>Package.load (mod_uri)</code>"
2324 content = function()
2325 %>
2190 <p> 2326 <p>
2191 Loads the given module. 2327 Loads the given module.
2192 The function starts by looking into the <a href="#Package.loaded"><code>Package.loaded</code></a> table 2328 The function starts by looking into the <a href="#Package.loaded"><code>Package.loaded</code></a> table
2193 to determine whether <code>mod_uri</code> is already loaded. 2329 to determine whether <code>mod_uri</code> is already loaded.
2194 If it is, then <code>Package.load</code> returns the value stored 2330 If it is, then <code>Package.load</code> returns the value stored
2195 at <code>Package.loaded[mod_uri]</code>. 2331 at <code>Package.loaded[mod_uri]</code>.
2196 Otherwise, it tries to load a new value for the module. 2332 Otherwise, it tries to load a new value for the module.
2333 </p>
2197 2334
2198 <p> 2335 <p>
2199 To load a new value, <code>Package.load</code> first checks if <code>mod_uri</code> starts with "<b>java:</b>". If yes, then this is a Java class which is loaded by special Java code. 2336 To load a new value, <code>Package.load</code> first checks if <code>mod_uri</code> starts with "<b>java:</b>". If yes, then this is a Java class which is loaded by special Java code.
2337 </p>
2200 2338
2201 <p> 2339 <p>
2202 Otherwise <code>Package.load</code> tries to read the text of the file referred to by <code>mod_uri</code>. If the file doesn't exist, then <code>Package.load</code> returns <b>false</b>. If the file exists, then its content is compiled into a chunk by calling <a href="#Luan.load"><code>Luan.load</code></a>. This chunk is run passing in <code>mod_uri</code> as an argument. The value returned by the chunk must not be <b>nil</b> and is loaded. 2340 Otherwise <code>Package.load</code> tries to read the text of the file referred to by <code>mod_uri</code>. If the file doesn't exist, then <code>Package.load</code> returns <b>false</b>. If the file exists, then its content is compiled into a chunk by calling <a href="#Luan.load"><code>Luan.load</code></a>. This chunk is run passing in <code>mod_uri</code> as an argument. The value returned by the chunk must not be <b>nil</b> and is loaded.
2341 </p>
2203 2342
2204 <p> 2343 <p>
2205 If a new value for the module successful loaded, then it is stored in <code>Package.loaded[mod_uri]</code>. The value is returned. 2344 If a new value for the module successful loaded, then it is stored in <code>Package.loaded[mod_uri]</code>. The value is returned.
2206 2345 </p>
2207 2346 <%
2208 2347 end
2209 2348 }
2210 <h4 heading><a name="Package.loaded" href="#Package.loaded"><code>Package.loaded</code></a></h4> 2349 ["Package.loaded"] = {
2211 2350 title = "<code>Package.loaded</code>"
2212 2351 content = function()
2352 %>
2213 <p> 2353 <p>
2214 A table used by <a href="#Package.load"><code>Package.load</code></a> to control which 2354 A table used by <a href="#Package.load"><code>Package.load</code></a> to control which
2215 modules are already loaded. 2355 modules are already loaded.
2216 When you load a module <code>mod_uri</code> and 2356 When you load a module <code>mod_uri</code> and
2217 <code>Package.loaded[mod_uri]</code> is not <b>nil</b>, 2357 <code>Package.loaded[mod_uri]</code> is not <b>nil</b>,
2218 <a href="#Package.load"><code>Package.load</code></a> simply returns the value stored there. 2358 <a href="#Package.load"><code>Package.load</code></a> simply returns the value stored there.
2219 2359 </p>
2220 2360
2221 <p> 2361 <p>
2222 This variable is only a reference to the real table; 2362 This variable is only a reference to the real table;
2223 assignments to this variable do not change the 2363 assignments to this variable do not change the
2224 table used by <a href="#Package.load"><code>Package.load</code></a>. 2364 table used by <a href="#Package.load"><code>Package.load</code></a>.
2225 2365 </p>
2226 2366 <%
2227 2367 end
2228 2368 }
2229 2369 }
2230 2370 }
2231 <h3 heading><a name="string_lib" href="#string_lib">String Manipulation</a></h3> 2371 string_lib = {
2232 2372 title = "String Manipulation"
2373 content = function()
2374 %>
2233 <p> 2375 <p>
2234 Include this library by: 2376 Include this library by:
2235 2377 </p>
2236 <pre> 2378 <pre>
2237 local String = require "luan:String.luan" 2379 local String = require "luan:String.luan"
2238 </pre> 2380 </pre>
2239 2381
2240 <p> 2382 <p>
2243 When indexing a string in Luan, the first character is at position&nbsp;1 2385 When indexing a string in Luan, the first character is at position&nbsp;1
2244 (not at&nbsp;0, as in Java). 2386 (not at&nbsp;0, as in Java).
2245 Indices are allowed to be negative and are interpreted as indexing backwards, 2387 Indices are allowed to be negative and are interpreted as indexing backwards,
2246 from the end of the string. 2388 from the end of the string.
2247 Thus, the last character is at position -1, and so on. 2389 Thus, the last character is at position -1, and so on.
2248 2390 </p>
2249 2391 <%
2250 2392 end
2251 <h4 heading><a name="String.char" href="#String.char"><code>String.char (&middot;&middot;&middot;)</code></a></h4> 2393 subs = {
2252 2394 ["String.char"] = {
2395 title = "<code>String.char (&middot;&middot;&middot;)</code>"
2396 content = function()
2397 %>
2253 <p> 2398 <p>
2254 Receives zero or more integers. 2399 Receives zero or more integers.
2255 Returns a string with length equal to the number of arguments, 2400 Returns a string with length equal to the number of arguments,
2256 in which each character has the internal numerical code equal 2401 in which each character has the internal numerical code equal
2257 to its corresponding argument. 2402 to its corresponding argument.
2258 2403 </p>
2259 2404 <%
2260 <h4 heading><a name="String.encode" href="#String.encode"><code>String.encode (s)</code></a></h4> 2405 end
2261 2406 }
2407 ["String.encode"] = {
2408 title = "<code>String.encode (s)</code>"
2409 content = function()
2410 %>
2262 <p> 2411 <p>
2263 Encodes argument <code>s</code> into a string that can be placed in quotes so as to return the original value of the string. 2412 Encodes argument <code>s</code> into a string that can be placed in quotes so as to return the original value of the string.
2264 2413 </p>
2265 2414 <%
2266 2415 end
2267 2416 }
2268 <h4 heading><a name="String.find" href="#String.find"><code>String.find (s, pattern [, init [, plain]])</code></a></h4> 2417 ["String.find"] = {
2269 2418 title = "<code>String.find (s, pattern [, init [, plain]])</code>"
2419 content = function()
2420 %>
2270 <p> 2421 <p>
2271 Looks for the first match of 2422 Looks for the first match of
2272 <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) in the string <code>s</code>. 2423 <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) in the string <code>s</code>.
2273 If it finds a match, then <code>find</code> returns the indices of&nbsp;<code>s</code> 2424 If it finds a match, then <code>find</code> returns the indices of&nbsp;<code>s</code>
2274 where this occurrence starts and ends; 2425 where this occurrence starts and ends;
2279 A value of <b>true</b> as a fourth, optional argument <code>plain</code> 2430 A value of <b>true</b> as a fourth, optional argument <code>plain</code>
2280 turns off the pattern matching facilities, 2431 turns off the pattern matching facilities,
2281 so the function does a plain "find substring" operation, 2432 so the function does a plain "find substring" operation,
2282 with no characters in <code>pattern</code> being considered magic. 2433 with no characters in <code>pattern</code> being considered magic.
2283 Note that if <code>plain</code> is given, then <code>init</code> must be given as well. 2434 Note that if <code>plain</code> is given, then <code>init</code> must be given as well.
2435 </p>
2284 2436
2285 <p> 2437 <p>
2286 If the pattern has captures, 2438 If the pattern has captures,
2287 then in a successful match 2439 then in a successful match
2288 the captured values are also returned, 2440 the captured values are also returned,
2289 after the two indices. 2441 after the two indices.
2290 2442 </p>
2291 2443 <%
2292 2444 end
2293 2445 }
2294 <h4 heading><a name="String.format" href="#String.format"><code>String.format (formatstring, &middot;&middot;&middot;)</code></a></h4> 2446 ["String.format"] = {
2295 2447 title = "<code>String.format (formatstring, &middot;&middot;&middot;)</code>"
2296 2448 content = function()
2449 %>
2297 <p> 2450 <p>
2298 Returns a formatted version of its variable number of arguments 2451 Returns a formatted version of its variable number of arguments
2299 following the description given in its first argument (which must be a string). 2452 following the description given in its first argument (which must be a string).
2300 The format string follows the same rules as the Java function <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#format(java.lang.String,%20java.lang.Object...)"><code>String.format</code></a> because Luan calls this internally. 2453 The format string follows the same rules as the Java function <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#format(java.lang.String,%20java.lang.Object...)"><code>String.format</code></a> because Luan calls this internally.
2454 </p>
2301 2455
2302 <p> 2456 <p>
2303 Note that Java's <code>String.format</code> is too stupid to convert between ints and floats, so you must provide the right kind of number. 2457 Note that Java's <code>String.format</code> is too stupid to convert between ints and floats, so you must provide the right kind of number.
2304 2458 </p>
2305 2459 <%
2306 2460 end
2307 <h4 heading><a name="String.gmatch" href="#String.gmatch"><code>String.gmatch (s, pattern)</code></a></h4> 2461 }
2308 2462 ["String.gmatch"] = {
2463 title = "<code>String.gmatch (s, pattern)</code>"
2464 content = function()
2465 %>
2309 <p> 2466 <p>
2310 Returns an iterator function that, 2467 Returns an iterator function that,
2311 each time it is called, 2468 each time it is called,
2312 returns the next captures from <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) 2469 returns the next captures from <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>)
2313 over the string <code>s</code>. 2470 over the string <code>s</code>.
2314 If <code>pattern</code> specifies no captures, 2471 If <code>pattern</code> specifies no captures,
2315 then the whole match is produced in each call. 2472 then the whole match is produced in each call.
2316 2473 </p>
2317 2474
2318 <p> 2475 <p>
2319 As an example, the following loop 2476 As an example, the following loop
2320 will iterate over all the words from string <code>s</code>, 2477 will iterate over all the words from string <code>s</code>,
2321 printing one per line: 2478 printing one per line:
2322 2479 </p>
2323 <pre> 2480 <pre>
2324 local s = "hello world from Lua" 2481 local s = "hello world from Lua"
2325 for w in String.gmatch(s, [[\w+]]) do 2482 for w in String.gmatch(s, [[\w+]]) do
2326 print(w) 2483 print(w)
2327 end 2484 end
2328 </pre> 2485 </pre>
2329 2486
2330 <p> 2487 <p>
2331 The next example collects all pairs <code>key=value</code> from the 2488 The next example collects all pairs <code>key=value</code> from the
2332 given string into a table: 2489 given string into a table:
2333 2490 </p>
2334 <pre> 2491 <pre>
2335 local t = {} 2492 local t = {}
2336 local s = "from=world, to=Lua" 2493 local s = "from=world, to=Lua"
2337 for k, v in String.gmatch(s, [[(\w+)=(\w+)]]) do 2494 for k, v in String.gmatch(s, [[(\w+)=(\w+)]]) do
2338 t[k] = v 2495 t[k] = v
2340 </pre> 2497 </pre>
2341 2498
2342 <p> 2499 <p>
2343 For this function, a caret '<code>^</code>' at the start of a pattern does not 2500 For this function, a caret '<code>^</code>' at the start of a pattern does not
2344 work as an anchor, as this would prevent the iteration. 2501 work as an anchor, as this would prevent the iteration.
2345 2502 </p>
2346 2503 <%
2347 2504 end
2348 <h4 heading><a name="String.gsub" href="#String.gsub"><code>String.gsub (s, pattern, repl [, n])</code></a></h4> 2505 }
2349 2506 ["String.gsub"] = {
2507 title = "<code>String.gsub (s, pattern, repl [, n])</code>"
2508 content = function()
2509 %>
2350 <p> 2510 <p>
2351 Returns a copy of <code>s</code> 2511 Returns a copy of <code>s</code>
2352 in which all (or the first <code>n</code>, if given) 2512 in which all (or the first <code>n</code>, if given)
2353 occurrences of the <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) have been 2513 occurrences of the <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) have been
2354 replaced by a replacement string specified by <code>repl</code>, 2514 replaced by a replacement string specified by <code>repl</code>,
2355 which can be a string, a table, or a function. 2515 which can be a string, a table, or a function.
2356 <code>gsub</code> also returns, as its second value, 2516 <code>gsub</code> also returns, as its second value,
2357 the total number of matches that occurred. 2517 the total number of matches that occurred.
2358 The name <code>gsub</code> comes from <em>Global SUBstitution</em>. 2518 The name <code>gsub</code> comes from <em>Global SUBstitution</em>.
2359 2519 </p>
2360 2520
2361 <p> 2521 <p>
2362 If <code>repl</code> is a string, then its value is used for replacement. 2522 If <code>repl</code> is a string, then its value is used for replacement.
2363 The character&nbsp;<code>\</code> works as an escape character. 2523 The character&nbsp;<code>\</code> works as an escape character.
2364 Any sequence in <code>repl</code> of the form <code>$<em>d</em></code>, 2524 Any sequence in <code>repl</code> of the form <code>$<em>d</em></code>,
2365 with <em>d</em> between 1 and 9, 2525 with <em>d</em> between 1 and 9,
2366 stands for the value of the <em>d</em>-th captured substring. 2526 stands for the value of the <em>d</em>-th captured substring.
2367 The sequence <code>$0</code> stands for the whole match. 2527 The sequence <code>$0</code> stands for the whole match.
2368 2528 </p>
2369 2529
2370 <p> 2530 <p>
2371 If <code>repl</code> is a table, then the table is queried for every match, 2531 If <code>repl</code> is a table, then the table is queried for every match,
2372 using the first capture as the key. 2532 using the first capture as the key.
2373 2533 </p>
2374 2534
2375 <p> 2535 <p>
2376 If <code>repl</code> is a function, then this function is called every time a 2536 If <code>repl</code> is a function, then this function is called every time a
2377 match occurs, with all captured substrings passed as arguments, 2537 match occurs, with all captured substrings passed as arguments,
2378 in order. 2538 in order.
2379 2539 </p>
2380 2540
2381 <p> 2541 <p>
2382 In any case, 2542 In any case,
2383 if the pattern specifies no captures, 2543 if the pattern specifies no captures,
2384 then it behaves as if the whole pattern was inside a capture. 2544 then it behaves as if the whole pattern was inside a capture.
2385 2545 </p>
2386 2546
2387 <p> 2547 <p>
2388 If the value returned by the table query or by the function call 2548 If the value returned by the table query or by the function call
2389 is not <b>nil</b>, 2549 is not <b>nil</b>,
2390 then it is used as the replacement string; 2550 then it is used as the replacement string;
2391 otherwise, if it is <b>nil</b>, 2551 otherwise, if it is <b>nil</b>,
2392 then there is no replacement 2552 then there is no replacement
2393 (that is, the original match is kept in the string). 2553 (that is, the original match is kept in the string).
2394 2554 </p>
2395 2555
2396 <p> 2556 <p>
2397 Here are some examples: 2557 Here are some examples:
2398 2558 </p>
2399 <pre> 2559 <pre>
2400 x = String.gsub("hello world", [[(\w+)]], "$1 $1") 2560 x = String.gsub("hello world", [[(\w+)]], "$1 $1")
2401 --&gt; x="hello hello world world" 2561 --&gt; x="hello hello world world"
2402 2562
2403 x = String.gsub("hello world", [[\w+]], "$0 $0", 1) 2563 x = String.gsub("hello world", [[\w+]], "$0 $0", 1)
2413 2573
2414 local t = {name="lua", version="5.3"} 2574 local t = {name="lua", version="5.3"}
2415 x = String.gsub("$name-$version.tar.gz", [[\$(\w+)]], t) 2575 x = String.gsub("$name-$version.tar.gz", [[\$(\w+)]], t)
2416 --&gt; x="lua-5.3.tar.gz" 2576 --&gt; x="lua-5.3.tar.gz"
2417 </pre> 2577 </pre>
2418 2578 <%
2419 2579 end
2420 <h4 heading><a name="String.lower" href="#String.lower"><code>String.lower (s)</code></a></h4> 2580 }
2581 ["String.lower"] = {
2582 title = "<code>String.lower (s)</code>"
2583 content = function()
2584 %>
2421 <p> 2585 <p>
2422 Receives a string and returns a copy of this string with all 2586 Receives a string and returns a copy of this string with all
2423 uppercase letters changed to lowercase. 2587 uppercase letters changed to lowercase.
2424 All other characters are left unchanged. 2588 All other characters are left unchanged.
2425 2589 </p>
2426 2590 <%
2427 2591 end
2428 <h4 heading><a name="String.match" href="#String.match"><code>String.match (s, pattern [, init])</code></a></h4> 2592 }
2429 2593 ["String.match"] = {
2594 title = "<code>String.match (s, pattern [, init])</code>"
2595 content = function()
2596 %>
2430 <p> 2597 <p>
2431 Looks for the first <em>match</em> of 2598 Looks for the first <em>match</em> of
2432 <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) in the string <code>s</code>. 2599 <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) in the string <code>s</code>.
2433 If it finds one, then <code>match</code> returns 2600 If it finds one, then <code>match</code> returns
2434 the captures from the pattern; 2601 the captures from the pattern;
2436 If <code>pattern</code> specifies no captures, 2603 If <code>pattern</code> specifies no captures,
2437 then the whole match is returned. 2604 then the whole match is returned.
2438 A third, optional numerical argument <code>init</code> specifies 2605 A third, optional numerical argument <code>init</code> specifies
2439 where to start the search; 2606 where to start the search;
2440 its default value is&nbsp;1 and can be negative. 2607 its default value is&nbsp;1 and can be negative.
2441 2608 </p>
2442 2609 <%
2443 <h4 heading><a name="String.matches" href="#String.matches"><code>String.matches (s, pattern)</code></a></h4> 2610 end
2611 }
2612 ["String.matches"] = {
2613 title = "<code>String.matches (s, pattern)</code>"
2614 content = function()
2615 %>
2444 <p> 2616 <p>
2445 Returns a boolean indicating whether the <code>pattern</code> can be found in string <code>s</code>. 2617 Returns a boolean indicating whether the <code>pattern</code> can be found in string <code>s</code>.
2446 This function is equivalent to 2618 This function is equivalent to
2447 2619 </p>
2448 <pre> 2620 <pre>
2449 return String.match(s,pattern) ~= nil 2621 return String.match(s,pattern) ~= nil
2450 </pre> 2622 </pre>
2451 2623 <%
2452 2624 end
2453 <h4 heading><a name="String.regex_quote" href="#String.regex_quote"><code>String.regex_quote (s)</code></a></h4> 2625 }
2626 ["String.regex_quote"] = {
2627 title = "<code>String.regex_quote (s)</code>"
2628 content = function()
2629 %>
2454 <p> 2630 <p>
2455 Returns a string which matches the literal string <code>s</code> in a regular expression. This function is simply the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html#quote(java.lang.String)"><code>Pattern.quote</code></a>. 2631 Returns a string which matches the literal string <code>s</code> in a regular expression. This function is simply the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html#quote(java.lang.String)"><code>Pattern.quote</code></a>.
2456 2632 </p>
2457 2633 <%
2458 <h4 heading><a name="String.rep" href="#String.rep"><code>String.rep (s, n [, sep])</code></a></h4> 2634 end
2635 }
2636 ["String.rep"] = {
2637 title = "<code>String.rep (s, n [, sep])</code>"
2638 content = function()
2639 %>
2459 <p> 2640 <p>
2460 Returns a string that is the concatenation of <code>n</code> copies of 2641 Returns a string that is the concatenation of <code>n</code> copies of
2461 the string <code>s</code> separated by the string <code>sep</code>. 2642 the string <code>s</code> separated by the string <code>sep</code>.
2462 The default value for <code>sep</code> is the empty string 2643 The default value for <code>sep</code> is the empty string
2463 (that is, no separator). 2644 (that is, no separator).
2464 Returns the empty string if <code>n</code> is not positive. 2645 Returns the empty string if <code>n</code> is not positive.
2465 2646 </p>
2466 2647 <%
2467 2648 end
2468 2649 }
2469 <h4 heading><a name="String.reverse" href="#String.reverse"><code>String.reverse (s)</code></a></h4> 2650 ["String.reverse"] = {
2651 title = "<code>String.reverse (s)</code>"
2652 content = function()
2653 %>
2470 <p> 2654 <p>
2471 Returns a string that is the string <code>s</code> reversed. 2655 Returns a string that is the string <code>s</code> reversed.
2472 2656 </p>
2473 2657 <%
2474 2658 end
2475 <h4 heading><a name="String.split" href="#String.match"><code>String.split (s, pattern [, limit])</code></a></h4> 2659 }
2476 2660 ["String.split"] = {
2661 title = "<code>String.split (s, pattern [, limit])</code>"
2662 content = function()
2663 %>
2477 <p> 2664 <p>
2478 Splits <code>s</code> using regex <code>pattern</code> and returns the results. If <code>limit</code> is positive, then only returns at most that many results. If <code>limit</code> is zero, then remove trailing empty results. 2665 Splits <code>s</code> using regex <code>pattern</code> and returns the results. If <code>limit</code> is positive, then only returns at most that many results. If <code>limit</code> is zero, then remove trailing empty results.
2479 2666 </p>
2480 2667 <%
2481 2668 end
2482 <h4 heading><a name="String.sub" href="#String.sub"><code>String.sub (s, i [, j])</code></a></h4> 2669 }
2483 2670 ["String.sub"] = {
2671 title = "<code>String.sub (s, i [, j])</code>"
2672 content = function()
2673 %>
2484 <p> 2674 <p>
2485 Returns the substring of <code>s</code> that 2675 Returns the substring of <code>s</code> that
2486 starts at <code>i</code> and continues until <code>j</code>; 2676 starts at <code>i</code> and continues until <code>j</code>;
2487 <code>i</code> and <code>j</code> can be negative. 2677 <code>i</code> and <code>j</code> can be negative.
2488 If <code>j</code> is absent, then it is assumed to be equal to -1 2678 If <code>j</code> is absent, then it is assumed to be equal to -1
2490 In particular, 2680 In particular,
2491 the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 2681 the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
2492 with length <code>j</code>, 2682 with length <code>j</code>,
2493 and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code> 2683 and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code>
2494 with length <code>i</code>. 2684 with length <code>i</code>.
2495 2685 </p>
2496 2686
2497 <p> 2687 <p>
2498 If, after the translation of negative indices, 2688 If, after the translation of negative indices,
2499 <code>i</code> is less than 1, 2689 <code>i</code> is less than 1,
2500 it is corrected to 1. 2690 it is corrected to 1.
2501 If <code>j</code> is greater than the string length, 2691 If <code>j</code> is greater than the string length,
2502 it is corrected to that length. 2692 it is corrected to that length.
2503 If, after these corrections, 2693 If, after these corrections,
2504 <code>i</code> is greater than <code>j</code>, 2694 <code>i</code> is greater than <code>j</code>,
2505 the function returns the empty string. 2695 the function returns the empty string.
2506 2696 </p>
2507 2697 <%
2508 2698 end
2509 <h4 heading><a name="String.to_binary" href="#String.to_binary"><code>String.to_binary (s)</code></a></h4> 2699 }
2510 2700 ["String.to_binary"] = {
2701 title = "<code>String.to_binary (s)</code>"
2702 content = function()
2703 %>
2511 <p> 2704 <p>
2512 Converts a string to a binary by calling the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#getBytes()"><code>String.getBytes</code></a>. 2705 Converts a string to a binary by calling the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#getBytes()"><code>String.getBytes</code></a>.
2513 2706 </p>
2514 2707 <%
2515 2708 end
2516 <h4 heading><a name="String.to_number" href="#String.to_number"><code>String.to_number (s [, base])</code></a></h4> 2709 }
2517 2710 ["String.to_number"] = {
2711 title = "<code>String.to_number (s [, base])</code>"
2712 content = function()
2713 %>
2518 <p> 2714 <p>
2519 When called with no <code>base</code>, 2715 When called with no <code>base</code>,
2520 <code>to_number</code> tries to convert its argument to a number. 2716 <code>to_number</code> tries to convert its argument to a number.
2521 If the argument is 2717 If the argument is
2522 a string convertible to a number, 2718 a string convertible to a number,
2523 then <code>to_number</code> returns this number; 2719 then <code>to_number</code> returns this number;
2524 otherwise, it returns <b>nil</b>. 2720 otherwise, it returns <b>nil</b>.
2525
2526 The conversion of strings can result in integers or floats. 2721 The conversion of strings can result in integers or floats.
2527 2722 </p>
2528 2723
2529 <p> 2724 <p>
2530 When called with <code>base</code>, 2725 When called with <code>base</code>,
2531 then <code>s</code> must be a string to be interpreted as 2726 then <code>s</code> must be a string to be interpreted as
2532 an integer numeral in that base. 2727 an integer numeral in that base.
2533 In bases above&nbsp;10, the letter '<code>A</code>' (in either upper or lower case) 2728 In bases above&nbsp;10, the letter '<code>A</code>' (in either upper or lower case)
2534 represents&nbsp;10, '<code>B</code>' represents&nbsp;11, and so forth, 2729 represents&nbsp;10, '<code>B</code>' represents&nbsp;11, and so forth,
2535 with '<code>Z</code>' representing 35. 2730 with '<code>Z</code>' representing 35.
2536 If the string <code>s</code> is not a valid numeral in the given base, 2731 If the string <code>s</code> is not a valid numeral in the given base,
2537 the function returns <b>nil</b>. 2732 the function returns <b>nil</b>.
2538 2733 </p>
2539 2734 <%
2540 2735 end
2541 <h4 heading><a name="String.trim" href="#String.trim"><code>String.trim (s)</code></a></h4> 2736 }
2542 2737 ["String.trim"] = {
2738 title = "<code>String.trim (s)</code>"
2739 content = function()
2740 %>
2543 <p> 2741 <p>
2544 Removes the leading and trailing whitespace by calling the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#trim()"><code>String.trim</code></a>. 2742 Removes the leading and trailing whitespace by calling the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#trim()"><code>String.trim</code></a>.
2545 2743 </p>
2546 2744 <%
2547 2745 end
2548 2746 }
2549 <h4 heading><a name="String.unicode" href="#String.unicode"><code>String.unicode (s [, i [, j]])</code></a></h4> 2747 ["String.unicode"] = {
2550 2748 title = "<code>String.unicode (s [, i [, j]])</code>"
2749 content = function()
2750 %>
2551 <p> 2751 <p>
2552 Returns the internal numerical codes of the characters <code>s[i]</code>, 2752 Returns the internal numerical codes of the characters <code>s[i]</code>,
2553 <code>s[i+1]</code>, ..., <code>s[j]</code>. 2753 <code>s[i+1]</code>, ..., <code>s[j]</code>.
2554 The default value for <code>i</code> is&nbsp;1; 2754 The default value for <code>i</code> is&nbsp;1;
2555 the default value for <code>j</code> is&nbsp;<code>i</code>. 2755 the default value for <code>j</code> is&nbsp;<code>i</code>.
2556 These indices are corrected 2756 These indices are corrected
2557 following the same rules of function <a href="#String.sub"><code>String.sub</code></a>. 2757 following the same rules of function <a href="#String.sub"><code>String.sub</code></a>.
2558 2758 </p>
2559 2759 <%
2560 2760 end
2561 2761 }
2562 2762 ["String.upper"] = {
2563 <h4 heading><a name="String.upper" href="#String.upper"><code>String.upper (s)</code></a></h4> 2763 title = "<code>String.upper (s)</code>"
2764 content = function()
2765 %>
2564 <p> 2766 <p>
2565 Receives a string and returns a copy of this string with all 2767 Receives a string and returns a copy of this string with all
2566 lowercase letters changed to uppercase. 2768 lowercase letters changed to uppercase.
2567 All other characters are left unchanged. 2769 All other characters are left unchanged.
2568 The definition of what a lowercase letter is depends on the current locale. 2770 The definition of what a lowercase letter is depends on the current locale.
2569 2771 </p>
2570 2772 <%
2571 2773 end
2572 2774 }
2573 2775 }
2574 <h3 heading><a name="binary_lib" href="#binary_lib">Binary Manipulation</a></h3> 2776 }
2575 2777 binary_lib = {
2778 title = "Binary Manipulation"
2779 content = function()
2780 %>
2576 <p> 2781 <p>
2577 Include this library by: 2782 Include this library by:
2578 2783 </p>
2579 <pre> 2784 <pre>
2580 local Binary = require "luan:Binary.luan" 2785 local Binary = require "luan:Binary.luan"
2581 </pre> 2786 </pre>
2582 2787 <%
2583 2788 end
2584 <h4 heading><a name="Binary.binary" href="#Binary.binary"><code>Binary.binary (&middot;&middot;&middot;)</code></a></h4> 2789 subs = {
2585 2790 ["Binary.binary"] = {
2791 title = "<code>Binary.binary (&middot;&middot;&middot;)</code>"
2792 content = function()
2793 %>
2586 <p> 2794 <p>
2587 Receives zero or more bytes (as integers). 2795 Receives zero or more bytes (as integers).
2588 Returns a binary with length equal to the number of arguments, 2796 Returns a binary with length equal to the number of arguments,
2589 in which each byte has the internal numerical code equal 2797 in which each byte has the internal numerical code equal
2590 to its corresponding argument. 2798 to its corresponding argument.
2591 2799 </p>
2592 2800 <%
2593 <h4 heading><a name="Binary.byte" href="#Binary.byte"><code>Binary.byte (b [, i [, j]])</code></a></h4> 2801 end
2594 2802 }
2803 ["Binary.byte"] = {
2804 title = "<code>Binary.byte (b [, i [, j]])</code>"
2805 content = function()
2806 %>
2595 <p> 2807 <p>
2596 Returns the internal numerical codes of the bytes <code>b[i]</code>, 2808 Returns the internal numerical codes of the bytes <code>b[i]</code>,
2597 <code>b[i+1]</code>, ..., <code>b[j]</code>. 2809 <code>b[i+1]</code>, ..., <code>b[j]</code>.
2598 The default value for <code>i</code> is&nbsp;1; 2810 The default value for <code>i</code> is&nbsp;1;
2599 the default value for <code>j</code> is&nbsp;<code>i</code>. 2811 the default value for <code>j</code> is&nbsp;<code>i</code>.
2600 These indices are corrected 2812 These indices are corrected
2601 following the same rules of function <a href="#String.sub"><code>String.sub</code></a>. 2813 following the same rules of function <a href="#String.sub"><code>String.sub</code></a>.
2602 2814 </p>
2603 2815 <%
2604 <h4 heading><a name="Binary.to_string" href="#Binary.to_string"><code>Binary.to_string (b [,charset])</code></a></h4> 2816 end
2817 }
2818 ["Binary.to_string"] = {
2819 title = "<code>Binary.to_string (b [,charset])</code>"
2820 content = function()
2821 %>
2605 <p> 2822 <p>
2606 If <code>charset</code> is not nil then converts the binary <code>b</code> to a string using the Java <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#String(byte[],%20java.lang.String)">String constructor</a>, else makes each byte a char. 2823 If <code>charset</code> is not nil then converts the binary <code>b</code> to a string using the Java <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#String(byte[],%20java.lang.String)">String constructor</a>, else makes each byte a char.
2607 2824 </p>
2608 2825 <%
2609 2826 end
2610 2827 }
2611 <h3 heading><a name="table_lib" href="#table_lib">Table Manipulation</a></h3> 2828 }
2612 2829 }
2830 table_lib = {
2831 title = "Table Manipulation"
2832 content = function()
2833 %>
2613 <p> 2834 <p>
2614 Include this library by: 2835 Include this library by:
2615 2836 </p>
2616 <pre> 2837 <pre>
2617 local Table = require "luan:Table.luan" 2838 local Table = require "luan:Table.luan"
2618 </pre> 2839 </pre>
2619 2840
2620 <p> 2841 <p>
2621 This library provides generic functions for table manipulation. 2842 This library provides generic functions for table manipulation.
2622 It provides all its functions inside the table <code>Table</code>. 2843 It provides all its functions inside the table <code>Table</code>.
2623 2844 </p>
2624 2845 <%
2625 2846 end
2626 <h4 heading><a name="Table.clear" href="#Table.clear"><code>Table.clear (tbl)</code></a></h4> 2847 subs = {
2627 2848 ["Table.clear"] = {
2849 title = "<code>Table.clear (tbl)</code>"
2850 content = function()
2851 %>
2628 <p> 2852 <p>
2629 Clears the table. 2853 Clears the table.
2630 2854 </p>
2631 2855 <%
2632 <h4 heading><a name="Table.concat" href="#Table.concat"><code>Table.concat (list [, sep [, i [, j]]])</code></a></h4> 2856 end
2633 2857 }
2858 ["Table.concat"] = {
2859 title = "<code>Table.concat (list [, sep [, i [, j]]])</code>"
2860 content = function()
2861 %>
2634 <p> 2862 <p>
2635 Given a list, 2863 Given a list,
2636 returns the string <code>list[i]..sep..list[i+1] &middot;&middot;&middot; sep..list[j]</code>. 2864 returns the string <code>list[i]..sep..list[i+1] &middot;&middot;&middot; sep..list[j]</code>.
2637 The default value for <code>sep</code> is the empty string, 2865 The default value for <code>sep</code> is the empty string,
2638 the default for <code>i</code> is 1, 2866 the default for <code>i</code> is 1,
2639 and the default for <code>j</code> is <code>#list</code>. 2867 and the default for <code>j</code> is <code>#list</code>.
2640 If <code>i</code> is greater than <code>j</code>, returns the empty string. 2868 If <code>i</code> is greater than <code>j</code>, returns the empty string.
2641 2869 </p>
2642 2870 <%
2643 <h4 heading><a name="Table.copy" href="#Table.copy"><code>Table.copy (tbl [, i [, j]])</code></a></h4> 2871 end
2644 2872 }
2873 ["Table.copy"] = {
2874 title = "<code>Table.copy (tbl [, i [, j]])</code>"
2875 content = function()
2876 %>
2645 <p> 2877 <p>
2646 If <code>i</code> is <code>nil</code>, returns a shallow copy of <code>tbl</code>. 2878 If <code>i</code> is <code>nil</code>, returns a shallow copy of <code>tbl</code>.
2647 Otherwise returns a new table which is a list of the elements <code>tbl[i] &middot;&middot;&middot; tbl[j]</code>. 2879 Otherwise returns a new table which is a list of the elements <code>tbl[i] &middot;&middot;&middot; tbl[j]</code>.
2648 By default, <code>j</code> is <code>#tbl</code>. 2880 By default, <code>j</code> is <code>#tbl</code>.
2649 2881 </p>
2650 2882 <%
2651 2883 end
2652 <h4 heading><a name="Table.insert" href="#Table.insert"><code>Table.insert (list, pos, value)</code></a></h4> 2884 }
2653 2885 ["Table.insert"] = {
2886 title = "<code>Table.insert (list, pos, value)</code>"
2887 content = function()
2888 %>
2654 <p> 2889 <p>
2655 Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>, 2890 Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>,
2656 shifting up the elements 2891 shifting up the elements
2657 <code>list[pos], list[pos+1], &middot;&middot;&middot;, list[#list]</code>. 2892 <code>list[pos], list[pos+1], &middot;&middot;&middot;, list[#list]</code>.
2658 2893 </p>
2659 2894 <%
2660 2895 end
2661 <h4 heading><a name="Table.is_empty" href="#Table.is_empty"><code>Table.is_empty (tbl)</code></a></h4> 2896 }
2662 2897 ["Table.is_empty"] = {
2663 2898 title = "<code>Table.is_empty (tbl)</code>"
2664 2899 content = function()
2665 <h4 heading><a name="Table.pack" href="#Table.pack"><code>Table.pack (&middot;&middot;&middot;)</code></a></h4> 2900 %>
2666 2901 <%
2902 end
2903 }
2904 ["Table.pack"] = {
2905 title = "<code>Table.pack (&middot;&middot;&middot;)</code>"
2906 content = function()
2907 %>
2667 <p> 2908 <p>
2668 Returns a new table with all parameters stored into keys 1, 2, etc. 2909 Returns a new table with all parameters stored into keys 1, 2, etc.
2669 and with a field "<code>n</code>" with the total number of parameters. 2910 and with a field "<code>n</code>" with the total number of parameters.
2670 Note that the resulting table may not be a sequence. 2911 Note that the resulting table may not be a sequence.
2671 2912 </p>
2672 2913 <%
2673 2914 end
2674 2915 }
2675 <h4 heading><a name="Table.remove" href="#Table.remove"><code>Table.remove (list, pos)</code></a></h4> 2916 ["Table.remove"] = {
2676 2917 title = "<code>Table.remove (list, pos)</code>"
2677 2918 content = function()
2919 %>
2678 <p> 2920 <p>
2679 Removes from <code>list</code> the element at position <code>pos</code>, 2921 Removes from <code>list</code> the element at position <code>pos</code>,
2680 returning the value of the removed element. 2922 returning the value of the removed element.
2681 When <code>pos</code> is an integer between 1 and <code>#list</code>, 2923 When <code>pos</code> is an integer between 1 and <code>#list</code>,
2682 it shifts down the elements 2924 it shifts down the elements
2683 <code>list[pos+1], list[pos+2], &middot;&middot;&middot;, list[#list]</code> 2925 <code>list[pos+1], list[pos+2], &middot;&middot;&middot;, list[#list]</code>
2684 and erases element <code>list[#list]</code>; 2926 and erases element <code>list[#list]</code>;
2685 The index <code>pos</code> can also be 0 when <code>#list</code> is 0, 2927 The index <code>pos</code> can also be 0 when <code>#list</code> is 0,
2686 or <code>#list + 1</code>; 2928 or <code>#list + 1</code>;
2687 in those cases, the function erases the element <code>list[pos]</code>. 2929 in those cases, the function erases the element <code>list[pos]</code>.
2688 2930 </p>
2689 2931 <%
2690 2932 end
2691 <h4 heading><a name="Table.size" href="#Table.size"><code>Table.size (tbl)</code></a></h4> 2933 }
2692 2934 ["Table.size"] = {
2693 2935 title = "<code>Table.size (tbl)</code>"
2694 2936 content = function()
2695 <h4 heading><a name="Table.sort" href="#Table.sort"><code>Table.sort (list [, comp])</code></a></h4> 2937 %>
2696 2938 <%
2939 end
2940 }
2941 ["Table.sort"] = {
2942 title = "<code>Table.sort (list [, comp])</code>"
2943 content = function()
2944 %>
2697 <p> 2945 <p>
2698 Sorts list elements in a given order, <em>in-place</em>, 2946 Sorts list elements in a given order, <em>in-place</em>,
2699 from <code>list[1]</code> to <code>list[#list]</code>. 2947 from <code>list[1]</code> to <code>list[#list]</code>.
2700 If <code>comp</code> is given, 2948 If <code>comp</code> is given,
2701 then it must be a function that receives two list elements 2949 then it must be a function that receives two list elements
2702 and returns true when the first element must come 2950 and returns true when the first element must come
2703 before the second in the final order 2951 before the second in the final order
2704 (so that <code>not comp(list[i+1],list[i])</code> will be true after the sort). 2952 (so that <code>not comp(list[i+1],list[i])</code> will be true after the sort).
2705 If <code>comp</code> is not given, 2953 If <code>comp</code> is not given,
2706 then the standard Lua operator <code>&lt;</code> is used instead. 2954 then the standard Lua operator <code>&lt;</code> is used instead.
2955 </p>
2707 2956
2708 <p> 2957 <p>
2709 The sort algorithm is not stable; 2958 The sort algorithm is not stable;
2710 that is, elements considered equal by the given order 2959 that is, elements considered equal by the given order
2711 may have their relative positions changed by the sort. 2960 may have their relative positions changed by the sort.
2712 2961 </p>
2713 2962 <%
2714 2963 end
2715 <h4 heading><a name="Table.unpack" href="#Table.unpack"><code>Table.unpack (list [, i [, j]])</code></a></h4> 2964 }
2716 2965 ["Table.unpack"] = {
2966 title = "<code>Table.unpack (list [, i [, j]])</code>"
2967 content = function()
2968 %>
2717 <p> 2969 <p>
2718 Returns the elements from the given list. 2970 Returns the elements from the given list.
2719 This function is equivalent to 2971 This function is equivalent to
2720 2972 </p>
2721 <pre> 2973 <pre>
2722 return list[i], list[i+1], &middot;&middot;&middot;, list[j] 2974 return list[i], list[i+1], &middot;&middot;&middot;, list[j]
2723 </pre> 2975 </pre>
2724 2976
2725 <p> 2977 <p>
2726 By default, <code>i</code> is 1 and <code>j</code> is <code>list.n or #list</code>. 2978 By default, <code>i</code> is 1 and <code>j</code> is <code>list.n or #list</code>.
2727 2979 </p>
2728 2980 <%
2729 2981 end
2730 2982 }
2731 <h3 heading><a name="number_lib" href="#number_lib">Number Manipulation</a></h3> 2983 }
2732 2984 }
2985 number_lib = {
2986 title = "Number Manipulation"
2987 content = function()
2988 %>
2733 <p> 2989 <p>
2734 Include this library by: 2990 Include this library by:
2735 2991 </p>
2736 <pre> 2992 <pre>
2737 local Number = require "luan:Number.luan" 2993 local Number = require "luan:Number.luan"
2738 </pre> 2994 </pre>
2739 2995 <%
2740 2996 end
2741 <h4 heading><a name="Number.double" href="#Number.double"><code>Number.double (x)</code></a></h4> 2997 subs = {
2998 ["Number.double"] = {
2999 title = "<code>Number.double (x)</code>"
3000 content = function()
3001 %>
2742 <p> 3002 <p>
2743 Returns <code>x</code> as a double. 3003 Returns <code>x</code> as a double.
2744 3004 </p>
2745 3005 <%
2746 <h4 heading><a name="Number.float" href="#Number.double"><code>Number.float (x)</code></a></h4> 3006 end
3007 }
3008 ["Number.float"] = {
3009 title = "<code>Number.float (x)</code>"
3010 content = function()
3011 %>
2747 <p> 3012 <p>
2748 Returns <code>x</code> as a float. 3013 Returns <code>x</code> as a float.
2749 3014 </p>
2750 3015 <%
2751 <h4 heading><a name="Number.integer" href="#Number.integer"><code>Number.integer (x)</code></a></h4> 3016 end
3017 }
3018 ["Number.integer"] = {
3019 title = "<code>Number.integer (x)</code>"
3020 content = function()
3021 %>
2752 <p> 3022 <p>
2753 If the value <code>x</code> is convertible to an integer, 3023 If the value <code>x</code> is convertible to an integer,
2754 returns that integer. 3024 returns that integer.
2755 Otherwise throws an error. 3025 Otherwise throws an error.
2756 3026 </p>
2757 3027 <%
2758 <h4 heading><a name="Number.long" href="#Number.long"><code>Number.long (x)</code></a></h4> 3028 end
3029 }
3030 ["Number.long"] = {
3031 title = "<code>Number.long (x)</code>"
3032 content = function()
3033 %>
2759 <p> 3034 <p>
2760 If the value <code>x</code> is convertible to an long, 3035 If the value <code>x</code> is convertible to an long,
2761 returns that long. 3036 returns that long.
2762 Otherwise throws an error. 3037 Otherwise throws an error.
2763 3038 </p>
2764 3039 <%
2765 <h4 heading><a name="Number.long_to_string" href="#Number.long_to_string"><code>Number.long_to_string (i, radix)</code></a></h4> 3040 end
3041 }
3042 ["Number.long_to_string"] = {
3043 title = "<code>Number.long_to_string (i, radix)</code>"
3044 content = function()
3045 %>
2766 <p> 3046 <p>
2767 Converts long value <code>i</code> to a string by calling <code><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Long.html#toString(long,%20int)">Long.toString</a></code>. 3047 Converts long value <code>i</code> to a string by calling <code><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Long.html#toString(long,%20int)">Long.toString</a></code>.
2768 3048 </p>
2769 3049 <%
2770 <h4 heading><a name="Number.type" href="#Number.type"><code>Number.type (x)</code></a></h4> 3050 end
3051 }
3052 ["Number.type"] = {
3053 title = "<code>Number.type (x)</code>"
3054 content = function()
3055 %>
2771 <p> 3056 <p>
2772 Returns a string for the numeric type of <code>x</code>. Possible return values include "<code>integer</code>", "<code>long</code>", "<code>double</code>", and "<code>float</code>". 3057 Returns a string for the numeric type of <code>x</code>. Possible return values include "<code>integer</code>", "<code>long</code>", "<code>double</code>", and "<code>float</code>".
2773 3058 </p>
2774 3059 <%
2775 3060 end
2776 3061 }
2777 <h3 heading><a name="math_lib" href="#math_lib">Mathematical Functions</a></h3> 3062 }
2778 3063 }
3064 math_lib = {
3065 title = "Mathematical Functions"
3066 content = function()
3067 %>
2779 <p> 3068 <p>
2780 Include this library by: 3069 Include this library by:
2781 3070 </p>
2782 <pre> 3071 <pre>
2783 local Math = require "luan:Math.luan" 3072 local Math = require "luan:Math.luan"
2784 </pre> 3073 </pre>
2785 3074
2786 <p> 3075 <p>
2787 This library provides basic mathematical functions. 3076 This library provides basic mathematical functions.
2788 It provides all its functions and constants inside the table <code>Math</code>. 3077 It provides all its functions and constants inside the table <code>Math</code>.
2789 3078 </p>
2790 3079 <%
2791 <h4 heading><a name="Math.abs" href="#Math.abs"><code>Math.abs (x)</code></a></h4> 3080 end
2792 3081 subs = {
3082 ["Math.abs"] = {
3083 title = "<code>Math.abs (x)</code>"
3084 content = function()
3085 %>
2793 <p> 3086 <p>
2794 Returns the absolute value of <code>x</code>. 3087 Returns the absolute value of <code>x</code>.
2795 3088 </p>
2796 3089 <%
2797 3090 end
2798 <h4 heading><a name="Math.acos" href="#Math.acos"><code>Math.acos (x)</code></a></h4> 3091 }
2799 3092 ["Math.acos"] = {
3093 title = "<code>Math.acos (x)</code>"
3094 content = function()
3095 %>
2800 <p> 3096 <p>
2801 Returns the arc cosine of <code>x</code> (in radians). 3097 Returns the arc cosine of <code>x</code> (in radians).
2802 3098 </p>
2803 3099 <%
2804 3100 end
2805 3101 }
2806 <h4 heading><a name="Math.asin" href="#Math.asin"><code>Math.asin (x)</code></a></h4> 3102 ["Math.asin"] = {
2807 3103 title = "<code>Math.asin (x)</code>"
3104 content = function()
3105 %>
2808 <p> 3106 <p>
2809 Returns the arc sine of <code>x</code> (in radians). 3107 Returns the arc sine of <code>x</code> (in radians).
2810 3108 </p>
2811 3109 <%
2812 3110 end
2813 3111 }
2814 <h4 heading><a name="Math.atan" href="#Math.atan"><code>Math.atan (y, x)</code></a></h4> 3112 ["Math.atan"] = {
2815 3113 title = "<code>Math.atan (y, x)</code>"
3114 content = function()
3115 %>
2816 <p> 3116 <p>
2817 Returns the arc tangent of <code>y/x</code> (in radians), 3117 Returns the arc tangent of <code>y/x</code> (in radians),
2818 but uses the signs of both parameters to find the 3118 but uses the signs of both parameters to find the
2819 quadrant of the result. 3119 quadrant of the result.
2820 (It also handles correctly the case of <code>x</code> being zero.) 3120 (It also handles correctly the case of <code>x</code> being zero.)
2821 3121 </p>
2822 3122 <%
2823 3123 end
2824 3124 }
2825 <h4 heading><a name="Math.ceil" href="#Math.ceil"><code>Math.ceil (x)</code></a></h4> 3125 ["Math.ceil"] = {
2826 3126 title = "<code>Math.ceil (x)</code>"
3127 content = function()
3128 %>
2827 <p> 3129 <p>
2828 Returns the smallest integral value larger than or equal to <code>x</code>. 3130 Returns the smallest integral value larger than or equal to <code>x</code>.
2829 3131 </p>
2830 3132 <%
2831 3133 end
2832 3134 }
2833 <h4 heading><a name="Math.cos" href="#Math.cos"><code>Math.cos (x)</code></a></h4> 3135 ["Math.cos"] = {
2834 3136 title = "<code>Math.cos (x)</code>"
3137 content = function()
3138 %>
2835 <p> 3139 <p>
2836 Returns the cosine of <code>x</code> (assumed to be in radians). 3140 Returns the cosine of <code>x</code> (assumed to be in radians).
2837 3141 </p>
2838 3142 <%
2839 3143 end
2840 3144 }
2841 <h4 heading><a name="Math.deg" href="#Math.deg"><code>Math.deg (x)</code></a></h4> 3145 ["Math.deg"] = {
2842 3146 title = "<code>Math.deg (x)</code>"
3147 content = function()
3148 %>
2843 <p> 3149 <p>
2844 Converts the angle <code>x</code> from radians to degrees. 3150 Converts the angle <code>x</code> from radians to degrees.
2845 3151 </p>
2846 3152 <%
2847 3153 end
2848 3154 }
2849 <h4 heading><a name="Math.exp" href="#Math.exp"><code>Math.exp (x)</code></a></h4> 3155 ["Math.exp"] = {
2850 3156 title = "<code>Math.exp (x)</code>"
3157 content = function()
3158 %>
2851 <p> 3159 <p>
2852 Returns the value <em>e<sup>x</sup></em> 3160 Returns the value <em>e<sup>x</sup></em>
2853 (where <code>e</code> is the base of natural logarithms). 3161 (where <code>e</code> is the base of natural logarithms).
2854 3162 </p>
2855 3163 <%
2856 3164 end
2857 3165 }
2858 <h4 heading><a name="Math.floor" href="#Math.floor"><code>Math.floor (x)</code></a></h4> 3166 ["Math.floor"] = {
2859 3167 title = "<code>Math.floor (x)</code>"
3168 content = function()
3169 %>
2860 <p> 3170 <p>
2861 Returns the largest integral value smaller than or equal to <code>x</code>. 3171 Returns the largest integral value smaller than or equal to <code>x</code>.
2862 3172 </p>
2863 3173 <%
2864 3174 end
2865 3175 }
2866 <h4 heading><a name="Math.fmod" href="#Math.fmod"><code>Math.fmod (x, y)</code></a></h4> 3176 ["Math.fmod"] = {
2867 3177 title = "<code>Math.fmod (x, y)</code>"
3178 content = function()
3179 %>
2868 <p> 3180 <p>
2869 Returns the remainder of the division of <code>x</code> by <code>y</code> 3181 Returns the remainder of the division of <code>x</code> by <code>y</code>
2870 that rounds the quotient towards zero. 3182 that rounds the quotient towards zero.
2871 3183 </p>
2872 3184 <%
2873 3185 end
2874 3186 }
2875 <h4 heading><a name="Math.huge" href="#Math.huge"><code>Math.huge</code></a></h4> 3187 ["Math.huge"] = {
2876 3188 title = "<code>Math.huge</code>"
3189 content = function()
3190 %>
2877 <p> 3191 <p>
2878 A value larger than any other numerical value. 3192 A value larger than any other numerical value.
2879 3193 </p>
2880 3194 <%
2881 3195 end
2882 3196 }
2883 <h4 heading><a name="Math.log" href="#Math.log"><code>Math.log (x [, base])</code></a></h4> 3197 ["Math.log"] = {
2884 3198 title = "<code>Math.log (x [, base])</code>"
3199 content = function()
3200 %>
2885 <p> 3201 <p>
2886 Returns the logarithm of <code>x</code> in the given base. 3202 Returns the logarithm of <code>x</code> in the given base.
2887 The default for <code>base</code> is <em>e</em> 3203 The default for <code>base</code> is <em>e</em>
2888 (so that the function returns the natural logarithm of <code>x</code>). 3204 (so that the function returns the natural logarithm of <code>x</code>).
2889 3205 </p>
2890 3206 <%
2891 3207 end
2892 3208 }
2893 <h4 heading><a name="Math.max" href="#Math.max"><code>Math.max (x, &middot;&middot;&middot;)</code></a></h4> 3209 ["Math.max"] = {
2894 3210 title = "<code>Math.max (x, &middot;&middot;&middot;)</code>"
3211 content = function()
3212 %>
2895 <p> 3213 <p>
2896 Returns the argument with the maximum value, 3214 Returns the argument with the maximum value,
2897 according to the Lua operator <code>&lt;</code>. 3215 according to the Lua operator <code>&lt;</code>.
2898 3216 </p>
2899 3217 <%
2900 3218 end
2901 3219 }
2902 <h4 heading><a name="Math.max_integer" href="#Math.max_integer"><code>Math.max_integer</code></a></h4> 3220 ["Math.max_integer"] = {
3221 title = "<code>Math.max_integer</code>"
3222 content = function()
3223 %>
2903 <p> 3224 <p>
2904 An integer with the maximum value for an integer. 3225 An integer with the maximum value for an integer.
2905 3226 </p>
2906 3227 <%
2907 3228 end
2908 3229 }
2909 <h4 heading><a name="Math.min" href="#Math.min"><code>Math.min (x, &middot;&middot;&middot;)</code></a></h4> 3230 ["Math.min"] = {
2910 3231 title = "<code>Math.min (x, &middot;&middot;&middot;)</code>"
3232 content = function()
3233 %>
2911 <p> 3234 <p>
2912 Returns the argument with the minimum value, 3235 Returns the argument with the minimum value,
2913 according to the Lua operator <code>&lt;</code>. 3236 according to the Lua operator <code>&lt;</code>.
2914 3237 </p>
2915 3238 <%
2916 3239 end
2917 3240 }
2918 <h4 heading><a name="Math.min_integer" href="#Math.min_integer"><code>Math.min_integer</code></a></h4> 3241 ["Math.min_integer"] = {
3242 title = "<code>Math.min_integer</code>"
3243 content = function()
3244 %>
2919 <p> 3245 <p>
2920 An integer with the minimum value for an integer. 3246 An integer with the minimum value for an integer.
2921 3247 </p>
2922 3248 <%
2923 3249 end
2924 3250 }
2925 <h4 heading><a name="Math.modf" href="#Math.modf"><code>Math.modf (x)</code></a></h4> 3251 ["Math.modf"] = {
2926 3252 title = "<code>Math.modf (x)</code>"
3253 content = function()
3254 %>
2927 <p> 3255 <p>
2928 Returns the integral part of <code>x</code> and the fractional part of <code>x</code>. 3256 Returns the integral part of <code>x</code> and the fractional part of <code>x</code>.
2929 3257 </p>
2930 3258 <%
2931 3259 end
2932 3260 }
2933 <h4 heading><a name="Math.pi" href="#Math.pi"><code>Math.pi</code></a></h4> 3261 ["Math.pi"] = {
2934 3262 title = "<code>Math.pi</code>"
3263 content = function()
3264 %>
2935 <p> 3265 <p>
2936 The value of <em>&pi;</em>. 3266 The value of <em>&pi;</em>.
2937 3267 </p>
2938 3268 <%
2939 3269 end
2940 3270 }
2941 <h4 heading><a name="Math.rad" href="#Math.rad"><code>Math.rad (x)</code></a></h4> 3271 ["Math.rad"] = {
2942 3272 title = "<code>Math.rad (x)</code>"
3273 content = function()
3274 %>
2943 <p> 3275 <p>
2944 Converts the angle <code>x</code> from degrees to radians. 3276 Converts the angle <code>x</code> from degrees to radians.
2945 3277 </p>
2946 3278 <%
2947 3279 end
2948 3280 }
2949 <h4 heading><a name="Math.random" href="#Math.random"><code>Math.random ([m [, n])</code></a></h4> 3281 ["Math.random"] = {
2950 3282 title = "<code>Math.random ([m [, n])</code>"
2951 3283 content = function()
3284 %>
2952 <p> 3285 <p>
2953 When called without arguments, 3286 When called without arguments,
2954 returns a pseudo-random float with uniform distribution 3287 returns a pseudo-random float with uniform distribution
2955 in the range <em>[0,1)</em>. 3288 in the range <em>[0,1)</em>.
2956 When called with two integers <code>m</code> and <code>n</code>, 3289 When called with two integers <code>m</code> and <code>n</code>,
2957 <code>Math.random</code> returns a pseudo-random integer 3290 <code>Math.random</code> returns a pseudo-random integer
2958 with uniform distribution in the range <em>[m, n]</em>. 3291 with uniform distribution in the range <em>[m, n]</em>.
2959 (The value <em>m-n</em> cannot be negative and must fit in a Luan integer.) 3292 (The value <em>m-n</em> cannot be negative and must fit in a Luan integer.)
2960 The call <code>Math.random(n)</code> is equivalent to <code>Math.random(1,n)</code>. 3293 The call <code>Math.random(n)</code> is equivalent to <code>Math.random(1,n)</code>.
2961 3294 </p>
2962 3295
2963 <p> 3296 <p>
2964 This function is an interface to the underling 3297 This function is an interface to the underling
2965 pseudo-random generator function provided by Java. 3298 pseudo-random generator function provided by Java.
2966 No guarantees can be given for its statistical properties. 3299 No guarantees can be given for its statistical properties.
2967 3300 </p>
2968 3301 <%
2969 3302 end
2970 3303 }
2971 <h4 heading><a name="Math.sin" href="#Math.sin"><code>Math.sin (x)</code></a></h4> 3304 ["Math.sin"] = {
2972 3305 title = "<code>Math.sin (x)</code>"
3306 content = function()
3307 %>
2973 <p> 3308 <p>
2974 Returns the sine of <code>x</code> (assumed to be in radians). 3309 Returns the sine of <code>x</code> (assumed to be in radians).
2975 3310 </p>
2976 3311 <%
2977 3312 end
2978 3313 }
2979 <h4 heading><a name="Math.sqrt" href="#Math.sqrt"><code>Math.sqrt (x)</code></a></h4> 3314 ["Math.sqrt"] = {
2980 3315 title = "<code>Math.sqrt (x)</code>"
3316 content = function()
3317 %>
2981 <p> 3318 <p>
2982 Returns the square root of <code>x</code>. 3319 Returns the square root of <code>x</code>.
2983 (You can also use the expression <code>x^0.5</code> to compute this value.) 3320 (You can also use the expression <code>x^0.5</code> to compute this value.)
2984 3321 </p>
2985 3322 <%
2986 3323 end
2987 3324 }
2988 <h4 heading><a name="Math.tan" href="#Math.tan"><code>Math.tan (x)</code></a></h4> 3325 ["Math.tan"] = {
2989 3326 title = "<code>Math.tan (x)</code>"
3327 content = function()
3328 %>
2990 <p> 3329 <p>
2991 Returns the tangent of <code>x</code> (assumed to be in radians). 3330 Returns the tangent of <code>x</code> (assumed to be in radians).
2992 3331 </p>
2993 3332 <%
2994 3333 end
2995 3334 }
2996 3335 }
2997 3336 }
2998 3337 }
2999 3338 }
3000 <h2>6.8 &ndash; <a name="6.8">Input and Output Facilities</a></h2> 3339 }
3001 3340
3002 <p> 3341
3003 The I/O library provides two different styles for file manipulation. 3342 return function()
3004 The first one uses implicit file handles; 3343 Io.stdout = Http.response.text_writer()
3005 that is, there are operations to set a default input file and a 3344 %>
3006 default output file, 3345 <!doctype html>
3007 and all input/output operations are over these default files. 3346 <html>
3008 The second style uses explicit file handles. 3347 <head>
3009 3348 <% head() %>
3010 3349 <title>Luan Reference Manual</title>
3011 <p> 3350 <style>
3012 When using implicit file handles, 3351 p[keywords] {
3013 all operations are supplied by table <a name="pdf-io"><code>io</code></a>. 3352 font-family: monospace;
3014 When using explicit file handles, 3353 margin-left: 40px;
3015 the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle 3354 max-width: 700px;
3016 and then all operations are supplied as methods of the file handle. 3355 }
3017 3356 p[keywords] span {
3018 3357 display: inline-block;
3019 <p> 3358 width: 100px;
3020 The table <code>io</code> also provides 3359 }
3021 three predefined file handles with their usual meanings from C: 3360 </style>
3022 <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>. 3361 </head>
3023 The I/O library never closes these files. 3362 <body>
3024 3363 <% docs_header() %>
3025 3364 <div content>
3026 <p> 3365 <h1><a href="manual.html">Luan Reference Manual</a></h1>
3027 Unless otherwise stated, 3366 <p small>
3028 all I/O functions return <b>nil</b> on failure 3367 Original copyright &copy; 2015 Lua.org, PUC-Rio.
3029 (plus an error message as a second result and 3368 Freely available under the terms of the
3030 a system-dependent error code as a third result) 3369 <a href="http://www.lua.org/license.html">Lua license</a>.
3031 and some value different from <b>nil</b> on success. 3370 Modified for Luan.
3032 On non-POSIX systems, 3371 </p>
3033 the computation of the error message and error code 3372 <hr>
3034 in case of errors 3373 <h2>Contents</h2>
3035 may be not thread safe, 3374 <div toc>
3036 because they rely on the global C variable <code>errno</code>. 3375 <% show_toc(content) %>
3037 3376 </div>
3038 3377 <hr>
3039 <p> 3378 <% show_content(content,2) %>
3040 <hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3>
3041
3042
3043 <p>
3044 Equivalent to <code>file:close()</code>.
3045 Without a <code>file</code>, closes the default output file.
3046
3047
3048
3049
3050 <p>
3051 <hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3>
3052
3053
3054 <p>
3055 Equivalent to <code>io.output():flush()</code>.
3056
3057
3058
3059
3060 <p>
3061 <hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3>
3062
3063
3064 <p>
3065 When called with a file name, it opens the named file (in text mode),
3066 and sets its handle as the default input file.
3067 When called with a file handle,
3068 it simply sets this file handle as the default input file.
3069 When called without parameters,
3070 it returns the current default input file.
3071
3072
3073 <p>
3074 In case of errors this function raises the error,
3075 instead of returning an error code.
3076
3077
3078
3079
3080 <p>
3081 <hr><h3><a name="pdf-io.lines"><code>io.lines ([filename &middot;&middot;&middot;])</code></a></h3>
3082
3083
3084 <p>
3085 Opens the given file name in read mode
3086 and returns an iterator function that
3087 works like <code>file:lines(&middot;&middot;&middot;)</code> over the opened file.
3088 When the iterator function detects the end of file,
3089 it returns no values (to finish the loop) and automatically closes the file.
3090
3091
3092 <p>
3093 The call <code>io.lines()</code> (with no file name) is equivalent
3094 to <code>io.input():lines("*l")</code>;
3095 that is, it iterates over the lines of the default input file.
3096 In this case it does not close the file when the loop ends.
3097
3098
3099 <p>
3100 In case of errors this function raises the error,
3101 instead of returning an error code.
3102
3103
3104
3105
3106 <p>
3107 <hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3>
3108
3109
3110 <p>
3111 This function opens a file,
3112 in the mode specified in the string <code>mode</code>.
3113 It returns a new file handle,
3114 or, in case of errors, <b>nil</b> plus an error message.
3115
3116
3117 <p>
3118 The <code>mode</code> string can be any of the following:
3119
3120 <ul>
3121 <li><b>"<code>r</code>": </b> read mode (the default);</li>
3122 <li><b>"<code>w</code>": </b> write mode;</li>
3123 <li><b>"<code>a</code>": </b> append mode;</li>
3124 <li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li>
3125 <li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li>
3126 <li><b>"<code>a+</code>": </b> append update mode, previous data is preserved,
3127 writing is only allowed at the end of file.</li>
3128 </ul><p>
3129 The <code>mode</code> string can also have a '<code>b</code>' at the end,
3130 which is needed in some systems to open the file in binary mode.
3131
3132
3133
3134
3135 <p>
3136 <hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3>
3137
3138
3139 <p>
3140 Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file.
3141
3142
3143
3144
3145 <p>
3146 <hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3>
3147
3148
3149 <p>
3150 This function is system dependent and is not available
3151 on all platforms.
3152
3153
3154 <p>
3155 Starts program <code>prog</code> in a separated process and returns
3156 a file handle that you can use to read data from this program
3157 (if <code>mode</code> is <code>"r"</code>, the default)
3158 or to write data to this program
3159 (if <code>mode</code> is <code>"w"</code>).
3160
3161
3162
3163
3164 <p>
3165 <hr><h3><a name="pdf-io.read"><code>io.read (&middot;&middot;&middot;)</code></a></h3>
3166
3167
3168 <p>
3169 Equivalent to <code>io.input():read(&middot;&middot;&middot;)</code>.
3170
3171
3172
3173
3174 <p>
3175 <hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3>
3176
3177
3178 <p>
3179 Returns a handle for a temporary file.
3180 This file is opened in update mode
3181 and it is automatically removed when the program ends.
3182
3183
3184
3185
3186 <p>
3187 <hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3>
3188
3189
3190 <p>
3191 Checks whether <code>obj</code> is a valid file handle.
3192 Returns the string <code>"file"</code> if <code>obj</code> is an open file handle,
3193 <code>"closed file"</code> if <code>obj</code> is a closed file handle,
3194 or <b>nil</b> if <code>obj</code> is not a file handle.
3195
3196
3197
3198
3199 <p>
3200 <hr><h3><a name="pdf-io.write"><code>io.write (&middot;&middot;&middot;)</code></a></h3>
3201
3202
3203 <p>
3204 Equivalent to <code>io.output():write(&middot;&middot;&middot;)</code>.
3205
3206
3207
3208
3209 <p>
3210 <hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3>
3211
3212
3213 <p>
3214 Closes <code>file</code>.
3215 Note that files are automatically closed when
3216 their handles are garbage collected,
3217 but that takes an unpredictable amount of time to happen.
3218
3219
3220 <p>
3221 When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>,
3222 <a href="#pdf-file:close"><code>file:close</code></a> returns the same values
3223 returned by <a href="#pdf-os.execute"><code>os.execute</code></a>.
3224
3225
3226
3227
3228 <p>
3229 <hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3>
3230
3231
3232 <p>
3233 Saves any written data to <code>file</code>.
3234
3235
3236
3237
3238 <p>
3239 <hr><h3><a name="pdf-file:lines"><code>file:lines (&middot;&middot;&middot;)</code></a></h3>
3240
3241
3242 <p>
3243 Returns an iterator function that,
3244 each time it is called,
3245 reads the file according to the given formats.
3246 When no format is given,
3247 uses "<code>l</code>" as a default.
3248 As an example, the construction
3249
3250 <pre>
3251 for c in file:lines(1) do <em>body</em> end
3252 </pre><p>
3253 will iterate over all characters of the file,
3254 starting at the current position.
3255 Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
3256 when the loop ends.
3257
3258
3259 <p>
3260 In case of errors this function raises the error,
3261 instead of returning an error code.
3262
3263
3264
3265
3266 <p>
3267 <hr><h3><a name="pdf-file:read"><code>file:read (&middot;&middot;&middot;)</code></a></h3>
3268
3269
3270 <p>
3271 Reads the file <code>file</code>,
3272 according to the given formats, which specify what to read.
3273 For each format,
3274 the function returns a string or a number with the characters read,
3275 or <b>nil</b> if it cannot read data with the specified format.
3276 (In this latter case,
3277 the function does not read subsequent formats.)
3278 When called without formats,
3279 it uses a default format that reads the next line
3280 (see below).
3281
3282
3283 <p>
3284 The available formats are
3285
3286 <ul>
3287
3288 <li><b>"<code>n</code>": </b>
3289 reads a numeral and returns it as a float or an integer,
3290 following the lexical conventions of Lua.
3291 (The numeral may have leading spaces and a sign.)
3292 This format always reads the longest input sequence that
3293 is a valid prefix for a number;
3294 if that prefix does not form a valid number
3295 (e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"),
3296 it is discarded and the function returns <b>nil</b>.
3297 </li>
3298
3299 <li><b>"<code>i</code>": </b>
3300 reads an integral number and returns it as an integer.
3301 </li>
3302
3303 <li><b>"<code>a</code>": </b>
3304 reads the whole file, starting at the current position.
3305 On end of file, it returns the empty string.
3306 </li>
3307
3308 <li><b>"<code>l</code>": </b>
3309 reads the next line skipping the end of line,
3310 returning <b>nil</b> on end of file.
3311 This is the default format.
3312 </li>
3313
3314 <li><b>"<code>L</code>": </b>
3315 reads the next line keeping the end-of-line character (if present),
3316 returning <b>nil</b> on end of file.
3317 </li>
3318
3319 <li><b><em>number</em>: </b>
3320 reads a string with up to this number of bytes,
3321 returning <b>nil</b> on end of file.
3322 If <code>number</code> is zero,
3323 it reads nothing and returns an empty string,
3324 or <b>nil</b> on end of file.
3325 </li>
3326
3327 </ul><p>
3328 The formats "<code>l</code>" and "<code>L</code>" should be used only for text files.
3329
3330
3331
3332
3333 <p>
3334 <hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3>
3335
3336
3337 <p>
3338 Sets and gets the file position,
3339 measured from the beginning of the file,
3340 to the position given by <code>offset</code> plus a base
3341 specified by the string <code>whence</code>, as follows:
3342
3343 <ul>
3344 <li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li>
3345 <li><b>"<code>cur</code>": </b> base is current position;</li>
3346 <li><b>"<code>end</code>": </b> base is end of file;</li>
3347 </ul><p>
3348 In case of success, <code>seek</code> returns the final file position,
3349 measured in bytes from the beginning of the file.
3350 If <code>seek</code> fails, it returns <b>nil</b>,
3351 plus a string describing the error.
3352
3353
3354 <p>
3355 The default value for <code>whence</code> is <code>"cur"</code>,
3356 and for <code>offset</code> is 0.
3357 Therefore, the call <code>file:seek()</code> returns the current
3358 file position, without changing it;
3359 the call <code>file:seek("set")</code> sets the position to the
3360 beginning of the file (and returns 0);
3361 and the call <code>file:seek("end")</code> sets the position to the
3362 end of the file, and returns its size.
3363
3364
3365
3366
3367 <p>
3368 <hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3>
3369
3370
3371 <p>
3372 Sets the buffering mode for an output file.
3373 There are three available modes:
3374
3375 <ul>
3376
3377 <li><b>"<code>no</code>": </b>
3378 no buffering; the result of any output operation appears immediately.
3379 </li>
3380
3381 <li><b>"<code>full</code>": </b>
3382 full buffering; output operation is performed only
3383 when the buffer is full or when
3384 you explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>).
3385 </li>
3386
3387 <li><b>"<code>line</code>": </b>
3388 line buffering; output is buffered until a newline is output
3389 or there is any input from some special files
3390 (such as a terminal device).
3391 </li>
3392
3393 </ul><p>
3394 For the last two cases, <code>size</code>
3395 specifies the size of the buffer, in bytes.
3396 The default is an appropriate size.
3397
3398
3399
3400
3401 <p>
3402 <hr><h3><a name="pdf-file:write"><code>file:write (&middot;&middot;&middot;)</code></a></h3>
3403
3404
3405 <p>
3406 Writes the value of each of its arguments to <code>file</code>.
3407 The arguments must be strings or numbers.
3408
3409
3410 <p>
3411 In case of success, this function returns <code>file</code>.
3412 Otherwise it returns <b>nil</b> plus a string describing the error.
3413
3414
3415
3416
3417
3418
3419
3420 <h2>6.9 &ndash; <a name="6.9">Operating System Facilities</a></h2>
3421
3422 <p>
3423 This library is implemented through table <a name="pdf-os"><code>os</code></a>.
3424
3425
3426 <p>
3427 <hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3>
3428
3429
3430 <p>
3431 Returns an approximation of the amount in seconds of CPU time
3432 used by the program.
3433
3434
3435
3436
3437 <p>
3438 <hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3>
3439
3440
3441 <p>
3442 Returns a string or a table containing date and time,
3443 formatted according to the given string <code>format</code>.
3444
3445
3446 <p>
3447 If the <code>time</code> argument is present,
3448 this is the time to be formatted
3449 (see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
3450 Otherwise, <code>date</code> formats the current time.
3451
3452
3453 <p>
3454 If <code>format</code> starts with '<code>!</code>',
3455 then the date is formatted in Coordinated Universal Time.
3456 After this optional character,
3457 if <code>format</code> is the string "<code>*t</code>",
3458 then <code>date</code> returns a table with the following fields:
3459 <code>year</code> (four digits), <code>month</code> (1&ndash;12), <code>day</code> (1&ndash;31),
3460 <code>hour</code> (0&ndash;23), <code>min</code> (0&ndash;59), <code>sec</code> (0&ndash;61),
3461 <code>wday</code> (weekday, Sunday is&nbsp;1),
3462 <code>yday</code> (day of the year),
3463 and <code>isdst</code> (daylight saving flag, a boolean).
3464 This last field may be absent
3465 if the information is not available.
3466
3467
3468 <p>
3469 If <code>format</code> is not "<code>*t</code>",
3470 then <code>date</code> returns the date as a string,
3471 formatted according to the same rules as the ISO&nbsp;C function <code>strftime</code>.
3472
3473
3474 <p>
3475 When called without arguments,
3476 <code>date</code> returns a reasonable date and time representation that depends on
3477 the host system and on the current locale
3478 (that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>).
3479
3480
3481 <p>
3482 On non-POSIX systems,
3483 this function may be not thread safe
3484 because of its reliance on C&nbsp;function <code>gmtime</code> and C&nbsp;function <code>localtime</code>.
3485
3486
3487
3488
3489 <p>
3490 <hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>
3491
3492
3493 <p>
3494 Returns the difference, in seconds,
3495 from time <code>t1</code> to time <code>t2</code>
3496 (where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>).
3497 In POSIX, Windows, and some other systems,
3498 this value is exactly <code>t2</code><em>-</em><code>t1</code>.
3499
3500
3501
3502
3503 <p>
3504 <hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3>
3505
3506
3507 <p>
3508 This function is equivalent to the ISO&nbsp;C function <code>system</code>.
3509 It passes <code>command</code> to be executed by an operating system shell.
3510 Its first result is <b>true</b>
3511 if the command terminated successfully,
3512 or <b>nil</b> otherwise.
3513 After this first result
3514 the function returns a string plus a number,
3515 as follows:
3516
3517 <ul>
3518
3519 <li><b>"<code>exit</code>": </b>
3520 the command terminated normally;
3521 the following number is the exit status of the command.
3522 </li>
3523
3524 <li><b>"<code>signal</code>": </b>
3525 the command was terminated by a signal;
3526 the following number is the signal that terminated the command.
3527 </li>
3528
3529 </ul>
3530
3531 <p>
3532 When called without a <code>command</code>,
3533 <code>os.execute</code> returns a boolean that is true if a shell is available.
3534
3535
3536
3537
3538 <p>
3539 <hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3>
3540
3541
3542 <p>
3543 Calls the ISO&nbsp;C function <code>exit</code> to terminate the host program.
3544 If <code>code</code> is <b>true</b>,
3545 the returned status is <code>EXIT_SUCCESS</code>;
3546 if <code>code</code> is <b>false</b>,
3547 the returned status is <code>EXIT_FAILURE</code>;
3548 if <code>code</code> is a number,
3549 the returned status is this number.
3550 The default value for <code>code</code> is <b>true</b>.
3551
3552
3553 <p>
3554 If the optional second argument <code>close</code> is true,
3555 closes the Lua state before exiting.
3556
3557
3558
3559
3560 <p>
3561 <hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3>
3562
3563
3564 <p>
3565 Returns the value of the process environment variable <code>varname</code>,
3566 or <b>nil</b> if the variable is not defined.
3567
3568
3569
3570
3571 <p>
3572 <hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3>
3573
3574
3575 <p>
3576 Deletes the file (or empty directory, on POSIX systems)
3577 with the given name.
3578 If this function fails, it returns <b>nil</b>,
3579 plus a string describing the error and the error code.
3580
3581
3582
3583
3584 <p>
3585 <hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3>
3586
3587
3588 <p>
3589 Renames file or directory named <code>oldname</code> to <code>newname</code>.
3590 If this function fails, it returns <b>nil</b>,
3591 plus a string describing the error and the error code.
3592
3593
3594
3595
3596 <p>
3597 <hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3>
3598
3599
3600 <p>
3601 Sets the current locale of the program.
3602 <code>locale</code> is a system-dependent string specifying a locale;
3603 <code>category</code> is an optional string describing which category to change:
3604 <code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>,
3605 <code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>;
3606 the default category is <code>"all"</code>.
3607 The function returns the name of the new locale,
3608 or <b>nil</b> if the request cannot be honored.
3609
3610
3611 <p>
3612 If <code>locale</code> is the empty string,
3613 the current locale is set to an implementation-defined native locale.
3614 If <code>locale</code> is the string "<code>C</code>",
3615 the current locale is set to the standard C locale.
3616
3617
3618 <p>
3619 When called with <b>nil</b> as the first argument,
3620 this function only returns the name of the current locale
3621 for the given category.
3622
3623
3624 <p>
3625 This function may be not thread safe
3626 because of its reliance on C&nbsp;function <code>setlocale</code>.
3627
3628
3629
3630
3631 <p>
3632 <hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3>
3633
3634
3635 <p>
3636 Returns the current time when called without arguments,
3637 or a time representing the date and time specified by the given table.
3638 This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>,
3639 and may have fields
3640 <code>hour</code> (default is 12),
3641 <code>min</code> (default is 0),
3642 <code>sec</code> (default is 0),
3643 and <code>isdst</code> (default is <b>nil</b>).
3644 For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function.
3645
3646
3647 <p>
3648 The returned value is a number, whose meaning depends on your system.
3649 In POSIX, Windows, and some other systems,
3650 this number counts the number
3651 of seconds since some given start time (the "epoch").
3652 In other systems, the meaning is not specified,
3653 and the number returned by <code>time</code> can be used only as an argument to
3654 <a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>.
3655
3656
3657
3658
3659 <p>
3660 <hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3>
3661
3662
3663 <p>
3664 Returns a string with a file name that can
3665 be used for a temporary file.
3666 The file must be explicitly opened before its use
3667 and explicitly removed when no longer needed.
3668
3669
3670 <p>
3671 On POSIX systems,
3672 this function also creates a file with that name,
3673 to avoid security risks.
3674 (Someone else might create the file with wrong permissions
3675 in the time between getting the name and creating the file.)
3676 You still have to open the file to use it
3677 and to remove it (even if you do not use it).
3678
3679
3680 <p>
3681 When possible,
3682 you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>,
3683 which automatically removes the file when the program ends.
3684
3685
3686
3687
3688
3689
3690
3691 <h2>6.10 &ndash; <a name="6.10">The Debug Library</a></h2>
3692
3693 <p>
3694 This library provides
3695 the functionality of the debug interface (<a href="#4.9">&sect;4.9</a>) to Lua programs.
3696 You should exert care when using this library.
3697 Several of its functions
3698 violate basic assumptions about Lua code
3699 (e.g., that variables local to a function
3700 cannot be accessed from outside;
3701 that userdata metatables cannot be changed by Lua code;
3702 that Lua programs do not crash)
3703 and therefore can compromise otherwise secure code.
3704 Moreover, some functions in this library may be slow.
3705
3706
3707 <p>
3708 All functions in this library are provided
3709 inside the <a name="pdf-debug"><code>debug</code></a> table.
3710 All functions that operate over a thread
3711 have an optional first argument which is the
3712 thread to operate over.
3713 The default is always the current thread.
3714
3715
3716 <p>
3717 <hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3>
3718
3719
3720 <p>
3721 Enters an interactive mode with the user,
3722 running each string that the user enters.
3723 Using simple commands and other debug facilities,
3724 the user can inspect global and local variables,
3725 change their values, evaluate expressions, and so on.
3726 A line containing only the word <code>cont</code> finishes this function,
3727 so that the caller continues its execution.
3728
3729
3730 <p>
3731 Note that commands for <code>debug.debug</code> are not lexically nested
3732 within any function and so have no direct access to local variables.
3733
3734
3735
3736
3737 <p>
3738 <hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3>
3739
3740
3741 <p>
3742 Returns the current hook settings of the thread, as three values:
3743 the current hook function, the current hook mask,
3744 and the current hook count
3745 (as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function).
3746
3747
3748
3749
3750 <p>
3751 <hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3>
3752
3753
3754 <p>
3755 Returns a table with information about a function.
3756 You can give the function directly
3757 or you can give a number as the value of <code>f</code>,
3758 which means the function running at level <code>f</code> of the call stack
3759 of the given thread:
3760 level&nbsp;0 is the current function (<code>getinfo</code> itself);
3761 level&nbsp;1 is the function that called <code>getinfo</code>
3762 (except for tail calls, which do not count on the stack);
3763 and so on.
3764 If <code>f</code> is a number larger than the number of active functions,
3765 then <code>getinfo</code> returns <b>nil</b>.
3766
3767
3768 <p>
3769 The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>,
3770 with the string <code>what</code> describing which fields to fill in.
3771 The default for <code>what</code> is to get all information available,
3772 except the table of valid lines.
3773 If present,
3774 the option '<code>f</code>'
3775 adds a field named <code>func</code> with the function itself.
3776 If present,
3777 the option '<code>L</code>'
3778 adds a field named <code>activelines</code> with the table of
3779 valid lines.
3780
3781
3782 <p>
3783 For instance, the expression <code>debug.getinfo(1,"n").name</code> returns
3784 a table with a name for the current function,
3785 if a reasonable name can be found,
3786 and the expression <code>debug.getinfo(print)</code>
3787 returns a table with all available information
3788 about the <a href="#pdf-print"><code>print</code></a> function.
3789
3790
3791
3792
3793 <p>
3794 <hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3>
3795
3796
3797 <p>
3798 This function returns the name and the value of the local variable
3799 with index <code>local</code> of the function at level <code>f</code> of the stack.
3800 This function accesses not only explicit local variables,
3801 but also parameters, temporaries, etc.
3802
3803
3804 <p>
3805 The first parameter or local variable has index&nbsp;1, and so on,
3806 following the order that they are declared in the code,
3807 counting only the variables that are active
3808 in the current scope of the function.
3809 Negative indices refer to vararg parameters;
3810 -1 is the first vararg parameter.
3811 The function returns <b>nil</b> if there is no variable with the given index,
3812 and raises an error when called with a level out of range.
3813 (You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.)
3814
3815
3816 <p>
3817 Variable names starting with '<code>(</code>' (open parenthesis)
3818 represent variables with no known names
3819 (internal variables such as loop control variables,
3820 and variables from chunks saved without debug information).
3821
3822
3823 <p>
3824 The parameter <code>f</code> may also be a function.
3825 In that case, <code>getlocal</code> returns only the name of function parameters.
3826
3827
3828
3829
3830 <p>
3831 <hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3>
3832
3833
3834 <p>
3835 Returns the metatable of the given <code>value</code>
3836 or <b>nil</b> if it does not have a metatable.
3837
3838
3839
3840
3841 <p>
3842 <hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3>
3843
3844
3845 <p>
3846 Returns the registry table (see <a href="#4.5">&sect;4.5</a>).
3847
3848
3849
3850
3851 <p>
3852 <hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3>
3853
3854
3855 <p>
3856 This function returns the name and the value of the upvalue
3857 with index <code>up</code> of the function <code>f</code>.
3858 The function returns <b>nil</b> if there is no upvalue with the given index.
3859
3860
3861 <p>
3862 Variable names starting with '<code>(</code>' (open parenthesis)
3863 represent variables with no known names
3864 (variables from chunks saved without debug information).
3865
3866
3867
3868
3869 <p>
3870 <hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3>
3871
3872
3873 <p>
3874 Returns the Lua value associated to <code>u</code>.
3875 If <code>u</code> is not a userdata,
3876 returns <b>nil</b>.
3877
3878
3879
3880
3881 <p>
3882 <hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3>
3883
3884
3885 <p>
3886 Sets the given function as a hook.
3887 The string <code>mask</code> and the number <code>count</code> describe
3888 when the hook will be called.
3889 The string mask may have any combination of the following characters,
3890 with the given meaning:
3891
3892 <ul>
3893 <li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li>
3894 <li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li>
3895 <li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li>
3896 </ul><p>
3897 Moreover,
3898 with a <code>count</code> different from zero,
3899 the hook is called also after every <code>count</code> instructions.
3900
3901
3902 <p>
3903 When called without arguments,
3904 <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook.
3905
3906
3907 <p>
3908 When the hook is called, its first parameter is a string
3909 describing the event that has triggered its call:
3910 <code>"call"</code> (or <code>"tail call"</code>),
3911 <code>"return"</code>,
3912 <code>"line"</code>, and <code>"count"</code>.
3913 For line events,
3914 the hook also gets the new line number as its second parameter.
3915 Inside a hook,
3916 you can call <code>getinfo</code> with level&nbsp;2 to get more information about
3917 the running function
3918 (level&nbsp;0 is the <code>getinfo</code> function,
3919 and level&nbsp;1 is the hook function).
3920
3921
3922
3923
3924 <p>
3925 <hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3>
3926
3927
3928 <p>
3929 This function assigns the value <code>value</code> to the local variable
3930 with index <code>local</code> of the function at level <code>level</code> of the stack.
3931 The function returns <b>nil</b> if there is no local
3932 variable with the given index,
3933 and raises an error when called with a <code>level</code> out of range.
3934 (You can call <code>getinfo</code> to check whether the level is valid.)
3935 Otherwise, it returns the name of the local variable.
3936
3937
3938 <p>
3939 See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about
3940 variable indices and names.
3941
3942
3943
3944
3945 <p>
3946 <hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3>
3947
3948
3949 <p>
3950 Sets the metatable for the given <code>value</code> to the given <code>table</code>
3951 (which can be <b>nil</b>).
3952 Returns <code>value</code>.
3953
3954
3955
3956
3957 <p>
3958 <hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3>
3959
3960
3961 <p>
3962 This function assigns the value <code>value</code> to the upvalue
3963 with index <code>up</code> of the function <code>f</code>.
3964 The function returns <b>nil</b> if there is no upvalue
3965 with the given index.
3966 Otherwise, it returns the name of the upvalue.
3967
3968
3969
3970
3971 <p>
3972 <hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3>
3973
3974
3975 <p>
3976 Sets the given <code>value</code> as
3977 the Lua value associated to the given <code>udata</code>.
3978 <code>udata</code> must be a full userdata.
3979
3980
3981 <p>
3982 Returns <code>udata</code>.
3983
3984
3985
3986
3987 <p>
3988 <hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3>
3989
3990
3991 <p>
3992 If <code>message</code> is present but is neither a string nor <b>nil</b>,
3993 this function returns <code>message</code> without further processing.
3994 Otherwise,
3995 it returns a string with a traceback of the call stack.
3996 The optional <code>message</code> string is appended
3997 at the beginning of the traceback.
3998 An optional <code>level</code> number tells at which level
3999 to start the traceback
4000 (default is 1, the function calling <code>traceback</code>).
4001
4002
4003
4004
4005 <p>
4006 <hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3>
4007
4008
4009 <p>
4010 Returns a unique identifier (as a light userdata)
4011 for the upvalue numbered <code>n</code>
4012 from the given function.
4013
4014
4015 <p>
4016 These unique identifiers allow a program to check whether different
4017 closures share upvalues.
4018 Lua closures that share an upvalue
4019 (that is, that access a same external local variable)
4020 will return identical ids for those upvalue indices.
4021
4022
4023
4024
4025 <p>
4026 <hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3>
4027
4028
4029 <p>
4030 Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code>
4031 refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>.
4032
4033
4034
4035
4036
4037
4038
4039 <h1>7 &ndash; <a name="7">Lua Standalone</a></h1>
4040
4041 <p>
4042 Although Lua has been designed as an extension language,
4043 to be embedded in a host C&nbsp;program,
4044 it is also frequently used as a standalone language.
4045 An interpreter for Lua as a standalone language,
4046 called simply <code>lua</code>,
4047 is provided with the standard distribution.
4048 The standalone interpreter includes
4049 all standard libraries, including the debug library.
4050 Its usage is:
4051
4052 <pre>
4053 lua [options] [script [args]]
4054 </pre><p>
4055 The options are:
4056
4057 <ul>
4058 <li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li>
4059 <li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li>
4060 <li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li>
4061 <li><b><code>-v</code>: </b> prints version information;</li>
4062 <li><b><code>-E</code>: </b> ignores environment variables;</li>
4063 <li><b><code>--</code>: </b> stops handling options;</li>
4064 <li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li>
4065 </ul><p>
4066 After handling its options, <code>lua</code> runs the given <em>script</em>.
4067 When called without arguments,
4068 <code>lua</code> behaves as <code>lua -v -i</code>
4069 when the standard input (<code>stdin</code>) is a terminal,
4070 and as <code>lua -</code> otherwise.
4071
4072
4073 <p>
4074 When called without option <code>-E</code>,
4075 the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a>
4076 (or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined)
4077 before running any argument.
4078 If the variable content has the format <code>@<em>filename</em></code>,
4079 then <code>lua</code> executes the file.
4080 Otherwise, <code>lua</code> executes the string itself.
4081
4082
4083 <p>
4084 When called with option <code>-E</code>,
4085 besides ignoring <code>LUA_INIT</code>,
4086 Lua also ignores
4087 the values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>,
4088 setting the values of
4089 <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a>
4090 with the default paths defined in <code>luaconf.h</code>.
4091
4092
4093 <p>
4094 All options are handled in order, except <code>-i</code> and <code>-E</code>.
4095 For instance, an invocation like
4096
4097 <pre>
4098 $ lua -e'a=1' -e 'print(a)' script.lua
4099 </pre><p>
4100 will first set <code>a</code> to 1, then print the value of <code>a</code>,
4101 and finally run the file <code>script.lua</code> with no arguments.
4102 (Here <code>$</code> is the shell prompt. Your prompt may be different.)
4103
4104
4105 <p>
4106 Before running any code,
4107 <code>lua</code> collects all command-line arguments
4108 in a global table called <code>arg</code>.
4109 The script name goes to index 0,
4110 the first argument after the script name goes to index 1,
4111 and so on.
4112 Any arguments before the script name
4113 (that is, the interpreter name plus its options)
4114 go to negative indices.
4115 For instance, in the call
4116
4117 <pre>
4118 $ lua -la b.lua t1 t2
4119 </pre><p>
4120 the table is like this:
4121
4122 <pre>
4123 arg = { [-2] = "lua", [-1] = "-la",
4124 [0] = "b.lua",
4125 [1] = "t1", [2] = "t2" }
4126 </pre><p>
4127 If there is no script in the call,
4128 the interpreter name goes to index 0,
4129 followed by the other arguments.
4130 For instance, the call
4131
4132 <pre>
4133 $ lua -e "print(arg[1])"
4134 </pre><p>
4135 will print "<code>-e</code>".
4136 If there is a script,
4137 the script is called with parameters
4138 <code>arg[1]</code>, &middot;&middot;&middot;, <code>arg[#arg]</code>.
4139 (Like all chunks in Lua,
4140 the script is compiled as a vararg function.)
4141
4142
4143 <p>
4144 In interactive mode,
4145 Lua repeatedly prompts and waits for a line.
4146 After reading a line,
4147 Lua first try to interpret the line as an expression.
4148 If it succeeds, it prints its value.
4149 Otherwise, it interprets the line as a statement.
4150 If you write an incomplete statement,
4151 the interpreter waits for its completion
4152 by issuing a different prompt.
4153
4154
4155 <p>
4156 In case of unprotected errors in the script,
4157 the interpreter reports the error to the standard error stream.
4158 If the error object is not a string but
4159 has a metamethod <code>__to_string</code>,
4160 the interpreter calls this metamethod to produce the final message.
4161 Otherwise, the interpreter converts the error object to a string
4162 and adds a stack traceback to it.
4163
4164
4165 <p>
4166 When finishing normally,
4167 the interpreter closes its main Lua state
4168 (see <a href="#lua_close"><code>lua_close</code></a>).
4169 The script can avoid this step by
4170 calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate.
4171
4172
4173 <p>
4174 To allow the use of Lua as a
4175 script interpreter in Unix systems,
4176 the standalone interpreter skips
4177 the first line of a chunk if it starts with <code>#</code>.
4178 Therefore, Lua scripts can be made into executable programs
4179 by using <code>chmod +x</code> and the&nbsp;<code>#!</code> form,
4180 as in
4181
4182 <pre>
4183 #!/usr/local/bin/lua
4184 </pre><p>
4185 (Of course,
4186 the location of the Lua interpreter may be different in your machine.
4187 If <code>lua</code> is in your <code>PATH</code>,
4188 then
4189
4190 <pre>
4191 #!/usr/bin/env lua
4192 </pre><p>
4193 is a more portable solution.)
4194
4195
4196
4197 <h1>8 &ndash; <a name="8">Incompatibilities with the Previous Version</a></h1>
4198
4199 <p>
4200 Here we list the incompatibilities that you may find when moving a program
4201 from Lua&nbsp;5.2 to Lua&nbsp;5.3.
4202 You can avoid some incompatibilities by compiling Lua with
4203 appropriate options (see file <code>luaconf.h</code>).
4204 However,
4205 all these compatibility options will be removed in the future.
4206
4207
4208 <p>
4209 Lua versions can always change the C API in ways that
4210 do not imply source-code changes in a program,
4211 such as the numeric values for constants
4212 or the implementation of functions as macros.
4213 Therefore,
4214 you should not assume that binaries are compatible between
4215 different Lua versions.
4216 Always recompile clients of the Lua API when
4217 using a new version.
4218
4219
4220 <p>
4221 Similarly, Lua versions can always change the internal representation
4222 of precompiled chunks;
4223 precompiled chunks are not compatible between different Lua versions.
4224
4225
4226 <p>
4227 The standard paths in the official distribution may
4228 change between versions.
4229
4230
4231
4232 <h2>8.1 &ndash; <a name="8.1">Changes in the Language</a></h2>
4233 <ul>
4234
4235 <li>
4236 The main difference between Lua&nbsp;5.2 and Lua&nbsp;5.3 is the
4237 introduction of an integer subtype for numbers.
4238 Although this change should not affect "normal" computations,
4239 some computations
4240 (mainly those that involve some kind of overflow)
4241 can give different results.
4242
4243
4244 <p>
4245 You can fix these differences by forcing a number to be a float
4246 (in Lua&nbsp;5.2 all numbers were float),
4247 in particular writing constants with an ending <code>.0</code>
4248 or using <code>x = x + 0.0</code> to convert a variable.
4249 (This recommendation is only for a quick fix
4250 for an occasional incompatibility;
4251 it is not a general guideline for good programming.
4252 For good programming,
4253 use floats where you need floats
4254 and integers where you need integers.)
4255 </li>
4256
4257 <li>
4258 The conversion of a float to a string now adds a <code>.0</code> suffix
4259 to the result if it looks like an integer.
4260 (For instance, the float 2.0 will be printed as <code>2.0</code>,
4261 not as <code>2</code>.)
4262 You should always use an explicit format
4263 when you need a specific format for numbers.
4264
4265
4266 <p>
4267 (Formally this is not an incompatibility,
4268 because Lua does not specify how numbers are formatted as strings,
4269 but some programs assumed a specific format.)
4270 </li>
4271
4272 <li>
4273 The generational mode for the garbage collector was removed.
4274 (It was an experimental feature in Lua&nbsp;5.2.)
4275 </li>
4276
4277 </ul>
4278
4279
4280
4281
4282 <h2>8.2 &ndash; <a name="8.2">Changes in the Libraries</a></h2>
4283 <ul>
4284
4285 <li>
4286 The <code>bit32</code> library has been deprecated.
4287 It is easy to require a compatible external library or,
4288 better yet, to replace its functions with appropriate bitwise operations.
4289 (Keep in mind that <code>bit32</code> operates on 32-bit integers,
4290 while the bitwise operators in standard Lua operate on 64-bit integers.)
4291 </li>
4292
4293 <li>
4294 The Table library now respects metamethods
4295 for setting and getting elements.
4296 </li>
4297
4298 <li>
4299 The <a href="#pdf-ipairs"><code>ipairs</code></a> iterator now respects metamethods and
4300 its <code>__ipairs</code> metamethod has been deprecated.
4301 </li>
4302
4303 <li>
4304 Option names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore.
4305 For compatibility, Lua will continue to ignore this character.
4306 </li>
4307
4308 <li>
4309 The following functions were deprecated in the mathematical library:
4310 <code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>,
4311 <code>frexp</code>, and <code>ldexp</code>.
4312 You can replace <code>math.pow(x,y)</code> with <code>x^y</code>;
4313 you can replace <code>math.atan2</code> with <code>math.atan</code>,
4314 which now accepts one or two parameters;
4315 you can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>.
4316 For the other operations,
4317 you can either use an external library or
4318 implement them in Lua.
4319 </li>
4320
4321 <li>
4322 The searcher for C loaders used by <a href="#pdf-require"><code>require</code></a>
4323 changed the way it handles versioned names.
4324 Now, the version should come after the module name
4325 (as is usual in most other tools).
4326 For compatibility, that searcher still tries the old format
4327 if it cannot find an open function according to the new style.
4328 (Lua&nbsp;5.2 already worked that way,
4329 but it did not document the change.)
4330 </li>
4331
4332 </ul>
4333
4334
4335
4336
4337 <h2>8.3 &ndash; <a name="8.3">Changes in the API</a></h2>
4338
4339
4340 <ul>
4341
4342 <li>
4343 Continuation functions now receive as parameters what they needed
4344 to get through <code>lua_getctx</code>,
4345 so <code>lua_getctx</code> has been removed.
4346 Adapt your code accordingly.
4347 </li>
4348
4349 <li>
4350 Function <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>.
4351 Use 0 as the value of this parameter to get the old behavior.
4352 </li>
4353
4354 <li>
4355 Functions to inject/project unsigned integers
4356 (<code>lua_pushunsigned</code>, <code>lua_tounsigned</code>, <code>lua_tounsignedx</code>,
4357 <code>luaL_checkunsigned</code>, <code>luaL_optunsigned</code>)
4358 were deprecated.
4359 Use their signed equivalents with a type cast.
4360 </li>
4361
4362 <li>
4363 Macros to project non-default integer types
4364 (<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>)
4365 were deprecated.
4366 Use their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast
4367 (or, when possible, use <a href="#lua_Integer"><code>lua_Integer</code></a> in your code).
4368 </li>
4369
4370 </ul>
4371
4372
4373
4374
4375 <h1>9 &ndash; <a name="9">The Complete Syntax of Lua</a></h1>
4376
4377 <p>
4378 Here is the complete syntax of Lua in extended BNF.
4379 As usual in extended BNF,
4380 {A} means 0 or more As,
4381 and [A] means an optional A.
4382 (For operator precedences, see <a href="#3.4.8">&sect;3.4.8</a>;
4383 for a description of the terminals
4384 Name, Numeral,
4385 and LiteralString, see <a href="#3.1">&sect;3.1</a>.)
4386
4387
4388
4389
4390 <pre>
4391
4392 chunk ::= block
4393
4394 block ::= {stat} [retstat]
4395
4396 stat ::= &lsquo;<b>;</b>&rsquo; |
4397 varlist &lsquo;<b>=</b>&rsquo; explist |
4398 functioncall |
4399 label |
4400 <b>break</b> |
4401 <b>goto</b> Name |
4402 <b>do</b> block <b>end</b> |
4403 <b>while</b> exp <b>do</b> block <b>end</b> |
4404 <b>repeat</b> block <b>until</b> exp |
4405 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> |
4406 <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> |
4407 <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> |
4408 <b>function</b> funcname funcbody |
4409 <b>local</b> <b>function</b> Name funcbody |
4410 <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist]
4411
4412 retstat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
4413
4414 label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
4415
4416 funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
4417
4418 varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
4419
4420 var ::= Name | prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; | prefixexp &lsquo;<b>.</b>&rsquo; Name
4421
4422 namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
4423
4424 explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
4425
4426 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | &lsquo;<b>...</b>&rsquo; | functiondef |
4427 prefixexp | tableconstructor | exp binop exp | unop exp
4428
4429 prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
4430
4431 functioncall ::= prefixexp args | prefixexp &lsquo;<b>:</b>&rsquo; Name args
4432
4433 args ::= &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo; | tableconstructor | LiteralString
4434
4435 functiondef ::= <b>function</b> funcbody
4436
4437 funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
4438
4439 parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
4440
4441 tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
4442
4443 fieldlist ::= field {fieldsep field} [fieldsep]
4444
4445 field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
4446
4447 fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
4448
4449 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; |
4450 &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; |
4451 &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; |
4452 <b>and</b> | <b>or</b>
4453
4454 unop ::= &lsquo;<b>-</b>&rsquo; | <b>not</b> | &lsquo;<b>#</b>&rsquo; | &lsquo;<b>~</b>&rsquo;
4455
4456 </pre>
4457
4458 <p>
4459
4460
4461
4462
4463
4464
4465
4466
4467 <HR>
4468 <SMALL CLASS="footer">
4469 Last update:
4470 Fri Jan 16 00:58:20 BRST 2015
4471 </SMALL>
4472 <!--
4473 Last change: minor edit
4474 -->
4475
4476 </div> 3379 </div>
4477 </body> 3380 </body>
4478 </html> 3381 </html>
4479 <% 3382 <%
4480 end 3383 end