comparison website/src/manual_old.html.luan @ 1656:540bf2343078

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