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 }
+ − 2418 ["String.encode"] = {
+ − 2419 title = "<code>String.encode (s)</code>"
+ − 2420 content = function()
+ − 2421 %>
+ − 2422 <p>
+ − 2423 Encodes argument <code>s</code> into a string that can be placed in quotes so as to return the original value of the string.
+ − 2424 </p>
+ − 2425 <%
+ − 2426 end
+ − 2427 }
+ − 2428 ["String.find"] = {
+ − 2429 title = "<code>String.find (s, pattern [, init [, plain]])</code>"
+ − 2430 content = function()
+ − 2431 %>
+ − 2432 <p>
+ − 2433 Looks for the first match of
+ − 2434 <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>.
+ − 2435 If it finds a match, then <code>find</code> returns the indices of <code>s</code>
+ − 2436 where this occurrence starts and ends;
+ − 2437 otherwise, it returns <b>nil</b>.
+ − 2438 A third, optional numerical argument <code>init</code> specifies
+ − 2439 where to start the search;
+ − 2440 its default value is 1 and can be negative.
+ − 2441 A value of <b>true</b> as a fourth, optional argument <code>plain</code>
+ − 2442 turns off the pattern matching facilities,
+ − 2443 so the function does a plain "find substring" operation,
+ − 2444 with no characters in <code>pattern</code> being considered magic.
+ − 2445 Note that if <code>plain</code> is given, then <code>init</code> must be given as well.
+ − 2446 </p>
+ − 2447
+ − 2448 <p>
+ − 2449 If the pattern has captures,
+ − 2450 then in a successful match
+ − 2451 the captured values are also returned,
+ − 2452 after the two indices.
+ − 2453 </p>
+ − 2454 <%
+ − 2455 end
+ − 2456 }
+ − 2457 ["String.format"] = {
+ − 2458 title = "<code>String.format (formatstring, ···)</code>"
+ − 2459 content = function()
+ − 2460 %>
+ − 2461 <p>
+ − 2462 Returns a formatted version of its variable number of arguments
+ − 2463 following the description given in its first argument (which must be a string).
+ − 2464 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.
+ − 2465 </p>
+ − 2466
+ − 2467 <p>
+ − 2468 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.
+ − 2469 </p>
+ − 2470 <%
+ − 2471 end
+ − 2472 }
+ − 2473 ["String.gmatch"] = {
+ − 2474 title = "<code>String.gmatch (s, pattern)</code>"
+ − 2475 content = function()
+ − 2476 %>
+ − 2477 <p>
+ − 2478 Returns an iterator function that,
+ − 2479 each time it is called,
+ − 2480 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>)
+ − 2481 over the string <code>s</code>.
+ − 2482 If <code>pattern</code> specifies no captures,
+ − 2483 then the whole match is produced in each call.
+ − 2484 </p>
+ − 2485
+ − 2486 <p>
+ − 2487 As an example, the following loop
+ − 2488 will iterate over all the words from string <code>s</code>,
+ − 2489 printing one per line:
+ − 2490 </p>
+ − 2491 <pre>
+ − 2492 local s = "hello world from Lua"
+ − 2493 for w in String.gmatch(s, [[\w+]]) do
+ − 2494 print(w)
+ − 2495 end
+ − 2496 </pre>
+ − 2497
+ − 2498 <p>
+ − 2499 The next example collects all pairs <code>key=value</code> from the
+ − 2500 given string into a table:
+ − 2501 </p>
+ − 2502 <pre>
+ − 2503 local t = {}
+ − 2504 local s = "from=world, to=Lua"
+ − 2505 for k, v in String.gmatch(s, [[(\w+)=(\w+)]]) do
+ − 2506 t[k] = v
+ − 2507 end
+ − 2508 </pre>
+ − 2509
+ − 2510 <p>
+ − 2511 For this function, a caret '<code>^</code>' at the start of a pattern does not
+ − 2512 work as an anchor, as this would prevent the iteration.
+ − 2513 </p>
+ − 2514 <%
+ − 2515 end
+ − 2516 }
+ − 2517 ["String.gsub"] = {
+ − 2518 title = "<code>String.gsub (s, pattern, repl [, n])</code>"
+ − 2519 content = function()
+ − 2520 %>
+ − 2521 <p>
+ − 2522 Returns a copy of <code>s</code>
+ − 2523 in which all (or the first <code>n</code>, if given)
+ − 2524 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
+ − 2525 replaced by a replacement string specified by <code>repl</code>,
+ − 2526 which can be a string, a table, or a function.
+ − 2527 <code>gsub</code> also returns, as its second value,
+ − 2528 the total number of matches that occurred.
+ − 2529 The name <code>gsub</code> comes from <em>Global SUBstitution</em>.
+ − 2530 </p>
+ − 2531
+ − 2532 <p>
+ − 2533 If <code>repl</code> is a string, then its value is used for replacement.
+ − 2534 The character <code>\</code> works as an escape character.
+ − 2535 Any sequence in <code>repl</code> of the form <code>$<em>d</em></code>,
+ − 2536 with <em>d</em> between 1 and 9,
+ − 2537 stands for the value of the <em>d</em>-th captured substring.
+ − 2538 The sequence <code>$0</code> stands for the whole match.
+ − 2539 </p>
+ − 2540
+ − 2541 <p>
+ − 2542 If <code>repl</code> is a table, then the table is queried for every match,
+ − 2543 using the first capture as the key.
+ − 2544 </p>
+ − 2545
+ − 2546 <p>
+ − 2547 If <code>repl</code> is a function, then this function is called every time a
+ − 2548 match occurs, with all captured substrings passed as arguments,
+ − 2549 in order.
+ − 2550 </p>
+ − 2551
+ − 2552 <p>
+ − 2553 In any case,
+ − 2554 if the pattern specifies no captures,
+ − 2555 then it behaves as if the whole pattern was inside a capture.
+ − 2556 </p>
+ − 2557
+ − 2558 <p>
+ − 2559 If the value returned by the table query or by the function call
+ − 2560 is not <b>nil</b>,
+ − 2561 then it is used as the replacement string;
+ − 2562 otherwise, if it is <b>nil</b>,
+ − 2563 then there is no replacement
+ − 2564 (that is, the original match is kept in the string).
+ − 2565 </p>
+ − 2566
+ − 2567 <p>
+ − 2568 Here are some examples:
+ − 2569 </p>
+ − 2570 <pre>
+ − 2571 x = String.gsub("hello world", [[(\w+)]], "$1 $1")
+ − 2572 --> x="hello hello world world"
+ − 2573
+ − 2574 x = String.gsub("hello world", [[\w+]], "$0 $0", 1)
+ − 2575 --> x="hello hello world"
+ − 2576
+ − 2577 x = String.gsub("hello world from Luan", [[(\w+)\s*(\w+)]], "$2 $1")
+ − 2578 --> x="world hello Luan from"
+ − 2579
+ − 2580 x = String.gsub("4+5 = $return 4+5$", [[\$(.*?)\$]], function (s)
+ − 2581 return load(s)()
+ − 2582 end)
+ − 2583 --> x="4+5 = 9"
+ − 2584
+ − 2585 local t = {name="lua", version="5.3"}
+ − 2586 x = String.gsub("$name-$version.tar.gz", [[\$(\w+)]], t)
+ − 2587 --> x="lua-5.3.tar.gz"
+ − 2588 </pre>
+ − 2589 <%
+ − 2590 end
+ − 2591 }
+ − 2592 ["String.lower"] = {
+ − 2593 title = "<code>String.lower (s)</code>"
+ − 2594 content = function()
+ − 2595 %>
+ − 2596 <p>
+ − 2597 Receives a string and returns a copy of this string with all
+ − 2598 uppercase letters changed to lowercase.
+ − 2599 All other characters are left unchanged.
+ − 2600 </p>
+ − 2601 <%
+ − 2602 end
+ − 2603 }
+ − 2604 ["String.match"] = {
+ − 2605 title = "<code>String.match (s, pattern [, init])</code>"
+ − 2606 content = function()
+ − 2607 %>
+ − 2608 <p>
+ − 2609 Looks for the first <em>match</em> of
+ − 2610 <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>.
+ − 2611 If it finds one, then <code>match</code> returns
+ − 2612 the captures from the pattern;
+ − 2613 otherwise it returns <b>nil</b>.
+ − 2614 If <code>pattern</code> specifies no captures,
+ − 2615 then the whole match is returned.
+ − 2616 A third, optional numerical argument <code>init</code> specifies
+ − 2617 where to start the search;
+ − 2618 its default value is 1 and can be negative.
+ − 2619 </p>
+ − 2620 <%
+ − 2621 end
+ − 2622 }
+ − 2623 ["String.matches"] = {
+ − 2624 title = "<code>String.matches (s, pattern)</code>"
+ − 2625 content = function()
+ − 2626 %>
+ − 2627 <p>
+ − 2628 Returns a boolean indicating whether the <code>pattern</code> can be found in string <code>s</code>.
+ − 2629 This function is equivalent to
+ − 2630 </p>
+ − 2631 <pre>
+ − 2632 return String.match(s,pattern) ~= nil
+ − 2633 </pre>
+ − 2634 <%
+ − 2635 end
+ − 2636 }
+ − 2637 ["String.regex_quote"] = {
+ − 2638 title = "<code>String.regex_quote (s)</code>"
+ − 2639 content = function()
+ − 2640 %>
+ − 2641 <p>
+ − 2642 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>.
+ − 2643 </p>
+ − 2644 <%
+ − 2645 end
+ − 2646 }
+ − 2647 ["String.rep"] = {
+ − 2648 title = "<code>String.rep (s, n [, sep])</code>"
+ − 2649 content = function()
+ − 2650 %>
+ − 2651 <p>
+ − 2652 Returns a string that is the concatenation of <code>n</code> copies of
+ − 2653 the string <code>s</code> separated by the string <code>sep</code>.
+ − 2654 The default value for <code>sep</code> is the empty string
+ − 2655 (that is, no separator).
+ − 2656 Returns the empty string if <code>n</code> is not positive.
+ − 2657 </p>
+ − 2658 <%
+ − 2659 end
+ − 2660 }
+ − 2661 ["String.reverse"] = {
+ − 2662 title = "<code>String.reverse (s)</code>"
+ − 2663 content = function()
+ − 2664 %>
+ − 2665 <p>
+ − 2666 Returns a string that is the string <code>s</code> reversed.
+ − 2667 </p>
+ − 2668 <%
+ − 2669 end
+ − 2670 }
+ − 2671 ["String.split"] = {
+ − 2672 title = "<code>String.split (s, pattern [, limit])</code>"
+ − 2673 content = function()
+ − 2674 %>
+ − 2675 <p>
+ − 2676 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.
+ − 2677 </p>
+ − 2678 <%
+ − 2679 end
+ − 2680 }
+ − 2681 ["String.sub"] = {
+ − 2682 title = "<code>String.sub (s, i [, j])</code>"
+ − 2683 content = function()
+ − 2684 %>
+ − 2685 <p>
+ − 2686 Returns the substring of <code>s</code> that
+ − 2687 starts at <code>i</code> and continues until <code>j</code>;
+ − 2688 <code>i</code> and <code>j</code> can be negative.
+ − 2689 If <code>j</code> is absent, then it is assumed to be equal to -1
+ − 2690 (which is the same as the string length).
+ − 2691 In particular,
+ − 2692 the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
+ − 2693 with length <code>j</code>,
+ − 2694 and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code>
+ − 2695 with length <code>i</code>.
+ − 2696 </p>
+ − 2697
+ − 2698 <p>
+ − 2699 If, after the translation of negative indices,
+ − 2700 <code>i</code> is less than 1,
+ − 2701 it is corrected to 1.
+ − 2702 If <code>j</code> is greater than the string length,
+ − 2703 it is corrected to that length.
+ − 2704 If, after these corrections,
+ − 2705 <code>i</code> is greater than <code>j</code>,
+ − 2706 the function returns the empty string.
+ − 2707 </p>
+ − 2708 <%
+ − 2709 end
+ − 2710 }
+ − 2711 ["String.to_binary"] = {
+ − 2712 title = "<code>String.to_binary (s)</code>"
+ − 2713 content = function()
+ − 2714 %>
+ − 2715 <p>
+ − 2716 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>.
+ − 2717 </p>
+ − 2718 <%
+ − 2719 end
+ − 2720 }
+ − 2721 ["String.to_number"] = {
+ − 2722 title = "<code>String.to_number (s [, base])</code>"
+ − 2723 content = function()
+ − 2724 %>
+ − 2725 <p>
+ − 2726 When called with no <code>base</code>,
+ − 2727 <code>to_number</code> tries to convert its argument to a number.
+ − 2728 If the argument is
+ − 2729 a string convertible to a number,
+ − 2730 then <code>to_number</code> returns this number;
+ − 2731 otherwise, it returns <b>nil</b>.
+ − 2732 The conversion of strings can result in integers or floats.
+ − 2733 </p>
+ − 2734
+ − 2735 <p>
+ − 2736 When called with <code>base</code>,
+ − 2737 then <code>s</code> must be a string to be interpreted as
+ − 2738 an integer numeral in that base.
+ − 2739 In bases above 10, the letter '<code>A</code>' (in either upper or lower case)
+ − 2740 represents 10, '<code>B</code>' represents 11, and so forth,
+ − 2741 with '<code>Z</code>' representing 35.
+ − 2742 If the string <code>s</code> is not a valid numeral in the given base,
+ − 2743 the function returns <b>nil</b>.
+ − 2744 </p>
+ − 2745 <%
+ − 2746 end
+ − 2747 }
+ − 2748 ["String.trim"] = {
+ − 2749 title = "<code>String.trim (s)</code>"
+ − 2750 content = function()
+ − 2751 %>
+ − 2752 <p>
+ − 2753 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>.
+ − 2754 </p>
+ − 2755 <%
+ − 2756 end
+ − 2757 }
+ − 2758 ["String.unicode"] = {
+ − 2759 title = "<code>String.unicode (s [, i [, j]])</code>"
+ − 2760 content = function()
+ − 2761 %>
+ − 2762 <p>
+ − 2763 Returns the internal numerical codes of the characters <code>s[i]</code>,
+ − 2764 <code>s[i+1]</code>, ..., <code>s[j]</code>.
+ − 2765 The default value for <code>i</code> is 1;
+ − 2766 the default value for <code>j</code> is <code>i</code>.
+ − 2767 These indices are corrected
+ − 2768 following the same rules of function <a href="#String.sub"><code>String.sub</code></a>.
+ − 2769 </p>
+ − 2770 <%
+ − 2771 end
+ − 2772 }
+ − 2773 ["String.upper"] = {
+ − 2774 title = "<code>String.upper (s)</code>"
+ − 2775 content = function()
+ − 2776 %>
+ − 2777 <p>
+ − 2778 Receives a string and returns a copy of this string with all
+ − 2779 lowercase letters changed to uppercase.
+ − 2780 All other characters are left unchanged.
+ − 2781 The definition of what a lowercase letter is depends on the current locale.
+ − 2782 </p>
+ − 2783 <%
+ − 2784 end
+ − 2785 }
+ − 2786 }
+ − 2787 }
+ − 2788 binary_lib = {
+ − 2789 title = "Binary Manipulation"
+ − 2790 content = function()
+ − 2791 %>
+ − 2792 <p>
+ − 2793 Include this library by:
+ − 2794 </p>
+ − 2795 <pre>
+ − 2796 local Binary = require "luan:Binary.luan"
+ − 2797 </pre>
+ − 2798 <%
+ − 2799 end
+ − 2800 subs = {
+ − 2801 ["Binary.binary"] = {
+ − 2802 title = "<code>Binary.binary (···)</code>"
+ − 2803 content = function()
+ − 2804 %>
+ − 2805 <p>
+ − 2806 Receives zero or more bytes (as integers).
+ − 2807 Returns a binary with length equal to the number of arguments,
+ − 2808 in which each byte has the internal numerical code equal
+ − 2809 to its corresponding argument.
+ − 2810 </p>
+ − 2811 <%
+ − 2812 end
+ − 2813 }
+ − 2814 ["Binary.byte"] = {
+ − 2815 title = "<code>Binary.byte (b [, i [, j]])</code>"
+ − 2816 content = function()
+ − 2817 %>
+ − 2818 <p>
+ − 2819 Returns the internal numerical codes of the bytes <code>b[i]</code>,
+ − 2820 <code>b[i+1]</code>, ..., <code>b[j]</code>.
+ − 2821 The default value for <code>i</code> is 1;
+ − 2822 the default value for <code>j</code> is <code>i</code>.
+ − 2823 These indices are corrected
+ − 2824 following the same rules of function <a href="#String.sub"><code>String.sub</code></a>.
+ − 2825 </p>
+ − 2826 <%
+ − 2827 end
+ − 2828 }
+ − 2829 ["Binary.to_string"] = {
+ − 2830 title = "<code>Binary.to_string (b [,charset])</code>"
+ − 2831 content = function()
+ − 2832 %>
+ − 2833 <p>
+ − 2834 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.
+ − 2835 </p>
+ − 2836 <%
+ − 2837 end
+ − 2838 }
+ − 2839 }
+ − 2840 }
+ − 2841 table_lib = {
+ − 2842 title = "Table Manipulation"
+ − 2843 content = function()
+ − 2844 %>
+ − 2845 <p>
+ − 2846 Include this library by:
+ − 2847 </p>
+ − 2848 <pre>
+ − 2849 local Table = require "luan:Table.luan"
+ − 2850 </pre>
+ − 2851
+ − 2852 <p>
+ − 2853 This library provides generic functions for table manipulation.
+ − 2854 It provides all its functions inside the table <code>Table</code>.
+ − 2855 </p>
+ − 2856 <%
+ − 2857 end
+ − 2858 subs = {
+ − 2859 ["Table.clear"] = {
+ − 2860 title = "<code>Table.clear (tbl)</code>"
+ − 2861 content = function()
+ − 2862 %>
+ − 2863 <p>
+ − 2864 Clears the table.
+ − 2865 </p>
+ − 2866 <%
+ − 2867 end
+ − 2868 }
+ − 2869 ["Table.concat"] = {
+ − 2870 title = "<code>Table.concat (list [, sep [, i [, j]]])</code>"
+ − 2871 content = function()
+ − 2872 %>
+ − 2873 <p>
+ − 2874 Given a list,
+ − 2875 returns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>.
+ − 2876 The default value for <code>sep</code> is the empty string,
+ − 2877 the default for <code>i</code> is 1,
+ − 2878 and the default for <code>j</code> is <code>#list</code>.
+ − 2879 If <code>i</code> is greater than <code>j</code>, returns the empty string.
+ − 2880 </p>
+ − 2881 <%
+ − 2882 end
+ − 2883 }
+ − 2884 ["Table.copy"] = {
+ − 2885 title = "<code>Table.copy (tbl [, i [, j]])</code>"
+ − 2886 content = function()
+ − 2887 %>
+ − 2888 <p>
+ − 2889 If <code>i</code> is <code>nil</code>, returns a shallow copy of <code>tbl</code>.
+ − 2890 Otherwise returns a new table which is a list of the elements <code>tbl[i] ··· tbl[j]</code>.
+ − 2891 By default, <code>j</code> is <code>#tbl</code>.
+ − 2892 </p>
+ − 2893 <%
+ − 2894 end
+ − 2895 }
+ − 2896 ["Table.insert"] = {
+ − 2897 title = "<code>Table.insert (list, pos, value)</code>"
+ − 2898 content = function()
+ − 2899 %>
+ − 2900 <p>
+ − 2901 Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>,
+ − 2902 shifting up the elements
+ − 2903 <code>list[pos], list[pos+1], ···, list[#list]</code>.
+ − 2904 </p>
+ − 2905 <%
+ − 2906 end
+ − 2907 }
+ − 2908 ["Table.is_empty"] = {
+ − 2909 title = "<code>Table.is_empty (tbl)</code>"
+ − 2910 content = function()
+ − 2911 %>
+ − 2912 <%
+ − 2913 end
+ − 2914 }
1704
+ − 2915 ["Table.is_list"] = {
+ − 2916 title = "<code>Table.is_list (tbl)</code>"
+ − 2917 content = function()
+ − 2918 %>
+ − 2919 <%
+ − 2920 end
+ − 2921 }
1668
+ − 2922 ["Table.pack"] = {
+ − 2923 title = "<code>Table.pack (···)</code>"
+ − 2924 content = function()
+ − 2925 %>
+ − 2926 <p>
+ − 2927 Returns a new table with all parameters stored into keys 1, 2, etc.
+ − 2928 and with a field "<code>n</code>" with the total number of parameters.
+ − 2929 Note that the resulting table may not be a sequence.
+ − 2930 </p>
+ − 2931 <%
+ − 2932 end
+ − 2933 }
+ − 2934 ["Table.remove"] = {
+ − 2935 title = "<code>Table.remove (list, pos)</code>"
+ − 2936 content = function()
+ − 2937 %>
+ − 2938 <p>
+ − 2939 Removes from <code>list</code> the element at position <code>pos</code>,
+ − 2940 returning the value of the removed element.
+ − 2941 When <code>pos</code> is an integer between 1 and <code>#list</code>,
+ − 2942 it shifts down the elements
+ − 2943 <code>list[pos+1], list[pos+2], ···, list[#list]</code>
+ − 2944 and erases element <code>list[#list]</code>;
+ − 2945 The index <code>pos</code> can also be 0 when <code>#list</code> is 0,
+ − 2946 or <code>#list + 1</code>;
+ − 2947 in those cases, the function erases the element <code>list[pos]</code>.
+ − 2948 </p>
+ − 2949 <%
+ − 2950 end
+ − 2951 }
+ − 2952 ["Table.size"] = {
+ − 2953 title = "<code>Table.size (tbl)</code>"
+ − 2954 content = function()
+ − 2955 %>
+ − 2956 <%
+ − 2957 end
+ − 2958 }
+ − 2959 ["Table.sort"] = {
+ − 2960 title = "<code>Table.sort (list [, comp])</code>"
+ − 2961 content = function()
+ − 2962 %>
+ − 2963 <p>
+ − 2964 Sorts list elements in a given order, <em>in-place</em>,
+ − 2965 from <code>list[1]</code> to <code>list[#list]</code>.
+ − 2966 If <code>comp</code> is given,
+ − 2967 then it must be a function that receives two list elements
+ − 2968 and returns true when the first element must come
+ − 2969 before the second in the final order
+ − 2970 (so that <code>not comp(list[i+1],list[i])</code> will be true after the sort).
+ − 2971 If <code>comp</code> is not given,
+ − 2972 then the standard Lua operator <code><</code> is used instead.
+ − 2973 </p>
+ − 2974
+ − 2975 <p>
+ − 2976 The sort algorithm is not stable;
+ − 2977 that is, elements considered equal by the given order
+ − 2978 may have their relative positions changed by the sort.
+ − 2979 </p>
+ − 2980 <%
+ − 2981 end
+ − 2982 }
+ − 2983 ["Table.unpack"] = {
+ − 2984 title = "<code>Table.unpack (list [, i [, j]])</code>"
+ − 2985 content = function()
+ − 2986 %>
+ − 2987 <p>
+ − 2988 Returns the elements from the given list.
+ − 2989 This function is equivalent to
+ − 2990 </p>
+ − 2991 <pre>
+ − 2992 return list[i], list[i+1], ···, list[j]
+ − 2993 </pre>
+ − 2994
+ − 2995 <p>
+ − 2996 By default, <code>i</code> is 1 and <code>j</code> is <code>list.n or #list</code>.
+ − 2997 </p>
+ − 2998 <%
+ − 2999 end
+ − 3000 }
+ − 3001 }
+ − 3002 }
+ − 3003 number_lib = {
+ − 3004 title = "Number Manipulation"
+ − 3005 content = function()
+ − 3006 %>
+ − 3007 <p>
+ − 3008 Include this library by:
+ − 3009 </p>
+ − 3010 <pre>
+ − 3011 local Number = require "luan:Number.luan"
+ − 3012 </pre>
+ − 3013 <%
+ − 3014 end
+ − 3015 subs = {
+ − 3016 ["Number.double"] = {
+ − 3017 title = "<code>Number.double (x)</code>"
+ − 3018 content = function()
+ − 3019 %>
+ − 3020 <p>
+ − 3021 Returns <code>x</code> as a double.
+ − 3022 </p>
+ − 3023 <%
+ − 3024 end
+ − 3025 }
+ − 3026 ["Number.float"] = {
+ − 3027 title = "<code>Number.float (x)</code>"
+ − 3028 content = function()
+ − 3029 %>
+ − 3030 <p>
+ − 3031 Returns <code>x</code> as a float.
+ − 3032 </p>
+ − 3033 <%
+ − 3034 end
+ − 3035 }
+ − 3036 ["Number.integer"] = {
+ − 3037 title = "<code>Number.integer (x)</code>"
+ − 3038 content = function()
+ − 3039 %>
+ − 3040 <p>
+ − 3041 If the value <code>x</code> is convertible to an integer,
+ − 3042 returns that integer.
+ − 3043 Otherwise throws an error.
+ − 3044 </p>
+ − 3045 <%
+ − 3046 end
+ − 3047 }
+ − 3048 ["Number.long"] = {
+ − 3049 title = "<code>Number.long (x)</code>"
+ − 3050 content = function()
+ − 3051 %>
+ − 3052 <p>
+ − 3053 If the value <code>x</code> is convertible to an long,
+ − 3054 returns that long.
+ − 3055 Otherwise throws an error.
+ − 3056 </p>
+ − 3057 <%
+ − 3058 end
+ − 3059 }
+ − 3060 ["Number.long_to_string"] = {
+ − 3061 title = "<code>Number.long_to_string (i, radix)</code>"
+ − 3062 content = function()
+ − 3063 %>
+ − 3064 <p>
+ − 3065 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>.
+ − 3066 </p>
+ − 3067 <%
+ − 3068 end
+ − 3069 }
+ − 3070 ["Number.type"] = {
+ − 3071 title = "<code>Number.type (x)</code>"
+ − 3072 content = function()
+ − 3073 %>
+ − 3074 <p>
+ − 3075 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>".
+ − 3076 </p>
+ − 3077 <%
+ − 3078 end
+ − 3079 }
+ − 3080 }
+ − 3081 }
1669
+ − 3082 math_lib = {
+ − 3083 title = "Mathematical Functions"
+ − 3084 content = function()
+ − 3085 %>
+ − 3086 <p>
+ − 3087 Include this library by:
+ − 3088 </p>
+ − 3089 <pre>
+ − 3090 local Math = require "luan:Math.luan"
+ − 3091 </pre>
+ − 3092
+ − 3093 <p>
+ − 3094 This library provides basic mathematical functions.
+ − 3095 It provides all its functions and constants inside the table <code>Math</code>.
+ − 3096 </p>
+ − 3097 <%
+ − 3098 end
+ − 3099 subs = {
+ − 3100 ["Math.abs"] = {
+ − 3101 title = "<code>Math.abs (x)</code>"
+ − 3102 content = function()
+ − 3103 %>
+ − 3104 <p>
+ − 3105 Returns the absolute value of <code>x</code>.
+ − 3106 </p>
+ − 3107 <%
+ − 3108 end
+ − 3109 }
+ − 3110 ["Math.acos"] = {
+ − 3111 title = "<code>Math.acos (x)</code>"
+ − 3112 content = function()
+ − 3113 %>
+ − 3114 <p>
+ − 3115 Returns the arc cosine of <code>x</code> (in radians).
+ − 3116 </p>
+ − 3117 <%
+ − 3118 end
+ − 3119 }
+ − 3120 ["Math.asin"] = {
+ − 3121 title = "<code>Math.asin (x)</code>"
+ − 3122 content = function()
+ − 3123 %>
+ − 3124 <p>
+ − 3125 Returns the arc sine of <code>x</code> (in radians).
+ − 3126 </p>
+ − 3127 <%
+ − 3128 end
+ − 3129 }
+ − 3130 ["Math.atan"] = {
+ − 3131 title = "<code>Math.atan (y, x)</code>"
+ − 3132 content = function()
+ − 3133 %>
+ − 3134 <p>
+ − 3135 Returns the arc tangent of <code>y/x</code> (in radians),
+ − 3136 but uses the signs of both parameters to find the
+ − 3137 quadrant of the result.
+ − 3138 (It also handles correctly the case of <code>x</code> being zero.)
+ − 3139 </p>
+ − 3140 <%
+ − 3141 end
+ − 3142 }
+ − 3143 ["Math.ceil"] = {
+ − 3144 title = "<code>Math.ceil (x)</code>"
+ − 3145 content = function()
+ − 3146 %>
+ − 3147 <p>
+ − 3148 Returns the smallest integral value larger than or equal to <code>x</code>.
+ − 3149 </p>
+ − 3150 <%
+ − 3151 end
+ − 3152 }
+ − 3153 ["Math.cos"] = {
+ − 3154 title = "<code>Math.cos (x)</code>"
+ − 3155 content = function()
+ − 3156 %>
+ − 3157 <p>
+ − 3158 Returns the cosine of <code>x</code> (assumed to be in radians).
+ − 3159 </p>
+ − 3160 <%
+ − 3161 end
+ − 3162 }
+ − 3163 ["Math.deg"] = {
+ − 3164 title = "<code>Math.deg (x)</code>"
+ − 3165 content = function()
+ − 3166 %>
+ − 3167 <p>
+ − 3168 Converts the angle <code>x</code> from radians to degrees.
+ − 3169 </p>
+ − 3170 <%
+ − 3171 end
+ − 3172 }
+ − 3173 ["Math.exp"] = {
+ − 3174 title = "<code>Math.exp (x)</code>"
+ − 3175 content = function()
+ − 3176 %>
+ − 3177 <p>
+ − 3178 Returns the value <em>e<sup>x</sup></em>
+ − 3179 (where <code>e</code> is the base of natural logarithms).
+ − 3180 </p>
+ − 3181 <%
+ − 3182 end
+ − 3183 }
+ − 3184 ["Math.floor"] = {
+ − 3185 title = "<code>Math.floor (x)</code>"
+ − 3186 content = function()
+ − 3187 %>
+ − 3188 <p>
+ − 3189 Returns the largest integral value smaller than or equal to <code>x</code>.
+ − 3190 </p>
+ − 3191 <%
+ − 3192 end
+ − 3193 }
+ − 3194 ["Math.fmod"] = {
+ − 3195 title = "<code>Math.fmod (x, y)</code>"
+ − 3196 content = function()
+ − 3197 %>
+ − 3198 <p>
+ − 3199 Returns the remainder of the division of <code>x</code> by <code>y</code>
+ − 3200 that rounds the quotient towards zero.
+ − 3201 </p>
+ − 3202 <%
+ − 3203 end
+ − 3204 }
+ − 3205 ["Math.huge"] = {
+ − 3206 title = "<code>Math.huge</code>"
+ − 3207 content = function()
+ − 3208 %>
+ − 3209 <p>
+ − 3210 A value larger than any other numerical value.
+ − 3211 </p>
+ − 3212 <%
+ − 3213 end
+ − 3214 }
+ − 3215 ["Math.log"] = {
+ − 3216 title = "<code>Math.log (x [, base])</code>"
+ − 3217 content = function()
+ − 3218 %>
+ − 3219 <p>
+ − 3220 Returns the logarithm of <code>x</code> in the given base.
+ − 3221 The default for <code>base</code> is <em>e</em>
+ − 3222 (so that the function returns the natural logarithm of <code>x</code>).
+ − 3223 </p>
+ − 3224 <%
+ − 3225 end
+ − 3226 }
+ − 3227 ["Math.max"] = {
+ − 3228 title = "<code>Math.max (x, ···)</code>"
+ − 3229 content = function()
+ − 3230 %>
+ − 3231 <p>
+ − 3232 Returns the argument with the maximum value,
+ − 3233 according to the Lua operator <code><</code>.
+ − 3234 </p>
+ − 3235 <%
+ − 3236 end
+ − 3237 }
+ − 3238 ["Math.max_integer"] = {
+ − 3239 title = "<code>Math.max_integer</code>"
+ − 3240 content = function()
+ − 3241 %>
+ − 3242 <p>
+ − 3243 An integer with the maximum value for an integer.
+ − 3244 </p>
+ − 3245 <%
+ − 3246 end
+ − 3247 }
+ − 3248 ["Math.min"] = {
+ − 3249 title = "<code>Math.min (x, ···)</code>"
+ − 3250 content = function()
+ − 3251 %>
+ − 3252 <p>
+ − 3253 Returns the argument with the minimum value,
+ − 3254 according to the Lua operator <code><</code>.
+ − 3255 </p>
+ − 3256 <%
+ − 3257 end
+ − 3258 }
+ − 3259 ["Math.min_integer"] = {
+ − 3260 title = "<code>Math.min_integer</code>"
+ − 3261 content = function()
+ − 3262 %>
+ − 3263 <p>
+ − 3264 An integer with the minimum value for an integer.
+ − 3265 </p>
+ − 3266 <%
+ − 3267 end
+ − 3268 }
+ − 3269 ["Math.modf"] = {
+ − 3270 title = "<code>Math.modf (x)</code>"
+ − 3271 content = function()
+ − 3272 %>
+ − 3273 <p>
+ − 3274 Returns the integral part of <code>x</code> and the fractional part of <code>x</code>.
+ − 3275 </p>
+ − 3276 <%
+ − 3277 end
+ − 3278 }
+ − 3279 ["Math.pi"] = {
+ − 3280 title = "<code>Math.pi</code>"
+ − 3281 content = function()
+ − 3282 %>
+ − 3283 <p>
+ − 3284 The value of <em>π</em>.
+ − 3285 </p>
+ − 3286 <%
+ − 3287 end
+ − 3288 }
+ − 3289 ["Math.rad"] = {
+ − 3290 title = "<code>Math.rad (x)</code>"
+ − 3291 content = function()
+ − 3292 %>
+ − 3293 <p>
+ − 3294 Converts the angle <code>x</code> from degrees to radians.
+ − 3295 </p>
+ − 3296 <%
+ − 3297 end
+ − 3298 }
+ − 3299 ["Math.random"] = {
+ − 3300 title = "<code>Math.random ([m [, n])</code>"
+ − 3301 content = function()
+ − 3302 %>
+ − 3303 <p>
+ − 3304 When called without arguments,
+ − 3305 returns a pseudo-random float with uniform distribution
+ − 3306 in the range <em>[0,1)</em>.
+ − 3307 When called with two integers <code>m</code> and <code>n</code>,
+ − 3308 <code>Math.random</code> returns a pseudo-random integer
+ − 3309 with uniform distribution in the range <em>[m, n]</em>.
+ − 3310 (The value <em>m-n</em> cannot be negative and must fit in a Luan integer.)
+ − 3311 The call <code>Math.random(n)</code> is equivalent to <code>Math.random(1,n)</code>.
+ − 3312 </p>
+ − 3313
+ − 3314 <p>
+ − 3315 This function is an interface to the underling
+ − 3316 pseudo-random generator function provided by Java.
+ − 3317 No guarantees can be given for its statistical properties.
+ − 3318 </p>
+ − 3319 <%
+ − 3320 end
+ − 3321 }
+ − 3322 ["Math.sin"] = {
+ − 3323 title = "<code>Math.sin (x)</code>"
+ − 3324 content = function()
+ − 3325 %>
+ − 3326 <p>
+ − 3327 Returns the sine of <code>x</code> (assumed to be in radians).
+ − 3328 </p>
+ − 3329 <%
+ − 3330 end
+ − 3331 }
+ − 3332 ["Math.sqrt"] = {
+ − 3333 title = "<code>Math.sqrt (x)</code>"
+ − 3334 content = function()
+ − 3335 %>
+ − 3336 <p>
+ − 3337 Returns the square root of <code>x</code>.
+ − 3338 (You can also use the expression <code>x^0.5</code> to compute this value.)
+ − 3339 </p>
+ − 3340 <%
+ − 3341 end
+ − 3342 }
+ − 3343 ["Math.tan"] = {
+ − 3344 title = "<code>Math.tan (x)</code>"
+ − 3345 content = function()
+ − 3346 %>
+ − 3347 <p>
+ − 3348 Returns the tangent of <code>x</code> (assumed to be in radians).
+ − 3349 </p>
+ − 3350 <%
+ − 3351 end
+ − 3352 }
+ − 3353 }
+ − 3354 }
1656
+ − 3355 }
+ − 3356 }
+ − 3357 }
+ − 3358
+ − 3359
+ − 3360 return function()
+ − 3361 Io.stdout = Http.response.text_writer()
+ − 3362 %>
+ − 3363 <!doctype html>
+ − 3364 <html>
+ − 3365 <head>
+ − 3366 <% head() %>
+ − 3367 <title>Luan Reference Manual</title>
+ − 3368 <style>
+ − 3369 p[keywords] {
+ − 3370 font-family: monospace;
+ − 3371 margin-left: 40px;
+ − 3372 max-width: 700px;
+ − 3373 }
+ − 3374 p[keywords] span {
+ − 3375 display: inline-block;
+ − 3376 width: 100px;
+ − 3377 }
+ − 3378 </style>
+ − 3379 </head>
+ − 3380 <body>
+ − 3381 <% docs_header() %>
+ − 3382 <div content>
+ − 3383 <h1><a href="manual.html">Luan Reference Manual</a></h1>
+ − 3384 <p small>
+ − 3385 Original copyright © 2015 Lua.org, PUC-Rio.
+ − 3386 Freely available under the terms of the
+ − 3387 <a href="http://www.lua.org/license.html">Lua license</a>.
+ − 3388 Modified for Luan.
+ − 3389 </p>
+ − 3390 <hr>
+ − 3391 <h2>Contents</h2>
+ − 3392 <div toc>
+ − 3393 <% show_toc(content) %>
+ − 3394 </div>
+ − 3395 <hr>
+ − 3396 <% show_content(content,2) %>
+ − 3397 </div>
+ − 3398 </body>
+ − 3399 </html>
+ − 3400 <%
+ − 3401 end