|
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 }
|
|
1667
|
1379 logical_ops = {
|
|
|
1380 title = "Logical Operators"
|
|
|
1381 content = function()
|
|
|
1382 %>
|
|
|
1383 <p>
|
|
|
1384 The logical operators in Luan are
|
|
|
1385 <b>and</b>, <b>or</b>, and <b>not</b>.
|
|
|
1386 The <b>and</b> and <b>or</b> operators consider both <b>false</b> and <b>nil</b> as false
|
|
|
1387 and anything else as true.
|
|
|
1388 Like the control structures (see <a href="#control">Control Structures</a>),
|
|
|
1389 the <b>not</b> operator requires a boolean value.
|
|
|
1390 </p>
|
|
|
1391
|
|
|
1392 <p>
|
|
|
1393 The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>.
|
|
|
1394 The conjunction operator <b>and</b> returns its first argument
|
|
|
1395 if this value is <b>false</b> or <b>nil</b>;
|
|
|
1396 otherwise, <b>and</b> returns its second argument.
|
|
|
1397 The disjunction operator <b>or</b> returns its first argument
|
|
|
1398 if this value is different from <b>nil</b> and <b>false</b>;
|
|
|
1399 otherwise, <b>or</b> returns its second argument.
|
|
|
1400 Both <b>and</b> and <b>or</b> use short-circuit evaluation;
|
|
|
1401 that is,
|
|
|
1402 the second operand is evaluated only if necessary.
|
|
|
1403 Here are some examples:
|
|
|
1404 </p>
|
|
|
1405
|
|
|
1406 <pre>
|
|
|
1407 10 or 20 --> 10
|
|
|
1408 10 or error() --> 10
|
|
|
1409 nil or "a" --> "a"
|
|
|
1410 nil and 10 --> nil
|
|
|
1411 false and error() --> false
|
|
|
1412 false and nil --> false
|
|
|
1413 false or nil --> nil
|
|
|
1414 10 and 20 --> 20
|
|
|
1415 </pre>
|
|
|
1416
|
|
|
1417 <p>
|
|
|
1418 (In this manual,
|
|
|
1419 <code>--></code> indicates the result of the preceding expression.)
|
|
|
1420 </p>
|
|
|
1421 <%
|
|
|
1422 end
|
|
|
1423 }
|
|
|
1424 concatenation = {
|
|
|
1425 title = "Concatenation"
|
|
|
1426 content = function()
|
|
|
1427 %>
|
|
|
1428 <p>
|
|
|
1429 The string concatenation operator in Luan is
|
|
|
1430 denoted by two dots ('<code>..</code>').
|
|
|
1431 All operands are converted to strings.
|
|
|
1432 </p>
|
|
|
1433 <%
|
|
|
1434 end
|
|
|
1435 }
|
|
|
1436 length = {
|
|
|
1437 title = "The Length Operator"
|
|
|
1438 content = function()
|
|
|
1439 %>
|
|
|
1440 <p>
|
|
|
1441 The length operator is denoted by the unary prefix operator <code>#</code>.
|
|
|
1442 The length of a string is its number of characters.
|
|
|
1443 The length of a binary is its number of bytes.
|
|
|
1444 </p>
|
|
|
1445
|
|
|
1446 <p>
|
|
|
1447 A program can modify the behavior of the length operator for
|
|
|
1448 any table through the <code>__len</code> metamethod (see <a href="#meta">Metatables and Metamethods</a>).
|
|
|
1449 </p>
|
|
|
1450
|
|
|
1451 <p>
|
|
|
1452 Unless a <code>__len</code> metamethod is given,
|
|
|
1453 the length of a table <code>t</code> is defined
|
|
|
1454 as the number of elements in <em>sequence</em>,
|
|
|
1455 that is,
|
|
|
1456 the size of the set of its positive numeric keys is equal to <em>{1..n}</em>
|
|
|
1457 for some non-negative integer <em>n</em>.
|
|
|
1458 In that case, <em>n</em> is its length.
|
|
|
1459 Note that a table like
|
|
|
1460 </p>
|
|
|
1461
|
|
|
1462 <pre>
|
|
|
1463 {10, 20, nil, 40}
|
|
|
1464 </pre>
|
|
|
1465
|
|
|
1466 <p>
|
|
|
1467 has a length of <code>2</code>, because that is the last key in sequence.
|
|
|
1468 </p>
|
|
|
1469 <%
|
|
|
1470 end
|
|
|
1471 }
|
|
|
1472 precedence = {
|
|
|
1473 title = "Precedence"
|
|
|
1474 content = function()
|
|
|
1475 %>
|
|
|
1476 <p>
|
|
|
1477 Operator precedence in Luan follows the table below,
|
|
|
1478 from lower to higher priority:
|
|
|
1479 </p>
|
|
|
1480
|
|
|
1481 <pre>
|
|
|
1482 or
|
|
|
1483 and
|
|
|
1484 < > <= >= ~= ==
|
|
|
1485 ..
|
|
|
1486 + -
|
|
|
1487 * / %
|
|
|
1488 unary operators (not # -)
|
|
|
1489 ^
|
|
|
1490 </pre>
|
|
|
1491
|
|
|
1492 <p>
|
|
|
1493 As usual,
|
|
|
1494 you can use parentheses to change the precedences of an expression.
|
|
|
1495 The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>')
|
|
|
1496 operators are right associative.
|
|
|
1497 All other binary operators are left associative.
|
|
|
1498 </p>
|
|
|
1499 <%
|
|
|
1500 end
|
|
|
1501 }
|
|
|
1502 constructors = {
|
|
|
1503 title = "Table Constructors"
|
|
|
1504 content = function()
|
|
|
1505 %>
|
|
|
1506 <p>
|
|
|
1507 Table constructors are expressions that create tables.
|
|
|
1508 Every time a constructor is evaluated, a new table is created.
|
|
|
1509 A constructor can be used to create an empty table
|
|
|
1510 or to create a table and initialize some of its fields.
|
|
|
1511 The general syntax for constructors is
|
|
|
1512 </p>
|
|
|
1513
|
|
|
1514 <pre>
|
|
|
1515 tableconstructor ::= ‘<b>{</b>’ fieldlist ‘<b>}</b>’
|
|
|
1516 fieldlist ::= [field] {fieldsep [field]}
|
|
|
1517 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp
|
|
|
1518 fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ | <b>end_of_line</b>
|
|
|
1519 </pre>
|
|
|
1520
|
|
|
1521 <p>
|
|
|
1522 Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry
|
|
|
1523 with key <code>exp1</code> and value <code>exp2</code>.
|
|
|
1524 A field of the form <code>name = exp</code> is equivalent to
|
|
|
1525 <code>["name"] = exp</code>.
|
|
|
1526 Finally, fields of the form <code>exp</code> are equivalent to
|
|
|
1527 <code>[i] = exp</code>, where <code>i</code> are consecutive integers
|
|
|
1528 starting with 1.
|
|
|
1529 Fields in the other formats do not affect this counting.
|
|
|
1530 For example,
|
|
|
1531 </p>
|
|
|
1532
|
|
|
1533 <pre>
|
|
|
1534 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
|
|
|
1535 </pre>
|
|
|
1536
|
|
|
1537 <p>
|
|
|
1538 is equivalent to
|
|
|
1539 </p>
|
|
|
1540
|
|
|
1541 <pre>
|
|
|
1542 do
|
|
|
1543 local t = {}
|
|
|
1544 t[f(1)] = g
|
|
|
1545 t[1] = "x" -- 1st exp
|
|
|
1546 t[2] = "y" -- 2nd exp
|
|
|
1547 t.x = 1 -- t["x"] = 1
|
|
|
1548 t[3] = f(x) -- 3rd exp
|
|
|
1549 t[30] = 23
|
|
|
1550 t[4] = 45 -- 4th exp
|
|
|
1551 a = t
|
|
|
1552 end
|
|
|
1553 </pre>
|
|
|
1554
|
|
|
1555 <p>
|
|
|
1556 The order of the assignments in a constructor is undefined.
|
|
|
1557 (This order would be relevant only when there are repeated keys.)
|
|
|
1558 </p>
|
|
|
1559
|
|
|
1560 <p>
|
|
|
1561 If the last field in the list has the form <code>exp</code>
|
|
|
1562 and the expression is a function call or a vararg expression,
|
|
|
1563 then all values returned by this expression enter the list consecutively
|
|
|
1564 (see <a href="#fn_calls">Function Calls</a>).
|
|
|
1565 </p>
|
|
|
1566
|
|
|
1567 <p>
|
|
|
1568 The field list can have an optional trailing separator,
|
|
|
1569 as a convenience for machine-generated code.
|
|
|
1570 </p>
|
|
|
1571 <%
|
|
|
1572 end
|
|
|
1573 }
|
|
|
1574 fn_calls = {
|
|
|
1575 title = "Function Calls"
|
|
|
1576 content = function()
|
|
|
1577 %>
|
|
|
1578 <p>
|
|
|
1579 A function call in Luan has the following syntax:
|
|
|
1580 </p>
|
|
|
1581
|
|
|
1582 <pre>
|
|
|
1583 functioncall ::= prefixexp args
|
|
|
1584 </pre>
|
|
|
1585
|
|
|
1586 <p>
|
|
|
1587 In a function call,
|
|
|
1588 first prefixexp and args are evaluated.
|
|
|
1589 The value of prefixexp must have type <em>function</em>.
|
|
|
1590 This function is called
|
|
|
1591 with the given arguments.
|
|
|
1592 </p>
|
|
|
1593
|
|
|
1594 <p>
|
|
|
1595 Arguments have the following syntax:
|
|
|
1596 </p>
|
|
|
1597
|
|
|
1598 <pre>
|
|
|
1599 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’
|
|
|
1600 args ::= tableconstructor
|
|
|
1601 args ::= LiteralString
|
|
|
1602 </pre>
|
|
|
1603
|
|
|
1604 <p>
|
|
|
1605 All argument expressions are evaluated before the call.
|
|
|
1606 A call of the form <code>f{<em>fields</em>}</code> is
|
|
|
1607 syntactic sugar for <code>f({<em>fields</em>})</code>;
|
|
|
1608 that is, the argument list is a single new table.
|
|
|
1609 A call of the form <code>f'<em>string</em>'</code>
|
|
|
1610 (or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>)
|
|
|
1611 is syntactic sugar for <code>f('<em>string</em>')</code>;
|
|
|
1612 that is, the argument list is a single literal string.
|
|
|
1613 </p>
|
|
|
1614 <%
|
|
|
1615 end
|
|
|
1616 }
|
|
|
1617 fn_def = {
|
|
|
1618 title = "Function Definitions"
|
|
|
1619 content = function()
|
|
|
1620 %>
|
|
|
1621 <p>
|
|
|
1622 The syntax for function definition is
|
|
|
1623 </p>
|
|
|
1624
|
|
|
1625 <pre>
|
|
|
1626 functiondef ::= <b>function</b> funcbody
|
|
|
1627 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block end_function
|
|
|
1628 end_function ::= <b>end_function</b> | <b>end</b>
|
|
|
1629 </pre>
|
|
|
1630
|
|
|
1631 <p>
|
|
|
1632 The following syntactic sugar simplifies function definitions:
|
|
|
1633 </p>
|
|
|
1634
|
|
|
1635 <pre>
|
|
|
1636 stat ::= <b>function</b> funcname funcbody
|
|
|
1637 stat ::= <b>local</b> <b>function</b> Name funcbody
|
|
|
1638 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name]
|
|
|
1639 </pre>
|
|
|
1640
|
|
|
1641 <p>
|
|
|
1642 The statement
|
|
|
1643 </p>
|
|
|
1644
|
|
|
1645 <pre>
|
|
|
1646 function f () <em>body</em> end
|
|
|
1647 </pre>
|
|
|
1648
|
|
|
1649 <p>
|
|
|
1650 translates to
|
|
|
1651 </p>
|
|
|
1652
|
|
|
1653 <pre>
|
|
|
1654 f = function () <em>body</em> end
|
|
|
1655 </pre>
|
|
|
1656
|
|
|
1657 <p>
|
|
|
1658 The statement
|
|
|
1659 <p>
|
|
|
1660
|
|
|
1661 <pre>
|
|
|
1662 function t.a.b.c.f () <em>body</em> end
|
|
|
1663 </pre>
|
|
|
1664
|
|
|
1665 <p>
|
|
|
1666 translates to
|
|
|
1667 </p>
|
|
|
1668
|
|
|
1669 <pre>
|
|
|
1670 t.a.b.c.f = function () <em>body</em> end
|
|
|
1671 </pre>
|
|
|
1672
|
|
|
1673 <p>
|
|
|
1674 The statement
|
|
|
1675 </p>
|
|
|
1676
|
|
|
1677 <pre>
|
|
|
1678 local function f () <em>body</em> end
|
|
|
1679 </pre>
|
|
|
1680
|
|
|
1681 <p>
|
|
|
1682 translates to
|
|
|
1683 </p>
|
|
|
1684
|
|
|
1685 <pre>
|
|
|
1686 local f; f = function () <em>body</em> end
|
|
|
1687 </pre>
|
|
|
1688
|
|
|
1689 <p>
|
|
|
1690 not to
|
|
|
1691 </p>
|
|
|
1692
|
|
|
1693 <pre>
|
|
|
1694 local f = function () <em>body</em> end
|
|
|
1695 </pre>
|
|
|
1696
|
|
|
1697 <p>
|
|
|
1698 (This only makes a difference when the body of the function
|
|
|
1699 contains references to <code>f</code>.)
|
|
|
1700 </p>
|
|
|
1701
|
|
|
1702 <p>
|
|
|
1703 A function definition is an executable expression,
|
|
|
1704 whose value has type <em>function</em>.
|
|
|
1705 When Luan precompiles a chunk,
|
|
|
1706 all its function bodies are precompiled too.
|
|
|
1707 Then, whenever Luan executes the function definition,
|
|
|
1708 the function is <em>instantiated</em> (or <em>closed</em>).
|
|
|
1709 This function instance (or <em>closure</em>)
|
|
|
1710 is the final value of the expression.
|
|
|
1711 </p>
|
|
|
1712
|
|
|
1713 <p>
|
|
|
1714 Parameters act as local variables that are
|
|
|
1715 initialized with the argument values:
|
|
|
1716 </p>
|
|
|
1717
|
|
|
1718 <pre>
|
|
|
1719 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’
|
|
|
1720 </pre>
|
|
|
1721
|
|
|
1722 <p>
|
|
|
1723 When a function is called,
|
|
|
1724 the list of arguments is adjusted to
|
|
|
1725 the length of the list of parameters if the list is too short,
|
|
|
1726 unless the function is a <em>vararg function</em>,
|
|
|
1727 which is indicated by three dots ('<code>...</code>')
|
|
|
1728 at the end of its parameter list.
|
|
|
1729 A vararg function does not adjust its argument list;
|
|
|
1730 instead, it collects all extra arguments and supplies them
|
|
|
1731 to the function through a <em>vararg expression</em>,
|
|
|
1732 which is also written as three dots.
|
|
|
1733 The value of this expression is a list of all actual extra arguments,
|
|
|
1734 similar to a function with multiple results.
|
|
|
1735 If a vararg expression is used inside another expression
|
|
|
1736 or in the middle of a list of expressions,
|
|
|
1737 then its return list is adjusted to one element.
|
|
|
1738 If the expression is used as the last element of a list of expressions,
|
|
|
1739 then no adjustment is made
|
|
|
1740 (unless that last expression is enclosed in parentheses).
|
|
|
1741 </p>
|
|
|
1742
|
|
|
1743 <p>
|
|
|
1744 As an example, consider the following definitions:
|
|
|
1745 </p>
|
|
|
1746 <pre>
|
|
|
1747 function f(a, b) end
|
|
|
1748 function g(a, b, ...) end
|
|
|
1749 function r() return 1,2,3 end
|
|
|
1750 </pre>
|
|
|
1751
|
|
|
1752 <p>
|
|
|
1753 Then, we have the following mapping from arguments to parameters and
|
|
|
1754 to the vararg expression:
|
|
|
1755 </p>
|
|
|
1756 <pre>
|
|
|
1757 CALL PARAMETERS
|
|
|
1758
|
|
|
1759 f(3) a=3, b=nil
|
|
|
1760 f(3, 4) a=3, b=4
|
|
|
1761 f(3, 4, 5) runtime error
|
|
|
1762 f(r(), 10) runtime error
|
|
|
1763 f(r()) runtime error
|
|
|
1764
|
|
|
1765 g(3) a=3, b=nil, ... --> (nothing)
|
|
|
1766 g(3, 4) a=3, b=4, ... --> (nothing)
|
|
|
1767 g(3, 4, 5, 8) a=3, b=4, ... --> 5 8
|
|
|
1768 g(5, r()) a=5, b=1, ... --> 2 3
|
|
|
1769 </pre>
|
|
|
1770
|
|
|
1771 <p>
|
|
|
1772 Results are returned using the <b>return</b> statement (see <a href="#control">Control Structures</a>).
|
|
|
1773 If control reaches the end of a function
|
|
|
1774 without encountering a <b>return</b> statement,
|
|
|
1775 then the function returns with no results.
|
|
|
1776 </p>
|
|
|
1777 <%
|
|
|
1778 end
|
|
|
1779 }
|
|
|
1780 }
|
|
|
1781 }
|
|
|
1782 visibility = {
|
|
|
1783 title = "Visibility Rules"
|
|
|
1784 content = function()
|
|
|
1785 %>
|
|
|
1786 <p>
|
|
|
1787 Luan is a lexically scoped language.
|
|
|
1788 The scope of a local variable begins at the first statement after
|
|
|
1789 its declaration and lasts until the last non-void statement
|
|
|
1790 of the innermost block that includes the declaration.
|
|
|
1791 Consider the following example:
|
|
|
1792 </p>
|
|
|
1793 <pre>
|
|
|
1794 x = 10 -- global variable
|
|
|
1795 do -- new block
|
|
|
1796 local x = x -- new 'x', with value 10
|
|
|
1797 print(x) --> 10
|
|
|
1798 x = x+1
|
|
|
1799 do -- another block
|
|
|
1800 local x = x+1 -- another 'x'
|
|
|
1801 print(x) --> 12
|
|
|
1802 end
|
|
|
1803 print(x) --> 11
|
|
|
1804 end
|
|
|
1805 print(x) --> 10 (the global one)
|
|
|
1806 </pre>
|
|
|
1807
|
|
|
1808 <p>
|
|
|
1809 Notice that, in a declaration like <code>local x = x</code>,
|
|
|
1810 the new <code>x</code> being declared is not in scope yet,
|
|
|
1811 and so the second <code>x</code> refers to the outside variable.
|
|
|
1812 </p>
|
|
|
1813
|
|
|
1814 <p>
|
|
|
1815 Because of the lexical scoping rules,
|
|
|
1816 local variables can be freely accessed by functions
|
|
|
1817 defined inside their scope.
|
|
|
1818 A local variable used by an inner function is called
|
|
|
1819 an <em>upvalue</em>, or <em>external local variable</em>,
|
|
|
1820 inside the inner function.
|
|
|
1821 </p>
|
|
|
1822
|
|
|
1823 <p>
|
|
|
1824 Notice that each execution of a <b>local</b> statement
|
|
|
1825 defines new local variables.
|
|
|
1826 Consider the following example:
|
|
|
1827 </p>
|
|
|
1828 <pre>
|
|
|
1829 a = {}
|
|
|
1830 local x = 20
|
|
|
1831 for i=1,10 do
|
|
|
1832 local y = 0
|
|
|
1833 a[i] = function () y=y+1; return x+y end
|
|
|
1834 end
|
|
|
1835 </pre>
|
|
|
1836
|
|
|
1837 <p>
|
|
|
1838 The loop creates ten closures
|
|
|
1839 (that is, ten instances of the anonymous function).
|
|
|
1840 Each of these closures uses a different <code>y</code> variable,
|
|
|
1841 while all of them share the same <code>x</code>.
|
|
|
1842 </p>
|
|
|
1843 <%
|
|
|
1844 end
|
|
|
1845 }
|
|
|
1846 }
|
|
|
1847 }
|
|
|
1848 libs = {
|
|
|
1849 title = "Standard Libraries"
|
|
|
1850 content = function()
|
|
|
1851 %>
|
|
|
1852 <p>
|
|
|
1853 The standard Luan libraries provide useful functions
|
|
|
1854 that are implemented both in Java and in Luan itself.
|
|
|
1855 How each function is implemented shouldn't matter to the user.
|
|
|
1856 Some of these functions provide essential services to the language
|
|
|
1857 (e.g., <a href="#Luan.type"><code>type</code></a> and <a href="#Luan.get_metatable"><code>get_metatable</code></a>);
|
|
|
1858 others provide access to "outside" services (e.g., I/O).
|
|
|
1859 </p>
|
|
|
1860 <%
|
|
|
1861 end
|
|
|
1862 subs = {
|
|
|
1863 default_lib = {
|
|
|
1864 title = "Default Environment"
|
|
|
1865 content = function()
|
|
|
1866 %>
|
|
|
1867 <p>
|
|
|
1868 This is provided by default as a local variable for any Luan code as described in <a href="#env">Environments</a>.
|
|
|
1869 </p>
|
|
|
1870 <%
|
|
|
1871 end
|
|
|
1872 subs = {
|
|
|
1873 require = {
|
|
|
1874 title = "<code>require (mod_uri)</code>"
|
|
|
1875 content = function()
|
|
|
1876 %>
|
|
|
1877 <p>
|
|
|
1878 Example use:
|
|
|
1879 </p>
|
|
|
1880 <pre>
|
|
|
1881 local Table = require "luan:Table.luan"
|
|
|
1882 </pre>
|
|
|
1883
|
|
|
1884 <p>
|
|
|
1885 Could be defined as:
|
|
|
1886 </p>
|
|
|
1887 <pre>
|
|
|
1888 local function require(mod_name)
|
|
|
1889 return <a href="#Package.load">Package.load</a>(mod_name) or <a href="#Luan.error">Luan.error</a>("module '"..mod_name.."' not found")
|
|
|
1890 end
|
|
|
1891 </pre>
|
|
|
1892
|
|
|
1893 <p>
|
|
|
1894 A special case is:
|
|
|
1895 </p>
|
|
|
1896 <pre>
|
|
|
1897 require "java"
|
|
|
1898 </pre>
|
|
|
1899
|
|
|
1900 <p>
|
|
|
1901 This enables Java in the current chunk if that chunk has permission to use Java. If the chunk doesn't have permission to use Java, then an error is thrown.
|
|
|
1902 </p>
|
|
|
1903 <%
|
|
|
1904 end
|
|
|
1905 }
|
|
|
1906 }
|
|
|
1907 }
|
|
|
1908 luan_lib = {
|
|
|
1909 title = "Basic Functions"
|
|
|
1910 content = function()
|
|
|
1911 %>
|
|
|
1912 <p>
|
|
|
1913 Include this library by:
|
|
|
1914 </p>
|
|
|
1915 <pre>
|
|
|
1916 local Luan = require "luan:Luan.luan"
|
|
|
1917 </pre>
|
|
|
1918
|
|
|
1919 <p>
|
|
|
1920 The basic library provides basic functions to Luan that don't depend on other libaries.
|
|
|
1921 </p>
|
|
|
1922 <%
|
|
|
1923 end
|
|
|
1924 subs = {
|
|
|
1925 ["Luan.do_file"] = {
|
|
|
1926 title = "<code>Luan.do_file ([uri])</code>"
|
|
|
1927 content = function()
|
|
|
1928 %>
|
|
|
1929 <p>
|
|
|
1930 Could be defined as:
|
|
|
1931 </p>
|
|
|
1932 <pre>
|
|
|
1933 function Luan.do_file(uri)
|
|
|
1934 local fn = <a href="#Luan.load_file">Luan.load_file</a>(uri) or <a href="#Luan.error">Luan.error</a>("file '"..uri.."' not found")
|
|
|
1935 return fn()
|
|
|
1936 end
|
|
|
1937 </pre>
|
|
|
1938 <%
|
|
|
1939 end
|
|
|
1940 }
|
|
|
1941 ["Luan.error"] = {
|
|
|
1942 title = "<code>Luan.error (message)</code>"
|
|
|
1943 content = function()
|
|
|
1944 %>
|
|
|
1945 <p>
|
|
|
1946 Throws an error containing the message.
|
|
|
1947 </p>
|
|
|
1948
|
|
|
1949 <p>
|
|
|
1950 Could be defined as:
|
|
|
1951 </p>
|
|
|
1952 <pre>
|
|
|
1953 function Luan.error(message)
|
|
|
1954 <a href="#Luan.new_error">Luan.new_error</a>(message).throw()
|
|
|
1955 end
|
|
|
1956 </pre>
|
|
|
1957 <%
|
|
|
1958 end
|
|
|
1959 }
|
|
|
1960 ["Luan.eval"] = {
|
|
|
1961 title = "<code>Luan.eval (text [, source_name [, env]])</code>"
|
|
|
1962 content = function()
|
|
|
1963 %>
|
|
|
1964 <p>
|
|
|
1965 Evaluates <code>text</code> as a Luan expression.
|
|
|
1966 </p>
|
|
|
1967
|
|
|
1968 <p>
|
|
|
1969 Could be defined as:
|
|
|
1970 </p>
|
|
|
1971 <pre>
|
|
|
1972 function Luan.eval(text,source_name, env)
|
|
|
1973 return <a href="#Luan.load">Luan.load</a>( "return "..text, source_name or "eval", env )()
|
|
|
1974 end
|
|
|
1975 </pre>
|
|
|
1976 <%
|
|
|
1977 end
|
|
|
1978 }
|
|
|
1979 ["Luan.get_metatable"] = {
|
|
|
1980 title = "<code>Luan.get_metatable (table)</code>"
|
|
|
1981 content = function()
|
|
|
1982 %>
|
|
|
1983 <p>
|
|
|
1984 If <code>table</code> does not have a metatable, returns <b>nil</b>.
|
|
|
1985 Otherwise,
|
|
|
1986 if the table's metatable has a <code>"__metatable"</code> field,
|
|
|
1987 returns the associated value.
|
|
|
1988 Otherwise, returns the metatable of the given table.
|
|
|
1989 </p>
|
|
|
1990 <%
|
|
|
1991 end
|
|
|
1992 }
|
|
|
1993 ["Luan.hash_code"] = {
|
|
|
1994 title = "<code>Luan.hash_code (v)</code>"
|
|
|
1995 content = function()
|
|
|
1996 %>
|
|
|
1997 <p>
|
|
|
1998 Returns the hash code of <code>v</code>.
|
|
|
1999 </p>
|
|
|
2000 <%
|
|
|
2001 end
|
|
|
2002 }
|
|
|
2003 ["Luan.ipairs"] = {
|
|
|
2004 title = "<code>Luan.ipairs (t)</code>"
|
|
|
2005 content = function()
|
|
|
2006 %>
|
|
|
2007 <p>
|
|
|
2008 Returns an iterator function
|
|
|
2009 so that the construction
|
|
|
2010 </p>
|
|
|
2011 <pre>
|
|
|
2012 for i,v in ipairs(t) do <em>body</em> end
|
|
|
2013 </pre>
|
|
|
2014
|
|
|
2015 <p>
|
|
|
2016 will iterate over the key–value pairs
|
|
|
2017 (<code>1,t[1]</code>), (<code>2,t[2]</code>), ...,
|
|
|
2018 up to the first nil value.
|
|
|
2019 </p>
|
|
|
2020
|
|
|
2021 <p>
|
|
|
2022 Could be defined as:
|
|
|
2023 </p>
|
|
|
2024 <pre>
|
|
|
2025 function Luan.ipairs(t)
|
|
|
2026 local i = 0
|
|
|
2027 return function()
|
|
|
2028 if i < #t then
|
|
|
2029 i = i + 1
|
|
|
2030 return i, t[i]
|
|
|
2031 end
|
|
|
2032 end
|
|
|
2033 end
|
|
|
2034 </pre>
|
|
|
2035 <%
|
|
|
2036 end
|
|
|
2037 }
|
|
|
2038 ["Luan.load"] = {
|
|
|
2039 title = "<code>Luan.load (text, [source_name [, env [, persist]]])</code>"
|
|
|
2040 content = function()
|
|
|
2041 %>
|
|
|
2042 <p>
|
|
|
2043 Loads a chunk.
|
|
|
2044 </p>
|
|
|
2045
|
|
|
2046 <p>
|
|
|
2047 The <code>text</code> is compiled.
|
|
|
2048 If there are no syntactic errors,
|
|
|
2049 returns the compiled chunk as a function;
|
|
|
2050 otherwise, throws an error.
|
|
|
2051 </p>
|
|
|
2052
|
|
|
2053 <p>
|
|
|
2054 The <code>source_name</code> parameter is a string saying where the text came from. It is used to produce error messages. Defaults to "load".
|
|
|
2055 </p>
|
|
|
2056
|
|
|
2057 <p>
|
|
|
2058 If the <code>env</code> parameter is supplied, it becomes the <code>_ENV</code> of the chunk.
|
|
|
2059 </p>
|
|
|
2060
|
|
|
2061 <p>
|
|
|
2062 The <code>persist</code> parameter is a boolean which determines if the compiled code is persistently cached to a temporary file. Defaults to <code>false</code>.
|
|
|
2063 </p>
|
|
|
2064 <%
|
|
|
2065 end
|
|
|
2066 }
|
|
|
2067 ["Luan.load_file"] = {
|
|
|
2068 title = "<code>Luan.load_file (file_uri)</code>"
|
|
|
2069 content = function()
|
|
|
2070 %>
|
|
|
2071 <p>
|
|
|
2072 Similar to <a href="#Luan.load"><code>load</code></a>,
|
|
|
2073 but gets the chunk from file <code>file_uri</code>.
|
|
|
2074 <code>file_uri</code> can be a string or a uri table.
|
|
|
2075 </p>
|
|
|
2076 <%
|
|
|
2077 end
|
|
|
2078 }
|
|
|
2079 ["Luan.new_error"] = {
|
|
|
2080 title = "<code>Luan.new_error (message)</code>"
|
|
|
2081 content = function()
|
|
|
2082 %>
|
|
|
2083 <p>
|
|
|
2084 Creates a new error table containing the message assigned to "<code>message</code>". The error table also contains a <code>throw</code> function which throws the error. The table also contains a list of stack trace elements where each stack trace element is a table containing "<code>source</code>", "<code>line</code>", and possible "<code>call_to</code>". The table also has a metatable containing "<code>__to_string</code>" to render the error.
|
|
|
2085 </p>
|
|
|
2086
|
|
|
2087 <p>
|
|
|
2088 To print the current stack trace, you could do:
|
|
|
2089 </p>
|
|
|
2090 <pre>
|
|
|
2091 Io.print( Luan.new_error "stack" )
|
|
|
2092 </pre>
|
|
|
2093 <%
|
|
|
2094 end
|
|
|
2095 }
|
|
|
2096 ["Luan.pairs"] = {
|
|
|
2097 title = "<code>Luan.pairs (t)</code>"
|
|
|
2098 content = function()
|
|
|
2099 %>
|
|
|
2100 <p>
|
|
|
2101 If <code>t</code> has a metamethod <code>__pairs</code>,
|
|
|
2102 calls it with <code>t</code> as argument and returns the
|
|
|
2103 result from the call.
|
|
|
2104 </p>
|
|
|
2105
|
|
|
2106 <p>
|
|
|
2107 Otherwise,
|
|
|
2108 returns a function
|
|
|
2109 so that the construction
|
|
|
2110 </p>
|
|
|
2111 <pre>
|
|
|
2112 for k,v in pairs(t) do <em>body</em> end
|
|
|
2113 </pre>
|
|
|
2114
|
|
|
2115 <p>
|
|
|
2116 will iterate over all key–value pairs of table <code>t</code>.
|
|
|
2117 </p>
|
|
|
2118 <%
|
|
|
2119 end
|
|
|
2120 }
|
|
|
2121 ["Luan.range"] = {
|
|
|
2122 title = "<code>Luan.range (start, stop [, step])</code>"
|
|
|
2123 content = function()
|
|
|
2124 %>
|
|
|
2125 <p>
|
|
|
2126 Based on <a href="https://docs.python.org/2/library/functions.html#range">the Python range() function</a>, this lets one iterate through a sequence of numbers.
|
|
|
2127 </p>
|
|
|
2128
|
|
|
2129 <p>
|
|
|
2130 Example use:
|
|
|
2131 </p>
|
|
|
2132 <pre>
|
|
|
2133 for i in range(1,10) do
|
|
|
2134 Io.print("count up:",i)
|
|
|
2135 end
|
|
|
2136 for i in range(10,0,-1) do
|
|
|
2137 Io.print("count down:",i)
|
|
|
2138 end
|
|
|
2139 </pre>
|
|
|
2140
|
|
|
2141 <p>
|
|
|
2142 Could be defined as:
|
|
|
2143 </p>
|
|
|
2144 <pre>
|
|
|
2145 function Luan.range(start, stop, step)
|
|
|
2146 step = step or 1
|
|
|
2147 step == 0 and <a href="#Luan.error">Luan.error</a> "bad argument #3 (step may not be zero)"
|
|
|
2148 local i = start
|
|
|
2149 return function()
|
|
|
2150 if step > 0 and i <= stop or step < 0 and i >= stop then
|
|
|
2151 local rtn = i
|
|
|
2152 i = i + step
|
|
|
2153 return rtn
|
|
|
2154 end
|
|
|
2155 end
|
|
|
2156 end
|
|
|
2157 </pre>
|
|
|
2158 <%
|
|
|
2159 end
|
|
|
2160 }
|
|
|
2161 ["Luan.raw_equal"] = {
|
|
|
2162 title = "<code>Luan.raw_equal (v1, v2)</code>"
|
|
|
2163 content = function()
|
|
|
2164 %>
|
|
|
2165 <p>
|
|
|
2166 Checks whether <code>v1</code> is equal to <code>v2</code>,
|
|
|
2167 without invoking any metamethod.
|
|
|
2168 Returns a boolean.
|
|
|
2169 </p>
|
|
|
2170 <%
|
|
|
2171 end
|
|
|
2172 }
|
|
|
2173 ["Luan.raw_get"] = {
|
|
|
2174 title = "<code>Luan.raw_get (table, index)</code>"
|
|
|
2175 content = function()
|
|
|
2176 %>
|
|
|
2177 <p>
|
|
|
2178 Gets the real value of <code>table[index]</code>,
|
|
|
2179 without invoking any metamethod.
|
|
|
2180 <code>table</code> must be a table;
|
|
|
2181 <code>index</code> may be any value.
|
|
|
2182 </p>
|
|
|
2183 <%
|
|
|
2184 end
|
|
|
2185 }
|
|
|
2186 ["Luan.raw_len"] = {
|
|
|
2187 title = "<code>Luan.raw_len (v)</code>"
|
|
|
2188 content = function()
|
|
|
2189 %>
|
|
|
2190 <p>
|
|
|
2191 Returns the length of the object <code>v</code>,
|
|
|
2192 which must be a table or a string,
|
|
|
2193 without invoking any metamethod.
|
|
|
2194 Returns an integer.
|
|
|
2195 </p>
|
|
|
2196 <%
|
|
|
2197 end
|
|
|
2198 }
|
|
|
2199 ["Luan.raw_set"] = {
|
|
|
2200 title = "<code>Luan.raw_set (table, index, value)</code>"
|
|
|
2201 content = function()
|
|
|
2202 %>
|
|
|
2203 <p>
|
|
|
2204 Sets the real value of <code>table[index]</code> to <code>value</code>,
|
|
|
2205 without invoking any metamethod.
|
|
|
2206 <code>table</code> must be a table,
|
|
|
2207 <code>index</code> any value different from <b>nil</b>,
|
|
|
2208 and <code>value</code> any Luan value.
|
|
|
2209 </p>
|
|
|
2210 <%
|
|
|
2211 end
|
|
|
2212 }
|
|
|
2213 ["Luan.set_metatable"] = {
|
|
|
2214 title = "<code>Luan.set_metatable (table, metatable)</code>"
|
|
|
2215 content = function()
|
|
|
2216 %>
|
|
|
2217 <p>
|
|
|
2218 Sets the metatable for the given table.
|
|
|
2219 If <code>metatable</code> is <b>nil</b>,
|
|
|
2220 removes the metatable of the given table.
|
|
|
2221 If the original metatable has a <code>"__metatable"</code> field,
|
|
|
2222 raises an error.
|
|
|
2223 </p>
|
|
|
2224 <%
|
|
|
2225 end
|
|
|
2226 }
|
|
|
2227 ["Luan.stringify"] = {
|
|
|
2228 title = "<code>Luan.stringify (v [,options])</code>"
|
|
|
2229 content = function()
|
|
|
2230 %>
|
|
|
2231 <p>
|
|
|
2232 Receives a value of any type and converts it to a string that is a Luan expression. <code>options</code> is a table. If <code>options.strict==true</code> then invalid types throw an error. Otherwise invalid types are represented but the resulting expression is invalid. If <code>options.number_types==true</code> then numbers will be wrapped in functions for their type.
|
|
|
2233 </p>
|
|
|
2234 <%
|
|
|
2235 end
|
|
|
2236 }
|
|
|
2237 ["Luan.to_string"] = {
|
|
|
2238 title = "<code>Luan.to_string (v)</code>"
|
|
|
2239 content = function()
|
|
|
2240 %>
|
|
|
2241 <p>
|
|
|
2242 Receives a value of any type and
|
|
|
2243 converts it to a string in a human-readable format.
|
|
|
2244 </p>
|
|
|
2245
|
|
|
2246 <p>
|
|
|
2247 If the metatable of <code>v</code> has a <code>"__to_string"</code> field,
|
|
|
2248 then <code>to_string</code> calls the corresponding value
|
|
|
2249 with <code>v</code> as argument,
|
|
|
2250 and uses the result of the call as its result.
|
|
|
2251 </p>
|
|
|
2252 <%
|
|
|
2253 end
|
|
|
2254 }
|
|
|
2255 ["Luan.type"] = {
|
|
|
2256 title = "<code>Luan.type (v)</code>"
|
|
|
2257 content = function()
|
|
|
2258 %>
|
|
|
2259 <p>
|
|
|
2260 Returns the type of its only argument, coded as a string.
|
|
|
2261 The possible results of this function are
|
|
|
2262 "<code>nil</code>" (a string, not the value <b>nil</b>),
|
|
|
2263 "<code>number</code>",
|
|
|
2264 "<code>string</code>",
|
|
|
2265 "<code>binary</code>",
|
|
|
2266 "<code>boolean</code>",
|
|
|
2267 "<code>table</code>",
|
|
|
2268 "<code>function</code>",
|
|
|
2269 and "<code>java</code>".
|
|
|
2270 </p>
|
|
|
2271 <%
|
|
|
2272 end
|
|
|
2273 }
|
|
|
2274 ["Luan.values"] = {
|
|
|
2275 title = "<code>Luan.values (···)</code>"
|
|
|
2276 content = function()
|
|
|
2277 %>
|
|
|
2278 <p>
|
|
|
2279 Returns a function so that the construction
|
|
|
2280 </p>
|
|
|
2281 <pre>
|
|
|
2282 for i, v in Luan.values(···) do <em>body</em> end
|
|
|
2283 </pre>
|
|
|
2284
|
|
|
2285 <p>
|
|
|
2286 will iterate over all values of <code>···</code>.
|
|
|
2287 </p>
|
|
|
2288 <%
|
|
|
2289 end
|
|
|
2290 }
|
|
|
2291 ["Luan.VERSION"] = {
|
|
|
2292 title = "<code>Luan.VERSION</code>"
|
|
|
2293 content = function()
|
|
|
2294 %>
|
|
|
2295 <p>
|
|
|
2296 A global variable (not a function) that
|
|
|
2297 holds a string containing the current Luan version.
|
|
|
2298 </p>
|
|
|
2299 <%
|
|
|
2300 end
|
|
|
2301 }
|
|
|
2302 }
|
|
|
2303 }
|
|
|
2304 package_lib = {
|
|
|
2305 title = "Modules"
|
|
|
2306 content = function()
|
|
|
2307 %>
|
|
|
2308 <p>
|
|
|
2309 Include this library by:
|
|
|
2310 </p>
|
|
|
2311 <pre>
|
|
|
2312 local Package = require "luan:Package.luan"
|
|
|
2313 </pre>
|
|
|
2314
|
|
|
2315 <p>
|
|
|
2316 The package library provides basic
|
|
|
2317 facilities for loading modules in Luan.
|
|
|
2318 </p>
|
|
|
2319 <%
|
|
|
2320 end
|
|
|
2321 subs = {
|
|
|
2322 ["Package.load"] = {
|
|
|
2323 title = "<code>Package.load (mod_uri)</code>"
|
|
|
2324 content = function()
|
|
|
2325 %>
|
|
|
2326 <p>
|
|
|
2327 Loads the given module.
|
|
|
2328 The function starts by looking into the <a href="#Package.loaded"><code>Package.loaded</code></a> table
|
|
|
2329 to determine whether <code>mod_uri</code> is already loaded.
|
|
|
2330 If it is, then <code>Package.load</code> returns the value stored
|
|
|
2331 at <code>Package.loaded[mod_uri]</code>.
|
|
|
2332 Otherwise, it tries to load a new value for the module.
|
|
|
2333 </p>
|
|
|
2334
|
|
|
2335 <p>
|
|
|
2336 To load a new value, <code>Package.load</code> first checks if <code>mod_uri</code> starts with "<b>java:</b>". If yes, then this is a Java class which is loaded by special Java code.
|
|
|
2337 </p>
|
|
|
2338
|
|
|
2339 <p>
|
|
|
2340 Otherwise <code>Package.load</code> tries to read the text of the file referred to by <code>mod_uri</code>. If the file doesn't exist, then <code>Package.load</code> returns <b>false</b>. If the file exists, then its content is compiled into a chunk by calling <a href="#Luan.load"><code>Luan.load</code></a>. This chunk is run passing in <code>mod_uri</code> as an argument. The value returned by the chunk must not be <b>nil</b> and is loaded.
|
|
|
2341 </p>
|
|
|
2342
|
|
|
2343 <p>
|
|
|
2344 If a new value for the module successful loaded, then it is stored in <code>Package.loaded[mod_uri]</code>. The value is returned.
|
|
|
2345 </p>
|
|
|
2346 <%
|
|
|
2347 end
|
|
|
2348 }
|
|
|
2349 ["Package.loaded"] = {
|
|
|
2350 title = "<code>Package.loaded</code>"
|
|
|
2351 content = function()
|
|
|
2352 %>
|
|
|
2353 <p>
|
|
|
2354 A table used by <a href="#Package.load"><code>Package.load</code></a> to control which
|
|
|
2355 modules are already loaded.
|
|
|
2356 When you load a module <code>mod_uri</code> and
|
|
|
2357 <code>Package.loaded[mod_uri]</code> is not <b>nil</b>,
|
|
|
2358 <a href="#Package.load"><code>Package.load</code></a> simply returns the value stored there.
|
|
|
2359 </p>
|
|
|
2360
|
|
|
2361 <p>
|
|
|
2362 This variable is only a reference to the real table;
|
|
|
2363 assignments to this variable do not change the
|
|
|
2364 table used by <a href="#Package.load"><code>Package.load</code></a>.
|
|
|
2365 </p>
|
|
|
2366 <%
|
|
|
2367 end
|
|
|
2368 }
|
|
1656
|
2369 }
|
|
|
2370 }
|
|
1668
|
2371 string_lib = {
|
|
|
2372 title = "String Manipulation"
|
|
|
2373 content = function()
|
|
|
2374 %>
|
|
|
2375 <p>
|
|
|
2376 Include this library by:
|
|
|
2377 </p>
|
|
|
2378 <pre>
|
|
|
2379 local String = require "luan:String.luan"
|
|
|
2380 </pre>
|
|
|
2381
|
|
|
2382 <p>
|
|
|
2383 This library provides generic functions for string manipulation,
|
|
|
2384 such as finding and extracting substrings, and pattern matching.
|
|
|
2385 When indexing a string in Luan, the first character is at position 1
|
|
|
2386 (not at 0, as in Java).
|
|
|
2387 Indices are allowed to be negative and are interpreted as indexing backwards,
|
|
|
2388 from the end of the string.
|
|
|
2389 Thus, the last character is at position -1, and so on.
|
|
|
2390 </p>
|
|
|
2391 <%
|
|
|
2392 end
|
|
|
2393 subs = {
|
|
|
2394 ["String.char"] = {
|
|
|
2395 title = "<code>String.char (···)</code>"
|
|
|
2396 content = function()
|
|
|
2397 %>
|
|
|
2398 <p>
|
|
|
2399 Receives zero or more integers.
|
|
|
2400 Returns a string with length equal to the number of arguments,
|
|
|
2401 in which each character has the internal numerical code equal
|
|
|
2402 to its corresponding argument.
|
|
|
2403 </p>
|
|
|
2404 <%
|
|
|
2405 end
|
|
|
2406 }
|
|
|
2407 ["String.encode"] = {
|
|
|
2408 title = "<code>String.encode (s)</code>"
|
|
|
2409 content = function()
|
|
|
2410 %>
|
|
|
2411 <p>
|
|
|
2412 Encodes argument <code>s</code> into a string that can be placed in quotes so as to return the original value of the string.
|
|
|
2413 </p>
|
|
|
2414 <%
|
|
|
2415 end
|
|
|
2416 }
|
|
|
2417 ["String.find"] = {
|
|
|
2418 title = "<code>String.find (s, pattern [, init [, plain]])</code>"
|
|
|
2419 content = function()
|
|
|
2420 %>
|
|
|
2421 <p>
|
|
|
2422 Looks for the first match of
|
|
|
2423 <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) in the string <code>s</code>.
|
|
|
2424 If it finds a match, then <code>find</code> returns the indices of <code>s</code>
|
|
|
2425 where this occurrence starts and ends;
|
|
|
2426 otherwise, it returns <b>nil</b>.
|
|
|
2427 A third, optional numerical argument <code>init</code> specifies
|
|
|
2428 where to start the search;
|
|
|
2429 its default value is 1 and can be negative.
|
|
|
2430 A value of <b>true</b> as a fourth, optional argument <code>plain</code>
|
|
|
2431 turns off the pattern matching facilities,
|
|
|
2432 so the function does a plain "find substring" operation,
|
|
|
2433 with no characters in <code>pattern</code> being considered magic.
|
|
|
2434 Note that if <code>plain</code> is given, then <code>init</code> must be given as well.
|
|
|
2435 </p>
|
|
|
2436
|
|
|
2437 <p>
|
|
|
2438 If the pattern has captures,
|
|
|
2439 then in a successful match
|
|
|
2440 the captured values are also returned,
|
|
|
2441 after the two indices.
|
|
|
2442 </p>
|
|
|
2443 <%
|
|
|
2444 end
|
|
|
2445 }
|
|
|
2446 ["String.format"] = {
|
|
|
2447 title = "<code>String.format (formatstring, ···)</code>"
|
|
|
2448 content = function()
|
|
|
2449 %>
|
|
|
2450 <p>
|
|
|
2451 Returns a formatted version of its variable number of arguments
|
|
|
2452 following the description given in its first argument (which must be a string).
|
|
|
2453 The format string follows the same rules as the Java function <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#format(java.lang.String,%20java.lang.Object...)"><code>String.format</code></a> because Luan calls this internally.
|
|
|
2454 </p>
|
|
|
2455
|
|
|
2456 <p>
|
|
|
2457 Note that Java's <code>String.format</code> is too stupid to convert between ints and floats, so you must provide the right kind of number.
|
|
|
2458 </p>
|
|
|
2459 <%
|
|
|
2460 end
|
|
|
2461 }
|
|
|
2462 ["String.gmatch"] = {
|
|
|
2463 title = "<code>String.gmatch (s, pattern)</code>"
|
|
|
2464 content = function()
|
|
|
2465 %>
|
|
|
2466 <p>
|
|
|
2467 Returns an iterator function that,
|
|
|
2468 each time it is called,
|
|
|
2469 returns the next captures from <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>)
|
|
|
2470 over the string <code>s</code>.
|
|
|
2471 If <code>pattern</code> specifies no captures,
|
|
|
2472 then the whole match is produced in each call.
|
|
|
2473 </p>
|
|
|
2474
|
|
|
2475 <p>
|
|
|
2476 As an example, the following loop
|
|
|
2477 will iterate over all the words from string <code>s</code>,
|
|
|
2478 printing one per line:
|
|
|
2479 </p>
|
|
|
2480 <pre>
|
|
|
2481 local s = "hello world from Lua"
|
|
|
2482 for w in String.gmatch(s, [[\w+]]) do
|
|
|
2483 print(w)
|
|
|
2484 end
|
|
|
2485 </pre>
|
|
|
2486
|
|
|
2487 <p>
|
|
|
2488 The next example collects all pairs <code>key=value</code> from the
|
|
|
2489 given string into a table:
|
|
|
2490 </p>
|
|
|
2491 <pre>
|
|
|
2492 local t = {}
|
|
|
2493 local s = "from=world, to=Lua"
|
|
|
2494 for k, v in String.gmatch(s, [[(\w+)=(\w+)]]) do
|
|
|
2495 t[k] = v
|
|
|
2496 end
|
|
|
2497 </pre>
|
|
|
2498
|
|
|
2499 <p>
|
|
|
2500 For this function, a caret '<code>^</code>' at the start of a pattern does not
|
|
|
2501 work as an anchor, as this would prevent the iteration.
|
|
|
2502 </p>
|
|
|
2503 <%
|
|
|
2504 end
|
|
|
2505 }
|
|
|
2506 ["String.gsub"] = {
|
|
|
2507 title = "<code>String.gsub (s, pattern, repl [, n])</code>"
|
|
|
2508 content = function()
|
|
|
2509 %>
|
|
|
2510 <p>
|
|
|
2511 Returns a copy of <code>s</code>
|
|
|
2512 in which all (or the first <code>n</code>, if given)
|
|
|
2513 occurrences of the <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) have been
|
|
|
2514 replaced by a replacement string specified by <code>repl</code>,
|
|
|
2515 which can be a string, a table, or a function.
|
|
|
2516 <code>gsub</code> also returns, as its second value,
|
|
|
2517 the total number of matches that occurred.
|
|
|
2518 The name <code>gsub</code> comes from <em>Global SUBstitution</em>.
|
|
|
2519 </p>
|
|
|
2520
|
|
|
2521 <p>
|
|
|
2522 If <code>repl</code> is a string, then its value is used for replacement.
|
|
|
2523 The character <code>\</code> works as an escape character.
|
|
|
2524 Any sequence in <code>repl</code> of the form <code>$<em>d</em></code>,
|
|
|
2525 with <em>d</em> between 1 and 9,
|
|
|
2526 stands for the value of the <em>d</em>-th captured substring.
|
|
|
2527 The sequence <code>$0</code> stands for the whole match.
|
|
|
2528 </p>
|
|
|
2529
|
|
|
2530 <p>
|
|
|
2531 If <code>repl</code> is a table, then the table is queried for every match,
|
|
|
2532 using the first capture as the key.
|
|
|
2533 </p>
|
|
|
2534
|
|
|
2535 <p>
|
|
|
2536 If <code>repl</code> is a function, then this function is called every time a
|
|
|
2537 match occurs, with all captured substrings passed as arguments,
|
|
|
2538 in order.
|
|
|
2539 </p>
|
|
|
2540
|
|
|
2541 <p>
|
|
|
2542 In any case,
|
|
|
2543 if the pattern specifies no captures,
|
|
|
2544 then it behaves as if the whole pattern was inside a capture.
|
|
|
2545 </p>
|
|
|
2546
|
|
|
2547 <p>
|
|
|
2548 If the value returned by the table query or by the function call
|
|
|
2549 is not <b>nil</b>,
|
|
|
2550 then it is used as the replacement string;
|
|
|
2551 otherwise, if it is <b>nil</b>,
|
|
|
2552 then there is no replacement
|
|
|
2553 (that is, the original match is kept in the string).
|
|
|
2554 </p>
|
|
|
2555
|
|
|
2556 <p>
|
|
|
2557 Here are some examples:
|
|
|
2558 </p>
|
|
|
2559 <pre>
|
|
|
2560 x = String.gsub("hello world", [[(\w+)]], "$1 $1")
|
|
|
2561 --> x="hello hello world world"
|
|
|
2562
|
|
|
2563 x = String.gsub("hello world", [[\w+]], "$0 $0", 1)
|
|
|
2564 --> x="hello hello world"
|
|
|
2565
|
|
|
2566 x = String.gsub("hello world from Luan", [[(\w+)\s*(\w+)]], "$2 $1")
|
|
|
2567 --> x="world hello Luan from"
|
|
|
2568
|
|
|
2569 x = String.gsub("4+5 = $return 4+5$", [[\$(.*?)\$]], function (s)
|
|
|
2570 return load(s)()
|
|
|
2571 end)
|
|
|
2572 --> x="4+5 = 9"
|
|
|
2573
|
|
|
2574 local t = {name="lua", version="5.3"}
|
|
|
2575 x = String.gsub("$name-$version.tar.gz", [[\$(\w+)]], t)
|
|
|
2576 --> x="lua-5.3.tar.gz"
|
|
|
2577 </pre>
|
|
|
2578 <%
|
|
|
2579 end
|
|
|
2580 }
|
|
|
2581 ["String.lower"] = {
|
|
|
2582 title = "<code>String.lower (s)</code>"
|
|
|
2583 content = function()
|
|
|
2584 %>
|
|
|
2585 <p>
|
|
|
2586 Receives a string and returns a copy of this string with all
|
|
|
2587 uppercase letters changed to lowercase.
|
|
|
2588 All other characters are left unchanged.
|
|
|
2589 </p>
|
|
|
2590 <%
|
|
|
2591 end
|
|
|
2592 }
|
|
|
2593 ["String.match"] = {
|
|
|
2594 title = "<code>String.match (s, pattern [, init])</code>"
|
|
|
2595 content = function()
|
|
|
2596 %>
|
|
|
2597 <p>
|
|
|
2598 Looks for the first <em>match</em> of
|
|
|
2599 <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) in the string <code>s</code>.
|
|
|
2600 If it finds one, then <code>match</code> returns
|
|
|
2601 the captures from the pattern;
|
|
|
2602 otherwise it returns <b>nil</b>.
|
|
|
2603 If <code>pattern</code> specifies no captures,
|
|
|
2604 then the whole match is returned.
|
|
|
2605 A third, optional numerical argument <code>init</code> specifies
|
|
|
2606 where to start the search;
|
|
|
2607 its default value is 1 and can be negative.
|
|
|
2608 </p>
|
|
|
2609 <%
|
|
|
2610 end
|
|
|
2611 }
|
|
|
2612 ["String.matches"] = {
|
|
|
2613 title = "<code>String.matches (s, pattern)</code>"
|
|
|
2614 content = function()
|
|
|
2615 %>
|
|
|
2616 <p>
|
|
|
2617 Returns a boolean indicating whether the <code>pattern</code> can be found in string <code>s</code>.
|
|
|
2618 This function is equivalent to
|
|
|
2619 </p>
|
|
|
2620 <pre>
|
|
|
2621 return String.match(s,pattern) ~= nil
|
|
|
2622 </pre>
|
|
|
2623 <%
|
|
|
2624 end
|
|
|
2625 }
|
|
|
2626 ["String.regex_quote"] = {
|
|
|
2627 title = "<code>String.regex_quote (s)</code>"
|
|
|
2628 content = function()
|
|
|
2629 %>
|
|
|
2630 <p>
|
|
|
2631 Returns a string which matches the literal string <code>s</code> in a regular expression. This function is simply the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html#quote(java.lang.String)"><code>Pattern.quote</code></a>.
|
|
|
2632 </p>
|
|
|
2633 <%
|
|
|
2634 end
|
|
|
2635 }
|
|
|
2636 ["String.rep"] = {
|
|
|
2637 title = "<code>String.rep (s, n [, sep])</code>"
|
|
|
2638 content = function()
|
|
|
2639 %>
|
|
|
2640 <p>
|
|
|
2641 Returns a string that is the concatenation of <code>n</code> copies of
|
|
|
2642 the string <code>s</code> separated by the string <code>sep</code>.
|
|
|
2643 The default value for <code>sep</code> is the empty string
|
|
|
2644 (that is, no separator).
|
|
|
2645 Returns the empty string if <code>n</code> is not positive.
|
|
|
2646 </p>
|
|
|
2647 <%
|
|
|
2648 end
|
|
|
2649 }
|
|
|
2650 ["String.reverse"] = {
|
|
|
2651 title = "<code>String.reverse (s)</code>"
|
|
|
2652 content = function()
|
|
|
2653 %>
|
|
|
2654 <p>
|
|
|
2655 Returns a string that is the string <code>s</code> reversed.
|
|
|
2656 </p>
|
|
|
2657 <%
|
|
|
2658 end
|
|
|
2659 }
|
|
|
2660 ["String.split"] = {
|
|
|
2661 title = "<code>String.split (s, pattern [, limit])</code>"
|
|
|
2662 content = function()
|
|
|
2663 %>
|
|
|
2664 <p>
|
|
|
2665 Splits <code>s</code> using regex <code>pattern</code> and returns the results. If <code>limit</code> is positive, then only returns at most that many results. If <code>limit</code> is zero, then remove trailing empty results.
|
|
|
2666 </p>
|
|
|
2667 <%
|
|
|
2668 end
|
|
|
2669 }
|
|
|
2670 ["String.sub"] = {
|
|
|
2671 title = "<code>String.sub (s, i [, j])</code>"
|
|
|
2672 content = function()
|
|
|
2673 %>
|
|
|
2674 <p>
|
|
|
2675 Returns the substring of <code>s</code> that
|
|
|
2676 starts at <code>i</code> and continues until <code>j</code>;
|
|
|
2677 <code>i</code> and <code>j</code> can be negative.
|
|
|
2678 If <code>j</code> is absent, then it is assumed to be equal to -1
|
|
|
2679 (which is the same as the string length).
|
|
|
2680 In particular,
|
|
|
2681 the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
|
|
|
2682 with length <code>j</code>,
|
|
|
2683 and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code>
|
|
|
2684 with length <code>i</code>.
|
|
|
2685 </p>
|
|
|
2686
|
|
|
2687 <p>
|
|
|
2688 If, after the translation of negative indices,
|
|
|
2689 <code>i</code> is less than 1,
|
|
|
2690 it is corrected to 1.
|
|
|
2691 If <code>j</code> is greater than the string length,
|
|
|
2692 it is corrected to that length.
|
|
|
2693 If, after these corrections,
|
|
|
2694 <code>i</code> is greater than <code>j</code>,
|
|
|
2695 the function returns the empty string.
|
|
|
2696 </p>
|
|
|
2697 <%
|
|
|
2698 end
|
|
|
2699 }
|
|
|
2700 ["String.to_binary"] = {
|
|
|
2701 title = "<code>String.to_binary (s)</code>"
|
|
|
2702 content = function()
|
|
|
2703 %>
|
|
|
2704 <p>
|
|
|
2705 Converts a string to a binary by calling the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#getBytes()"><code>String.getBytes</code></a>.
|
|
|
2706 </p>
|
|
|
2707 <%
|
|
|
2708 end
|
|
|
2709 }
|
|
|
2710 ["String.to_number"] = {
|
|
|
2711 title = "<code>String.to_number (s [, base])</code>"
|
|
|
2712 content = function()
|
|
|
2713 %>
|
|
|
2714 <p>
|
|
|
2715 When called with no <code>base</code>,
|
|
|
2716 <code>to_number</code> tries to convert its argument to a number.
|
|
|
2717 If the argument is
|
|
|
2718 a string convertible to a number,
|
|
|
2719 then <code>to_number</code> returns this number;
|
|
|
2720 otherwise, it returns <b>nil</b>.
|
|
|
2721 The conversion of strings can result in integers or floats.
|
|
|
2722 </p>
|
|
|
2723
|
|
|
2724 <p>
|
|
|
2725 When called with <code>base</code>,
|
|
|
2726 then <code>s</code> must be a string to be interpreted as
|
|
|
2727 an integer numeral in that base.
|
|
|
2728 In bases above 10, the letter '<code>A</code>' (in either upper or lower case)
|
|
|
2729 represents 10, '<code>B</code>' represents 11, and so forth,
|
|
|
2730 with '<code>Z</code>' representing 35.
|
|
|
2731 If the string <code>s</code> is not a valid numeral in the given base,
|
|
|
2732 the function returns <b>nil</b>.
|
|
|
2733 </p>
|
|
|
2734 <%
|
|
|
2735 end
|
|
|
2736 }
|
|
|
2737 ["String.trim"] = {
|
|
|
2738 title = "<code>String.trim (s)</code>"
|
|
|
2739 content = function()
|
|
|
2740 %>
|
|
|
2741 <p>
|
|
|
2742 Removes the leading and trailing whitespace by calling the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#trim()"><code>String.trim</code></a>.
|
|
|
2743 </p>
|
|
|
2744 <%
|
|
|
2745 end
|
|
|
2746 }
|
|
|
2747 ["String.unicode"] = {
|
|
|
2748 title = "<code>String.unicode (s [, i [, j]])</code>"
|
|
|
2749 content = function()
|
|
|
2750 %>
|
|
|
2751 <p>
|
|
|
2752 Returns the internal numerical codes of the characters <code>s[i]</code>,
|
|
|
2753 <code>s[i+1]</code>, ..., <code>s[j]</code>.
|
|
|
2754 The default value for <code>i</code> is 1;
|
|
|
2755 the default value for <code>j</code> is <code>i</code>.
|
|
|
2756 These indices are corrected
|
|
|
2757 following the same rules of function <a href="#String.sub"><code>String.sub</code></a>.
|
|
|
2758 </p>
|
|
|
2759 <%
|
|
|
2760 end
|
|
|
2761 }
|
|
|
2762 ["String.upper"] = {
|
|
|
2763 title = "<code>String.upper (s)</code>"
|
|
|
2764 content = function()
|
|
|
2765 %>
|
|
|
2766 <p>
|
|
|
2767 Receives a string and returns a copy of this string with all
|
|
|
2768 lowercase letters changed to uppercase.
|
|
|
2769 All other characters are left unchanged.
|
|
|
2770 The definition of what a lowercase letter is depends on the current locale.
|
|
|
2771 </p>
|
|
|
2772 <%
|
|
|
2773 end
|
|
|
2774 }
|
|
|
2775 }
|
|
|
2776 }
|
|
|
2777 binary_lib = {
|
|
|
2778 title = "Binary Manipulation"
|
|
|
2779 content = function()
|
|
|
2780 %>
|
|
|
2781 <p>
|
|
|
2782 Include this library by:
|
|
|
2783 </p>
|
|
|
2784 <pre>
|
|
|
2785 local Binary = require "luan:Binary.luan"
|
|
|
2786 </pre>
|
|
|
2787 <%
|
|
|
2788 end
|
|
|
2789 subs = {
|
|
|
2790 ["Binary.binary"] = {
|
|
|
2791 title = "<code>Binary.binary (···)</code>"
|
|
|
2792 content = function()
|
|
|
2793 %>
|
|
|
2794 <p>
|
|
|
2795 Receives zero or more bytes (as integers).
|
|
|
2796 Returns a binary with length equal to the number of arguments,
|
|
|
2797 in which each byte has the internal numerical code equal
|
|
|
2798 to its corresponding argument.
|
|
|
2799 </p>
|
|
|
2800 <%
|
|
|
2801 end
|
|
|
2802 }
|
|
|
2803 ["Binary.byte"] = {
|
|
|
2804 title = "<code>Binary.byte (b [, i [, j]])</code>"
|
|
|
2805 content = function()
|
|
|
2806 %>
|
|
|
2807 <p>
|
|
|
2808 Returns the internal numerical codes of the bytes <code>b[i]</code>,
|
|
|
2809 <code>b[i+1]</code>, ..., <code>b[j]</code>.
|
|
|
2810 The default value for <code>i</code> is 1;
|
|
|
2811 the default value for <code>j</code> is <code>i</code>.
|
|
|
2812 These indices are corrected
|
|
|
2813 following the same rules of function <a href="#String.sub"><code>String.sub</code></a>.
|
|
|
2814 </p>
|
|
|
2815 <%
|
|
|
2816 end
|
|
|
2817 }
|
|
|
2818 ["Binary.to_string"] = {
|
|
|
2819 title = "<code>Binary.to_string (b [,charset])</code>"
|
|
|
2820 content = function()
|
|
|
2821 %>
|
|
|
2822 <p>
|
|
|
2823 If <code>charset</code> is not nil then converts the binary <code>b</code> to a string using the Java <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#String(byte[],%20java.lang.String)">String constructor</a>, else makes each byte a char.
|
|
|
2824 </p>
|
|
|
2825 <%
|
|
|
2826 end
|
|
|
2827 }
|
|
|
2828 }
|
|
|
2829 }
|
|
|
2830 table_lib = {
|
|
|
2831 title = "Table Manipulation"
|
|
|
2832 content = function()
|
|
|
2833 %>
|
|
|
2834 <p>
|
|
|
2835 Include this library by:
|
|
|
2836 </p>
|
|
|
2837 <pre>
|
|
|
2838 local Table = require "luan:Table.luan"
|
|
|
2839 </pre>
|
|
|
2840
|
|
|
2841 <p>
|
|
|
2842 This library provides generic functions for table manipulation.
|
|
|
2843 It provides all its functions inside the table <code>Table</code>.
|
|
|
2844 </p>
|
|
|
2845 <%
|
|
|
2846 end
|
|
|
2847 subs = {
|
|
|
2848 ["Table.clear"] = {
|
|
|
2849 title = "<code>Table.clear (tbl)</code>"
|
|
|
2850 content = function()
|
|
|
2851 %>
|
|
|
2852 <p>
|
|
|
2853 Clears the table.
|
|
|
2854 </p>
|
|
|
2855 <%
|
|
|
2856 end
|
|
|
2857 }
|
|
|
2858 ["Table.concat"] = {
|
|
|
2859 title = "<code>Table.concat (list [, sep [, i [, j]]])</code>"
|
|
|
2860 content = function()
|
|
|
2861 %>
|
|
|
2862 <p>
|
|
|
2863 Given a list,
|
|
|
2864 returns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>.
|
|
|
2865 The default value for <code>sep</code> is the empty string,
|
|
|
2866 the default for <code>i</code> is 1,
|
|
|
2867 and the default for <code>j</code> is <code>#list</code>.
|
|
|
2868 If <code>i</code> is greater than <code>j</code>, returns the empty string.
|
|
|
2869 </p>
|
|
|
2870 <%
|
|
|
2871 end
|
|
|
2872 }
|
|
|
2873 ["Table.copy"] = {
|
|
|
2874 title = "<code>Table.copy (tbl [, i [, j]])</code>"
|
|
|
2875 content = function()
|
|
|
2876 %>
|
|
|
2877 <p>
|
|
|
2878 If <code>i</code> is <code>nil</code>, returns a shallow copy of <code>tbl</code>.
|
|
|
2879 Otherwise returns a new table which is a list of the elements <code>tbl[i] ··· tbl[j]</code>.
|
|
|
2880 By default, <code>j</code> is <code>#tbl</code>.
|
|
|
2881 </p>
|
|
|
2882 <%
|
|
|
2883 end
|
|
|
2884 }
|
|
|
2885 ["Table.insert"] = {
|
|
|
2886 title = "<code>Table.insert (list, pos, value)</code>"
|
|
|
2887 content = function()
|
|
|
2888 %>
|
|
|
2889 <p>
|
|
|
2890 Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>,
|
|
|
2891 shifting up the elements
|
|
|
2892 <code>list[pos], list[pos+1], ···, list[#list]</code>.
|
|
|
2893 </p>
|
|
|
2894 <%
|
|
|
2895 end
|
|
|
2896 }
|
|
|
2897 ["Table.is_empty"] = {
|
|
|
2898 title = "<code>Table.is_empty (tbl)</code>"
|
|
|
2899 content = function()
|
|
|
2900 %>
|
|
|
2901 <%
|
|
|
2902 end
|
|
|
2903 }
|
|
|
2904 ["Table.pack"] = {
|
|
|
2905 title = "<code>Table.pack (···)</code>"
|
|
|
2906 content = function()
|
|
|
2907 %>
|
|
|
2908 <p>
|
|
|
2909 Returns a new table with all parameters stored into keys 1, 2, etc.
|
|
|
2910 and with a field "<code>n</code>" with the total number of parameters.
|
|
|
2911 Note that the resulting table may not be a sequence.
|
|
|
2912 </p>
|
|
|
2913 <%
|
|
|
2914 end
|
|
|
2915 }
|
|
|
2916 ["Table.remove"] = {
|
|
|
2917 title = "<code>Table.remove (list, pos)</code>"
|
|
|
2918 content = function()
|
|
|
2919 %>
|
|
|
2920 <p>
|
|
|
2921 Removes from <code>list</code> the element at position <code>pos</code>,
|
|
|
2922 returning the value of the removed element.
|
|
|
2923 When <code>pos</code> is an integer between 1 and <code>#list</code>,
|
|
|
2924 it shifts down the elements
|
|
|
2925 <code>list[pos+1], list[pos+2], ···, list[#list]</code>
|
|
|
2926 and erases element <code>list[#list]</code>;
|
|
|
2927 The index <code>pos</code> can also be 0 when <code>#list</code> is 0,
|
|
|
2928 or <code>#list + 1</code>;
|
|
|
2929 in those cases, the function erases the element <code>list[pos]</code>.
|
|
|
2930 </p>
|
|
|
2931 <%
|
|
|
2932 end
|
|
|
2933 }
|
|
|
2934 ["Table.size"] = {
|
|
|
2935 title = "<code>Table.size (tbl)</code>"
|
|
|
2936 content = function()
|
|
|
2937 %>
|
|
|
2938 <%
|
|
|
2939 end
|
|
|
2940 }
|
|
|
2941 ["Table.sort"] = {
|
|
|
2942 title = "<code>Table.sort (list [, comp])</code>"
|
|
|
2943 content = function()
|
|
|
2944 %>
|
|
|
2945 <p>
|
|
|
2946 Sorts list elements in a given order, <em>in-place</em>,
|
|
|
2947 from <code>list[1]</code> to <code>list[#list]</code>.
|
|
|
2948 If <code>comp</code> is given,
|
|
|
2949 then it must be a function that receives two list elements
|
|
|
2950 and returns true when the first element must come
|
|
|
2951 before the second in the final order
|
|
|
2952 (so that <code>not comp(list[i+1],list[i])</code> will be true after the sort).
|
|
|
2953 If <code>comp</code> is not given,
|
|
|
2954 then the standard Lua operator <code><</code> is used instead.
|
|
|
2955 </p>
|
|
|
2956
|
|
|
2957 <p>
|
|
|
2958 The sort algorithm is not stable;
|
|
|
2959 that is, elements considered equal by the given order
|
|
|
2960 may have their relative positions changed by the sort.
|
|
|
2961 </p>
|
|
|
2962 <%
|
|
|
2963 end
|
|
|
2964 }
|
|
|
2965 ["Table.unpack"] = {
|
|
|
2966 title = "<code>Table.unpack (list [, i [, j]])</code>"
|
|
|
2967 content = function()
|
|
|
2968 %>
|
|
|
2969 <p>
|
|
|
2970 Returns the elements from the given list.
|
|
|
2971 This function is equivalent to
|
|
|
2972 </p>
|
|
|
2973 <pre>
|
|
|
2974 return list[i], list[i+1], ···, list[j]
|
|
|
2975 </pre>
|
|
|
2976
|
|
|
2977 <p>
|
|
|
2978 By default, <code>i</code> is 1 and <code>j</code> is <code>list.n or #list</code>.
|
|
|
2979 </p>
|
|
|
2980 <%
|
|
|
2981 end
|
|
|
2982 }
|
|
|
2983 }
|
|
|
2984 }
|
|
|
2985 number_lib = {
|
|
|
2986 title = "Number Manipulation"
|
|
|
2987 content = function()
|
|
|
2988 %>
|
|
|
2989 <p>
|
|
|
2990 Include this library by:
|
|
|
2991 </p>
|
|
|
2992 <pre>
|
|
|
2993 local Number = require "luan:Number.luan"
|
|
|
2994 </pre>
|
|
|
2995 <%
|
|
|
2996 end
|
|
|
2997 subs = {
|
|
|
2998 ["Number.double"] = {
|
|
|
2999 title = "<code>Number.double (x)</code>"
|
|
|
3000 content = function()
|
|
|
3001 %>
|
|
|
3002 <p>
|
|
|
3003 Returns <code>x</code> as a double.
|
|
|
3004 </p>
|
|
|
3005 <%
|
|
|
3006 end
|
|
|
3007 }
|
|
|
3008 ["Number.float"] = {
|
|
|
3009 title = "<code>Number.float (x)</code>"
|
|
|
3010 content = function()
|
|
|
3011 %>
|
|
|
3012 <p>
|
|
|
3013 Returns <code>x</code> as a float.
|
|
|
3014 </p>
|
|
|
3015 <%
|
|
|
3016 end
|
|
|
3017 }
|
|
|
3018 ["Number.integer"] = {
|
|
|
3019 title = "<code>Number.integer (x)</code>"
|
|
|
3020 content = function()
|
|
|
3021 %>
|
|
|
3022 <p>
|
|
|
3023 If the value <code>x</code> is convertible to an integer,
|
|
|
3024 returns that integer.
|
|
|
3025 Otherwise throws an error.
|
|
|
3026 </p>
|
|
|
3027 <%
|
|
|
3028 end
|
|
|
3029 }
|
|
|
3030 ["Number.long"] = {
|
|
|
3031 title = "<code>Number.long (x)</code>"
|
|
|
3032 content = function()
|
|
|
3033 %>
|
|
|
3034 <p>
|
|
|
3035 If the value <code>x</code> is convertible to an long,
|
|
|
3036 returns that long.
|
|
|
3037 Otherwise throws an error.
|
|
|
3038 </p>
|
|
|
3039 <%
|
|
|
3040 end
|
|
|
3041 }
|
|
|
3042 ["Number.long_to_string"] = {
|
|
|
3043 title = "<code>Number.long_to_string (i, radix)</code>"
|
|
|
3044 content = function()
|
|
|
3045 %>
|
|
|
3046 <p>
|
|
|
3047 Converts long value <code>i</code> to a string by calling <code><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Long.html#toString(long,%20int)">Long.toString</a></code>.
|
|
|
3048 </p>
|
|
|
3049 <%
|
|
|
3050 end
|
|
|
3051 }
|
|
|
3052 ["Number.type"] = {
|
|
|
3053 title = "<code>Number.type (x)</code>"
|
|
|
3054 content = function()
|
|
|
3055 %>
|
|
|
3056 <p>
|
|
|
3057 Returns a string for the numeric type of <code>x</code>. Possible return values include "<code>integer</code>", "<code>long</code>", "<code>double</code>", and "<code>float</code>".
|
|
|
3058 </p>
|
|
|
3059 <%
|
|
|
3060 end
|
|
|
3061 }
|
|
|
3062 }
|
|
|
3063 }
|
|
1656
|
3064 }
|
|
|
3065 }
|
|
|
3066 }
|
|
|
3067
|
|
|
3068
|
|
|
3069 return function()
|
|
|
3070 Io.stdout = Http.response.text_writer()
|
|
|
3071 %>
|
|
|
3072 <!doctype html>
|
|
|
3073 <html>
|
|
|
3074 <head>
|
|
|
3075 <% head() %>
|
|
|
3076 <title>Luan Reference Manual</title>
|
|
|
3077 <style>
|
|
|
3078 p[keywords] {
|
|
|
3079 font-family: monospace;
|
|
|
3080 margin-left: 40px;
|
|
|
3081 max-width: 700px;
|
|
|
3082 }
|
|
|
3083 p[keywords] span {
|
|
|
3084 display: inline-block;
|
|
|
3085 width: 100px;
|
|
|
3086 }
|
|
|
3087 </style>
|
|
|
3088 </head>
|
|
|
3089 <body>
|
|
|
3090 <% docs_header() %>
|
|
|
3091 <div content>
|
|
|
3092 <h1><a href="manual.html">Luan Reference Manual</a></h1>
|
|
|
3093 <p small>
|
|
|
3094 Original copyright © 2015 Lua.org, PUC-Rio.
|
|
|
3095 Freely available under the terms of the
|
|
|
3096 <a href="http://www.lua.org/license.html">Lua license</a>.
|
|
|
3097 Modified for Luan.
|
|
|
3098 </p>
|
|
|
3099 <hr>
|
|
|
3100 <h2>Contents</h2>
|
|
|
3101 <div toc>
|
|
|
3102 <% show_toc(content) %>
|
|
|
3103 </div>
|
|
|
3104 <hr>
|
|
|
3105 <% show_content(content,2) %>
|
|
|
3106 </div>
|
|
|
3107 </body>
|
|
|
3108 </html>
|
|
|
3109 <%
|
|
|
3110 end
|
