|
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>
|
|
1680
|
295 <b>"idiv": </b>
|
|
|
296 the <code>//</code> operation.
|
|
|
297 Behavior similar to the "add" operation.
|
|
|
298 </p></li>
|
|
|
299
|
|
|
300 <li><p>
|
|
1656
|
301 <b>"mod": </b>
|
|
|
302 the <code>%</code> operation.
|
|
|
303 Behavior similar to the "add" operation.
|
|
|
304 </p></li>
|
|
|
305
|
|
|
306 <li><p>
|
|
|
307 <b>"pow": </b>
|
|
|
308 the <code>^</code> (exponentiation) operation.
|
|
|
309 Behavior similar to the "add" operation.
|
|
|
310 </p></li>
|
|
|
311
|
|
|
312 <li><p>
|
|
|
313 <b>"unm": </b>
|
|
|
314 the <code>-</code> (unary minus) operation.
|
|
|
315 Behavior similar to the "add" operation.
|
|
|
316 </p></li>
|
|
|
317
|
|
|
318 <li><p>
|
|
|
319 <b>"concat": </b>
|
|
|
320 the <code>..</code> (concatenation) operation.
|
|
|
321 Behavior similar to the "add" operation.
|
|
|
322 </p></li>
|
|
|
323
|
|
|
324 <li><p>
|
|
|
325 <b>"len": </b>
|
|
|
326 the <code>#</code> (length) operation.
|
|
|
327 If there is a metamethod,
|
|
|
328 Luan calls it with the object as argument,
|
|
|
329 and the result of the call
|
|
|
330 (always adjusted to one value)
|
|
|
331 is the result of the operation.
|
|
|
332 If there is no metamethod but the object is a table,
|
|
|
333 then Luan uses the table length operation (see <a href="#length">The Length Operator</a>).
|
|
|
334 Otherwise, Luan raises an error.
|
|
|
335 </p></li>
|
|
|
336
|
|
|
337 <li><p>
|
|
|
338 <b>"eq": </b>
|
|
|
339 the <code>==</code> (equal) operation.
|
|
|
340 Behavior similar to the "add" operation,
|
|
|
341 except that Luan will try a metamethod only when the values
|
|
|
342 being compared are both tables
|
|
|
343 and they are not primitively equal.
|
|
|
344 The result of the call is always converted to a boolean.
|
|
|
345 </p></li>
|
|
|
346
|
|
|
347 <li><p>
|
|
|
348 <b>"lt": </b>
|
|
|
349 the <code><</code> (less than) operation.
|
|
|
350 Behavior similar to the "add" operation.
|
|
|
351 The result of the call is always converted to a boolean.
|
|
|
352 </p></li>
|
|
|
353
|
|
|
354 <li><p>
|
|
|
355 <b>"le": </b>
|
|
|
356 the <code><=</code> (less equal) operation.
|
|
|
357 Unlike other operations,
|
|
|
358 The less-equal operation can use two different events.
|
|
|
359 First, Luan looks for the "<code>__le</code>" metamethod in both operands,
|
|
|
360 like in the "lt" operation.
|
|
|
361 If it cannot find such a metamethod,
|
|
|
362 then it will try the "<code>__lt</code>" event,
|
|
|
363 assuming that <code>a <= b</code> is equivalent to <code>not (b < a)</code>.
|
|
|
364 As with the other comparison operators,
|
|
|
365 the result is always a boolean.
|
|
|
366 </p></li>
|
|
|
367
|
|
|
368 <li>
|
|
|
369 <p>
|
|
|
370 <b>"index": </b>
|
|
|
371 The indexing access <code>table[key]</code>.
|
|
|
372 This event happens
|
|
|
373 when <code>key</code> is not present in <code>table</code>.
|
|
|
374 The metamethod is looked up in <code>table</code>.
|
|
|
375 </p>
|
|
|
376
|
|
|
377 <p>
|
|
|
378 Despite the name,
|
|
|
379 the metamethod for this event can be any type.
|
|
|
380 If it is a function,
|
|
|
381 it is called with <code>table</code> and <code>key</code> as arguments.
|
|
|
382 Otherwise
|
|
|
383 the final result is the result of indexing this metamethod object with <code>key</code>.
|
|
|
384 (This indexing is regular, not raw,
|
|
|
385 and therefore can trigger another metamethod if the metamethod object is a table.)
|
|
|
386 </p>
|
|
|
387 </li>
|
|
|
388
|
|
|
389 <li>
|
|
|
390 <p>
|
|
|
391 <b>"new_index": </b>
|
|
|
392 The indexing assignment <code>table[key] = value</code>.
|
|
|
393 Like the index event,
|
|
|
394 this event happens when
|
|
|
395 when <code>key</code> is not present in <code>table</code>.
|
|
|
396 The metamethod is looked up in <code>table</code>.
|
|
|
397 </p>
|
|
|
398
|
|
|
399 <p>
|
|
|
400 Like with indexing,
|
|
|
401 the metamethod for this event can be either a function or a table.
|
|
|
402 If it is a function,
|
|
|
403 it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments.
|
|
|
404 If it is a table,
|
|
|
405 Luan does an indexing assignment to this table with the same key and value.
|
|
|
406 (This assignment is regular, not raw,
|
|
|
407 and therefore can trigger another metamethod.)
|
|
|
408 </p>
|
|
|
409
|
|
|
410 <p>
|
|
|
411 Whenever there is a "new_index" metamethod,
|
|
|
412 Luan does not perform the primitive assignment.
|
|
|
413 (If necessary,
|
|
|
414 the metamethod itself can call <a href="#Luan.raw_set"><code>raw_set</code></a>
|
|
|
415 to do the assignment.)
|
|
|
416 </p>
|
|
|
417 </li>
|
|
|
418
|
|
|
419 <li><p>
|
|
|
420 <b>"gc":</b>
|
|
|
421 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.
|
|
|
422 </p></li>
|
|
|
423
|
|
|
424 </ul>
|
|
|
425 <%
|
|
|
426 end
|
|
|
427 }
|
|
|
428 gc = {
|
|
|
429 title = "Garbage Collection"
|
|
|
430 content = function()
|
|
|
431 %>
|
|
|
432 <p>
|
|
|
433 Luan uses Java's garbage collection.
|
|
|
434 </p>
|
|
|
435 <%
|
|
|
436 end
|
|
|
437 }
|
|
|
438 }
|
|
|
439 }
|
|
|
440 lang = {
|
|
|
441 title = "The Language"
|
|
|
442 content = function()
|
|
|
443 %>
|
|
|
444 <p>
|
|
|
445 This section describes the lexis, the syntax, and the semantics of Luan.
|
|
|
446 In other words,
|
|
|
447 this section describes
|
|
|
448 which tokens are valid,
|
|
|
449 how they can be combined,
|
|
|
450 and what their combinations mean.
|
|
|
451 </p>
|
|
|
452
|
|
|
453 <p>
|
|
|
454 Language constructs will be explained using the usual extended BNF notation,
|
|
|
455 in which
|
|
|
456 {<em>a</em>} means 0 or more <em>a</em>'s, and
|
|
|
457 [<em>a</em>] means an optional <em>a</em>.
|
|
|
458 Non-terminals are shown like non-terminal,
|
|
|
459 keywords are shown like <b>kword</b>,
|
|
|
460 and other terminal symbols are shown like ‘<b>=</b>’.
|
|
|
461 The complete syntax of Luan can be found in <a href="#9">§9</a>
|
|
|
462 at the end of this manual.
|
|
|
463 </p>
|
|
|
464 <%
|
|
|
465 end
|
|
|
466 subs = {
|
|
|
467 lex = {
|
|
|
468 title = "Lexical Conventions"
|
|
|
469 content = function()
|
|
|
470 %>
|
|
|
471 <p>
|
|
|
472 Luan ignores spaces and comments
|
|
|
473 between lexical elements (tokens),
|
|
|
474 except as delimiters between names and keywords.
|
|
|
475 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.
|
|
|
476 </p>
|
|
|
477
|
|
|
478 <p>
|
|
|
479 <em>Names</em>
|
|
|
480 (also called <em>identifiers</em>)
|
|
|
481 in Luan can be any string of letters,
|
|
|
482 digits, and underscores,
|
|
|
483 not beginning with a digit.
|
|
|
484 Identifiers are used to name variables, table fields, and labels.
|
|
|
485 </p>
|
|
|
486
|
|
|
487 <p>
|
|
|
488 The following <em>keywords</em> are reserved
|
|
|
489 and cannot be used as names:
|
|
|
490 </p>
|
|
|
491
|
|
|
492 <p keywords>
|
|
|
493 <span>and</span>
|
|
|
494 <span>break</span>
|
|
|
495 <span>catch</span>
|
|
|
496 <span>continue</span>
|
|
|
497 <span>do</span>
|
|
|
498 <span>else</span>
|
|
|
499 <span>elseif</span>
|
|
|
500 <span>end_do</span>
|
|
|
501 <span>end_for</span>
|
|
|
502 <span>end_function</span>
|
|
|
503 <span>end_if</span>
|
|
|
504 <span>end_try</span>
|
|
|
505 <span>end_while</span>
|
|
|
506 <span>false</span>
|
|
|
507 <span>finally</span>
|
|
|
508 <span>for</span>
|
|
|
509 <span>function</span>
|
|
|
510 <span>if</span>
|
|
|
511 <span>in</span>
|
|
|
512 <span>local</span>
|
|
|
513 <span>nil</span>
|
|
|
514 <span>not</span>
|
|
|
515 <span>or</span>
|
|
|
516 <span>repeat</span>
|
|
|
517 <span>return</span>
|
|
|
518 <span>then</span>
|
|
|
519 <span>true</span>
|
|
|
520 <span>try</span>
|
|
|
521 <span>until</span>
|
|
|
522 <span>while</span>
|
|
|
523 </p>
|
|
|
524
|
|
|
525 <p>
|
|
|
526 Luan is a case-sensitive language:
|
|
|
527 <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
|
|
|
528 are two different, valid names.
|
|
|
529 </p>
|
|
|
530
|
|
|
531 <p>
|
|
|
532 The following strings denote other tokens:
|
|
|
533 </p>
|
|
|
534
|
|
|
535 <pre>
|
|
|
536 + - * / % ^ #
|
|
|
537 & ~ | << >> //
|
|
|
538 == ~= <= >= < > =
|
|
|
539 ( ) { } [ ] ::
|
|
|
540 ; : , . .. ...
|
|
|
541 </pre>
|
|
|
542
|
|
|
543 <p>
|
|
|
544 <em>Literal strings</em>
|
|
|
545 can be delimited by matching single or double quotes,
|
|
|
546 and can contain the following C-like escape sequences:
|
|
|
547 '<code>\a</code>' (bell),
|
|
|
548 '<code>\b</code>' (backspace),
|
|
|
549 '<code>\f</code>' (form feed),
|
|
|
550 '<code>\n</code>' (newline),
|
|
|
551 '<code>\r</code>' (carriage return),
|
|
|
552 '<code>\t</code>' (horizontal tab),
|
|
|
553 '<code>\v</code>' (vertical tab),
|
|
|
554 '<code>\\</code>' (backslash),
|
|
|
555 '<code>\"</code>' (quotation mark [double quote]),
|
|
|
556 and '<code>\'</code>' (apostrophe [single quote]).
|
|
|
557 A backslash followed by a real newline
|
|
|
558 results in a newline in the string.
|
|
|
559 The escape sequence '<code>\z</code>' skips the following span
|
|
|
560 of white-space characters,
|
|
|
561 including line breaks;
|
|
|
562 it is particularly useful to break and indent a long literal string
|
|
|
563 into multiple lines without adding the newlines and spaces
|
|
|
564 into the string contents.
|
|
|
565 </p>
|
|
|
566
|
|
|
567 <p>
|
|
|
568 Luan can specify any character in a literal string by its numerical value.
|
|
|
569 This can be done
|
|
|
570 with the escape sequence <code>\x<em>XX</em></code>,
|
|
|
571 where <em>XX</em> is a sequence of exactly two hexadecimal digits,
|
|
|
572 or with the escape sequence <code>\u<em>XXXX</em></code>,
|
|
|
573 where <em>XXXX</em> is a sequence of exactly four hexadecimal digits,
|
|
|
574 or with the escape sequence <code>\<em>ddd</em></code>,
|
|
|
575 where <em>ddd</em> is a sequence of up to three decimal digits.
|
|
|
576 (Note that if a decimal escape sequence is to be followed by a digit,
|
|
|
577 it must be expressed using exactly three digits.)
|
|
|
578 </p>
|
|
|
579
|
|
|
580 <p>
|
|
|
581 Literal strings can also be defined using a long format
|
|
|
582 enclosed by <em>long brackets</em>.
|
|
|
583 We define an <em>opening long bracket of level <em>n</em></em> as an opening
|
|
|
584 square bracket followed by <em>n</em> equal signs followed by another
|
|
|
585 opening square bracket.
|
|
|
586 So, an opening long bracket of level 0 is written as <code>[[</code>,
|
|
|
587 an opening long bracket of level 1 is written as <code>[=[</code>,
|
|
|
588 and so on.
|
|
|
589 A <em>closing long bracket</em> is defined similarly;
|
|
|
590 for instance,
|
|
|
591 a closing long bracket of level 4 is written as <code>]====]</code>.
|
|
|
592 A <em>long literal</em> starts with an opening long bracket of any level and
|
|
|
593 ends at the first closing long bracket of the same level.
|
|
|
594 It can contain any text except a closing bracket of the same level.
|
|
|
595 Literals in this bracketed form can run for several lines,
|
|
|
596 do not interpret any escape sequences,
|
|
|
597 and ignore long brackets of any other level.
|
|
|
598 Any kind of end-of-line sequence
|
|
|
599 (carriage return, newline, carriage return followed by newline,
|
|
|
600 or newline followed by carriage return)
|
|
|
601 is converted to a simple newline.
|
|
|
602 </p>
|
|
|
603
|
|
|
604 <p>
|
|
|
605 Any character in a literal string not
|
|
|
606 explicitly affected by the previous rules represents itself.
|
|
|
607 However, Luan opens files for parsing in text mode,
|
|
|
608 and the system file functions may have problems with
|
|
|
609 some control characters.
|
|
|
610 So, it is safer to represent
|
|
|
611 non-text data as a quoted literal with
|
|
|
612 explicit escape sequences for non-text characters.
|
|
|
613 </p>
|
|
|
614
|
|
|
615 <p>
|
|
|
616 For convenience,
|
|
|
617 when the opening long bracket is immediately followed by a newline,
|
|
|
618 the newline is not included in the string.
|
|
|
619 As an example
|
|
|
620 the five literal strings below denote the same string:
|
|
|
621 </p>
|
|
|
622
|
|
|
623 <pre>
|
|
|
624 a = 'alo\n123"'
|
|
|
625 a = "alo\n123\""
|
|
|
626 a = '\97lo\10\04923"'
|
|
|
627 a = [[alo
|
|
|
628 123"]]
|
|
|
629 a = [==[
|
|
|
630 alo
|
|
|
631 123"]==]
|
|
|
632 </pre>
|
|
|
633
|
|
|
634 <p>
|
|
|
635 A <em>numerical constant</em> (or <em>numeral</em>)
|
|
|
636 can be written with an optional fractional part
|
|
|
637 and an optional decimal exponent,
|
|
|
638 marked by a letter '<code>e</code>' or '<code>E</code>'.
|
|
|
639 Luan also accepts hexadecimal constants,
|
|
|
640 which start with <code>0x</code> or <code>0X</code>.
|
|
|
641 Hexadecimal constants also accept an optional fractional part
|
|
|
642 plus an optional binary exponent,
|
|
|
643 marked by a letter '<code>p</code>' or '<code>P</code>'.
|
|
|
644 A numeric constant with a fractional dot or an exponent
|
|
|
645 denotes a float;
|
|
|
646 otherwise it denotes an integer.
|
|
|
647 Examples of valid integer constants are
|
|
|
648 </p>
|
|
|
649
|
|
|
650 <pre>
|
|
|
651 3 345 0xff 0xBEBADA
|
|
|
652 </pre>
|
|
|
653
|
|
|
654 <p>
|
|
|
655 Examples of valid float constants are
|
|
|
656 </p>
|
|
|
657
|
|
|
658 <pre>
|
|
|
659 3.0 3.1416 314.16e-2 0.31416E1 34e1
|
|
|
660 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1
|
|
|
661 </pre>
|
|
|
662
|
|
|
663 <p>
|
|
|
664 A <em>comment</em> starts with a double hyphen (<code>--</code>)
|
|
|
665 anywhere outside a string.
|
|
|
666 If the text immediately after <code>--</code> is not an opening long bracket,
|
|
|
667 the comment is a <em>short comment</em>,
|
|
|
668 which runs until the end of the line.
|
|
|
669 Otherwise, it is a <em>long comment</em>,
|
|
|
670 which runs until the corresponding closing long bracket.
|
|
|
671 Long comments are frequently used to disable code temporarily.
|
|
|
672 </p>
|
|
|
673 <%
|
|
|
674 end
|
|
|
675 }
|
|
|
676 vars = {
|
|
|
677 title = "Variables"
|
|
|
678 content = function()
|
|
|
679 %>
|
|
|
680 <p>
|
|
|
681 Variables are places that store values.
|
|
|
682 There are three kinds of variables in Luan:
|
|
|
683 global variables, local variables, and table fields.
|
|
|
684 </p>
|
|
|
685
|
|
|
686 <p>
|
|
|
687 A single name can denote a global variable or a local variable
|
|
|
688 (or a function's formal parameter,
|
|
|
689 which is a particular kind of local variable):
|
|
|
690 </p>
|
|
|
691
|
|
|
692 <pre>
|
|
|
693 var ::= Name
|
|
|
694 </pre>
|
|
|
695
|
|
|
696 <p>
|
|
|
697 Name denotes identifiers, as defined in <a href="#lex">Lexical Conventions</a>.
|
|
|
698 </p>
|
|
|
699
|
|
|
700 <p>
|
|
|
701 Local variables are <em>lexically scoped</em>:
|
|
|
702 local variables can be freely accessed by functions
|
|
|
703 defined inside their scope (see <a href="#visibility">Visibility Rules</a>).
|
|
|
704 </p>
|
|
|
705
|
|
|
706 <p>
|
|
|
707 Before the first assignment to a variable, its value is <b>nil</b>.
|
|
|
708 </p>
|
|
|
709
|
|
|
710 <p>
|
|
|
711 Square brackets are used to index a table:
|
|
|
712 </p>
|
|
|
713
|
|
|
714 <pre>
|
|
|
715 var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’
|
|
|
716 </pre>
|
|
|
717
|
|
|
718 <p>
|
|
|
719 The meaning of accesses to table fields can be changed via metatables.
|
|
|
720 An access to an indexed variable <code>t[i]</code> is equivalent to
|
|
|
721 a call <code>gettable_event(t,i)</code>.
|
|
|
722 (See <a href="#meta">Metatables and Metamethods</a> for a complete description of the
|
|
|
723 <code>gettable_event</code> function.
|
|
|
724 This function is not defined or callable in Luan.
|
|
|
725 We use it here only for explanatory purposes.)
|
|
|
726 </p>
|
|
|
727
|
|
|
728 <p>
|
|
|
729 The syntax <code>var.Name</code> is just syntactic sugar for
|
|
|
730 <code>var["Name"]</code>:
|
|
|
731 </p>
|
|
|
732
|
|
|
733 <pre>
|
|
|
734 var ::= prefixexp ‘<b>.</b>’ Name
|
|
|
735 </pre>
|
|
|
736
|
|
|
737 <p>
|
|
|
738 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>
|
|
|
739 is equivalent to <code>_ENV.x</code>.
|
|
|
740 Due to the way that chunks are compiled,
|
|
|
741 <code>_ENV</code> is never a global name (see <a href="#env">Environments</a>).
|
|
|
742 </p>
|
|
|
743 <%
|
|
|
744 end
|
|
|
745 }
|
|
|
746 stmt = {
|
|
|
747 title = "Statements"
|
|
|
748 content = function()
|
|
|
749 %>
|
|
|
750 <p>
|
|
|
751 Luan supports an almost conventional set of statements,
|
|
|
752 similar to those in Pascal or C.
|
|
|
753 This set includes
|
|
|
754 assignments, control structures, function calls,
|
|
|
755 and variable declarations.
|
|
|
756 </p>
|
|
|
757 <%
|
|
|
758 end
|
|
|
759 subs = {
|
|
|
760 blocks = {
|
|
|
761 title = "Blocks"
|
|
|
762 content = function()
|
|
|
763 %>
|
|
|
764 <p>
|
|
|
765 A block is a list of statements,
|
|
|
766 which are executed sequentially:
|
|
|
767 </p>
|
|
|
768
|
|
|
769 <pre>
|
|
|
770 block ::= {stat}
|
|
|
771 </pre>
|
|
|
772
|
|
|
773 <p>
|
|
|
774 Luan has <em>empty statements</em>
|
|
|
775 that allow you to separate statements with semicolons,
|
|
|
776 start a block with a semicolon
|
|
|
777 or write two semicolons in sequence:
|
|
|
778 </p>
|
|
|
779
|
|
|
780 <pre>
|
|
|
781 stat ::= ‘<b>;</b>’
|
|
|
782 </pre>
|
|
|
783
|
|
|
784 <p>
|
|
|
785 A block can be explicitly delimited to produce a single statement:
|
|
|
786 </p>
|
|
|
787
|
|
|
788 <pre>
|
|
|
789 stat ::= <b>do</b> block end_do
|
|
|
790 end_do ::= <b>end_do</b> | <b>end</b>
|
|
|
791 </pre>
|
|
|
792
|
|
|
793 <p>
|
|
|
794 Explicit blocks are useful
|
|
|
795 to control the scope of variable declarations.
|
|
|
796 Explicit blocks are also sometimes used to
|
|
|
797 add a <b>return</b> statement in the middle
|
|
|
798 of another block (see <a href="#control">Control Structures</a>).
|
|
|
799 </p>
|
|
|
800 <%
|
|
|
801 end
|
|
|
802 }
|
|
|
803 chunks = {
|
|
|
804 title = "Chunks"
|
|
|
805 content = function()
|
|
|
806 %>
|
|
|
807 <p>
|
|
|
808 The unit of compilation of Luan is called a <em>chunk</em>.
|
|
|
809 Syntactically,
|
|
|
810 a chunk is simply a block:
|
|
|
811 </p>
|
|
|
812
|
|
|
813 <pre>
|
|
|
814 chunk ::= block
|
|
|
815 </pre>
|
|
|
816
|
|
|
817 <p>
|
|
|
818 Luan handles a chunk as the body of an anonymous function
|
|
|
819 with a variable number of arguments
|
|
|
820 (see <a href="#fn_def">Function Definitions</a>).
|
|
|
821 As such, chunks can define local variables,
|
|
|
822 receive arguments, and return values.
|
|
|
823 </p>
|
|
|
824
|
|
|
825 <p>
|
|
|
826 A chunk can be stored in a file or in a string inside the host program.
|
|
|
827 To execute a chunk,
|
|
|
828 Luan first <em>loads</em> it,
|
|
|
829 compiling the chunk's code,
|
|
|
830 and then Luan executes the compiled code.
|
|
|
831 </p>
|
|
|
832 <%
|
|
|
833 end
|
|
|
834 }
|
|
|
835 assignment = {
|
|
|
836 title = "Assignment"
|
|
|
837 content = function()
|
|
|
838 %>
|
|
|
839 <p>
|
|
|
840 Luan allows multiple assignments.
|
|
|
841 Therefore, the syntax for assignment
|
|
|
842 defines a list of variables on the left side
|
|
|
843 and a list of expressions on the right side.
|
|
|
844 The elements in both lists are separated by commas:
|
|
|
845 </p>
|
|
|
846
|
|
|
847 <pre>
|
|
|
848 stat ::= varlist ‘<b>=</b>’ explist
|
|
|
849 varlist ::= var {‘<b>,</b>’ var}
|
|
|
850 explist ::= exp {‘<b>,</b>’ exp}
|
|
|
851 </pre>
|
|
|
852
|
|
|
853 <p>
|
|
|
854 Expressions are discussed in <a href="#expressions">Expressions</a>.
|
|
|
855 </p>
|
|
|
856
|
|
|
857 <p>
|
|
|
858 Before the assignment,
|
|
|
859 the list of values is <em>adjusted</em> to the length of
|
|
|
860 the list of variables.
|
|
|
861 If there are more values than needed,
|
|
|
862 the excess values are thrown away.
|
|
|
863 If there are fewer values than needed,
|
|
|
864 the list is extended with as many <b>nil</b>'s as needed.
|
|
|
865 If the list of expressions ends with a function call,
|
|
|
866 then all values returned by that call enter the list of values,
|
|
|
867 before the adjustment
|
|
|
868 (except when the call is enclosed in parentheses; see <a href="#expressions">Expressions</a>).
|
|
|
869 </p>
|
|
|
870
|
|
|
871 <p>
|
|
|
872 The assignment statement first evaluates all its expressions
|
|
|
873 and only then the assignments are performed.
|
|
|
874 Thus the code
|
|
|
875 </p>
|
|
|
876
|
|
|
877 <pre>
|
|
|
878 i = 3
|
|
|
879 i, a[i] = i+1, 20
|
|
|
880 </pre>
|
|
|
881
|
|
|
882 <p>
|
|
|
883 sets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
|
|
|
884 because the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
|
|
|
885 before it is assigned 4.
|
|
|
886 Similarly, the line
|
|
|
887 </p>
|
|
|
888
|
|
|
889 <pre>
|
|
|
890 x, y = y, x
|
|
|
891 </pre>
|
|
|
892
|
|
|
893 <p>
|
|
|
894 exchanges the values of <code>x</code> and <code>y</code>,
|
|
|
895 and
|
|
|
896 </p>
|
|
|
897
|
|
|
898 <pre>
|
|
|
899 x, y, z = y, z, x
|
|
|
900 </pre>
|
|
|
901
|
|
|
902 <p>
|
|
|
903 cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>.
|
|
|
904 </p>
|
|
|
905
|
|
|
906 <p>
|
|
|
907 The meaning of assignments to global variables
|
|
|
908 and table fields can be changed via metatables.
|
|
|
909 An assignment to an indexed variable <code>t[i] = val</code> is equivalent to
|
|
|
910 <code>settable_event(t,i,val)</code>.
|
|
|
911 (See <a href="#meta">Metatables and Metamethods</a> for a complete description of the
|
|
|
912 <code>settable_event</code> function.
|
|
|
913 This function is not defined or callable in Luan.
|
|
|
914 We use it here only for explanatory purposes.)
|
|
|
915 </p>
|
|
|
916
|
|
|
917 <p>
|
|
|
918 An assignment to a global name <code>x = val</code>
|
|
|
919 is equivalent to the assignment
|
|
|
920 <code>_ENV.x = val</code> (see <a href="#env">Environments</a>).
|
|
|
921 Global names are only available when <code>_ENV</code> is defined.
|
|
|
922 </p>
|
|
|
923 <%
|
|
|
924 end
|
|
|
925 }
|
|
1660
|
926 control = {
|
|
|
927 title = "Control Structures"
|
|
|
928 content = function()
|
|
|
929 %>
|
|
|
930 <p>
|
|
|
931 The control structures
|
|
|
932 <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
|
|
|
933 familiar syntax:
|
|
|
934 </p>
|
|
|
935
|
|
|
936 <pre>
|
|
|
937 stat ::= <b>while</b> exp <b>do</b> block end_while
|
|
|
938 stat ::= <b>repeat</b> block <b>until</b> exp
|
|
|
939 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] end_if
|
|
|
940 end_while ::= <b>end_while</b> | <b>end</b>
|
|
|
941 end_if ::= <b>end_if</b> | <b>end</b>
|
|
|
942 </pre>
|
|
|
943
|
|
|
944 <p>
|
|
|
945 Luan also has a <b>for</b> statement (see <a href="#for">For Statement</a>).
|
|
|
946 </p>
|
|
|
947
|
|
|
948 <p>
|
|
|
949 The condition expression of a
|
|
|
950 control structure must be a boolean.
|
|
|
951 Any other value type will produce an error.
|
|
|
952 This helps catch errors and makes code more readable.
|
|
|
953 </p>
|
|
|
954
|
|
|
955 <p>
|
|
|
956 In the <b>repeat</b>–<b>until</b> loop,
|
|
|
957 the inner block does not end at the <b>until</b> keyword,
|
|
|
958 but only after the condition.
|
|
|
959 So, the condition can refer to local variables
|
|
|
960 declared inside the loop block.
|
|
|
961 </p>
|
|
|
962
|
|
|
963 <p>
|
|
|
964 The <b>break</b> statement terminates the execution of a
|
|
|
965 <b>while</b>, <b>repeat</b>, or <b>for</b> loop,
|
|
|
966 skipping to the next statement after the loop:
|
|
|
967 </p>
|
|
|
968
|
|
|
969 <pre>
|
|
|
970 stat ::= <b>break</b>
|
|
|
971 </pre>
|
|
|
972
|
|
|
973 <p>
|
|
|
974 A <b>break</b> ends the innermost enclosing loop.
|
|
|
975 </p>
|
|
|
976
|
|
|
977 <p>
|
|
|
978 The <b>continue</b> statement jumps to the beginning of a
|
|
|
979 <b>while</b>, <b>repeat</b>, or <b>for</b> loop for next iteration,
|
|
|
980 skipping the execution of statements inside the body of loop for the current iteration:
|
|
|
981 </p>
|
|
|
982
|
|
|
983 <pre>
|
|
|
984 stat ::= <b>continue</b>
|
|
|
985 </pre>
|
|
|
986
|
|
|
987 <p>
|
|
|
988 The <b>return</b> statement is used to return values
|
|
|
989 from a function or a chunk
|
|
|
990 (which is an anonymous function).
|
|
|
991 Functions can return more than one value,
|
|
|
992 so the syntax for the <b>return</b> statement is
|
|
|
993 </p>
|
|
|
994
|
|
|
995 <pre>
|
|
|
996 stat ::= <b>return</b> [explist] [‘<b>;</b>’]
|
|
|
997 </pre>
|
|
|
998 <%
|
|
|
999 end
|
|
|
1000 }
|
|
|
1001 ["for"] = {
|
|
|
1002 title = "For Statement"
|
|
|
1003 content = function()
|
|
|
1004 %>
|
|
|
1005 <p>
|
|
|
1006 The <b>for</b> statement works over functions,
|
|
|
1007 called <em>iterators</em>.
|
|
|
1008 On each iteration, the iterator function is called to produce a new value,
|
|
|
1009 stopping when this new value is <b>nil</b>.
|
|
|
1010 The <b>for</b> loop has the following syntax:
|
|
|
1011 </p>
|
|
|
1012
|
|
|
1013 <pre>
|
|
|
1014 stat ::= <b>for</b> namelist <b>in</b> exp <b>do</b> block end_for
|
|
|
1015 namelist ::= Name {‘<b>,</b>’ Name}
|
|
|
1016 end_for ::= <b>end_for</b> | <b>end</b>
|
|
|
1017 </pre>
|
|
|
1018
|
|
|
1019 <p>
|
|
|
1020 A <b>for</b> statement like
|
|
|
1021 </p>
|
|
|
1022
|
|
|
1023 <pre>
|
|
|
1024 for <em>var_1</em>, ···, <em>var_n</em> in <em>exp</em> do <em>block</em> end
|
|
|
1025 </pre>
|
|
|
1026
|
|
|
1027 <p>
|
|
|
1028 is equivalent to the code:
|
|
|
1029 </p>
|
|
|
1030
|
|
|
1031 <pre>
|
|
|
1032 do
|
|
|
1033 local <em>f</em> = <em>exp</em>
|
|
|
1034 while true do
|
|
|
1035 local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>()
|
|
|
1036 if <em>var_1</em> == nil then break end
|
|
|
1037 <em>block</em>
|
|
|
1038 end
|
|
|
1039 end
|
|
|
1040 </pre>
|
|
|
1041
|
|
|
1042 <p>
|
|
|
1043 Note the following:
|
|
|
1044 </p>
|
|
|
1045
|
|
|
1046 <ul>
|
|
|
1047 <li>
|
|
|
1048 <code><em>exp</em></code> is evaluated only once.
|
|
|
1049 Its result is an <em>iterator</em> function.
|
|
|
1050 </li>
|
|
|
1051 <li>
|
|
|
1052 <code><em>f</em></code> is an invisible variable.
|
|
|
1053 The name is here for explanatory purposes only.
|
|
|
1054 </li>
|
|
|
1055 <li>
|
|
|
1056 You can use <b>break</b> to exit a <b>for</b> loop.
|
|
|
1057 </li>
|
|
|
1058 <li>
|
|
|
1059 The loop variables <code><em>var_i</em></code> are local to the loop;
|
|
|
1060 you cannot use their values after the <b>for</b> ends.
|
|
|
1061 If you need these values,
|
|
|
1062 then assign them to other variables before breaking or exiting the loop.
|
|
|
1063 </li>
|
|
|
1064 </ul>
|
|
|
1065 <%
|
|
|
1066 end
|
|
|
1067 }
|
|
|
1068 ["try"] = {
|
|
|
1069 title = "Try Statement"
|
|
|
1070 content = function()
|
|
|
1071 %>
|
|
|
1072 <p>
|
|
|
1073 The <b>try</b> statement has the same semantics as in Java.
|
|
|
1074 </p>
|
|
|
1075
|
|
|
1076 <pre>
|
|
|
1077 stat ::= <b>try</b> block [<b>catch</b> Name block] [<b>finally</b> block] end_try
|
|
|
1078 end_try ::= <b>end_try</b> | <b>end</b>
|
|
|
1079 </pre>
|
|
|
1080 <%
|
|
|
1081 end
|
|
|
1082 }
|
|
|
1083 fn_stmt = {
|
|
|
1084 title = "Function Calls as Statements"
|
|
|
1085 content = function()
|
|
|
1086 %>
|
|
|
1087 <p>
|
|
|
1088 To allow possible side-effects,
|
|
|
1089 function calls can be executed as statements:
|
|
|
1090 </p>
|
|
|
1091
|
|
|
1092 <pre>
|
|
|
1093 stat ::= functioncall
|
|
|
1094 </pre>
|
|
|
1095
|
|
|
1096 <p>
|
|
|
1097 In this case, all returned values are thrown away.
|
|
|
1098 Function calls are explained in <a href="#fn_calls">Function Calls</a>.
|
|
|
1099 </p>
|
|
|
1100 <%
|
|
|
1101 end
|
|
|
1102 }
|
|
|
1103 logical_stmt = {
|
|
|
1104 title = "Logical Statement"
|
|
|
1105 content = function()
|
|
|
1106 %>
|
|
|
1107 <p>
|
|
|
1108 <a href="#logical_ops">Logical expressions</a> can be statements.
|
|
|
1109 This is useful in cases like this:
|
|
|
1110 </p>
|
|
|
1111
|
|
|
1112 <pre>
|
|
|
1113 x==5 or error "x should be 5"
|
|
|
1114 </pre>
|
|
|
1115 <%
|
|
|
1116 end
|
|
|
1117 }
|
|
|
1118 local_stmt = {
|
|
|
1119 title = "Local Declarations"
|
|
|
1120 content = function()
|
|
|
1121 %>
|
|
|
1122 <p>
|
|
|
1123 Local variables can be declared anywhere inside a block.
|
|
|
1124 The declaration can include an initial assignment:
|
|
|
1125 </p>
|
|
|
1126
|
|
|
1127 <pre>
|
|
|
1128 stat ::= <b>local</b> namelist [‘<b>=</b>’ explist]
|
|
|
1129 </pre>
|
|
|
1130
|
|
|
1131 <p>
|
|
|
1132 If present, an initial assignment has the same semantics
|
|
|
1133 of a multiple assignment (see <a href="#assignment">Assignment</a>).
|
|
|
1134 Otherwise, all variables are initialized with <b>nil</b>.
|
|
|
1135 </p>
|
|
|
1136
|
|
|
1137 <p>
|
|
|
1138 A chunk is also a block (see <a href="#chunks">Chunks</a>),
|
|
|
1139 and so local variables can be declared in a chunk outside any explicit block.
|
|
|
1140 </p>
|
|
|
1141
|
|
|
1142 <p>
|
|
|
1143 The visibility rules for local variables are explained in <a href="#visibility">Visibility Rules</a>.
|
|
|
1144 </p>
|
|
|
1145 <%
|
|
|
1146 end
|
|
|
1147 }
|
|
|
1148 template_stmt = {
|
|
|
1149 title = "Template Statements"
|
|
|
1150 content = function()
|
|
|
1151 %>
|
|
|
1152 <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>
|
|
|
1153 </p>
|
|
|
1154
|
|
|
1155 <pre>
|
|
|
1156 local name = "Bob"
|
|
|
1157 %>
|
|
|
1158 Hello <%= name %>!
|
|
|
1159 Bye <%= name %>.
|
|
|
1160 <%
|
|
|
1161 </pre>
|
|
|
1162
|
|
|
1163 <p>
|
|
|
1164 is equivalent to the code:
|
|
|
1165 </p>
|
|
|
1166
|
|
|
1167 <pre>
|
|
|
1168 local name = "Bob"
|
|
|
1169 require("luan:Io.luan").stdout.write( "Hello ", name , "!\nBye ", name , ".\n" )
|
|
|
1170 </pre>
|
|
|
1171 <%
|
|
|
1172 end
|
|
|
1173 }
|
|
|
1174 }
|
|
|
1175 }
|
|
|
1176 expressions = {
|
|
|
1177 title = "Expressions"
|
|
|
1178 content = function()
|
|
|
1179 %>
|
|
|
1180 <p>
|
|
|
1181 The basic expressions in Luan are the following:
|
|
|
1182 </p>
|
|
|
1183
|
|
|
1184 <pre>
|
|
|
1185 exp ::= prefixexp
|
|
|
1186 exp ::= <b>nil</b> | <b>false</b> | <b>true</b>
|
|
|
1187 exp ::= Numeral
|
|
|
1188 exp ::= LiteralString
|
|
|
1189 exp ::= functiondef
|
|
|
1190 exp ::= tableconstructor
|
|
|
1191 exp ::= ‘<b>...</b>’
|
|
|
1192 exp ::= exp binop exp
|
|
|
1193 exp ::= unop exp
|
|
|
1194 prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’
|
|
|
1195 </pre>
|
|
|
1196
|
|
|
1197 <p>
|
|
|
1198 Numerals and literal strings are explained in <a href="#lex">Lexical Conventions</a>;
|
|
|
1199 variables are explained in <a href="#vars">Variables</a>;
|
|
|
1200 function definitions are explained in <a href="#fn_def">Function Definitions</a>;
|
|
|
1201 function calls are explained in <a href="#fn_calls">Function Calls</a>;
|
|
|
1202 table constructors are explained in <a href="#constructors">Table Constructors</a>.
|
|
|
1203 Vararg expressions,
|
|
|
1204 denoted by three dots ('<code>...</code>'), can only be used when
|
|
|
1205 directly inside a vararg function;
|
|
|
1206 they are explained in <a href="#fn_def">Function Definitions</a>.
|
|
|
1207 </p>
|
|
|
1208
|
|
|
1209 <p>
|
|
|
1210 Binary operators comprise arithmetic operators (see <a href="#arithmetic">Arithmetic Operators</a>),
|
|
|
1211 relational operators (see <a href="#relational">Relational Operators</a>), logical operators (see <a href="#logical_ops">Logical Operators</a>),
|
|
|
1212 and the concatenation operator (see <a href="#concatenation">Concatenation</a>).
|
|
|
1213 Unary operators comprise the unary minus (see <a href="#arithmetic">Arithmetic Operators</a>),
|
|
|
1214 the unary logical <b>not</b> (see <a href="#logical_ops">Logical Operators</a>),
|
|
|
1215 and the unary <em>length operator</em> (see <a href="#length">The Length Operator</a>).
|
|
|
1216 </p>
|
|
|
1217
|
|
|
1218 <p>
|
|
|
1219 Both function calls and vararg expressions can result in multiple values.
|
|
|
1220 If a function call is used as a statement (see <a href="#fn_stmt">Function Calls as Statements</a>),
|
|
|
1221 then its return list is adjusted to zero elements,
|
|
|
1222 thus discarding all returned values.
|
|
|
1223 If an expression is used as the last (or the only) element
|
|
|
1224 of a list of expressions,
|
|
|
1225 then no adjustment is made
|
|
|
1226 (unless the expression is enclosed in parentheses).
|
|
|
1227 In all other contexts,
|
|
|
1228 Luan adjusts the result list to one element,
|
|
|
1229 either discarding all values except the first one
|
|
|
1230 or adding a single <b>nil</b> if there are no values.
|
|
|
1231 </p>
|
|
|
1232
|
|
|
1233 <p>
|
|
|
1234 Here are some examples:
|
|
|
1235 </p>
|
|
|
1236
|
|
|
1237 <pre>
|
|
|
1238 f() -- adjusted to 0 results
|
|
|
1239 g(f(), x) -- f() is adjusted to 1 result
|
|
|
1240 g(x, f()) -- g gets x plus all results from f()
|
|
|
1241 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil)
|
|
|
1242 a,b = ... -- a gets the first vararg parameter, b gets
|
|
|
1243 -- the second (both a and b can get nil if there
|
|
|
1244 -- is no corresponding vararg parameter)
|
|
|
1245
|
|
|
1246 a,b,c = x, f() -- f() is adjusted to 2 results
|
|
|
1247 a,b,c = f() -- f() is adjusted to 3 results
|
|
|
1248 return f() -- returns all results from f()
|
|
|
1249 return ... -- returns all received vararg parameters
|
|
|
1250 return x,y,f() -- returns x, y, and all results from f()
|
|
|
1251 {f()} -- creates a list with all results from f()
|
|
|
1252 {...} -- creates a list with all vararg parameters
|
|
|
1253 {f(), nil} -- f() is adjusted to 1 result
|
|
|
1254 </pre>
|
|
|
1255
|
|
|
1256 <p>
|
|
|
1257 Any expression enclosed in parentheses always results in only one value.
|
|
|
1258 Thus,
|
|
|
1259 <code>(f(x,y,z))</code> is always a single value,
|
|
|
1260 even if <code>f</code> returns several values.
|
|
|
1261 (The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code>
|
|
|
1262 or <b>nil</b> if <code>f</code> does not return any values.)
|
|
|
1263 </p>
|
|
|
1264 <%
|
|
|
1265 end
|
|
|
1266 subs = {
|
|
|
1267 arithmetic = {
|
|
|
1268 title = "Arithmetic Operators"
|
|
|
1269 content = function()
|
|
|
1270 %>
|
|
|
1271 <p>
|
|
|
1272 Luan supports the following arithmetic operators:
|
|
|
1273 </p>
|
|
|
1274
|
|
|
1275 <ul>
|
|
|
1276 <li><b><code>+</code>: </b>addition</li>
|
|
|
1277 <li><b><code>-</code>: </b>subtraction</li>
|
|
|
1278 <li><b><code>*</code>: </b>multiplication</li>
|
|
1680
|
1279 <li><b><code>/</code>: </b>float division</li>
|
|
|
1280 <li><b><code>//</code>: </b>floor division</li>
|
|
1660
|
1281 <li><b><code>%</code>: </b>modulo</li>
|
|
|
1282 <li><b><code>^</code>: </b>exponentiation</li>
|
|
|
1283 <li><b><code>-</code>: </b>unary minus</li>
|
|
|
1284 </ul>
|
|
|
1285
|
|
|
1286 <p>
|
|
|
1287 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.
|
|
|
1288 </p>
|
|
|
1289
|
|
|
1290 <p>
|
|
1680
|
1291 Floor division (//) is a division that rounds the quotient towards minus infinity, that is, the floor of the division of its operands.
|
|
|
1292 </p>
|
|
|
1293
|
|
|
1294 <p>
|
|
1660
|
1295 Modulo is defined as the remainder of a division
|
|
|
1296 that rounds the quotient towards minus infinite (floor division).
|
|
|
1297 (The Java modulo operator is not used.)
|
|
|
1298 </p>
|
|
|
1299 <%
|
|
|
1300 end
|
|
|
1301 }
|
|
|
1302 conversions = {
|
|
|
1303 title = "Coercions and Conversions"
|
|
|
1304 content = function()
|
|
|
1305 %>
|
|
|
1306 <p>
|
|
|
1307 Luan generally avoids automatic conversions.
|
|
|
1308 String concatenation automatically converts all of its arguments to strings.
|
|
|
1309 </p>
|
|
|
1310
|
|
|
1311 <p>
|
|
|
1312 Luan provides library functions for explicit type conversions.
|
|
|
1313 </p>
|
|
|
1314 <%
|
|
|
1315 end
|
|
|
1316 }
|
|
|
1317 relational = {
|
|
|
1318 title = "Relational Operators"
|
|
|
1319 content = function()
|
|
|
1320 %>
|
|
|
1321 <p>
|
|
|
1322 Luan supports the following relational operators:
|
|
|
1323 </p>
|
|
|
1324
|
|
|
1325 <ul>
|
|
|
1326 <li><b><code>==</code>: </b>equality</li>
|
|
|
1327 <li><b><code>~=</code>: </b>inequality</li>
|
|
|
1328 <li><b><code><</code>: </b>less than</li>
|
|
|
1329 <li><b><code>></code>: </b>greater than</li>
|
|
|
1330 <li><b><code><=</code>: </b>less or equal</li>
|
|
|
1331 <li><b><code>>=</code>: </b>greater or equal</li>
|
|
|
1332 </ul>
|
|
|
1333
|
|
|
1334 <p>
|
|
|
1335 These operators always result in <b>false</b> or <b>true</b>.
|
|
|
1336 </p>
|
|
|
1337
|
|
|
1338 <p>
|
|
|
1339 Equality (<code>==</code>) first compares the type of its operands.
|
|
|
1340 If the types are different, then the result is <b>false</b>.
|
|
|
1341 Otherwise, the values of the operands are compared.
|
|
|
1342 Strings, numbers, and binary values are compared in the obvious way (by value).
|
|
|
1343 </p>
|
|
|
1344
|
|
|
1345 <p>
|
|
|
1346 Tables
|
|
|
1347 are compared by reference:
|
|
|
1348 two objects are considered equal only if they are the same object.
|
|
|
1349 Every time you create a new table,
|
|
|
1350 it is different from any previously existing table.
|
|
|
1351 Closures are also compared by reference.
|
|
|
1352 </p>
|
|
|
1353
|
|
|
1354 <p>
|
|
|
1355 You can change the way that Luan compares tables
|
|
|
1356 by using the "eq" metamethod (see <a href="#meta">Metatables and Metamethods</a>).
|
|
|
1357 </p>
|
|
|
1358
|
|
|
1359 <p>
|
|
|
1360 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.
|
|
|
1361 </p>
|
|
|
1362
|
|
|
1363 <p>
|
|
|
1364 Equality comparisons do not convert strings to numbers
|
|
|
1365 or vice versa.
|
|
|
1366 Thus, <code>"0"==0</code> evaluates to <b>false</b>,
|
|
|
1367 and <code>t[0]</code> and <code>t["0"]</code> denote different
|
|
|
1368 entries in a table.
|
|
|
1369 </p>
|
|
|
1370
|
|
|
1371 <p>
|
|
|
1372 The operator <code>~=</code> is exactly the negation of equality (<code>==</code>).
|
|
|
1373 </p>
|
|
|
1374
|
|
|
1375 <p>
|
|
|
1376 The order operators work as follows.
|
|
|
1377 If both arguments are numbers,
|
|
|
1378 then they are compared following
|
|
|
1379 the usual rule for binary operations.
|
|
|
1380 Otherwise, if both arguments are strings,
|
|
|
1381 then their values are compared according to the current locale.
|
|
|
1382 Otherwise, Luan tries to call the "lt" or the "le"
|
|
|
1383 metamethod (see <a href="#meta">Metatables and Metamethods</a>).
|
|
|
1384 A comparison <code>a > b</code> is translated to <code>b < a</code>
|
|
|
1385 and <code>a >= b</code> is translated to <code>b <= a</code>.
|
|
|
1386 </p>
|
|
|
1387 <%
|
|
|
1388 end
|
|
|
1389 }
|
|
1667
|
1390 logical_ops = {
|
|
|
1391 title = "Logical Operators"
|
|
|
1392 content = function()
|
|
|
1393 %>
|
|
|
1394 <p>
|
|
|
1395 The logical operators in Luan are
|
|
|
1396 <b>and</b>, <b>or</b>, and <b>not</b>.
|
|
|
1397 The <b>and</b> and <b>or</b> operators consider both <b>false</b> and <b>nil</b> as false
|
|
|
1398 and anything else as true.
|
|
|
1399 Like the control structures (see <a href="#control">Control Structures</a>),
|
|
|
1400 the <b>not</b> operator requires a boolean value.
|
|
|
1401 </p>
|
|
|
1402
|
|
|
1403 <p>
|
|
|
1404 The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>.
|
|
|
1405 The conjunction operator <b>and</b> returns its first argument
|
|
|
1406 if this value is <b>false</b> or <b>nil</b>;
|
|
|
1407 otherwise, <b>and</b> returns its second argument.
|
|
|
1408 The disjunction operator <b>or</b> returns its first argument
|
|
|
1409 if this value is different from <b>nil</b> and <b>false</b>;
|
|
|
1410 otherwise, <b>or</b> returns its second argument.
|
|
|
1411 Both <b>and</b> and <b>or</b> use short-circuit evaluation;
|
|
|
1412 that is,
|
|
|
1413 the second operand is evaluated only if necessary.
|
|
|
1414 Here are some examples:
|
|
|
1415 </p>
|
|
|
1416
|
|
|
1417 <pre>
|
|
|
1418 10 or 20 --> 10
|
|
|
1419 10 or error() --> 10
|
|
|
1420 nil or "a" --> "a"
|
|
|
1421 nil and 10 --> nil
|
|
|
1422 false and error() --> false
|
|
|
1423 false and nil --> false
|
|
|
1424 false or nil --> nil
|
|
|
1425 10 and 20 --> 20
|
|
|
1426 </pre>
|
|
|
1427
|
|
|
1428 <p>
|
|
|
1429 (In this manual,
|
|
|
1430 <code>--></code> indicates the result of the preceding expression.)
|
|
|
1431 </p>
|
|
|
1432 <%
|
|
|
1433 end
|
|
|
1434 }
|
|
|
1435 concatenation = {
|
|
|
1436 title = "Concatenation"
|
|
|
1437 content = function()
|
|
|
1438 %>
|
|
|
1439 <p>
|
|
|
1440 The string concatenation operator in Luan is
|
|
|
1441 denoted by two dots ('<code>..</code>').
|
|
|
1442 All operands are converted to strings.
|
|
|
1443 </p>
|
|
|
1444 <%
|
|
|
1445 end
|
|
|
1446 }
|
|
|
1447 length = {
|
|
|
1448 title = "The Length Operator"
|
|
|
1449 content = function()
|
|
|
1450 %>
|
|
|
1451 <p>
|
|
|
1452 The length operator is denoted by the unary prefix operator <code>#</code>.
|
|
|
1453 The length of a string is its number of characters.
|
|
|
1454 The length of a binary is its number of bytes.
|
|
|
1455 </p>
|
|
|
1456
|
|
|
1457 <p>
|
|
|
1458 A program can modify the behavior of the length operator for
|
|
|
1459 any table through the <code>__len</code> metamethod (see <a href="#meta">Metatables and Metamethods</a>).
|
|
|
1460 </p>
|
|
|
1461
|
|
|
1462 <p>
|
|
|
1463 Unless a <code>__len</code> metamethod is given,
|
|
|
1464 the length of a table <code>t</code> is defined
|
|
|
1465 as the number of elements in <em>sequence</em>,
|
|
|
1466 that is,
|
|
|
1467 the size of the set of its positive numeric keys is equal to <em>{1..n}</em>
|
|
|
1468 for some non-negative integer <em>n</em>.
|
|
|
1469 In that case, <em>n</em> is its length.
|
|
|
1470 Note that a table like
|
|
|
1471 </p>
|
|
|
1472
|
|
|
1473 <pre>
|
|
|
1474 {10, 20, nil, 40}
|
|
|
1475 </pre>
|
|
|
1476
|
|
|
1477 <p>
|
|
|
1478 has a length of <code>2</code>, because that is the last key in sequence.
|
|
|
1479 </p>
|
|
|
1480 <%
|
|
|
1481 end
|
|
|
1482 }
|
|
|
1483 precedence = {
|
|
|
1484 title = "Precedence"
|
|
|
1485 content = function()
|
|
|
1486 %>
|
|
|
1487 <p>
|
|
|
1488 Operator precedence in Luan follows the table below,
|
|
|
1489 from lower to higher priority:
|
|
|
1490 </p>
|
|
|
1491
|
|
|
1492 <pre>
|
|
|
1493 or
|
|
|
1494 and
|
|
|
1495 < > <= >= ~= ==
|
|
|
1496 ..
|
|
|
1497 + -
|
|
|
1498 * / %
|
|
|
1499 unary operators (not # -)
|
|
|
1500 ^
|
|
|
1501 </pre>
|
|
|
1502
|
|
|
1503 <p>
|
|
|
1504 As usual,
|
|
|
1505 you can use parentheses to change the precedences of an expression.
|
|
|
1506 The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>')
|
|
|
1507 operators are right associative.
|
|
|
1508 All other binary operators are left associative.
|
|
|
1509 </p>
|
|
|
1510 <%
|
|
|
1511 end
|
|
|
1512 }
|
|
|
1513 constructors = {
|
|
|
1514 title = "Table Constructors"
|
|
|
1515 content = function()
|
|
|
1516 %>
|
|
|
1517 <p>
|
|
|
1518 Table constructors are expressions that create tables.
|
|
|
1519 Every time a constructor is evaluated, a new table is created.
|
|
|
1520 A constructor can be used to create an empty table
|
|
|
1521 or to create a table and initialize some of its fields.
|
|
|
1522 The general syntax for constructors is
|
|
|
1523 </p>
|
|
|
1524
|
|
|
1525 <pre>
|
|
|
1526 tableconstructor ::= ‘<b>{</b>’ fieldlist ‘<b>}</b>’
|
|
|
1527 fieldlist ::= [field] {fieldsep [field]}
|
|
|
1528 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp
|
|
|
1529 fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ | <b>end_of_line</b>
|
|
|
1530 </pre>
|
|
|
1531
|
|
|
1532 <p>
|
|
|
1533 Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry
|
|
|
1534 with key <code>exp1</code> and value <code>exp2</code>.
|
|
|
1535 A field of the form <code>name = exp</code> is equivalent to
|
|
|
1536 <code>["name"] = exp</code>.
|
|
|
1537 Finally, fields of the form <code>exp</code> are equivalent to
|
|
|
1538 <code>[i] = exp</code>, where <code>i</code> are consecutive integers
|
|
|
1539 starting with 1.
|
|
|
1540 Fields in the other formats do not affect this counting.
|
|
|
1541 For example,
|
|
|
1542 </p>
|
|
|
1543
|
|
|
1544 <pre>
|
|
|
1545 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
|
|
|
1546 </pre>
|
|
|
1547
|
|
|
1548 <p>
|
|
|
1549 is equivalent to
|
|
|
1550 </p>
|
|
|
1551
|
|
|
1552 <pre>
|
|
|
1553 do
|
|
|
1554 local t = {}
|
|
|
1555 t[f(1)] = g
|
|
|
1556 t[1] = "x" -- 1st exp
|
|
|
1557 t[2] = "y" -- 2nd exp
|
|
|
1558 t.x = 1 -- t["x"] = 1
|
|
|
1559 t[3] = f(x) -- 3rd exp
|
|
|
1560 t[30] = 23
|
|
|
1561 t[4] = 45 -- 4th exp
|
|
|
1562 a = t
|
|
|
1563 end
|
|
|
1564 </pre>
|
|
|
1565
|
|
|
1566 <p>
|
|
|
1567 The order of the assignments in a constructor is undefined.
|
|
|
1568 (This order would be relevant only when there are repeated keys.)
|
|
|
1569 </p>
|
|
|
1570
|
|
|
1571 <p>
|
|
|
1572 If the last field in the list has the form <code>exp</code>
|
|
|
1573 and the expression is a function call or a vararg expression,
|
|
|
1574 then all values returned by this expression enter the list consecutively
|
|
|
1575 (see <a href="#fn_calls">Function Calls</a>).
|
|
|
1576 </p>
|
|
|
1577
|
|
|
1578 <p>
|
|
|
1579 The field list can have an optional trailing separator,
|
|
|
1580 as a convenience for machine-generated code.
|
|
|
1581 </p>
|
|
|
1582 <%
|
|
|
1583 end
|
|
|
1584 }
|
|
|
1585 fn_calls = {
|
|
|
1586 title = "Function Calls"
|
|
|
1587 content = function()
|
|
|
1588 %>
|
|
|
1589 <p>
|
|
|
1590 A function call in Luan has the following syntax:
|
|
|
1591 </p>
|
|
|
1592
|
|
|
1593 <pre>
|
|
|
1594 functioncall ::= prefixexp args
|
|
|
1595 </pre>
|
|
|
1596
|
|
|
1597 <p>
|
|
|
1598 In a function call,
|
|
|
1599 first prefixexp and args are evaluated.
|
|
|
1600 The value of prefixexp must have type <em>function</em>.
|
|
|
1601 This function is called
|
|
|
1602 with the given arguments.
|
|
|
1603 </p>
|
|
|
1604
|
|
|
1605 <p>
|
|
|
1606 Arguments have the following syntax:
|
|
|
1607 </p>
|
|
|
1608
|
|
|
1609 <pre>
|
|
|
1610 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’
|
|
|
1611 args ::= tableconstructor
|
|
|
1612 args ::= LiteralString
|
|
|
1613 </pre>
|
|
|
1614
|
|
|
1615 <p>
|
|
|
1616 All argument expressions are evaluated before the call.
|
|
|
1617 A call of the form <code>f{<em>fields</em>}</code> is
|
|
|
1618 syntactic sugar for <code>f({<em>fields</em>})</code>;
|
|
|
1619 that is, the argument list is a single new table.
|
|
|
1620 A call of the form <code>f'<em>string</em>'</code>
|
|
|
1621 (or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>)
|
|
|
1622 is syntactic sugar for <code>f('<em>string</em>')</code>;
|
|
|
1623 that is, the argument list is a single literal string.
|
|
|
1624 </p>
|
|
|
1625 <%
|
|
|
1626 end
|
|
|
1627 }
|
|
|
1628 fn_def = {
|
|
|
1629 title = "Function Definitions"
|
|
|
1630 content = function()
|
|
|
1631 %>
|
|
|
1632 <p>
|
|
|
1633 The syntax for function definition is
|
|
|
1634 </p>
|
|
|
1635
|
|
|
1636 <pre>
|
|
|
1637 functiondef ::= <b>function</b> funcbody
|
|
|
1638 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block end_function
|
|
|
1639 end_function ::= <b>end_function</b> | <b>end</b>
|
|
|
1640 </pre>
|
|
|
1641
|
|
|
1642 <p>
|
|
|
1643 The following syntactic sugar simplifies function definitions:
|
|
|
1644 </p>
|
|
|
1645
|
|
|
1646 <pre>
|
|
|
1647 stat ::= <b>function</b> funcname funcbody
|
|
|
1648 stat ::= <b>local</b> <b>function</b> Name funcbody
|
|
|
1649 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name]
|
|
|
1650 </pre>
|
|
|
1651
|
|
|
1652 <p>
|
|
|
1653 The statement
|
|
|
1654 </p>
|
|
|
1655
|
|
|
1656 <pre>
|
|
|
1657 function f () <em>body</em> end
|
|
|
1658 </pre>
|
|
|
1659
|
|
|
1660 <p>
|
|
|
1661 translates to
|
|
|
1662 </p>
|
|
|
1663
|
|
|
1664 <pre>
|
|
|
1665 f = function () <em>body</em> end
|
|
|
1666 </pre>
|
|
|
1667
|
|
|
1668 <p>
|
|
|
1669 The statement
|
|
|
1670 <p>
|
|
|
1671
|
|
|
1672 <pre>
|
|
|
1673 function t.a.b.c.f () <em>body</em> end
|
|
|
1674 </pre>
|
|
|
1675
|
|
|
1676 <p>
|
|
|
1677 translates to
|
|
|
1678 </p>
|
|
|
1679
|
|
|
1680 <pre>
|
|
|
1681 t.a.b.c.f = function () <em>body</em> end
|
|
|
1682 </pre>
|
|
|
1683
|
|
|
1684 <p>
|
|
|
1685 The statement
|
|
|
1686 </p>
|
|
|
1687
|
|
|
1688 <pre>
|
|
|
1689 local function f () <em>body</em> end
|
|
|
1690 </pre>
|
|
|
1691
|
|
|
1692 <p>
|
|
|
1693 translates to
|
|
|
1694 </p>
|
|
|
1695
|
|
|
1696 <pre>
|
|
|
1697 local f; f = function () <em>body</em> end
|
|
|
1698 </pre>
|
|
|
1699
|
|
|
1700 <p>
|
|
|
1701 not to
|
|
|
1702 </p>
|
|
|
1703
|
|
|
1704 <pre>
|
|
|
1705 local f = function () <em>body</em> end
|
|
|
1706 </pre>
|
|
|
1707
|
|
|
1708 <p>
|
|
|
1709 (This only makes a difference when the body of the function
|
|
|
1710 contains references to <code>f</code>.)
|
|
|
1711 </p>
|
|
|
1712
|
|
|
1713 <p>
|
|
|
1714 A function definition is an executable expression,
|
|
|
1715 whose value has type <em>function</em>.
|
|
|
1716 When Luan precompiles a chunk,
|
|
|
1717 all its function bodies are precompiled too.
|
|
|
1718 Then, whenever Luan executes the function definition,
|
|
|
1719 the function is <em>instantiated</em> (or <em>closed</em>).
|
|
|
1720 This function instance (or <em>closure</em>)
|
|
|
1721 is the final value of the expression.
|
|
|
1722 </p>
|
|
|
1723
|
|
|
1724 <p>
|
|
|
1725 Parameters act as local variables that are
|
|
|
1726 initialized with the argument values:
|
|
|
1727 </p>
|
|
|
1728
|
|
|
1729 <pre>
|
|
|
1730 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’
|
|
|
1731 </pre>
|
|
|
1732
|
|
|
1733 <p>
|
|
|
1734 When a function is called,
|
|
|
1735 the list of arguments is adjusted to
|
|
|
1736 the length of the list of parameters if the list is too short,
|
|
|
1737 unless the function is a <em>vararg function</em>,
|
|
|
1738 which is indicated by three dots ('<code>...</code>')
|
|
|
1739 at the end of its parameter list.
|
|
|
1740 A vararg function does not adjust its argument list;
|
|
|
1741 instead, it collects all extra arguments and supplies them
|
|
|
1742 to the function through a <em>vararg expression</em>,
|
|
|
1743 which is also written as three dots.
|
|
|
1744 The value of this expression is a list of all actual extra arguments,
|
|
|
1745 similar to a function with multiple results.
|
|
|
1746 If a vararg expression is used inside another expression
|
|
|
1747 or in the middle of a list of expressions,
|
|
|
1748 then its return list is adjusted to one element.
|
|
|
1749 If the expression is used as the last element of a list of expressions,
|
|
|
1750 then no adjustment is made
|
|
|
1751 (unless that last expression is enclosed in parentheses).
|
|
|
1752 </p>
|
|
|
1753
|
|
|
1754 <p>
|
|
|
1755 As an example, consider the following definitions:
|
|
|
1756 </p>
|
|
|
1757 <pre>
|
|
|
1758 function f(a, b) end
|
|
|
1759 function g(a, b, ...) end
|
|
|
1760 function r() return 1,2,3 end
|
|
|
1761 </pre>
|
|
|
1762
|
|
|
1763 <p>
|
|
|
1764 Then, we have the following mapping from arguments to parameters and
|
|
|
1765 to the vararg expression:
|
|
|
1766 </p>
|
|
|
1767 <pre>
|
|
|
1768 CALL PARAMETERS
|
|
|
1769
|
|
|
1770 f(3) a=3, b=nil
|
|
|
1771 f(3, 4) a=3, b=4
|
|
|
1772 f(3, 4, 5) runtime error
|
|
|
1773 f(r(), 10) runtime error
|
|
|
1774 f(r()) runtime error
|
|
|
1775
|
|
|
1776 g(3) a=3, b=nil, ... --> (nothing)
|
|
|
1777 g(3, 4) a=3, b=4, ... --> (nothing)
|
|
|
1778 g(3, 4, 5, 8) a=3, b=4, ... --> 5 8
|
|
|
1779 g(5, r()) a=5, b=1, ... --> 2 3
|
|
|
1780 </pre>
|
|
|
1781
|
|
|
1782 <p>
|
|
|
1783 Results are returned using the <b>return</b> statement (see <a href="#control">Control Structures</a>).
|
|
|
1784 If control reaches the end of a function
|
|
|
1785 without encountering a <b>return</b> statement,
|
|
|
1786 then the function returns with no results.
|
|
|
1787 </p>
|
|
|
1788 <%
|
|
|
1789 end
|
|
|
1790 }
|
|
|
1791 }
|
|
|
1792 }
|
|
|
1793 visibility = {
|
|
|
1794 title = "Visibility Rules"
|
|
|
1795 content = function()
|
|
|
1796 %>
|
|
|
1797 <p>
|
|
|
1798 Luan is a lexically scoped language.
|
|
|
1799 The scope of a local variable begins at the first statement after
|
|
|
1800 its declaration and lasts until the last non-void statement
|
|
|
1801 of the innermost block that includes the declaration.
|
|
|
1802 Consider the following example:
|
|
|
1803 </p>
|
|
|
1804 <pre>
|
|
|
1805 x = 10 -- global variable
|
|
|
1806 do -- new block
|
|
|
1807 local x = x -- new 'x', with value 10
|
|
|
1808 print(x) --> 10
|
|
|
1809 x = x+1
|
|
|
1810 do -- another block
|
|
|
1811 local x = x+1 -- another 'x'
|
|
|
1812 print(x) --> 12
|
|
|
1813 end
|
|
|
1814 print(x) --> 11
|
|
|
1815 end
|
|
|
1816 print(x) --> 10 (the global one)
|
|
|
1817 </pre>
|
|
|
1818
|
|
|
1819 <p>
|
|
|
1820 Notice that, in a declaration like <code>local x = x</code>,
|
|
|
1821 the new <code>x</code> being declared is not in scope yet,
|
|
|
1822 and so the second <code>x</code> refers to the outside variable.
|
|
|
1823 </p>
|
|
|
1824
|
|
|
1825 <p>
|
|
|
1826 Because of the lexical scoping rules,
|
|
|
1827 local variables can be freely accessed by functions
|
|
|
1828 defined inside their scope.
|
|
|
1829 A local variable used by an inner function is called
|
|
|
1830 an <em>upvalue</em>, or <em>external local variable</em>,
|
|
|
1831 inside the inner function.
|
|
|
1832 </p>
|
|
|
1833
|
|
|
1834 <p>
|
|
|
1835 Notice that each execution of a <b>local</b> statement
|
|
|
1836 defines new local variables.
|
|
|
1837 Consider the following example:
|
|
|
1838 </p>
|
|
|
1839 <pre>
|
|
|
1840 a = {}
|
|
|
1841 local x = 20
|
|
|
1842 for i=1,10 do
|
|
|
1843 local y = 0
|
|
|
1844 a[i] = function () y=y+1; return x+y end
|
|
|
1845 end
|
|
|
1846 </pre>
|
|
|
1847
|
|
|
1848 <p>
|
|
|
1849 The loop creates ten closures
|
|
|
1850 (that is, ten instances of the anonymous function).
|
|
|
1851 Each of these closures uses a different <code>y</code> variable,
|
|
|
1852 while all of them share the same <code>x</code>.
|
|
|
1853 </p>
|
|
|
1854 <%
|
|
|
1855 end
|
|
|
1856 }
|
|
|
1857 }
|
|
|
1858 }
|
|
|
1859 libs = {
|
|
|
1860 title = "Standard Libraries"
|
|
|
1861 content = function()
|
|
|
1862 %>
|
|
|
1863 <p>
|
|
|
1864 The standard Luan libraries provide useful functions
|
|
|
1865 that are implemented both in Java and in Luan itself.
|
|
|
1866 How each function is implemented shouldn't matter to the user.
|
|
|
1867 Some of these functions provide essential services to the language
|
|
|
1868 (e.g., <a href="#Luan.type"><code>type</code></a> and <a href="#Luan.get_metatable"><code>get_metatable</code></a>);
|
|
|
1869 others provide access to "outside" services (e.g., I/O).
|
|
|
1870 </p>
|
|
|
1871 <%
|
|
|
1872 end
|
|
|
1873 subs = {
|
|
|
1874 default_lib = {
|
|
|
1875 title = "Default Environment"
|
|
|
1876 content = function()
|
|
|
1877 %>
|
|
|
1878 <p>
|
|
|
1879 This is provided by default as a local variable for any Luan code as described in <a href="#env">Environments</a>.
|
|
|
1880 </p>
|
|
|
1881 <%
|
|
|
1882 end
|
|
|
1883 subs = {
|
|
|
1884 require = {
|
|
|
1885 title = "<code>require (mod_uri)</code>"
|
|
|
1886 content = function()
|
|
|
1887 %>
|
|
|
1888 <p>
|
|
|
1889 Example use:
|
|
|
1890 </p>
|
|
|
1891 <pre>
|
|
|
1892 local Table = require "luan:Table.luan"
|
|
|
1893 </pre>
|
|
|
1894
|
|
|
1895 <p>
|
|
|
1896 Could be defined as:
|
|
|
1897 </p>
|
|
|
1898 <pre>
|
|
|
1899 local function require(mod_name)
|
|
|
1900 return <a href="#Package.load">Package.load</a>(mod_name) or <a href="#Luan.error">Luan.error</a>("module '"..mod_name.."' not found")
|
|
|
1901 end
|
|
|
1902 </pre>
|
|
|
1903
|
|
|
1904 <p>
|
|
|
1905 A special case is:
|
|
|
1906 </p>
|
|
|
1907 <pre>
|
|
|
1908 require "java"
|
|
|
1909 </pre>
|
|
|
1910
|
|
|
1911 <p>
|
|
|
1912 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.
|
|
|
1913 </p>
|
|
|
1914 <%
|
|
|
1915 end
|
|
|
1916 }
|
|
|
1917 }
|
|
|
1918 }
|
|
|
1919 luan_lib = {
|
|
|
1920 title = "Basic Functions"
|
|
|
1921 content = function()
|
|
|
1922 %>
|
|
|
1923 <p>
|
|
|
1924 Include this library by:
|
|
|
1925 </p>
|
|
|
1926 <pre>
|
|
|
1927 local Luan = require "luan:Luan.luan"
|
|
|
1928 </pre>
|
|
|
1929
|
|
|
1930 <p>
|
|
|
1931 The basic library provides basic functions to Luan that don't depend on other libaries.
|
|
|
1932 </p>
|
|
|
1933 <%
|
|
|
1934 end
|
|
|
1935 subs = {
|
|
|
1936 ["Luan.do_file"] = {
|
|
|
1937 title = "<code>Luan.do_file ([uri])</code>"
|
|
|
1938 content = function()
|
|
|
1939 %>
|
|
|
1940 <p>
|
|
|
1941 Could be defined as:
|
|
|
1942 </p>
|
|
|
1943 <pre>
|
|
|
1944 function Luan.do_file(uri)
|
|
|
1945 local fn = <a href="#Luan.load_file">Luan.load_file</a>(uri) or <a href="#Luan.error">Luan.error</a>("file '"..uri.."' not found")
|
|
|
1946 return fn()
|
|
|
1947 end
|
|
|
1948 </pre>
|
|
|
1949 <%
|
|
|
1950 end
|
|
|
1951 }
|
|
|
1952 ["Luan.error"] = {
|
|
|
1953 title = "<code>Luan.error (message)</code>"
|
|
|
1954 content = function()
|
|
|
1955 %>
|
|
|
1956 <p>
|
|
|
1957 Throws an error containing the message.
|
|
|
1958 </p>
|
|
|
1959
|
|
|
1960 <p>
|
|
|
1961 Could be defined as:
|
|
|
1962 </p>
|
|
|
1963 <pre>
|
|
|
1964 function Luan.error(message)
|
|
|
1965 <a href="#Luan.new_error">Luan.new_error</a>(message).throw()
|
|
|
1966 end
|
|
|
1967 </pre>
|
|
|
1968 <%
|
|
|
1969 end
|
|
|
1970 }
|
|
|
1971 ["Luan.eval"] = {
|
|
|
1972 title = "<code>Luan.eval (text [, source_name [, env]])</code>"
|
|
|
1973 content = function()
|
|
|
1974 %>
|
|
|
1975 <p>
|
|
|
1976 Evaluates <code>text</code> as a Luan expression.
|
|
|
1977 </p>
|
|
|
1978
|
|
|
1979 <p>
|
|
|
1980 Could be defined as:
|
|
|
1981 </p>
|
|
|
1982 <pre>
|
|
|
1983 function Luan.eval(text,source_name, env)
|
|
|
1984 return <a href="#Luan.load">Luan.load</a>( "return "..text, source_name or "eval", env )()
|
|
|
1985 end
|
|
|
1986 </pre>
|
|
|
1987 <%
|
|
|
1988 end
|
|
|
1989 }
|
|
|
1990 ["Luan.get_metatable"] = {
|
|
|
1991 title = "<code>Luan.get_metatable (table)</code>"
|
|
|
1992 content = function()
|
|
|
1993 %>
|
|
|
1994 <p>
|
|
|
1995 If <code>table</code> does not have a metatable, returns <b>nil</b>.
|
|
|
1996 Otherwise,
|
|
|
1997 if the table's metatable has a <code>"__metatable"</code> field,
|
|
|
1998 returns the associated value.
|
|
|
1999 Otherwise, returns the metatable of the given table.
|
|
|
2000 </p>
|
|
|
2001 <%
|
|
|
2002 end
|
|
|
2003 }
|
|
|
2004 ["Luan.hash_code"] = {
|
|
|
2005 title = "<code>Luan.hash_code (v)</code>"
|
|
|
2006 content = function()
|
|
|
2007 %>
|
|
|
2008 <p>
|
|
|
2009 Returns the hash code of <code>v</code>.
|
|
|
2010 </p>
|
|
|
2011 <%
|
|
|
2012 end
|
|
|
2013 }
|
|
|
2014 ["Luan.ipairs"] = {
|
|
|
2015 title = "<code>Luan.ipairs (t)</code>"
|
|
|
2016 content = function()
|
|
|
2017 %>
|
|
|
2018 <p>
|
|
|
2019 Returns an iterator function
|
|
|
2020 so that the construction
|
|
|
2021 </p>
|
|
|
2022 <pre>
|
|
|
2023 for i,v in ipairs(t) do <em>body</em> end
|
|
|
2024 </pre>
|
|
|
2025
|
|
|
2026 <p>
|
|
|
2027 will iterate over the key–value pairs
|
|
|
2028 (<code>1,t[1]</code>), (<code>2,t[2]</code>), ...,
|
|
|
2029 up to the first nil value.
|
|
|
2030 </p>
|
|
|
2031
|
|
|
2032 <p>
|
|
|
2033 Could be defined as:
|
|
|
2034 </p>
|
|
|
2035 <pre>
|
|
|
2036 function Luan.ipairs(t)
|
|
|
2037 local i = 0
|
|
|
2038 return function()
|
|
|
2039 if i < #t then
|
|
|
2040 i = i + 1
|
|
|
2041 return i, t[i]
|
|
|
2042 end
|
|
|
2043 end
|
|
|
2044 end
|
|
|
2045 </pre>
|
|
|
2046 <%
|
|
|
2047 end
|
|
|
2048 }
|
|
|
2049 ["Luan.load"] = {
|
|
|
2050 title = "<code>Luan.load (text, [source_name [, env [, persist]]])</code>"
|
|
|
2051 content = function()
|
|
|
2052 %>
|
|
|
2053 <p>
|
|
|
2054 Loads a chunk.
|
|
|
2055 </p>
|
|
|
2056
|
|
|
2057 <p>
|
|
|
2058 The <code>text</code> is compiled.
|
|
|
2059 If there are no syntactic errors,
|
|
|
2060 returns the compiled chunk as a function;
|
|
|
2061 otherwise, throws an error.
|
|
|
2062 </p>
|
|
|
2063
|
|
|
2064 <p>
|
|
|
2065 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".
|
|
|
2066 </p>
|
|
|
2067
|
|
|
2068 <p>
|
|
|
2069 If the <code>env</code> parameter is supplied, it becomes the <code>_ENV</code> of the chunk.
|
|
|
2070 </p>
|
|
|
2071
|
|
|
2072 <p>
|
|
|
2073 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>.
|
|
|
2074 </p>
|
|
|
2075 <%
|
|
|
2076 end
|
|
|
2077 }
|
|
|
2078 ["Luan.load_file"] = {
|
|
|
2079 title = "<code>Luan.load_file (file_uri)</code>"
|
|
|
2080 content = function()
|
|
|
2081 %>
|
|
|
2082 <p>
|
|
|
2083 Similar to <a href="#Luan.load"><code>load</code></a>,
|
|
|
2084 but gets the chunk from file <code>file_uri</code>.
|
|
|
2085 <code>file_uri</code> can be a string or a uri table.
|
|
|
2086 </p>
|
|
|
2087 <%
|
|
|
2088 end
|
|
|
2089 }
|
|
|
2090 ["Luan.new_error"] = {
|
|
|
2091 title = "<code>Luan.new_error (message)</code>"
|
|
|
2092 content = function()
|
|
|
2093 %>
|
|
|
2094 <p>
|
|
|
2095 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.
|
|
|
2096 </p>
|
|
|
2097
|
|
|
2098 <p>
|
|
|
2099 To print the current stack trace, you could do:
|
|
|
2100 </p>
|
|
|
2101 <pre>
|
|
|
2102 Io.print( Luan.new_error "stack" )
|
|
|
2103 </pre>
|
|
|
2104 <%
|
|
|
2105 end
|
|
|
2106 }
|
|
|
2107 ["Luan.pairs"] = {
|
|
|
2108 title = "<code>Luan.pairs (t)</code>"
|
|
|
2109 content = function()
|
|
|
2110 %>
|
|
|
2111 <p>
|
|
|
2112 If <code>t</code> has a metamethod <code>__pairs</code>,
|
|
|
2113 calls it with <code>t</code> as argument and returns the
|
|
|
2114 result from the call.
|
|
|
2115 </p>
|
|
|
2116
|
|
|
2117 <p>
|
|
|
2118 Otherwise,
|
|
|
2119 returns a function
|
|
|
2120 so that the construction
|
|
|
2121 </p>
|
|
|
2122 <pre>
|
|
|
2123 for k,v in pairs(t) do <em>body</em> end
|
|
|
2124 </pre>
|
|
|
2125
|
|
|
2126 <p>
|
|
|
2127 will iterate over all key–value pairs of table <code>t</code>.
|
|
|
2128 </p>
|
|
|
2129 <%
|
|
|
2130 end
|
|
|
2131 }
|
|
|
2132 ["Luan.range"] = {
|
|
|
2133 title = "<code>Luan.range (start, stop [, step])</code>"
|
|
|
2134 content = function()
|
|
|
2135 %>
|
|
|
2136 <p>
|
|
|
2137 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.
|
|
|
2138 </p>
|
|
|
2139
|
|
|
2140 <p>
|
|
|
2141 Example use:
|
|
|
2142 </p>
|
|
|
2143 <pre>
|
|
|
2144 for i in range(1,10) do
|
|
|
2145 Io.print("count up:",i)
|
|
|
2146 end
|
|
|
2147 for i in range(10,0,-1) do
|
|
|
2148 Io.print("count down:",i)
|
|
|
2149 end
|
|
|
2150 </pre>
|
|
|
2151
|
|
|
2152 <p>
|
|
|
2153 Could be defined as:
|
|
|
2154 </p>
|
|
|
2155 <pre>
|
|
|
2156 function Luan.range(start, stop, step)
|
|
|
2157 step = step or 1
|
|
|
2158 step == 0 and <a href="#Luan.error">Luan.error</a> "bad argument #3 (step may not be zero)"
|
|
|
2159 local i = start
|
|
|
2160 return function()
|
|
|
2161 if step > 0 and i <= stop or step < 0 and i >= stop then
|
|
|
2162 local rtn = i
|
|
|
2163 i = i + step
|
|
|
2164 return rtn
|
|
|
2165 end
|
|
|
2166 end
|
|
|
2167 end
|
|
|
2168 </pre>
|
|
|
2169 <%
|
|
|
2170 end
|
|
|
2171 }
|
|
|
2172 ["Luan.raw_equal"] = {
|
|
|
2173 title = "<code>Luan.raw_equal (v1, v2)</code>"
|
|
|
2174 content = function()
|
|
|
2175 %>
|
|
|
2176 <p>
|
|
|
2177 Checks whether <code>v1</code> is equal to <code>v2</code>,
|
|
|
2178 without invoking any metamethod.
|
|
|
2179 Returns a boolean.
|
|
|
2180 </p>
|
|
|
2181 <%
|
|
|
2182 end
|
|
|
2183 }
|
|
|
2184 ["Luan.raw_get"] = {
|
|
|
2185 title = "<code>Luan.raw_get (table, index)</code>"
|
|
|
2186 content = function()
|
|
|
2187 %>
|
|
|
2188 <p>
|
|
|
2189 Gets the real value of <code>table[index]</code>,
|
|
|
2190 without invoking any metamethod.
|
|
|
2191 <code>table</code> must be a table;
|
|
|
2192 <code>index</code> may be any value.
|
|
|
2193 </p>
|
|
|
2194 <%
|
|
|
2195 end
|
|
|
2196 }
|
|
|
2197 ["Luan.raw_len"] = {
|
|
|
2198 title = "<code>Luan.raw_len (v)</code>"
|
|
|
2199 content = function()
|
|
|
2200 %>
|
|
|
2201 <p>
|
|
|
2202 Returns the length of the object <code>v</code>,
|
|
|
2203 which must be a table or a string,
|
|
|
2204 without invoking any metamethod.
|
|
|
2205 Returns an integer.
|
|
|
2206 </p>
|
|
|
2207 <%
|
|
|
2208 end
|
|
|
2209 }
|
|
|
2210 ["Luan.raw_set"] = {
|
|
|
2211 title = "<code>Luan.raw_set (table, index, value)</code>"
|
|
|
2212 content = function()
|
|
|
2213 %>
|
|
|
2214 <p>
|
|
|
2215 Sets the real value of <code>table[index]</code> to <code>value</code>,
|
|
|
2216 without invoking any metamethod.
|
|
|
2217 <code>table</code> must be a table,
|
|
|
2218 <code>index</code> any value different from <b>nil</b>,
|
|
|
2219 and <code>value</code> any Luan value.
|
|
|
2220 </p>
|
|
|
2221 <%
|
|
|
2222 end
|
|
|
2223 }
|
|
|
2224 ["Luan.set_metatable"] = {
|
|
|
2225 title = "<code>Luan.set_metatable (table, metatable)</code>"
|
|
|
2226 content = function()
|
|
|
2227 %>
|
|
|
2228 <p>
|
|
|
2229 Sets the metatable for the given table.
|
|
|
2230 If <code>metatable</code> is <b>nil</b>,
|
|
|
2231 removes the metatable of the given table.
|
|
|
2232 If the original metatable has a <code>"__metatable"</code> field,
|
|
|
2233 raises an error.
|
|
|
2234 </p>
|
|
|
2235 <%
|
|
|
2236 end
|
|
|
2237 }
|
|
|
2238 ["Luan.stringify"] = {
|
|
|
2239 title = "<code>Luan.stringify (v [,options])</code>"
|
|
|
2240 content = function()
|
|
|
2241 %>
|
|
|
2242 <p>
|
|
|
2243 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.
|
|
|
2244 </p>
|
|
|
2245 <%
|
|
|
2246 end
|
|
|
2247 }
|
|
|
2248 ["Luan.to_string"] = {
|
|
|
2249 title = "<code>Luan.to_string (v)</code>"
|
|
|
2250 content = function()
|
|
|
2251 %>
|
|
|
2252 <p>
|
|
|
2253 Receives a value of any type and
|
|
|
2254 converts it to a string in a human-readable format.
|
|
|
2255 </p>
|
|
|
2256
|
|
|
2257 <p>
|
|
|
2258 If the metatable of <code>v</code> has a <code>"__to_string"</code> field,
|
|
|
2259 then <code>to_string</code> calls the corresponding value
|
|
|
2260 with <code>v</code> as argument,
|
|
|
2261 and uses the result of the call as its result.
|
|
|
2262 </p>
|
|
|
2263 <%
|
|
|
2264 end
|
|
|
2265 }
|
|
|
2266 ["Luan.type"] = {
|
|
|
2267 title = "<code>Luan.type (v)</code>"
|
|
|
2268 content = function()
|
|
|
2269 %>
|
|
|
2270 <p>
|
|
|
2271 Returns the type of its only argument, coded as a string.
|
|
|
2272 The possible results of this function are
|
|
|
2273 "<code>nil</code>" (a string, not the value <b>nil</b>),
|
|
|
2274 "<code>number</code>",
|
|
|
2275 "<code>string</code>",
|
|
|
2276 "<code>binary</code>",
|
|
|
2277 "<code>boolean</code>",
|
|
|
2278 "<code>table</code>",
|
|
|
2279 "<code>function</code>",
|
|
|
2280 and "<code>java</code>".
|
|
|
2281 </p>
|
|
|
2282 <%
|
|
|
2283 end
|
|
|
2284 }
|
|
|
2285 ["Luan.values"] = {
|
|
|
2286 title = "<code>Luan.values (···)</code>"
|
|
|
2287 content = function()
|
|
|
2288 %>
|
|
|
2289 <p>
|
|
|
2290 Returns a function so that the construction
|
|
|
2291 </p>
|
|
|
2292 <pre>
|
|
|
2293 for i, v in Luan.values(···) do <em>body</em> end
|
|
|
2294 </pre>
|
|
|
2295
|
|
|
2296 <p>
|
|
|
2297 will iterate over all values of <code>···</code>.
|
|
|
2298 </p>
|
|
|
2299 <%
|
|
|
2300 end
|
|
|
2301 }
|
|
|
2302 ["Luan.VERSION"] = {
|
|
|
2303 title = "<code>Luan.VERSION</code>"
|
|
|
2304 content = function()
|
|
|
2305 %>
|
|
|
2306 <p>
|
|
|
2307 A global variable (not a function) that
|
|
|
2308 holds a string containing the current Luan version.
|
|
|
2309 </p>
|
|
|
2310 <%
|
|
|
2311 end
|
|
|
2312 }
|
|
|
2313 }
|
|
|
2314 }
|
|
|
2315 package_lib = {
|
|
|
2316 title = "Modules"
|
|
|
2317 content = function()
|
|
|
2318 %>
|
|
|
2319 <p>
|
|
|
2320 Include this library by:
|
|
|
2321 </p>
|
|
|
2322 <pre>
|
|
|
2323 local Package = require "luan:Package.luan"
|
|
|
2324 </pre>
|
|
|
2325
|
|
|
2326 <p>
|
|
|
2327 The package library provides basic
|
|
|
2328 facilities for loading modules in Luan.
|
|
|
2329 </p>
|
|
|
2330 <%
|
|
|
2331 end
|
|
|
2332 subs = {
|
|
|
2333 ["Package.load"] = {
|
|
|
2334 title = "<code>Package.load (mod_uri)</code>"
|
|
|
2335 content = function()
|
|
|
2336 %>
|
|
|
2337 <p>
|
|
|
2338 Loads the given module.
|
|
|
2339 The function starts by looking into the <a href="#Package.loaded"><code>Package.loaded</code></a> table
|
|
|
2340 to determine whether <code>mod_uri</code> is already loaded.
|
|
|
2341 If it is, then <code>Package.load</code> returns the value stored
|
|
|
2342 at <code>Package.loaded[mod_uri]</code>.
|
|
|
2343 Otherwise, it tries to load a new value for the module.
|
|
|
2344 </p>
|
|
|
2345
|
|
|
2346 <p>
|
|
|
2347 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.
|
|
|
2348 </p>
|
|
|
2349
|
|
|
2350 <p>
|
|
|
2351 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.
|
|
|
2352 </p>
|
|
|
2353
|
|
|
2354 <p>
|
|
|
2355 If a new value for the module successful loaded, then it is stored in <code>Package.loaded[mod_uri]</code>. The value is returned.
|
|
|
2356 </p>
|
|
|
2357 <%
|
|
|
2358 end
|
|
|
2359 }
|
|
|
2360 ["Package.loaded"] = {
|
|
|
2361 title = "<code>Package.loaded</code>"
|
|
|
2362 content = function()
|
|
|
2363 %>
|
|
|
2364 <p>
|
|
|
2365 A table used by <a href="#Package.load"><code>Package.load</code></a> to control which
|
|
|
2366 modules are already loaded.
|
|
|
2367 When you load a module <code>mod_uri</code> and
|
|
|
2368 <code>Package.loaded[mod_uri]</code> is not <b>nil</b>,
|
|
|
2369 <a href="#Package.load"><code>Package.load</code></a> simply returns the value stored there.
|
|
|
2370 </p>
|
|
|
2371
|
|
|
2372 <p>
|
|
|
2373 This variable is only a reference to the real table;
|
|
|
2374 assignments to this variable do not change the
|
|
|
2375 table used by <a href="#Package.load"><code>Package.load</code></a>.
|
|
|
2376 </p>
|
|
|
2377 <%
|
|
|
2378 end
|
|
|
2379 }
|
|
1656
|
2380 }
|
|
|
2381 }
|
|
1668
|
2382 string_lib = {
|
|
|
2383 title = "String Manipulation"
|
|
|
2384 content = function()
|
|
|
2385 %>
|
|
|
2386 <p>
|
|
|
2387 Include this library by:
|
|
|
2388 </p>
|
|
|
2389 <pre>
|
|
|
2390 local String = require "luan:String.luan"
|
|
|
2391 </pre>
|
|
|
2392
|
|
|
2393 <p>
|
|
|
2394 This library provides generic functions for string manipulation,
|
|
|
2395 such as finding and extracting substrings, and pattern matching.
|
|
|
2396 When indexing a string in Luan, the first character is at position 1
|
|
|
2397 (not at 0, as in Java).
|
|
|
2398 Indices are allowed to be negative and are interpreted as indexing backwards,
|
|
|
2399 from the end of the string.
|
|
|
2400 Thus, the last character is at position -1, and so on.
|
|
|
2401 </p>
|
|
|
2402 <%
|
|
|
2403 end
|
|
|
2404 subs = {
|
|
|
2405 ["String.char"] = {
|
|
|
2406 title = "<code>String.char (···)</code>"
|
|
|
2407 content = function()
|
|
|
2408 %>
|
|
|
2409 <p>
|
|
|
2410 Receives zero or more integers.
|
|
|
2411 Returns a string with length equal to the number of arguments,
|
|
|
2412 in which each character has the internal numerical code equal
|
|
|
2413 to its corresponding argument.
|
|
|
2414 </p>
|
|
|
2415 <%
|
|
|
2416 end
|
|
|
2417 }
|
|
1716
|
2418 ["String.contains"] = {
|
|
|
2419 title = "<code>String.contains (s, s2)</code>"
|
|
|
2420 content = function()
|
|
|
2421 %>
|
|
|
2422 <p>
|
|
|
2423 Returns a boolean indicating whether the <code>s</code> contains <code>s2</code>.
|
|
|
2424 </p>
|
|
|
2425 <%
|
|
|
2426 end
|
|
|
2427 }
|
|
1668
|
2428 ["String.encode"] = {
|
|
|
2429 title = "<code>String.encode (s)</code>"
|
|
|
2430 content = function()
|
|
|
2431 %>
|
|
|
2432 <p>
|
|
|
2433 Encodes argument <code>s</code> into a string that can be placed in quotes so as to return the original value of the string.
|
|
|
2434 </p>
|
|
|
2435 <%
|
|
|
2436 end
|
|
|
2437 }
|
|
1716
|
2438 ["String.ends_with"] = {
|
|
|
2439 title = "<code>String.ends_with (s, s2)</code>"
|
|
|
2440 content = function()
|
|
|
2441 %>
|
|
|
2442 <p>
|
|
|
2443 Returns a boolean indicating whether the <code>s</code> ends with <code>s2</code>.
|
|
|
2444 </p>
|
|
|
2445 <%
|
|
|
2446 end
|
|
|
2447 }
|
|
1668
|
2448 ["String.find"] = {
|
|
|
2449 title = "<code>String.find (s, pattern [, init [, plain]])</code>"
|
|
|
2450 content = function()
|
|
|
2451 %>
|
|
|
2452 <p>
|
|
|
2453 Looks for the first match of
|
|
|
2454 <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>.
|
|
|
2455 If it finds a match, then <code>find</code> returns the indices of <code>s</code>
|
|
|
2456 where this occurrence starts and ends;
|
|
|
2457 otherwise, it returns <b>nil</b>.
|
|
|
2458 A third, optional numerical argument <code>init</code> specifies
|
|
|
2459 where to start the search;
|
|
|
2460 its default value is 1 and can be negative.
|
|
|
2461 A value of <b>true</b> as a fourth, optional argument <code>plain</code>
|
|
|
2462 turns off the pattern matching facilities,
|
|
|
2463 so the function does a plain "find substring" operation,
|
|
|
2464 with no characters in <code>pattern</code> being considered magic.
|
|
|
2465 Note that if <code>plain</code> is given, then <code>init</code> must be given as well.
|
|
|
2466 </p>
|
|
|
2467
|
|
|
2468 <p>
|
|
|
2469 If the pattern has captures,
|
|
|
2470 then in a successful match
|
|
|
2471 the captured values are also returned,
|
|
|
2472 after the two indices.
|
|
|
2473 </p>
|
|
|
2474 <%
|
|
|
2475 end
|
|
|
2476 }
|
|
|
2477 ["String.format"] = {
|
|
|
2478 title = "<code>String.format (formatstring, ···)</code>"
|
|
|
2479 content = function()
|
|
|
2480 %>
|
|
|
2481 <p>
|
|
|
2482 Returns a formatted version of its variable number of arguments
|
|
|
2483 following the description given in its first argument (which must be a string).
|
|
|
2484 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.
|
|
|
2485 </p>
|
|
|
2486
|
|
|
2487 <p>
|
|
|
2488 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.
|
|
|
2489 </p>
|
|
|
2490 <%
|
|
|
2491 end
|
|
|
2492 }
|
|
|
2493 ["String.gmatch"] = {
|
|
|
2494 title = "<code>String.gmatch (s, pattern)</code>"
|
|
|
2495 content = function()
|
|
|
2496 %>
|
|
|
2497 <p>
|
|
|
2498 Returns an iterator function that,
|
|
|
2499 each time it is called,
|
|
|
2500 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>)
|
|
|
2501 over the string <code>s</code>.
|
|
|
2502 If <code>pattern</code> specifies no captures,
|
|
|
2503 then the whole match is produced in each call.
|
|
|
2504 </p>
|
|
|
2505
|
|
|
2506 <p>
|
|
|
2507 As an example, the following loop
|
|
|
2508 will iterate over all the words from string <code>s</code>,
|
|
|
2509 printing one per line:
|
|
|
2510 </p>
|
|
|
2511 <pre>
|
|
|
2512 local s = "hello world from Lua"
|
|
|
2513 for w in String.gmatch(s, [[\w+]]) do
|
|
|
2514 print(w)
|
|
|
2515 end
|
|
|
2516 </pre>
|
|
|
2517
|
|
|
2518 <p>
|
|
|
2519 The next example collects all pairs <code>key=value</code> from the
|
|
|
2520 given string into a table:
|
|
|
2521 </p>
|
|
|
2522 <pre>
|
|
|
2523 local t = {}
|
|
|
2524 local s = "from=world, to=Lua"
|
|
|
2525 for k, v in String.gmatch(s, [[(\w+)=(\w+)]]) do
|
|
|
2526 t[k] = v
|
|
|
2527 end
|
|
|
2528 </pre>
|
|
|
2529
|
|
|
2530 <p>
|
|
|
2531 For this function, a caret '<code>^</code>' at the start of a pattern does not
|
|
|
2532 work as an anchor, as this would prevent the iteration.
|
|
|
2533 </p>
|
|
|
2534 <%
|
|
|
2535 end
|
|
|
2536 }
|
|
|
2537 ["String.gsub"] = {
|
|
|
2538 title = "<code>String.gsub (s, pattern, repl [, n])</code>"
|
|
|
2539 content = function()
|
|
|
2540 %>
|
|
|
2541 <p>
|
|
|
2542 Returns a copy of <code>s</code>
|
|
|
2543 in which all (or the first <code>n</code>, if given)
|
|
|
2544 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
|
|
|
2545 replaced by a replacement string specified by <code>repl</code>,
|
|
|
2546 which can be a string, a table, or a function.
|
|
|
2547 <code>gsub</code> also returns, as its second value,
|
|
|
2548 the total number of matches that occurred.
|
|
|
2549 The name <code>gsub</code> comes from <em>Global SUBstitution</em>.
|
|
|
2550 </p>
|
|
|
2551
|
|
|
2552 <p>
|
|
|
2553 If <code>repl</code> is a string, then its value is used for replacement.
|
|
|
2554 The character <code>\</code> works as an escape character.
|
|
|
2555 Any sequence in <code>repl</code> of the form <code>$<em>d</em></code>,
|
|
|
2556 with <em>d</em> between 1 and 9,
|
|
|
2557 stands for the value of the <em>d</em>-th captured substring.
|
|
|
2558 The sequence <code>$0</code> stands for the whole match.
|
|
|
2559 </p>
|
|
|
2560
|
|
|
2561 <p>
|
|
|
2562 If <code>repl</code> is a table, then the table is queried for every match,
|
|
|
2563 using the first capture as the key.
|
|
|
2564 </p>
|
|
|
2565
|
|
|
2566 <p>
|
|
|
2567 If <code>repl</code> is a function, then this function is called every time a
|
|
|
2568 match occurs, with all captured substrings passed as arguments,
|
|
|
2569 in order.
|
|
|
2570 </p>
|
|
|
2571
|
|
|
2572 <p>
|
|
|
2573 In any case,
|
|
|
2574 if the pattern specifies no captures,
|
|
|
2575 then it behaves as if the whole pattern was inside a capture.
|
|
|
2576 </p>
|
|
|
2577
|
|
|
2578 <p>
|
|
|
2579 If the value returned by the table query or by the function call
|
|
|
2580 is not <b>nil</b>,
|
|
|
2581 then it is used as the replacement string;
|
|
|
2582 otherwise, if it is <b>nil</b>,
|
|
|
2583 then there is no replacement
|
|
|
2584 (that is, the original match is kept in the string).
|
|
|
2585 </p>
|
|
|
2586
|
|
|
2587 <p>
|
|
|
2588 Here are some examples:
|
|
|
2589 </p>
|
|
|
2590 <pre>
|
|
|
2591 x = String.gsub("hello world", [[(\w+)]], "$1 $1")
|
|
|
2592 --> x="hello hello world world"
|
|
|
2593
|
|
|
2594 x = String.gsub("hello world", [[\w+]], "$0 $0", 1)
|
|
|
2595 --> x="hello hello world"
|
|
|
2596
|
|
|
2597 x = String.gsub("hello world from Luan", [[(\w+)\s*(\w+)]], "$2 $1")
|
|
|
2598 --> x="world hello Luan from"
|
|
|
2599
|
|
|
2600 x = String.gsub("4+5 = $return 4+5$", [[\$(.*?)\$]], function (s)
|
|
|
2601 return load(s)()
|
|
|
2602 end)
|
|
|
2603 --> x="4+5 = 9"
|
|
|
2604
|
|
|
2605 local t = {name="lua", version="5.3"}
|
|
|
2606 x = String.gsub("$name-$version.tar.gz", [[\$(\w+)]], t)
|
|
|
2607 --> x="lua-5.3.tar.gz"
|
|
|
2608 </pre>
|
|
|
2609 <%
|
|
|
2610 end
|
|
|
2611 }
|
|
|
2612 ["String.lower"] = {
|
|
|
2613 title = "<code>String.lower (s)</code>"
|
|
|
2614 content = function()
|
|
|
2615 %>
|
|
|
2616 <p>
|
|
|
2617 Receives a string and returns a copy of this string with all
|
|
|
2618 uppercase letters changed to lowercase.
|
|
|
2619 All other characters are left unchanged.
|
|
|
2620 </p>
|
|
|
2621 <%
|
|
|
2622 end
|
|
|
2623 }
|
|
|
2624 ["String.match"] = {
|
|
|
2625 title = "<code>String.match (s, pattern [, init])</code>"
|
|
|
2626 content = function()
|
|
|
2627 %>
|
|
|
2628 <p>
|
|
|
2629 Looks for the first <em>match</em> of
|
|
|
2630 <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>.
|
|
|
2631 If it finds one, then <code>match</code> returns
|
|
|
2632 the captures from the pattern;
|
|
|
2633 otherwise it returns <b>nil</b>.
|
|
|
2634 If <code>pattern</code> specifies no captures,
|
|
|
2635 then the whole match is returned.
|
|
|
2636 A third, optional numerical argument <code>init</code> specifies
|
|
|
2637 where to start the search;
|
|
|
2638 its default value is 1 and can be negative.
|
|
|
2639 </p>
|
|
|
2640 <%
|
|
|
2641 end
|
|
|
2642 }
|
|
|
2643 ["String.matches"] = {
|
|
|
2644 title = "<code>String.matches (s, pattern)</code>"
|
|
|
2645 content = function()
|
|
|
2646 %>
|
|
|
2647 <p>
|
|
|
2648 Returns a boolean indicating whether the <code>pattern</code> can be found in string <code>s</code>.
|
|
|
2649 This function is equivalent to
|
|
|
2650 </p>
|
|
|
2651 <pre>
|
|
|
2652 return String.match(s,pattern) ~= nil
|
|
|
2653 </pre>
|
|
|
2654 <%
|
|
|
2655 end
|
|
|
2656 }
|
|
1716
|
2657 ["String.regex"] = {
|
|
|
2658 title = "<code>String.regex (s)</code>"
|
|
|
2659 content = function()
|
|
|
2660 %>
|
|
|
2661 <p>
|
|
|
2662 Returns a <a href="#regex_table">regex</a> table for the pattern <code>s</code>.
|
|
|
2663 </p>
|
|
|
2664 <%
|
|
|
2665 end
|
|
|
2666 }
|
|
1668
|
2667 ["String.regex_quote"] = {
|
|
|
2668 title = "<code>String.regex_quote (s)</code>"
|
|
|
2669 content = function()
|
|
|
2670 %>
|
|
|
2671 <p>
|
|
|
2672 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>.
|
|
|
2673 </p>
|
|
|
2674 <%
|
|
|
2675 end
|
|
|
2676 }
|
|
|
2677 ["String.rep"] = {
|
|
|
2678 title = "<code>String.rep (s, n [, sep])</code>"
|
|
|
2679 content = function()
|
|
|
2680 %>
|
|
|
2681 <p>
|
|
|
2682 Returns a string that is the concatenation of <code>n</code> copies of
|
|
|
2683 the string <code>s</code> separated by the string <code>sep</code>.
|
|
|
2684 The default value for <code>sep</code> is the empty string
|
|
|
2685 (that is, no separator).
|
|
|
2686 Returns the empty string if <code>n</code> is not positive.
|
|
|
2687 </p>
|
|
|
2688 <%
|
|
|
2689 end
|
|
|
2690 }
|
|
1717
|
2691 ["String.replace"] = {
|
|
|
2692 title = "<code>String.replace (s, target, replacement)</code>"
|
|
|
2693 content = function()
|
|
|
2694 %>
|
|
|
2695 <p>
|
|
|
2696 Returns a string where each substring <code>target</code> in <code>s</code> is replaced by <code>replacement</code>.
|
|
|
2697 </p>
|
|
|
2698 <%
|
|
|
2699 end
|
|
|
2700 }
|
|
1668
|
2701 ["String.reverse"] = {
|
|
|
2702 title = "<code>String.reverse (s)</code>"
|
|
|
2703 content = function()
|
|
|
2704 %>
|
|
|
2705 <p>
|
|
|
2706 Returns a string that is the string <code>s</code> reversed.
|
|
|
2707 </p>
|
|
|
2708 <%
|
|
|
2709 end
|
|
|
2710 }
|
|
|
2711 ["String.split"] = {
|
|
|
2712 title = "<code>String.split (s, pattern [, limit])</code>"
|
|
|
2713 content = function()
|
|
|
2714 %>
|
|
|
2715 <p>
|
|
|
2716 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.
|
|
|
2717 </p>
|
|
|
2718 <%
|
|
|
2719 end
|
|
|
2720 }
|
|
1716
|
2721 ["String.starts_with"] = {
|
|
|
2722 title = "<code>String.starts_with (s, s2)</code>"
|
|
|
2723 content = function()
|
|
|
2724 %>
|
|
|
2725 <p>
|
|
|
2726 Returns a boolean indicating whether the <code>s</code> starts with <code>s2</code>.
|
|
|
2727 </p>
|
|
|
2728 <%
|
|
|
2729 end
|
|
|
2730 }
|
|
1668
|
2731 ["String.sub"] = {
|
|
|
2732 title = "<code>String.sub (s, i [, j])</code>"
|
|
|
2733 content = function()
|
|
|
2734 %>
|
|
|
2735 <p>
|
|
|
2736 Returns the substring of <code>s</code> that
|
|
|
2737 starts at <code>i</code> and continues until <code>j</code>;
|
|
|
2738 <code>i</code> and <code>j</code> can be negative.
|
|
|
2739 If <code>j</code> is absent, then it is assumed to be equal to -1
|
|
|
2740 (which is the same as the string length).
|
|
|
2741 In particular,
|
|
|
2742 the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
|
|
|
2743 with length <code>j</code>,
|
|
|
2744 and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code>
|
|
|
2745 with length <code>i</code>.
|
|
|
2746 </p>
|
|
|
2747
|
|
|
2748 <p>
|
|
|
2749 If, after the translation of negative indices,
|
|
|
2750 <code>i</code> is less than 1,
|
|
|
2751 it is corrected to 1.
|
|
|
2752 If <code>j</code> is greater than the string length,
|
|
|
2753 it is corrected to that length.
|
|
|
2754 If, after these corrections,
|
|
|
2755 <code>i</code> is greater than <code>j</code>,
|
|
|
2756 the function returns the empty string.
|
|
|
2757 </p>
|
|
|
2758 <%
|
|
|
2759 end
|
|
|
2760 }
|
|
|
2761 ["String.to_binary"] = {
|
|
|
2762 title = "<code>String.to_binary (s)</code>"
|
|
|
2763 content = function()
|
|
|
2764 %>
|
|
|
2765 <p>
|
|
|
2766 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>.
|
|
|
2767 </p>
|
|
|
2768 <%
|
|
|
2769 end
|
|
|
2770 }
|
|
|
2771 ["String.to_number"] = {
|
|
|
2772 title = "<code>String.to_number (s [, base])</code>"
|
|
|
2773 content = function()
|
|
|
2774 %>
|
|
|
2775 <p>
|
|
|
2776 When called with no <code>base</code>,
|
|
|
2777 <code>to_number</code> tries to convert its argument to a number.
|
|
|
2778 If the argument is
|
|
|
2779 a string convertible to a number,
|
|
|
2780 then <code>to_number</code> returns this number;
|
|
|
2781 otherwise, it returns <b>nil</b>.
|
|
|
2782 The conversion of strings can result in integers or floats.
|
|
|
2783 </p>
|
|
|
2784
|
|
|
2785 <p>
|
|
|
2786 When called with <code>base</code>,
|
|
|
2787 then <code>s</code> must be a string to be interpreted as
|
|
|
2788 an integer numeral in that base.
|
|
|
2789 In bases above 10, the letter '<code>A</code>' (in either upper or lower case)
|
|
|
2790 represents 10, '<code>B</code>' represents 11, and so forth,
|
|
|
2791 with '<code>Z</code>' representing 35.
|
|
|
2792 If the string <code>s</code> is not a valid numeral in the given base,
|
|
|
2793 the function returns <b>nil</b>.
|
|
|
2794 </p>
|
|
|
2795 <%
|
|
|
2796 end
|
|
|
2797 }
|
|
|
2798 ["String.trim"] = {
|
|
|
2799 title = "<code>String.trim (s)</code>"
|
|
|
2800 content = function()
|
|
|
2801 %>
|
|
|
2802 <p>
|
|
|
2803 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>.
|
|
|
2804 </p>
|
|
|
2805 <%
|
|
|
2806 end
|
|
|
2807 }
|
|
|
2808 ["String.unicode"] = {
|
|
|
2809 title = "<code>String.unicode (s [, i [, j]])</code>"
|
|
|
2810 content = function()
|
|
|
2811 %>
|
|
|
2812 <p>
|
|
|
2813 Returns the internal numerical codes of the characters <code>s[i]</code>,
|
|
|
2814 <code>s[i+1]</code>, ..., <code>s[j]</code>.
|
|
|
2815 The default value for <code>i</code> is 1;
|
|
|
2816 the default value for <code>j</code> is <code>i</code>.
|
|
|
2817 These indices are corrected
|
|
|
2818 following the same rules of function <a href="#String.sub"><code>String.sub</code></a>.
|
|
|
2819 </p>
|
|
|
2820 <%
|
|
|
2821 end
|
|
|
2822 }
|
|
|
2823 ["String.upper"] = {
|
|
|
2824 title = "<code>String.upper (s)</code>"
|
|
|
2825 content = function()
|
|
|
2826 %>
|
|
|
2827 <p>
|
|
|
2828 Receives a string and returns a copy of this string with all
|
|
|
2829 lowercase letters changed to uppercase.
|
|
|
2830 All other characters are left unchanged.
|
|
|
2831 The definition of what a lowercase letter is depends on the current locale.
|
|
|
2832 </p>
|
|
|
2833 <%
|
|
|
2834 end
|
|
|
2835 }
|
|
|
2836 }
|
|
|
2837 }
|
|
1716
|
2838 regex_table = {
|
|
|
2839 title = "Regular Expressions"
|
|
|
2840 content = function()
|
|
|
2841 %>
|
|
|
2842 <p>
|
|
|
2843 Regular expressions are handled using a regex table generated by <a href="#String.regex">String.regex</a>.
|
|
|
2844 </p>
|
|
|
2845
|
|
|
2846 <p>
|
|
|
2847 Pattern matching is based on the Java <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a> class.
|
|
|
2848 </p>
|
|
|
2849 <%
|
|
|
2850 end
|
|
|
2851 subs = {
|
|
|
2852 ["regex.find"] = {
|
|
|
2853 title = "<code>regex.find (s [, init])</code>"
|
|
|
2854 content = function()
|
|
|
2855 %>
|
|
|
2856 <p>
|
|
|
2857 Looks for the first match of
|
|
|
2858 the regex in the string <code>s</code>.
|
|
|
2859 If it finds a match, then <code>find</code> returns the indices of <code>s</code>
|
|
|
2860 where this occurrence starts and ends;
|
|
|
2861 otherwise, it returns <b>nil</b>.
|
|
|
2862 A third, optional numerical argument <code>init</code> specifies
|
|
|
2863 where to start the search;
|
|
|
2864 its default value is 1 and can be negative.
|
|
|
2865 </p>
|
|
|
2866
|
|
|
2867 <p>
|
|
|
2868 If the regex has captures,
|
|
|
2869 then in a successful match
|
|
|
2870 the captured values are also returned,
|
|
|
2871 after the two indices.
|
|
|
2872 </p>
|
|
|
2873 <%
|
|
|
2874 end
|
|
|
2875 }
|
|
|
2876 ["regex.gmatch"] = {
|
|
|
2877 title = "<code>regex.gmatch (s)</code>"
|
|
|
2878 content = function()
|
|
|
2879 %>
|
|
|
2880 <p>
|
|
|
2881 Returns an iterator function that,
|
|
|
2882 each time it is called,
|
|
|
2883 returns the next captures from the regex
|
|
|
2884 over the string <code>s</code>.
|
|
|
2885 If the regex specifies no captures,
|
|
|
2886 then the whole match is produced in each call.
|
|
|
2887 </p>
|
|
|
2888
|
|
|
2889 <p>
|
|
|
2890 As an example, the following loop
|
|
|
2891 will iterate over all the words from string <code>s</code>,
|
|
|
2892 printing one per line:
|
|
|
2893 </p>
|
|
|
2894 <pre>
|
|
|
2895 local r = String.regex[[\w+]]
|
|
|
2896 local s = "hello world from Lua"
|
|
|
2897 for w in r.gmatch(s) do
|
|
|
2898 print(w)
|
|
|
2899 end
|
|
|
2900 </pre>
|
|
|
2901
|
|
|
2902 <p>
|
|
|
2903 The next example collects all pairs <code>key=value</code> from the
|
|
|
2904 given string into a table:
|
|
|
2905 </p>
|
|
|
2906 <pre>
|
|
|
2907 local t = {}
|
|
|
2908 local r = String.regex[[(\w+)=(\w+)]]
|
|
|
2909 local s = "from=world, to=Lua"
|
|
|
2910 for k, v in r.gmatch(s) do
|
|
|
2911 t[k] = v
|
|
|
2912 end
|
|
|
2913 </pre>
|
|
|
2914
|
|
|
2915 <p>
|
|
|
2916 For this function, a caret '<code>^</code>' at the start of a pattern does not
|
|
|
2917 work as an anchor, as this would prevent the iteration.
|
|
|
2918 </p>
|
|
|
2919 <%
|
|
|
2920 end
|
|
|
2921 }
|
|
|
2922 ["regex.gsub"] = {
|
|
|
2923 title = "<code>regex.gsub (s, repl [, n])</code>"
|
|
|
2924 content = function()
|
|
|
2925 %>
|
|
|
2926 <p>
|
|
|
2927 Returns a copy of <code>s</code>
|
|
|
2928 in which all (or the first <code>n</code>, if given)
|
|
|
2929 occurrences of the regex have been
|
|
|
2930 replaced by a replacement string specified by <code>repl</code>,
|
|
|
2931 which can be a string, a table, or a function.
|
|
|
2932 <code>gsub</code> also returns, as its second value,
|
|
|
2933 the total number of matches that occurred.
|
|
|
2934 The name <code>gsub</code> comes from <em>Global SUBstitution</em>.
|
|
|
2935 </p>
|
|
|
2936
|
|
|
2937 <p>
|
|
|
2938 If <code>repl</code> is a string, then its value is used for replacement.
|
|
|
2939 The character <code>\</code> works as an escape character.
|
|
|
2940 Any sequence in <code>repl</code> of the form <code>$<em>d</em></code>,
|
|
|
2941 with <em>d</em> between 1 and 9,
|
|
|
2942 stands for the value of the <em>d</em>-th captured substring.
|
|
|
2943 The sequence <code>$0</code> stands for the whole match.
|
|
|
2944 </p>
|
|
|
2945
|
|
|
2946 <p>
|
|
|
2947 If <code>repl</code> is a table, then the table is queried for every match,
|
|
|
2948 using the first capture as the key.
|
|
|
2949 </p>
|
|
|
2950
|
|
|
2951 <p>
|
|
|
2952 If <code>repl</code> is a function, then this function is called every time a
|
|
|
2953 match occurs, with all captured substrings passed as arguments,
|
|
|
2954 in order.
|
|
|
2955 </p>
|
|
|
2956
|
|
|
2957 <p>
|
|
|
2958 In any case,
|
|
|
2959 if the regex specifies no captures,
|
|
|
2960 then it behaves as if the whole regex was inside a capture.
|
|
|
2961 </p>
|
|
|
2962
|
|
|
2963 <p>
|
|
|
2964 If the value returned by the table query or by the function call
|
|
|
2965 is not <b>nil</b>,
|
|
|
2966 then it is used as the replacement string;
|
|
|
2967 otherwise, if it is <b>nil</b>,
|
|
|
2968 then there is no replacement
|
|
|
2969 (that is, the original match is kept in the string).
|
|
|
2970 </p>
|
|
|
2971
|
|
|
2972 <p>
|
|
|
2973 Here are some examples:
|
|
|
2974 </p>
|
|
|
2975 <pre>
|
|
|
2976 local r = String.regex[[(\w+)]]
|
|
|
2977 local x = r.gsub("hello world", "$1 $1")
|
|
|
2978 --> x="hello hello world world"
|
|
|
2979
|
|
|
2980 local r = String.regex[[(\w+)]]
|
|
|
2981 local x = r.gsub("hello world", "$0 $0", 1)
|
|
|
2982 --> x="hello hello world"
|
|
|
2983
|
|
|
2984 local r = String.regex[[(\w+)\s*(\w+)]]
|
|
|
2985 local x = r.gsub("hello world from Luan", "$2 $1")
|
|
|
2986 --> x="world hello Luan from"
|
|
|
2987
|
|
|
2988 local r = String.regex[[\$(.*?)\$]]
|
|
|
2989 local x = r.gsub("4+5 = $return 4+5$", function(s)
|
|
|
2990 return load(s)()
|
|
|
2991 end)
|
|
|
2992 --> x="4+5 = 9"
|
|
|
2993
|
|
|
2994 local r = String.regex[[\$(\w+)]]
|
|
|
2995 local t = {name="lua", version="5.3"}
|
|
|
2996 local x = r.gsub("$name-$version.tar.gz", t)
|
|
|
2997 --> x="lua-5.3.tar.gz"
|
|
|
2998 </pre>
|
|
|
2999 <%
|
|
|
3000 end
|
|
|
3001 }
|
|
|
3002 ["regex.match"] = {
|
|
|
3003 title = "<code>regex.match (s [, init])</code>"
|
|
|
3004 content = function()
|
|
|
3005 %>
|
|
|
3006 <p>
|
|
|
3007 Looks for the first <em>match</em> of
|
|
|
3008 the regex in the string <code>s</code>.
|
|
|
3009 If it finds one, then <code>match</code> returns
|
|
|
3010 the captures from the regex;
|
|
|
3011 otherwise it returns <b>nil</b>.
|
|
|
3012 If the regex specifies no captures,
|
|
|
3013 then the whole match is returned.
|
|
|
3014 A third, optional numerical argument <code>init</code> specifies
|
|
|
3015 where to start the search;
|
|
|
3016 its default value is 1 and can be negative.
|
|
|
3017 </p>
|
|
|
3018 <%
|
|
|
3019 end
|
|
|
3020 }
|
|
|
3021 ["regex.matches"] = {
|
|
|
3022 title = "<code>regex.matches (s)</code>"
|
|
|
3023 content = function()
|
|
|
3024 %>
|
|
|
3025 <p>
|
|
|
3026 Returns a boolean indicating whether the regex can be found in string <code>s</code>.
|
|
|
3027 This function is equivalent to
|
|
|
3028 </p>
|
|
|
3029 <pre>
|
|
|
3030 return regex.match(s) ~= nil
|
|
|
3031 </pre>
|
|
|
3032 <%
|
|
|
3033 end
|
|
|
3034 }
|
|
|
3035 }
|
|
|
3036 }
|
|
1668
|
3037 binary_lib = {
|
|
|
3038 title = "Binary Manipulation"
|
|
|
3039 content = function()
|
|
|
3040 %>
|
|
|
3041 <p>
|
|
|
3042 Include this library by:
|
|
|
3043 </p>
|
|
|
3044 <pre>
|
|
|
3045 local Binary = require "luan:Binary.luan"
|
|
|
3046 </pre>
|
|
|
3047 <%
|
|
|
3048 end
|
|
|
3049 subs = {
|
|
|
3050 ["Binary.binary"] = {
|
|
|
3051 title = "<code>Binary.binary (···)</code>"
|
|
|
3052 content = function()
|
|
|
3053 %>
|
|
|
3054 <p>
|
|
|
3055 Receives zero or more bytes (as integers).
|
|
|
3056 Returns a binary with length equal to the number of arguments,
|
|
|
3057 in which each byte has the internal numerical code equal
|
|
|
3058 to its corresponding argument.
|
|
|
3059 </p>
|
|
|
3060 <%
|
|
|
3061 end
|
|
|
3062 }
|
|
|
3063 ["Binary.byte"] = {
|
|
|
3064 title = "<code>Binary.byte (b [, i [, j]])</code>"
|
|
|
3065 content = function()
|
|
|
3066 %>
|
|
|
3067 <p>
|
|
|
3068 Returns the internal numerical codes of the bytes <code>b[i]</code>,
|
|
|
3069 <code>b[i+1]</code>, ..., <code>b[j]</code>.
|
|
|
3070 The default value for <code>i</code> is 1;
|
|
|
3071 the default value for <code>j</code> is <code>i</code>.
|
|
|
3072 These indices are corrected
|
|
|
3073 following the same rules of function <a href="#String.sub"><code>String.sub</code></a>.
|
|
|
3074 </p>
|
|
|
3075 <%
|
|
|
3076 end
|
|
|
3077 }
|
|
|
3078 ["Binary.to_string"] = {
|
|
|
3079 title = "<code>Binary.to_string (b [,charset])</code>"
|
|
|
3080 content = function()
|
|
|
3081 %>
|
|
|
3082 <p>
|
|
|
3083 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.
|
|
|
3084 </p>
|
|
|
3085 <%
|
|
|
3086 end
|
|
|
3087 }
|
|
|
3088 }
|
|
|
3089 }
|
|
|
3090 table_lib = {
|
|
|
3091 title = "Table Manipulation"
|
|
|
3092 content = function()
|
|
|
3093 %>
|
|
|
3094 <p>
|
|
|
3095 Include this library by:
|
|
|
3096 </p>
|
|
|
3097 <pre>
|
|
|
3098 local Table = require "luan:Table.luan"
|
|
|
3099 </pre>
|
|
|
3100
|
|
|
3101 <p>
|
|
|
3102 This library provides generic functions for table manipulation.
|
|
|
3103 It provides all its functions inside the table <code>Table</code>.
|
|
|
3104 </p>
|
|
|
3105 <%
|
|
|
3106 end
|
|
|
3107 subs = {
|
|
|
3108 ["Table.clear"] = {
|
|
|
3109 title = "<code>Table.clear (tbl)</code>"
|
|
|
3110 content = function()
|
|
|
3111 %>
|
|
|
3112 <p>
|
|
|
3113 Clears the table.
|
|
|
3114 </p>
|
|
|
3115 <%
|
|
|
3116 end
|
|
|
3117 }
|
|
|
3118 ["Table.concat"] = {
|
|
|
3119 title = "<code>Table.concat (list [, sep [, i [, j]]])</code>"
|
|
|
3120 content = function()
|
|
|
3121 %>
|
|
|
3122 <p>
|
|
|
3123 Given a list,
|
|
|
3124 returns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>.
|
|
|
3125 The default value for <code>sep</code> is the empty string,
|
|
|
3126 the default for <code>i</code> is 1,
|
|
|
3127 and the default for <code>j</code> is <code>#list</code>.
|
|
|
3128 If <code>i</code> is greater than <code>j</code>, returns the empty string.
|
|
|
3129 </p>
|
|
|
3130 <%
|
|
|
3131 end
|
|
|
3132 }
|
|
|
3133 ["Table.copy"] = {
|
|
|
3134 title = "<code>Table.copy (tbl [, i [, j]])</code>"
|
|
|
3135 content = function()
|
|
|
3136 %>
|
|
|
3137 <p>
|
|
|
3138 If <code>i</code> is <code>nil</code>, returns a shallow copy of <code>tbl</code>.
|
|
|
3139 Otherwise returns a new table which is a list of the elements <code>tbl[i] ··· tbl[j]</code>.
|
|
|
3140 By default, <code>j</code> is <code>#tbl</code>.
|
|
|
3141 </p>
|
|
|
3142 <%
|
|
|
3143 end
|
|
|
3144 }
|
|
|
3145 ["Table.insert"] = {
|
|
|
3146 title = "<code>Table.insert (list, pos, value)</code>"
|
|
|
3147 content = function()
|
|
|
3148 %>
|
|
|
3149 <p>
|
|
|
3150 Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>,
|
|
|
3151 shifting up the elements
|
|
|
3152 <code>list[pos], list[pos+1], ···, list[#list]</code>.
|
|
|
3153 </p>
|
|
|
3154 <%
|
|
|
3155 end
|
|
|
3156 }
|
|
|
3157 ["Table.is_empty"] = {
|
|
|
3158 title = "<code>Table.is_empty (tbl)</code>"
|
|
|
3159 content = function()
|
|
|
3160 %>
|
|
|
3161 <%
|
|
|
3162 end
|
|
|
3163 }
|
|
1704
|
3164 ["Table.is_list"] = {
|
|
|
3165 title = "<code>Table.is_list (tbl)</code>"
|
|
|
3166 content = function()
|
|
|
3167 %>
|
|
|
3168 <%
|
|
|
3169 end
|
|
|
3170 }
|
|
1668
|
3171 ["Table.pack"] = {
|
|
|
3172 title = "<code>Table.pack (···)</code>"
|
|
|
3173 content = function()
|
|
|
3174 %>
|
|
|
3175 <p>
|
|
|
3176 Returns a new table with all parameters stored into keys 1, 2, etc.
|
|
|
3177 and with a field "<code>n</code>" with the total number of parameters.
|
|
|
3178 Note that the resulting table may not be a sequence.
|
|
|
3179 </p>
|
|
|
3180 <%
|
|
|
3181 end
|
|
|
3182 }
|
|
|
3183 ["Table.remove"] = {
|
|
|
3184 title = "<code>Table.remove (list, pos)</code>"
|
|
|
3185 content = function()
|
|
|
3186 %>
|
|
|
3187 <p>
|
|
|
3188 Removes from <code>list</code> the element at position <code>pos</code>,
|
|
|
3189 returning the value of the removed element.
|
|
|
3190 When <code>pos</code> is an integer between 1 and <code>#list</code>,
|
|
|
3191 it shifts down the elements
|
|
|
3192 <code>list[pos+1], list[pos+2], ···, list[#list]</code>
|
|
|
3193 and erases element <code>list[#list]</code>;
|
|
|
3194 The index <code>pos</code> can also be 0 when <code>#list</code> is 0,
|
|
|
3195 or <code>#list + 1</code>;
|
|
|
3196 in those cases, the function erases the element <code>list[pos]</code>.
|
|
|
3197 </p>
|
|
|
3198 <%
|
|
|
3199 end
|
|
|
3200 }
|
|
|
3201 ["Table.size"] = {
|
|
|
3202 title = "<code>Table.size (tbl)</code>"
|
|
|
3203 content = function()
|
|
|
3204 %>
|
|
|
3205 <%
|
|
|
3206 end
|
|
|
3207 }
|
|
|
3208 ["Table.sort"] = {
|
|
|
3209 title = "<code>Table.sort (list [, comp])</code>"
|
|
|
3210 content = function()
|
|
|
3211 %>
|
|
|
3212 <p>
|
|
|
3213 Sorts list elements in a given order, <em>in-place</em>,
|
|
|
3214 from <code>list[1]</code> to <code>list[#list]</code>.
|
|
|
3215 If <code>comp</code> is given,
|
|
|
3216 then it must be a function that receives two list elements
|
|
|
3217 and returns true when the first element must come
|
|
|
3218 before the second in the final order
|
|
|
3219 (so that <code>not comp(list[i+1],list[i])</code> will be true after the sort).
|
|
|
3220 If <code>comp</code> is not given,
|
|
|
3221 then the standard Lua operator <code><</code> is used instead.
|
|
|
3222 </p>
|
|
|
3223
|
|
|
3224 <p>
|
|
|
3225 The sort algorithm is not stable;
|
|
|
3226 that is, elements considered equal by the given order
|
|
|
3227 may have their relative positions changed by the sort.
|
|
|
3228 </p>
|
|
|
3229 <%
|
|
|
3230 end
|
|
|
3231 }
|
|
|
3232 ["Table.unpack"] = {
|
|
|
3233 title = "<code>Table.unpack (list [, i [, j]])</code>"
|
|
|
3234 content = function()
|
|
|
3235 %>
|
|
|
3236 <p>
|
|
|
3237 Returns the elements from the given list.
|
|
|
3238 This function is equivalent to
|
|
|
3239 </p>
|
|
|
3240 <pre>
|
|
|
3241 return list[i], list[i+1], ···, list[j]
|
|
|
3242 </pre>
|
|
|
3243
|
|
|
3244 <p>
|
|
|
3245 By default, <code>i</code> is 1 and <code>j</code> is <code>list.n or #list</code>.
|
|
|
3246 </p>
|
|
|
3247 <%
|
|
|
3248 end
|
|
|
3249 }
|
|
|
3250 }
|
|
|
3251 }
|
|
|
3252 number_lib = {
|
|
|
3253 title = "Number Manipulation"
|
|
|
3254 content = function()
|
|
|
3255 %>
|
|
|
3256 <p>
|
|
|
3257 Include this library by:
|
|
|
3258 </p>
|
|
|
3259 <pre>
|
|
|
3260 local Number = require "luan:Number.luan"
|
|
|
3261 </pre>
|
|
|
3262 <%
|
|
|
3263 end
|
|
|
3264 subs = {
|
|
|
3265 ["Number.double"] = {
|
|
|
3266 title = "<code>Number.double (x)</code>"
|
|
|
3267 content = function()
|
|
|
3268 %>
|
|
|
3269 <p>
|
|
|
3270 Returns <code>x</code> as a double.
|
|
|
3271 </p>
|
|
|
3272 <%
|
|
|
3273 end
|
|
|
3274 }
|
|
|
3275 ["Number.float"] = {
|
|
|
3276 title = "<code>Number.float (x)</code>"
|
|
|
3277 content = function()
|
|
|
3278 %>
|
|
|
3279 <p>
|
|
|
3280 Returns <code>x</code> as a float.
|
|
|
3281 </p>
|
|
|
3282 <%
|
|
|
3283 end
|
|
|
3284 }
|
|
|
3285 ["Number.integer"] = {
|
|
|
3286 title = "<code>Number.integer (x)</code>"
|
|
|
3287 content = function()
|
|
|
3288 %>
|
|
|
3289 <p>
|
|
|
3290 If the value <code>x</code> is convertible to an integer,
|
|
|
3291 returns that integer.
|
|
|
3292 Otherwise throws an error.
|
|
|
3293 </p>
|
|
|
3294 <%
|
|
|
3295 end
|
|
|
3296 }
|
|
|
3297 ["Number.long"] = {
|
|
|
3298 title = "<code>Number.long (x)</code>"
|
|
|
3299 content = function()
|
|
|
3300 %>
|
|
|
3301 <p>
|
|
|
3302 If the value <code>x</code> is convertible to an long,
|
|
|
3303 returns that long.
|
|
|
3304 Otherwise throws an error.
|
|
|
3305 </p>
|
|
|
3306 <%
|
|
|
3307 end
|
|
|
3308 }
|
|
|
3309 ["Number.long_to_string"] = {
|
|
|
3310 title = "<code>Number.long_to_string (i, radix)</code>"
|
|
|
3311 content = function()
|
|
|
3312 %>
|
|
|
3313 <p>
|
|
|
3314 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>.
|
|
|
3315 </p>
|
|
|
3316 <%
|
|
|
3317 end
|
|
|
3318 }
|
|
|
3319 ["Number.type"] = {
|
|
|
3320 title = "<code>Number.type (x)</code>"
|
|
|
3321 content = function()
|
|
|
3322 %>
|
|
|
3323 <p>
|
|
|
3324 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>".
|
|
|
3325 </p>
|
|
|
3326 <%
|
|
|
3327 end
|
|
|
3328 }
|
|
|
3329 }
|
|
|
3330 }
|
|
1669
|
3331 math_lib = {
|
|
|
3332 title = "Mathematical Functions"
|
|
|
3333 content = function()
|
|
|
3334 %>
|
|
|
3335 <p>
|
|
|
3336 Include this library by:
|
|
|
3337 </p>
|
|
|
3338 <pre>
|
|
|
3339 local Math = require "luan:Math.luan"
|
|
|
3340 </pre>
|
|
|
3341
|
|
|
3342 <p>
|
|
|
3343 This library provides basic mathematical functions.
|
|
|
3344 It provides all its functions and constants inside the table <code>Math</code>.
|
|
|
3345 </p>
|
|
|
3346 <%
|
|
|
3347 end
|
|
|
3348 subs = {
|
|
|
3349 ["Math.abs"] = {
|
|
|
3350 title = "<code>Math.abs (x)</code>"
|
|
|
3351 content = function()
|
|
|
3352 %>
|
|
|
3353 <p>
|
|
|
3354 Returns the absolute value of <code>x</code>.
|
|
|
3355 </p>
|
|
|
3356 <%
|
|
|
3357 end
|
|
|
3358 }
|
|
|
3359 ["Math.acos"] = {
|
|
|
3360 title = "<code>Math.acos (x)</code>"
|
|
|
3361 content = function()
|
|
|
3362 %>
|
|
|
3363 <p>
|
|
|
3364 Returns the arc cosine of <code>x</code> (in radians).
|
|
|
3365 </p>
|
|
|
3366 <%
|
|
|
3367 end
|
|
|
3368 }
|
|
|
3369 ["Math.asin"] = {
|
|
|
3370 title = "<code>Math.asin (x)</code>"
|
|
|
3371 content = function()
|
|
|
3372 %>
|
|
|
3373 <p>
|
|
|
3374 Returns the arc sine of <code>x</code> (in radians).
|
|
|
3375 </p>
|
|
|
3376 <%
|
|
|
3377 end
|
|
|
3378 }
|
|
|
3379 ["Math.atan"] = {
|
|
|
3380 title = "<code>Math.atan (y, x)</code>"
|
|
|
3381 content = function()
|
|
|
3382 %>
|
|
|
3383 <p>
|
|
|
3384 Returns the arc tangent of <code>y/x</code> (in radians),
|
|
|
3385 but uses the signs of both parameters to find the
|
|
|
3386 quadrant of the result.
|
|
|
3387 (It also handles correctly the case of <code>x</code> being zero.)
|
|
|
3388 </p>
|
|
|
3389 <%
|
|
|
3390 end
|
|
|
3391 }
|
|
|
3392 ["Math.ceil"] = {
|
|
|
3393 title = "<code>Math.ceil (x)</code>"
|
|
|
3394 content = function()
|
|
|
3395 %>
|
|
|
3396 <p>
|
|
|
3397 Returns the smallest integral value larger than or equal to <code>x</code>.
|
|
|
3398 </p>
|
|
|
3399 <%
|
|
|
3400 end
|
|
|
3401 }
|
|
|
3402 ["Math.cos"] = {
|
|
|
3403 title = "<code>Math.cos (x)</code>"
|
|
|
3404 content = function()
|
|
|
3405 %>
|
|
|
3406 <p>
|
|
|
3407 Returns the cosine of <code>x</code> (assumed to be in radians).
|
|
|
3408 </p>
|
|
|
3409 <%
|
|
|
3410 end
|
|
|
3411 }
|
|
|
3412 ["Math.deg"] = {
|
|
|
3413 title = "<code>Math.deg (x)</code>"
|
|
|
3414 content = function()
|
|
|
3415 %>
|
|
|
3416 <p>
|
|
|
3417 Converts the angle <code>x</code> from radians to degrees.
|
|
|
3418 </p>
|
|
|
3419 <%
|
|
|
3420 end
|
|
|
3421 }
|
|
|
3422 ["Math.exp"] = {
|
|
|
3423 title = "<code>Math.exp (x)</code>"
|
|
|
3424 content = function()
|
|
|
3425 %>
|
|
|
3426 <p>
|
|
|
3427 Returns the value <em>e<sup>x</sup></em>
|
|
|
3428 (where <code>e</code> is the base of natural logarithms).
|
|
|
3429 </p>
|
|
|
3430 <%
|
|
|
3431 end
|
|
|
3432 }
|
|
|
3433 ["Math.floor"] = {
|
|
|
3434 title = "<code>Math.floor (x)</code>"
|
|
|
3435 content = function()
|
|
|
3436 %>
|
|
|
3437 <p>
|
|
|
3438 Returns the largest integral value smaller than or equal to <code>x</code>.
|
|
|
3439 </p>
|
|
|
3440 <%
|
|
|
3441 end
|
|
|
3442 }
|
|
|
3443 ["Math.fmod"] = {
|
|
|
3444 title = "<code>Math.fmod (x, y)</code>"
|
|
|
3445 content = function()
|
|
|
3446 %>
|
|
|
3447 <p>
|
|
|
3448 Returns the remainder of the division of <code>x</code> by <code>y</code>
|
|
|
3449 that rounds the quotient towards zero.
|
|
|
3450 </p>
|
|
|
3451 <%
|
|
|
3452 end
|
|
|
3453 }
|
|
|
3454 ["Math.huge"] = {
|
|
|
3455 title = "<code>Math.huge</code>"
|
|
|
3456 content = function()
|
|
|
3457 %>
|
|
|
3458 <p>
|
|
|
3459 A value larger than any other numerical value.
|
|
|
3460 </p>
|
|
|
3461 <%
|
|
|
3462 end
|
|
|
3463 }
|
|
|
3464 ["Math.log"] = {
|
|
|
3465 title = "<code>Math.log (x [, base])</code>"
|
|
|
3466 content = function()
|
|
|
3467 %>
|
|
|
3468 <p>
|
|
|
3469 Returns the logarithm of <code>x</code> in the given base.
|
|
|
3470 The default for <code>base</code> is <em>e</em>
|
|
|
3471 (so that the function returns the natural logarithm of <code>x</code>).
|
|
|
3472 </p>
|
|
|
3473 <%
|
|
|
3474 end
|
|
|
3475 }
|
|
|
3476 ["Math.max"] = {
|
|
|
3477 title = "<code>Math.max (x, ···)</code>"
|
|
|
3478 content = function()
|
|
|
3479 %>
|
|
|
3480 <p>
|
|
|
3481 Returns the argument with the maximum value,
|
|
|
3482 according to the Lua operator <code><</code>.
|
|
|
3483 </p>
|
|
|
3484 <%
|
|
|
3485 end
|
|
|
3486 }
|
|
|
3487 ["Math.max_integer"] = {
|
|
|
3488 title = "<code>Math.max_integer</code>"
|
|
|
3489 content = function()
|
|
|
3490 %>
|
|
|
3491 <p>
|
|
|
3492 An integer with the maximum value for an integer.
|
|
|
3493 </p>
|
|
|
3494 <%
|
|
|
3495 end
|
|
|
3496 }
|
|
|
3497 ["Math.min"] = {
|
|
|
3498 title = "<code>Math.min (x, ···)</code>"
|
|
|
3499 content = function()
|
|
|
3500 %>
|
|
|
3501 <p>
|
|
|
3502 Returns the argument with the minimum value,
|
|
|
3503 according to the Lua operator <code><</code>.
|
|
|
3504 </p>
|
|
|
3505 <%
|
|
|
3506 end
|
|
|
3507 }
|
|
|
3508 ["Math.min_integer"] = {
|
|
|
3509 title = "<code>Math.min_integer</code>"
|
|
|
3510 content = function()
|
|
|
3511 %>
|
|
|
3512 <p>
|
|
|
3513 An integer with the minimum value for an integer.
|
|
|
3514 </p>
|
|
|
3515 <%
|
|
|
3516 end
|
|
|
3517 }
|
|
|
3518 ["Math.modf"] = {
|
|
|
3519 title = "<code>Math.modf (x)</code>"
|
|
|
3520 content = function()
|
|
|
3521 %>
|
|
|
3522 <p>
|
|
|
3523 Returns the integral part of <code>x</code> and the fractional part of <code>x</code>.
|
|
|
3524 </p>
|
|
|
3525 <%
|
|
|
3526 end
|
|
|
3527 }
|
|
|
3528 ["Math.pi"] = {
|
|
|
3529 title = "<code>Math.pi</code>"
|
|
|
3530 content = function()
|
|
|
3531 %>
|
|
|
3532 <p>
|
|
|
3533 The value of <em>π</em>.
|
|
|
3534 </p>
|
|
|
3535 <%
|
|
|
3536 end
|
|
|
3537 }
|
|
|
3538 ["Math.rad"] = {
|
|
|
3539 title = "<code>Math.rad (x)</code>"
|
|
|
3540 content = function()
|
|
|
3541 %>
|
|
|
3542 <p>
|
|
|
3543 Converts the angle <code>x</code> from degrees to radians.
|
|
|
3544 </p>
|
|
|
3545 <%
|
|
|
3546 end
|
|
|
3547 }
|
|
|
3548 ["Math.random"] = {
|
|
|
3549 title = "<code>Math.random ([m [, n])</code>"
|
|
|
3550 content = function()
|
|
|
3551 %>
|
|
|
3552 <p>
|
|
|
3553 When called without arguments,
|
|
|
3554 returns a pseudo-random float with uniform distribution
|
|
|
3555 in the range <em>[0,1)</em>.
|
|
|
3556 When called with two integers <code>m</code> and <code>n</code>,
|
|
|
3557 <code>Math.random</code> returns a pseudo-random integer
|
|
|
3558 with uniform distribution in the range <em>[m, n]</em>.
|
|
|
3559 (The value <em>m-n</em> cannot be negative and must fit in a Luan integer.)
|
|
|
3560 The call <code>Math.random(n)</code> is equivalent to <code>Math.random(1,n)</code>.
|
|
|
3561 </p>
|
|
|
3562
|
|
|
3563 <p>
|
|
|
3564 This function is an interface to the underling
|
|
|
3565 pseudo-random generator function provided by Java.
|
|
|
3566 No guarantees can be given for its statistical properties.
|
|
|
3567 </p>
|
|
|
3568 <%
|
|
|
3569 end
|
|
|
3570 }
|
|
|
3571 ["Math.sin"] = {
|
|
|
3572 title = "<code>Math.sin (x)</code>"
|
|
|
3573 content = function()
|
|
|
3574 %>
|
|
|
3575 <p>
|
|
|
3576 Returns the sine of <code>x</code> (assumed to be in radians).
|
|
|
3577 </p>
|
|
|
3578 <%
|
|
|
3579 end
|
|
|
3580 }
|
|
|
3581 ["Math.sqrt"] = {
|
|
|
3582 title = "<code>Math.sqrt (x)</code>"
|
|
|
3583 content = function()
|
|
|
3584 %>
|
|
|
3585 <p>
|
|
|
3586 Returns the square root of <code>x</code>.
|
|
|
3587 (You can also use the expression <code>x^0.5</code> to compute this value.)
|
|
|
3588 </p>
|
|
|
3589 <%
|
|
|
3590 end
|
|
|
3591 }
|
|
|
3592 ["Math.tan"] = {
|
|
|
3593 title = "<code>Math.tan (x)</code>"
|
|
|
3594 content = function()
|
|
|
3595 %>
|
|
|
3596 <p>
|
|
|
3597 Returns the tangent of <code>x</code> (assumed to be in radians).
|
|
|
3598 </p>
|
|
|
3599 <%
|
|
|
3600 end
|
|
|
3601 }
|
|
|
3602 }
|
|
|
3603 }
|
|
1656
|
3604 }
|
|
|
3605 }
|
|
|
3606 }
|
|
|
3607
|
|
|
3608
|
|
|
3609 return function()
|
|
|
3610 Io.stdout = Http.response.text_writer()
|
|
|
3611 %>
|
|
|
3612 <!doctype html>
|
|
|
3613 <html>
|
|
|
3614 <head>
|
|
|
3615 <% head() %>
|
|
|
3616 <title>Luan Reference Manual</title>
|
|
|
3617 <style>
|
|
|
3618 p[keywords] {
|
|
|
3619 font-family: monospace;
|
|
|
3620 margin-left: 40px;
|
|
|
3621 max-width: 700px;
|
|
|
3622 }
|
|
|
3623 p[keywords] span {
|
|
|
3624 display: inline-block;
|
|
|
3625 width: 100px;
|
|
|
3626 }
|
|
1716
|
3627 code {
|
|
|
3628 font-size: 16px;
|
|
|
3629 font-weight: bold;
|
|
|
3630 }
|
|
|
3631 div[toc] code {
|
|
|
3632 font-size: inherit;
|
|
|
3633 font-weight: inherit;
|
|
|
3634 }
|
|
1656
|
3635 </style>
|
|
|
3636 </head>
|
|
|
3637 <body>
|
|
|
3638 <% docs_header() %>
|
|
|
3639 <div content>
|
|
|
3640 <h1><a href="manual.html">Luan Reference Manual</a></h1>
|
|
|
3641 <p small>
|
|
|
3642 Original copyright © 2015 Lua.org, PUC-Rio.
|
|
|
3643 Freely available under the terms of the
|
|
|
3644 <a href="http://www.lua.org/license.html">Lua license</a>.
|
|
|
3645 Modified for Luan.
|
|
|
3646 </p>
|
|
|
3647 <hr>
|
|
|
3648 <h2>Contents</h2>
|
|
|
3649 <div toc>
|
|
|
3650 <% show_toc(content) %>
|
|
|
3651 </div>
|
|
|
3652 <hr>
|
|
|
3653 <% show_content(content,2) %>
|
|
|
3654 </div>
|
|
|
3655 </body>
|
|
|
3656 </html>
|
|
|
3657 <%
|
|
|
3658 end
|
