|
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 }
|
|
1660
|
920 control = {
|
|
|
921 title = "Control Structures"
|
|
|
922 content = function()
|
|
|
923 %>
|
|
|
924 <p>
|
|
|
925 The control structures
|
|
|
926 <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
|
|
|
927 familiar syntax:
|
|
|
928 </p>
|
|
|
929
|
|
|
930 <pre>
|
|
|
931 stat ::= <b>while</b> exp <b>do</b> block end_while
|
|
|
932 stat ::= <b>repeat</b> block <b>until</b> exp
|
|
|
933 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] end_if
|
|
|
934 end_while ::= <b>end_while</b> | <b>end</b>
|
|
|
935 end_if ::= <b>end_if</b> | <b>end</b>
|
|
|
936 </pre>
|
|
|
937
|
|
|
938 <p>
|
|
|
939 Luan also has a <b>for</b> statement (see <a href="#for">For Statement</a>).
|
|
|
940 </p>
|
|
|
941
|
|
|
942 <p>
|
|
|
943 The condition expression of a
|
|
|
944 control structure must be a boolean.
|
|
|
945 Any other value type will produce an error.
|
|
|
946 This helps catch errors and makes code more readable.
|
|
|
947 </p>
|
|
|
948
|
|
|
949 <p>
|
|
|
950 In the <b>repeat</b>–<b>until</b> loop,
|
|
|
951 the inner block does not end at the <b>until</b> keyword,
|
|
|
952 but only after the condition.
|
|
|
953 So, the condition can refer to local variables
|
|
|
954 declared inside the loop block.
|
|
|
955 </p>
|
|
|
956
|
|
|
957 <p>
|
|
|
958 The <b>break</b> statement terminates the execution of a
|
|
|
959 <b>while</b>, <b>repeat</b>, or <b>for</b> loop,
|
|
|
960 skipping to the next statement after the loop:
|
|
|
961 </p>
|
|
|
962
|
|
|
963 <pre>
|
|
|
964 stat ::= <b>break</b>
|
|
|
965 </pre>
|
|
|
966
|
|
|
967 <p>
|
|
|
968 A <b>break</b> ends the innermost enclosing loop.
|
|
|
969 </p>
|
|
|
970
|
|
|
971 <p>
|
|
|
972 The <b>continue</b> statement jumps to the beginning of a
|
|
|
973 <b>while</b>, <b>repeat</b>, or <b>for</b> loop for next iteration,
|
|
|
974 skipping the execution of statements inside the body of loop for the current iteration:
|
|
|
975 </p>
|
|
|
976
|
|
|
977 <pre>
|
|
|
978 stat ::= <b>continue</b>
|
|
|
979 </pre>
|
|
|
980
|
|
|
981 <p>
|
|
|
982 The <b>return</b> statement is used to return values
|
|
|
983 from a function or a chunk
|
|
|
984 (which is an anonymous function).
|
|
|
985 Functions can return more than one value,
|
|
|
986 so the syntax for the <b>return</b> statement is
|
|
|
987 </p>
|
|
|
988
|
|
|
989 <pre>
|
|
|
990 stat ::= <b>return</b> [explist] [‘<b>;</b>’]
|
|
|
991 </pre>
|
|
|
992 <%
|
|
|
993 end
|
|
|
994 }
|
|
|
995 ["for"] = {
|
|
|
996 title = "For Statement"
|
|
|
997 content = function()
|
|
|
998 %>
|
|
|
999 <p>
|
|
|
1000 The <b>for</b> statement works over functions,
|
|
|
1001 called <em>iterators</em>.
|
|
|
1002 On each iteration, the iterator function is called to produce a new value,
|
|
|
1003 stopping when this new value is <b>nil</b>.
|
|
|
1004 The <b>for</b> loop has the following syntax:
|
|
|
1005 </p>
|
|
|
1006
|
|
|
1007 <pre>
|
|
|
1008 stat ::= <b>for</b> namelist <b>in</b> exp <b>do</b> block end_for
|
|
|
1009 namelist ::= Name {‘<b>,</b>’ Name}
|
|
|
1010 end_for ::= <b>end_for</b> | <b>end</b>
|
|
|
1011 </pre>
|
|
|
1012
|
|
|
1013 <p>
|
|
|
1014 A <b>for</b> statement like
|
|
|
1015 </p>
|
|
|
1016
|
|
|
1017 <pre>
|
|
|
1018 for <em>var_1</em>, ···, <em>var_n</em> in <em>exp</em> do <em>block</em> end
|
|
|
1019 </pre>
|
|
|
1020
|
|
|
1021 <p>
|
|
|
1022 is equivalent to the code:
|
|
|
1023 </p>
|
|
|
1024
|
|
|
1025 <pre>
|
|
|
1026 do
|
|
|
1027 local <em>f</em> = <em>exp</em>
|
|
|
1028 while true do
|
|
|
1029 local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>()
|
|
|
1030 if <em>var_1</em> == nil then break end
|
|
|
1031 <em>block</em>
|
|
|
1032 end
|
|
|
1033 end
|
|
|
1034 </pre>
|
|
|
1035
|
|
|
1036 <p>
|
|
|
1037 Note the following:
|
|
|
1038 </p>
|
|
|
1039
|
|
|
1040 <ul>
|
|
|
1041 <li>
|
|
|
1042 <code><em>exp</em></code> is evaluated only once.
|
|
|
1043 Its result is an <em>iterator</em> function.
|
|
|
1044 </li>
|
|
|
1045 <li>
|
|
|
1046 <code><em>f</em></code> is an invisible variable.
|
|
|
1047 The name is here for explanatory purposes only.
|
|
|
1048 </li>
|
|
|
1049 <li>
|
|
|
1050 You can use <b>break</b> to exit a <b>for</b> loop.
|
|
|
1051 </li>
|
|
|
1052 <li>
|
|
|
1053 The loop variables <code><em>var_i</em></code> are local to the loop;
|
|
|
1054 you cannot use their values after the <b>for</b> ends.
|
|
|
1055 If you need these values,
|
|
|
1056 then assign them to other variables before breaking or exiting the loop.
|
|
|
1057 </li>
|
|
|
1058 </ul>
|
|
|
1059 <%
|
|
|
1060 end
|
|
|
1061 }
|
|
|
1062 ["try"] = {
|
|
|
1063 title = "Try Statement"
|
|
|
1064 content = function()
|
|
|
1065 %>
|
|
|
1066 <p>
|
|
|
1067 The <b>try</b> statement has the same semantics as in Java.
|
|
|
1068 </p>
|
|
|
1069
|
|
|
1070 <pre>
|
|
|
1071 stat ::= <b>try</b> block [<b>catch</b> Name block] [<b>finally</b> block] end_try
|
|
|
1072 end_try ::= <b>end_try</b> | <b>end</b>
|
|
|
1073 </pre>
|
|
|
1074 <%
|
|
|
1075 end
|
|
|
1076 }
|
|
|
1077 fn_stmt = {
|
|
|
1078 title = "Function Calls as Statements"
|
|
|
1079 content = function()
|
|
|
1080 %>
|
|
|
1081 <p>
|
|
|
1082 To allow possible side-effects,
|
|
|
1083 function calls can be executed as statements:
|
|
|
1084 </p>
|
|
|
1085
|
|
|
1086 <pre>
|
|
|
1087 stat ::= functioncall
|
|
|
1088 </pre>
|
|
|
1089
|
|
|
1090 <p>
|
|
|
1091 In this case, all returned values are thrown away.
|
|
|
1092 Function calls are explained in <a href="#fn_calls">Function Calls</a>.
|
|
|
1093 </p>
|
|
|
1094 <%
|
|
|
1095 end
|
|
|
1096 }
|
|
|
1097 logical_stmt = {
|
|
|
1098 title = "Logical Statement"
|
|
|
1099 content = function()
|
|
|
1100 %>
|
|
|
1101 <p>
|
|
|
1102 <a href="#logical_ops">Logical expressions</a> can be statements.
|
|
|
1103 This is useful in cases like this:
|
|
|
1104 </p>
|
|
|
1105
|
|
|
1106 <pre>
|
|
|
1107 x==5 or error "x should be 5"
|
|
|
1108 </pre>
|
|
|
1109 <%
|
|
|
1110 end
|
|
|
1111 }
|
|
|
1112 local_stmt = {
|
|
|
1113 title = "Local Declarations"
|
|
|
1114 content = function()
|
|
|
1115 %>
|
|
|
1116 <p>
|
|
|
1117 Local variables can be declared anywhere inside a block.
|
|
|
1118 The declaration can include an initial assignment:
|
|
|
1119 </p>
|
|
|
1120
|
|
|
1121 <pre>
|
|
|
1122 stat ::= <b>local</b> namelist [‘<b>=</b>’ explist]
|
|
|
1123 </pre>
|
|
|
1124
|
|
|
1125 <p>
|
|
|
1126 If present, an initial assignment has the same semantics
|
|
|
1127 of a multiple assignment (see <a href="#assignment">Assignment</a>).
|
|
|
1128 Otherwise, all variables are initialized with <b>nil</b>.
|
|
|
1129 </p>
|
|
|
1130
|
|
|
1131 <p>
|
|
|
1132 A chunk is also a block (see <a href="#chunks">Chunks</a>),
|
|
|
1133 and so local variables can be declared in a chunk outside any explicit block.
|
|
|
1134 </p>
|
|
|
1135
|
|
|
1136 <p>
|
|
|
1137 The visibility rules for local variables are explained in <a href="#visibility">Visibility Rules</a>.
|
|
|
1138 </p>
|
|
|
1139 <%
|
|
|
1140 end
|
|
|
1141 }
|
|
|
1142 template_stmt = {
|
|
|
1143 title = "Template Statements"
|
|
|
1144 content = function()
|
|
|
1145 %>
|
|
|
1146 <p>Template statements provide the full equivalent of <a href="http://en.wikipedia.org/wiki/JavaServer_Pages">JSP</a> but in a general way. Template statements write to standard output. For example:</p>
|
|
|
1147 </p>
|
|
|
1148
|
|
|
1149 <pre>
|
|
|
1150 local name = "Bob"
|
|
|
1151 %>
|
|
|
1152 Hello <%= name %>!
|
|
|
1153 Bye <%= name %>.
|
|
|
1154 <%
|
|
|
1155 </pre>
|
|
|
1156
|
|
|
1157 <p>
|
|
|
1158 is equivalent to the code:
|
|
|
1159 </p>
|
|
|
1160
|
|
|
1161 <pre>
|
|
|
1162 local name = "Bob"
|
|
|
1163 require("luan:Io.luan").stdout.write( "Hello ", name , "!\nBye ", name , ".\n" )
|
|
|
1164 </pre>
|
|
|
1165 <%
|
|
|
1166 end
|
|
|
1167 }
|
|
|
1168 }
|
|
|
1169 }
|
|
|
1170 expressions = {
|
|
|
1171 title = "Expressions"
|
|
|
1172 content = function()
|
|
|
1173 %>
|
|
|
1174 <p>
|
|
|
1175 The basic expressions in Luan are the following:
|
|
|
1176 </p>
|
|
|
1177
|
|
|
1178 <pre>
|
|
|
1179 exp ::= prefixexp
|
|
|
1180 exp ::= <b>nil</b> | <b>false</b> | <b>true</b>
|
|
|
1181 exp ::= Numeral
|
|
|
1182 exp ::= LiteralString
|
|
|
1183 exp ::= functiondef
|
|
|
1184 exp ::= tableconstructor
|
|
|
1185 exp ::= ‘<b>...</b>’
|
|
|
1186 exp ::= exp binop exp
|
|
|
1187 exp ::= unop exp
|
|
|
1188 prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’
|
|
|
1189 </pre>
|
|
|
1190
|
|
|
1191 <p>
|
|
|
1192 Numerals and literal strings are explained in <a href="#lex">Lexical Conventions</a>;
|
|
|
1193 variables are explained in <a href="#vars">Variables</a>;
|
|
|
1194 function definitions are explained in <a href="#fn_def">Function Definitions</a>;
|
|
|
1195 function calls are explained in <a href="#fn_calls">Function Calls</a>;
|
|
|
1196 table constructors are explained in <a href="#constructors">Table Constructors</a>.
|
|
|
1197 Vararg expressions,
|
|
|
1198 denoted by three dots ('<code>...</code>'), can only be used when
|
|
|
1199 directly inside a vararg function;
|
|
|
1200 they are explained in <a href="#fn_def">Function Definitions</a>.
|
|
|
1201 </p>
|
|
|
1202
|
|
|
1203 <p>
|
|
|
1204 Binary operators comprise arithmetic operators (see <a href="#arithmetic">Arithmetic Operators</a>),
|
|
|
1205 relational operators (see <a href="#relational">Relational Operators</a>), logical operators (see <a href="#logical_ops">Logical Operators</a>),
|
|
|
1206 and the concatenation operator (see <a href="#concatenation">Concatenation</a>).
|
|
|
1207 Unary operators comprise the unary minus (see <a href="#arithmetic">Arithmetic Operators</a>),
|
|
|
1208 the unary logical <b>not</b> (see <a href="#logical_ops">Logical Operators</a>),
|
|
|
1209 and the unary <em>length operator</em> (see <a href="#length">The Length Operator</a>).
|
|
|
1210 </p>
|
|
|
1211
|
|
|
1212 <p>
|
|
|
1213 Both function calls and vararg expressions can result in multiple values.
|
|
|
1214 If a function call is used as a statement (see <a href="#fn_stmt">Function Calls as Statements</a>),
|
|
|
1215 then its return list is adjusted to zero elements,
|
|
|
1216 thus discarding all returned values.
|
|
|
1217 If an expression is used as the last (or the only) element
|
|
|
1218 of a list of expressions,
|
|
|
1219 then no adjustment is made
|
|
|
1220 (unless the expression is enclosed in parentheses).
|
|
|
1221 In all other contexts,
|
|
|
1222 Luan adjusts the result list to one element,
|
|
|
1223 either discarding all values except the first one
|
|
|
1224 or adding a single <b>nil</b> if there are no values.
|
|
|
1225 </p>
|
|
|
1226
|
|
|
1227 <p>
|
|
|
1228 Here are some examples:
|
|
|
1229 </p>
|
|
|
1230
|
|
|
1231 <pre>
|
|
|
1232 f() -- adjusted to 0 results
|
|
|
1233 g(f(), x) -- f() is adjusted to 1 result
|
|
|
1234 g(x, f()) -- g gets x plus all results from f()
|
|
|
1235 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil)
|
|
|
1236 a,b = ... -- a gets the first vararg parameter, b gets
|
|
|
1237 -- the second (both a and b can get nil if there
|
|
|
1238 -- is no corresponding vararg parameter)
|
|
|
1239
|
|
|
1240 a,b,c = x, f() -- f() is adjusted to 2 results
|
|
|
1241 a,b,c = f() -- f() is adjusted to 3 results
|
|
|
1242 return f() -- returns all results from f()
|
|
|
1243 return ... -- returns all received vararg parameters
|
|
|
1244 return x,y,f() -- returns x, y, and all results from f()
|
|
|
1245 {f()} -- creates a list with all results from f()
|
|
|
1246 {...} -- creates a list with all vararg parameters
|
|
|
1247 {f(), nil} -- f() is adjusted to 1 result
|
|
|
1248 </pre>
|
|
|
1249
|
|
|
1250 <p>
|
|
|
1251 Any expression enclosed in parentheses always results in only one value.
|
|
|
1252 Thus,
|
|
|
1253 <code>(f(x,y,z))</code> is always a single value,
|
|
|
1254 even if <code>f</code> returns several values.
|
|
|
1255 (The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code>
|
|
|
1256 or <b>nil</b> if <code>f</code> does not return any values.)
|
|
|
1257 </p>
|
|
|
1258 <%
|
|
|
1259 end
|
|
|
1260 subs = {
|
|
|
1261 arithmetic = {
|
|
|
1262 title = "Arithmetic Operators"
|
|
|
1263 content = function()
|
|
|
1264 %>
|
|
|
1265 <p>
|
|
|
1266 Luan supports the following arithmetic operators:
|
|
|
1267 </p>
|
|
|
1268
|
|
|
1269 <ul>
|
|
|
1270 <li><b><code>+</code>: </b>addition</li>
|
|
|
1271 <li><b><code>-</code>: </b>subtraction</li>
|
|
|
1272 <li><b><code>*</code>: </b>multiplication</li>
|
|
|
1273 <li><b><code>/</code>: </b>division</li>
|
|
|
1274 <li><b><code>%</code>: </b>modulo</li>
|
|
|
1275 <li><b><code>^</code>: </b>exponentiation</li>
|
|
|
1276 <li><b><code>-</code>: </b>unary minus</li>
|
|
|
1277 </ul>
|
|
|
1278
|
|
|
1279 <p>
|
|
|
1280 Addition, subtraction, multiplication, division, and unary minus are the same as these operators in Java. Exponentiation uses Java's <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Math.html#pow(double,%20double)">Math.pow</a> function.
|
|
|
1281 </p>
|
|
|
1282
|
|
|
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 </p>
|
|
|
1288 <%
|
|
|
1289 end
|
|
|
1290 }
|
|
|
1291 conversions = {
|
|
|
1292 title = "Coercions and Conversions"
|
|
|
1293 content = function()
|
|
|
1294 %>
|
|
|
1295 <p>
|
|
|
1296 Luan generally avoids automatic conversions.
|
|
|
1297 String concatenation automatically converts all of its arguments to strings.
|
|
|
1298 </p>
|
|
|
1299
|
|
|
1300 <p>
|
|
|
1301 Luan provides library functions for explicit type conversions.
|
|
|
1302 </p>
|
|
|
1303 <%
|
|
|
1304 end
|
|
|
1305 }
|
|
|
1306 relational = {
|
|
|
1307 title = "Relational Operators"
|
|
|
1308 content = function()
|
|
|
1309 %>
|
|
|
1310 <p>
|
|
|
1311 Luan supports the following relational operators:
|
|
|
1312 </p>
|
|
|
1313
|
|
|
1314 <ul>
|
|
|
1315 <li><b><code>==</code>: </b>equality</li>
|
|
|
1316 <li><b><code>~=</code>: </b>inequality</li>
|
|
|
1317 <li><b><code><</code>: </b>less than</li>
|
|
|
1318 <li><b><code>></code>: </b>greater than</li>
|
|
|
1319 <li><b><code><=</code>: </b>less or equal</li>
|
|
|
1320 <li><b><code>>=</code>: </b>greater or equal</li>
|
|
|
1321 </ul>
|
|
|
1322
|
|
|
1323 <p>
|
|
|
1324 These operators always result in <b>false</b> or <b>true</b>.
|
|
|
1325 </p>
|
|
|
1326
|
|
|
1327 <p>
|
|
|
1328 Equality (<code>==</code>) first compares the type of its operands.
|
|
|
1329 If the types are different, then the result is <b>false</b>.
|
|
|
1330 Otherwise, the values of the operands are compared.
|
|
|
1331 Strings, numbers, and binary values are compared in the obvious way (by value).
|
|
|
1332 </p>
|
|
|
1333
|
|
|
1334 <p>
|
|
|
1335 Tables
|
|
|
1336 are compared by reference:
|
|
|
1337 two objects are considered equal only if they are the same object.
|
|
|
1338 Every time you create a new table,
|
|
|
1339 it is different from any previously existing table.
|
|
|
1340 Closures are also compared by reference.
|
|
|
1341 </p>
|
|
|
1342
|
|
|
1343 <p>
|
|
|
1344 You can change the way that Luan compares tables
|
|
|
1345 by using the "eq" metamethod (see <a href="#meta">Metatables and Metamethods</a>).
|
|
|
1346 </p>
|
|
|
1347
|
|
|
1348 <p>
|
|
|
1349 Java values are compared for equality with the Java <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html#equals(java.lang.Object)"><code>equals</code></a> method.
|
|
|
1350 </p>
|
|
|
1351
|
|
|
1352 <p>
|
|
|
1353 Equality comparisons do not convert strings to numbers
|
|
|
1354 or vice versa.
|
|
|
1355 Thus, <code>"0"==0</code> evaluates to <b>false</b>,
|
|
|
1356 and <code>t[0]</code> and <code>t["0"]</code> denote different
|
|
|
1357 entries in a table.
|
|
|
1358 </p>
|
|
|
1359
|
|
|
1360 <p>
|
|
|
1361 The operator <code>~=</code> is exactly the negation of equality (<code>==</code>).
|
|
|
1362 </p>
|
|
|
1363
|
|
|
1364 <p>
|
|
|
1365 The order operators work as follows.
|
|
|
1366 If both arguments are numbers,
|
|
|
1367 then they are compared following
|
|
|
1368 the usual rule for binary operations.
|
|
|
1369 Otherwise, if both arguments are strings,
|
|
|
1370 then their values are compared according to the current locale.
|
|
|
1371 Otherwise, Luan tries to call the "lt" or the "le"
|
|
|
1372 metamethod (see <a href="#meta">Metatables and Metamethods</a>).
|
|
|
1373 A comparison <code>a > b</code> is translated to <code>b < a</code>
|
|
|
1374 and <code>a >= b</code> is translated to <code>b <= a</code>.
|
|
|
1375 </p>
|
|
|
1376 <%
|
|
|
1377 end
|
|
|
1378 }
|
|
1656
|
1379 }
|
|
|
1380 }
|
|
|
1381 }
|
|
|
1382 }
|
|
|
1383 }
|
|
|
1384
|
|
|
1385
|
|
|
1386 return function()
|
|
|
1387 Io.stdout = Http.response.text_writer()
|
|
|
1388 %>
|
|
|
1389 <!doctype html>
|
|
|
1390 <html>
|
|
|
1391 <head>
|
|
|
1392 <% head() %>
|
|
|
1393 <title>Luan Reference Manual</title>
|
|
|
1394 <style>
|
|
|
1395 p[keywords] {
|
|
|
1396 font-family: monospace;
|
|
|
1397 margin-left: 40px;
|
|
|
1398 max-width: 700px;
|
|
|
1399 }
|
|
|
1400 p[keywords] span {
|
|
|
1401 display: inline-block;
|
|
|
1402 width: 100px;
|
|
|
1403 }
|
|
|
1404 </style>
|
|
|
1405 </head>
|
|
|
1406 <body>
|
|
|
1407 <% docs_header() %>
|
|
|
1408 <div content>
|
|
|
1409 <h1><a href="manual.html">Luan Reference Manual</a></h1>
|
|
|
1410 <p small>
|
|
|
1411 Original copyright © 2015 Lua.org, PUC-Rio.
|
|
|
1412 Freely available under the terms of the
|
|
|
1413 <a href="http://www.lua.org/license.html">Lua license</a>.
|
|
|
1414 Modified for Luan.
|
|
|
1415 </p>
|
|
|
1416 <hr>
|
|
|
1417 <h2>Contents</h2>
|
|
|
1418 <div toc>
|
|
|
1419 <% show_toc(content) %>
|
|
|
1420 </div>
|
|
|
1421 <hr>
|
|
|
1422 <% show_content(content,2) %>
|
|
|
1423 </div>
|
|
|
1424 </body>
|
|
|
1425 </html>
|
|
|
1426 <%
|
|
|
1427 end
|
