Mercurial Hosting > luan
annotate website/src/manual.html.luan @ 1809:90187946d1a4
minor
| author | Franklin Schmidt <fschmidt@gmail.com> |
|---|---|
| date | Sun, 12 May 2024 17:15:33 -0600 |
| parents | ba43135bb98d |
| children | f44dcb3fedf7 |
| rev | line source |
|---|---|
| 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 } | |
| 1797 | 1791 backticks = { |
| 1792 title = "Backticks" | |
| 1793 content = function() | |
| 1794 %> | |
| 1795 <p> | |
| 1796 A block between backticks is run and then whatever was sent to standard output is returned as a string. Examples: | |
| 1797 </p> | |
| 1798 <pre> | |
| 1799 local s = `%>1 + 1 = <%=1+1%><%` | |
| 1800 | |
| 1801 local s = ` fn(whatever) ` | |
| 1802 | |
| 1803 local s = `%> | |
| 1804 ... | |
| 1805 <%` | |
| 1806 </pre> | |
| 1807 <p> | |
| 1808 Backticks complement <a href="#template_stmt">template statements</a>. | |
| 1809 </p> | |
| 1810 <% | |
| 1811 end | |
| 1812 } | |
| 1667 | 1813 } |
| 1814 } | |
| 1815 visibility = { | |
| 1816 title = "Visibility Rules" | |
| 1817 content = function() | |
| 1818 %> | |
| 1819 <p> | |
| 1820 Luan is a lexically scoped language. | |
| 1821 The scope of a local variable begins at the first statement after | |
| 1822 its declaration and lasts until the last non-void statement | |
| 1823 of the innermost block that includes the declaration. | |
| 1824 Consider the following example: | |
| 1825 </p> | |
| 1826 <pre> | |
| 1827 x = 10 -- global variable | |
| 1828 do -- new block | |
| 1829 local x = x -- new 'x', with value 10 | |
| 1830 print(x) --> 10 | |
| 1831 x = x+1 | |
| 1832 do -- another block | |
| 1833 local x = x+1 -- another 'x' | |
| 1834 print(x) --> 12 | |
| 1835 end | |
| 1836 print(x) --> 11 | |
| 1837 end | |
| 1838 print(x) --> 10 (the global one) | |
| 1839 </pre> | |
| 1840 | |
| 1841 <p> | |
| 1842 Notice that, in a declaration like <code>local x = x</code>, | |
| 1843 the new <code>x</code> being declared is not in scope yet, | |
| 1844 and so the second <code>x</code> refers to the outside variable. | |
| 1845 </p> | |
| 1846 | |
| 1847 <p> | |
| 1848 Because of the lexical scoping rules, | |
| 1849 local variables can be freely accessed by functions | |
| 1850 defined inside their scope. | |
| 1851 A local variable used by an inner function is called | |
| 1852 an <em>upvalue</em>, or <em>external local variable</em>, | |
| 1853 inside the inner function. | |
| 1854 </p> | |
| 1855 | |
| 1856 <p> | |
| 1857 Notice that each execution of a <b>local</b> statement | |
| 1858 defines new local variables. | |
| 1859 Consider the following example: | |
| 1860 </p> | |
| 1861 <pre> | |
| 1862 a = {} | |
| 1863 local x = 20 | |
| 1864 for i=1,10 do | |
| 1865 local y = 0 | |
| 1866 a[i] = function () y=y+1; return x+y end | |
| 1867 end | |
| 1868 </pre> | |
| 1869 | |
| 1870 <p> | |
| 1871 The loop creates ten closures | |
| 1872 (that is, ten instances of the anonymous function). | |
| 1873 Each of these closures uses a different <code>y</code> variable, | |
| 1874 while all of them share the same <code>x</code>. | |
| 1875 </p> | |
| 1876 <% | |
| 1877 end | |
| 1878 } | |
| 1879 } | |
| 1880 } | |
| 1881 libs = { | |
| 1882 title = "Standard Libraries" | |
| 1883 content = function() | |
| 1884 %> | |
| 1885 <p> | |
| 1886 The standard Luan libraries provide useful functions | |
| 1887 that are implemented both in Java and in Luan itself. | |
| 1888 How each function is implemented shouldn't matter to the user. | |
| 1889 Some of these functions provide essential services to the language | |
| 1890 (e.g., <a href="#Luan.type"><code>type</code></a> and <a href="#Luan.get_metatable"><code>get_metatable</code></a>); | |
| 1891 others provide access to "outside" services (e.g., I/O). | |
| 1892 </p> | |
| 1893 <% | |
| 1894 end | |
| 1895 subs = { | |
| 1896 default_lib = { | |
| 1897 title = "Default Environment" | |
| 1898 content = function() | |
| 1899 %> | |
| 1900 <p> | |
| 1901 This is provided by default as a local variable for any Luan code as described in <a href="#env">Environments</a>. | |
| 1902 </p> | |
| 1903 <% | |
| 1904 end | |
| 1905 subs = { | |
| 1906 require = { | |
| 1907 title = "<code>require (mod_uri)</code>" | |
| 1908 content = function() | |
| 1909 %> | |
| 1910 <p> | |
| 1911 Example use: | |
| 1912 </p> | |
| 1913 <pre> | |
| 1914 local Table = require "luan:Table.luan" | |
| 1915 </pre> | |
| 1916 | |
| 1917 <p> | |
| 1918 Could be defined as: | |
| 1919 </p> | |
| 1920 <pre> | |
| 1921 local function require(mod_name) | |
| 1922 return <a href="#Package.load">Package.load</a>(mod_name) or <a href="#Luan.error">Luan.error</a>("module '"..mod_name.."' not found") | |
| 1923 end | |
| 1924 </pre> | |
| 1925 | |
| 1926 <p> | |
| 1927 A special case is: | |
| 1928 </p> | |
| 1929 <pre> | |
| 1930 require "java" | |
| 1931 </pre> | |
| 1932 | |
| 1933 <p> | |
| 1934 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. | |
| 1935 </p> | |
| 1936 <% | |
| 1937 end | |
| 1938 } | |
| 1939 } | |
| 1940 } | |
| 1941 luan_lib = { | |
| 1942 title = "Basic Functions" | |
| 1943 content = function() | |
| 1944 %> | |
| 1945 <p> | |
| 1946 Include this library by: | |
| 1947 </p> | |
| 1948 <pre> | |
| 1949 local Luan = require "luan:Luan.luan" | |
| 1950 </pre> | |
| 1951 | |
| 1952 <p> | |
| 1953 The basic library provides basic functions to Luan that don't depend on other libaries. | |
| 1954 </p> | |
| 1955 <% | |
| 1956 end | |
| 1957 subs = { | |
| 1958 ["Luan.do_file"] = { | |
| 1959 title = "<code>Luan.do_file ([uri])</code>" | |
| 1960 content = function() | |
| 1961 %> | |
| 1962 <p> | |
| 1963 Could be defined as: | |
| 1964 </p> | |
| 1965 <pre> | |
| 1966 function Luan.do_file(uri) | |
| 1967 local fn = <a href="#Luan.load_file">Luan.load_file</a>(uri) or <a href="#Luan.error">Luan.error</a>("file '"..uri.."' not found") | |
| 1968 return fn() | |
| 1969 end | |
| 1970 </pre> | |
| 1971 <% | |
| 1972 end | |
| 1973 } | |
| 1974 ["Luan.error"] = { | |
| 1975 title = "<code>Luan.error (message)</code>" | |
| 1976 content = function() | |
| 1977 %> | |
| 1978 <p> | |
| 1979 Throws an error containing the message. | |
| 1980 </p> | |
| 1981 | |
| 1982 <p> | |
| 1983 Could be defined as: | |
| 1984 </p> | |
| 1985 <pre> | |
| 1986 function Luan.error(message) | |
| 1987 <a href="#Luan.new_error">Luan.new_error</a>(message).throw() | |
| 1988 end | |
| 1989 </pre> | |
| 1990 <% | |
| 1991 end | |
| 1992 } | |
| 1993 ["Luan.eval"] = { | |
| 1994 title = "<code>Luan.eval (text [, source_name [, env]])</code>" | |
| 1995 content = function() | |
| 1996 %> | |
| 1997 <p> | |
| 1998 Evaluates <code>text</code> as a Luan expression. | |
| 1999 </p> | |
| 2000 | |
| 2001 <p> | |
| 2002 Could be defined as: | |
| 2003 </p> | |
| 2004 <pre> | |
| 2005 function Luan.eval(text,source_name, env) | |
| 2006 return <a href="#Luan.load">Luan.load</a>( "return "..text, source_name or "eval", env )() | |
| 2007 end | |
| 2008 </pre> | |
| 2009 <% | |
| 2010 end | |
| 2011 } | |
| 2012 ["Luan.get_metatable"] = { | |
| 2013 title = "<code>Luan.get_metatable (table)</code>" | |
| 2014 content = function() | |
| 2015 %> | |
| 2016 <p> | |
| 2017 If <code>table</code> does not have a metatable, returns <b>nil</b>. | |
| 2018 Otherwise, | |
| 2019 if the table's metatable has a <code>"__metatable"</code> field, | |
| 2020 returns the associated value. | |
| 2021 Otherwise, returns the metatable of the given table. | |
| 2022 </p> | |
| 2023 <% | |
| 2024 end | |
| 2025 } | |
| 2026 ["Luan.hash_code"] = { | |
| 2027 title = "<code>Luan.hash_code (v)</code>" | |
| 2028 content = function() | |
| 2029 %> | |
| 2030 <p> | |
| 2031 Returns the hash code of <code>v</code>. | |
| 2032 </p> | |
| 2033 <% | |
| 2034 end | |
| 2035 } | |
| 2036 ["Luan.ipairs"] = { | |
| 2037 title = "<code>Luan.ipairs (t)</code>" | |
| 2038 content = function() | |
| 2039 %> | |
| 2040 <p> | |
| 2041 Returns an iterator function | |
| 2042 so that the construction | |
| 2043 </p> | |
| 2044 <pre> | |
| 2045 for i,v in ipairs(t) do <em>body</em> end | |
| 2046 </pre> | |
| 2047 | |
| 2048 <p> | |
| 2049 will iterate over the key–value pairs | |
| 2050 (<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., | |
| 2051 up to the first nil value. | |
| 2052 </p> | |
| 2053 | |
| 2054 <p> | |
| 2055 Could be defined as: | |
| 2056 </p> | |
| 2057 <pre> | |
| 2058 function Luan.ipairs(t) | |
| 2059 local i = 0 | |
| 2060 return function() | |
| 2061 if i < #t then | |
| 2062 i = i + 1 | |
| 2063 return i, t[i] | |
| 2064 end | |
| 2065 end | |
| 2066 end | |
| 2067 </pre> | |
| 2068 <% | |
| 2069 end | |
| 2070 } | |
| 2071 ["Luan.load"] = { | |
| 2072 title = "<code>Luan.load (text, [source_name [, env [, persist]]])</code>" | |
| 2073 content = function() | |
| 2074 %> | |
| 2075 <p> | |
| 2076 Loads a chunk. | |
| 2077 </p> | |
| 2078 | |
| 2079 <p> | |
| 2080 The <code>text</code> is compiled. | |
| 2081 If there are no syntactic errors, | |
| 2082 returns the compiled chunk as a function; | |
| 2083 otherwise, throws an error. | |
| 2084 </p> | |
| 2085 | |
| 2086 <p> | |
| 2087 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". | |
| 2088 </p> | |
| 2089 | |
| 2090 <p> | |
| 2091 If the <code>env</code> parameter is supplied, it becomes the <code>_ENV</code> of the chunk. | |
| 2092 </p> | |
| 2093 | |
| 2094 <p> | |
| 2095 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>. | |
| 2096 </p> | |
| 2097 <% | |
| 2098 end | |
| 2099 } | |
| 2100 ["Luan.load_file"] = { | |
| 2101 title = "<code>Luan.load_file (file_uri)</code>" | |
| 2102 content = function() | |
| 2103 %> | |
| 2104 <p> | |
| 2105 Similar to <a href="#Luan.load"><code>load</code></a>, | |
| 2106 but gets the chunk from file <code>file_uri</code>. | |
| 2107 <code>file_uri</code> can be a string or a uri table. | |
| 2108 </p> | |
| 2109 <% | |
| 2110 end | |
| 2111 } | |
| 2112 ["Luan.new_error"] = { | |
| 2113 title = "<code>Luan.new_error (message)</code>" | |
| 2114 content = function() | |
| 2115 %> | |
| 2116 <p> | |
| 2117 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. | |
| 2118 </p> | |
| 2119 | |
| 2120 <p> | |
| 2121 To print the current stack trace, you could do: | |
| 2122 </p> | |
| 2123 <pre> | |
| 2124 Io.print( Luan.new_error "stack" ) | |
| 2125 </pre> | |
| 2126 <% | |
| 2127 end | |
| 2128 } | |
| 2129 ["Luan.pairs"] = { | |
| 2130 title = "<code>Luan.pairs (t)</code>" | |
| 2131 content = function() | |
| 2132 %> | |
| 2133 <p> | |
| 2134 If <code>t</code> has a metamethod <code>__pairs</code>, | |
| 2135 calls it with <code>t</code> as argument and returns the | |
| 2136 result from the call. | |
| 2137 </p> | |
| 2138 | |
| 2139 <p> | |
| 2140 Otherwise, | |
| 2141 returns a function | |
| 2142 so that the construction | |
| 2143 </p> | |
| 2144 <pre> | |
| 2145 for k,v in pairs(t) do <em>body</em> end | |
| 2146 </pre> | |
| 2147 | |
| 2148 <p> | |
| 2149 will iterate over all key–value pairs of table <code>t</code>. | |
| 2150 </p> | |
| 2151 <% | |
| 2152 end | |
| 2153 } | |
| 2154 ["Luan.range"] = { | |
| 2155 title = "<code>Luan.range (start, stop [, step])</code>" | |
| 2156 content = function() | |
| 2157 %> | |
| 2158 <p> | |
| 2159 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. | |
| 2160 </p> | |
| 2161 | |
| 2162 <p> | |
| 2163 Example use: | |
| 2164 </p> | |
| 2165 <pre> | |
| 2166 for i in range(1,10) do | |
| 2167 Io.print("count up:",i) | |
| 2168 end | |
| 2169 for i in range(10,0,-1) do | |
| 2170 Io.print("count down:",i) | |
| 2171 end | |
| 2172 </pre> | |
| 2173 | |
| 2174 <p> | |
| 2175 Could be defined as: | |
| 2176 </p> | |
| 2177 <pre> | |
| 2178 function Luan.range(start, stop, step) | |
| 2179 step = step or 1 | |
| 2180 step == 0 and <a href="#Luan.error">Luan.error</a> "bad argument #3 (step may not be zero)" | |
| 2181 local i = start | |
| 2182 return function() | |
| 2183 if step > 0 and i <= stop or step < 0 and i >= stop then | |
| 2184 local rtn = i | |
| 2185 i = i + step | |
| 2186 return rtn | |
| 2187 end | |
| 2188 end | |
| 2189 end | |
| 2190 </pre> | |
| 2191 <% | |
| 2192 end | |
| 2193 } | |
| 2194 ["Luan.raw_equal"] = { | |
| 2195 title = "<code>Luan.raw_equal (v1, v2)</code>" | |
| 2196 content = function() | |
| 2197 %> | |
| 2198 <p> | |
| 2199 Checks whether <code>v1</code> is equal to <code>v2</code>, | |
| 2200 without invoking any metamethod. | |
| 2201 Returns a boolean. | |
| 2202 </p> | |
| 2203 <% | |
| 2204 end | |
| 2205 } | |
| 2206 ["Luan.raw_get"] = { | |
| 2207 title = "<code>Luan.raw_get (table, index)</code>" | |
| 2208 content = function() | |
| 2209 %> | |
| 2210 <p> | |
| 2211 Gets the real value of <code>table[index]</code>, | |
| 2212 without invoking any metamethod. | |
| 2213 <code>table</code> must be a table; | |
| 2214 <code>index</code> may be any value. | |
| 2215 </p> | |
| 2216 <% | |
| 2217 end | |
| 2218 } | |
| 2219 ["Luan.raw_len"] = { | |
| 2220 title = "<code>Luan.raw_len (v)</code>" | |
| 2221 content = function() | |
| 2222 %> | |
| 2223 <p> | |
| 2224 Returns the length of the object <code>v</code>, | |
| 2225 which must be a table or a string, | |
| 2226 without invoking any metamethod. | |
| 2227 Returns an integer. | |
| 2228 </p> | |
| 2229 <% | |
| 2230 end | |
| 2231 } | |
| 2232 ["Luan.raw_set"] = { | |
| 2233 title = "<code>Luan.raw_set (table, index, value)</code>" | |
| 2234 content = function() | |
| 2235 %> | |
| 2236 <p> | |
| 2237 Sets the real value of <code>table[index]</code> to <code>value</code>, | |
| 2238 without invoking any metamethod. | |
| 2239 <code>table</code> must be a table, | |
| 2240 <code>index</code> any value different from <b>nil</b>, | |
| 2241 and <code>value</code> any Luan value. | |
| 2242 </p> | |
| 2243 <% | |
| 2244 end | |
| 2245 } | |
| 2246 ["Luan.set_metatable"] = { | |
| 2247 title = "<code>Luan.set_metatable (table, metatable)</code>" | |
| 2248 content = function() | |
| 2249 %> | |
| 2250 <p> | |
| 2251 Sets the metatable for the given table. | |
| 2252 If <code>metatable</code> is <b>nil</b>, | |
| 2253 removes the metatable of the given table. | |
| 2254 If the original metatable has a <code>"__metatable"</code> field, | |
| 2255 raises an error. | |
| 2256 </p> | |
| 2257 <% | |
| 2258 end | |
| 2259 } | |
| 2260 ["Luan.stringify"] = { | |
| 2261 title = "<code>Luan.stringify (v [,options])</code>" | |
| 2262 content = function() | |
| 2263 %> | |
| 2264 <p> | |
| 2265 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. | |
| 2266 </p> | |
| 2267 <% | |
| 2268 end | |
| 2269 } | |
| 2270 ["Luan.to_string"] = { | |
| 2271 title = "<code>Luan.to_string (v)</code>" | |
| 2272 content = function() | |
| 2273 %> | |
| 2274 <p> | |
| 2275 Receives a value of any type and | |
| 2276 converts it to a string in a human-readable format. | |
| 2277 </p> | |
| 2278 | |
| 2279 <p> | |
| 2280 If the metatable of <code>v</code> has a <code>"__to_string"</code> field, | |
| 2281 then <code>to_string</code> calls the corresponding value | |
| 2282 with <code>v</code> as argument, | |
| 2283 and uses the result of the call as its result. | |
| 2284 </p> | |
| 2285 <% | |
| 2286 end | |
| 2287 } | |
| 2288 ["Luan.type"] = { | |
| 2289 title = "<code>Luan.type (v)</code>" | |
| 2290 content = function() | |
| 2291 %> | |
| 2292 <p> | |
| 2293 Returns the type of its only argument, coded as a string. | |
| 2294 The possible results of this function are | |
| 2295 "<code>nil</code>" (a string, not the value <b>nil</b>), | |
| 2296 "<code>number</code>", | |
| 2297 "<code>string</code>", | |
| 2298 "<code>binary</code>", | |
| 2299 "<code>boolean</code>", | |
| 2300 "<code>table</code>", | |
| 2301 "<code>function</code>", | |
| 2302 and "<code>java</code>". | |
| 2303 </p> | |
| 2304 <% | |
| 2305 end | |
| 2306 } | |
| 2307 ["Luan.values"] = { | |
| 2308 title = "<code>Luan.values (···)</code>" | |
| 2309 content = function() | |
| 2310 %> | |
| 2311 <p> | |
| 2312 Returns a function so that the construction | |
| 2313 </p> | |
| 2314 <pre> | |
| 2315 for i, v in Luan.values(···) do <em>body</em> end | |
| 2316 </pre> | |
| 2317 | |
| 2318 <p> | |
| 2319 will iterate over all values of <code>···</code>. | |
| 2320 </p> | |
| 2321 <% | |
| 2322 end | |
| 2323 } | |
| 2324 ["Luan.VERSION"] = { | |
| 2325 title = "<code>Luan.VERSION</code>" | |
| 2326 content = function() | |
| 2327 %> | |
| 2328 <p> | |
| 2329 A global variable (not a function) that | |
| 2330 holds a string containing the current Luan version. | |
| 2331 </p> | |
| 2332 <% | |
| 2333 end | |
| 2334 } | |
| 2335 } | |
| 2336 } | |
| 2337 package_lib = { | |
| 2338 title = "Modules" | |
| 2339 content = function() | |
| 2340 %> | |
| 2341 <p> | |
| 2342 Include this library by: | |
| 2343 </p> | |
| 2344 <pre> | |
| 2345 local Package = require "luan:Package.luan" | |
| 2346 </pre> | |
| 2347 | |
| 2348 <p> | |
| 2349 The package library provides basic | |
| 2350 facilities for loading modules in Luan. | |
| 2351 </p> | |
| 2352 <% | |
| 2353 end | |
| 2354 subs = { | |
| 2355 ["Package.load"] = { | |
| 2356 title = "<code>Package.load (mod_uri)</code>" | |
| 2357 content = function() | |
| 2358 %> | |
| 2359 <p> | |
| 2360 Loads the given module. | |
| 2361 The function starts by looking into the <a href="#Package.loaded"><code>Package.loaded</code></a> table | |
| 2362 to determine whether <code>mod_uri</code> is already loaded. | |
| 2363 If it is, then <code>Package.load</code> returns the value stored | |
| 2364 at <code>Package.loaded[mod_uri]</code>. | |
| 2365 Otherwise, it tries to load a new value for the module. | |
| 2366 </p> | |
| 2367 | |
| 2368 <p> | |
| 2369 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. | |
| 2370 </p> | |
| 2371 | |
| 2372 <p> | |
| 2373 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. | |
| 2374 </p> | |
| 2375 | |
| 2376 <p> | |
| 2377 If a new value for the module successful loaded, then it is stored in <code>Package.loaded[mod_uri]</code>. The value is returned. | |
| 2378 </p> | |
| 2379 <% | |
| 2380 end | |
| 2381 } | |
| 2382 ["Package.loaded"] = { | |
| 2383 title = "<code>Package.loaded</code>" | |
| 2384 content = function() | |
| 2385 %> | |
| 2386 <p> | |
| 2387 A table used by <a href="#Package.load"><code>Package.load</code></a> to control which | |
| 2388 modules are already loaded. | |
| 2389 When you load a module <code>mod_uri</code> and | |
| 2390 <code>Package.loaded[mod_uri]</code> is not <b>nil</b>, | |
| 2391 <a href="#Package.load"><code>Package.load</code></a> simply returns the value stored there. | |
| 2392 </p> | |
| 2393 | |
| 2394 <p> | |
| 2395 This variable is only a reference to the real table; | |
| 2396 assignments to this variable do not change the | |
| 2397 table used by <a href="#Package.load"><code>Package.load</code></a>. | |
| 2398 </p> | |
| 2399 <% | |
| 2400 end | |
| 2401 } | |
| 1656 | 2402 } |
| 2403 } | |
| 1668 | 2404 string_lib = { |
| 2405 title = "String Manipulation" | |
| 2406 content = function() | |
| 2407 %> | |
| 2408 <p> | |
| 2409 Include this library by: | |
| 2410 </p> | |
| 2411 <pre> | |
| 2412 local String = require "luan:String.luan" | |
| 2413 </pre> | |
| 2414 | |
| 2415 <p> | |
| 2416 This library provides generic functions for string manipulation, | |
| 2417 such as finding and extracting substrings, and pattern matching. | |
| 2418 When indexing a string in Luan, the first character is at position 1 | |
| 2419 (not at 0, as in Java). | |
| 2420 Indices are allowed to be negative and are interpreted as indexing backwards, | |
| 2421 from the end of the string. | |
| 2422 Thus, the last character is at position -1, and so on. | |
| 2423 </p> | |
| 2424 <% | |
| 2425 end | |
| 2426 subs = { | |
| 2427 ["String.char"] = { | |
| 2428 title = "<code>String.char (···)</code>" | |
| 2429 content = function() | |
| 2430 %> | |
| 2431 <p> | |
| 2432 Receives zero or more integers. | |
| 2433 Returns a string with length equal to the number of arguments, | |
| 2434 in which each character has the internal numerical code equal | |
| 2435 to its corresponding argument. | |
| 2436 </p> | |
| 2437 <% | |
| 2438 end | |
| 2439 } | |
| 1716 | 2440 ["String.contains"] = { |
| 2441 title = "<code>String.contains (s, s2)</code>" | |
| 2442 content = function() | |
| 2443 %> | |
| 2444 <p> | |
| 2445 Returns a boolean indicating whether the <code>s</code> contains <code>s2</code>. | |
| 2446 </p> | |
| 2447 <% | |
| 2448 end | |
| 2449 } | |
| 1668 | 2450 ["String.encode"] = { |
| 2451 title = "<code>String.encode (s)</code>" | |
| 2452 content = function() | |
| 2453 %> | |
| 2454 <p> | |
| 2455 Encodes argument <code>s</code> into a string that can be placed in quotes so as to return the original value of the string. | |
| 2456 </p> | |
| 2457 <% | |
| 2458 end | |
| 2459 } | |
| 1716 | 2460 ["String.ends_with"] = { |
| 2461 title = "<code>String.ends_with (s, s2)</code>" | |
| 2462 content = function() | |
| 2463 %> | |
| 2464 <p> | |
| 2465 Returns a boolean indicating whether the <code>s</code> ends with <code>s2</code>. | |
| 2466 </p> | |
| 2467 <% | |
| 2468 end | |
| 2469 } | |
| 1668 | 2470 ["String.find"] = { |
|
1721
5c69d2e8bd75
no regex in String.find and String.split
Franklin Schmidt <fschmidt@gmail.com>
parents:
1719
diff
changeset
|
2471 title = "<code>String.find (s, s2 [, init])</code>" |
| 1668 | 2472 content = function() |
| 2473 %> | |
| 2474 <p> | |
|
1721
5c69d2e8bd75
no regex in String.find and String.split
Franklin Schmidt <fschmidt@gmail.com>
parents:
1719
diff
changeset
|
2475 Looks for the first substring |
|
5c69d2e8bd75
no regex in String.find and String.split
Franklin Schmidt <fschmidt@gmail.com>
parents:
1719
diff
changeset
|
2476 <code>s2</code> in the string <code>s</code>. |
| 1668 | 2477 If it finds a match, then <code>find</code> returns the indices of <code>s</code> |
| 2478 where this occurrence starts and ends; | |
| 2479 otherwise, it returns <b>nil</b>. | |
| 2480 A third, optional numerical argument <code>init</code> specifies | |
| 2481 where to start the search; | |
| 2482 its default value is 1 and can be negative. | |
| 2483 </p> | |
| 2484 | |
| 2485 <p> | |
| 2486 If the pattern has captures, | |
| 2487 then in a successful match | |
| 2488 the captured values are also returned, | |
| 2489 after the two indices. | |
| 2490 </p> | |
| 2491 <% | |
| 2492 end | |
| 2493 } | |
| 2494 ["String.format"] = { | |
| 2495 title = "<code>String.format (formatstring, ···)</code>" | |
| 2496 content = function() | |
| 2497 %> | |
| 2498 <p> | |
| 2499 Returns a formatted version of its variable number of arguments | |
| 2500 following the description given in its first argument (which must be a string). | |
| 2501 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. | |
| 2502 </p> | |
| 2503 | |
| 2504 <p> | |
| 2505 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. | |
| 2506 </p> | |
| 2507 <% | |
| 2508 end | |
| 2509 } | |
| 2510 ["String.lower"] = { | |
| 2511 title = "<code>String.lower (s)</code>" | |
| 2512 content = function() | |
| 2513 %> | |
| 2514 <p> | |
| 2515 Receives a string and returns a copy of this string with all | |
| 2516 uppercase letters changed to lowercase. | |
| 2517 All other characters are left unchanged. | |
| 2518 </p> | |
| 2519 <% | |
| 2520 end | |
| 2521 } | |
| 1716 | 2522 ["String.regex"] = { |
| 2523 title = "<code>String.regex (s)</code>" | |
| 2524 content = function() | |
| 2525 %> | |
| 2526 <p> | |
| 2527 Returns a <a href="#regex_table">regex</a> table for the pattern <code>s</code>. | |
| 2528 </p> | |
| 2529 <% | |
| 2530 end | |
| 2531 } | |
| 1668 | 2532 ["String.regex_quote"] = { |
| 2533 title = "<code>String.regex_quote (s)</code>" | |
| 2534 content = function() | |
| 2535 %> | |
| 2536 <p> | |
| 2537 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>. | |
| 2538 </p> | |
| 2539 <% | |
| 2540 end | |
| 2541 } | |
|
1718
5603ee8e2a71
rename String.rep to String.repeated
Franklin Schmidt <fschmidt@gmail.com>
parents:
1717
diff
changeset
|
2542 ["String.repeated"] = { |
|
5603ee8e2a71
rename String.rep to String.repeated
Franklin Schmidt <fschmidt@gmail.com>
parents:
1717
diff
changeset
|
2543 title = "<code>String.repeated (s, n [, sep])</code>" |
| 1668 | 2544 content = function() |
| 2545 %> | |
| 2546 <p> | |
| 2547 Returns a string that is the concatenation of <code>n</code> copies of | |
| 2548 the string <code>s</code> separated by the string <code>sep</code>. | |
| 2549 The default value for <code>sep</code> is the empty string | |
| 2550 (that is, no separator). | |
| 2551 Returns the empty string if <code>n</code> is not positive. | |
| 2552 </p> | |
| 2553 <% | |
| 2554 end | |
| 2555 } | |
| 1717 | 2556 ["String.replace"] = { |
| 2557 title = "<code>String.replace (s, target, replacement)</code>" | |
| 2558 content = function() | |
| 2559 %> | |
| 2560 <p> | |
| 2561 Returns a string where each substring <code>target</code> in <code>s</code> is replaced by <code>replacement</code>. | |
| 2562 </p> | |
| 2563 <% | |
| 2564 end | |
| 2565 } | |
| 1668 | 2566 ["String.reverse"] = { |
| 2567 title = "<code>String.reverse (s)</code>" | |
| 2568 content = function() | |
| 2569 %> | |
| 2570 <p> | |
| 2571 Returns a string that is the string <code>s</code> reversed. | |
| 2572 </p> | |
| 2573 <% | |
| 2574 end | |
| 2575 } | |
| 2576 ["String.split"] = { | |
|
1721
5c69d2e8bd75
no regex in String.find and String.split
Franklin Schmidt <fschmidt@gmail.com>
parents:
1719
diff
changeset
|
2577 title = "<code>String.split (s, s2 [, limit])</code>" |
| 1668 | 2578 content = function() |
| 2579 %> | |
| 2580 <p> | |
|
1721
5c69d2e8bd75
no regex in String.find and String.split
Franklin Schmidt <fschmidt@gmail.com>
parents:
1719
diff
changeset
|
2581 Splits <code>s</code> using substring <code>s2</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. |
| 1668 | 2582 </p> |
| 2583 <% | |
| 2584 end | |
| 2585 } | |
| 1716 | 2586 ["String.starts_with"] = { |
| 2587 title = "<code>String.starts_with (s, s2)</code>" | |
| 2588 content = function() | |
| 2589 %> | |
| 2590 <p> | |
| 2591 Returns a boolean indicating whether the <code>s</code> starts with <code>s2</code>. | |
| 2592 </p> | |
| 2593 <% | |
| 2594 end | |
| 2595 } | |
| 1668 | 2596 ["String.sub"] = { |
| 2597 title = "<code>String.sub (s, i [, j])</code>" | |
| 2598 content = function() | |
| 2599 %> | |
| 2600 <p> | |
| 2601 Returns the substring of <code>s</code> that | |
| 2602 starts at <code>i</code> and continues until <code>j</code>; | |
| 2603 <code>i</code> and <code>j</code> can be negative. | |
| 2604 If <code>j</code> is absent, then it is assumed to be equal to -1 | |
| 2605 (which is the same as the string length). | |
| 2606 In particular, | |
| 2607 the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> | |
| 2608 with length <code>j</code>, | |
| 2609 and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code> | |
| 2610 with length <code>i</code>. | |
| 2611 </p> | |
| 2612 | |
| 2613 <p> | |
| 2614 If, after the translation of negative indices, | |
| 2615 <code>i</code> is less than 1, | |
| 2616 it is corrected to 1. | |
| 2617 If <code>j</code> is greater than the string length, | |
| 2618 it is corrected to that length. | |
| 2619 If, after these corrections, | |
| 2620 <code>i</code> is greater than <code>j</code>, | |
| 2621 the function returns the empty string. | |
| 2622 </p> | |
| 2623 <% | |
| 2624 end | |
| 2625 } | |
| 2626 ["String.to_binary"] = { | |
| 2627 title = "<code>String.to_binary (s)</code>" | |
| 2628 content = function() | |
| 2629 %> | |
| 2630 <p> | |
| 2631 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>. | |
| 2632 </p> | |
| 2633 <% | |
| 2634 end | |
| 2635 } | |
| 2636 ["String.to_number"] = { | |
| 2637 title = "<code>String.to_number (s [, base])</code>" | |
| 2638 content = function() | |
| 2639 %> | |
| 2640 <p> | |
| 2641 When called with no <code>base</code>, | |
| 2642 <code>to_number</code> tries to convert its argument to a number. | |
| 2643 If the argument is | |
| 2644 a string convertible to a number, | |
| 2645 then <code>to_number</code> returns this number; | |
| 2646 otherwise, it returns <b>nil</b>. | |
| 2647 The conversion of strings can result in integers or floats. | |
| 2648 </p> | |
| 2649 | |
| 2650 <p> | |
| 2651 When called with <code>base</code>, | |
| 2652 then <code>s</code> must be a string to be interpreted as | |
| 2653 an integer numeral in that base. | |
| 2654 In bases above 10, the letter '<code>A</code>' (in either upper or lower case) | |
| 2655 represents 10, '<code>B</code>' represents 11, and so forth, | |
| 2656 with '<code>Z</code>' representing 35. | |
| 2657 If the string <code>s</code> is not a valid numeral in the given base, | |
| 2658 the function returns <b>nil</b>. | |
| 2659 </p> | |
| 2660 <% | |
| 2661 end | |
| 2662 } | |
| 2663 ["String.trim"] = { | |
| 2664 title = "<code>String.trim (s)</code>" | |
| 2665 content = function() | |
| 2666 %> | |
| 2667 <p> | |
| 2668 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>. | |
| 2669 </p> | |
| 2670 <% | |
| 2671 end | |
| 2672 } | |
| 2673 ["String.unicode"] = { | |
| 2674 title = "<code>String.unicode (s [, i [, j]])</code>" | |
| 2675 content = function() | |
| 2676 %> | |
| 2677 <p> | |
| 2678 Returns the internal numerical codes of the characters <code>s[i]</code>, | |
| 2679 <code>s[i+1]</code>, ..., <code>s[j]</code>. | |
| 2680 The default value for <code>i</code> is 1; | |
| 2681 the default value for <code>j</code> is <code>i</code>. | |
| 2682 These indices are corrected | |
| 2683 following the same rules of function <a href="#String.sub"><code>String.sub</code></a>. | |
| 2684 </p> | |
| 2685 <% | |
| 2686 end | |
| 2687 } | |
| 2688 ["String.upper"] = { | |
| 2689 title = "<code>String.upper (s)</code>" | |
| 2690 content = function() | |
| 2691 %> | |
| 2692 <p> | |
| 2693 Receives a string and returns a copy of this string with all | |
| 2694 lowercase letters changed to uppercase. | |
| 2695 All other characters are left unchanged. | |
| 2696 The definition of what a lowercase letter is depends on the current locale. | |
| 2697 </p> | |
| 2698 <% | |
| 2699 end | |
| 2700 } | |
| 2701 } | |
| 2702 } | |
| 1716 | 2703 regex_table = { |
| 2704 title = "Regular Expressions" | |
| 2705 content = function() | |
| 2706 %> | |
| 2707 <p> | |
| 2708 Regular expressions are handled using a regex table generated by <a href="#String.regex">String.regex</a>. | |
| 2709 </p> | |
| 2710 | |
| 2711 <p> | |
| 2712 Pattern matching is based on the Java <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a> class. | |
| 2713 </p> | |
| 2714 <% | |
| 2715 end | |
| 2716 subs = { | |
| 2717 ["regex.find"] = { | |
| 2718 title = "<code>regex.find (s [, init])</code>" | |
| 2719 content = function() | |
| 2720 %> | |
| 2721 <p> | |
| 2722 Looks for the first match of | |
| 2723 the regex in the string <code>s</code>. | |
| 2724 If it finds a match, then <code>find</code> returns the indices of <code>s</code> | |
| 2725 where this occurrence starts and ends; | |
| 2726 otherwise, it returns <b>nil</b>. | |
| 2727 A third, optional numerical argument <code>init</code> specifies | |
| 2728 where to start the search; | |
| 2729 its default value is 1 and can be negative. | |
| 2730 </p> | |
| 2731 | |
| 2732 <p> | |
| 2733 If the regex has captures, | |
| 2734 then in a successful match | |
| 2735 the captured values are also returned, | |
| 2736 after the two indices. | |
| 2737 </p> | |
| 2738 <% | |
| 2739 end | |
| 2740 } | |
| 2741 ["regex.gmatch"] = { | |
| 2742 title = "<code>regex.gmatch (s)</code>" | |
| 2743 content = function() | |
| 2744 %> | |
| 2745 <p> | |
| 2746 Returns an iterator function that, | |
| 2747 each time it is called, | |
| 2748 returns the next captures from the regex | |
| 2749 over the string <code>s</code>. | |
| 2750 If the regex specifies no captures, | |
| 2751 then the whole match is produced in each call. | |
| 2752 </p> | |
| 2753 | |
| 2754 <p> | |
| 2755 As an example, the following loop | |
| 2756 will iterate over all the words from string <code>s</code>, | |
| 2757 printing one per line: | |
| 2758 </p> | |
| 2759 <pre> | |
| 2760 local r = String.regex[[\w+]] | |
| 2761 local s = "hello world from Lua" | |
| 2762 for w in r.gmatch(s) do | |
| 2763 print(w) | |
| 2764 end | |
| 2765 </pre> | |
| 2766 | |
| 2767 <p> | |
| 2768 The next example collects all pairs <code>key=value</code> from the | |
| 2769 given string into a table: | |
| 2770 </p> | |
| 2771 <pre> | |
| 2772 local t = {} | |
| 2773 local r = String.regex[[(\w+)=(\w+)]] | |
| 2774 local s = "from=world, to=Lua" | |
| 2775 for k, v in r.gmatch(s) do | |
| 2776 t[k] = v | |
| 2777 end | |
| 2778 </pre> | |
| 2779 | |
| 2780 <p> | |
| 2781 For this function, a caret '<code>^</code>' at the start of a pattern does not | |
| 2782 work as an anchor, as this would prevent the iteration. | |
| 2783 </p> | |
| 2784 <% | |
| 2785 end | |
| 2786 } | |
| 2787 ["regex.gsub"] = { | |
| 2788 title = "<code>regex.gsub (s, repl [, n])</code>" | |
| 2789 content = function() | |
| 2790 %> | |
| 2791 <p> | |
| 2792 Returns a copy of <code>s</code> | |
| 2793 in which all (or the first <code>n</code>, if given) | |
| 2794 occurrences of the regex have been | |
| 2795 replaced by a replacement string specified by <code>repl</code>, | |
| 2796 which can be a string, a table, or a function. | |
| 2797 <code>gsub</code> also returns, as its second value, | |
| 2798 the total number of matches that occurred. | |
| 2799 The name <code>gsub</code> comes from <em>Global SUBstitution</em>. | |
| 2800 </p> | |
| 2801 | |
| 2802 <p> | |
| 2803 If <code>repl</code> is a string, then its value is used for replacement. | |
| 2804 The character <code>\</code> works as an escape character. | |
| 2805 Any sequence in <code>repl</code> of the form <code>$<em>d</em></code>, | |
| 2806 with <em>d</em> between 1 and 9, | |
| 2807 stands for the value of the <em>d</em>-th captured substring. | |
| 2808 The sequence <code>$0</code> stands for the whole match. | |
| 2809 </p> | |
| 2810 | |
| 2811 <p> | |
| 2812 If <code>repl</code> is a table, then the table is queried for every match, | |
| 2813 using the first capture as the key. | |
| 2814 </p> | |
| 2815 | |
| 2816 <p> | |
| 2817 If <code>repl</code> is a function, then this function is called every time a | |
| 2818 match occurs, with all captured substrings passed as arguments, | |
| 2819 in order. | |
| 2820 </p> | |
| 2821 | |
| 2822 <p> | |
| 2823 In any case, | |
| 2824 if the regex specifies no captures, | |
| 2825 then it behaves as if the whole regex was inside a capture. | |
| 2826 </p> | |
| 2827 | |
| 2828 <p> | |
| 2829 If the value returned by the table query or by the function call | |
| 2830 is not <b>nil</b>, | |
| 2831 then it is used as the replacement string; | |
| 2832 otherwise, if it is <b>nil</b>, | |
| 2833 then there is no replacement | |
| 2834 (that is, the original match is kept in the string). | |
| 2835 </p> | |
| 2836 | |
| 2837 <p> | |
| 2838 Here are some examples: | |
| 2839 </p> | |
| 2840 <pre> | |
| 2841 local r = String.regex[[(\w+)]] | |
| 2842 local x = r.gsub("hello world", "$1 $1") | |
| 2843 --> x="hello hello world world" | |
| 2844 | |
| 2845 local r = String.regex[[(\w+)]] | |
| 2846 local x = r.gsub("hello world", "$0 $0", 1) | |
| 2847 --> x="hello hello world" | |
| 2848 | |
| 2849 local r = String.regex[[(\w+)\s*(\w+)]] | |
| 2850 local x = r.gsub("hello world from Luan", "$2 $1") | |
| 2851 --> x="world hello Luan from" | |
| 2852 | |
| 2853 local r = String.regex[[\$(.*?)\$]] | |
| 2854 local x = r.gsub("4+5 = $return 4+5$", function(s) | |
| 2855 return load(s)() | |
| 2856 end) | |
| 2857 --> x="4+5 = 9" | |
| 2858 | |
| 2859 local r = String.regex[[\$(\w+)]] | |
| 2860 local t = {name="lua", version="5.3"} | |
| 2861 local x = r.gsub("$name-$version.tar.gz", t) | |
| 2862 --> x="lua-5.3.tar.gz" | |
| 2863 </pre> | |
| 2864 <% | |
| 2865 end | |
| 2866 } | |
| 2867 ["regex.match"] = { | |
| 2868 title = "<code>regex.match (s [, init])</code>" | |
| 2869 content = function() | |
| 2870 %> | |
| 2871 <p> | |
| 2872 Looks for the first <em>match</em> of | |
| 2873 the regex in the string <code>s</code>. | |
| 2874 If it finds one, then <code>match</code> returns | |
| 2875 the captures from the regex; | |
| 2876 otherwise it returns <b>nil</b>. | |
| 2877 If the regex specifies no captures, | |
| 2878 then the whole match is returned. | |
| 2879 A third, optional numerical argument <code>init</code> specifies | |
| 2880 where to start the search; | |
| 2881 its default value is 1 and can be negative. | |
| 2882 </p> | |
| 2883 <% | |
| 2884 end | |
| 2885 } | |
| 2886 ["regex.matches"] = { | |
| 2887 title = "<code>regex.matches (s)</code>" | |
| 2888 content = function() | |
| 2889 %> | |
| 2890 <p> | |
| 2891 Returns a boolean indicating whether the regex can be found in string <code>s</code>. | |
| 2892 This function is equivalent to | |
| 2893 </p> | |
| 2894 <pre> | |
| 2895 return regex.match(s) ~= nil | |
| 2896 </pre> | |
| 2897 <% | |
| 2898 end | |
| 2899 } | |
| 1719 | 2900 ["regex.set"] = { |
| 2901 title = "<code>regex.set (pattern)</code>" | |
| 2902 content = function() | |
| 2903 %> | |
| 2904 <p> | |
| 2905 Changes the regex pattern to <code>pattern</code>. | |
| 2906 </p> | |
| 2907 <% | |
| 2908 end | |
| 2909 } | |
| 2910 ["regex.split"] = { | |
| 2911 title = "<code>regex.split (s [, limit])</code>" | |
| 2912 content = function() | |
| 2913 %> | |
| 2914 <p> | |
| 2915 Splits <code>s</code> using the regex 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. | |
| 2916 </p> | |
| 2917 <% | |
| 2918 end | |
| 2919 } | |
| 1716 | 2920 } |
| 2921 } | |
| 1668 | 2922 binary_lib = { |
| 2923 title = "Binary Manipulation" | |
| 2924 content = function() | |
| 2925 %> | |
| 2926 <p> | |
| 2927 Include this library by: | |
| 2928 </p> | |
| 2929 <pre> | |
| 2930 local Binary = require "luan:Binary.luan" | |
| 2931 </pre> | |
| 2932 <% | |
| 2933 end | |
| 2934 subs = { | |
| 2935 ["Binary.binary"] = { | |
| 2936 title = "<code>Binary.binary (···)</code>" | |
| 2937 content = function() | |
| 2938 %> | |
| 2939 <p> | |
| 2940 Receives zero or more bytes (as integers). | |
| 2941 Returns a binary with length equal to the number of arguments, | |
| 2942 in which each byte has the internal numerical code equal | |
| 2943 to its corresponding argument. | |
| 2944 </p> | |
| 2945 <% | |
| 2946 end | |
| 2947 } | |
| 2948 ["Binary.byte"] = { | |
| 2949 title = "<code>Binary.byte (b [, i [, j]])</code>" | |
| 2950 content = function() | |
| 2951 %> | |
| 2952 <p> | |
| 2953 Returns the internal numerical codes of the bytes <code>b[i]</code>, | |
| 2954 <code>b[i+1]</code>, ..., <code>b[j]</code>. | |
| 2955 The default value for <code>i</code> is 1; | |
| 2956 the default value for <code>j</code> is <code>i</code>. | |
| 2957 These indices are corrected | |
| 2958 following the same rules of function <a href="#String.sub"><code>String.sub</code></a>. | |
| 2959 </p> | |
| 2960 <% | |
| 2961 end | |
| 2962 } | |
| 2963 ["Binary.to_string"] = { | |
| 2964 title = "<code>Binary.to_string (b [,charset])</code>" | |
| 2965 content = function() | |
| 2966 %> | |
| 2967 <p> | |
| 2968 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. | |
| 2969 </p> | |
| 2970 <% | |
| 2971 end | |
| 2972 } | |
| 2973 } | |
| 2974 } | |
| 2975 table_lib = { | |
| 2976 title = "Table Manipulation" | |
| 2977 content = function() | |
| 2978 %> | |
| 2979 <p> | |
| 2980 Include this library by: | |
| 2981 </p> | |
| 2982 <pre> | |
| 2983 local Table = require "luan:Table.luan" | |
| 2984 </pre> | |
| 2985 | |
| 2986 <p> | |
| 2987 This library provides generic functions for table manipulation. | |
| 2988 It provides all its functions inside the table <code>Table</code>. | |
| 2989 </p> | |
| 2990 <% | |
| 2991 end | |
| 2992 subs = { | |
| 2993 ["Table.clear"] = { | |
| 2994 title = "<code>Table.clear (tbl)</code>" | |
| 2995 content = function() | |
| 2996 %> | |
| 2997 <p> | |
| 2998 Clears the table. | |
| 2999 </p> | |
| 3000 <% | |
| 3001 end | |
| 3002 } | |
| 3003 ["Table.concat"] = { | |
| 3004 title = "<code>Table.concat (list [, sep [, i [, j]]])</code>" | |
| 3005 content = function() | |
| 3006 %> | |
| 3007 <p> | |
| 3008 Given a list, | |
| 3009 returns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>. | |
| 3010 The default value for <code>sep</code> is the empty string, | |
| 3011 the default for <code>i</code> is 1, | |
| 3012 and the default for <code>j</code> is <code>#list</code>. | |
| 3013 If <code>i</code> is greater than <code>j</code>, returns the empty string. | |
| 3014 </p> | |
| 3015 <% | |
| 3016 end | |
| 3017 } | |
| 3018 ["Table.copy"] = { | |
| 3019 title = "<code>Table.copy (tbl [, i [, j]])</code>" | |
| 3020 content = function() | |
| 3021 %> | |
| 3022 <p> | |
| 3023 If <code>i</code> is <code>nil</code>, returns a shallow copy of <code>tbl</code>. | |
| 3024 Otherwise returns a new table which is a list of the elements <code>tbl[i] ··· tbl[j]</code>. | |
| 3025 By default, <code>j</code> is <code>#tbl</code>. | |
| 3026 </p> | |
| 3027 <% | |
| 3028 end | |
| 3029 } | |
| 3030 ["Table.insert"] = { | |
| 3031 title = "<code>Table.insert (list, pos, value)</code>" | |
| 3032 content = function() | |
| 3033 %> | |
| 3034 <p> | |
| 3035 Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>, | |
| 3036 shifting up the elements | |
| 3037 <code>list[pos], list[pos+1], ···, list[#list]</code>. | |
| 3038 </p> | |
| 3039 <% | |
| 3040 end | |
| 3041 } | |
| 3042 ["Table.is_empty"] = { | |
| 3043 title = "<code>Table.is_empty (tbl)</code>" | |
| 3044 content = function() | |
| 3045 %> | |
| 3046 <% | |
| 3047 end | |
| 3048 } | |
| 1704 | 3049 ["Table.is_list"] = { |
| 3050 title = "<code>Table.is_list (tbl)</code>" | |
| 3051 content = function() | |
| 3052 %> | |
| 3053 <% | |
| 3054 end | |
| 3055 } | |
| 1668 | 3056 ["Table.pack"] = { |
| 3057 title = "<code>Table.pack (···)</code>" | |
| 3058 content = function() | |
| 3059 %> | |
| 3060 <p> | |
| 3061 Returns a new table with all parameters stored into keys 1, 2, etc. | |
| 3062 and with a field "<code>n</code>" with the total number of parameters. | |
| 3063 Note that the resulting table may not be a sequence. | |
| 3064 </p> | |
| 3065 <% | |
| 3066 end | |
| 3067 } | |
| 3068 ["Table.remove"] = { | |
| 3069 title = "<code>Table.remove (list, pos)</code>" | |
| 3070 content = function() | |
| 3071 %> | |
| 3072 <p> | |
| 3073 Removes from <code>list</code> the element at position <code>pos</code>, | |
| 3074 returning the value of the removed element. | |
| 3075 When <code>pos</code> is an integer between 1 and <code>#list</code>, | |
| 3076 it shifts down the elements | |
| 3077 <code>list[pos+1], list[pos+2], ···, list[#list]</code> | |
| 3078 and erases element <code>list[#list]</code>; | |
| 3079 The index <code>pos</code> can also be 0 when <code>#list</code> is 0, | |
| 3080 or <code>#list + 1</code>; | |
| 3081 in those cases, the function erases the element <code>list[pos]</code>. | |
| 3082 </p> | |
| 3083 <% | |
| 3084 end | |
| 3085 } | |
| 3086 ["Table.size"] = { | |
| 3087 title = "<code>Table.size (tbl)</code>" | |
| 3088 content = function() | |
| 3089 %> | |
| 3090 <% | |
| 3091 end | |
| 3092 } | |
| 3093 ["Table.sort"] = { | |
| 3094 title = "<code>Table.sort (list [, comp])</code>" | |
| 3095 content = function() | |
| 3096 %> | |
| 3097 <p> | |
| 3098 Sorts list elements in a given order, <em>in-place</em>, | |
| 3099 from <code>list[1]</code> to <code>list[#list]</code>. | |
| 3100 If <code>comp</code> is given, | |
| 3101 then it must be a function that receives two list elements | |
| 3102 and returns true when the first element must come | |
| 3103 before the second in the final order | |
| 3104 (so that <code>not comp(list[i+1],list[i])</code> will be true after the sort). | |
| 3105 If <code>comp</code> is not given, | |
| 3106 then the standard Lua operator <code><</code> is used instead. | |
| 3107 </p> | |
| 3108 | |
| 3109 <p> | |
| 3110 The sort algorithm is not stable; | |
| 3111 that is, elements considered equal by the given order | |
| 3112 may have their relative positions changed by the sort. | |
| 3113 </p> | |
| 3114 <% | |
| 3115 end | |
| 3116 } | |
| 3117 ["Table.unpack"] = { | |
| 3118 title = "<code>Table.unpack (list [, i [, j]])</code>" | |
| 3119 content = function() | |
| 3120 %> | |
| 3121 <p> | |
| 3122 Returns the elements from the given list. | |
| 3123 This function is equivalent to | |
| 3124 </p> | |
| 3125 <pre> | |
| 3126 return list[i], list[i+1], ···, list[j] | |
| 3127 </pre> | |
| 3128 | |
| 3129 <p> | |
| 3130 By default, <code>i</code> is 1 and <code>j</code> is <code>list.n or #list</code>. | |
| 3131 </p> | |
| 3132 <% | |
| 3133 end | |
| 3134 } | |
| 3135 } | |
| 3136 } | |
| 3137 number_lib = { | |
| 3138 title = "Number Manipulation" | |
| 3139 content = function() | |
| 3140 %> | |
| 3141 <p> | |
| 3142 Include this library by: | |
| 3143 </p> | |
| 3144 <pre> | |
| 3145 local Number = require "luan:Number.luan" | |
| 3146 </pre> | |
| 3147 <% | |
| 3148 end | |
| 3149 subs = { | |
| 3150 ["Number.double"] = { | |
| 3151 title = "<code>Number.double (x)</code>" | |
| 3152 content = function() | |
| 3153 %> | |
| 3154 <p> | |
| 3155 Returns <code>x</code> as a double. | |
| 3156 </p> | |
| 3157 <% | |
| 3158 end | |
| 3159 } | |
| 3160 ["Number.float"] = { | |
| 3161 title = "<code>Number.float (x)</code>" | |
| 3162 content = function() | |
| 3163 %> | |
| 3164 <p> | |
| 3165 Returns <code>x</code> as a float. | |
| 3166 </p> | |
| 3167 <% | |
| 3168 end | |
| 3169 } | |
| 3170 ["Number.integer"] = { | |
| 3171 title = "<code>Number.integer (x)</code>" | |
| 3172 content = function() | |
| 3173 %> | |
| 3174 <p> | |
| 3175 If the value <code>x</code> is convertible to an integer, | |
| 3176 returns that integer. | |
| 3177 Otherwise throws an error. | |
| 3178 </p> | |
| 3179 <% | |
| 3180 end | |
| 3181 } | |
| 3182 ["Number.long"] = { | |
| 3183 title = "<code>Number.long (x)</code>" | |
| 3184 content = function() | |
| 3185 %> | |
| 3186 <p> | |
| 3187 If the value <code>x</code> is convertible to an long, | |
| 3188 returns that long. | |
| 3189 Otherwise throws an error. | |
| 3190 </p> | |
| 3191 <% | |
| 3192 end | |
| 3193 } | |
| 3194 ["Number.long_to_string"] = { | |
| 3195 title = "<code>Number.long_to_string (i, radix)</code>" | |
| 3196 content = function() | |
| 3197 %> | |
| 3198 <p> | |
| 3199 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>. | |
| 3200 </p> | |
| 3201 <% | |
| 3202 end | |
| 3203 } | |
| 3204 ["Number.type"] = { | |
| 3205 title = "<code>Number.type (x)</code>" | |
| 3206 content = function() | |
| 3207 %> | |
| 3208 <p> | |
| 3209 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>". | |
| 3210 </p> | |
| 3211 <% | |
| 3212 end | |
| 3213 } | |
| 3214 } | |
| 3215 } | |
| 1669 | 3216 math_lib = { |
| 3217 title = "Mathematical Functions" | |
| 3218 content = function() | |
| 3219 %> | |
| 3220 <p> | |
| 3221 Include this library by: | |
| 3222 </p> | |
| 3223 <pre> | |
| 3224 local Math = require "luan:Math.luan" | |
| 3225 </pre> | |
| 3226 | |
| 3227 <p> | |
| 3228 This library provides basic mathematical functions. | |
| 3229 It provides all its functions and constants inside the table <code>Math</code>. | |
| 3230 </p> | |
| 3231 <% | |
| 3232 end | |
| 3233 subs = { | |
| 3234 ["Math.abs"] = { | |
| 3235 title = "<code>Math.abs (x)</code>" | |
| 3236 content = function() | |
| 3237 %> | |
| 3238 <p> | |
| 3239 Returns the absolute value of <code>x</code>. | |
| 3240 </p> | |
| 3241 <% | |
| 3242 end | |
| 3243 } | |
| 3244 ["Math.acos"] = { | |
| 3245 title = "<code>Math.acos (x)</code>" | |
| 3246 content = function() | |
| 3247 %> | |
| 3248 <p> | |
| 3249 Returns the arc cosine of <code>x</code> (in radians). | |
| 3250 </p> | |
| 3251 <% | |
| 3252 end | |
| 3253 } | |
| 3254 ["Math.asin"] = { | |
| 3255 title = "<code>Math.asin (x)</code>" | |
| 3256 content = function() | |
| 3257 %> | |
| 3258 <p> | |
| 3259 Returns the arc sine of <code>x</code> (in radians). | |
| 3260 </p> | |
| 3261 <% | |
| 3262 end | |
| 3263 } | |
| 3264 ["Math.atan"] = { | |
| 3265 title = "<code>Math.atan (y, x)</code>" | |
| 3266 content = function() | |
| 3267 %> | |
| 3268 <p> | |
| 3269 Returns the arc tangent of <code>y/x</code> (in radians), | |
| 3270 but uses the signs of both parameters to find the | |
| 3271 quadrant of the result. | |
| 3272 (It also handles correctly the case of <code>x</code> being zero.) | |
| 3273 </p> | |
| 3274 <% | |
| 3275 end | |
| 3276 } | |
| 3277 ["Math.ceil"] = { | |
| 3278 title = "<code>Math.ceil (x)</code>" | |
| 3279 content = function() | |
| 3280 %> | |
| 3281 <p> | |
| 3282 Returns the smallest integral value larger than or equal to <code>x</code>. | |
| 3283 </p> | |
| 3284 <% | |
| 3285 end | |
| 3286 } | |
| 3287 ["Math.cos"] = { | |
| 3288 title = "<code>Math.cos (x)</code>" | |
| 3289 content = function() | |
| 3290 %> | |
| 3291 <p> | |
| 3292 Returns the cosine of <code>x</code> (assumed to be in radians). | |
| 3293 </p> | |
| 3294 <% | |
| 3295 end | |
| 3296 } | |
| 3297 ["Math.deg"] = { | |
| 3298 title = "<code>Math.deg (x)</code>" | |
| 3299 content = function() | |
| 3300 %> | |
| 3301 <p> | |
| 3302 Converts the angle <code>x</code> from radians to degrees. | |
| 3303 </p> | |
| 3304 <% | |
| 3305 end | |
| 3306 } | |
| 3307 ["Math.exp"] = { | |
| 3308 title = "<code>Math.exp (x)</code>" | |
| 3309 content = function() | |
| 3310 %> | |
| 3311 <p> | |
| 3312 Returns the value <em>e<sup>x</sup></em> | |
| 3313 (where <code>e</code> is the base of natural logarithms). | |
| 3314 </p> | |
| 3315 <% | |
| 3316 end | |
| 3317 } | |
| 3318 ["Math.floor"] = { | |
| 3319 title = "<code>Math.floor (x)</code>" | |
| 3320 content = function() | |
| 3321 %> | |
| 3322 <p> | |
| 3323 Returns the largest integral value smaller than or equal to <code>x</code>. | |
| 3324 </p> | |
| 3325 <% | |
| 3326 end | |
| 3327 } | |
| 3328 ["Math.fmod"] = { | |
| 3329 title = "<code>Math.fmod (x, y)</code>" | |
| 3330 content = function() | |
| 3331 %> | |
| 3332 <p> | |
| 3333 Returns the remainder of the division of <code>x</code> by <code>y</code> | |
| 3334 that rounds the quotient towards zero. | |
| 3335 </p> | |
| 3336 <% | |
| 3337 end | |
| 3338 } | |
| 3339 ["Math.huge"] = { | |
| 3340 title = "<code>Math.huge</code>" | |
| 3341 content = function() | |
| 3342 %> | |
| 3343 <p> | |
| 3344 A value larger than any other numerical value. | |
| 3345 </p> | |
| 3346 <% | |
| 3347 end | |
| 3348 } | |
| 3349 ["Math.log"] = { | |
| 3350 title = "<code>Math.log (x [, base])</code>" | |
| 3351 content = function() | |
| 3352 %> | |
| 3353 <p> | |
| 3354 Returns the logarithm of <code>x</code> in the given base. | |
| 3355 The default for <code>base</code> is <em>e</em> | |
| 3356 (so that the function returns the natural logarithm of <code>x</code>). | |
| 3357 </p> | |
| 3358 <% | |
| 3359 end | |
| 3360 } | |
| 3361 ["Math.max"] = { | |
| 3362 title = "<code>Math.max (x, ···)</code>" | |
| 3363 content = function() | |
| 3364 %> | |
| 3365 <p> | |
| 3366 Returns the argument with the maximum value, | |
| 3367 according to the Lua operator <code><</code>. | |
| 3368 </p> | |
| 3369 <% | |
| 3370 end | |
| 3371 } | |
| 3372 ["Math.max_integer"] = { | |
| 3373 title = "<code>Math.max_integer</code>" | |
| 3374 content = function() | |
| 3375 %> | |
| 3376 <p> | |
| 3377 An integer with the maximum value for an integer. | |
| 3378 </p> | |
| 3379 <% | |
| 3380 end | |
| 3381 } | |
| 3382 ["Math.min"] = { | |
| 3383 title = "<code>Math.min (x, ···)</code>" | |
| 3384 content = function() | |
| 3385 %> | |
| 3386 <p> | |
| 3387 Returns the argument with the minimum value, | |
| 3388 according to the Lua operator <code><</code>. | |
| 3389 </p> | |
| 3390 <% | |
| 3391 end | |
| 3392 } | |
| 3393 ["Math.min_integer"] = { | |
| 3394 title = "<code>Math.min_integer</code>" | |
| 3395 content = function() | |
| 3396 %> | |
| 3397 <p> | |
| 3398 An integer with the minimum value for an integer. | |
| 3399 </p> | |
| 3400 <% | |
| 3401 end | |
| 3402 } | |
| 3403 ["Math.modf"] = { | |
| 3404 title = "<code>Math.modf (x)</code>" | |
| 3405 content = function() | |
| 3406 %> | |
| 3407 <p> | |
| 3408 Returns the integral part of <code>x</code> and the fractional part of <code>x</code>. | |
| 3409 </p> | |
| 3410 <% | |
| 3411 end | |
| 3412 } | |
| 3413 ["Math.pi"] = { | |
| 3414 title = "<code>Math.pi</code>" | |
| 3415 content = function() | |
| 3416 %> | |
| 3417 <p> | |
| 3418 The value of <em>π</em>. | |
| 3419 </p> | |
| 3420 <% | |
| 3421 end | |
| 3422 } | |
| 3423 ["Math.rad"] = { | |
| 3424 title = "<code>Math.rad (x)</code>" | |
| 3425 content = function() | |
| 3426 %> | |
| 3427 <p> | |
| 3428 Converts the angle <code>x</code> from degrees to radians. | |
| 3429 </p> | |
| 3430 <% | |
| 3431 end | |
| 3432 } | |
| 3433 ["Math.random"] = { | |
| 3434 title = "<code>Math.random ([m [, n])</code>" | |
| 3435 content = function() | |
| 3436 %> | |
| 3437 <p> | |
| 3438 When called without arguments, | |
| 3439 returns a pseudo-random float with uniform distribution | |
| 3440 in the range <em>[0,1)</em>. | |
| 3441 When called with two integers <code>m</code> and <code>n</code>, | |
| 3442 <code>Math.random</code> returns a pseudo-random integer | |
| 3443 with uniform distribution in the range <em>[m, n]</em>. | |
| 3444 (The value <em>m-n</em> cannot be negative and must fit in a Luan integer.) | |
| 3445 The call <code>Math.random(n)</code> is equivalent to <code>Math.random(1,n)</code>. | |
| 3446 </p> | |
| 3447 | |
| 3448 <p> | |
| 3449 This function is an interface to the underling | |
| 3450 pseudo-random generator function provided by Java. | |
| 3451 No guarantees can be given for its statistical properties. | |
| 3452 </p> | |
| 3453 <% | |
| 3454 end | |
| 3455 } | |
| 3456 ["Math.sin"] = { | |
| 3457 title = "<code>Math.sin (x)</code>" | |
| 3458 content = function() | |
| 3459 %> | |
| 3460 <p> | |
| 3461 Returns the sine of <code>x</code> (assumed to be in radians). | |
| 3462 </p> | |
| 3463 <% | |
| 3464 end | |
| 3465 } | |
| 3466 ["Math.sqrt"] = { | |
| 3467 title = "<code>Math.sqrt (x)</code>" | |
| 3468 content = function() | |
| 3469 %> | |
| 3470 <p> | |
| 3471 Returns the square root of <code>x</code>. | |
| 3472 (You can also use the expression <code>x^0.5</code> to compute this value.) | |
| 3473 </p> | |
| 3474 <% | |
| 3475 end | |
| 3476 } | |
| 3477 ["Math.tan"] = { | |
| 3478 title = "<code>Math.tan (x)</code>" | |
| 3479 content = function() | |
| 3480 %> | |
| 3481 <p> | |
| 3482 Returns the tangent of <code>x</code> (assumed to be in radians). | |
| 3483 </p> | |
| 3484 <% | |
| 3485 end | |
| 3486 } | |
| 3487 } | |
| 3488 } | |
| 1656 | 3489 } |
| 3490 } | |
| 3491 } | |
| 3492 | |
| 3493 | |
| 3494 return function() | |
| 3495 Io.stdout = Http.response.text_writer() | |
| 3496 %> | |
| 3497 <!doctype html> | |
| 3498 <html> | |
| 3499 <head> | |
| 3500 <% head() %> | |
| 3501 <title>Luan Reference Manual</title> | |
| 3502 <style> | |
| 3503 p[keywords] { | |
| 3504 font-family: monospace; | |
| 3505 margin-left: 40px; | |
| 3506 max-width: 700px; | |
| 3507 } | |
| 3508 p[keywords] span { | |
| 3509 display: inline-block; | |
| 3510 width: 100px; | |
| 3511 } | |
| 1716 | 3512 code { |
| 3513 font-size: 16px; | |
| 3514 font-weight: bold; | |
| 3515 } | |
| 3516 div[toc] code { | |
| 3517 font-size: inherit; | |
| 3518 font-weight: inherit; | |
| 3519 } | |
| 1656 | 3520 </style> |
| 3521 </head> | |
| 3522 <body> | |
| 3523 <% docs_header() %> | |
| 3524 <div content> | |
| 3525 <h1><a href="manual.html">Luan Reference Manual</a></h1> | |
| 3526 <p small> | |
| 3527 Original copyright © 2015 Lua.org, PUC-Rio. | |
| 3528 Freely available under the terms of the | |
| 3529 <a href="http://www.lua.org/license.html">Lua license</a>. | |
| 3530 Modified for Luan. | |
| 3531 </p> | |
| 3532 <hr> | |
| 3533 <h2>Contents</h2> | |
| 3534 <div toc> | |
| 3535 <% show_toc(content) %> | |
| 3536 </div> | |
| 3537 <hr> | |
| 3538 <% show_content(content,2) %> | |
| 3539 </div> | |
| 3540 </body> | |
| 3541 </html> | |
| 3542 <% | |
| 3543 end |