|
1656
|
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><</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><=</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 <= b</code> is equivalent to <code>not (b < 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>} means 0 or more <em>a</em>'s, and
|
|
|
451 [<em>a</em>] 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 ‘<b>=</b>’.
|
|
|
455 The complete syntax of Luan can be found in <a href="#9">§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 & ~ | << >> //
|
|
|
532 == ~= <= >= < > =
|
|
|
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 ‘<b>[</b>’ exp ‘<b>]</b>’
|
|
|
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 ‘<b>.</b>’ 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 ::= ‘<b>;</b>’
|
|
|
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 ‘<b>=</b>’ explist
|
|
|
843 varlist ::= var {‘<b>,</b>’ var}
|
|
|
844 explist ::= exp {‘<b>,</b>’ 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 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 © 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
|
