Mercurial Hosting > luan

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

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
manual work
author Franklin Schmidt <fschmidt@gmail.com>
date Tue, 05 Apr 2022 21:50:24 -0600
parents
children 2968e43cdd44
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 local show_toc = Shared.show_toc or error()
9 local show_content = Shared.show_content or error()
10
11
12 local content = {
13 intro = {
14 title = "Introduction"
15 content = function()
16 %>
17 <p>
18 Luan is a high level programming language based on <a href="http://www.lua.org">Lua</a>. A great strength of Lua is its simplicity and Luan takes this even further, being even simpler than Lua. The goal is to provide a simple programming language for the casual programmer with as few concepts as possible so that one can quickly learn the language and then easily understand any code written in Luan.
19 </p>
20
21 <p>
22 Luan is implemented in Java and is tightly coupled with Java. So it makes a great scripting language for Java programmers.
23 </p>
24
25 <p>
26 Unlike Lua which is meant to be embedded, Luan is meant to be a full scripting language. This done not by adding features to Luan, but rather by providing a complete set of libraries.
27 </p>
28 <%
29 end
30 }
31 basic = {
32 title = "Basic Concepts"
33 content = function()
34 %>
35 <p>
36 This section describes the basic concepts of the language.
37 </p>
38 <%
39 end
40 subs = {
41 types = {
42 title = "Values and Types"
43 content = function()
44 %>
45 <p>
46 Luan is a <em>dynamically typed language</em>.
47 This means that
48 variables do not have types; only values do.
49 There are no type definitions in the language.
50 All values carry their own type.
51 </p>
52
53 <p>
54 All values in Luan are <em>first-class values</em>.
55 This means that all values can be stored in variables,
56 passed as arguments to other functions, and returned as results.
57 </p>
58
59 <p>
60 There are eight basic types in Luan:
61 <em>nil</em>, <em>boolean</em>, <em>number</em>,
62 <em>string</em>, <em>binary</em>, <em>function</em>, <em>java</em>,
63 and <em>table</em>.
64 <em>Nil</em> is the type of the value <b>nil</b>,
65 whose main property is to be different from any other value;
66 it usually represents the absence of a useful value.
67 <em>Nil</em> is implemented as the Java value <em>null</em>.
68 <em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>.
69 <em>Boolean</em> is implemented as the Java class <em>Boolean</em>.
70 <em>Number</em> represents both
71 integer numbers and real (floating-point) numbers.
72 <em>Number</em> is implemented as the Java class <em>Number</em>. Any Java subclass of <em>Number</em> is allowed and this is invisible to the Luan user. Operations on numbers follow the same rules of
73 the underlying Java implementation.
74 <em>String</em> is implemented as the Java class <em>String</em>.
75 <em>Binary</em> is implemented as the Java type <em>byte[]</em>.
76 </p>
77
78 <p>
79 Luan can call (and manipulate) functions written in Luan and
80 functions written in Java (see <a href="#fn_calls">Function Calls</a>).
81 Both are represented by the type <em>function</em>.
82 </p>
83
84 <p>
85 The type <em>java</em> is provided to allow arbitrary Java objects to
86 be stored in Luan variables.
87 A <em>java</em> value is a Java object that isn't one of the standard Luan types.
88 Java values have no predefined operations in Luan,
89 except assignment and identity test.
90 Java values are useful when Java access is enabled in Luan.
91 </p>
92
93 <p>
94 The type <em>table</em> implements associative arrays,
95 that is, arrays that can be indexed not only with numbers,
96 but with any Luan value except <b>nil</b>.
97 Tables can be <em>heterogeneous</em>;
98 that is, they can contain values of all types (except <b>nil</b>).
99 Any key with value <b>nil</b> is not considered part of the table.
100 Conversely, any key that is not part of a table has
101 an associated value <b>nil</b>.
102 </p>
103
104 <p>
105 Tables are the sole data-structuring mechanism in Luan;
106 they can be used to represent ordinary arrays, sequences,
107 symbol tables, sets, records, graphs, trees, etc.
108 To represent records, Luan uses the field name as an index.
109 The language supports this representation by
110 providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>.
111 There are several convenient ways to create tables in Luan
112 (see <a href="#constructors">Table Constructors</a>).
113 </p>
114
115 <p>
116 We use the term <em>sequence</em> to denote a table where
117 the set of all positive numeric keys is equal to {1..<em>n</em>}
118 for some non-negative integer <em>n</em>,
119 which is called the length of the sequence (see <a href="#length">The Length Operator</a>).
120 </p>
121
122 <p>
123 Like indices,
124 the values of table fields can be of any type.
125 In particular,
126 because functions are first-class values,
127 table fields can contain functions.
128 Thus tables can also carry <em>methods</em> (see <a href="#fn_def">Function Definitions</a>).
129 </p>
130
131 <p>
132 The indexing of tables follows
133 the definition of raw equality in the language.
134 The expressions <code>a[i]</code> and <code>a[j]</code>
135 denote the same table element
136 if and only if <code>i</code> and <code>j</code> are raw equal
137 (that is, equal without metamethods).
138 In particular, floats with integral values
139 are equal to their respective integers
140 (e.g., <code>1.0 == 1</code>).
141 </p>
142
143 <p>
144 Luan values are <em>objects</em>:
145 variables do not actually <em>contain</em> values,
146 only <em>references</em> to them.
147 Assignment, parameter passing, and function returns
148 always manipulate references to values;
149 these operations do not imply any kind of copy.
150 </p>
151
152 <p>
153 The library function <a href="#Luan.type"><code>Luan.type</code></a> returns a string describing the type
154 of a given value.
155 </p>
156 <%
157 end
158 }
159 env = {
160 title = "Environments"
161 content = function()
162 %>
163 <p>
164 The environment of a chunk starts with only one local variable: <code><a href="#require">require</a></code>. This function is used to load and access libraries and other modules. All other variables must be added to the environment using <a href="http://localhost:8080/manual.html#local_stmt">local declarations</a>.
165 </p>
166
167 <p>
168 As will be discussed in <a href="#vars">Variables</a> and <a href=#assignment">Assignment</a>,
169 any reference to a free name
170 (that is, a name not bound to any declaration) <code>var</code>
171 can be syntactically translated to <code>_ENV.var</code> if <code>_ENV</code> is defined.
172 </p>
173 <%
174 end
175 }
176 error = {
177 title = "Error Handling"
178 content = function()
179 %>
180 <p>
181 Luan code can explicitly generate an error by calling the
182 <a href="#Luan.error"><code>error</code></a> function.
183 If you need to catch errors in Luan,
184 you can use the <a href="#try">Try Statement</code></a>.
185 </p>
186
187 <p>
188 Whenever there is an error,
189 an <em>error table</em>
190 is propagated with information about the error.
191 See <a href="#Luan.new_error"><code>Luan.new_error</code></a>.
192 </p>
193 <%
194 end
195 }
196 meta = {
197 title = "Metatables and Metamethods"
198 content = function()
199 %>
200 <p>
201 Every table in Luan can have a <em>metatable</em>.
202 This <em>metatable</em> is an ordinary Luan table
203 that defines the behavior of the original value
204 under certain special operations.
205 You can change several aspects of the behavior
206 of operations over a value by setting specific fields in its metatable.
207 For instance, when a table is the operand of an addition,
208 Luan checks for a function in the field "<code>__add</code>" of the table's metatable.
209 If it finds one,
210 Luan calls this function to perform the addition.
211 </p>
212
213 <p>
214 The keys in a metatable are derived from the <em>event</em> names;
215 the corresponding values are called <ii>metamethods</em>.
216 In the previous example, the event is <code>"add"</code>
217 and the metamethod is the function that performs the addition.
218 </p>
219
220 <p>
221 You can query the metatable of any table
222 using the <a href="#Luan.get_metatable"><code>get_metatable</code></a> function.
223 </p>
224
225 <p>
226 You can replace the metatable of tables
227 using the <a href="#Luan.set_metatable"><code>set_metatable</code></a> function.
228 </p>
229
230 <p>
231 A metatable controls how a table behaves in
232 arithmetic operations, bitwise operations,
233 order comparisons, concatenation, length operation, calls, and indexing.
234 </p>
235
236 <p>
237 A detailed list of events controlled by metatables is given next.
238 Each operation is identified by its corresponding event name.
239 The key for each event is a string with its name prefixed by
240 two underscores, '<code>__</code>';
241 for instance, the key for operation "add" is the
242 string "<code>__add</code>".
243 Note that queries for metamethods are always raw;
244 the access to a metamethod does not invoke other metamethods.
245 You can emulate how Luan queries a metamethod for an object <code>obj</code>
246 with the following code:
247 </p>
248
249 <pre>
250 raw_get(get_metatable(obj) or {}, "__" .. event_name)
251 </pre>
252
253 <p>
254 Here are the events:
255 </p>
256
257 <ul>
258
259 <li><p>
260 <b>"add": </b>
261 the <code>+</code> operation.
262
263 If any operand for an addition is a table,
264 Luan will try to call a metamethod.
265 First, Luan will check the first operand (even if it is valid).
266 If that operand does not define a metamethod for the "<code>__add</code>" event,
267 then Luan will check the second operand.
268 If Luan can find a metamethod,
269 it calls the metamethod with the two operands as arguments,
270 and the result of the call
271 (adjusted to one value)
272 is the result of the operation.
273 Otherwise,
274 it raises an error.
275 </p></li>
276
277 <li><p>
278 <b>"sub": </b>
279 the <code>-</code> operation.
280 Behavior similar to the "add" operation.
281 </li>
282
283 <li><p><b>"mul": </b>
284 the <code>*</code> operation.
285 Behavior similar to the "add" operation.
286 </p></li>
287
288 <li><p>
289 <b>"div": </b>
290 the <code>/</code> operation.
291 Behavior similar to the "add" operation.
292 </p></li>
293
294 <li><p>
295 <b>"mod": </b>
296 the <code>%</code> operation.
297 Behavior similar to the "add" operation.
298 </p></li>
299
300 <li><p>
301 <b>"pow": </b>
302 the <code>^</code> (exponentiation) operation.
303 Behavior similar to the "add" operation.
304 </p></li>
305
306 <li><p>
307 <b>"unm": </b>
308 the <code>-</code> (unary minus) operation.
309 Behavior similar to the "add" operation.
310 </p></li>
311
312 <li><p>
313 <b>"concat": </b>
314 the <code>..</code> (concatenation) operation.
315 Behavior similar to the "add" operation.
316 </p></li>
317
318 <li><p>
319 <b>"len": </b>
320 the <code>#</code> (length) operation.
321 If there is a metamethod,
322 Luan calls it with the object as argument,
323 and the result of the call
324 (always adjusted to one value)
325 is the result of the operation.
326 If there is no metamethod but the object is a table,
327 then Luan uses the table length operation (see <a href="#length">The Length Operator</a>).
328 Otherwise, Luan raises an error.
329 </p></li>
330
331 <li><p>
332 <b>"eq": </b>
333 the <code>==</code> (equal) operation.
334 Behavior similar to the "add" operation,
335 except that Luan will try a metamethod only when the values
336 being compared are both tables
337 and they are not primitively equal.
338 The result of the call is always converted to a boolean.
339 </p></li>
340
341 <li><p>
342 <b>"lt": </b>
343 the <code>&lt;</code> (less than) operation.
344 Behavior similar to the "add" operation.
345 The result of the call is always converted to a boolean.
346 </p></li>
347
348 <li><p>
349 <b>"le": </b>
350 the <code>&lt;=</code> (less equal) operation.
351 Unlike other operations,
352 The less-equal operation can use two different events.
353 First, Luan looks for the "<code>__le</code>" metamethod in both operands,
354 like in the "lt" operation.
355 If it cannot find such a metamethod,
356 then it will try the "<code>__lt</code>" event,
357 assuming that <code>a &lt;= b</code> is equivalent to <code>not (b &lt; a)</code>.
358 As with the other comparison operators,
359 the result is always a boolean.
360 </p></li>
361
362 <li>
363 <p>
364 <b>"index": </b>
365 The indexing access <code>table[key]</code>.
366 This event happens
367 when <code>key</code> is not present in <code>table</code>.
368 The metamethod is looked up in <code>table</code>.
369 </p>
370
371 <p>
372 Despite the name,
373 the metamethod for this event can be any type.
374 If it is a function,
375 it is called with <code>table</code> and <code>key</code> as arguments.
376 Otherwise
377 the final result is the result of indexing this metamethod object with <code>key</code>.
378 (This indexing is regular, not raw,
379 and therefore can trigger another metamethod if the metamethod object is a table.)
380 </p>
381 </li>
382
383 <li>
384 <p>
385 <b>"new_index": </b>
386 The indexing assignment <code>table[key] = value</code>.
387 Like the index event,
388 this event happens when
389 when <code>key</code> is not present in <code>table</code>.
390 The metamethod is looked up in <code>table</code>.
391 </p>
392
393 <p>
394 Like with indexing,
395 the metamethod for this event can be either a function or a table.
396 If it is a function,
397 it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments.
398 If it is a table,
399 Luan does an indexing assignment to this table with the same key and value.
400 (This assignment is regular, not raw,
401 and therefore can trigger another metamethod.)
402 </p>
403
404 <p>
405 Whenever there is a "new_index" metamethod,
406 Luan does not perform the primitive assignment.
407 (If necessary,
408 the metamethod itself can call <a href="#Luan.raw_set"><code>raw_set</code></a>
409 to do the assignment.)
410 </p>
411 </li>
412
413 <li><p>
414 <b>"gc":</b>
415 This is when a table is garbage collected. When the table's <a href="https://docs.oracle.com/javase/7/docs/api/java/lang/Object.html#finalize()">finalize</a> method is called by the Java garbage collector, if there is a "<code>__gc</code>" metamethod then it is called with the table as a parameter.
416 </p></li>
417
418 </ul>
419 <%
420 end
421 }
422 gc = {
423 title = "Garbage Collection"
424 content = function()
425 %>
426 <p>
427 Luan uses Java's garbage collection.
428 </p>
429 <%
430 end
431 }
432 }
433 }
434 lang = {
435 title = "The Language"
436 content = function()
437 %>
438 <p>
439 This section describes the lexis, the syntax, and the semantics of Luan.
440 In other words,
441 this section describes
442 which tokens are valid,
443 how they can be combined,
444 and what their combinations mean.
445 </p>
446
447 <p>
448 Language constructs will be explained using the usual extended BNF notation,
449 in which
450 {<em>a</em>}&nbsp;means&nbsp;0 or more <em>a</em>'s, and
451 [<em>a</em>]&nbsp;means an optional <em>a</em>.
452 Non-terminals are shown like non-terminal,
453 keywords are shown like <b>kword</b>,
454 and other terminal symbols are shown like &lsquo;<b>=</b>&rsquo;.
455 The complete syntax of Luan can be found in <a href="#9">&sect;9</a>
456 at the end of this manual.
457 </p>
458 <%
459 end
460 subs = {
461 lex = {
462 title = "Lexical Conventions"
463 content = function()
464 %>
465 <p>
466 Luan ignores spaces and comments
467 between lexical elements (tokens),
468 except as delimiters between names and keywords.
469 Luan considers the end of a line to be the end of a statement. This catches errors and encourages readability. If you want to continue a statement on another line, you can use a backslash followed by a newline which will be treated as white space.
470 </p>
471
472 <p>
473 <em>Names</em>
474 (also called <em>identifiers</em>)
475 in Luan can be any string of letters,
476 digits, and underscores,
477 not beginning with a digit.
478 Identifiers are used to name variables, table fields, and labels.
479 </p>
480
481 <p>
482 The following <em>keywords</em> are reserved
483 and cannot be used as names:
484 </p>
485
486 <p keywords>
487 <span>and</span>
488 <span>break</span>
489 <span>catch</span>
490 <span>continue</span>
491 <span>do</span>
492 <span>else</span>
493 <span>elseif</span>
494 <span>end_do</span>
495 <span>end_for</span>
496 <span>end_function</span>
497 <span>end_if</span>
498 <span>end_try</span>
499 <span>end_while</span>
500 <span>false</span>
501 <span>finally</span>
502 <span>for</span>
503 <span>function</span>
504 <span>if</span>
505 <span>in</span>
506 <span>local</span>
507 <span>nil</span>
508 <span>not</span>
509 <span>or</span>
510 <span>repeat</span>
511 <span>return</span>
512 <span>then</span>
513 <span>true</span>
514 <span>try</span>
515 <span>until</span>
516 <span>while</span>
517 </p>
518
519 <p>
520 Luan is a case-sensitive language:
521 <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
522 are two different, valid names.
523 </p>
524
525 <p>
526 The following strings denote other tokens:
527 </p>
528
529 <pre>
530 + - * / % ^ #
531 &amp; ~ | &lt;&lt; &gt;&gt; //
532 == ~= &lt;= &gt;= &lt; &gt; =
533 ( ) { } [ ] ::
534 ; : , . .. ...
535 </pre>
536
537 <p>
538 <em>Literal strings</em>
539 can be delimited by matching single or double quotes,
540 and can contain the following C-like escape sequences:
541 '<code>\a</code>' (bell),
542 '<code>\b</code>' (backspace),
543 '<code>\f</code>' (form feed),
544 '<code>\n</code>' (newline),
545 '<code>\r</code>' (carriage return),
546 '<code>\t</code>' (horizontal tab),
547 '<code>\v</code>' (vertical tab),
548 '<code>\\</code>' (backslash),
549 '<code>\"</code>' (quotation mark [double quote]),
550 and '<code>\'</code>' (apostrophe [single quote]).
551 A backslash followed by a real newline
552 results in a newline in the string.
553 The escape sequence '<code>\z</code>' skips the following span
554 of white-space characters,
555 including line breaks;
556 it is particularly useful to break and indent a long literal string
557 into multiple lines without adding the newlines and spaces
558 into the string contents.
559 </p>
560
561 <p>
562 Luan can specify any character in a literal string by its numerical value.
563 This can be done
564 with the escape sequence <code>\x<em>XX</em></code>,
565 where <em>XX</em> is a sequence of exactly two hexadecimal digits,
566 or with the escape sequence <code>\u<em>XXXX</em></code>,
567 where <em>XXXX</em> is a sequence of exactly four hexadecimal digits,
568 or with the escape sequence <code>\<em>ddd</em></code>,
569 where <em>ddd</em> is a sequence of up to three decimal digits.
570 (Note that if a decimal escape sequence is to be followed by a digit,
571 it must be expressed using exactly three digits.)
572 </p>
573
574 <p>
575 Literal strings can also be defined using a long format
576 enclosed by <em>long brackets</em>.
577 We define an <em>opening long bracket of level <em>n</em></em> as an opening
578 square bracket followed by <em>n</em> equal signs followed by another
579 opening square bracket.
580 So, an opening long bracket of level 0 is written as <code>[[</code>,
581 an opening long bracket of level 1 is written as <code>[=[</code>,
582 and so on.
583 A <em>closing long bracket</em> is defined similarly;
584 for instance,
585 a closing long bracket of level 4 is written as <code>]====]</code>.
586 A <em>long literal</em> starts with an opening long bracket of any level and
587 ends at the first closing long bracket of the same level.
588 It can contain any text except a closing bracket of the same level.
589 Literals in this bracketed form can run for several lines,
590 do not interpret any escape sequences,
591 and ignore long brackets of any other level.
592 Any kind of end-of-line sequence
593 (carriage return, newline, carriage return followed by newline,
594 or newline followed by carriage return)
595 is converted to a simple newline.
596 </p>
597
598 <p>
599 Any character in a literal string not
600 explicitly affected by the previous rules represents itself.
601 However, Luan opens files for parsing in text mode,
602 and the system file functions may have problems with
603 some control characters.
604 So, it is safer to represent
605 non-text data as a quoted literal with
606 explicit escape sequences for non-text characters.
607 </p>
608
609 <p>
610 For convenience,
611 when the opening long bracket is immediately followed by a newline,
612 the newline is not included in the string.
613 As an example
614 the five literal strings below denote the same string:
615 </p>
616
617 <pre>
618 a = 'alo\n123"'
619 a = "alo\n123\""
620 a = '\97lo\10\04923"'
621 a = [[alo
622 123"]]
623 a = [==[
624 alo
625 123"]==]
626 </pre>
627
628 <p>
629 A <em>numerical constant</em> (or <em>numeral</em>)
630 can be written with an optional fractional part
631 and an optional decimal exponent,
632 marked by a letter '<code>e</code>' or '<code>E</code>'.
633 Luan also accepts hexadecimal constants,
634 which start with <code>0x</code> or <code>0X</code>.
635 Hexadecimal constants also accept an optional fractional part
636 plus an optional binary exponent,
637 marked by a letter '<code>p</code>' or '<code>P</code>'.
638 A numeric constant with a fractional dot or an exponent
639 denotes a float;
640 otherwise it denotes an integer.
641 Examples of valid integer constants are
642 </p>
643
644 <pre>
645 3 345 0xff 0xBEBADA
646 </pre>
647
648 <p>
649 Examples of valid float constants are
650 </p>
651
652 <pre>
653 3.0 3.1416 314.16e-2 0.31416E1 34e1
654 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1
655 </pre>
656
657 <p>
658 A <em>comment</em> starts with a double hyphen (<code>--</code>)
659 anywhere outside a string.
660 If the text immediately after <code>--</code> is not an opening long bracket,
661 the comment is a <em>short comment</em>,
662 which runs until the end of the line.
663 Otherwise, it is a <em>long comment</em>,
664 which runs until the corresponding closing long bracket.
665 Long comments are frequently used to disable code temporarily.
666 </p>
667 <%
668 end
669 }
670 vars = {
671 title = "Variables"
672 content = function()
673 %>
674 <p>
675 Variables are places that store values.
676 There are three kinds of variables in Luan:
677 global variables, local variables, and table fields.
678 </p>
679
680 <p>
681 A single name can denote a global variable or a local variable
682 (or a function's formal parameter,
683 which is a particular kind of local variable):
684 </p>
685
686 <pre>
687 var ::= Name
688 </pre>
689
690 <p>
691 Name denotes identifiers, as defined in <a href="#lex">Lexical Conventions</a>.
692 </p>
693
694 <p>
695 Local variables are <em>lexically scoped</em>:
696 local variables can be freely accessed by functions
697 defined inside their scope (see <a href="#visibility">Visibility Rules</a>).
698 </p>
699
700 <p>
701 Before the first assignment to a variable, its value is <b>nil</b>.
702 </p>
703
704 <p>
705 Square brackets are used to index a table:
706 </p>
707
708 <pre>
709 var ::= prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo;
710 </pre>
711
712 <p>
713 The meaning of accesses to table fields can be changed via metatables.
714 An access to an indexed variable <code>t[i]</code> is equivalent to
715 a call <code>gettable_event(t,i)</code>.
716 (See <a href="#meta">Metatables and Metamethods</a> for a complete description of the
717 <code>gettable_event</code> function.
718 This function is not defined or callable in Luan.
719 We use it here only for explanatory purposes.)
720 </p>
721
722 <p>
723 The syntax <code>var.Name</code> is just syntactic sugar for
724 <code>var["Name"]</code>:
725 </p>
726
727 <pre>
728 var ::= prefixexp &lsquo;<b>.</b>&rsquo; Name
729 </pre>
730
731 <p>
732 Global variables are not available by default. To enable global variable, you must define <code>_ENV</code> as a local variable whose value is a table. If <code>_ENV</code> is not defined, then an unrecognized variable name will produce a compile error. If <code>_ENV</code> is defined then an access to an unrecognized variable name will be consider a global variable. So then an acces to global variable <code>x</code>
733 is equivalent to <code>_ENV.x</code>.
734 Due to the way that chunks are compiled,
735 <code>_ENV</code> is never a global name (see <a href="#env">Environments</a>).
736 </p>
737 <%
738 end
739 }
740 stmt = {
741 title = "Statements"
742 content = function()
743 %>
744 <p>
745 Luan supports an almost conventional set of statements,
746 similar to those in Pascal or C.
747 This set includes
748 assignments, control structures, function calls,
749 and variable declarations.
750 </p>
751 <%
752 end
753 subs = {
754 blocks = {
755 title = "Blocks"
756 content = function()
757 %>
758 <p>
759 A block is a list of statements,
760 which are executed sequentially:
761 </p>
762
763 <pre>
764 block ::= {stat}
765 </pre>
766
767 <p>
768 Luan has <em>empty statements</em>
769 that allow you to separate statements with semicolons,
770 start a block with a semicolon
771 or write two semicolons in sequence:
772 </p>
773
774 <pre>
775 stat ::= &lsquo;<b>;</b>&rsquo;
776 </pre>
777
778 <p>
779 A block can be explicitly delimited to produce a single statement:
780 </p>
781
782 <pre>
783 stat ::= <b>do</b> block end_do
784 end_do ::= <b>end_do</b> | <b>end</b>
785 </pre>
786
787 <p>
788 Explicit blocks are useful
789 to control the scope of variable declarations.
790 Explicit blocks are also sometimes used to
791 add a <b>return</b> statement in the middle
792 of another block (see <a href="#control">Control Structures</a>).
793 </p>
794 <%
795 end
796 }
797 chunks = {
798 title = "Chunks"
799 content = function()
800 %>
801 <p>
802 The unit of compilation of Luan is called a <em>chunk</em>.
803 Syntactically,
804 a chunk is simply a block:
805 </p>
806
807 <pre>
808 chunk ::= block
809 </pre>
810
811 <p>
812 Luan handles a chunk as the body of an anonymous function
813 with a variable number of arguments
814 (see <a href="#fn_def">Function Definitions</a>).
815 As such, chunks can define local variables,
816 receive arguments, and return values.
817 </p>
818
819 <p>
820 A chunk can be stored in a file or in a string inside the host program.
821 To execute a chunk,
822 Luan first <em>loads</em> it,
823 compiling the chunk's code,
824 and then Luan executes the compiled code.
825 </p>
826 <%
827 end
828 }
829 assignment = {
830 title = "Assignment"
831 content = function()
832 %>
833 <p>
834 Luan allows multiple assignments.
835 Therefore, the syntax for assignment
836 defines a list of variables on the left side
837 and a list of expressions on the right side.
838 The elements in both lists are separated by commas:
839 </p>
840
841 <pre>
842 stat ::= varlist &lsquo;<b>=</b>&rsquo; explist
843 varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
844 explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
845 </pre>
846
847 <p>
848 Expressions are discussed in <a href="#expressions">Expressions</a>.
849 </p>
850
851 <p>
852 Before the assignment,
853 the list of values is <em>adjusted</em> to the length of
854 the list of variables.
855 If there are more values than needed,
856 the excess values are thrown away.
857 If there are fewer values than needed,
858 the list is extended with as many <b>nil</b>'s as needed.
859 If the list of expressions ends with a function call,
860 then all values returned by that call enter the list of values,
861 before the adjustment
862 (except when the call is enclosed in parentheses; see <a href="#expressions">Expressions</a>).
863 </p>
864
865 <p>
866 The assignment statement first evaluates all its expressions
867 and only then the assignments are performed.
868 Thus the code
869 </p>
870
871 <pre>
872 i = 3
873 i, a[i] = i+1, 20
874 </pre>
875
876 <p>
877 sets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
878 because the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
879 before it is assigned&nbsp;4.
880 Similarly, the line
881 </p>
882
883 <pre>
884 x, y = y, x
885 </pre>
886
887 <p>
888 exchanges the values of <code>x</code> and <code>y</code>,
889 and
890 </p>
891
892 <pre>
893 x, y, z = y, z, x
894 </pre>
895
896 <p>
897 cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>.
898 </p>
899
900 <p>
901 The meaning of assignments to global variables
902 and table fields can be changed via metatables.
903 An assignment to an indexed variable <code>t[i] = val</code> is equivalent to
904 <code>settable_event(t,i,val)</code>.
905 (See <a href="#meta">Metatables and Metamethods</a> for a complete description of the
906 <code>settable_event</code> function.
907 This function is not defined or callable in Luan.
908 We use it here only for explanatory purposes.)
909 </p>
910
911 <p>
912 An assignment to a global name <code>x = val</code>
913 is equivalent to the assignment
914 <code>_ENV.x = val</code> (see <a href="#env">Environments</a>).
915 Global names are only available when <code>_ENV</code> is defined.
916 </p>
917 <%
918 end
919 }
920 }
921 }
922 }
923 }
924 }
925
926
927 return function()
928 Io.stdout = Http.response.text_writer()
929 %>
930 <!doctype html>
931 <html>
932 <head>
933 <% head() %>
934 <title>Luan Reference Manual</title>
935 <style>
936 p[keywords] {
937 font-family: monospace;
938 margin-left: 40px;
939 max-width: 700px;
940 }
941 p[keywords] span {
942 display: inline-block;
943 width: 100px;
944 }
945 </style>
946 </head>
947 <body>
948 <% docs_header() %>
949 <div content>
950 <h1><a href="manual.html">Luan Reference Manual</a></h1>
951 <p small>
952 Original copyright &copy; 2015 Lua.org, PUC-Rio.
953 Freely available under the terms of the
954 <a href="http://www.lua.org/license.html">Lua license</a>.
955 Modified for Luan.
956 </p>
957 <hr>
958 <h2>Contents</h2>
959 <div toc>
960 <% show_toc(content) %>
961 </div>
962 <hr>
963 <% show_content(content,2) %>
964 </div>
965 </body>
966 </html>
967 <%
968 end