comparison website/src/manual.html.luan @ 562:7cc9d4a53d3b

remove SimplyHTML from documentation
author Franklin Schmidt <fschmidt@gmail.com>
date Wed, 24 Jun 2015 14:20:00 -0600
parents d02f43598ba3
children 22bfd8a2eaee
comparison
equal deleted inserted replaced
561:363d07e26549 562:7cc9d4a53d3b
1 local Luan = require "luan:Luan" 1 local Luan = require "luan:Luan"
2 local Io = require "luan:Io" 2 local Io = require "luan:Io"
3 local Html = require "luan:Html" 3 local Html = require "luan:Html"
4 local Http = require "luan:http/Http" 4 local Http = require "luan:http/Http"
5 local Shared = require "site:/Shared" 5 local Shared = require "site:/Shared"
6 local heading_options = Shared.heading_options
7 6
8 7
9 return function() 8 return function()
10 Io.stdout = Http.response.text_writer() 9 Io.stdout = Http.response.text_writer()
11 %> 10 %>
12 <html> 11 <html>
13 <head> 12 <head>
14 <% Html.simply_html_head() %>
15 <title>Luan Reference Manual</title> 13 <title>Luan Reference Manual</title>
14 <style>
15 @import "/site.css";
16 </style>
16 </head> 17 </head>
17 <body> 18 <body>
18 19
19 <div container> 20 <div container>
20 <% Shared.header() %> 21 <% Shared.header() %>
21 22
22 <h1>Luan Reference Manual</h1> 23 <h1>Luan Reference Manual</h1>
23 24
24 <p> 25 <p small>
25 <small>
26 Original copyright &copy; 2015 Lua.org, PUC-Rio. 26 Original copyright &copy; 2015 Lua.org, PUC-Rio.
27 Freely available under the terms of the 27 Freely available under the terms of the
28 <a href="http://www.lua.org/license.html">Lua license</a>. 28 <a href="http://www.lua.org/license.html">Lua license</a>.
29 Modified for Luan. 29 Modified for Luan.
30 </small>
31 </p> 30 </p>
32 31
33 <hr/> 32 <hr/>
34 33
35 <h2>Contents</h2> 34 <h2>Contents</h2>
36 35
37 <div margin-bottom="1em"><a href="#intro">Introduction</a></div> 36 <div contents><a href="#intro">Introduction</a></div>
38 37
39 <div margin-bottom="1em"> 38 <div contents>
40 <a href="#basic">Basic Concepts</a> 39 <a href="#basic">Basic Concepts</a>
41 <ul> 40 <ul>
42 <li><a href="#types">Values and Types</a></li> 41 <li><a href="#types">Values and Types</a></li>
43 <li><a href="#env">Environments</a></li> 42 <li><a href="#env">Environments</a></li>
44 <li><a href="#error">Error Handling</a></li> 43 <li><a href="#error">Error Handling</a></li>
45 <li><a href="#meta">Metatables and Metamethods</a></li> 44 <li><a href="#meta">Metatables and Metamethods</a></li>
46 <li><a href="#gc">Garbage Collection</a></li> 45 <li><a href="#gc">Garbage Collection</a></li>
47 </ul> 46 </ul>
48 </div> 47 </div>
49 48
50 <div margin-bottom="1em"> 49 <div contents>
51 <a href="#lang">The Language</a> 50 <a href="#lang">The Language</a>
52 <ul> 51 <ul>
53 <li><a href="#lex">Lexical Conventions</a></li> 52 <li><a href="#lex">Lexical Conventions</a></li>
54 <li><a href="#vars">Variables</a></li> 53 <li><a href="#vars">Variables</a></li>
55 <li> 54 <li>
83 </li> 82 </li>
84 <li><a href="#visibility">Visibility Rules</a></li> 83 <li><a href="#visibility">Visibility Rules</a></li>
85 </ul> 84 </ul>
86 </div> 85 </div>
87 86
88 <div margin-bottom="1em"> 87 <div contents>
89 <a href="#libs">Standard Libraries</a> 88 <a href="#libs">Standard Libraries</a>
90 <ul> 89 <ul>
91 <li><a href="#default_lib">Default Environment</a></li> 90 <li><a href="#default_lib">Default Environment</a></li>
92 <li><a href="#luan_lib">Basic Functions</a></li> 91 <li><a href="#luan_lib">Basic Functions</a></li>
93 <li><a href="#package_lib">Modules</a></li> 92 <li><a href="#package_lib">Modules</a></li>
96 </div> 95 </div>
97 96
98 <hr/> 97 <hr/>
99 98
100 99
101 <h2 <%=heading_options%> ><a name="intro">Introduction</a></h2> 100 <h2 heading><a name="intro">Introduction</a></h2>
102 101
103 <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> 102 <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>
104 103
105 <p>Luan is implemented in Java and is tightly coupled with Java. So it makes a great scripting language for Java programmers.</p> 104 <p>Luan is implemented in Java and is tightly coupled with Java. So it makes a great scripting language for Java programmers.</p>
106 105
107 <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> 106 <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>
108 107
109 108
110 <h2 <%=heading_options%> ><a name="basic">Basic Concepts</a></h2> 109 <h2 heading><a name="basic">Basic Concepts</a></h2>
111 110
112 <p>This section describes the basic concepts of the language.</p> 111 <p>This section describes the basic concepts of the language.</p>
113 112
114 <h3 <%=heading_options%> ><a name="types">Values and Types</a></h3> 113 <h3 heading><a name="types">Values and Types</a></h3>
115 114
116 <p> 115 <p>
117 Luan is a <i>dynamically typed language</i>. 116 Luan is a <em>dynamically typed language</em>.
118 This means that 117 This means that
119 variables do not have types; only values do. 118 variables do not have types; only values do.
120 There are no type definitions in the language. 119 There are no type definitions in the language.
121 All values carry their own type. 120 All values carry their own type.
122 121
123 122
124 <p> 123 <p>
125 All values in Luan are <i>first-class values</i>. 124 All values in Luan are <em>first-class values</em>.
126 This means that all values can be stored in variables, 125 This means that all values can be stored in variables,
127 passed as arguments to other functions, and returned as results. 126 passed as arguments to other functions, and returned as results.
128 127
129 128
130 <p> 129 <p>
131 There are eight basic types in Luan: 130 There are eight basic types in Luan:
132 <i>nil</i>, <i>boolean</i>, <i>number</i>, 131 <em>nil</em>, <em>boolean</em>, <em>number</em>,
133 <i>string</i>, <i>binary</i>, <i>function</i>, <i>java</i>, 132 <em>string</em>, <em>binary</em>, <em>function</em>, <em>java</em>,
134 and <i>table</i>. 133 and <em>table</em>.
135 <i>Nil</i> is the type of the value <b>nil</b>, 134 <em>Nil</em> is the type of the value <b>nil</b>,
136 whose main property is to be different from any other value; 135 whose main property is to be different from any other value;
137 it usually represents the absence of a useful value. 136 it usually represents the absence of a useful value.
138 <i>Nil</i> is implemented as the Java value <i>null</i>. 137 <em>Nil</em> is implemented as the Java value <em>null</em>.
139 <i>Boolean</i> is the type of the values <b>false</b> and <b>true</b>. 138 <em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>.
140 <i>Boolean</i> is implemented as the Java class <i>Boolean</i>. 139 <em>Boolean</em> is implemented as the Java class <em>Boolean</em>.
141 <i>Number</i> represents both 140 <em>Number</em> represents both
142 integer numbers and real (floating-point) numbers. 141 integer numbers and real (floating-point) numbers.
143 <i>Number</i> is implemented as the Java class <i>Number</i>. Any Java subclass of <i>Number</i> is allowed and this is invisible to the Luan user. Operations on numbers follow the same rules of 142 <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
144 the underlying Java implementation. 143 the underlying Java implementation.
145 144
146 <i>String</i> is implemented as the Java class <i>String</i>. 145 <em>String</em> is implemented as the Java class <em>String</em>.
147 <i>Binary</i> is implemented as the Java type <i>byte[]</i>. 146 <em>Binary</em> is implemented as the Java type <em>byte[]</em>.
148 147
149 148
150 <p> 149 <p>
151 Luan can call (and manipulate) functions written in Luan and 150 Luan can call (and manipulate) functions written in Luan and
152 functions written in Java (see <a href="#fn_calls">Function Calls</a>). 151 functions written in Java (see <a href="#fn_calls">Function Calls</a>).
153 Both are represented by the type <i>function</i>. 152 Both are represented by the type <em>function</em>.
154 153
155 154
156 <p> 155 <p>
157 The type <i>java</i> is provided to allow arbitrary Java objects to 156 The type <em>java</em> is provided to allow arbitrary Java objects to
158 be stored in Luan variables. 157 be stored in Luan variables.
159 A <i>java</i> value is a Java object that isn't one of the standard Luan types. 158 A <em>java</em> value is a Java object that isn't one of the standard Luan types.
160 Java values have no predefined operations in Luan, 159 Java values have no predefined operations in Luan,
161 except assignment and identity test. 160 except assignment and identity test.
162 Java values are useful when Java access is enabled in Luan 161 Java values are useful when Java access is enabled in Luan
163 162
164 163
165 164
166 <p> 165 <p>
167 The type <i>table</i> implements associative arrays, 166 The type <em>table</em> implements associative arrays,
168 that is, arrays that can be indexed not only with numbers, 167 that is, arrays that can be indexed not only with numbers,
169 but with any Luan value except <b>nil</b>. 168 but with any Luan value except <b>nil</b>.
170 Tables can be <i>heterogeneous</i>; 169 Tables can be <em>heterogeneous</em>;
171 that is, they can contain values of all types (except <b>nil</b>). 170 that is, they can contain values of all types (except <b>nil</b>).
172 Any key with value <b>nil</b> is not considered part of the table. 171 Any key with value <b>nil</b> is not considered part of the table.
173 Conversely, any key that is not part of a table has 172 Conversely, any key that is not part of a table has
174 an associated value <b>nil</b>. 173 an associated value <b>nil</b>.
175 174
178 Tables are the sole data-structuring mechanism in Luan; 177 Tables are the sole data-structuring mechanism in Luan;
179 they can be used to represent ordinary arrays, sequences, 178 they can be used to represent ordinary arrays, sequences,
180 symbol tables, sets, records, graphs, trees, etc. 179 symbol tables, sets, records, graphs, trees, etc.
181 To represent records, Luan uses the field name as an index. 180 To represent records, Luan uses the field name as an index.
182 The language supports this representation by 181 The language supports this representation by
183 providing <tt>a.name</tt> as syntactic sugar for <tt>a["name"]</tt>. 182 providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>.
184 There are several convenient ways to create tables in Luan 183 There are several convenient ways to create tables in Luan
185 (see <a href="#constructors">Table Constructors</a>). 184 (see <a href="#constructors">Table Constructors</a>).
186 185
187 186
188 <p> 187 <p>
189 We use the term <i>sequence</i> to denote a table where 188 We use the term <em>sequence</em> to denote a table where
190 the set of all positive numeric keys is equal to {1..<i>n</i>} 189 the set of all positive numeric keys is equal to {1..<em>n</em>}
191 for some non-negative integer <i>n</i>, 190 for some non-negative integer <em>n</em>,
192 which is called the length of the sequence (see <a href="#length">The Length Operator</a>). 191 which is called the length of the sequence (see <a href="#length">The Length Operator</a>).
193 192
194 193
195 <p> 194 <p>
196 Like indices, 195 Like indices,
197 the values of table fields can be of any type. 196 the values of table fields can be of any type.
198 In particular, 197 In particular,
199 because functions are first-class values, 198 because functions are first-class values,
200 table fields can contain functions. 199 table fields can contain functions.
201 Thus tables can also carry <i>methods</i> (see <a href="#fn_def">Function Definitions</a>). 200 Thus tables can also carry <em>methods</em> (see <a href="#fn_def">Function Definitions</a>).
202 201
203 202
204 <p> 203 <p>
205 The indexing of tables follows 204 The indexing of tables follows
206 the definition of raw equality in the language. 205 the definition of raw equality in the language.
207 The expressions <tt>a[i]</tt> and <tt>a[j]</tt> 206 The expressions <code>a[i]</code> and <code>a[j]</code>
208 denote the same table element 207 denote the same table element
209 if and only if <tt>i</tt> and <tt>j</tt> are raw equal 208 if and only if <code>i</code> and <code>j</code> are raw equal
210 (that is, equal without metamethods). 209 (that is, equal without metamethods).
211 In particular, floats with integral values 210 In particular, floats with integral values
212 are equal to their respective integers 211 are equal to their respective integers
213 (e.g., <tt>1.0 == 1</tt>). 212 (e.g., <code>1.0 == 1</code>).
214 213
215 214
216 <p> 215 <p>
217 Luan values are <i>objects</i>: 216 Luan values are <em>objects</em>:
218 variables do not actually <i>contain</i> values, 217 variables do not actually <em>contain</em> values,
219 only <i>references</i> to them. 218 only <em>references</em> to them.
220 Assignment, parameter passing, and function returns 219 Assignment, parameter passing, and function returns
221 always manipulate references to values; 220 always manipulate references to values;
222 these operations do not imply any kind of copy. 221 these operations do not imply any kind of copy.
223 222
224 223
225 <p> 224 <p>
226 The library function <a href="#Luan.type"><tt>Luan.type</tt></a> returns a string describing the type 225 The library function <a href="#Luan.type"><code>Luan.type</code></a> returns a string describing the type
227 of a given value. 226 of a given value.
228 227
229 228
230 229
231 230
232 231
233 <h3 <%=heading_options%> ><a name="env">Environments</a></h3> 232 <h3 heading><a name="env">Environments</a></h3>
234 233
235 <p> 234 <p>
236 The environment of a chunk starts with only two local variables: <tt><a href="#require">require</a></tt> and <tt><a href="#java">java</a></tt>. These are functions are 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>. 235 The environment of a chunk starts with only two local variables: <code><a href="#require">require</a></code> and <code><a href="#java">java</a></code>. These are functions are 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>.
237 236
238 <p> 237 <p>
239 As will be discussed in <a href="#vars">Variables</a> and <a href=#assignment">Assignment</a>, 238 As will be discussed in <a href="#vars">Variables</a> and <a href=#assignment">Assignment</a>,
240 any reference to a free name 239 any reference to a free name
241 (that is, a name not bound to any declaration) <tt>var</tt> 240 (that is, a name not bound to any declaration) <code>var</code>
242 can be syntactically translated to <tt>_ENV.var</tt> if <tt>_ENV</tt> is defined. 241 can be syntactically translated to <code>_ENV.var</code> if <code>_ENV</code> is defined.
243 242
244 243
245 <h3 <%=heading_options%> ><a name="error">Error Handling</a></h3> 244 <h3 heading><a name="error">Error Handling</a></h3>
246 245
247 <p> 246 <p>
248 Luan code can explicitly generate an error by calling the 247 Luan code can explicitly generate an error by calling the
249 <a href="#Luan.error"><tt>error</tt></a> function. 248 <a href="#Luan.error"><code>error</code></a> function.
250 If you need to catch errors in Luan, 249 If you need to catch errors in Luan,
251 you can use <a href="#Luan.pcall"><tt>pcall</tt></a> or <a href="#Luan.try"><tt>try</tt></a> 250 you can use <a href="#Luan.pcall"><code>pcall</code></a> or <a href="#Luan.try"><code>try</code></a>
252 to call a given function in <i>protected mode</i>. 251 to call a given function in <em>protected mode</em>.
253 252
254 253
255 <p> 254 <p>
256 Whenever there is an error, 255 Whenever there is an error,
257 an <i>error table</i> 256 an <em>error table</em>
258 is propagated with information about the error. 257 is propagated with information about the error.
259 See <a href="#Luan.new_error"><tt>Luan.new_error</tt></a>. 258 See <a href="#Luan.new_error"><code>Luan.new_error</code></a>.
260 259
261 260
262 261
263 <h3 <%=heading_options%> ><a name="meta">Metatables and Metamethods</a></h3> 262 <h3 heading><a name="meta">Metatables and Metamethods</a></h3>
264 263
265 <p> 264 <p>
266 Every table in Luan can have a <i>metatable</i>. 265 Every table in Luan can have a <em>metatable</em>.
267 This <i>metatable</i> is an ordinary Luan table 266 This <em>metatable</em> is an ordinary Luan table
268 that defines the behavior of the original value 267 that defines the behavior of the original value
269 under certain special operations. 268 under certain special operations.
270 You can change several aspects of the behavior 269 You can change several aspects of the behavior
271 of operations over a value by setting specific fields in its metatable. 270 of operations over a value by setting specific fields in its metatable.
272 For instance, when a table is the operand of an addition, 271 For instance, when a table is the operand of an addition,
273 Luan checks for a function in the field "<tt>__add</tt>" of the table's metatable. 272 Luan checks for a function in the field "<code>__add</code>" of the table's metatable.
274 If it finds one, 273 If it finds one,
275 Luan calls this function to perform the addition. 274 Luan calls this function to perform the addition.
276 275
277 276
278 <p> 277 <p>
279 The keys in a metatable are derived from the <i>event</i> names; 278 The keys in a metatable are derived from the <em>event</em> names;
280 the corresponding values are called <ii>metamethods</i>. 279 the corresponding values are called <ii>metamethods</em>.
281 In the previous example, the event is <tt>"add"</tt> 280 In the previous example, the event is <code>"add"</code>
282 and the metamethod is the function that performs the addition. 281 and the metamethod is the function that performs the addition.
283 282
284 283
285 <p> 284 <p>
286 You can query the metatable of any table 285 You can query the metatable of any table
287 using the <a href="#Luan.get_metatable"><tt>get_metatable</tt></a> function. 286 using the <a href="#Luan.get_metatable"><code>get_metatable</code></a> function.
288 287
289 288
290 <p> 289 <p>
291 You can replace the metatable of tables 290 You can replace the metatable of tables
292 using the <a href="#Luan.set_metatable"><tt>set_metatable</tt></a> function. 291 using the <a href="#Luan.set_metatable"><code>set_metatable</code></a> function.
293 292
294 293
295 <p> 294 <p>
296 A metatable controls how a table behaves in 295 A metatable controls how a table behaves in
297 arithmetic operations, bitwise operations, 296 arithmetic operations, bitwise operations,
300 299
301 <p> 300 <p>
302 A detailed list of events controlled by metatables is given next. 301 A detailed list of events controlled by metatables is given next.
303 Each operation is identified by its corresponding event name. 302 Each operation is identified by its corresponding event name.
304 The key for each event is a string with its name prefixed by 303 The key for each event is a string with its name prefixed by
305 two underscores, '<tt>__</tt>'; 304 two underscores, '<code>__</code>';
306 for instance, the key for operation "add" is the 305 for instance, the key for operation "add" is the
307 string "<tt>__add</tt>". 306 string "<code>__add</code>".
308 Note that queries for metamethods are always raw; 307 Note that queries for metamethods are always raw;
309 the access to a metamethod does not invoke other metamethods. 308 the access to a metamethod does not invoke other metamethods.
310 You can emulate how Luan queries a metamethod for an object <tt>obj</tt> 309 You can emulate how Luan queries a metamethod for an object <code>obj</code>
311 with the following code: 310 with the following code:
312 311
313 <p><tt><pre> 312 <pre>
314 raw_get(get_metatable(obj) or {}, "__" .. event_name) 313 raw_get(get_metatable(obj) or {}, "__" .. event_name)
315 </pre></tt></p> 314 </pre>
316 315
317 <p> 316 <p>
318 Here are the events: 317 Here are the events:
319 318
320 <ul> 319 <ul>
321 320
322 <li><p><b>"add": </b> 321 <li><p><b>"add": </b>
323 the <tt>+</tt> operation. 322 the <code>+</code> operation.
324 323
325 If any operand for an addition is a table, 324 If any operand for an addition is a table,
326 Luan will try to call a metamethod. 325 Luan will try to call a metamethod.
327 First, Luan will check the first operand (even if it is valid). 326 First, Luan will check the first operand (even if it is valid).
328 If that operand does not define a metamethod for the "<tt>__add</tt>" event, 327 If that operand does not define a metamethod for the "<code>__add</code>" event,
329 then Luan will check the second operand. 328 then Luan will check the second operand.
330 If Luan can find a metamethod, 329 If Luan can find a metamethod,
331 it calls the metamethod with the two operands as arguments, 330 it calls the metamethod with the two operands as arguments,
332 and the result of the call 331 and the result of the call
333 (adjusted to one value) 332 (adjusted to one value)
335 Otherwise, 334 Otherwise,
336 it raises an error. 335 it raises an error.
337 </li> 336 </li>
338 337
339 <li><p><b>"sub": </b> 338 <li><p><b>"sub": </b>
340 the <tt>-</tt> operation. 339 the <code>-</code> operation.
341 340
342 Behavior similar to the "add" operation. 341 Behavior similar to the "add" operation.
343 </li> 342 </li>
344 343
345 <li><p><b>"mul": </b> 344 <li><p><b>"mul": </b>
346 the <tt>*</tt> operation. 345 the <code>*</code> operation.
347 346
348 Behavior similar to the "add" operation. 347 Behavior similar to the "add" operation.
349 </li> 348 </li>
350 349
351 <li><p><b>"div": </b> 350 <li><p><b>"div": </b>
352 the <tt>/</tt> operation. 351 the <code>/</code> operation.
353 352
354 Behavior similar to the "add" operation. 353 Behavior similar to the "add" operation.
355 </li> 354 </li>
356 355
357 <li><p><b>"mod": </b> 356 <li><p><b>"mod": </b>
358 the <tt>%</tt> operation. 357 the <code>%</code> operation.
359 358
360 Behavior similar to the "add" operation. 359 Behavior similar to the "add" operation.
361 </li> 360 </li>
362 361
363 <li><p><b>"pow": </b> 362 <li><p><b>"pow": </b>
364 the <tt>^</tt> (exponentiation) operation. 363 the <code>^</code> (exponentiation) operation.
365 364
366 Behavior similar to the "add" operation. 365 Behavior similar to the "add" operation.
367 </li> 366 </li>
368 367
369 <li><p><b>"unm": </b> 368 <li><p><b>"unm": </b>
370 the <tt>-</tt> (unary minus) operation. 369 the <code>-</code> (unary minus) operation.
371 370
372 Behavior similar to the "add" operation. 371 Behavior similar to the "add" operation.
373 </li> 372 </li>
374 373
375 <li><p><b>"concat": </b> 374 <li><p><b>"concat": </b>
376 the <tt>..</tt> (concatenation) operation. 375 the <code>..</code> (concatenation) operation.
377 376
378 Behavior similar to the "add" operation. 377 Behavior similar to the "add" operation.
379 </li> 378 </li>
380 379
381 <li><p><b>"len": </b> 380 <li><p><b>"len": </b>
382 the <tt>#</tt> (length) operation. 381 the <code>#</code> (length) operation.
383 382
384 If there is a metamethod, 383 If there is a metamethod,
385 Luan calls it with the object as argument, 384 Luan calls it with the object as argument,
386 and the result of the call 385 and the result of the call
387 (always adjusted to one value) 386 (always adjusted to one value)
390 then Luan uses the table length operation (see <a href="#length">The Length Operator</a>). 389 then Luan uses the table length operation (see <a href="#length">The Length Operator</a>).
391 Otherwise, Luan raises an error. 390 Otherwise, Luan raises an error.
392 </li> 391 </li>
393 392
394 <li><p><b>"eq": </b> 393 <li><p><b>"eq": </b>
395 the <tt>==</tt> (equal) operation. 394 the <code>==</code> (equal) operation.
396 395
397 Behavior similar to the "add" operation, 396 Behavior similar to the "add" operation,
398 except that Luan will try a metamethod only when the values 397 except that Luan will try a metamethod only when the values
399 being compared are both tables 398 being compared are both tables
400 and they are not primitively equal. 399 and they are not primitively equal.
401 The result of the call is always converted to a boolean. 400 The result of the call is always converted to a boolean.
402 </li> 401 </li>
403 402
404 <li><p><b>"lt": </b> 403 <li><p><b>"lt": </b>
405 the <tt>&lt;</tt> (less than) operation. 404 the <code>&lt;</code> (less than) operation.
406 405
407 Behavior similar to the "add" operation. 406 Behavior similar to the "add" operation.
408 The result of the call is always converted to a boolean. 407 The result of the call is always converted to a boolean.
409 </li> 408 </li>
410 409
411 <li><p><b>"le": </b> 410 <li><p><b>"le": </b>
412 the <tt>&lt;=</tt> (less equal) operation. 411 the <code>&lt;=</code> (less equal) operation.
413 412
414 Unlike other operations, 413 Unlike other operations,
415 The less-equal operation can use two different events. 414 The less-equal operation can use two different events.
416 First, Luan looks for the "<tt>__le</tt>" metamethod in both operands, 415 First, Luan looks for the "<code>__le</code>" metamethod in both operands,
417 like in the "lt" operation. 416 like in the "lt" operation.
418 If it cannot find such a metamethod, 417 If it cannot find such a metamethod,
419 then it will try the "<tt>__lt</tt>" event, 418 then it will try the "<code>__lt</code>" event,
420 assuming that <tt>a &lt;= b</tt> is equivalent to <tt>not (b &lt; a)</tt>. 419 assuming that <code>a &lt;= b</code> is equivalent to <code>not (b &lt; a)</code>.
421 As with the other comparison operators, 420 As with the other comparison operators,
422 the result is always a boolean. 421 the result is always a boolean.
423 </li> 422 </li>
424 423
425 <li><p><b>"index": </b> 424 <li><p><b>"index": </b>
426 The indexing access <tt>table[key]</tt>. 425 The indexing access <code>table[key]</code>.
427 426
428 This event happens 427 This event happens
429 when <tt>key</tt> is not present in <tt>table</tt>. 428 when <code>key</code> is not present in <code>table</code>.
430 The metamethod is looked up in <tt>table</tt>. 429 The metamethod is looked up in <code>table</code>.
431 430
432 431
433 <p> 432 <p>
434 Despite the name, 433 Despite the name,
435 the metamethod for this event can be any type. 434 the metamethod for this event can be any type.
436 If it is a function, 435 If it is a function,
437 it is called with <tt>table</tt> and <tt>key</tt> as arguments. 436 it is called with <code>table</code> and <code>key</code> as arguments.
438 Otherwise 437 Otherwise
439 the final result is the result of indexing this metamethod object with <tt>key</tt>. 438 the final result is the result of indexing this metamethod object with <code>key</code>.
440 (This indexing is regular, not raw, 439 (This indexing is regular, not raw,
441 and therefore can trigger another metamethod if the metamethod object is a table.) 440 and therefore can trigger another metamethod if the metamethod object is a table.)
442 </li> 441 </li>
443 442
444 <li><p><b>"new_index": </b> 443 <li><p><b>"new_index": </b>
445 The indexing assignment <tt>table[key] = value</tt>. 444 The indexing assignment <code>table[key] = value</code>.
446 445
447 Like the index event, 446 Like the index event,
448 this event happens when 447 this event happens when
449 when <tt>key</tt> is not present in <tt>table</tt>. 448 when <code>key</code> is not present in <code>table</code>.
450 The metamethod is looked up in <tt>table</tt>. 449 The metamethod is looked up in <code>table</code>.
451 450
452 451
453 <p> 452 <p>
454 Like with indexing, 453 Like with indexing,
455 the metamethod for this event can be either a function or a table. 454 the metamethod for this event can be either a function or a table.
456 If it is a function, 455 If it is a function,
457 it is called with <tt>table</tt>, <tt>key</tt>, and <tt>value</tt> as arguments. 456 it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments.
458 If it is a table, 457 If it is a table,
459 Luan does an indexing assignment to this table with the same key and value. 458 Luan does an indexing assignment to this table with the same key and value.
460 (This assignment is regular, not raw, 459 (This assignment is regular, not raw,
461 and therefore can trigger another metamethod.) 460 and therefore can trigger another metamethod.)
462 461
463 462
464 <p> 463 <p>
465 Whenever there is a "new_index" metamethod, 464 Whenever there is a "new_index" metamethod,
466 Luan does not perform the primitive assignment. 465 Luan does not perform the primitive assignment.
467 (If necessary, 466 (If necessary,
468 the metamethod itself can call <a href="#Luan.raw_set"><tt>raw_set</tt></a> 467 the metamethod itself can call <a href="#Luan.raw_set"><code>raw_set</code></a>
469 to do the assignment.) 468 to do the assignment.)
470 </li> 469 </li>
471 470
472 <li><p><b>"call": </b> 471 <li><p><b>"call": </b>
473 The call operation <tt>func(args)</tt>. 472 The call operation <code>func(args)</code>.
474 473
475 This event happens when Luan tries to call a table. 474 This event happens when Luan tries to call a table.
476 The metamethod is looked up in <tt>func</tt>. 475 The metamethod is looked up in <code>func</code>.
477 If present, 476 If present,
478 the metamethod is called with <tt>func</tt> as its first argument, 477 the metamethod is called with <code>func</code> as its first argument,
479 followed by the arguments of the original call (<tt>args</tt>). 478 followed by the arguments of the original call (<code>args</code>).
480 </li> 479 </li>
481 480
482 </ul> 481 </ul>
483 482
484 483
485 484
486 485
487 <h3 <%=heading_options%> ><a name="gc">Garbage Collection</a></h3> 486 <h3 heading><a name="gc">Garbage Collection</a></h3>
488 487
489 <p> 488 <p>
490 Luan uses Java's garbage collection. 489 Luan uses Java's garbage collection.
491 490
492 491
493 492
494 493
495 494
496 <h2 <%=heading_options%> ><a name="lang">The Language</a></h2> 495 <h2 heading><a name="lang">The Language</a></h2>
497 496
498 <p> 497 <p>
499 This section describes the lexis, the syntax, and the semantics of Luan. 498 This section describes the lexis, the syntax, and the semantics of Luan.
500 In other words, 499 In other words,
501 this section describes 500 this section describes
505 504
506 505
507 <p> 506 <p>
508 Language constructs will be explained using the usual extended BNF notation, 507 Language constructs will be explained using the usual extended BNF notation,
509 in which 508 in which
510 {<i>a</i>}&nbsp;means&nbsp;0 or more <i>a</i>'s, and 509 {<em>a</em>}&nbsp;means&nbsp;0 or more <em>a</em>'s, and
511 [<i>a</i>]&nbsp;means an optional <i>a</i>. 510 [<em>a</em>]&nbsp;means an optional <em>a</em>.
512 Non-terminals are shown like non-terminal, 511 Non-terminals are shown like non-terminal,
513 keywords are shown like <b>kword</b>, 512 keywords are shown like <b>kword</b>,
514 and other terminal symbols are shown like &lsquo;<b>=</b>&rsquo;. 513 and other terminal symbols are shown like &lsquo;<b>=</b>&rsquo;.
515 The complete syntax of Luan can be found in <a href="#9">&sect;9</a> 514 The complete syntax of Luan can be found in <a href="#9">&sect;9</a>
516 at the end of this manual. 515 at the end of this manual.
517 516
518 517
519 518
520 <h3 <%=heading_options%> ><a name="lex">Lexical Conventions</a></h3> 519 <h3 heading><a name="lex">Lexical Conventions</a></h3>
521 520
522 <p> 521 <p>
523 Luan ignores spaces and comments 522 Luan ignores spaces and comments
524 between lexical elements (tokens), 523 between lexical elements (tokens),
525 except as delimiters between names and keywords. 524 except as delimiters between names and keywords.
526 Luan generally considers the end of a line to be the end of a statement. This catches errors and encourages readability. The exception to this is in paranthesis ( <i>(...)</i>, <i>[...]</i>, and <i>{...}</i> ) where the end of line is treated as white space. 525 Luan generally considers the end of a line to be the end of a statement. This catches errors and encourages readability. The exception to this is in paranthesis ( <em>(...)</em>, <em>[...]</em>, and <em>{...}</em> ) where the end of line is treated as white space.
527 526
528 <p> 527 <p>
529 <i>Names</i> 528 <em>Names</em>
530 (also called <i>identifiers</i>) 529 (also called <em>identifiers</em>)
531 in Luan can be any string of letters, 530 in Luan can be any string of letters,
532 digits, and underscores, 531 digits, and underscores,
533 not beginning with a digit. 532 not beginning with a digit.
534 Identifiers are used to name variables, table fields, and labels. 533 Identifiers are used to name variables, table fields, and labels.
535 534
536 535
537 <p> 536 <p>
538 The following <i>keywords</i> are reserved 537 The following <em>keywords</em> are reserved
539 and cannot be used as names: 538 and cannot be used as names:
540 539
541 540
542 <p><tt><pre> 541 <pre>
543 and break do else elseif end 542 and break do else elseif end
544 false for function goto if in 543 false for function goto if in
545 local nil not or repeat return 544 local nil not or repeat return
546 then true until while 545 then true until while
547 </pre></tt></p> 546 </pre>
548 547
549 <p> 548 <p>
550 Luan is a case-sensitive language: 549 Luan is a case-sensitive language:
551 <tt>and</tt> is a reserved word, but <tt>And</tt> and <tt>AND</tt> 550 <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
552 are two different, valid names. 551 are two different, valid names.
553 552
554 553
555 <p> 554 <p>
556 The following strings denote other tokens: 555 The following strings denote other tokens:
557 556
558 <p><tt><pre> 557 <pre>
559 + - * / % ^ # 558 + - * / % ^ #
560 &amp; ~ | &lt;&lt; &gt;&gt; // 559 &amp; ~ | &lt;&lt; &gt;&gt; //
561 == ~= &lt;= &gt;= &lt; &gt; = 560 == ~= &lt;= &gt;= &lt; &gt; =
562 ( ) { } [ ] :: 561 ( ) { } [ ] ::
563 ; : , . .. ... 562 ; : , . .. ...
564 </pre></tt></p> 563 </pre>
565 564
566 <p> 565 <p>
567 <i>Literal strings</i> 566 <em>Literal strings</em>
568 can be delimited by matching single or double quotes, 567 can be delimited by matching single or double quotes,
569 and can contain the following C-like escape sequences: 568 and can contain the following C-like escape sequences:
570 '<tt>\a</tt>' (bell), 569 '<code>\a</code>' (bell),
571 '<tt>\b</tt>' (backspace), 570 '<code>\b</code>' (backspace),
572 '<tt>\f</tt>' (form feed), 571 '<code>\f</code>' (form feed),
573 '<tt>\n</tt>' (newline), 572 '<code>\n</code>' (newline),
574 '<tt>\r</tt>' (carriage return), 573 '<code>\r</code>' (carriage return),
575 '<tt>\t</tt>' (horizontal tab), 574 '<code>\t</code>' (horizontal tab),
576 '<tt>\v</tt>' (vertical tab), 575 '<code>\v</code>' (vertical tab),
577 '<tt>\\</tt>' (backslash), 576 '<code>\\</code>' (backslash),
578 '<tt>\"</tt>' (quotation mark [double quote]), 577 '<code>\"</code>' (quotation mark [double quote]),
579 and '<tt>\'</tt>' (apostrophe [single quote]). 578 and '<code>\'</code>' (apostrophe [single quote]).
580 A backslash followed by a real newline 579 A backslash followed by a real newline
581 results in a newline in the string. 580 results in a newline in the string.
582 The escape sequence '<tt>\z</tt>' skips the following span 581 The escape sequence '<code>\z</code>' skips the following span
583 of white-space characters, 582 of white-space characters,
584 including line breaks; 583 including line breaks;
585 it is particularly useful to break and indent a long literal string 584 it is particularly useful to break and indent a long literal string
586 into multiple lines without adding the newlines and spaces 585 into multiple lines without adding the newlines and spaces
587 into the string contents. 586 into the string contents.
588 587
589 588
590 <p> 589 <p>
591 Luan can specify any character in a literal string by its numerical value. 590 Luan can specify any character in a literal string by its numerical value.
592 This can be done 591 This can be done
593 with the escape sequence <tt>\x<i>XX</i></tt>, 592 with the escape sequence <code>\x<em>XX</em></code>,
594 where <i>XX</i> is a sequence of exactly two hexadecimal digits, 593 where <em>XX</em> is a sequence of exactly two hexadecimal digits,
595 or with the escape sequence <tt>\<i>ddd</i></tt>, 594 or with the escape sequence <code>\<em>ddd</em></code>,
596 where <i>ddd</i> is a sequence of up to three decimal digits. 595 where <em>ddd</em> is a sequence of up to three decimal digits.
597 (Note that if a decimal escape sequence is to be followed by a digit, 596 (Note that if a decimal escape sequence is to be followed by a digit,
598 it must be expressed using exactly three digits.) 597 it must be expressed using exactly three digits.)
599 598
600 599
601 <p> 600 <p>
602 Literal strings can also be defined using a long format 601 Literal strings can also be defined using a long format
603 enclosed by <i>long brackets</i>. 602 enclosed by <em>long brackets</em>.
604 We define an <i>opening long bracket of level <i>n</i></i> as an opening 603 We define an <em>opening long bracket of level <em>n</em></em> as an opening
605 square bracket followed by <i>n</i> equal signs followed by another 604 square bracket followed by <em>n</em> equal signs followed by another
606 opening square bracket. 605 opening square bracket.
607 So, an opening long bracket of level 0 is written as <tt>[[</tt>, 606 So, an opening long bracket of level 0 is written as <code>[[</code>,
608 an opening long bracket of level 1 is written as <tt>[=[</tt>, 607 an opening long bracket of level 1 is written as <code>[=[</code>,
609 and so on. 608 and so on.
610 A <i>closing long bracket</i> is defined similarly; 609 A <em>closing long bracket</em> is defined similarly;
611 for instance, 610 for instance,
612 a closing long bracket of level 4 is written as <tt>]====]</tt>. 611 a closing long bracket of level 4 is written as <code>]====]</code>.
613 A <i>long literal</i> starts with an opening long bracket of any level and 612 A <em>long literal</em> starts with an opening long bracket of any level and
614 ends at the first closing long bracket of the same level. 613 ends at the first closing long bracket of the same level.
615 It can contain any text except a closing bracket of the same level. 614 It can contain any text except a closing bracket of the same level.
616 Literals in this bracketed form can run for several lines, 615 Literals in this bracketed form can run for several lines,
617 do not interpret any escape sequences, 616 do not interpret any escape sequences,
618 and ignore long brackets of any other level. 617 and ignore long brackets of any other level.
638 when the opening long bracket is immediately followed by a newline, 637 when the opening long bracket is immediately followed by a newline,
639 the newline is not included in the string. 638 the newline is not included in the string.
640 As an example 639 As an example
641 the five literal strings below denote the same string: 640 the five literal strings below denote the same string:
642 641
643 <p><tt><pre> 642 <pre>
644 a = 'alo\n123"' 643 a = 'alo\n123"'
645 a = "alo\n123\"" 644 a = "alo\n123\""
646 a = '\97lo\10\04923"' 645 a = '\97lo\10\04923"'
647 a = [[alo 646 a = [[alo
648 123"]] 647 123"]]
649 a = [==[ 648 a = [==[
650 alo 649 alo
651 123"]==] 650 123"]==]
652 </pre></tt></p> 651 </pre>
653 652
654 <p> 653 <p>
655 A <i>numerical constant</i> (or <i>numeral</i>) 654 A <em>numerical constant</em> (or <em>numeral</em>)
656 can be written with an optional fractional part 655 can be written with an optional fractional part
657 and an optional decimal exponent, 656 and an optional decimal exponent,
658 marked by a letter '<tt>e</tt>' or '<tt>E</tt>'. 657 marked by a letter '<code>e</code>' or '<code>E</code>'.
659 Luan also accepts hexadecimal constants, 658 Luan also accepts hexadecimal constants,
660 which start with <tt>0x</tt> or <tt>0X</tt>. 659 which start with <code>0x</code> or <code>0X</code>.
661 Hexadecimal constants also accept an optional fractional part 660 Hexadecimal constants also accept an optional fractional part
662 plus an optional binary exponent, 661 plus an optional binary exponent,
663 marked by a letter '<tt>p</tt>' or '<tt>P</tt>'. 662 marked by a letter '<code>p</code>' or '<code>P</code>'.
664 A numeric constant with a fractional dot or an exponent 663 A numeric constant with a fractional dot or an exponent
665 denotes a float; 664 denotes a float;
666 otherwise it denotes an integer. 665 otherwise it denotes an integer.
667 Examples of valid integer constants are 666 Examples of valid integer constants are
668 667
669 <p><tt><pre> 668 <pre>
670 3 345 0xff 0xBEBADA 669 3 345 0xff 0xBEBADA
671 </pre></tt></p> 670 </pre>
672 671
673 <p> 672 <p>
674 Examples of valid float constants are 673 Examples of valid float constants are
675 674
676 <p><tt><pre> 675 <pre>
677 3.0 3.1416 314.16e-2 0.31416E1 34e1 676 3.0 3.1416 314.16e-2 0.31416E1 34e1
678 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 677 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1
679 </pre></tt></p> 678 </pre>
680 679
681 <p> 680 <p>
682 A <i>comment</i> starts with a double hyphen (<tt>--</tt>) 681 A <em>comment</em> starts with a double hyphen (<code>--</code>)
683 anywhere outside a string. 682 anywhere outside a string.
684 If the text immediately after <tt>--</tt> is not an opening long bracket, 683 If the text immediately after <code>--</code> is not an opening long bracket,
685 the comment is a <i>short comment</i>, 684 the comment is a <em>short comment</em>,
686 which runs until the end of the line. 685 which runs until the end of the line.
687 Otherwise, it is a <i>long comment</i>, 686 Otherwise, it is a <em>long comment</em>,
688 which runs until the corresponding closing long bracket. 687 which runs until the corresponding closing long bracket.
689 Long comments are frequently used to disable code temporarily. 688 Long comments are frequently used to disable code temporarily.
690 689
691 690
692 691
693 692
694 693
695 <h3 <%=heading_options%> ><a name="vars">Variables</a></h3> 694 <h3 heading><a name="vars">Variables</a></h3>
696 695
697 <p> 696 <p>
698 Variables are places that store values. 697 Variables are places that store values.
699 There are three kinds of variables in Luan: 698 There are three kinds of variables in Luan:
700 global variables, local variables, and table fields. 699 global variables, local variables, and table fields.
702 <p> 701 <p>
703 A single name can denote a global variable or a local variable 702 A single name can denote a global variable or a local variable
704 (or a function's formal parameter, 703 (or a function's formal parameter,
705 which is a particular kind of local variable): 704 which is a particular kind of local variable):
706 705
707 <p><tt><pre> 706 <pre>
708 var ::= Name 707 var ::= Name
709 </pre></tt></p> 708 </pre>
710 709
711 <p> 710 <p>
712 Name denotes identifiers, as defined in <a href="#lex">Lexical Conventions</a>. 711 Name denotes identifiers, as defined in <a href="#lex">Lexical Conventions</a>.
713 712
714 <p> 713 <p>
715 Local variables are <i>lexically scoped</i>: 714 Local variables are <em>lexically scoped</em>:
716 local variables can be freely accessed by functions 715 local variables can be freely accessed by functions
717 defined inside their scope (see <a href="#visibility">Visibility Rules</a>). 716 defined inside their scope (see <a href="#visibility">Visibility Rules</a>).
718 717
719 718
720 <p> 719 <p>
721 Before the first assignment to a variable, its value is <b>nil</b>. 720 Before the first assignment to a variable, its value is <b>nil</b>.
722 721
723 <p> 722 <p>
724 Square brackets are used to index a table: 723 Square brackets are used to index a table:
725 724
726 <p><tt><pre> 725 <pre>
727 var ::= prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; 726 var ::= prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo;
728 </pre></tt></p> 727 </pre>
729 728
730 <p> 729 <p>
731 The meaning of accesses to table fields can be changed via metatables. 730 The meaning of accesses to table fields can be changed via metatables.
732 An access to an indexed variable <tt>t[i]</tt> is equivalent to 731 An access to an indexed variable <code>t[i]</code> is equivalent to
733 a call <tt>gettable_event(t,i)</tt>. 732 a call <code>gettable_event(t,i)</code>.
734 (See <a href="#meta">Metatables and Metamethods</a> for a complete description of the 733 (See <a href="#meta">Metatables and Metamethods</a> for a complete description of the
735 <tt>gettable_event</tt> function. 734 <code>gettable_event</code> function.
736 This function is not defined or callable in Luan. 735 This function is not defined or callable in Luan.
737 We use it here only for explanatory purposes.) 736 We use it here only for explanatory purposes.)
738 737
739 738
740 <p> 739 <p>
741 The syntax <tt>var.Name</tt> is just syntactic sugar for 740 The syntax <code>var.Name</code> is just syntactic sugar for
742 <tt>var["Name"]</tt>: 741 <code>var["Name"]</code>:
743 742
744 <p><tt><pre> 743 <pre>
745 var ::= prefixexp &lsquo;<b>.</b>&rsquo; Name 744 var ::= prefixexp &lsquo;<b>.</b>&rsquo; Name
746 </pre></tt></p> 745 </pre>
747 746
748 <p> 747 <p>
749 Global variables are not available by default. To enable global variable, you must define <tt>_ENV</tt> as a local variable whose value is a table. If <tt>_ENV</tt> is not defined, then an unrecognized variable name will produce a compile error. If <tt>_ENV</tt> is defined then an access to an unrecognized variable name will be consider a global variable. So then an acces to global variable <tt>x</tt> 748 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>
750 is equivalent to <tt>_ENV.x</tt>. 749 is equivalent to <code>_ENV.x</code>.
751 Due to the way that chunks are compiled, 750 Due to the way that chunks are compiled,
752 <tt>_ENV</tt> is never a global name (see <a href="#env">Environments</a>). 751 <code>_ENV</code> is never a global name (see <a href="#env">Environments</a>).
753 752
754 753
755 754
756 755
757 756
758 <h3 <%=heading_options%> ><a name="stmts">Statements</a></h3> 757 <h3 heading><a name="stmts">Statements</a></h3>
759 758
760 <p> 759 <p>
761 Luan supports an almost conventional set of statements, 760 Luan supports an almost conventional set of statements,
762 similar to those in Pascal or C. 761 similar to those in Pascal or C.
763 This set includes 762 This set includes
764 assignments, control structures, function calls, 763 assignments, control structures, function calls,
765 and variable declarations. 764 and variable declarations.
766 765
767 766
768 767
769 <h4 <%=heading_options%> ><a name="blocks">Blocks</a></h4> 768 <h4 heading><a name="blocks">Blocks</a></h4>
770 769
771 <p> 770 <p>
772 A block is a list of statements, 771 A block is a list of statements,
773 which are executed sequentially: 772 which are executed sequentially:
774 773
775 <p><tt><pre> 774 <pre>
776 block ::= {stat} 775 block ::= {stat}
777 </pre></tt></p> 776 </pre>
778 777
779 <p> 778 <p>
780 Luan has <i>empty statements</i> 779 Luan has <em>empty statements</em>
781 that allow you to separate statements with semicolons, 780 that allow you to separate statements with semicolons,
782 start a block with a semicolon 781 start a block with a semicolon
783 or write two semicolons in sequence: 782 or write two semicolons in sequence:
784 783
785 <p><tt><pre> 784 <pre>
786 stat ::= &lsquo;<b>;</b>&rsquo; 785 stat ::= &lsquo;<b>;</b>&rsquo;
787 </pre></tt></p> 786 </pre>
788 787
789 <p> 788 <p>
790 A block can be explicitly delimited to produce a single statement: 789 A block can be explicitly delimited to produce a single statement:
791 790
792 <p><tt><pre> 791 <pre>
793 stat ::= <b>do</b> block <b>end</b> 792 stat ::= <b>do</b> block <b>end</b>
794 </pre></tt></p> 793 </pre>
795 794
796 <p> 795 <p>
797 Explicit blocks are useful 796 Explicit blocks are useful
798 to control the scope of variable declarations. 797 to control the scope of variable declarations.
799 Explicit blocks are also sometimes used to 798 Explicit blocks are also sometimes used to
802 801
803 802
804 803
805 804
806 805
807 <h4 <%=heading_options%> ><a name="chunks">Chunks</a></h4> 806 <h4 heading><a name="chunks">Chunks</a></h4>
808 807
809 <p> 808 <p>
810 The unit of compilation of Luan is called a <i>chunk</i>. 809 The unit of compilation of Luan is called a <em>chunk</em>.
811 Syntactically, 810 Syntactically,
812 a chunk is simply a block: 811 a chunk is simply a block:
813 812
814 <p><tt><pre> 813 <pre>
815 chunk ::= block 814 chunk ::= block
816 </pre></tt></p> 815 </pre>
817 816
818 <p> 817 <p>
819 Luan handles a chunk as the body of an anonymous function 818 Luan handles a chunk as the body of an anonymous function
820 with a variable number of arguments 819 with a variable number of arguments
821 (see <a href="#fn_def">Function Definitions</a>). 820 (see <a href="#fn_def">Function Definitions</a>).
824 823
825 824
826 <p> 825 <p>
827 A chunk can be stored in a file or in a string inside the host program. 826 A chunk can be stored in a file or in a string inside the host program.
828 To execute a chunk, 827 To execute a chunk,
829 Luan first <i>loads</i> it, 828 Luan first <em>loads</em> it,
830 compiling the chunk's code, 829 compiling the chunk's code,
831 and then Luan executes the compiled code. 830 and then Luan executes the compiled code.
832 831
833 832
834 833
835 834
836 835
837 <h4 <%=heading_options%> ><a name="assignment">Assignment</a></h4> 836 <h4 heading><a name="assignment">Assignment</a></h4>
838 837
839 <p> 838 <p>
840 Luan allows multiple assignments. 839 Luan allows multiple assignments.
841 Therefore, the syntax for assignment 840 Therefore, the syntax for assignment
842 defines a list of variables on the left side 841 defines a list of variables on the left side
843 and a list of expressions on the right side. 842 and a list of expressions on the right side.
844 The elements in both lists are separated by commas: 843 The elements in both lists are separated by commas:
845 844
846 <p><tt><pre> 845 <pre>
847 stat ::= varlist &lsquo;<b>=</b>&rsquo; explist 846 stat ::= varlist &lsquo;<b>=</b>&rsquo; explist
848 varlist ::= var {&lsquo;<b>,</b>&rsquo; var} 847 varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
849 explist ::= exp {&lsquo;<b>,</b>&rsquo; exp} 848 explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
850 </pre></tt></p> 849 </pre>
851 850
852 <p> 851 <p>
853 Expressions are discussed in <a href="#expressions">Expressions</a>. 852 Expressions are discussed in <a href="#expressions">Expressions</a>.
854 853
855 854
856 <p> 855 <p>
857 Before the assignment, 856 Before the assignment,
858 the list of values is <i>adjusted</i> to the length of 857 the list of values is <em>adjusted</em> to the length of
859 the list of variables. 858 the list of variables.
860 If there are more values than needed, 859 If there are more values than needed,
861 the excess values are thrown away. 860 the excess values are thrown away.
862 If there are fewer values than needed, 861 If there are fewer values than needed,
863 the list is extended with as many <b>nil</b>'s as needed. 862 the list is extended with as many <b>nil</b>'s as needed.
870 <p> 869 <p>
871 The assignment statement first evaluates all its expressions 870 The assignment statement first evaluates all its expressions
872 and only then the assignments are performed. 871 and only then the assignments are performed.
873 Thus the code 872 Thus the code
874 873
875 <p><tt><pre> 874 <pre>
876 i = 3 875 i = 3
877 i, a[i] = i+1, 20 876 i, a[i] = i+1, 20
878 </pre></tt></p> 877 </pre>
879 878
880 <p> 879 <p>
881 sets <tt>a[3]</tt> to 20, without affecting <tt>a[4]</tt> 880 sets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
882 because the <tt>i</tt> in <tt>a[i]</tt> is evaluated (to 3) 881 because the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
883 before it is assigned&nbsp;4. 882 before it is assigned&nbsp;4.
884 Similarly, the line 883 Similarly, the line
885 884
886 <p><tt><pre> 885 <pre>
887 x, y = y, x 886 x, y = y, x
888 </pre></tt></p> 887 </pre>
889 888
890 <p> 889 <p>
891 exchanges the values of <tt>x</tt> and <tt>y</tt>, 890 exchanges the values of <code>x</code> and <code>y</code>,
892 and 891 and
893 892
894 <p><tt><pre> 893 <pre>
895 x, y, z = y, z, x 894 x, y, z = y, z, x
896 </pre></tt></p> 895 </pre>
897 896
898 <p> 897 <p>
899 cyclically permutes the values of <tt>x</tt>, <tt>y</tt>, and <tt>z</tt>. 898 cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>.
900 899
901 900
902 <p> 901 <p>
903 The meaning of assignments to global variables 902 The meaning of assignments to global variables
904 and table fields can be changed via metatables. 903 and table fields can be changed via metatables.
905 An assignment to an indexed variable <tt>t[i] = val</tt> is equivalent to 904 An assignment to an indexed variable <code>t[i] = val</code> is equivalent to
906 <tt>settable_event(t,i,val)</tt>. 905 <code>settable_event(t,i,val)</code>.
907 (See <a href="#meta">Metatables and Metamethods</a> for a complete description of the 906 (See <a href="#meta">Metatables and Metamethods</a> for a complete description of the
908 <tt>settable_event</tt> function. 907 <code>settable_event</code> function.
909 This function is not defined or callable in Luan. 908 This function is not defined or callable in Luan.
910 We use it here only for explanatory purposes.) 909 We use it here only for explanatory purposes.)
911 910
912 911
913 <p> 912 <p>
914 An assignment to a global name <tt>x = val</tt> 913 An assignment to a global name <code>x = val</code>
915 is equivalent to the assignment 914 is equivalent to the assignment
916 <tt>_ENV.x = val</tt> (see <a href="#env">Environments</a>). 915 <code>_ENV.x = val</code> (see <a href="#env">Environments</a>).
917 Global names are only available when <tt>_ENV</tt> is defined. 916 Global names are only available when <code>_ENV</code> is defined.
918 917
919 918
920 919
921 <h4 <%=heading_options%> ><a name="control">Control Structures</a></h4> 920 <h4 heading><a name="control">Control Structures</a></h4>
922 921
923 <p> 922 <p>
924 The control structures 923 The control structures
925 <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 924 <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
926 familiar syntax: 925 familiar syntax:
927 926
928 <p><tt><pre> 927 <pre>
929 stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 928 stat ::= <b>while</b> exp <b>do</b> block <b>end</b>
930 stat ::= <b>repeat</b> block <b>until</b> exp 929 stat ::= <b>repeat</b> block <b>until</b> exp
931 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> 930 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b>
932 </pre></tt></p> 931 </pre>
933 932
934 <p> 933 <p>
935 Luan also has a <b>for</b> statement (see <a href="#for">For Statement</a>). 934 Luan also has a <b>for</b> statement (see <a href="#for">For Statement</a>).
936 935
937 936
954 The <b>break</b> statement terminates the execution of a 953 The <b>break</b> statement terminates the execution of a
955 <b>while</b>, <b>repeat</b>, or <b>for</b> loop, 954 <b>while</b>, <b>repeat</b>, or <b>for</b> loop,
956 skipping to the next statement after the loop: 955 skipping to the next statement after the loop:
957 956
958 957
959 <p><tt><pre> 958 <pre>
960 stat ::= <b>break</b> 959 stat ::= <b>break</b>
961 </pre></tt></p> 960 </pre>
962 961
963 <p> 962 <p>
964 A <b>break</b> ends the innermost enclosing loop. 963 A <b>break</b> ends the innermost enclosing loop.
965 964
966 965
970 (which is an anonymous function). 969 (which is an anonymous function).
971 970
972 Functions can return more than one value, 971 Functions can return more than one value,
973 so the syntax for the <b>return</b> statement is 972 so the syntax for the <b>return</b> statement is
974 973
975 <p><tt><pre> 974 <pre>
976 stat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;] 975 stat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
977 </pre></tt></p> 976 </pre>
978 977
979 978
980 979
981 980
982 <h4 <%=heading_options%> ><a name="for">For Statement</a></h4> 981 <h4 heading><a name="for">For Statement</a></h4>
983 982
984 <p> 983 <p>
985 The <b>for</b> statement works over functions, 984 The <b>for</b> statement works over functions,
986 called <i>iterators</i>. 985 called <em>iterators</em>.
987 On each iteration, the iterator function is called to produce a new value, 986 On each iteration, the iterator function is called to produce a new value,
988 stopping when this new value is <b>nil</b>. 987 stopping when this new value is <b>nil</b>.
989 The <b>for</b> loop has the following syntax: 988 The <b>for</b> loop has the following syntax:
990 989
991 <p><tt><pre> 990 <pre>
992 stat ::= <b>for</b> namelist <b>in</b> exp <b>do</b> block <b>end</b> 991 stat ::= <b>for</b> namelist <b>in</b> exp <b>do</b> block <b>end</b>
993 namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name} 992 namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
994 </pre></tt></p> 993 </pre>
995 994
996 <p> 995 <p>
997 A <b>for</b> statement like 996 A <b>for</b> statement like
998 997
999 <p><tt><pre> 998 <pre>
1000 for <i>var_1</i>, &middot;&middot;&middot;, <i>var_n</i> in <i>exp</i> do <i>block</i> end 999 for <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> in <em>exp</em> do <em>block</em> end
1001 </pre></tt></p> 1000 </pre>
1002 1001
1003 <p> 1002 <p>
1004 is equivalent to the code: 1003 is equivalent to the code:
1005 1004
1006 <p><tt><pre> 1005 <pre>
1007 do 1006 do
1008 local <i>f</i> = <i>exp</i> 1007 local <em>f</em> = <em>exp</em>
1009 while true do 1008 while true do
1010 local <i>var_1</i>, &middot;&middot;&middot;, <i>var_n</i> = <i>f</i>() 1009 local <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> = <em>f</em>()
1011 if <i>var_1</i> == nil then break end 1010 if <em>var_1</em> == nil then break end
1012 <i>block</i> 1011 <em>block</em>
1013 end 1012 end
1014 end 1013 end
1015 </pre></tt></p> 1014 </pre>
1016 1015
1017 <p> 1016 <p>
1018 Note the following: 1017 Note the following:
1019 1018
1020 <ul> 1019 <ul>
1021 1020
1022 <li> 1021 <li>
1023 <tt><i>exp</i></tt> is evaluated only once. 1022 <code><em>exp</em></code> is evaluated only once.
1024 Its result is an <i>iterator</i> function. 1023 Its result is an <em>iterator</em> function.
1025 </li> 1024 </li>
1026 1025
1027 <li> 1026 <li>
1028 <tt><i>f</i></tt> is an invisible variable. 1027 <code><em>f</em></code> is an invisible variable.
1029 The name is here for explanatory purposes only. 1028 The name is here for explanatory purposes only.
1030 </li> 1029 </li>
1031 1030
1032 <li> 1031 <li>
1033 You can use <b>break</b> to exit a <b>for</b> loop. 1032 You can use <b>break</b> to exit a <b>for</b> loop.
1034 </li> 1033 </li>
1035 1034
1036 <li> 1035 <li>
1037 The loop variables <tt><i>var_i</i></tt> are local to the loop; 1036 The loop variables <code><em>var_i</em></code> are local to the loop;
1038 you cannot use their values after the <b>for</b> ends. 1037 you cannot use their values after the <b>for</b> ends.
1039 If you need these values, 1038 If you need these values,
1040 then assign them to other variables before breaking or exiting the loop. 1039 then assign them to other variables before breaking or exiting the loop.
1041 </li> 1040 </li>
1042 1041
1043 </ul> 1042 </ul>
1044 1043
1045 1044
1046 1045
1047 1046
1048 <h4 <%=heading_options%> ><a name="fn_stmt">Function Calls as Statements</a></h4> 1047 <h4 heading><a name="fn_stmt">Function Calls as Statements</a></h4>
1049 1048
1050 <p> 1049 <p>
1051 To allow possible side-effects, 1050 To allow possible side-effects,
1052 function calls can be executed as statements: 1051 function calls can be executed as statements:
1053 1052
1054 <p><tt><pre> 1053 <pre>
1055 stat ::= functioncall 1054 stat ::= functioncall
1056 </pre></tt></p> 1055 </pre>
1057 1056
1058 <p> 1057 <p>
1059 In this case, all returned values are thrown away. 1058 In this case, all returned values are thrown away.
1060 Function calls are explained in <a href="#fn_calls">Function Calls</a>. 1059 Function calls are explained in <a href="#fn_calls">Function Calls</a>.
1061 1060
1062 1061
1063 1062
1064 <h4 <%=heading_options%> ><a name="local_stmt">Local Declarations</a></h4> 1063 <h4 heading><a name="local_stmt">Local Declarations</a></h4>
1065 1064
1066 <p> 1065 <p>
1067 Local variables can be declared anywhere inside a block. 1066 Local variables can be declared anywhere inside a block.
1068 The declaration can include an initial assignment: 1067 The declaration can include an initial assignment:
1069 1068
1070 <p><tt><pre> 1069 <pre>
1071 stat ::= <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist] 1070 stat ::= <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist]
1072 </pre></tt></p> 1071 </pre>
1073 1072
1074 <p> 1073 <p>
1075 If present, an initial assignment has the same semantics 1074 If present, an initial assignment has the same semantics
1076 of a multiple assignment (see <a href="#assignment">Assignment</a>). 1075 of a multiple assignment (see <a href="#assignment">Assignment</a>).
1077 Otherwise, all variables are initialized with <b>nil</b>. 1076 Otherwise, all variables are initialized with <b>nil</b>.
1084 1083
1085 <p> 1084 <p>
1086 The visibility rules for local variables are explained in <a href="#visibility">Visibility Rules</a>. 1085 The visibility rules for local variables are explained in <a href="#visibility">Visibility Rules</a>.
1087 1086
1088 1087
1089 <h4 <%=heading_options%> ><a name="template_stmt">Template Statements</a></h4> 1088 <h4 heading><a name="template_stmt">Template Statements</a></h4>
1090 1089
1091 <p>Template statements are based on <a href="#template_expr">template exressions</a> and provide the full equivalent of <a href="http://en.wikipedia.org/wiki/JavaServer_Pages">JSP</a> but in a general way. Template statements write the equivalent template exression to standard output. For example:</p> 1090 <p>Template statements are based on <a href="#template_expr">template exressions</a> and provide the full equivalent of <a href="http://en.wikipedia.org/wiki/JavaServer_Pages">JSP</a> but in a general way. Template statements write the equivalent template exression to standard output. For example:</p>
1092 1091
1093 <p><tt><pre><%=Html.encode[[ 1092 <pre><%=Html.encode[[
1094 local name = "Bob" 1093 local name = "Bob"
1095 %> 1094 %>
1096 Hello <%= name %>! 1095 Hello <%= name %>!
1097 Bye <%= name %>. 1096 Bye <%= name %>.
1098 <% 1097 <%
1099 ]]%></pre></tt></p> 1098 ]]%></pre>
1100 1099
1101 <p>is equivalent to the code:</p> 1100 <p>is equivalent to the code:</p>
1102 1101
1103 <p><tt><pre><%=Html.encode[[ 1102 <pre><%=Html.encode[[
1104 local name = "Bob" 1103 local name = "Bob"
1105 require("luan:Io").stdout.write( %> 1104 require("luan:Io").stdout.write( %>
1106 Hello <%= name %>! 1105 Hello <%= name %>!
1107 Bye <%= name %>. 1106 Bye <%= name %>.
1108 <% ) 1107 <% )
1109 ]]%></pre></tt></p> 1108 ]]%></pre>
1110 1109
1111 1110
1112 1111
1113 <h3 <%=heading_options%> ><a name="expressions">Expressions</a></h3> 1112 <h3 heading><a name="expressions">Expressions</a></h3>
1114 1113
1115 <p> 1114 <p>
1116 The basic expressions in Luan are the following: 1115 The basic expressions in Luan are the following:
1117 1116
1118 <p><tt><pre> 1117 <pre>
1119 exp ::= prefixexp 1118 exp ::= prefixexp
1120 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 1119 exp ::= <b>nil</b> | <b>false</b> | <b>true</b>
1121 exp ::= Numeral 1120 exp ::= Numeral
1122 exp ::= LiteralString 1121 exp ::= LiteralString
1123 exp ::= functiondef 1122 exp ::= functiondef
1124 exp ::= tableconstructor 1123 exp ::= tableconstructor
1125 exp ::= &lsquo;<b>...</b>&rsquo; 1124 exp ::= &lsquo;<b>...</b>&rsquo;
1126 exp ::= exp binop exp 1125 exp ::= exp binop exp
1127 exp ::= unop exp 1126 exp ::= unop exp
1128 prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo; 1127 prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
1129 </pre></tt></p> 1128 </pre>
1130 1129
1131 <p> 1130 <p>
1132 Numerals and literal strings are explained in <a href="#lex">Lexical Conventions</a>; 1131 Numerals and literal strings are explained in <a href="#lex">Lexical Conventions</a>;
1133 variables are explained in <a href="#vars">Variables</a>; 1132 variables are explained in <a href="#vars">Variables</a>;
1134 function definitions are explained in <a href="#fn_def">Function Definitions</a>; 1133 function definitions are explained in <a href="#fn_def">Function Definitions</a>;
1135 function calls are explained in <a href="#fn_calls">Function Calls</a>; 1134 function calls are explained in <a href="#fn_calls">Function Calls</a>;
1136 table constructors are explained in <a href="#constructors">Table Constructors</a>. 1135 table constructors are explained in <a href="#constructors">Table Constructors</a>.
1137 Vararg expressions, 1136 Vararg expressions,
1138 denoted by three dots ('<tt>...</tt>'), can only be used when 1137 denoted by three dots ('<code>...</code>'), can only be used when
1139 directly inside a vararg function; 1138 directly inside a vararg function;
1140 they are explained in <a href="#fn_def">Function Definitions</a>. 1139 they are explained in <a href="#fn_def">Function Definitions</a>.
1141 1140
1142 1141
1143 <p> 1142 <p>
1165 1164
1166 1165
1167 <p> 1166 <p>
1168 Here are some examples: 1167 Here are some examples:
1169 1168
1170 <p><tt><pre> 1169 <pre>
1171 f() -- adjusted to 0 results 1170 f() -- adjusted to 0 results
1172 g(f(), x) -- f() is adjusted to 1 result 1171 g(f(), x) -- f() is adjusted to 1 result
1173 g(x, f()) -- g gets x plus all results from f() 1172 g(x, f()) -- g gets x plus all results from f()
1174 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) 1173 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil)
1175 a,b = ... -- a gets the first vararg parameter, b gets 1174 a,b = ... -- a gets the first vararg parameter, b gets
1182 return ... -- returns all received vararg parameters 1181 return ... -- returns all received vararg parameters
1183 return x,y,f() -- returns x, y, and all results from f() 1182 return x,y,f() -- returns x, y, and all results from f()
1184 {f()} -- creates a list with all results from f() 1183 {f()} -- creates a list with all results from f()
1185 {...} -- creates a list with all vararg parameters 1184 {...} -- creates a list with all vararg parameters
1186 {f(), nil} -- f() is adjusted to 1 result 1185 {f(), nil} -- f() is adjusted to 1 result
1187 </pre></tt></p> 1186 </pre>
1188 1187
1189 <p> 1188 <p>
1190 Any expression enclosed in parentheses always results in only one value. 1189 Any expression enclosed in parentheses always results in only one value.
1191 Thus, 1190 Thus,
1192 <tt>(f(x,y,z))</tt> is always a single value, 1191 <code>(f(x,y,z))</code> is always a single value,
1193 even if <tt>f</tt> returns several values. 1192 even if <code>f</code> returns several values.
1194 (The value of <tt>(f(x,y,z))</tt> is the first value returned by <tt>f</tt> 1193 (The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code>
1195 or <b>nil</b> if <tt>f</tt> does not return any values.) 1194 or <b>nil</b> if <code>f</code> does not return any values.)
1196 1195
1197 1196
1198 1197
1199 <h4 <%=heading_options%> ><a name="arithmetic">Arithmetic Operators</a></h4> 1198 <h4 heading><a name="arithmetic">Arithmetic Operators</a></h4>
1200 1199
1201 <p> 1200 <p>
1202 Luan supports the following arithmetic operators: 1201 Luan supports the following arithmetic operators:
1203 1202
1204 <ul> 1203 <ul>
1205 <li><b><tt>+</tt>: </b>addition</li> 1204 <li><b><code>+</code>: </b>addition</li>
1206 <li><b><tt>-</tt>: </b>subtraction</li> 1205 <li><b><code>-</code>: </b>subtraction</li>
1207 <li><b><tt>*</tt>: </b>multiplication</li> 1206 <li><b><code>*</code>: </b>multiplication</li>
1208 <li><b><tt>/</tt>: </b>division</li> 1207 <li><b><code>/</code>: </b>division</li>
1209 <li><b><tt>%</tt>: </b>modulo</li> 1208 <li><b><code>%</code>: </b>modulo</li>
1210 <li><b><tt>^</tt>: </b>exponentiation</li> 1209 <li><b><code>^</code>: </b>exponentiation</li>
1211 <li><b><tt>-</tt>: </b>unary minus</li> 1210 <li><b><code>-</code>: </b>unary minus</li>
1212 </ul> 1211 </ul>
1213 1212
1214 <p> 1213 <p>
1215 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. 1214 Addition, subtraction, multiplication, division, and unary minus are the same as these operators in Java. Exponentiation uses Java's <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Math.html#pow(double,%20double)">Math.pow</a> function.
1216 1215
1219 that rounds the quotient towards minus infinite (floor division). 1218 that rounds the quotient towards minus infinite (floor division).
1220 (The Java modulo operator is not used.) 1219 (The Java modulo operator is not used.)
1221 1220
1222 1221
1223 1222
1224 <h4 <%=heading_options%> ><a name="conversions">Coercions and Conversions</a></h4> 1223 <h4 heading><a name="conversions">Coercions and Conversions</a></h4>
1225 1224
1226 <p> 1225 <p>
1227 Luan generally avoids automatic conversions. 1226 Luan generally avoids automatic conversions.
1228 String concatenation automatically converts all of its arguments to strings. 1227 String concatenation automatically converts all of its arguments to strings.
1229 1228
1231 Luan provides library functions for explicit type conversions. 1230 Luan provides library functions for explicit type conversions.
1232 1231
1233 1232
1234 1233
1235 1234
1236 <h4 <%=heading_options%> ><a name="relational">Relational Operators</a></h4> 1235 <h4 heading><a name="relational">Relational Operators</a></h4>
1237 1236
1238 <p> 1237 <p>
1239 Luan supports the following relational operators: 1238 Luan supports the following relational operators:
1240 1239
1241 <ul> 1240 <ul>
1242 <li><b><tt>==</tt>: </b>equality</li> 1241 <li><b><code>==</code>: </b>equality</li>
1243 <li><b><tt>~=</tt>: </b>inequality</li> 1242 <li><b><code>~=</code>: </b>inequality</li>
1244 <li><b><tt>&lt;</tt>: </b>less than</li> 1243 <li><b><code>&lt;</code>: </b>less than</li>
1245 <li><b><tt>&gt;</tt>: </b>greater than</li> 1244 <li><b><code>&gt;</code>: </b>greater than</li>
1246 <li><b><tt>&lt;=</tt>: </b>less or equal</li> 1245 <li><b><code>&lt;=</code>: </b>less or equal</li>
1247 <li><b><tt>&gt;=</tt>: </b>greater or equal</li> 1246 <li><b><code>&gt;=</code>: </b>greater or equal</li>
1248 </ul><p> 1247 </ul><p>
1249 These operators always result in <b>false</b> or <b>true</b>. 1248 These operators always result in <b>false</b> or <b>true</b>.
1250 1249
1251 1250
1252 <p> 1251 <p>
1253 Equality (<tt>==</tt>) first compares the type of its operands. 1252 Equality (<code>==</code>) first compares the type of its operands.
1254 If the types are different, then the result is <b>false</b>. 1253 If the types are different, then the result is <b>false</b>.
1255 Otherwise, the values of the operands are compared. 1254 Otherwise, the values of the operands are compared.
1256 Strings, numbers, and binary values are compared in the obvious way (by value). 1255 Strings, numbers, and binary values are compared in the obvious way (by value).
1257 1256
1258 <p> 1257 <p>
1266 <p> 1265 <p>
1267 You can change the way that Luan compares tables 1266 You can change the way that Luan compares tables
1268 by using the "eq" metamethod (see <a href="#meta">Metatables and Metamethods</a>). 1267 by using the "eq" metamethod (see <a href="#meta">Metatables and Metamethods</a>).
1269 1268
1270 <p> 1269 <p>
1271 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)"><tt>equals</tt></a> method. 1270 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.
1272 1271
1273 <p> 1272 <p>
1274 Equality comparisons do not convert strings to numbers 1273 Equality comparisons do not convert strings to numbers
1275 or vice versa. 1274 or vice versa.
1276 Thus, <tt>"0"==0</tt> evaluates to <b>false</b>, 1275 Thus, <code>"0"==0</code> evaluates to <b>false</b>,
1277 and <tt>t[0]</tt> and <tt>t["0"]</tt> denote different 1276 and <code>t[0]</code> and <code>t["0"]</code> denote different
1278 entries in a table. 1277 entries in a table.
1279 1278
1280 1279
1281 <p> 1280 <p>
1282 The operator <tt>~=</tt> is exactly the negation of equality (<tt>==</tt>). 1281 The operator <code>~=</code> is exactly the negation of equality (<code>==</code>).
1283 1282
1284 1283
1285 <p> 1284 <p>
1286 The order operators work as follows. 1285 The order operators work as follows.
1287 1286
1290 the usual rule for binary operations. 1289 the usual rule for binary operations.
1291 Otherwise, if both arguments are strings, 1290 Otherwise, if both arguments are strings,
1292 then their values are compared according to the current locale. 1291 then their values are compared according to the current locale.
1293 Otherwise, Luan tries to call the "lt" or the "le" 1292 Otherwise, Luan tries to call the "lt" or the "le"
1294 metamethod (see <a href="#meta">Metatables and Metamethods</a>). 1293 metamethod (see <a href="#meta">Metatables and Metamethods</a>).
1295 A comparison <tt>a &gt; b</tt> is translated to <tt>b &lt; a</tt> 1294 A comparison <code>a &gt; b</code> is translated to <code>b &lt; a</code>
1296 and <tt>a &gt;= b</tt> is translated to <tt>b &lt;= a</tt>. 1295 and <code>a &gt;= b</code> is translated to <code>b &lt;= a</code>.
1297 1296
1298 1297
1299 1298
1300 1299
1301 1300
1302 <h4 <%=heading_options%> ><a name="logical_ops">Logical Operators</a></h4> 1301 <h4 heading><a name="logical_ops">Logical Operators</a></h4>
1303 1302
1304 <p> 1303 <p>
1305 The logical operators in Luan are 1304 The logical operators in Luan are
1306 <b>and</b>, <b>or</b>, and <b>not</b>. 1305 <b>and</b>, <b>or</b>, and <b>not</b>.
1307 The <b>and</b> and <b>or</b> operators consider both <b>false</b> and <b>nil</b> as false 1306 The <b>and</b> and <b>or</b> operators consider both <b>false</b> and <b>nil</b> as false
1320 Both <b>and</b> and <b>or</b> use short-circuit evaluation; 1319 Both <b>and</b> and <b>or</b> use short-circuit evaluation;
1321 that is, 1320 that is,
1322 the second operand is evaluated only if necessary. 1321 the second operand is evaluated only if necessary.
1323 Here are some examples: 1322 Here are some examples:
1324 1323
1325 <p><tt><pre> 1324 <pre>
1326 10 or 20 --&gt; 10 1325 10 or 20 --&gt; 10
1327 10 or error() --&gt; 10 1326 10 or error() --&gt; 10
1328 nil or "a" --&gt; "a" 1327 nil or "a" --&gt; "a"
1329 nil and 10 --&gt; nil 1328 nil and 10 --&gt; nil
1330 false and error() --&gt; false 1329 false and error() --&gt; false
1331 false and nil --&gt; false 1330 false and nil --&gt; false
1332 false or nil --&gt; nil 1331 false or nil --&gt; nil
1333 10 and 20 --&gt; 20 1332 10 and 20 --&gt; 20
1334 </pre></tt></p> 1333 </pre>
1335 1334
1336 <p> 1335 <p>
1337 (In this manual, 1336 (In this manual,
1338 <tt>--&gt;</tt> indicates the result of the preceding expression.) 1337 <code>--&gt;</code> indicates the result of the preceding expression.)
1339 1338
1340 1339
1341 1340
1342 <h4 <%=heading_options%> ><a name="concatenation">Concatenation</a></h4> 1341 <h4 heading><a name="concatenation">Concatenation</a></h4>
1343 1342
1344 <p> 1343 <p>
1345 The string concatenation operator in Luan is 1344 The string concatenation operator in Luan is
1346 denoted by two dots ('<tt>..</tt>'). 1345 denoted by two dots ('<code>..</code>').
1347 All operands are converted to strings. 1346 All operands are converted to strings.
1348 1347
1349 1348
1350 1349
1351 <h4 <%=heading_options%> ><a name="length">The Length Operator</a></h4> 1350 <h4 heading><a name="length">The Length Operator</a></h4>
1352 1351
1353 <p> 1352 <p>
1354 The length operator is denoted by the unary prefix operator <tt>#</tt>. 1353 The length operator is denoted by the unary prefix operator <code>#</code>.
1355 The length of a string is its number of characters. 1354 The length of a string is its number of characters.
1356 The length of a binary is its number of bytes. 1355 The length of a binary is its number of bytes.
1357 1356
1358 1357
1359 <p> 1358 <p>
1360 A program can modify the behavior of the length operator for 1359 A program can modify the behavior of the length operator for
1361 any table through the <tt>__len</tt> metamethod (see <a href="#meta">Metatables and Metamethods</a>). 1360 any table through the <code>__len</code> metamethod (see <a href="#meta">Metatables and Metamethods</a>).
1362 1361
1363 1362
1364 <p> 1363 <p>
1365 Unless a <tt>__len</tt> metamethod is given, 1364 Unless a <code>__len</code> metamethod is given,
1366 the length of a table <tt>t</tt> is defined 1365 the length of a table <code>t</code> is defined
1367 as the number of elements in <em>sequence</em>, 1366 as the number of elements in <em>sequence</em>,
1368 that is, 1367 that is,
1369 the size of the set of its positive numeric keys is equal to <em>{1..n}</em> 1368 the size of the set of its positive numeric keys is equal to <em>{1..n}</em>
1370 for some non-negative integer <em>n</em>. 1369 for some non-negative integer <em>n</em>.
1371 In that case, <em>n</em> is its length. 1370 In that case, <em>n</em> is its length.
1372 Note that a table like 1371 Note that a table like
1373 1372
1374 <p><tt><pre> 1373 <pre>
1375 {10, 20, nil, 40} 1374 {10, 20, nil, 40}
1376 </pre></tt></p> 1375 </pre>
1377 1376
1378 <p> 1377 <p>
1379 has a length of <tt>2</tt>, because that is the last key in sequence. 1378 has a length of <code>2</code>, because that is the last key in sequence.
1380 1379
1381 1380
1382 1381
1383 1382
1384 1383
1385 <h4 <%=heading_options%> ><a name="precedence">Precedence</a></h4> 1384 <h4 heading><a name="precedence">Precedence</a></h4>
1386 1385
1387 <p> 1386 <p>
1388 Operator precedence in Luan follows the table below, 1387 Operator precedence in Luan follows the table below,
1389 from lower to higher priority: 1388 from lower to higher priority:
1390 1389
1391 <p><tt><pre> 1390 <pre>
1392 or 1391 or
1393 and 1392 and
1394 &lt; &gt; &lt;= &gt;= ~= == 1393 &lt; &gt; &lt;= &gt;= ~= ==
1395 .. 1394 ..
1396 + - 1395 + -
1397 * / % 1396 * / %
1398 unary operators (not # -) 1397 unary operators (not # -)
1399 ^ 1398 ^
1400 </pre></tt></p> 1399 </pre>
1401 1400
1402 <p> 1401 <p>
1403 As usual, 1402 As usual,
1404 you can use parentheses to change the precedences of an expression. 1403 you can use parentheses to change the precedences of an expression.
1405 The concatenation ('<tt>..</tt>') and exponentiation ('<tt>^</tt>') 1404 The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>')
1406 operators are right associative. 1405 operators are right associative.
1407 All other binary operators are left associative. 1406 All other binary operators are left associative.
1408 1407
1409 1408
1410 1409
1411 1410
1412 1411
1413 <h4 <%=heading_options%> ><a name="constructors">Table Constructors</a></h4> 1412 <h4 heading><a name="constructors">Table Constructors</a></h4>
1414 1413
1415 <p> 1414 <p>
1416 Table constructors are expressions that create tables. 1415 Table constructors are expressions that create tables.
1417 Every time a constructor is evaluated, a new table is created. 1416 Every time a constructor is evaluated, a new table is created.
1418 A constructor can be used to create an empty table 1417 A constructor can be used to create an empty table
1419 or to create a table and initialize some of its fields. 1418 or to create a table and initialize some of its fields.
1420 The general syntax for constructors is 1419 The general syntax for constructors is
1421 1420
1422 <p><tt><pre> 1421 <pre>
1423 tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo; 1422 tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
1424 fieldlist ::= field {fieldsep field} [fieldsep] 1423 fieldlist ::= field {fieldsep field} [fieldsep]
1425 field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp 1424 field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
1426 fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo; 1425 fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
1427 </pre></tt></p> 1426 </pre>
1428 1427
1429 <p> 1428 <p>
1430 Each field of the form <tt>[exp1] = exp2</tt> adds to the new table an entry 1429 Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry
1431 with key <tt>exp1</tt> and value <tt>exp2</tt>. 1430 with key <code>exp1</code> and value <code>exp2</code>.
1432 A field of the form <tt>name = exp</tt> is equivalent to 1431 A field of the form <code>name = exp</code> is equivalent to
1433 <tt>["name"] = exp</tt>. 1432 <code>["name"] = exp</code>.
1434 Finally, fields of the form <tt>exp</tt> are equivalent to 1433 Finally, fields of the form <code>exp</code> are equivalent to
1435 <tt>[i] = exp</tt>, where <tt>i</tt> are consecutive integers 1434 <code>[i] = exp</code>, where <code>i</code> are consecutive integers
1436 starting with 1. 1435 starting with 1.
1437 Fields in the other formats do not affect this counting. 1436 Fields in the other formats do not affect this counting.
1438 For example, 1437 For example,
1439 1438
1440 <p><tt><pre> 1439 <pre>
1441 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 1440 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
1442 </pre></tt></p> 1441 </pre>
1443 1442
1444 <p> 1443 <p>
1445 is equivalent to 1444 is equivalent to
1446 1445
1447 <p><tt><pre> 1446 <pre>
1448 do 1447 do
1449 local t = {} 1448 local t = {}
1450 t[f(1)] = g 1449 t[f(1)] = g
1451 t[1] = "x" -- 1st exp 1450 t[1] = "x" -- 1st exp
1452 t[2] = "y" -- 2nd exp 1451 t[2] = "y" -- 2nd exp
1454 t[3] = f(x) -- 3rd exp 1453 t[3] = f(x) -- 3rd exp
1455 t[30] = 23 1454 t[30] = 23
1456 t[4] = 45 -- 4th exp 1455 t[4] = 45 -- 4th exp
1457 a = t 1456 a = t
1458 end 1457 end
1459 </pre></tt></p> 1458 </pre>
1460 1459
1461 <p> 1460 <p>
1462 The order of the assignments in a constructor is undefined. 1461 The order of the assignments in a constructor is undefined.
1463 (This order would be relevant only when there are repeated keys.) 1462 (This order would be relevant only when there are repeated keys.)
1464 1463
1465 1464
1466 <p> 1465 <p>
1467 If the last field in the list has the form <tt>exp</tt> 1466 If the last field in the list has the form <code>exp</code>
1468 and the expression is a function call or a vararg expression, 1467 and the expression is a function call or a vararg expression,
1469 then all values returned by this expression enter the list consecutively 1468 then all values returned by this expression enter the list consecutively
1470 (see <a href="#fn_calls">Function Calls</a>). 1469 (see <a href="#fn_calls">Function Calls</a>).
1471 1470
1472 1471
1476 1475
1477 1476
1478 1477
1479 1478
1480 1479
1481 <h4 <%=heading_options%> ><a name="fn_calls">Function Calls</a></h4> 1480 <h4 heading><a name="fn_calls">Function Calls</a></h4>
1482 1481
1483 <p> 1482 <p>
1484 A function call in Luan has the following syntax: 1483 A function call in Luan has the following syntax:
1485 1484
1486 <p><tt><pre> 1485 <pre>
1487 functioncall ::= prefixexp args 1486 functioncall ::= prefixexp args
1488 </pre></tt></p> 1487 </pre>
1489 1488
1490 <p> 1489 <p>
1491 In a function call, 1490 In a function call,
1492 first prefixexp and args are evaluated. 1491 first prefixexp and args are evaluated.
1493 If the value of prefixexp has type <i>function</i>, 1492 If the value of prefixexp has type <em>function</em>,
1494 then this function is called 1493 then this function is called
1495 with the given arguments. 1494 with the given arguments.
1496 Otherwise, the prefixexp "call" metamethod is called, 1495 Otherwise, the prefixexp "call" metamethod is called,
1497 having as first parameter the value of prefixexp, 1496 having as first parameter the value of prefixexp,
1498 followed by the original call arguments 1497 followed by the original call arguments
1500 1499
1501 1500
1502 <p> 1501 <p>
1503 Arguments have the following syntax: 1502 Arguments have the following syntax:
1504 1503
1505 <p><tt><pre> 1504 <pre>
1506 args ::= &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo; 1505 args ::= &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo;
1507 args ::= tableconstructor 1506 args ::= tableconstructor
1508 args ::= LiteralString 1507 args ::= LiteralString
1509 </pre></tt></p> 1508 </pre>
1510 1509
1511 <p> 1510 <p>
1512 All argument expressions are evaluated before the call. 1511 All argument expressions are evaluated before the call.
1513 A call of the form <tt>f{<i>fields</i>}</tt> is 1512 A call of the form <code>f{<em>fields</em>}</code> is
1514 syntactic sugar for <tt>f({<i>fields</i>})</tt>; 1513 syntactic sugar for <code>f({<em>fields</em>})</code>;
1515 that is, the argument list is a single new table. 1514 that is, the argument list is a single new table.
1516 A call of the form <tt>f'<i>string</i>'</tt> 1515 A call of the form <code>f'<em>string</em>'</code>
1517 (or <tt>f"<i>string</i>"</tt> or <tt>f[[<i>string</i>]]</tt>) 1516 (or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>)
1518 is syntactic sugar for <tt>f('<i>string</i>')</tt>; 1517 is syntactic sugar for <code>f('<em>string</em>')</code>;
1519 that is, the argument list is a single literal string. 1518 that is, the argument list is a single literal string.
1520 1519
1521 1520
1522 <p> 1521 <p>
1523 A call of the form <tt>return <i>functioncall</i></tt> is called 1522 A call of the form <code>return <em>functioncall</em></code> is called
1524 a <i>tail call</i>. 1523 a <em>tail call</em>.
1525 Luan implements <i>proper tail calls</i> 1524 Luan implements <em>proper tail calls</em>
1526 (or <i>proper tail recursion</i>): 1525 (or <em>proper tail recursion</em>):
1527 in a tail call, 1526 in a tail call,
1528 the called function reuses the stack entry of the calling function. 1527 the called function reuses the stack entry of the calling function.
1529 Therefore, there is no limit on the number of nested tail calls that 1528 Therefore, there is no limit on the number of nested tail calls that
1530 a program can execute. 1529 a program can execute.
1531 However, a tail call erases any debug information about the 1530 However, a tail call erases any debug information about the
1534 where the <b>return</b> has one single function call as argument; 1533 where the <b>return</b> has one single function call as argument;
1535 this syntax makes the calling function return exactly 1534 this syntax makes the calling function return exactly
1536 the returns of the called function. 1535 the returns of the called function.
1537 So, none of the following examples are tail calls: 1536 So, none of the following examples are tail calls:
1538 1537
1539 <p><tt><pre> 1538 <pre>
1540 return (f(x)) -- results adjusted to 1 1539 return (f(x)) -- results adjusted to 1
1541 return 2 * f(x) 1540 return 2 * f(x)
1542 return x, f(x) -- additional results 1541 return x, f(x) -- additional results
1543 f(x); return -- results discarded 1542 f(x); return -- results discarded
1544 return x or f(x) -- results adjusted to 1 1543 return x or f(x) -- results adjusted to 1
1545 </pre></tt></p> 1544 </pre>
1546 1545
1547 1546
1548 1547
1549 1548
1550 <h4 <%=heading_options%> ><a name="fn_def">Function Definitions</a></h4> 1549 <h4 heading><a name="fn_def">Function Definitions</a></h4>
1551 1550
1552 <p> 1551 <p>
1553 The syntax for function definition is 1552 The syntax for function definition is
1554 1553
1555 <p><tt><pre> 1554 <pre>
1556 functiondef ::= <b>function</b> funcbody 1555 functiondef ::= <b>function</b> funcbody
1557 funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b> 1556 funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
1558 </pre></tt></p> 1557 </pre>
1559 1558
1560 <p> 1559 <p>
1561 The following syntactic sugar simplifies function definitions: 1560 The following syntactic sugar simplifies function definitions:
1562 1561
1563 <p><tt><pre> 1562 <pre>
1564 stat ::= <b>function</b> funcname funcbody 1563 stat ::= <b>function</b> funcname funcbody
1565 stat ::= <b>local</b> <b>function</b> Name funcbody 1564 stat ::= <b>local</b> <b>function</b> Name funcbody
1566 funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name] 1565 funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
1567 </pre></tt></p> 1566 </pre>
1568 1567
1569 <p> 1568 <p>
1570 The statement 1569 The statement
1571 1570
1572 <p><tt><pre> 1571 <pre>
1573 function f () <i>body</i> end 1572 function f () <em>body</em> end
1574 </pre></tt></p> 1573 </pre>
1575 1574
1576 <p> 1575 <p>
1577 translates to 1576 translates to
1578 1577
1579 <p><tt><pre> 1578 <pre>
1580 f = function () <i>body</i> end 1579 f = function () <em>body</em> end
1581 </pre></tt></p> 1580 </pre>
1582 1581
1583 <p> 1582 <p>
1584 The statement 1583 The statement
1585 1584
1586 <p><tt><pre> 1585 <pre>
1587 function t.a.b.c.f () <i>body</i> end 1586 function t.a.b.c.f () <em>body</em> end
1588 </pre></tt></p> 1587 </pre>
1589 1588
1590 <p> 1589 <p>
1591 translates to 1590 translates to
1592 1591
1593 <p><tt><pre> 1592 <pre>
1594 t.a.b.c.f = function () <i>body</i> end 1593 t.a.b.c.f = function () <em>body</em> end
1595 </pre></tt></p> 1594 </pre>
1596 1595
1597 <p> 1596 <p>
1598 The statement 1597 The statement
1599 1598
1600 <p><tt><pre> 1599 <pre>
1601 local function f () <i>body</i> end 1600 local function f () <em>body</em> end
1602 </pre></tt></p> 1601 </pre>
1603 1602
1604 <p> 1603 <p>
1605 translates to 1604 translates to
1606 1605
1607 <p><tt><pre> 1606 <pre>
1608 local f; f = function () <em>body</em> end 1607 local f; f = function () <em>body</em> end
1609 </pre></tt></p> 1608 </pre>
1610 1609
1611 <p> 1610 <p>
1612 not to 1611 not to
1613 1612
1614 <p><tt><pre> 1613 <pre>
1615 local f = function () <em>body</em> end 1614 local f = function () <em>body</em> end
1616 </pre></tt></p> 1615 </pre>
1617 1616
1618 <p> 1617 <p>
1619 (This only makes a difference when the body of the function 1618 (This only makes a difference when the body of the function
1620 contains references to <tt>f</tt>.) 1619 contains references to <code>f</code>.)
1621 1620
1622 1621
1623 <p> 1622 <p>
1624 A function definition is an executable expression, 1623 A function definition is an executable expression,
1625 whose value has type <i>function</i>. 1624 whose value has type <em>function</em>.
1626 When Luan precompiles a chunk, 1625 When Luan precompiles a chunk,
1627 all its function bodies are precompiled too. 1626 all its function bodies are precompiled too.
1628 Then, whenever Luan executes the function definition, 1627 Then, whenever Luan executes the function definition,
1629 the function is <i>instantiated</i> (or <i>closed</i>). 1628 the function is <em>instantiated</em> (or <em>closed</em>).
1630 This function instance (or <i>closure</i>) 1629 This function instance (or <em>closure</em>)
1631 is the final value of the expression. 1630 is the final value of the expression.
1632 1631
1633 1632
1634 <p> 1633 <p>
1635 Parameters act as local variables that are 1634 Parameters act as local variables that are
1636 initialized with the argument values: 1635 initialized with the argument values:
1637 1636
1638 <p><tt><pre> 1637 <pre>
1639 parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo; 1638 parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
1640 </pre></tt></p> 1639 </pre>
1641 1640
1642 <p> 1641 <p>
1643 When a function is called, 1642 When a function is called,
1644 the list of arguments is adjusted to 1643 the list of arguments is adjusted to
1645 the length of the list of parameters, 1644 the length of the list of parameters,
1646 unless the function is a <i>vararg function</i>, 1645 unless the function is a <em>vararg function</em>,
1647 which is indicated by three dots ('<tt>...</tt>') 1646 which is indicated by three dots ('<code>...</code>')
1648 at the end of its parameter list. 1647 at the end of its parameter list.
1649 A vararg function does not adjust its argument list; 1648 A vararg function does not adjust its argument list;
1650 instead, it collects all extra arguments and supplies them 1649 instead, it collects all extra arguments and supplies them
1651 to the function through a <i>vararg expression</i>, 1650 to the function through a <em>vararg expression</em>,
1652 which is also written as three dots. 1651 which is also written as three dots.
1653 The value of this expression is a list of all actual extra arguments, 1652 The value of this expression is a list of all actual extra arguments,
1654 similar to a function with multiple results. 1653 similar to a function with multiple results.
1655 If a vararg expression is used inside another expression 1654 If a vararg expression is used inside another expression
1656 or in the middle of a list of expressions, 1655 or in the middle of a list of expressions,
1661 1660
1662 1661
1663 <p> 1662 <p>
1664 As an example, consider the following definitions: 1663 As an example, consider the following definitions:
1665 1664
1666 <p><tt><pre> 1665 <pre>
1667 function f(a, b) end 1666 function f(a, b) end
1668 function g(a, b, ...) end 1667 function g(a, b, ...) end
1669 function r() return 1,2,3 end 1668 function r() return 1,2,3 end
1670 </pre></tt></p> 1669 </pre>
1671 1670
1672 <p> 1671 <p>
1673 Then, we have the following mapping from arguments to parameters and 1672 Then, we have the following mapping from arguments to parameters and
1674 to the vararg expression: 1673 to the vararg expression:
1675 1674
1676 <p><tt><pre> 1675 <pre>
1677 CALL PARAMETERS 1676 CALL PARAMETERS
1678 1677
1679 f(3) a=3, b=nil 1678 f(3) a=3, b=nil
1680 f(3, 4) a=3, b=4 1679 f(3, 4) a=3, b=4
1681 f(3, 4, 5) a=3, b=4 1680 f(3, 4, 5) a=3, b=4
1684 1683
1685 g(3) a=3, b=nil, ... --&gt; (nothing) 1684 g(3) a=3, b=nil, ... --&gt; (nothing)
1686 g(3, 4) a=3, b=4, ... --&gt; (nothing) 1685 g(3, 4) a=3, b=4, ... --&gt; (nothing)
1687 g(3, 4, 5, 8) a=3, b=4, ... --&gt; 5 8 1686 g(3, 4, 5, 8) a=3, b=4, ... --&gt; 5 8
1688 g(5, r()) a=5, b=1, ... --&gt; 2 3 1687 g(5, r()) a=5, b=1, ... --&gt; 2 3
1689 </pre></tt></p> 1688 </pre>
1690 1689
1691 <p> 1690 <p>
1692 Results are returned using the <b>return</b> statement (see <a href="#control">Control Structures</a>). 1691 Results are returned using the <b>return</b> statement (see <a href="#control">Control Structures</a>).
1693 If control reaches the end of a function 1692 If control reaches the end of a function
1694 without encountering a <b>return</b> statement, 1693 without encountering a <b>return</b> statement,
1695 then the function returns with no results. 1694 then the function returns with no results.
1696 1695
1697 1696
1698 <h4 <%=heading_options%> ><a name="template_expr">Template Expressions</a></h4> 1697 <h4 heading><a name="template_expr">Template Expressions</a></h4>
1699 1698
1700 <p>Luan template expression are based on <a href="http://en.wikipedia.org/wiki/JavaServer_Pages">JSP</a>. Template expressions return multiple values. Here is an example:</p> 1699 <p>Luan template expression are based on <a href="http://en.wikipedia.org/wiki/JavaServer_Pages">JSP</a>. Template expressions return multiple values. Here is an example:</p>
1701 1700
1702 <p><tt><pre><%=Html.encode[[ 1701 <pre><%=Html.encode[[
1703 local name = "Bob" 1702 local name = "Bob"
1704 write( %>Hello <%= name %>!<% ) 1703 write( %>Hello <%= name %>!<% )
1705 ]]%></pre></tt></p> 1704 ]]%></pre>
1706 1705
1707 <p>This is equivalent to the code:</p> 1706 <p>This is equivalent to the code:</p>
1708 1707
1709 <p><tt><pre> 1708 <pre>
1710 local name = "Bob" 1709 local name = "Bob"
1711 write( "Hello ", name, "!" ) 1710 write( "Hello ", name, "!" )
1712 </pre></tt></p> 1711 </pre>
1713 1712
1714 <p>The strings in template expressions may be multiple lines.</p> 1713 <p>The strings in template expressions may be multiple lines.</p>
1715 1714
1716 1715
1717 1716
1718 <h3 <%=heading_options%> ><a name="visibility">Visibility Rules</a></h3> 1717 <h3 heading><a name="visibility">Visibility Rules</a></h3>
1719 1718
1720 <p> 1719 <p>
1721 Luan is a lexically scoped language. 1720 Luan is a lexically scoped language.
1722 The scope of a local variable begins at the first statement after 1721 The scope of a local variable begins at the first statement after
1723 its declaration and lasts until the last non-void statement 1722 its declaration and lasts until the last non-void statement
1724 of the innermost block that includes the declaration. 1723 of the innermost block that includes the declaration.
1725 Consider the following example: 1724 Consider the following example:
1726 1725
1727 <p><tt><pre> 1726 <pre>
1728 x = 10 -- global variable 1727 x = 10 -- global variable
1729 do -- new block 1728 do -- new block
1730 local x = x -- new 'x', with value 10 1729 local x = x -- new 'x', with value 10
1731 print(x) --&gt; 10 1730 print(x) --&gt; 10
1732 x = x+1 1731 x = x+1
1735 print(x) --&gt; 12 1734 print(x) --&gt; 12
1736 end 1735 end
1737 print(x) --&gt; 11 1736 print(x) --&gt; 11
1738 end 1737 end
1739 print(x) --&gt; 10 (the global one) 1738 print(x) --&gt; 10 (the global one)
1740 </pre></tt></p> 1739 </pre>
1741 1740
1742 <p> 1741 <p>
1743 Notice that, in a declaration like <tt>local x = x</tt>, 1742 Notice that, in a declaration like <code>local x = x</code>,
1744 the new <tt>x</tt> being declared is not in scope yet, 1743 the new <code>x</code> being declared is not in scope yet,
1745 and so the second <tt>x</tt> refers to the outside variable. 1744 and so the second <code>x</code> refers to the outside variable.
1746 1745
1747 1746
1748 <p> 1747 <p>
1749 Because of the lexical scoping rules, 1748 Because of the lexical scoping rules,
1750 local variables can be freely accessed by functions 1749 local variables can be freely accessed by functions
1751 defined inside their scope. 1750 defined inside their scope.
1752 A local variable used by an inner function is called 1751 A local variable used by an inner function is called
1753 an <i>upvalue</i>, or <i>external local variable</i>, 1752 an <em>upvalue</em>, or <em>external local variable</em>,
1754 inside the inner function. 1753 inside the inner function.
1755 1754
1756 1755
1757 <p> 1756 <p>
1758 Notice that each execution of a <b>local</b> statement 1757 Notice that each execution of a <b>local</b> statement
1759 defines new local variables. 1758 defines new local variables.
1760 Consider the following example: 1759 Consider the following example:
1761 1760
1762 <p><tt><pre> 1761 <pre>
1763 a = {} 1762 a = {}
1764 local x = 20 1763 local x = 20
1765 for i=1,10 do 1764 for i=1,10 do
1766 local y = 0 1765 local y = 0
1767 a[i] = function () y=y+1; return x+y end 1766 a[i] = function () y=y+1; return x+y end
1768 end 1767 end
1769 </pre></tt></p> 1768 </pre>
1770 1769
1771 <p> 1770 <p>
1772 The loop creates ten closures 1771 The loop creates ten closures
1773 (that is, ten instances of the anonymous function). 1772 (that is, ten instances of the anonymous function).
1774 Each of these closures uses a different <tt>y</tt> variable, 1773 Each of these closures uses a different <code>y</code> variable,
1775 while all of them share the same <tt>x</tt>. 1774 while all of them share the same <code>x</code>.
1776 1775
1777 1776
1778 1777
1779 1778
1780 1779
1781 <h2 <%=heading_options%> ><a name="libs">Standard Libraries</a></h2> 1780 <h2 heading><a name="libs">Standard Libraries</a></h2>
1782 1781
1783 <p> 1782 <p>
1784 The standard Luan libraries provide useful functions 1783 The standard Luan libraries provide useful functions
1785 that are implemented both in Java and in Luan itself. 1784 that are implemented both in Java and in Luan itself.
1786 How each function is implemented shouldn't matter to the user. 1785 How each function is implemented shouldn't matter to the user.
1787 Some of these functions provide essential services to the language 1786 Some of these functions provide essential services to the language
1788 (e.g., <a href="#Luan.type"><tt>type</tt></a> and <a href="#Luan.get_metatable"><tt>get_metatable</tt></a>); 1787 (e.g., <a href="#Luan.type"><code>type</code></a> and <a href="#Luan.get_metatable"><code>get_metatable</code></a>);
1789 others provide access to "outside" services (e.g., I/O). 1788 others provide access to "outside" services (e.g., I/O).
1790 1789
1791 1790
1792 <h3 <%=heading_options%> ><a name="default_lib">Default Environment</a></h3> 1791 <h3 heading><a name="default_lib">Default Environment</a></h3>
1793 1792
1794 <p> 1793 <p>
1795 These are provided by default as local variables for any Luan code as described in <a href="#env">Environments</a>. 1794 These are provided by default as local variables for any Luan code as described in <a href="#env">Environments</a>.
1796 1795
1797 1796
1798 <h4 <%=heading_options%> ><a name="require"><tt>java ()</tt></a></h4> 1797 <h4 heading><a name="require"><code>java ()</code></a></h4>
1799 1798
1800 <p> 1799 <p>
1801 This function 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. 1800 This function 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.
1802 1801
1803 1802
1804 <h4 <%=heading_options%> ><a name="require"><tt>require (mod_uri)</tt></a></h4> 1803 <h4 heading><a name="require"><code>require (mod_uri)</code></a></h4>
1805 1804
1806 <p> 1805 <p>
1807 Example use: 1806 Example use:
1808 1807
1809 <p><tt><pre> 1808 <pre>
1810 local Table = require "luan:Table" 1809 local Table = require "luan:Table"
1811 </pre></tt></p> 1810 </pre>
1812 1811
1813 <p> 1812 <p>
1814 Could be defined as: 1813 Could be defined as:
1815 1814
1816 <p><tt><pre> 1815 <pre>
1817 local function require(mod_name) 1816 local function require(mod_name)
1818 return <a href="#Package.load">Package.load</a>(mod_name) or <a href="#Luan.error">Luan.error</a>("module '"..mod_name.."' not found") 1817 return <a href="#Package.load">Package.load</a>(mod_name) or <a href="#Luan.error">Luan.error</a>("module '"..mod_name.."' not found")
1819 end 1818 end
1820 </pre></tt></p> 1819 </pre>
1821 1820
1822 1821
1823 <h3 <%=heading_options%> ><a name="luan_lib">Basic Functions</a></h3> 1822 <h3 heading><a name="luan_lib">Basic Functions</a></h3>
1824 1823
1825 <p> 1824 <p>
1826 Include this library by: 1825 Include this library by:
1827 1826
1828 <p><tt><pre> 1827 <pre>
1829 local Luan = require "luan:Luan" 1828 local Luan = require "luan:Luan"
1830 </pre></tt></p> 1829 </pre>
1831 1830
1832 <p> 1831 <p>
1833 The basic library provides basic functions to Luan that don't depend on other libaries. 1832 The basic library provides basic functions to Luan that don't depend on other libaries.
1834 1833
1835 1834
1836 <h4 <%=heading_options%> ><a name="Luan.assert"><tt>Luan.assert (v [, message])</tt></a></h4> 1835 <h4 heading><a name="Luan.assert"><code>Luan.assert (v [, message])</code></a></h4>
1837 1836
1838 <p> 1837 <p>
1839 Could be defined as: 1838 Could be defined as:
1840 1839
1841 <p><tt><pre> 1840 <pre>
1842 function Luan.assert(v,message) 1841 function Luan.assert(v,message)
1843 return v or <a href="#Luan.error">Luan.error</a>(message or "assertion failed!") 1842 return v or <a href="#Luan.error">Luan.error</a>(message or "assertion failed!")
1844 end 1843 end
1845 </pre></tt></p> 1844 </pre>
1846 1845
1847 1846
1848 <h4 <%=heading_options%> ><a name="Luan.assert_binary"><tt>Luan.assert_binary (v)</tt></a></h4> 1847 <h4 heading><a name="Luan.assert_binary"><code>Luan.assert_binary (v)</code></a></h4>
1849 1848
1850 <p> 1849 <p>
1851 Could be defined as: 1850 Could be defined as:
1852 1851
1853 <p><tt><pre> 1852 <pre>
1854 function Luan.assert_binary(v) 1853 function Luan.assert_binary(v)
1855 local v_type = Luan.type(v) 1854 local v_type = Luan.type(v)
1856 return v_type == "binary" and v or <a href="#Luan.error">Luan.error</a>("bad argument #1 (binary expected, got "..v_type..")") 1855 return v_type == "binary" and v or <a href="#Luan.error">Luan.error</a>("bad argument #1 (binary expected, got "..v_type..")")
1857 end 1856 end
1858 </pre></tt></p> 1857 </pre>
1859 1858
1860 1859
1861 <h4 <%=heading_options%> ><a name="Luan.assert_boolean"><tt>Luan.assert_boolean (v)</tt></a></h4> 1860 <h4 heading><a name="Luan.assert_boolean"><code>Luan.assert_boolean (v)</code></a></h4>
1862 1861
1863 <p> 1862 <p>
1864 Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>boolean</tt>. 1863 Like <a href="#Luan.assert_binary"><code>assert_binary</code></a> but for type <code>boolean</code>.
1865 1864
1866 1865
1867 <h4 <%=heading_options%> ><a name="Luan.assert_integer"><tt>Luan.assert_integer (v)</tt></a></h4> 1866 <h4 heading><a name="Luan.assert_integer"><code>Luan.assert_integer (v)</code></a></h4>
1868 1867
1869 <p> 1868 <p>
1870 Asserts that <tt>v</tt> can be converted to Java type <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html">Integer</a> and returns an Integer. 1869 Asserts that <code>v</code> can be converted to Java type <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html">Integer</a> and returns an Integer.
1871 1870
1872 1871
1873 <h4 <%=heading_options%> ><a name="Luan.assert_long"><tt>Luan.assert_long (v)</tt></a></h4> 1872 <h4 heading><a name="Luan.assert_long"><code>Luan.assert_long (v)</code></a></h4>
1874 1873
1875 <p> 1874 <p>
1876 Asserts that <tt>v</tt> can be converted to Java type <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Long.html">Long</a> and returns a Long. 1875 Asserts that <code>v</code> can be converted to Java type <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Long.html">Long</a> and returns a Long.
1877 1876
1878 1877
1879 <h4 <%=heading_options%> ><a name="Luan.assert_number"><tt>Luan.assert_number (v)</tt></a></h4> 1878 <h4 heading><a name="Luan.assert_number"><code>Luan.assert_number (v)</code></a></h4>
1880 1879
1881 <p> 1880 <p>
1882 Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>number</tt>. 1881 Like <a href="#Luan.assert_binary"><code>assert_binary</code></a> but for type <code>number</code>.
1883 1882
1884 1883
1885 <h4 <%=heading_options%> ><a name="Luan.assert_string"><tt>Luan.assert_string (v)</tt></a></h4> 1884 <h4 heading><a name="Luan.assert_string"><code>Luan.assert_string (v)</code></a></h4>
1886 1885
1887 <p> 1886 <p>
1888 Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>string</tt>. 1887 Like <a href="#Luan.assert_binary"><code>assert_binary</code></a> but for type <code>string</code>.
1889 1888
1890 1889
1891 <h4 <%=heading_options%> ><a name="Luan.assert_table"><tt>Luan.assert_table (v)</tt></a></h4> 1890 <h4 heading><a name="Luan.assert_table"><code>Luan.assert_table (v)</code></a></h4>
1892 1891
1893 <p> 1892 <p>
1894 Like <a href="#Luan.assert_binary"><tt>assert_binary</tt></a> but for type <tt>table</tt>. 1893 Like <a href="#Luan.assert_binary"><code>assert_binary</code></a> but for type <code>table</code>.
1895 1894
1896 1895
1897 <h4 <%=heading_options%> ><a name="Luan.do_file"><tt>Luan.do_file ([uri])</tt></a></h4> 1896 <h4 heading><a name="Luan.do_file"><code>Luan.do_file ([uri])</code></a></h4>
1898 1897
1899 <p> 1898 <p>
1900 Could be defined as: 1899 Could be defined as:
1901 1900
1902 <p><tt><pre> 1901 <pre>
1903 function Luan.do_file(uri) 1902 function Luan.do_file(uri)
1904 return <a href="#Luan.load_file">Luan.load_file</a>(uri)() 1903 return <a href="#Luan.load_file">Luan.load_file</a>(uri)()
1905 end 1904 end
1906 </pre></tt></p> 1905 </pre>
1907 1906
1908 1907
1909 1908
1910 <h4 <%=heading_options%> ><a name="Luan.error"><tt>Luan.error (message)</tt></a></h4> 1909 <h4 heading><a name="Luan.error"><code>Luan.error (message)</code></a></h4>
1911 1910
1912 <p> 1911 <p>
1913 Throws an error containing the message. 1912 Throws an error containing the message.
1914 1913
1915 <p> 1914 <p>
1916 Could be defined as: 1915 Could be defined as:
1917 1916
1918 <p><tt><pre> 1917 <pre>
1919 function Luan.error(message) 1918 function Luan.error(message)
1920 <a href="#Luan.new_error">Luan.new_error</a>(message).throw() 1919 <a href="#Luan.new_error">Luan.new_error</a>(message).throw()
1921 end 1920 end
1922 </pre></tt></p> 1921 </pre>
1923 1922
1924 1923
1925 1924
1926 <h4 <%=heading_options%> ><a name="Luan.get_metatable"><tt>Luan.get_metatable (table)</tt></a></h4> 1925 <h4 heading><a name="Luan.get_metatable"><code>Luan.get_metatable (table)</code></a></h4>
1927 1926
1928 <p> 1927 <p>
1929 If <tt>table</tt> does not have a metatable, returns <b>nil</b>. 1928 If <code>table</code> does not have a metatable, returns <b>nil</b>.
1930 Otherwise, 1929 Otherwise,
1931 if the table's metatable has a <tt>"__metatable"</tt> field, 1930 if the table's metatable has a <code>"__metatable"</code> field,
1932 returns the associated value. 1931 returns the associated value.
1933 Otherwise, returns the metatable of the given table. 1932 Otherwise, returns the metatable of the given table.
1934 1933
1935 1934
1936 <h4 <%=heading_options%> ><a name="Luan.ipairs"><tt>Luan.ipairs (t)</tt></a></h4> 1935 <h4 heading><a name="Luan.ipairs"><code>Luan.ipairs (t)</code></a></h4>
1937 1936
1938 <p> 1937 <p>
1939 Returns an iterator function 1938 Returns an iterator function
1940 so that the construction 1939 so that the construction
1941 1940
1942 <p><tt><pre> 1941 <pre>
1943 for i,v in ipairs(t) do <i>body</i> end 1942 for i,v in ipairs(t) do <em>body</em> end
1944 </pre></tt></p> 1943 </pre>
1945 1944
1946 <p> 1945 <p>
1947 will iterate over the key&ndash;value pairs 1946 will iterate over the key&ndash;value pairs
1948 (<tt>1,t[1]</tt>), (<tt>2,t[2]</tt>), ..., 1947 (<code>1,t[1]</code>), (<code>2,t[2]</code>), ...,
1949 up to the first nil value. 1948 up to the first nil value.
1950 1949
1951 <p> 1950 <p>
1952 Could be defined as: 1951 Could be defined as:
1953 1952
1954 <p><tt><pre> 1953 <pre>
1955 function Luan.ipairs(t) 1954 function Luan.ipairs(t)
1956 local i = 0 1955 local i = 0
1957 return function() 1956 return function()
1958 if i < #t then 1957 if i < #t then
1959 i = i + 1 1958 i = i + 1
1960 return i, t[i] 1959 return i, t[i]
1961 end 1960 end
1962 end 1961 end
1963 end 1962 end
1964 </pre></tt></p> 1963 </pre>
1965 1964
1966 1965
1967 1966
1968 <h4 <%=heading_options%> ><a name="Luan.load"><tt>Luan.load (text, source_name [env, [, allow_expression]])</tt></a></h4> 1967 <h4 heading><a name="Luan.load"><code>Luan.load (text, source_name [env, [, allow_expression]])</code></a></h4>
1969 1968
1970 <p> 1969 <p>
1971 Loads a chunk. 1970 Loads a chunk.
1972 1971
1973 <p> 1972 <p>
1974 The <tt>text</tt> is compiled. 1973 The <code>text</code> is compiled.
1975 If there are no syntactic errors, 1974 If there are no syntactic errors,
1976 returns the compiled chunk as a function; 1975 returns the compiled chunk as a function;
1977 otherwise, throws an error. 1976 otherwise, throws an error.
1978 1977
1979 <p> 1978 <p>
1980 The <tt>source_name</tt> parameter is a string saying where the text came from. It is used to produce error messages. 1979 The <code>source_name</code> parameter is a string saying where the text came from. It is used to produce error messages.
1981 1980
1982 <p> 1981 <p>
1983 If the <tt>env</tt> parameter is supplied, it becomes the <tt>_ENV</tt> of the chunk. 1982 If the <code>env</code> parameter is supplied, it becomes the <code>_ENV</code> of the chunk.
1984 1983
1985 <p> 1984 <p>
1986 If the <tt>allow_expression</tt> parameter is <tt>true</tt> then the entire text can be nothing more than an expression in which case the chunk returns the value of this expression. 1985 If the <code>allow_expression</code> parameter is <code>true</code> then the entire text can be nothing more than an expression in which case the chunk returns the value of this expression.
1987 1986
1988 1987
1989 <h4 <%=heading_options%> ><a name="Luan.load_file"><tt>Luan.load_file (file_uri [, add_extension])</tt></a></h4> 1988 <h4 heading><a name="Luan.load_file"><code>Luan.load_file (file_uri [, add_extension])</code></a></h4>
1990 1989
1991 <p> 1990 <p>
1992 Similar to <a href="#Luan.load"><tt>load</tt></a>, 1991 Similar to <a href="#Luan.load"><code>load</code></a>,
1993 but gets the chunk from file <tt>file_uri</tt> 1992 but gets the chunk from file <code>file_uri</code>
1994 or from the standard input, 1993 or from the standard input,
1995 if no file uri is given. 1994 if no file uri is given.
1996 1995
1997 <p> 1996 <p>
1998 Could be defined as: 1997 Could be defined as:
1999 1998
2000 <p><tt><pre> 1999 <pre>
2001 function Luan.load_file(file_uri,add_extension) 2000 function Luan.load_file(file_uri,add_extension)
2002 file_uri = file_uri or "stdin:" 2001 file_uri = file_uri or "stdin:"
2003 local f = Io.uri(file_uri,add_extension) 2002 local f = Io.uri(file_uri,add_extension)
2004 f.exists() or <a href="#Luan.error">Luan.error</a>("file '"..file_uri.."' not found") 2003 f.exists() or <a href="#Luan.error">Luan.error</a>("file '"..file_uri.."' not found")
2005 return <a href="#Luan.load">Luan.load</a>( f.read_text(), file_uri ) 2004 return <a href="#Luan.load">Luan.load</a>( f.read_text(), file_uri )
2006 end 2005 end
2007 </pre></tt></p> 2006 </pre>
2008 2007
2009 2008
2010 <h4 <%=heading_options%> ><a name="Luan.new_error"><tt>Luan.new_error (message)</tt></a></h4> 2009 <h4 heading><a name="Luan.new_error"><code>Luan.new_error (message)</code></a></h4>
2011 2010
2012 <p> 2011 <p>
2013 Creates a new error table containing the message assigned to "<tt>message</tt>". The error table also contains a <tt>throw</tt> function which throws the error. The table also contains a list of stack trace elements where each stack trace element is a table containing "<tt>source</tt>", "<tt>line</tt>", and possible "<tt>call_to</tt>". The table also has a metatable containing "<tt>__to_string</tt>" to render the error. 2012 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.
2014 2013
2015 <p> 2014 <p>
2016 To print the current stack trace, you could do: 2015 To print the current stack trace, you could do:
2017 2016
2018 <p><tt><pre> 2017 <pre>
2019 Io.print( Luan.new_error "stack" ) 2018 Io.print( Luan.new_error "stack" )
2020 </pre></tt></p> 2019 </pre>
2021 2020
2022 2021
2023 <h4 <%=heading_options%> ><a name="Luan.pairs"><tt>Luan.pairs (t)</tt></a></h4> 2022 <h4 heading><a name="Luan.pairs"><code>Luan.pairs (t)</code></a></h4>
2024 2023
2025 <p> 2024 <p>
2026 If <tt>t</tt> has a metamethod <tt>__pairs</tt>, 2025 If <code>t</code> has a metamethod <code>__pairs</code>,
2027 calls it with <tt>t</tt> as argument and returns the 2026 calls it with <code>t</code> as argument and returns the
2028 result from the call. 2027 result from the call.
2029 2028
2030 2029
2031 <p> 2030 <p>
2032 Otherwise, 2031 Otherwise,
2033 returns a function 2032 returns a function
2034 so that the construction 2033 so that the construction
2035 2034
2036 <p><tt><pre> 2035 <pre>
2037 for k,v in pairs(t) do <i>body</i> end 2036 for k,v in pairs(t) do <em>body</em> end
2038 </pre></tt></p> 2037 </pre>
2039 2038
2040 <p> 2039 <p>
2041 will iterate over all key&ndash;value pairs of table <tt>t</tt>. 2040 will iterate over all key&ndash;value pairs of table <code>t</code>.
2042 2041
2043 2042
2044 2043
2045 <h4 <%=heading_options%> ><a name="Luan.pcall"><tt>Luan.pcall (f [, arg1, &middot;&middot;&middot;])</tt></a></h4> 2044 <h4 heading><a name="Luan.pcall"><code>Luan.pcall (f [, arg1, &middot;&middot;&middot;])</code></a></h4>
2046 2045
2047 <p> 2046 <p>
2048 Calls function <tt>f</tt> with 2047 Calls function <code>f</code> with
2049 the given arguments in <i>protected mode</i>. 2048 the given arguments in <em>protected mode</em>.
2050 This means that any error inside&nbsp;<tt>f</tt> is not propagated; 2049 This means that any error inside&nbsp;<code>f</code> is not propagated;
2051 instead, <tt>pcall</tt> catches the error 2050 instead, <code>pcall</code> catches the error
2052 and returns a status code. 2051 and returns a status code.
2053 Its first result is the status code (a boolean), 2052 Its first result is the status code (a boolean),
2054 which is true if the call succeeds without errors. 2053 which is true if the call succeeds without errors.
2055 In such case, <tt>pcall</tt> also returns all results from the call, 2054 In such case, <code>pcall</code> also returns all results from the call,
2056 after this first result. 2055 after this first result.
2057 In case of any error, <tt>pcall</tt> returns <b>false</b> plus the error. 2056 In case of any error, <code>pcall</code> returns <b>false</b> plus the error.
2058 2057
2059 2058
2060 2059
2061 2060
2062 <p> 2061 <p>
2070 For complete control over the output, 2069 For complete control over the output,
2071 use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. 2070 use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>.
2072 2071
2073 2072
2074 2073
2075 <h4 <%=heading_options%> ><a name="Luan.range"><tt>Luan.range (start, stop [, step])</tt></a></h4> 2074 <h4 heading><a name="Luan.range"><code>Luan.range (start, stop [, step])</code></a></h4>
2076 2075
2077 <p> 2076 <p>
2078 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. 2077 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.
2079 2078
2080 <p> 2079 <p>
2081 Example use: 2080 Example use:
2082 2081
2083 <p><tt><pre> 2082 <pre>
2084 for i in range(1,10) do 2083 for i in range(1,10) do
2085 Io.print("count up:",i) 2084 Io.print("count up:",i)
2086 end 2085 end
2087 for i in range(10,0,-1) do 2086 for i in range(10,0,-1) do
2088 Io.print("count down:",i) 2087 Io.print("count down:",i)
2089 end 2088 end
2090 </pre></tt></p> 2089 </pre>
2091 2090
2092 <p> 2091 <p>
2093 Could be defined as: 2092 Could be defined as:
2094 2093
2095 <p><tt><pre> 2094 <pre>
2096 function Luan.range(start, stop, step) 2095 function Luan.range(start, stop, step)
2097 step = step or 1 2096 step = step or 1
2098 step == 0 and <a href="#Luan.error">Luan.error</a> "bad argument #3 (step may not be zero)" 2097 step == 0 and <a href="#Luan.error">Luan.error</a> "bad argument #3 (step may not be zero)"
2099 local i = start 2098 local i = start
2100 return function() 2099 return function()
2103 i = i + step 2102 i = i + step
2104 return rtn 2103 return rtn
2105 end 2104 end
2106 end 2105 end
2107 end 2106 end
2108 </pre></tt></p> 2107 </pre>
2109 2108
2110 2109
2111 2110
2112 <h4 <%=heading_options%> ><a name="Luan.raw_equal"><tt>Luan.raw_equal (v1, v2)</tt></a></h4> 2111 <h4 heading><a name="Luan.raw_equal"><code>Luan.raw_equal (v1, v2)</code></a></h4>
2113 2112
2114 <p> 2113 <p>
2115 Checks whether <tt>v1</tt> is equal to <tt>v2</tt>, 2114 Checks whether <code>v1</code> is equal to <code>v2</code>,
2116 without invoking any metamethod. 2115 without invoking any metamethod.
2117 Returns a boolean. 2116 Returns a boolean.
2118 2117
2119 2118
2120 2119
2121 <h4 <%=heading_options%> ><a name="Luan.raw_get"><tt>Luan.raw_get (table, index)</tt></a></h4> 2120 <h4 heading><a name="Luan.raw_get"><code>Luan.raw_get (table, index)</code></a></h4>
2122 2121
2123 <p> 2122 <p>
2124 Gets the real value of <tt>table[index]</tt>, 2123 Gets the real value of <code>table[index]</code>,
2125 without invoking any metamethod. 2124 without invoking any metamethod.
2126 <tt>table</tt> must be a table; 2125 <code>table</code> must be a table;
2127 <tt>index</tt> may be any value. 2126 <code>index</code> may be any value.
2128 2127
2129 2128
2130 2129
2131 <h4 <%=heading_options%> ><a name="Luan.raw_len"><tt>Luan.raw_len (v)</tt></a></h4> 2130 <h4 heading><a name="Luan.raw_len"><code>Luan.raw_len (v)</code></a></h4>
2132 2131
2133 <p> 2132 <p>
2134 Returns the length of the object <tt>v</tt>, 2133 Returns the length of the object <code>v</code>,
2135 which must be a table or a string, 2134 which must be a table or a string,
2136 without invoking any metamethod. 2135 without invoking any metamethod.
2137 Returns an integer. 2136 Returns an integer.
2138 2137
2139 2138
2140 2139
2141 <h4 <%=heading_options%> ><a name="Luan.raw_set"><tt>Luan.raw_set (table, index, value)</tt></a></h4> 2140 <h4 heading><a name="Luan.raw_set"><code>Luan.raw_set (table, index, value)</code></a></h4>
2142 2141
2143 <p> 2142 <p>
2144 Sets the real value of <tt>table[index]</tt> to <tt>value</tt>, 2143 Sets the real value of <code>table[index]</code> to <code>value</code>,
2145 without invoking any metamethod. 2144 without invoking any metamethod.
2146 <tt>table</tt> must be a table, 2145 <code>table</code> must be a table,
2147 <tt>index</tt> any value different from <b>nil</b>, 2146 <code>index</code> any value different from <b>nil</b>,
2148 and <tt>value</tt> any Lua value. 2147 and <code>value</code> any Lua value.
2149 2148
2150 2149
2151 <h4 <%=heading_options%> ><a name="Luan.set_metatable"><tt>Luan.set_metatable (table, metatable)</tt></a></h4> 2150 <h4 heading><a name="Luan.set_metatable"><code>Luan.set_metatable (table, metatable)</code></a></h4>
2152 2151
2153 <p> 2152 <p>
2154 Sets the metatable for the given table. 2153 Sets the metatable for the given table.
2155 If <tt>metatable</tt> is <b>nil</b>, 2154 If <code>metatable</code> is <b>nil</b>,
2156 removes the metatable of the given table. 2155 removes the metatable of the given table.
2157 If the original metatable has a <tt>"__metatable"</tt> field, 2156 If the original metatable has a <code>"__metatable"</code> field,
2158 raises an error. 2157 raises an error.
2159 2158
2160 2159
2161 2160
2162 <h4 <%=heading_options%> ><a name="Luan.to_string"><tt>Luan.to_string (v)</tt></a></h4> 2161 <h4 heading><a name="Luan.to_string"><code>Luan.to_string (v)</code></a></h4>
2163 2162
2164 <p> 2163 <p>
2165 Receives a value of any type and 2164 Receives a value of any type and
2166 converts it to a string in a human-readable format. 2165 converts it to a string in a human-readable format.
2167 2166
2168 <p> 2167 <p>
2169 If the metatable of <tt>v</tt> has a <tt>"__to_string"</tt> field, 2168 If the metatable of <code>v</code> has a <code>"__to_string"</code> field,
2170 then <tt>to_string</tt> calls the corresponding value 2169 then <code>to_string</code> calls the corresponding value
2171 with <tt>v</tt> as argument, 2170 with <code>v</code> as argument,
2172 and uses the result of the call as its result. 2171 and uses the result of the call as its result.
2173 2172
2174 2173
2175 2174
2176 <h4 <%=heading_options%> ><a name="Luan.try"><tt>Luan.try (t)</tt></a></h4> 2175 <h4 heading><a name="Luan.try"><code>Luan.try (t)</code></a></h4>
2177 2176
2178 <p> 2177 <p>
2179 Implements try-catch as found in other languages where each block is in table <tt>t</tt>. <tt>t[1]</tt> is the "try" block. The <tt>t.catch</tt> and <tt>t.finally</tt> blocks are optional. Returns the result of the "try" block or the "catch" block. 2178 Implements try-catch as found in other languages where each block is in table <code>t</code>. <code>t[1]</code> is the "try" block. The <code>t.catch</code> and <code>t.finally</code> blocks are optional. Returns the result of the "try" block or the "catch" block.
2180 2179
2181 <p> 2180 <p>
2182 Example use: 2181 Example use:
2183 2182
2184 <p><tt><pre> 2183 <pre>
2185 try { 2184 try {
2186 function() 2185 function()
2187 a_dangerous_fn() 2186 a_dangerous_fn()
2188 end; 2187 end;
2189 catch = function(e) 2188 catch = function(e)
2191 end; 2190 end;
2192 finally = function() 2191 finally = function()
2193 -- clean up 2192 -- clean up
2194 end; 2193 end;
2195 } 2194 }
2196 </pre></tt></p> 2195 </pre>
2197 2196
2198 <p> 2197 <p>
2199 Could be defined as: 2198 Could be defined as:
2200 2199
2201 <p><tt><pre> 2200 <pre>
2202 function Luan.try(t) 2201 function Luan.try(t)
2203 local r = { <a href="#Luan.pcall">Luan.pcall</a>(t[1]) } 2202 local r = { <a href="#Luan.pcall">Luan.pcall</a>(t[1]) }
2204 if r[1] then 2203 if r[1] then
2205 Table.remove(r,1) 2204 Table.remove(r,1)
2206 elseif t.catch ~= nil then 2205 elseif t.catch ~= nil then
2210 r[2].throw() 2209 r[2].throw()
2211 end 2210 end
2212 t.finally and t.finally() 2211 t.finally and t.finally()
2213 return Table.unpack(r) 2212 return Table.unpack(r)
2214 end 2213 end
2215 </pre></tt></p> 2214 </pre>
2216 2215
2217 2216
2218 <h4 <%=heading_options%> ><a name="Luan.type"><tt>Luan.type (v)</tt></a></h4> 2217 <h4 heading><a name="Luan.type"><code>Luan.type (v)</code></a></h4>
2219 2218
2220 <p> 2219 <p>
2221 Returns the type of its only argument, coded as a string. 2220 Returns the type of its only argument, coded as a string.
2222 The possible results of this function are 2221 The possible results of this function are
2223 "<tt>nil</tt>" (a string, not the value <b>nil</b>), 2222 "<code>nil</code>" (a string, not the value <b>nil</b>),
2224 "<tt>number</tt>", 2223 "<code>number</code>",
2225 "<tt>string</tt>", 2224 "<code>string</code>",
2226 "<tt>binary</tt>", 2225 "<code>binary</code>",
2227 "<tt>boolean</tt>", 2226 "<code>boolean</code>",
2228 "<tt>table</tt>", 2227 "<code>table</code>",
2229 "<tt>function</tt>", 2228 "<code>function</code>",
2230 and "<tt>java</tt>". 2229 and "<code>java</code>".
2231 2230
2232 2231
2233 <h4 <%=heading_options%> ><a name="Luan.values"><tt>Luan.values (&middot;&middot;&middot;)</tt></a></h4> 2232 <h4 heading><a name="Luan.values"><code>Luan.values (&middot;&middot;&middot;)</code></a></h4>
2234 2233
2235 <p> 2234 <p>
2236 Returns a function so that the construction 2235 Returns a function so that the construction
2237 2236
2238 <p><tt><pre> 2237 <pre>
2239 for v in Luan.values(&middot;&middot;&middot;) do <i>body</i> end 2238 for v in Luan.values(&middot;&middot;&middot;) do <em>body</em> end
2240 </pre></tt></p> 2239 </pre>
2241 2240
2242 <p> 2241 <p>
2243 will iterate over all values of <tt>&middot;&middot;&middot;</tt>. 2242 will iterate over all values of <code>&middot;&middot;&middot;</code>.
2244 2243
2245 2244
2246 2245
2247 <h4 <%=heading_options%> ><a name="Luan.VERSION"><tt>Luan.VERSION</tt></a></h4> 2246 <h4 heading><a name="Luan.VERSION"><code>Luan.VERSION</code></a></h4>
2248 2247
2249 <p> 2248 <p>
2250 A global variable (not a function) that 2249 A global variable (not a function) that
2251 holds a string containing the current interpreter version. 2250 holds a string containing the current interpreter version.
2252 The current value of this variable is "<tt><%=Luan.VERSION%></tt>". 2251 The current value of this variable is "<code><%=Luan.VERSION%></code>".
2253 2252
2254 2253
2255 2254
2256 2255
2257 2256
2258 2257
2259 <h3 <%=heading_options%> ><a name="package_lib">Modules</a></h3> 2258 <h3 heading><a name="package_lib">Modules</a></h3>
2260 2259
2261 <p> 2260 <p>
2262 Include this library by: 2261 Include this library by:
2263 2262
2264 <p><tt><pre> 2263 <pre>
2265 local Package = require "luan:Package" 2264 local Package = require "luan:Package"
2266 </pre></tt></p> 2265 </pre>
2267 2266
2268 <p> 2267 <p>
2269 The package library provides basic 2268 The package library provides basic
2270 facilities for loading modules in Luan. 2269 facilities for loading modules in Luan.
2271 2270
2272 2271
2273 <h4 <%=heading_options%> ><a name="Package.load"><tt>Package.load (mod_uri)</tt></a></h4> 2272 <h4 heading><a name="Package.load"><code>Package.load (mod_uri)</code></a></h4>
2274 2273
2275 <p> 2274 <p>
2276 Loads the given module. 2275 Loads the given module.
2277 The function starts by looking into the <a href="#Package.loaded"><tt>Package.loaded</tt></a> table 2276 The function starts by looking into the <a href="#Package.loaded"><code>Package.loaded</code></a> table
2278 to determine whether <tt>mod_uri</tt> is already loaded. 2277 to determine whether <code>mod_uri</code> is already loaded.
2279 If it is, then <tt>Package.load</tt> returns the value stored 2278 If it is, then <code>Package.load</code> returns the value stored
2280 at <tt>Package.loaded[mod_uri]</tt>. 2279 at <code>Package.loaded[mod_uri]</code>.
2281 Otherwise, it tries to load a new value for the module. 2280 Otherwise, it tries to load a new value for the module.
2282 2281
2283 <p> 2282 <p>
2284 To load a new value, <tt>Package.load</tt> first checks if <tt>mod_uri</tt> starts with "<b>java:</b>". If yes, then this is a Java class which is loaded by special Java code. 2283 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.
2285 2284
2286 <p> 2285 <p>
2287 If <tt>mod_uri</tt> is not a Java class, then <tt>Package.load</tt> tries to read the text of the file referred to by <tt>mod_uri</tt> (using <tt>add_extension</tt>=true). If the file doesn't exist, then <tt>Package.load</tt> returns <b>nil</b>. If the file exists, then its content is compiled into a chunk calling <a href="#Luan.load"><tt>Luan.load</tt></a> and passing in an empty table as the <tt>env</tt> value. This chunk is run passing in <tt>mod_uri</tt> as an argument. If the chunk returns a value other than <b>nil</b>, then that value is the value of this module. Otherwise the <tt>env</tt> that was passed in is the value of this module. 2286 If <code>mod_uri</code> is not a Java class, then <code>Package.load</code> tries to read the text of the file referred to by <code>mod_uri</code> (using <code>add_extension</code>=true). If the file doesn't exist, then <code>Package.load</code> returns <b>nil</b>. If the file exists, then its content is compiled into a chunk calling <a href="#Luan.load"><code>Luan.load</code></a> and passing in an empty table as the <code>env</code> value. This chunk is run passing in <code>mod_uri</code> as an argument. If the chunk returns a value other than <b>nil</b>, then that value is the value of this module. Otherwise the <code>env</code> that was passed in is the value of this module.
2288 2287
2289 <p> 2288 <p>
2290 If a new value for the module successful loaded, then it is stored in <tt>Package.loaded[mod_uri]</tt>. The value is returned. 2289 If a new value for the module successful loaded, then it is stored in <code>Package.loaded[mod_uri]</code>. The value is returned.
2291 2290
2292 2291
2293 2292
2294 2293
2295 <h4 <%=heading_options%> ><a name="Package.loaded"><tt>Package.loaded</tt></a></h4> 2294 <h4 heading><a name="Package.loaded"><code>Package.loaded</code></a></h4>
2296 2295
2297 2296
2298 <p> 2297 <p>
2299 A table used by <a href="#Package.load"><tt>Package.load</tt></a> to control which 2298 A table used by <a href="#Package.load"><code>Package.load</code></a> to control which
2300 modules are already loaded. 2299 modules are already loaded.
2301 When you load a module <tt>mod_uri</tt> and 2300 When you load a module <code>mod_uri</code> and
2302 <tt>Package.loaded[mod_uri]</tt> is not <b>nil</b>, 2301 <code>Package.loaded[mod_uri]</code> is not <b>nil</b>,
2303 <a href="#Package.load"><tt>Package.load</tt></a> simply returns the value stored there. 2302 <a href="#Package.load"><code>Package.load</code></a> simply returns the value stored there.
2304 2303
2305 2304
2306 <p> 2305 <p>
2307 This variable is only a reference to the real table; 2306 This variable is only a reference to the real table;
2308 assignments to this variable do not change the 2307 assignments to this variable do not change the
2309 table used by <a href="#Package.load"><tt>Package.load</tt></a>. 2308 table used by <a href="#Package.load"><code>Package.load</code></a>.
2310 2309
2311 2310
2312 2311
2313 2312
2314 2313
2315 2314
2316 <h3 <%=heading_options%> ><a name="string_lib">String Manipulation</a></h3> 2315 <h3 heading><a name="string_lib">String Manipulation</a></h3>
2317 2316
2318 <p> 2317 <p>
2319 Include this library by: 2318 Include this library by:
2320 2319
2321 <p><tt><pre> 2320 <pre>
2322 local String = require "luan:String" 2321 local String = require "luan:String"
2323 </pre></tt></p> 2322 </pre>
2324 2323
2325 <p> 2324 <p>
2326 This library provides generic functions for string manipulation, 2325 This library provides generic functions for string manipulation,
2327 such as finding and extracting substrings, and pattern matching. 2326 such as finding and extracting substrings, and pattern matching.
2328 When indexing a string in Luan, the first character is at position&nbsp;1 2327 When indexing a string in Luan, the first character is at position&nbsp;1
2331 from the end of the string. 2330 from the end of the string.
2332 Thus, the last character is at position -1, and so on. 2331 Thus, the last character is at position -1, and so on.
2333 2332
2334 2333
2335 2334
2336 <h4 <%=heading_options%> ><a name="String.char"><tt>String.char (&middot;&middot;&middot;)</tt></a></h4> 2335 <h4 heading><a name="String.char"><code>String.char (&middot;&middot;&middot;)</code></a></h4>
2337 2336
2338 <p> 2337 <p>
2339 Receives zero or more integers. 2338 Receives zero or more integers.
2340 Returns a string with length equal to the number of arguments, 2339 Returns a string with length equal to the number of arguments,
2341 in which each character has the internal numerical code equal 2340 in which each character has the internal numerical code equal
2342 to its corresponding argument. 2341 to its corresponding argument.
2343 2342
2344 2343
2345 <h4 <%=heading_options%> ><a name="String.concat"><tt>String.concat (&middot;&middot;&middot;)</tt></a></h4> 2344 <h4 heading><a name="String.concat"><code>String.concat (&middot;&middot;&middot;)</code></a></h4>
2346 2345
2347 <p> 2346 <p>
2348 Concatenates the <a href="#Luan.to_string"><tt>to_string</tt></a> value of all arguments. 2347 Concatenates the <a href="#Luan.to_string"><code>to_string</code></a> value of all arguments.
2349 2348
2350 2349
2351 2350
2352 <h4 <%=heading_options%> ><a name="String.encode"><tt>String.encode (s)</tt></a></h4> 2351 <h4 heading><a name="String.encode"><code>String.encode (s)</code></a></h4>
2353 2352
2354 <p> 2353 <p>
2355 Encodes argument <tt>s</tt> into a string that can be placed in quotes so as to return the original value of the string. 2354 Encodes argument <code>s</code> into a string that can be placed in quotes so as to return the original value of the string.
2356 2355
2357 2356
2358 2357
2359 2358
2360 <h4 <%=heading_options%> ><a name="String.find"><tt>String.find (s, pattern [, init [, plain]])</tt></a></h4> 2359 <h4 heading><a name="String.find"><code>String.find (s, pattern [, init [, plain]])</code></a></h4>
2361 2360
2362 <p> 2361 <p>
2363 Looks for the first match of 2362 Looks for the first match of
2364 <tt>pattern</tt> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) in the string <tt>s</tt>. 2363 <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>.
2365 If it finds a match, then <tt>find</tt> returns the indices of&nbsp;<tt>s</tt> 2364 If it finds a match, then <code>find</code> returns the indices of&nbsp;<code>s</code>
2366 where this occurrence starts and ends; 2365 where this occurrence starts and ends;
2367 otherwise, it returns <b>nil</b>. 2366 otherwise, it returns <b>nil</b>.
2368 A third, optional numerical argument <tt>init</tt> specifies 2367 A third, optional numerical argument <code>init</code> specifies
2369 where to start the search; 2368 where to start the search;
2370 its default value is&nbsp;1 and can be negative. 2369 its default value is&nbsp;1 and can be negative.
2371 A value of <b>true</b> as a fourth, optional argument <tt>plain</tt> 2370 A value of <b>true</b> as a fourth, optional argument <code>plain</code>
2372 turns off the pattern matching facilities, 2371 turns off the pattern matching facilities,
2373 so the function does a plain "find substring" operation, 2372 so the function does a plain "find substring" operation,
2374 with no characters in <tt>pattern</tt> being considered magic. 2373 with no characters in <code>pattern</code> being considered magic.
2375 Note that if <tt>plain</tt> is given, then <tt>init</tt> must be given as well. 2374 Note that if <code>plain</code> is given, then <code>init</code> must be given as well.
2376 2375
2377 <p> 2376 <p>
2378 If the pattern has captures, 2377 If the pattern has captures,
2379 then in a successful match 2378 then in a successful match
2380 the captured values are also returned, 2379 the captured values are also returned,
2381 after the two indices. 2380 after the two indices.
2382 2381
2383 2382
2384 2383
2385 2384
2386 <h4 <%=heading_options%> ><a name="String.format"><tt>String.format (formatstring, &middot;&middot;&middot;)</tt></a></h4> 2385 <h4 heading><a name="String.format"><code>String.format (formatstring, &middot;&middot;&middot;)</code></a></h4>
2387 2386
2388 2387
2389 <p> 2388 <p>
2390 Returns a formatted version of its variable number of arguments 2389 Returns a formatted version of its variable number of arguments
2391 following the description given in its first argument (which must be a string). 2390 following the description given in its first argument (which must be a string).
2392 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...)"><tt>String.format</tt></a> because Luan calls this internally. 2391 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.
2393 2392
2394 <p> 2393 <p>
2395 Note that Java's <tt>String.format</tt> is too stupid to convert between ints and floats, so you must provide the right kind of number. 2394 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.
2396 2395
2397 2396
2398 2397
2399 <h4 <%=heading_options%> ><a name="String.gmatch"><tt>String.gmatch (s, pattern)</tt></a></h4> 2398 <h4 heading><a name="String.gmatch"><code>String.gmatch (s, pattern)</code></a></h4>
2400 2399
2401 <p> 2400 <p>
2402 Returns an iterator function that, 2401 Returns an iterator function that,
2403 each time it is called, 2402 each time it is called,
2404 returns the next captures from <tt>pattern</tt> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) 2403 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>)
2405 over the string <tt>s</tt>. 2404 over the string <code>s</code>.
2406 If <tt>pattern</tt> specifies no captures, 2405 If <code>pattern</code> specifies no captures,
2407 then the whole match is produced in each call. 2406 then the whole match is produced in each call.
2408 2407
2409 2408
2410 <p> 2409 <p>
2411 As an example, the following loop 2410 As an example, the following loop
2412 will iterate over all the words from string <tt>s</tt>, 2411 will iterate over all the words from string <code>s</code>,
2413 printing one per line: 2412 printing one per line:
2414 2413
2415 <p><tt><pre> 2414 <pre>
2416 local s = "hello world from Lua" 2415 local s = "hello world from Lua"
2417 for w in String.gmatch(s, [[\w+]]) do 2416 for w in String.gmatch(s, [[\w+]]) do
2418 print(w) 2417 print(w)
2419 end 2418 end
2420 </pre></tt></p> 2419 </pre>
2421 2420
2422 <p> 2421 <p>
2423 The next example collects all pairs <tt>key=value</tt> from the 2422 The next example collects all pairs <code>key=value</code> from the
2424 given string into a table: 2423 given string into a table:
2425 2424
2426 <p><tt><pre> 2425 <pre>
2427 local t = {} 2426 local t = {}
2428 local s = "from=world, to=Lua" 2427 local s = "from=world, to=Lua"
2429 for k, v in String.gmatch(s, [[(\w+)=(\w+)]]) do 2428 for k, v in String.gmatch(s, [[(\w+)=(\w+)]]) do
2430 t[k] = v 2429 t[k] = v
2431 end 2430 end
2432 </pre></tt></p> 2431 </pre>
2433 2432
2434 <p> 2433 <p>
2435 For this function, a caret '<tt>^</tt>' at the start of a pattern does not 2434 For this function, a caret '<code>^</code>' at the start of a pattern does not
2436 work as an anchor, as this would prevent the iteration. 2435 work as an anchor, as this would prevent the iteration.
2437 2436
2438 2437
2439 2438
2440 <h4 <%=heading_options%> ><a name="String.gsub"><tt>String.gsub (s, pattern, repl [, n])</tt></a></h4> 2439 <h4 heading><a name="String.gsub"><code>String.gsub (s, pattern, repl [, n])</code></a></h4>
2441 2440
2442 <p> 2441 <p>
2443 Returns a copy of <tt>s</tt> 2442 Returns a copy of <code>s</code>
2444 in which all (or the first <tt>n</tt>, if given) 2443 in which all (or the first <code>n</code>, if given)
2445 occurrences of the <tt>pattern</tt> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) have been 2444 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
2446 replaced by a replacement string specified by <tt>repl</tt>, 2445 replaced by a replacement string specified by <code>repl</code>,
2447 which can be a string, a table, or a function. 2446 which can be a string, a table, or a function.
2448 <tt>gsub</tt> also returns, as its second value, 2447 <code>gsub</code> also returns, as its second value,
2449 the total number of matches that occurred. 2448 the total number of matches that occurred.
2450 The name <tt>gsub</tt> comes from <i>Global SUBstitution</i>. 2449 The name <code>gsub</code> comes from <em>Global SUBstitution</em>.
2451 2450
2452 2451
2453 <p> 2452 <p>
2454 If <tt>repl</tt> is a string, then its value is used for replacement. 2453 If <code>repl</code> is a string, then its value is used for replacement.
2455 The character&nbsp;<tt>\</tt> works as an escape character. 2454 The character&nbsp;<code>\</code> works as an escape character.
2456 Any sequence in <tt>repl</tt> of the form <tt>$<i>d</i></tt>, 2455 Any sequence in <code>repl</code> of the form <code>$<em>d</em></code>,
2457 with <i>d</i> between 1 and 9, 2456 with <em>d</em> between 1 and 9,
2458 stands for the value of the <i>d</i>-th captured substring. 2457 stands for the value of the <em>d</em>-th captured substring.
2459 The sequence <tt>$0</tt> stands for the whole match. 2458 The sequence <code>$0</code> stands for the whole match.
2460 2459
2461 2460
2462 <p> 2461 <p>
2463 If <tt>repl</tt> is a table, then the table is queried for every match, 2462 If <code>repl</code> is a table, then the table is queried for every match,
2464 using the first capture as the key. 2463 using the first capture as the key.
2465 2464
2466 2465
2467 <p> 2466 <p>
2468 If <tt>repl</tt> is a function, then this function is called every time a 2467 If <code>repl</code> is a function, then this function is called every time a
2469 match occurs, with all captured substrings passed as arguments, 2468 match occurs, with all captured substrings passed as arguments,
2470 in order. 2469 in order.
2471 2470
2472 2471
2473 <p> 2472 <p>
2486 2485
2487 2486
2488 <p> 2487 <p>
2489 Here are some examples: 2488 Here are some examples:
2490 2489
2491 <p><tt><pre> 2490 <pre>
2492 x = String.gsub("hello world", [[(\w+)]], "$1 $1") 2491 x = String.gsub("hello world", [[(\w+)]], "$1 $1")
2493 --&gt; x="hello hello world world" 2492 --&gt; x="hello hello world world"
2494 2493
2495 x = String.gsub("hello world", [[\w+]], "$0 $0", 1) 2494 x = String.gsub("hello world", [[\w+]], "$0 $0", 1)
2496 --&gt; x="hello hello world" 2495 --&gt; x="hello hello world"
2504 --&gt; x="4+5 = 9" 2503 --&gt; x="4+5 = 9"
2505 2504
2506 local t = {name="lua", version="5.3"} 2505 local t = {name="lua", version="5.3"}
2507 x = String.gsub("$name-$version.tar.gz", [[\$(\w+)]], t) 2506 x = String.gsub("$name-$version.tar.gz", [[\$(\w+)]], t)
2508 --&gt; x="lua-5.3.tar.gz" 2507 --&gt; x="lua-5.3.tar.gz"
2509 </pre></tt></p> 2508 </pre>
2510 2509
2511 2510
2512 2511
2513 <h4 <%=heading_options%> ><a name="String.literal"><tt>String.literal (s)</tt></a></h4> 2512 <h4 heading><a name="String.literal"><code>String.literal (s)</code></a></h4>
2514 <p> 2513 <p>
2515 Returns a string which matches the literal string <tt>s</tt> 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)"><tt>Pattern.quote</tt></a>. 2514 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>.
2516 2515
2517 2516
2518 <h4 <%=heading_options%> ><a name="String.lower"><tt>String.lower (s)</tt></a></h4> 2517 <h4 heading><a name="String.lower"><code>String.lower (s)</code></a></h4>
2519 <p> 2518 <p>
2520 Receives a string and returns a copy of this string with all 2519 Receives a string and returns a copy of this string with all
2521 uppercase letters changed to lowercase. 2520 uppercase letters changed to lowercase.
2522 All other characters are left unchanged. 2521 All other characters are left unchanged.
2523 2522
2524 2523
2525 2524
2526 2525
2527 <h4 <%=heading_options%> ><a name="String.match"><tt>String.match (s, pattern [, init])</tt></a></h4> 2526 <h4 heading><a name="String.match"><code>String.match (s, pattern [, init])</code></a></h4>
2528 2527
2529 <p> 2528 <p>
2530 Looks for the first <i>match</i> of 2529 Looks for the first <em>match</em> of
2531 <tt>pattern</tt> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) in the string <tt>s</tt>. 2530 <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>.
2532 If it finds one, then <tt>match</tt> returns 2531 If it finds one, then <code>match</code> returns
2533 the captures from the pattern; 2532 the captures from the pattern;
2534 otherwise it returns <b>nil</b>. 2533 otherwise it returns <b>nil</b>.
2535 If <tt>pattern</tt> specifies no captures, 2534 If <code>pattern</code> specifies no captures,
2536 then the whole match is returned. 2535 then the whole match is returned.
2537 A third, optional numerical argument <tt>init</tt> specifies 2536 A third, optional numerical argument <code>init</code> specifies
2538 where to start the search; 2537 where to start the search;
2539 its default value is&nbsp;1 and can be negative. 2538 its default value is&nbsp;1 and can be negative.
2540 2539
2541 2540
2542 <h4 <%=heading_options%> ><a name="String.matches"><tt>String.matches (s, pattern)</tt></a></h4> 2541 <h4 heading><a name="String.matches"><code>String.matches (s, pattern)</code></a></h4>
2543 <p> 2542 <p>
2544 Returns a boolean indicating whether the entire string <tt>s</tt> matches <tt>pattern</tt>. 2543 Returns a boolean indicating whether the entire string <code>s</code> matches <code>pattern</code>.
2545 2544
2546 2545
2547 2546
2548 <h4 <%=heading_options%> ><a name="String.rep"><tt>String.rep (s, n [, sep])</tt></a></h4> 2547 <h4 heading><a name="String.rep"><code>String.rep (s, n [, sep])</code></a></h4>
2549 <p> 2548 <p>
2550 Returns a string that is the concatenation of <tt>n</tt> copies of 2549 Returns a string that is the concatenation of <code>n</code> copies of
2551 the string <tt>s</tt> separated by the string <tt>sep</tt>. 2550 the string <code>s</code> separated by the string <code>sep</code>.
2552 The default value for <tt>sep</tt> is the empty string 2551 The default value for <code>sep</code> is the empty string
2553 (that is, no separator). 2552 (that is, no separator).
2554 Returns the empty string if <tt>n</tt> is not positive. 2553 Returns the empty string if <code>n</code> is not positive.
2555 2554
2556 2555
2557 2556
2558 2557
2559 <h4 <%=heading_options%> ><a name="String.reverse"><tt>String.reverse (s)</tt></a></h4> 2558 <h4 heading><a name="String.reverse"><code>String.reverse (s)</code></a></h4>
2560 <p> 2559 <p>
2561 Returns a string that is the string <tt>s</tt> reversed. 2560 Returns a string that is the string <code>s</code> reversed.
2562 2561
2563 2562
2564 2563
2565 2564
2566 <h4 <%=heading_options%> ><a name="String.sub"><tt>String.sub (s, i [, j])</tt></a></h4> 2565 <h4 heading><a name="String.sub"><code>String.sub (s, i [, j])</code></a></h4>
2567 2566
2568 <p> 2567 <p>
2569 Returns the substring of <tt>s</tt> that 2568 Returns the substring of <code>s</code> that
2570 starts at <tt>i</tt> and continues until <tt>j</tt>; 2569 starts at <code>i</code> and continues until <code>j</code>;
2571 <tt>i</tt> and <tt>j</tt> can be negative. 2570 <code>i</code> and <code>j</code> can be negative.
2572 If <tt>j</tt> is absent, then it is assumed to be equal to -1 2571 If <code>j</code> is absent, then it is assumed to be equal to -1
2573 (which is the same as the string length). 2572 (which is the same as the string length).
2574 In particular, 2573 In particular,
2575 the call <tt>string.sub(s,1,j)</tt> returns a prefix of <tt>s</tt> 2574 the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
2576 with length <tt>j</tt>, 2575 with length <code>j</code>,
2577 and <tt>string.sub(s, -i)</tt> returns a suffix of <tt>s</tt> 2576 and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code>
2578 with length <tt>i</tt>. 2577 with length <code>i</code>.
2579 2578
2580 2579
2581 <p> 2580 <p>
2582 If, after the translation of negative indices, 2581 If, after the translation of negative indices,
2583 <tt>i</tt> is less than 1, 2582 <code>i</code> is less than 1,
2584 it is corrected to 1. 2583 it is corrected to 1.
2585 If <tt>j</tt> is greater than the string length, 2584 If <code>j</code> is greater than the string length,
2586 it is corrected to that length. 2585 it is corrected to that length.
2587 If, after these corrections, 2586 If, after these corrections,
2588 <tt>i</tt> is greater than <tt>j</tt>, 2587 <code>i</code> is greater than <code>j</code>,
2589 the function returns the empty string. 2588 the function returns the empty string.
2590 2589
2591 2590
2592 2591
2593 <h4 <%=heading_options%> ><a name="String.to_binary"><tt>String.to_binary (s)</tt></a></h4> 2592 <h4 heading><a name="String.to_binary"><code>String.to_binary (s)</code></a></h4>
2594 2593
2595 <p> 2594 <p>
2596 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()"><tt>String.getBytes</tt></a>. 2595 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>.
2597 2596
2598 2597
2599 2598
2600 <h4 <%=heading_options%> ><a name="String.to_number"><tt>String.to_number (s [, base])</tt></a></h4> 2599 <h4 heading><a name="String.to_number"><code>String.to_number (s [, base])</code></a></h4>
2601 2600
2602 <p> 2601 <p>
2603 When called with no <tt>base</tt>, 2602 When called with no <code>base</code>,
2604 <tt>to_number</tt> tries to convert its argument to a number. 2603 <code>to_number</code> tries to convert its argument to a number.
2605 If the argument is 2604 If the argument is
2606 a string convertible to a number, 2605 a string convertible to a number,
2607 then <tt>to_number</tt> returns this number; 2606 then <code>to_number</code> returns this number;
2608 otherwise, it returns <b>nil</b>. 2607 otherwise, it returns <b>nil</b>.
2609 2608
2610 The conversion of strings can result in integers or floats. 2609 The conversion of strings can result in integers or floats.
2611 2610
2612 2611
2613 <p> 2612 <p>
2614 When called with <tt>base</tt>, 2613 When called with <code>base</code>,
2615 then <tt>s</tt> must be a string to be interpreted as 2614 then <code>s</code> must be a string to be interpreted as
2616 an integer numeral in that base. 2615 an integer numeral in that base.
2617 In bases above&nbsp;10, the letter '<tt>A</tt>' (in either upper or lower case) 2616 In bases above&nbsp;10, the letter '<code>A</code>' (in either upper or lower case)
2618 represents&nbsp;10, '<tt>B</tt>' represents&nbsp;11, and so forth, 2617 represents&nbsp;10, '<code>B</code>' represents&nbsp;11, and so forth,
2619 with '<tt>Z</tt>' representing 35. 2618 with '<code>Z</code>' representing 35.
2620 If the string <tt>s</tt> is not a valid numeral in the given base, 2619 If the string <code>s</code> is not a valid numeral in the given base,
2621 the function returns <b>nil</b>. 2620 the function returns <b>nil</b>.
2622 2621
2623 2622
2624 2623
2625 <h4 <%=heading_options%> ><a name="String.trim"><tt>String.trim (s)</tt></a></h4> 2624 <h4 heading><a name="String.trim"><code>String.trim (s)</code></a></h4>
2626 2625
2627 <p> 2626 <p>
2628 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()"><tt>String.trim</tt></a>. 2627 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>.
2629 2628
2630 2629
2631 2630
2632 2631
2633 <h4 <%=heading_options%> ><a name="String.unicode"><tt>String.unicode (s [, i [, j]])</tt></a></h4> 2632 <h4 heading><a name="String.unicode"><code>String.unicode (s [, i [, j]])</code></a></h4>
2634 2633
2635 <p> 2634 <p>
2636 Returns the internal numerical codes of the characters <tt>s[i]</tt>, 2635 Returns the internal numerical codes of the characters <code>s[i]</code>,
2637 <tt>s[i+1]</tt>, ..., <tt>s[j]</tt>. 2636 <code>s[i+1]</code>, ..., <code>s[j]</code>.
2638 The default value for <tt>i</tt> is&nbsp;1; 2637 The default value for <code>i</code> is&nbsp;1;
2639 the default value for <tt>j</tt> is&nbsp;<tt>i</tt>. 2638 the default value for <code>j</code> is&nbsp;<code>i</code>.
2640 These indices are corrected 2639 These indices are corrected
2641 following the same rules of function <a href="#String.sub"><tt>String.sub</tt></a>. 2640 following the same rules of function <a href="#String.sub"><code>String.sub</code></a>.
2642 2641
2643 2642
2644 2643
2645 2644
2646 2645
2647 <h4 <%=heading_options%> ><a name="String.upper"><tt>String.upper (s)</tt></a></h4> 2646 <h4 heading><a name="String.upper"><code>String.upper (s)</code></a></h4>
2648 <p> 2647 <p>
2649 Receives a string and returns a copy of this string with all 2648 Receives a string and returns a copy of this string with all
2650 lowercase letters changed to uppercase. 2649 lowercase letters changed to uppercase.
2651 All other characters are left unchanged. 2650 All other characters are left unchanged.
2652 The definition of what a lowercase letter is depends on the current locale. 2651 The definition of what a lowercase letter is depends on the current locale.
4595 Last change: minor edit 4594 Last change: minor edit
4596 --> 4595 -->
4597 4596
4598 </div> 4597 </div>
4599 4598
4600 <% Html.simply_html_body_bottom() %>
4601 </body> 4599 </body>
4602 </html> 4600 </html>
4603 <% 4601 <%
4604 end 4602 end