manual.html revision 1.3
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2 <html> 3 4 <head> 5 <title>Lua 5.3 Reference Manual</title> 6 <link rel="stylesheet" type="text/css" href="lua.css"> 7 <link rel="stylesheet" type="text/css" href="manual.css"> 8 <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> 9 </head> 10 11 <body> 12 13 <hr> 14 <h1> 15 <a href="http://www.lua.org/"><img src="logo.gif" alt="" border="0"></a> 16 Lua 5.3 Reference Manual 17 </h1> 18 19 by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes 20 <p> 21 <small> 22 Copyright © 2015 Lua.org, PUC-Rio. 23 Freely available under the terms of the 24 <a href="http://www.lua.org/license.html">Lua license</a>. 25 </small> 26 <hr> 27 <p> 28 29 <a href="contents.html#contents">contents</A> 30 · 31 <a href="contents.html#index">index</A> 32 33 <!-- ====================================================================== --> 34 <p> 35 36 <!-- Id: manual.of,v 1.146 2015/01/06 11:23:01 roberto Exp --> 37 38 39 40 41 <h1>1 – <a name="1">Introduction</a></h1> 42 43 <p> 44 Lua is an extension programming language designed to support 45 general procedural programming with data description 46 facilities. 47 Lua also offers good support for object-oriented programming, 48 functional programming, and data-driven programming. 49 Lua is intended to be used as a powerful, lightweight, 50 embeddable scripting language for any program that needs one. 51 Lua is implemented as a library, written in <em>clean C</em>, 52 the common subset of Standard C and C++. 53 54 55 <p> 56 As an extension language, Lua has no notion of a "main" program: 57 it only works <em>embedded</em> in a host client, 58 called the <em>embedding program</em> or simply the <em>host</em>. 59 The host program can invoke functions to execute a piece of Lua code, 60 can write and read Lua variables, 61 and can register C functions to be called by Lua code. 62 Through the use of C functions, Lua can be augmented to cope with 63 a wide range of different domains, 64 thus creating customized programming languages sharing a syntactical framework. 65 The Lua distribution includes a sample host program called <code>lua</code>, 66 which uses the Lua library to offer a complete, standalone Lua interpreter, 67 for interactive or batch use. 68 69 70 <p> 71 Lua is free software, 72 and is provided as usual with no guarantees, 73 as stated in its license. 74 The implementation described in this manual is available 75 at Lua's official web site, <code>www.lua.org</code>. 76 77 78 <p> 79 Like any other reference manual, 80 this document is dry in places. 81 For a discussion of the decisions behind the design of Lua, 82 see the technical papers available at Lua's web site. 83 For a detailed introduction to programming in Lua, 84 see Roberto's book, <em>Programming in Lua</em>. 85 86 87 88 <h1>2 – <a name="2">Basic Concepts</a></h1> 89 90 <p> 91 This section describes the basic concepts of the language. 92 93 94 95 <h2>2.1 – <a name="2.1">Values and Types</a></h2> 96 97 <p> 98 Lua is a <em>dynamically typed language</em>. 99 This means that 100 variables do not have types; only values do. 101 There are no type definitions in the language. 102 All values carry their own type. 103 104 105 <p> 106 All values in Lua are <em>first-class values</em>. 107 This means that all values can be stored in variables, 108 passed as arguments to other functions, and returned as results. 109 110 111 <p> 112 There are eight basic types in Lua: 113 <em>nil</em>, <em>boolean</em>, <em>number</em>, 114 <em>string</em>, <em>function</em>, <em>userdata</em>, 115 <em>thread</em>, and <em>table</em>. 116 <em>Nil</em> is the type of the value <b>nil</b>, 117 whose main property is to be different from any other value; 118 it usually represents the absence of a useful value. 119 <em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>. 120 Both <b>nil</b> and <b>false</b> make a condition false; 121 any other value makes it true. 122 <em>Number</em> represents both 123 integer numbers and real (floating-point) numbers. 124 <em>String</em> represents immutable sequences of bytes. 125 126 Lua is 8-bit clean: 127 strings can contain any 8-bit value, 128 including embedded zeros ('<code>\0</code>'). 129 Lua is also encoding-agnostic; 130 it makes no assumptions about the contents of a string. 131 132 133 <p> 134 The type <em>number</em> uses two internal representations, 135 one called <em>integer</em> and the other called <em>float</em>. 136 Lua has explicit rules about when each representation is used, 137 but it also converts between them automatically as needed (see <a href="#3.4.3">§3.4.3</a>). 138 Therefore, 139 the programmer may choose to mostly ignore the difference 140 between integers and floats 141 or to assume complete control over the representation of each number. 142 Standard Lua uses 64-bit integers and double-precision (64-bit) floats, 143 but you can also compile Lua so that it 144 uses 32-bit integers and/or single-precision (32-bit) floats. 145 The option with 32 bits for both integers and floats 146 is particularly attractive 147 for small machines and embedded systems. 148 (See macro <code>LUA_32BITS</code> in file <code>luaconf.h</code>.) 149 150 151 <p> 152 Lua can call (and manipulate) functions written in Lua and 153 functions written in C (see <a href="#3.4.10">§3.4.10</a>). 154 Both are represented by the type <em>function</em>. 155 156 157 <p> 158 The type <em>userdata</em> is provided to allow arbitrary C data to 159 be stored in Lua variables. 160 A userdata value represents a block of raw memory. 161 There are two kinds of userdata: 162 <em>full userdata</em>, 163 which is an object with a block of memory managed by Lua, 164 and <em>light userdata</em>, 165 which is simply a C pointer value. 166 Userdata has no predefined operations in Lua, 167 except assignment and identity test. 168 By using <em>metatables</em>, 169 the programmer can define operations for full userdata values 170 (see <a href="#2.4">§2.4</a>). 171 Userdata values cannot be created or modified in Lua, 172 only through the C API. 173 This guarantees the integrity of data owned by the host program. 174 175 176 <p> 177 The type <em>thread</em> represents independent threads of execution 178 and it is used to implement coroutines (see <a href="#2.6">§2.6</a>). 179 Lua threads are not related to operating-system threads. 180 Lua supports coroutines on all systems, 181 even those that do not support threads natively. 182 183 184 <p> 185 The type <em>table</em> implements associative arrays, 186 that is, arrays that can be indexed not only with numbers, 187 but with any Lua value except <b>nil</b> and NaN. 188 (<em>Not a Number</em> is a special numeric value used to represent 189 undefined or unrepresentable results, such as <code>0/0</code>.) 190 Tables can be <em>heterogeneous</em>; 191 that is, they can contain values of all types (except <b>nil</b>). 192 Any key with value <b>nil</b> is not considered part of the table. 193 Conversely, any key that is not part of a table has 194 an associated value <b>nil</b>. 195 196 197 <p> 198 Tables are the sole data-structuring mechanism in Lua; 199 they can be used to represent ordinary arrays, sequences, 200 symbol tables, sets, records, graphs, trees, etc. 201 To represent records, Lua uses the field name as an index. 202 The language supports this representation by 203 providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. 204 There are several convenient ways to create tables in Lua 205 (see <a href="#3.4.9">§3.4.9</a>). 206 207 208 <p> 209 We use the term <em>sequence</em> to denote a table where 210 the set of all positive numeric keys is equal to {1..<em>n</em>} 211 for some non-negative integer <em>n</em>, 212 which is called the length of the sequence (see <a href="#3.4.7">§3.4.7</a>). 213 214 215 <p> 216 Like indices, 217 the values of table fields can be of any type. 218 In particular, 219 because functions are first-class values, 220 table fields can contain functions. 221 Thus tables can also carry <em>methods</em> (see <a href="#3.4.11">§3.4.11</a>). 222 223 224 <p> 225 The indexing of tables follows 226 the definition of raw equality in the language. 227 The expressions <code>a[i]</code> and <code>a[j]</code> 228 denote the same table element 229 if and only if <code>i</code> and <code>j</code> are raw equal 230 (that is, equal without metamethods). 231 In particular, floats with integral values 232 are equal to their respective integers 233 (e.g., <code>1.0 == 1</code>). 234 To avoid ambiguities, 235 any float with integral value used as a key 236 is converted to its respective integer. 237 For instance, if you write <code>a[2.0] = true</code>, 238 the actual key inserted into the table will be the 239 integer <code>2</code>. 240 (On the other hand, 241 2 and "<code>2</code>" are different Lua values and therefore 242 denote different table entries.) 243 244 245 <p> 246 Tables, functions, threads, and (full) userdata values are <em>objects</em>: 247 variables do not actually <em>contain</em> these values, 248 only <em>references</em> to them. 249 Assignment, parameter passing, and function returns 250 always manipulate references to such values; 251 these operations do not imply any kind of copy. 252 253 254 <p> 255 The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type 256 of a given value (see <a href="#6.1">§6.1</a>). 257 258 259 260 261 262 <h2>2.2 – <a name="2.2">Environments and the Global Environment</a></h2> 263 264 <p> 265 As will be discussed in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>, 266 any reference to a free name 267 (that is, a name not bound to any declaration) <code>var</code> 268 is syntactically translated to <code>_ENV.var</code>. 269 Moreover, every chunk is compiled in the scope of 270 an external local variable named <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>), 271 so <code>_ENV</code> itself is never a free name in a chunk. 272 273 274 <p> 275 Despite the existence of this external <code>_ENV</code> variable and 276 the translation of free names, 277 <code>_ENV</code> is a completely regular name. 278 In particular, 279 you can define new variables and parameters with that name. 280 Each reference to a free name uses the <code>_ENV</code> that is 281 visible at that point in the program, 282 following the usual visibility rules of Lua (see <a href="#3.5">§3.5</a>). 283 284 285 <p> 286 Any table used as the value of <code>_ENV</code> is called an <em>environment</em>. 287 288 289 <p> 290 Lua keeps a distinguished environment called the <em>global environment</em>. 291 This value is kept at a special index in the C registry (see <a href="#4.5">§4.5</a>). 292 In Lua, the global variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value. 293 (<a href="#pdf-_G"><code>_G</code></a> is never used internally.) 294 295 296 <p> 297 When Lua loads a chunk, 298 the default value for its <code>_ENV</code> upvalue 299 is the global environment (see <a href="#pdf-load"><code>load</code></a>). 300 Therefore, by default, 301 free names in Lua code refer to entries in the global environment 302 (and, therefore, they are also called <em>global variables</em>). 303 Moreover, all standard libraries are loaded in the global environment 304 and some functions there operate on that environment. 305 You can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>) 306 to load a chunk with a different environment. 307 (In C, you have to load the chunk and then change the value 308 of its first upvalue.) 309 310 311 312 313 314 <h2>2.3 – <a name="2.3">Error Handling</a></h2> 315 316 <p> 317 Because Lua is an embedded extension language, 318 all Lua actions start from C code in the host program 319 calling a function from the Lua library. 320 (When you use Lua standalone, 321 the <code>lua</code> application is the host program.) 322 Whenever an error occurs during 323 the compilation or execution of a Lua chunk, 324 control returns to the host, 325 which can take appropriate measures 326 (such as printing an error message). 327 328 329 <p> 330 Lua code can explicitly generate an error by calling the 331 <a href="#pdf-error"><code>error</code></a> function. 332 If you need to catch errors in Lua, 333 you can use <a href="#pdf-pcall"><code>pcall</code></a> or <a href="#pdf-xpcall"><code>xpcall</code></a> 334 to call a given function in <em>protected mode</em>. 335 336 337 <p> 338 Whenever there is an error, 339 an <em>error object</em> (also called an <em>error message</em>) 340 is propagated with information about the error. 341 Lua itself only generates errors whose error object is a string, 342 but programs may generate errors with 343 any value as the error object. 344 It is up to the Lua program or its host to handle such error objects. 345 346 347 <p> 348 When you use <a href="#pdf-xpcall"><code>xpcall</code></a> or <a href="#lua_pcall"><code>lua_pcall</code></a>, 349 you may give a <em>message handler</em> 350 to be called in case of errors. 351 This function is called with the original error message 352 and returns a new error message. 353 It is called before the error unwinds the stack, 354 so that it can gather more information about the error, 355 for instance by inspecting the stack and creating a stack traceback. 356 This message handler is still protected by the protected call; 357 so, an error inside the message handler 358 will call the message handler again. 359 If this loop goes on for too long, 360 Lua breaks it and returns an appropriate message. 361 362 363 364 365 366 <h2>2.4 – <a name="2.4">Metatables and Metamethods</a></h2> 367 368 <p> 369 Every value in Lua can have a <em>metatable</em>. 370 This <em>metatable</em> is an ordinary Lua table 371 that defines the behavior of the original value 372 under certain special operations. 373 You can change several aspects of the behavior 374 of operations over a value by setting specific fields in its metatable. 375 For instance, when a non-numeric value is the operand of an addition, 376 Lua checks for a function in the field "<code>__add</code>" of the value's metatable. 377 If it finds one, 378 Lua calls this function to perform the addition. 379 380 381 <p> 382 The keys in a metatable are derived from the <em>event</em> names; 383 the corresponding values are called <em>metamethods</em>. 384 In the previous example, the event is <code>"add"</code> 385 and the metamethod is the function that performs the addition. 386 387 388 <p> 389 You can query the metatable of any value 390 using the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function. 391 392 393 <p> 394 You can replace the metatable of tables 395 using the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function. 396 You cannot change the metatable of other types from Lua 397 (except by using the debug library (<a href="#6.10">§6.10</a>)); 398 you must use the C API for that. 399 400 401 <p> 402 Tables and full userdata have individual metatables 403 (although multiple tables and userdata can share their metatables). 404 Values of all other types share one single metatable per type; 405 that is, there is one single metatable for all numbers, 406 one for all strings, etc. 407 By default, a value has no metatable, 408 but the string library sets a metatable for the string type (see <a href="#6.4">§6.4</a>). 409 410 411 <p> 412 A metatable controls how an object behaves in 413 arithmetic operations, bitwise operations, 414 order comparisons, concatenation, length operation, calls, and indexing. 415 A metatable also can define a function to be called 416 when a userdata or a table is garbage collected (<a href="#2.5">§2.5</a>). 417 418 419 <p> 420 A detailed list of events controlled by metatables is given next. 421 Each operation is identified by its corresponding event name. 422 The key for each event is a string with its name prefixed by 423 two underscores, '<code>__</code>'; 424 for instance, the key for operation "add" is the 425 string "<code>__add</code>". 426 Note that queries for metamethods are always raw; 427 the access to a metamethod does not invoke other metamethods. 428 You can emulate how Lua queries a metamethod for an object <code>obj</code> 429 with the following code: 430 431 <pre> 432 rawget(getmetatable(obj) or {}, "__" .. event_name) 433 </pre> 434 435 <p> 436 For the unary operators (negation, length, and bitwise not), 437 the metamethod is computed and called with a dummy second operand, 438 equal to the first one. 439 This extra operand is only to simplify Lua's internals 440 (by making these operators behave like a binary operation) 441 and may be removed in future versions. 442 (For most uses this extra operand is irrelevant.) 443 444 445 446 <ul> 447 448 <li><b>"add": </b> 449 the <code>+</code> operation. 450 451 If any operand for an addition is not a number 452 (nor a string coercible to a number), 453 Lua will try to call a metamethod. 454 First, Lua will check the first operand (even if it is valid). 455 If that operand does not define a metamethod for the "<code>__add</code>" event, 456 then Lua will check the second operand. 457 If Lua can find a metamethod, 458 it calls the metamethod with the two operands as arguments, 459 and the result of the call 460 (adjusted to one value) 461 is the result of the operation. 462 Otherwise, 463 it raises an error. 464 </li> 465 466 <li><b>"sub": </b> 467 the <code>-</code> operation. 468 469 Behavior similar to the "add" operation. 470 </li> 471 472 <li><b>"mul": </b> 473 the <code>*</code> operation. 474 475 Behavior similar to the "add" operation. 476 </li> 477 478 <li><b>"div": </b> 479 the <code>/</code> operation. 480 481 Behavior similar to the "add" operation. 482 </li> 483 484 <li><b>"mod": </b> 485 the <code>%</code> operation. 486 487 Behavior similar to the "add" operation. 488 </li> 489 490 <li><b>"pow": </b> 491 the <code>^</code> (exponentiation) operation. 492 493 Behavior similar to the "add" operation. 494 </li> 495 496 <li><b>"unm": </b> 497 the <code>-</code> (unary minus) operation. 498 499 Behavior similar to the "add" operation. 500 </li> 501 502 <li><b>"idiv": </b> 503 the <code>//</code> (floor division) operation. 504 505 Behavior similar to the "add" operation. 506 </li> 507 508 <li><b>"band": </b> 509 the <code>&</code> (bitwise and) operation. 510 511 Behavior similar to the "add" operation, 512 except that Lua will try a metamethod 513 if any operator is neither an integer 514 nor a value coercible to an integer (see <a href="#3.4.3">§3.4.3</a>). 515 </li> 516 517 <li><b>"bor": </b> 518 the <code>|</code> (bitwise or) operation. 519 520 Behavior similar to the "band" operation. 521 </li> 522 523 <li><b>"bxor": </b> 524 the <code>~</code> (bitwise exclusive or) operation. 525 526 Behavior similar to the "band" operation. 527 </li> 528 529 <li><b>"bnot": </b> 530 the <code>~</code> (bitwise unary not) operation. 531 532 Behavior similar to the "band" operation. 533 </li> 534 535 <li><b>"shl": </b> 536 the <code><<</code> (bitwise left shift) operation. 537 538 Behavior similar to the "band" operation. 539 </li> 540 541 <li><b>"shr": </b> 542 the <code>>></code> (bitwise right shift) operation. 543 544 Behavior similar to the "band" operation. 545 </li> 546 547 <li><b>"concat": </b> 548 the <code>..</code> (concatenation) operation. 549 550 Behavior similar to the "add" operation, 551 except that Lua will try a metamethod 552 if any operator is neither a string nor a number 553 (which is always coercible to a string). 554 </li> 555 556 <li><b>"len": </b> 557 the <code>#</code> (length) operation. 558 559 If the object is not a string, 560 Lua will try its metamethod. 561 If there is a metamethod, 562 Lua calls it with the object as argument, 563 and the result of the call 564 (always adjusted to one value) 565 is the result of the operation. 566 If there is no metamethod but the object is a table, 567 then Lua uses the table length operation (see <a href="#3.4.7">§3.4.7</a>). 568 Otherwise, Lua raises an error. 569 </li> 570 571 <li><b>"eq": </b> 572 the <code>==</code> (equal) operation. 573 574 Behavior similar to the "add" operation, 575 except that Lua will try a metamethod only when the values 576 being compared are either both tables or both full userdata 577 and they are not primitively equal. 578 The result of the call is always converted to a boolean. 579 </li> 580 581 <li><b>"lt": </b> 582 the <code><</code> (less than) operation. 583 584 Behavior similar to the "add" operation, 585 except that Lua will try a metamethod only when the values 586 being compared are neither both numbers nor both strings. 587 The result of the call is always converted to a boolean. 588 </li> 589 590 <li><b>"le": </b> 591 the <code><=</code> (less equal) operation. 592 593 Unlike other operations, 594 The less-equal operation can use two different events. 595 First, Lua looks for the "<code>__le</code>" metamethod in both operands, 596 like in the "lt" operation. 597 If it cannot find such a metamethod, 598 then it will try the "<code>__lt</code>" event, 599 assuming that <code>a <= b</code> is equivalent to <code>not (b < a)</code>. 600 As with the other comparison operators, 601 the result is always a boolean. 602 </li> 603 604 <li><b>"index": </b> 605 The indexing access <code>table[key]</code>. 606 607 This event happens when <code>table</code> is not a table or 608 when <code>key</code> is not present in <code>table</code>. 609 The metamethod is looked up in <code>table</code>. 610 611 612 <p> 613 Despite the name, 614 the metamethod for this event can be either a function or a table. 615 If it is a function, 616 it is called with <code>table</code> and <code>key</code> as arguments. 617 If it is a table, 618 the final result is the result of indexing this table with <code>key</code>. 619 (This indexing is regular, not raw, 620 and therefore can trigger another metamethod.) 621 </li> 622 623 <li><b>"newindex": </b> 624 The indexing assignment <code>table[key] = value</code>. 625 626 Like the index event, 627 this event happens when <code>table</code> is not a table or 628 when <code>key</code> is not present in <code>table</code>. 629 The metamethod is looked up in <code>table</code>. 630 631 632 <p> 633 Like with indexing, 634 the metamethod for this event can be either a function or a table. 635 If it is a function, 636 it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments. 637 If it is a table, 638 Lua does an indexing assignment to this table with the same key and value. 639 (This assignment is regular, not raw, 640 and therefore can trigger another metamethod.) 641 642 643 <p> 644 Whenever there is a "newindex" metamethod, 645 Lua does not perform the primitive assignment. 646 (If necessary, 647 the metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a> 648 to do the assignment.) 649 </li> 650 651 <li><b>"call": </b> 652 The call operation <code>func(args)</code>. 653 654 This event happens when Lua tries to call a non-function value 655 (that is, <code>func</code> is not a function). 656 The metamethod is looked up in <code>func</code>. 657 If present, 658 the metamethod is called with <code>func</code> as its first argument, 659 followed by the arguments of the original call (<code>args</code>). 660 </li> 661 662 </ul> 663 664 665 666 667 <h2>2.5 – <a name="2.5">Garbage Collection</a></h2> 668 669 <p> 670 Lua performs automatic memory management. 671 This means that 672 you do not have to worry about allocating memory for new objects 673 or freeing it when the objects are no longer needed. 674 Lua manages memory automatically by running 675 a <em>garbage collector</em> to collect all <em>dead objects</em> 676 (that is, objects that are no longer accessible from Lua). 677 All memory used by Lua is subject to automatic management: 678 strings, tables, userdata, functions, threads, internal structures, etc. 679 680 681 <p> 682 Lua implements an incremental mark-and-sweep collector. 683 It uses two numbers to control its garbage-collection cycles: 684 the <em>garbage-collector pause</em> and 685 the <em>garbage-collector step multiplier</em>. 686 Both use percentage points as units 687 (e.g., a value of 100 means an internal value of 1). 688 689 690 <p> 691 The garbage-collector pause 692 controls how long the collector waits before starting a new cycle. 693 Larger values make the collector less aggressive. 694 Values smaller than 100 mean the collector will not wait to 695 start a new cycle. 696 A value of 200 means that the collector waits for the total memory in use 697 to double before starting a new cycle. 698 699 700 <p> 701 The garbage-collector step multiplier 702 controls the relative speed of the collector relative to 703 memory allocation. 704 Larger values make the collector more aggressive but also increase 705 the size of each incremental step. 706 You should not use values smaller than 100, 707 because they make the collector too slow and 708 can result in the collector never finishing a cycle. 709 The default is 200, 710 which means that the collector runs at "twice" 711 the speed of memory allocation. 712 713 714 <p> 715 If you set the step multiplier to a very large number 716 (larger than 10% of the maximum number of 717 bytes that the program may use), 718 the collector behaves like a stop-the-world collector. 719 If you then set the pause to 200, 720 the collector behaves as in old Lua versions, 721 doing a complete collection every time Lua doubles its 722 memory usage. 723 724 725 <p> 726 You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C 727 or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. 728 You can also use these functions to control 729 the collector directly (e.g., stop and restart it). 730 731 732 733 <h3>2.5.1 – <a name="2.5.1">Garbage-Collection Metamethods</a></h3> 734 735 <p> 736 You can set garbage-collector metamethods for tables 737 and, using the C API, 738 for full userdata (see <a href="#2.4">§2.4</a>). 739 These metamethods are also called <em>finalizers</em>. 740 Finalizers allow you to coordinate Lua's garbage collection 741 with external resource management 742 (such as closing files, network or database connections, 743 or freeing your own memory). 744 745 746 <p> 747 For an object (table or userdata) to be finalized when collected, 748 you must <em>mark</em> it for finalization. 749 750 You mark an object for finalization when you set its metatable 751 and the metatable has a field indexed by the string "<code>__gc</code>". 752 Note that if you set a metatable without a <code>__gc</code> field 753 and later create that field in the metatable, 754 the object will not be marked for finalization. 755 However, after an object has been marked, 756 you can freely change the <code>__gc</code> field of its metatable. 757 758 759 <p> 760 When a marked object becomes garbage, 761 it is not collected immediately by the garbage collector. 762 Instead, Lua puts it in a list. 763 After the collection, 764 Lua goes through that list. 765 For each object in the list, 766 it checks the object's <code>__gc</code> metamethod: 767 If it is a function, 768 Lua calls it with the object as its single argument; 769 if the metamethod is not a function, 770 Lua simply ignores it. 771 772 773 <p> 774 At the end of each garbage-collection cycle, 775 the finalizers for objects are called in 776 the reverse order that the objects were marked for finalization, 777 among those collected in that cycle; 778 that is, the first finalizer to be called is the one associated 779 with the object marked last in the program. 780 The execution of each finalizer may occur at any point during 781 the execution of the regular code. 782 783 784 <p> 785 Because the object being collected must still be used by the finalizer, 786 that object (and other objects accessible only through it) 787 must be <em>resurrected</em> by Lua. 788 Usually, this resurrection is transient, 789 and the object memory is freed in the next garbage-collection cycle. 790 However, if the finalizer stores the object in some global place 791 (e.g., a global variable), 792 then the resurrection is permanent. 793 Moreover, if the finalizer marks a finalizing object for finalization again, 794 its finalizer will be called again in the next cycle where the 795 object is unreachable. 796 In any case, 797 the object memory is freed only in the GC cycle where 798 the object is unreachable and not marked for finalization. 799 800 801 <p> 802 When you close a state (see <a href="#lua_close"><code>lua_close</code></a>), 803 Lua calls the finalizers of all objects marked for finalization, 804 following the reverse order that they were marked. 805 If any finalizer marks objects for collection during that phase, 806 these marks have no effect. 807 808 809 810 811 812 <h3>2.5.2 – <a name="2.5.2">Weak Tables</a></h3> 813 814 <p> 815 A <em>weak table</em> is a table whose elements are 816 <em>weak references</em>. 817 A weak reference is ignored by the garbage collector. 818 In other words, 819 if the only references to an object are weak references, 820 then the garbage collector will collect that object. 821 822 823 <p> 824 A weak table can have weak keys, weak values, or both. 825 A table with weak keys allows the collection of its keys, 826 but prevents the collection of its values. 827 A table with both weak keys and weak values allows the collection of 828 both keys and values. 829 In any case, if either the key or the value is collected, 830 the whole pair is removed from the table. 831 The weakness of a table is controlled by the 832 <code>__mode</code> field of its metatable. 833 If the <code>__mode</code> field is a string containing the character '<code>k</code>', 834 the keys in the table are weak. 835 If <code>__mode</code> contains '<code>v</code>', 836 the values in the table are weak. 837 838 839 <p> 840 A table with weak keys and strong values 841 is also called an <em>ephemeron table</em>. 842 In an ephemeron table, 843 a value is considered reachable only if its key is reachable. 844 In particular, 845 if the only reference to a key comes through its value, 846 the pair is removed. 847 848 849 <p> 850 Any change in the weakness of a table may take effect only 851 at the next collect cycle. 852 In particular, if you change the weakness to a stronger mode, 853 Lua may still collect some items from that table 854 before the change takes effect. 855 856 857 <p> 858 Only objects that have an explicit construction 859 are removed from weak tables. 860 Values, such as numbers and light C functions, 861 are not subject to garbage collection, 862 and therefore are not removed from weak tables 863 (unless their associated values are collected). 864 Although strings are subject to garbage collection, 865 they do not have an explicit construction, 866 and therefore are not removed from weak tables. 867 868 869 <p> 870 Resurrected objects 871 (that is, objects being finalized 872 and objects accessible only through objects being finalized) 873 have a special behavior in weak tables. 874 They are removed from weak values before running their finalizers, 875 but are removed from weak keys only in the next collection 876 after running their finalizers, when such objects are actually freed. 877 This behavior allows the finalizer to access properties 878 associated with the object through weak tables. 879 880 881 <p> 882 If a weak table is among the resurrected objects in a collection cycle, 883 it may not be properly cleared until the next cycle. 884 885 886 887 888 889 890 891 <h2>2.6 – <a name="2.6">Coroutines</a></h2> 892 893 <p> 894 Lua supports coroutines, 895 also called <em>collaborative multithreading</em>. 896 A coroutine in Lua represents an independent thread of execution. 897 Unlike threads in multithread systems, however, 898 a coroutine only suspends its execution by explicitly calling 899 a yield function. 900 901 902 <p> 903 You create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>. 904 Its sole argument is a function 905 that is the main function of the coroutine. 906 The <code>create</code> function only creates a new coroutine and 907 returns a handle to it (an object of type <em>thread</em>); 908 it does not start the coroutine. 909 910 911 <p> 912 You execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 913 When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 914 passing as its first argument 915 a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 916 the coroutine starts its execution, 917 at the first line of its main function. 918 Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed 919 as arguments to the coroutine's main function. 920 After the coroutine starts running, 921 it runs until it terminates or <em>yields</em>. 922 923 924 <p> 925 A coroutine can terminate its execution in two ways: 926 normally, when its main function returns 927 (explicitly or implicitly, after the last instruction); 928 and abnormally, if there is an unprotected error. 929 In case of normal termination, 930 <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>, 931 plus any values returned by the coroutine main function. 932 In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b> 933 plus an error message. 934 935 936 <p> 937 A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 938 When a coroutine yields, 939 the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately, 940 even if the yield happens inside nested function calls 941 (that is, not in the main function, 942 but in a function directly or indirectly called by the main function). 943 In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>, 944 plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 945 The next time you resume the same coroutine, 946 it continues its execution from the point where it yielded, 947 with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra 948 arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 949 950 951 <p> 952 Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 953 the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine, 954 but instead of returning the coroutine itself, 955 it returns a function that, when called, resumes the coroutine. 956 Any arguments passed to this function 957 go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 958 <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> returns all the values returned by <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 959 except the first one (the boolean error code). 960 Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 961 <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors; 962 any error is propagated to the caller. 963 964 965 <p> 966 As an example of how coroutines work, 967 consider the following code: 968 969 <pre> 970 function foo (a) 971 print("foo", a) 972 return coroutine.yield(2*a) 973 end 974 975 co = coroutine.create(function (a,b) 976 print("co-body", a, b) 977 local r = foo(a+1) 978 print("co-body", r) 979 local r, s = coroutine.yield(a+b, a-b) 980 print("co-body", r, s) 981 return b, "end" 982 end) 983 984 print("main", coroutine.resume(co, 1, 10)) 985 print("main", coroutine.resume(co, "r")) 986 print("main", coroutine.resume(co, "x", "y")) 987 print("main", coroutine.resume(co, "x", "y")) 988 </pre><p> 989 When you run it, it produces the following output: 990 991 <pre> 992 co-body 1 10 993 foo 2 994 main true 4 995 co-body r 996 main true 11 -9 997 co-body x y 998 main true 10 end 999 main false cannot resume dead coroutine 1000 </pre> 1001 1002 <p> 1003 You can also create and manipulate coroutines through the C API: 1004 see functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>, 1005 and <a href="#lua_yield"><code>lua_yield</code></a>. 1006 1007 1008 1009 1010 1011 <h1>3 – <a name="3">The Language</a></h1> 1012 1013 <p> 1014 This section describes the lexis, the syntax, and the semantics of Lua. 1015 In other words, 1016 this section describes 1017 which tokens are valid, 1018 how they can be combined, 1019 and what their combinations mean. 1020 1021 1022 <p> 1023 Language constructs will be explained using the usual extended BNF notation, 1024 in which 1025 {<em>a</em>} means 0 or more <em>a</em>'s, and 1026 [<em>a</em>] means an optional <em>a</em>. 1027 Non-terminals are shown like non-terminal, 1028 keywords are shown like <b>kword</b>, 1029 and other terminal symbols are shown like ‘<b>=</b>’. 1030 The complete syntax of Lua can be found in <a href="#9">§9</a> 1031 at the end of this manual. 1032 1033 1034 1035 <h2>3.1 – <a name="3.1">Lexical Conventions</a></h2> 1036 1037 <p> 1038 Lua is a free-form language. 1039 It ignores spaces (including new lines) and comments 1040 between lexical elements (tokens), 1041 except as delimiters between names and keywords. 1042 1043 1044 <p> 1045 <em>Names</em> 1046 (also called <em>identifiers</em>) 1047 in Lua can be any string of letters, 1048 digits, and underscores, 1049 not beginning with a digit. 1050 Identifiers are used to name variables, table fields, and labels. 1051 1052 1053 <p> 1054 The following <em>keywords</em> are reserved 1055 and cannot be used as names: 1056 1057 1058 <pre> 1059 and break do else elseif end 1060 false for function goto if in 1061 local nil not or repeat return 1062 then true until while 1063 </pre> 1064 1065 <p> 1066 Lua is a case-sensitive language: 1067 <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> 1068 are two different, valid names. 1069 As a convention, 1070 programs should avoid creating 1071 names that start with an underscore followed by 1072 one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>). 1073 1074 1075 <p> 1076 The following strings denote other tokens: 1077 1078 <pre> 1079 + - * / % ^ # 1080 & ~ | << >> // 1081 == ~= <= >= < > = 1082 ( ) { } [ ] :: 1083 ; : , . .. ... 1084 </pre> 1085 1086 <p> 1087 <em>Literal strings</em> 1088 can be delimited by matching single or double quotes, 1089 and can contain the following C-like escape sequences: 1090 '<code>\a</code>' (bell), 1091 '<code>\b</code>' (backspace), 1092 '<code>\f</code>' (form feed), 1093 '<code>\n</code>' (newline), 1094 '<code>\r</code>' (carriage return), 1095 '<code>\t</code>' (horizontal tab), 1096 '<code>\v</code>' (vertical tab), 1097 '<code>\\</code>' (backslash), 1098 '<code>\"</code>' (quotation mark [double quote]), 1099 and '<code>\'</code>' (apostrophe [single quote]). 1100 A backslash followed by a real newline 1101 results in a newline in the string. 1102 The escape sequence '<code>\z</code>' skips the following span 1103 of white-space characters, 1104 including line breaks; 1105 it is particularly useful to break and indent a long literal string 1106 into multiple lines without adding the newlines and spaces 1107 into the string contents. 1108 1109 1110 <p> 1111 Strings in Lua can contain any 8-bit value, including embedded zeros, 1112 which can be specified as '<code>\0</code>'. 1113 More generally, 1114 we can specify any byte in a literal string by its numerical value. 1115 This can be done 1116 with the escape sequence <code>\x<em>XX</em></code>, 1117 where <em>XX</em> is a sequence of exactly two hexadecimal digits, 1118 or with the escape sequence <code>\<em>ddd</em></code>, 1119 where <em>ddd</em> is a sequence of up to three decimal digits. 1120 (Note that if a decimal escape sequence is to be followed by a digit, 1121 it must be expressed using exactly three digits.) 1122 1123 1124 <p> 1125 The UTF-8 encoding of a Unicode character 1126 can be inserted in a literal string with 1127 the escape sequence <code>\u{<em>XXX</em>}</code> 1128 (note the mandatory enclosing brackets), 1129 where <em>XXX</em> is a sequence of one or more hexadecimal digits 1130 representing the character code point. 1131 1132 1133 <p> 1134 Literal strings can also be defined using a long format 1135 enclosed by <em>long brackets</em>. 1136 We define an <em>opening long bracket of level <em>n</em></em> as an opening 1137 square bracket followed by <em>n</em> equal signs followed by another 1138 opening square bracket. 1139 So, an opening long bracket of level 0 is written as <code>[[</code>, 1140 an opening long bracket of level 1 is written as <code>[=[</code>, 1141 and so on. 1142 A <em>closing long bracket</em> is defined similarly; 1143 for instance, 1144 a closing long bracket of level 4 is written as <code>]====]</code>. 1145 A <em>long literal</em> starts with an opening long bracket of any level and 1146 ends at the first closing long bracket of the same level. 1147 It can contain any text except a closing bracket of the same level. 1148 Literals in this bracketed form can run for several lines, 1149 do not interpret any escape sequences, 1150 and ignore long brackets of any other level. 1151 Any kind of end-of-line sequence 1152 (carriage return, newline, carriage return followed by newline, 1153 or newline followed by carriage return) 1154 is converted to a simple newline. 1155 1156 1157 <p> 1158 Any byte in a literal string not 1159 explicitly affected by the previous rules represents itself. 1160 However, Lua opens files for parsing in text mode, 1161 and the system file functions may have problems with 1162 some control characters. 1163 So, it is safer to represent 1164 non-text data as a quoted literal with 1165 explicit escape sequences for non-text characters. 1166 1167 1168 <p> 1169 For convenience, 1170 when the opening long bracket is immediately followed by a newline, 1171 the newline is not included in the string. 1172 As an example, in a system using ASCII 1173 (in which '<code>a</code>' is coded as 97, 1174 newline is coded as 10, and '<code>1</code>' is coded as 49), 1175 the five literal strings below denote the same string: 1176 1177 <pre> 1178 a = 'alo\n123"' 1179 a = "alo\n123\"" 1180 a = '\97lo\10\04923"' 1181 a = [[alo 1182 123"]] 1183 a = [==[ 1184 alo 1185 123"]==] 1186 </pre> 1187 1188 <p> 1189 A <em>numerical constant</em> (or <em>numeral</em>) 1190 can be written with an optional fractional part 1191 and an optional decimal exponent, 1192 marked by a letter '<code>e</code>' or '<code>E</code>'. 1193 Lua also accepts hexadecimal constants, 1194 which start with <code>0x</code> or <code>0X</code>. 1195 Hexadecimal constants also accept an optional fractional part 1196 plus an optional binary exponent, 1197 marked by a letter '<code>p</code>' or '<code>P</code>'. 1198 A numeric constant with a fractional dot or an exponent 1199 denotes a float; 1200 otherwise it denotes an integer. 1201 Examples of valid integer constants are 1202 1203 <pre> 1204 3 345 0xff 0xBEBADA 1205 </pre><p> 1206 Examples of valid float constants are 1207 1208 <pre> 1209 3.0 3.1416 314.16e-2 0.31416E1 34e1 1210 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 1211 </pre> 1212 1213 <p> 1214 A <em>comment</em> starts with a double hyphen (<code>--</code>) 1215 anywhere outside a string. 1216 If the text immediately after <code>--</code> is not an opening long bracket, 1217 the comment is a <em>short comment</em>, 1218 which runs until the end of the line. 1219 Otherwise, it is a <em>long comment</em>, 1220 which runs until the corresponding closing long bracket. 1221 Long comments are frequently used to disable code temporarily. 1222 1223 1224 1225 1226 1227 <h2>3.2 – <a name="3.2">Variables</a></h2> 1228 1229 <p> 1230 Variables are places that store values. 1231 There are three kinds of variables in Lua: 1232 global variables, local variables, and table fields. 1233 1234 1235 <p> 1236 A single name can denote a global variable or a local variable 1237 (or a function's formal parameter, 1238 which is a particular kind of local variable): 1239 1240 <pre> 1241 var ::= Name 1242 </pre><p> 1243 Name denotes identifiers, as defined in <a href="#3.1">§3.1</a>. 1244 1245 1246 <p> 1247 Any variable name is assumed to be global unless explicitly declared 1248 as a local (see <a href="#3.3.7">§3.3.7</a>). 1249 Local variables are <em>lexically scoped</em>: 1250 local variables can be freely accessed by functions 1251 defined inside their scope (see <a href="#3.5">§3.5</a>). 1252 1253 1254 <p> 1255 Before the first assignment to a variable, its value is <b>nil</b>. 1256 1257 1258 <p> 1259 Square brackets are used to index a table: 1260 1261 <pre> 1262 var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ 1263 </pre><p> 1264 The meaning of accesses to table fields can be changed via metatables. 1265 An access to an indexed variable <code>t[i]</code> is equivalent to 1266 a call <code>gettable_event(t,i)</code>. 1267 (See <a href="#2.4">§2.4</a> for a complete description of the 1268 <code>gettable_event</code> function. 1269 This function is not defined or callable in Lua. 1270 We use it here only for explanatory purposes.) 1271 1272 1273 <p> 1274 The syntax <code>var.Name</code> is just syntactic sugar for 1275 <code>var["Name"]</code>: 1276 1277 <pre> 1278 var ::= prefixexp ‘<b>.</b>’ Name 1279 </pre> 1280 1281 <p> 1282 An access to a global variable <code>x</code> 1283 is equivalent to <code>_ENV.x</code>. 1284 Due to the way that chunks are compiled, 1285 <code>_ENV</code> is never a global name (see <a href="#2.2">§2.2</a>). 1286 1287 1288 1289 1290 1291 <h2>3.3 – <a name="3.3">Statements</a></h2> 1292 1293 <p> 1294 Lua supports an almost conventional set of statements, 1295 similar to those in Pascal or C. 1296 This set includes 1297 assignments, control structures, function calls, 1298 and variable declarations. 1299 1300 1301 1302 <h3>3.3.1 – <a name="3.3.1">Blocks</a></h3> 1303 1304 <p> 1305 A block is a list of statements, 1306 which are executed sequentially: 1307 1308 <pre> 1309 block ::= {stat} 1310 </pre><p> 1311 Lua has <em>empty statements</em> 1312 that allow you to separate statements with semicolons, 1313 start a block with a semicolon 1314 or write two semicolons in sequence: 1315 1316 <pre> 1317 stat ::= ‘<b>;</b>’ 1318 </pre> 1319 1320 <p> 1321 Function calls and assignments 1322 can start with an open parenthesis. 1323 This possibility leads to an ambiguity in Lua's grammar. 1324 Consider the following fragment: 1325 1326 <pre> 1327 a = b + c 1328 (print or io.write)('done') 1329 </pre><p> 1330 The grammar could see it in two ways: 1331 1332 <pre> 1333 a = b + c(print or io.write)('done') 1334 1335 a = b + c; (print or io.write)('done') 1336 </pre><p> 1337 The current parser always sees such constructions 1338 in the first way, 1339 interpreting the open parenthesis 1340 as the start of the arguments to a call. 1341 To avoid this ambiguity, 1342 it is a good practice to always precede with a semicolon 1343 statements that start with a parenthesis: 1344 1345 <pre> 1346 ;(print or io.write)('done') 1347 </pre> 1348 1349 <p> 1350 A block can be explicitly delimited to produce a single statement: 1351 1352 <pre> 1353 stat ::= <b>do</b> block <b>end</b> 1354 </pre><p> 1355 Explicit blocks are useful 1356 to control the scope of variable declarations. 1357 Explicit blocks are also sometimes used to 1358 add a <b>return</b> statement in the middle 1359 of another block (see <a href="#3.3.4">§3.3.4</a>). 1360 1361 1362 1363 1364 1365 <h3>3.3.2 – <a name="3.3.2">Chunks</a></h3> 1366 1367 <p> 1368 The unit of compilation of Lua is called a <em>chunk</em>. 1369 Syntactically, 1370 a chunk is simply a block: 1371 1372 <pre> 1373 chunk ::= block 1374 </pre> 1375 1376 <p> 1377 Lua handles a chunk as the body of an anonymous function 1378 with a variable number of arguments 1379 (see <a href="#3.4.11">§3.4.11</a>). 1380 As such, chunks can define local variables, 1381 receive arguments, and return values. 1382 Moreover, such anonymous function is compiled as in the 1383 scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>). 1384 The resulting function always has <code>_ENV</code> as its only upvalue, 1385 even if it does not use that variable. 1386 1387 1388 <p> 1389 A chunk can be stored in a file or in a string inside the host program. 1390 To execute a chunk, 1391 Lua first <em>loads</em> it, 1392 precompiling the chunk's code into instructions for a virtual machine, 1393 and then Lua executes the compiled code 1394 with an interpreter for the virtual machine. 1395 1396 1397 <p> 1398 Chunks can also be precompiled into binary form; 1399 see program <code>luac</code> and function <a href="#pdf-string.dump"><code>string.dump</code></a> for details. 1400 Programs in source and compiled forms are interchangeable; 1401 Lua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>). 1402 1403 1404 1405 1406 1407 <h3>3.3.3 – <a name="3.3.3">Assignment</a></h3> 1408 1409 <p> 1410 Lua allows multiple assignments. 1411 Therefore, the syntax for assignment 1412 defines a list of variables on the left side 1413 and a list of expressions on the right side. 1414 The elements in both lists are separated by commas: 1415 1416 <pre> 1417 stat ::= varlist ‘<b>=</b>’ explist 1418 varlist ::= var {‘<b>,</b>’ var} 1419 explist ::= exp {‘<b>,</b>’ exp} 1420 </pre><p> 1421 Expressions are discussed in <a href="#3.4">§3.4</a>. 1422 1423 1424 <p> 1425 Before the assignment, 1426 the list of values is <em>adjusted</em> to the length of 1427 the list of variables. 1428 If there are more values than needed, 1429 the excess values are thrown away. 1430 If there are fewer values than needed, 1431 the list is extended with as many <b>nil</b>'s as needed. 1432 If the list of expressions ends with a function call, 1433 then all values returned by that call enter the list of values, 1434 before the adjustment 1435 (except when the call is enclosed in parentheses; see <a href="#3.4">§3.4</a>). 1436 1437 1438 <p> 1439 The assignment statement first evaluates all its expressions 1440 and only then the assignments are performed. 1441 Thus the code 1442 1443 <pre> 1444 i = 3 1445 i, a[i] = i+1, 20 1446 </pre><p> 1447 sets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 1448 because the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 1449 before it is assigned 4. 1450 Similarly, the line 1451 1452 <pre> 1453 x, y = y, x 1454 </pre><p> 1455 exchanges the values of <code>x</code> and <code>y</code>, 1456 and 1457 1458 <pre> 1459 x, y, z = y, z, x 1460 </pre><p> 1461 cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 1462 1463 1464 <p> 1465 The meaning of assignments to global variables 1466 and table fields can be changed via metatables. 1467 An assignment to an indexed variable <code>t[i] = val</code> is equivalent to 1468 <code>settable_event(t,i,val)</code>. 1469 (See <a href="#2.4">§2.4</a> for a complete description of the 1470 <code>settable_event</code> function. 1471 This function is not defined or callable in Lua. 1472 We use it here only for explanatory purposes.) 1473 1474 1475 <p> 1476 An assignment to a global name <code>x = val</code> 1477 is equivalent to the assignment 1478 <code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>). 1479 1480 1481 1482 1483 1484 <h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p> 1485 The control structures 1486 <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 1487 familiar syntax: 1488 1489 1490 1491 1492 <pre> 1493 stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 1494 stat ::= <b>repeat</b> block <b>until</b> exp 1495 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> 1496 </pre><p> 1497 Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>). 1498 1499 1500 <p> 1501 The condition expression of a 1502 control structure can return any value. 1503 Both <b>false</b> and <b>nil</b> are considered false. 1504 All values different from <b>nil</b> and <b>false</b> are considered true 1505 (in particular, the number 0 and the empty string are also true). 1506 1507 1508 <p> 1509 In the <b>repeat</b>–<b>until</b> loop, 1510 the inner block does not end at the <b>until</b> keyword, 1511 but only after the condition. 1512 So, the condition can refer to local variables 1513 declared inside the loop block. 1514 1515 1516 <p> 1517 The <b>goto</b> statement transfers the program control to a label. 1518 For syntactical reasons, 1519 labels in Lua are considered statements too: 1520 1521 1522 1523 <pre> 1524 stat ::= <b>goto</b> Name 1525 stat ::= label 1526 label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 1527 </pre> 1528 1529 <p> 1530 A label is visible in the entire block where it is defined, 1531 except 1532 inside nested blocks where a label with the same name is defined and 1533 inside nested functions. 1534 A goto may jump to any visible label as long as it does not 1535 enter into the scope of a local variable. 1536 1537 1538 <p> 1539 Labels and empty statements are called <em>void statements</em>, 1540 as they perform no actions. 1541 1542 1543 <p> 1544 The <b>break</b> statement terminates the execution of a 1545 <b>while</b>, <b>repeat</b>, or <b>for</b> loop, 1546 skipping to the next statement after the loop: 1547 1548 1549 <pre> 1550 stat ::= <b>break</b> 1551 </pre><p> 1552 A <b>break</b> ends the innermost enclosing loop. 1553 1554 1555 <p> 1556 The <b>return</b> statement is used to return values 1557 from a function or a chunk 1558 (which is an anonymous function). 1559 1560 Functions can return more than one value, 1561 so the syntax for the <b>return</b> statement is 1562 1563 <pre> 1564 stat ::= <b>return</b> [explist] [‘<b>;</b>’] 1565 </pre> 1566 1567 <p> 1568 The <b>return</b> statement can only be written 1569 as the last statement of a block. 1570 If it is really necessary to <b>return</b> in the middle of a block, 1571 then an explicit inner block can be used, 1572 as in the idiom <code>do return end</code>, 1573 because now <b>return</b> is the last statement in its (inner) block. 1574 1575 1576 1577 1578 1579 <h3>3.3.5 – <a name="3.3.5">For Statement</a></h3> 1580 1581 <p> 1582 1583 The <b>for</b> statement has two forms: 1584 one numeric and one generic. 1585 1586 1587 <p> 1588 The numeric <b>for</b> loop repeats a block of code while a 1589 control variable runs through an arithmetic progression. 1590 It has the following syntax: 1591 1592 <pre> 1593 stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> 1594 </pre><p> 1595 The <em>block</em> is repeated for <em>name</em> starting at the value of 1596 the first <em>exp</em>, until it passes the second <em>exp</em> by steps of the 1597 third <em>exp</em>. 1598 More precisely, a <b>for</b> statement like 1599 1600 <pre> 1601 for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end 1602 </pre><p> 1603 is equivalent to the code: 1604 1605 <pre> 1606 do 1607 local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>) 1608 if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end 1609 <em>var</em> = <em>var</em> - <em>step</em> 1610 while true do 1611 <em>var</em> = <em>var</em> + <em>step</em> 1612 if (<em>step</em> >= 0 and <em>var</em> > <em>limit</em>) or (<em>step</em> < 0 and <em>var</em> < <em>limit</em>) then 1613 break 1614 end 1615 local v = <em>var</em> 1616 <em>block</em> 1617 end 1618 end 1619 </pre> 1620 1621 <p> 1622 Note the following: 1623 1624 <ul> 1625 1626 <li> 1627 All three control expressions are evaluated only once, 1628 before the loop starts. 1629 They must all result in numbers. 1630 </li> 1631 1632 <li> 1633 <code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables. 1634 The names shown here are for explanatory purposes only. 1635 </li> 1636 1637 <li> 1638 If the third expression (the step) is absent, 1639 then a step of 1 is used. 1640 </li> 1641 1642 <li> 1643 You can use <b>break</b> and <b>goto</b> to exit a <b>for</b> loop. 1644 </li> 1645 1646 <li> 1647 The loop variable <code>v</code> is local to the loop body. 1648 If you need its value after the loop, 1649 assign it to another variable before exiting the loop. 1650 </li> 1651 1652 </ul> 1653 1654 <p> 1655 The generic <b>for</b> statement works over functions, 1656 called <em>iterators</em>. 1657 On each iteration, the iterator function is called to produce a new value, 1658 stopping when this new value is <b>nil</b>. 1659 The generic <b>for</b> loop has the following syntax: 1660 1661 <pre> 1662 stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> 1663 namelist ::= Name {‘<b>,</b>’ Name} 1664 </pre><p> 1665 A <b>for</b> statement like 1666 1667 <pre> 1668 for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end 1669 </pre><p> 1670 is equivalent to the code: 1671 1672 <pre> 1673 do 1674 local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em> 1675 while true do 1676 local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>) 1677 if <em>var_1</em> == nil then break end 1678 <em>var</em> = <em>var_1</em> 1679 <em>block</em> 1680 end 1681 end 1682 </pre><p> 1683 Note the following: 1684 1685 <ul> 1686 1687 <li> 1688 <code><em>explist</em></code> is evaluated only once. 1689 Its results are an <em>iterator</em> function, 1690 a <em>state</em>, 1691 and an initial value for the first <em>iterator variable</em>. 1692 </li> 1693 1694 <li> 1695 <code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables. 1696 The names are here for explanatory purposes only. 1697 </li> 1698 1699 <li> 1700 You can use <b>break</b> to exit a <b>for</b> loop. 1701 </li> 1702 1703 <li> 1704 The loop variables <code><em>var_i</em></code> are local to the loop; 1705 you cannot use their values after the <b>for</b> ends. 1706 If you need these values, 1707 then assign them to other variables before breaking or exiting the loop. 1708 </li> 1709 1710 </ul> 1711 1712 1713 1714 1715 <h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p> 1716 To allow possible side-effects, 1717 function calls can be executed as statements: 1718 1719 <pre> 1720 stat ::= functioncall 1721 </pre><p> 1722 In this case, all returned values are thrown away. 1723 Function calls are explained in <a href="#3.4.10">§3.4.10</a>. 1724 1725 1726 1727 1728 1729 <h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p> 1730 Local variables can be declared anywhere inside a block. 1731 The declaration can include an initial assignment: 1732 1733 <pre> 1734 stat ::= <b>local</b> namelist [‘<b>=</b>’ explist] 1735 </pre><p> 1736 If present, an initial assignment has the same semantics 1737 of a multiple assignment (see <a href="#3.3.3">§3.3.3</a>). 1738 Otherwise, all variables are initialized with <b>nil</b>. 1739 1740 1741 <p> 1742 A chunk is also a block (see <a href="#3.3.2">§3.3.2</a>), 1743 and so local variables can be declared in a chunk outside any explicit block. 1744 1745 1746 <p> 1747 The visibility rules for local variables are explained in <a href="#3.5">§3.5</a>. 1748 1749 1750 1751 1752 1753 1754 1755 <h2>3.4 – <a name="3.4">Expressions</a></h2> 1756 1757 <p> 1758 The basic expressions in Lua are the following: 1759 1760 <pre> 1761 exp ::= prefixexp 1762 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 1763 exp ::= Numeral 1764 exp ::= LiteralString 1765 exp ::= functiondef 1766 exp ::= tableconstructor 1767 exp ::= ‘<b>...</b>’ 1768 exp ::= exp binop exp 1769 exp ::= unop exp 1770 prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 1771 </pre> 1772 1773 <p> 1774 Numerals and literal strings are explained in <a href="#3.1">§3.1</a>; 1775 variables are explained in <a href="#3.2">§3.2</a>; 1776 function definitions are explained in <a href="#3.4.11">§3.4.11</a>; 1777 function calls are explained in <a href="#3.4.10">§3.4.10</a>; 1778 table constructors are explained in <a href="#3.4.9">§3.4.9</a>. 1779 Vararg expressions, 1780 denoted by three dots ('<code>...</code>'), can only be used when 1781 directly inside a vararg function; 1782 they are explained in <a href="#3.4.11">§3.4.11</a>. 1783 1784 1785 <p> 1786 Binary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), 1787 bitwise operators (see <a href="#3.4.2">§3.4.2</a>), 1788 relational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>), 1789 and the concatenation operator (see <a href="#3.4.6">§3.4.6</a>). 1790 Unary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), 1791 the unary bitwise not (see <a href="#3.4.2">§3.4.2</a>), 1792 the unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), 1793 and the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). 1794 1795 1796 <p> 1797 Both function calls and vararg expressions can result in multiple values. 1798 If a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>), 1799 then its return list is adjusted to zero elements, 1800 thus discarding all returned values. 1801 If an expression is used as the last (or the only) element 1802 of a list of expressions, 1803 then no adjustment is made 1804 (unless the expression is enclosed in parentheses). 1805 In all other contexts, 1806 Lua adjusts the result list to one element, 1807 either discarding all values except the first one 1808 or adding a single <b>nil</b> if there are no values. 1809 1810 1811 <p> 1812 Here are some examples: 1813 1814 <pre> 1815 f() -- adjusted to 0 results 1816 g(f(), x) -- f() is adjusted to 1 result 1817 g(x, f()) -- g gets x plus all results from f() 1818 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) 1819 a,b = ... -- a gets the first vararg parameter, b gets 1820 -- the second (both a and b can get nil if there 1821 -- is no corresponding vararg parameter) 1822 1823 a,b,c = x, f() -- f() is adjusted to 2 results 1824 a,b,c = f() -- f() is adjusted to 3 results 1825 return f() -- returns all results from f() 1826 return ... -- returns all received vararg parameters 1827 return x,y,f() -- returns x, y, and all results from f() 1828 {f()} -- creates a list with all results from f() 1829 {...} -- creates a list with all vararg parameters 1830 {f(), nil} -- f() is adjusted to 1 result 1831 </pre> 1832 1833 <p> 1834 Any expression enclosed in parentheses always results in only one value. 1835 Thus, 1836 <code>(f(x,y,z))</code> is always a single value, 1837 even if <code>f</code> returns several values. 1838 (The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> 1839 or <b>nil</b> if <code>f</code> does not return any values.) 1840 1841 1842 1843 <h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p> 1844 Lua supports the following arithmetic operators: 1845 1846 <ul> 1847 <li><b><code>+</code>: </b>addition</li> 1848 <li><b><code>-</code>: </b>subtraction</li> 1849 <li><b><code>*</code>: </b>multiplication</li> 1850 <li><b><code>/</code>: </b>float division</li> 1851 <li><b><code>//</code>: </b>floor division</li> 1852 <li><b><code>%</code>: </b>modulo</li> 1853 <li><b><code>^</code>: </b>exponentiation</li> 1854 <li><b><code>-</code>: </b>unary minus</li> 1855 </ul> 1856 1857 <p> 1858 With the exception of exponentiation and float division, 1859 the arithmetic operators work as follows: 1860 If both operands are integers, 1861 the operation is performed over integers and the result is an integer. 1862 Otherwise, if both operands are numbers 1863 or strings that can be converted to 1864 numbers (see <a href="#3.4.3">§3.4.3</a>), 1865 then they are converted to floats, 1866 the operation is performed following the usual rules 1867 for floating-point arithmetic 1868 (usually the IEEE 754 standard), 1869 and the result is a float. 1870 1871 1872 <p> 1873 Exponentiation and float division (<code>/</code>) 1874 always convert their operands to floats 1875 and the result is always a float. 1876 Exponentiation uses the ISO C function <code>pow</code>, 1877 so that it works for non-integer exponents too. 1878 1879 1880 <p> 1881 Floor division (<code>//</code>) is a division 1882 that rounds the quotient towards minus infinite, 1883 that is, the floor of the division of its operands. 1884 1885 1886 <p> 1887 Modulo is defined as the remainder of a division 1888 that rounds the quotient towards minus infinite (floor division). 1889 1890 1891 <p> 1892 In case of overflows in integer arithmetic, 1893 all operations <em>wrap around</em>, 1894 according to the usual rules of two-complement arithmetic. 1895 (In other words, 1896 they return the unique representable integer 1897 that is equal modulo <em>2<sup>64</sup></em> to the mathematical result.) 1898 1899 1900 1901 <h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p> 1902 Lua supports the following bitwise operators: 1903 1904 <ul> 1905 <li><b><code>&</code>: </b>bitwise and</li> 1906 <li><b><code>|</code>: </b>bitwise or</li> 1907 <li><b><code>~</code>: </b>bitwise exclusive or</li> 1908 <li><b><code>>></code>: </b>right shift</li> 1909 <li><b><code><<</code>: </b>left shift</li> 1910 <li><b><code>~</code>: </b>unary bitwise not</li> 1911 </ul> 1912 1913 <p> 1914 All bitwise operations convert its operands to integers 1915 (see <a href="#3.4.3">§3.4.3</a>), 1916 operate on all bits of those integers, 1917 and result in an integer. 1918 1919 1920 <p> 1921 Both right and left shifts fill the vacant bits with zeros. 1922 Negative displacements shift to the other direction; 1923 displacements with absolute values equal to or higher than 1924 the number of bits in an integer 1925 result in zero (as all bits are shifted out). 1926 1927 1928 1929 1930 1931 <h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p> 1932 Lua provides some automatic conversions between some 1933 types and representations at run time. 1934 Bitwise operators always convert float operands to integers. 1935 Exponentiation and float division 1936 always convert integer operands to floats. 1937 All other arithmetic operations applied to mixed numbers 1938 (integers and floats) convert the integer operand to a float; 1939 this is called the <em>usual rule</em>. 1940 The C API also converts both integers to floats and 1941 floats to integers, as needed. 1942 Moreover, string concatenation accepts numbers as arguments, 1943 besides strings. 1944 1945 1946 <p> 1947 Lua also converts strings to numbers, 1948 whenever a number is expected. 1949 1950 1951 <p> 1952 In a conversion from integer to float, 1953 if the integer value has an exact representation as a float, 1954 that is the result. 1955 Otherwise, 1956 the conversion gets the nearest higher or 1957 the nearest lower representable value. 1958 This kind of conversion never fails. 1959 1960 1961 <p> 1962 The conversion from float to integer 1963 checks whether the float has an exact representation as an integer 1964 (that is, the float has an integral value and 1965 it is in the range of integer representation). 1966 If it does, that representation is the result. 1967 Otherwise, the conversion fails. 1968 1969 1970 <p> 1971 The conversion from strings to numbers goes as follows: 1972 First, the string is converted to an integer or a float, 1973 following its syntax and the rules of the Lua lexer. 1974 (The string may have also leading and trailing spaces and a sign.) 1975 Then, the resulting number is converted to the required type 1976 (float or integer) according to the previous rules. 1977 1978 1979 <p> 1980 The conversion from numbers to strings uses a 1981 non-specified human-readable format. 1982 For complete control over how numbers are converted to strings, 1983 use the <code>format</code> function from the string library 1984 (see <a href="#pdf-string.format"><code>string.format</code></a>). 1985 1986 1987 1988 1989 1990 <h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p> 1991 Lua supports the following relational operators: 1992 1993 <ul> 1994 <li><b><code>==</code>: </b>equality</li> 1995 <li><b><code>~=</code>: </b>inequality</li> 1996 <li><b><code><</code>: </b>less than</li> 1997 <li><b><code>></code>: </b>greater than</li> 1998 <li><b><code><=</code>: </b>less or equal</li> 1999 <li><b><code>>=</code>: </b>greater or equal</li> 2000 </ul><p> 2001 These operators always result in <b>false</b> or <b>true</b>. 2002 2003 2004 <p> 2005 Equality (<code>==</code>) first compares the type of its operands. 2006 If the types are different, then the result is <b>false</b>. 2007 Otherwise, the values of the operands are compared. 2008 Strings are compared in the obvious way. 2009 Numbers follow the usual rule for binary operations: 2010 if both operands are integers, 2011 they are compared as integers; 2012 otherwise, they are converted to floats 2013 and compared as such. 2014 2015 2016 <p> 2017 Tables, userdata, and threads 2018 are compared by reference: 2019 two objects are considered equal only if they are the same object. 2020 Every time you create a new object 2021 (a table, userdata, or thread), 2022 this new object is different from any previously existing object. 2023 Closures with the same reference are always equal. 2024 Closures with any detectable difference 2025 (different behavior, different definition) are always different. 2026 2027 2028 <p> 2029 You can change the way that Lua compares tables and userdata 2030 by using the "eq" metamethod (see <a href="#2.4">§2.4</a>). 2031 2032 2033 <p> 2034 Equality comparisons do not convert strings to numbers 2035 or vice versa. 2036 Thus, <code>"0"==0</code> evaluates to <b>false</b>, 2037 and <code>t[0]</code> and <code>t["0"]</code> denote different 2038 entries in a table. 2039 2040 2041 <p> 2042 The operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 2043 2044 2045 <p> 2046 The order operators work as follows. 2047 If both arguments are numbers, 2048 then they are compared following 2049 the usual rule for binary operations. 2050 Otherwise, if both arguments are strings, 2051 then their values are compared according to the current locale. 2052 Otherwise, Lua tries to call the "lt" or the "le" 2053 metamethod (see <a href="#2.4">§2.4</a>). 2054 A comparison <code>a > b</code> is translated to <code>b < a</code> 2055 and <code>a >= b</code> is translated to <code>b <= a</code>. 2056 2057 2058 2059 2060 2061 <h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p> 2062 The logical operators in Lua are 2063 <b>and</b>, <b>or</b>, and <b>not</b>. 2064 Like the control structures (see <a href="#3.3.4">§3.3.4</a>), 2065 all logical operators consider both <b>false</b> and <b>nil</b> as false 2066 and anything else as true. 2067 2068 2069 <p> 2070 The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 2071 The conjunction operator <b>and</b> returns its first argument 2072 if this value is <b>false</b> or <b>nil</b>; 2073 otherwise, <b>and</b> returns its second argument. 2074 The disjunction operator <b>or</b> returns its first argument 2075 if this value is different from <b>nil</b> and <b>false</b>; 2076 otherwise, <b>or</b> returns its second argument. 2077 Both <b>and</b> and <b>or</b> use short-circuit evaluation; 2078 that is, 2079 the second operand is evaluated only if necessary. 2080 Here are some examples: 2081 2082 <pre> 2083 10 or 20 --> 10 2084 10 or error() --> 10 2085 nil or "a" --> "a" 2086 nil and 10 --> nil 2087 false and error() --> false 2088 false and nil --> false 2089 false or nil --> nil 2090 10 and 20 --> 20 2091 </pre><p> 2092 (In this manual, 2093 <code>--></code> indicates the result of the preceding expression.) 2094 2095 2096 2097 2098 2099 <h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p> 2100 The string concatenation operator in Lua is 2101 denoted by two dots ('<code>..</code>'). 2102 If both operands are strings or numbers, then they are converted to 2103 strings according to the rules described in <a href="#3.4.3">§3.4.3</a>. 2104 Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). 2105 2106 2107 2108 2109 2110 <h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3> 2111 2112 <p> 2113 The length operator is denoted by the unary prefix operator <code>#</code>. 2114 The length of a string is its number of bytes 2115 (that is, the usual meaning of string length when each 2116 character is one byte). 2117 2118 2119 <p> 2120 A program can modify the behavior of the length operator for 2121 any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>). 2122 2123 2124 <p> 2125 Unless a <code>__len</code> metamethod is given, 2126 the length of a table <code>t</code> is only defined if the 2127 table is a <em>sequence</em>, 2128 that is, 2129 the set of its positive numeric keys is equal to <em>{1..n}</em> 2130 for some non-negative integer <em>n</em>. 2131 In that case, <em>n</em> is its length. 2132 Note that a table like 2133 2134 <pre> 2135 {10, 20, nil, 40} 2136 </pre><p> 2137 is not a sequence, because it has the key <code>4</code> 2138 but does not have the key <code>3</code>. 2139 (So, there is no <em>n</em> such that the set <em>{1..n}</em> is equal 2140 to the set of positive numeric keys of that table.) 2141 Note, however, that non-numeric keys do not interfere 2142 with whether a table is a sequence. 2143 2144 2145 2146 2147 2148 <h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p> 2149 Operator precedence in Lua follows the table below, 2150 from lower to higher priority: 2151 2152 <pre> 2153 or 2154 and 2155 < > <= >= ~= == 2156 | 2157 ~ 2158 & 2159 << >> 2160 .. 2161 + - 2162 * / // % 2163 unary operators (not # - ~) 2164 ^ 2165 </pre><p> 2166 As usual, 2167 you can use parentheses to change the precedences of an expression. 2168 The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 2169 operators are right associative. 2170 All other binary operators are left associative. 2171 2172 2173 2174 2175 2176 <h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p> 2177 Table constructors are expressions that create tables. 2178 Every time a constructor is evaluated, a new table is created. 2179 A constructor can be used to create an empty table 2180 or to create a table and initialize some of its fields. 2181 The general syntax for constructors is 2182 2183 <pre> 2184 tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 2185 fieldlist ::= field {fieldsep field} [fieldsep] 2186 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 2187 fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 2188 </pre> 2189 2190 <p> 2191 Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry 2192 with key <code>exp1</code> and value <code>exp2</code>. 2193 A field of the form <code>name = exp</code> is equivalent to 2194 <code>["name"] = exp</code>. 2195 Finally, fields of the form <code>exp</code> are equivalent to 2196 <code>[i] = exp</code>, where <code>i</code> are consecutive integers 2197 starting with 1. 2198 Fields in the other formats do not affect this counting. 2199 For example, 2200 2201 <pre> 2202 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 2203 </pre><p> 2204 is equivalent to 2205 2206 <pre> 2207 do 2208 local t = {} 2209 t[f(1)] = g 2210 t[1] = "x" -- 1st exp 2211 t[2] = "y" -- 2nd exp 2212 t.x = 1 -- t["x"] = 1 2213 t[3] = f(x) -- 3rd exp 2214 t[30] = 23 2215 t[4] = 45 -- 4th exp 2216 a = t 2217 end 2218 </pre> 2219 2220 <p> 2221 The order of the assignments in a constructor is undefined. 2222 (This order would be relevant only when there are repeated keys.) 2223 2224 2225 <p> 2226 If the last field in the list has the form <code>exp</code> 2227 and the expression is a function call or a vararg expression, 2228 then all values returned by this expression enter the list consecutively 2229 (see <a href="#3.4.10">§3.4.10</a>). 2230 2231 2232 <p> 2233 The field list can have an optional trailing separator, 2234 as a convenience for machine-generated code. 2235 2236 2237 2238 2239 2240 <h3>3.4.10 – <a name="3.4.10">Function Calls</a></h3><p> 2241 A function call in Lua has the following syntax: 2242 2243 <pre> 2244 functioncall ::= prefixexp args 2245 </pre><p> 2246 In a function call, 2247 first prefixexp and args are evaluated. 2248 If the value of prefixexp has type <em>function</em>, 2249 then this function is called 2250 with the given arguments. 2251 Otherwise, the prefixexp "call" metamethod is called, 2252 having as first parameter the value of prefixexp, 2253 followed by the original call arguments 2254 (see <a href="#2.4">§2.4</a>). 2255 2256 2257 <p> 2258 The form 2259 2260 <pre> 2261 functioncall ::= prefixexp ‘<b>:</b>’ Name args 2262 </pre><p> 2263 can be used to call "methods". 2264 A call <code>v:name(<em>args</em>)</code> 2265 is syntactic sugar for <code>v.name(v,<em>args</em>)</code>, 2266 except that <code>v</code> is evaluated only once. 2267 2268 2269 <p> 2270 Arguments have the following syntax: 2271 2272 <pre> 2273 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ 2274 args ::= tableconstructor 2275 args ::= LiteralString 2276 </pre><p> 2277 All argument expressions are evaluated before the call. 2278 A call of the form <code>f{<em>fields</em>}</code> is 2279 syntactic sugar for <code>f({<em>fields</em>})</code>; 2280 that is, the argument list is a single new table. 2281 A call of the form <code>f'<em>string</em>'</code> 2282 (or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 2283 is syntactic sugar for <code>f('<em>string</em>')</code>; 2284 that is, the argument list is a single literal string. 2285 2286 2287 <p> 2288 A call of the form <code>return <em>functioncall</em></code> is called 2289 a <em>tail call</em>. 2290 Lua implements <em>proper tail calls</em> 2291 (or <em>proper tail recursion</em>): 2292 in a tail call, 2293 the called function reuses the stack entry of the calling function. 2294 Therefore, there is no limit on the number of nested tail calls that 2295 a program can execute. 2296 However, a tail call erases any debug information about the 2297 calling function. 2298 Note that a tail call only happens with a particular syntax, 2299 where the <b>return</b> has one single function call as argument; 2300 this syntax makes the calling function return exactly 2301 the returns of the called function. 2302 So, none of the following examples are tail calls: 2303 2304 <pre> 2305 return (f(x)) -- results adjusted to 1 2306 return 2 * f(x) 2307 return x, f(x) -- additional results 2308 f(x); return -- results discarded 2309 return x or f(x) -- results adjusted to 1 2310 </pre> 2311 2312 2313 2314 2315 <h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3> 2316 2317 <p> 2318 The syntax for function definition is 2319 2320 <pre> 2321 functiondef ::= <b>function</b> funcbody 2322 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 2323 </pre> 2324 2325 <p> 2326 The following syntactic sugar simplifies function definitions: 2327 2328 <pre> 2329 stat ::= <b>function</b> funcname funcbody 2330 stat ::= <b>local</b> <b>function</b> Name funcbody 2331 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 2332 </pre><p> 2333 The statement 2334 2335 <pre> 2336 function f () <em>body</em> end 2337 </pre><p> 2338 translates to 2339 2340 <pre> 2341 f = function () <em>body</em> end 2342 </pre><p> 2343 The statement 2344 2345 <pre> 2346 function t.a.b.c.f () <em>body</em> end 2347 </pre><p> 2348 translates to 2349 2350 <pre> 2351 t.a.b.c.f = function () <em>body</em> end 2352 </pre><p> 2353 The statement 2354 2355 <pre> 2356 local function f () <em>body</em> end 2357 </pre><p> 2358 translates to 2359 2360 <pre> 2361 local f; f = function () <em>body</em> end 2362 </pre><p> 2363 not to 2364 2365 <pre> 2366 local f = function () <em>body</em> end 2367 </pre><p> 2368 (This only makes a difference when the body of the function 2369 contains references to <code>f</code>.) 2370 2371 2372 <p> 2373 A function definition is an executable expression, 2374 whose value has type <em>function</em>. 2375 When Lua precompiles a chunk, 2376 all its function bodies are precompiled too. 2377 Then, whenever Lua executes the function definition, 2378 the function is <em>instantiated</em> (or <em>closed</em>). 2379 This function instance (or <em>closure</em>) 2380 is the final value of the expression. 2381 2382 2383 <p> 2384 Parameters act as local variables that are 2385 initialized with the argument values: 2386 2387 <pre> 2388 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 2389 </pre><p> 2390 When a function is called, 2391 the list of arguments is adjusted to 2392 the length of the list of parameters, 2393 unless the function is a <em>vararg function</em>, 2394 which is indicated by three dots ('<code>...</code>') 2395 at the end of its parameter list. 2396 A vararg function does not adjust its argument list; 2397 instead, it collects all extra arguments and supplies them 2398 to the function through a <em>vararg expression</em>, 2399 which is also written as three dots. 2400 The value of this expression is a list of all actual extra arguments, 2401 similar to a function with multiple results. 2402 If a vararg expression is used inside another expression 2403 or in the middle of a list of expressions, 2404 then its return list is adjusted to one element. 2405 If the expression is used as the last element of a list of expressions, 2406 then no adjustment is made 2407 (unless that last expression is enclosed in parentheses). 2408 2409 2410 <p> 2411 As an example, consider the following definitions: 2412 2413 <pre> 2414 function f(a, b) end 2415 function g(a, b, ...) end 2416 function r() return 1,2,3 end 2417 </pre><p> 2418 Then, we have the following mapping from arguments to parameters and 2419 to the vararg expression: 2420 2421 <pre> 2422 CALL PARAMETERS 2423 2424 f(3) a=3, b=nil 2425 f(3, 4) a=3, b=4 2426 f(3, 4, 5) a=3, b=4 2427 f(r(), 10) a=1, b=10 2428 f(r()) a=1, b=2 2429 2430 g(3) a=3, b=nil, ... --> (nothing) 2431 g(3, 4) a=3, b=4, ... --> (nothing) 2432 g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 2433 g(5, r()) a=5, b=1, ... --> 2 3 2434 </pre> 2435 2436 <p> 2437 Results are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>). 2438 If control reaches the end of a function 2439 without encountering a <b>return</b> statement, 2440 then the function returns with no results. 2441 2442 2443 <p> 2444 2445 There is a system-dependent limit on the number of values 2446 that a function may return. 2447 This limit is guaranteed to be larger than 1000. 2448 2449 2450 <p> 2451 The <em>colon</em> syntax 2452 is used for defining <em>methods</em>, 2453 that is, functions that have an implicit extra parameter <code>self</code>. 2454 Thus, the statement 2455 2456 <pre> 2457 function t.a.b.c:f (<em>params</em>) <em>body</em> end 2458 </pre><p> 2459 is syntactic sugar for 2460 2461 <pre> 2462 t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end 2463 </pre> 2464 2465 2466 2467 2468 2469 2470 <h2>3.5 – <a name="3.5">Visibility Rules</a></h2> 2471 2472 <p> 2473 2474 Lua is a lexically scoped language. 2475 The scope of a local variable begins at the first statement after 2476 its declaration and lasts until the last non-void statement 2477 of the innermost block that includes the declaration. 2478 Consider the following example: 2479 2480 <pre> 2481 x = 10 -- global variable 2482 do -- new block 2483 local x = x -- new 'x', with value 10 2484 print(x) --> 10 2485 x = x+1 2486 do -- another block 2487 local x = x+1 -- another 'x' 2488 print(x) --> 12 2489 end 2490 print(x) --> 11 2491 end 2492 print(x) --> 10 (the global one) 2493 </pre> 2494 2495 <p> 2496 Notice that, in a declaration like <code>local x = x</code>, 2497 the new <code>x</code> being declared is not in scope yet, 2498 and so the second <code>x</code> refers to the outside variable. 2499 2500 2501 <p> 2502 Because of the lexical scoping rules, 2503 local variables can be freely accessed by functions 2504 defined inside their scope. 2505 A local variable used by an inner function is called 2506 an <em>upvalue</em>, or <em>external local variable</em>, 2507 inside the inner function. 2508 2509 2510 <p> 2511 Notice that each execution of a <b>local</b> statement 2512 defines new local variables. 2513 Consider the following example: 2514 2515 <pre> 2516 a = {} 2517 local x = 20 2518 for i=1,10 do 2519 local y = 0 2520 a[i] = function () y=y+1; return x+y end 2521 end 2522 </pre><p> 2523 The loop creates ten closures 2524 (that is, ten instances of the anonymous function). 2525 Each of these closures uses a different <code>y</code> variable, 2526 while all of them share the same <code>x</code>. 2527 2528 2529 2530 2531 2532 <h1>4 – <a name="4">The Application Program Interface</a></h1> 2533 2534 <p> 2535 2536 This section describes the C API for Lua, that is, 2537 the set of C functions available to the host program to communicate 2538 with Lua. 2539 All API functions and related types and constants 2540 are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. 2541 2542 2543 <p> 2544 Even when we use the term "function", 2545 any facility in the API may be provided as a macro instead. 2546 Except where stated otherwise, 2547 all such macros use each of their arguments exactly once 2548 (except for the first argument, which is always a Lua state), 2549 and so do not generate any hidden side-effects. 2550 2551 2552 <p> 2553 As in most C libraries, 2554 the Lua API functions do not check their arguments for validity or consistency. 2555 However, you can change this behavior by compiling Lua 2556 with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined. 2557 2558 2559 2560 <h2>4.1 – <a name="4.1">The Stack</a></h2> 2561 2562 <p> 2563 Lua uses a <em>virtual stack</em> to pass values to and from C. 2564 Each element in this stack represents a Lua value 2565 (<b>nil</b>, number, string, etc.). 2566 2567 2568 <p> 2569 Whenever Lua calls C, the called function gets a new stack, 2570 which is independent of previous stacks and of stacks of 2571 C functions that are still active. 2572 This stack initially contains any arguments to the C function 2573 and it is where the C function pushes its results 2574 to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 2575 2576 2577 <p> 2578 For convenience, 2579 most query operations in the API do not follow a strict stack discipline. 2580 Instead, they can refer to any element in the stack 2581 by using an <em>index</em>: 2582 A positive index represents an absolute stack position 2583 (starting at 1); 2584 a negative index represents an offset relative to the top of the stack. 2585 More specifically, if the stack has <em>n</em> elements, 2586 then index 1 represents the first element 2587 (that is, the element that was pushed onto the stack first) 2588 and 2589 index <em>n</em> represents the last element; 2590 index -1 also represents the last element 2591 (that is, the element at the top) 2592 and index <em>-n</em> represents the first element. 2593 2594 2595 2596 2597 2598 <h2>4.2 – <a name="4.2">Stack Size</a></h2> 2599 2600 <p> 2601 When you interact with the Lua API, 2602 you are responsible for ensuring consistency. 2603 In particular, 2604 <em>you are responsible for controlling stack overflow</em>. 2605 You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> 2606 to ensure that the stack has enough space for pushing new elements. 2607 2608 2609 <p> 2610 Whenever Lua calls C, 2611 it ensures that the stack has space for 2612 at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots. 2613 <code>LUA_MINSTACK</code> is defined as 20, 2614 so that usually you do not have to worry about stack space 2615 unless your code has loops pushing elements onto the stack. 2616 2617 2618 <p> 2619 When you call a Lua function 2620 without a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>), 2621 Lua ensures that the stack has enough space for all results, 2622 but it does not ensure any extra space. 2623 So, before pushing anything in the stack after such a call 2624 you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>. 2625 2626 2627 2628 2629 2630 <h2>4.3 – <a name="4.3">Valid and Acceptable Indices</a></h2> 2631 2632 <p> 2633 Any function in the API that receives stack indices 2634 works only with <em>valid indices</em> or <em>acceptable indices</em>. 2635 2636 2637 <p> 2638 A <em>valid index</em> is an index that refers to a 2639 real position within the stack, that is, 2640 its position lies between 1 and the stack top 2641 (<code>1 ≤ abs(index) ≤ top</code>). 2642 2643 Usually, functions that can modify the value at an index 2644 require valid indices. 2645 2646 2647 <p> 2648 Unless otherwise noted, 2649 any function that accepts valid indices also accepts <em>pseudo-indices</em>, 2650 which represent some Lua values that are accessible to C code 2651 but which are not in the stack. 2652 Pseudo-indices are used to access the registry 2653 and the upvalues of a C function (see <a href="#4.4">§4.4</a>). 2654 2655 2656 <p> 2657 Functions that do not need a specific stack position, 2658 but only a value in the stack (e.g., query functions), 2659 can be called with acceptable indices. 2660 An <em>acceptable index</em> can be any valid index, 2661 including the pseudo-indices, 2662 but it also can be any positive index after the stack top 2663 within the space allocated for the stack, 2664 that is, indices up to the stack size. 2665 (Note that 0 is never an acceptable index.) 2666 Except when noted otherwise, 2667 functions in the API work with acceptable indices. 2668 2669 2670 <p> 2671 Acceptable indices serve to avoid extra tests 2672 against the stack top when querying the stack. 2673 For instance, a C function can query its third argument 2674 without the need to first check whether there is a third argument, 2675 that is, without the need to check whether 3 is a valid index. 2676 2677 2678 <p> 2679 For functions that can be called with acceptable indices, 2680 any non-valid index is treated as if it 2681 contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>, 2682 which behaves like a nil value. 2683 2684 2685 2686 2687 2688 <h2>4.4 – <a name="4.4">C Closures</a></h2> 2689 2690 <p> 2691 When a C function is created, 2692 it is possible to associate some values with it, 2693 thus creating a <em>C closure</em> 2694 (see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>); 2695 these values are called <em>upvalues</em> and are 2696 accessible to the function whenever it is called. 2697 2698 2699 <p> 2700 Whenever a C function is called, 2701 its upvalues are located at specific pseudo-indices. 2702 These pseudo-indices are produced by the macro 2703 <a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>. 2704 The first value associated with a function is at position 2705 <code>lua_upvalueindex(1)</code>, and so on. 2706 Any access to <code>lua_upvalueindex(<em>n</em>)</code>, 2707 where <em>n</em> is greater than the number of upvalues of the 2708 current function (but not greater than 256), 2709 produces an acceptable but invalid index. 2710 2711 2712 2713 2714 2715 <h2>4.5 – <a name="4.5">Registry</a></h2> 2716 2717 <p> 2718 Lua provides a <em>registry</em>, 2719 a predefined table that can be used by any C code to 2720 store whatever Lua values it needs to store. 2721 The registry table is always located at pseudo-index 2722 <a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>, 2723 which is a valid index. 2724 Any C library can store data into this table, 2725 but it must take care to choose keys 2726 that are different from those used 2727 by other libraries, to avoid collisions. 2728 Typically, you should use as key a string containing your library name, 2729 or a light userdata with the address of a C object in your code, 2730 or any Lua object created by your code. 2731 As with variable names, 2732 string keys starting with an underscore followed by 2733 uppercase letters are reserved for Lua. 2734 2735 2736 <p> 2737 The integer keys in the registry are used 2738 by the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>) 2739 and by some predefined values. 2740 Therefore, integer keys must not be used for other purposes. 2741 2742 2743 <p> 2744 When you create a new Lua state, 2745 its registry comes with some predefined values. 2746 These predefined values are indexed with integer keys 2747 defined as constants in <code>lua.h</code>. 2748 The following constants are defined: 2749 2750 <ul> 2751 <li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has 2752 the main thread of the state. 2753 (The main thread is the one created together with the state.) 2754 </li> 2755 2756 <li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has 2757 the global environment. 2758 </li> 2759 </ul> 2760 2761 2762 2763 2764 <h2>4.6 – <a name="4.6">Error Handling in C</a></h2> 2765 2766 <p> 2767 Internally, Lua uses the C <code>longjmp</code> facility to handle errors. 2768 (Lua will use exceptions if you compile it as C++; 2769 search for <code>LUAI_THROW</code> in the source code for details.) 2770 When Lua faces any error 2771 (such as a memory allocation error, type errors, syntax errors, 2772 and runtime errors) 2773 it <em>raises</em> an error; 2774 that is, it does a long jump. 2775 A <em>protected environment</em> uses <code>setjmp</code> 2776 to set a recovery point; 2777 any error jumps to the most recent active recovery point. 2778 2779 2780 <p> 2781 If an error happens outside any protected environment, 2782 Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) 2783 and then calls <code>abort</code>, 2784 thus exiting the host application. 2785 Your panic function can avoid this exit by 2786 never returning 2787 (e.g., doing a long jump to your own recovery point outside Lua). 2788 2789 2790 <p> 2791 The panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>); 2792 in particular, the error message is at the top of the stack. 2793 However, there is no guarantee about stack space. 2794 To push anything on the stack, 2795 the panic function must first check the available space (see <a href="#4.2">§4.2</a>). 2796 2797 2798 <p> 2799 Most functions in the API can raise an error, 2800 for instance due to a memory allocation error. 2801 The documentation for each function indicates whether 2802 it can raise errors. 2803 2804 2805 <p> 2806 Inside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>. 2807 2808 2809 2810 2811 2812 <h2>4.7 – <a name="4.7">Handling Yields in C</a></h2> 2813 2814 <p> 2815 Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine. 2816 Therefore, if a C function <code>foo</code> calls an API function 2817 and this API function yields 2818 (directly or indirectly by calling another function that yields), 2819 Lua cannot return to <code>foo</code> any more, 2820 because the <code>longjmp</code> removes its frame from the C stack. 2821 2822 2823 <p> 2824 To avoid this kind of problem, 2825 Lua raises an error whenever it tries to yield across an API call, 2826 except for three functions: 2827 <a href="#lua_yieldk"><code>lua_yieldk</code></a>, <a href="#lua_callk"><code>lua_callk</code></a>, and <a href="#lua_pcallk"><code>lua_pcallk</code></a>. 2828 All those functions receive a <em>continuation function</em> 2829 (as a parameter named <code>k</code>) to continue execution after a yield. 2830 2831 2832 <p> 2833 We need to set some terminology to explain continuations. 2834 We have a C function called from Lua which we will call 2835 the <em>original function</em>. 2836 This original function then calls one of those three functions in the C API, 2837 which we will call the <em>callee function</em>, 2838 that then yields the current thread. 2839 (This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 2840 or when the callee function is either <a href="#lua_callk"><code>lua_callk</code></a> or <a href="#lua_pcallk"><code>lua_pcallk</code></a> 2841 and the function called by them yields.) 2842 2843 2844 <p> 2845 Suppose the running thread yields while executing the callee function. 2846 After the thread resumes, 2847 it eventually will finish running the callee function. 2848 However, 2849 the callee function cannot return to the original function, 2850 because its frame in the C stack was destroyed by the yield. 2851 Instead, Lua calls a <em>continuation function</em>, 2852 which was given as an argument to the callee function. 2853 As the name implies, 2854 the continuation function should continue the task 2855 of the original function. 2856 2857 2858 <p> 2859 As an illustration, consider the following function: 2860 2861 <pre> 2862 int original_function (lua_State *L) { 2863 ... /* code 1 */ 2864 status = lua_pcall(L, n, m, h); /* calls Lua */ 2865 ... /* code 2 */ 2866 } 2867 </pre><p> 2868 Now we want to allow 2869 the Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield. 2870 First, we can rewrite our function like here: 2871 2872 <pre> 2873 int k (lua_State *L, int status, lua_KContext ctx) { 2874 ... /* code 2 */ 2875 } 2876 2877 int original_function (lua_State *L) { 2878 ... /* code 1 */ 2879 return k(L, lua_pcall(L, n, m, h), ctx); 2880 } 2881 </pre><p> 2882 In the above code, 2883 the new function <code>k</code> is a 2884 <em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>), 2885 which should do all the work that the original function 2886 was doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>. 2887 Now, we must inform Lua that it must call <code>k</code> if the Lua code 2888 being executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way 2889 (errors or yielding), 2890 so we rewrite the code as here, 2891 replacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>: 2892 2893 <pre> 2894 int original_function (lua_State *L) { 2895 ... /* code 1 */ 2896 return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1); 2897 } 2898 </pre><p> 2899 Note the external, explicit call to the continuation: 2900 Lua will call the continuation only if needed, that is, 2901 in case of errors or resuming after a yield. 2902 If the called function returns normally without ever yielding, 2903 <a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally. 2904 (Of course, instead of calling the continuation in that case, 2905 you can do the equivalent work directly inside the original function.) 2906 2907 2908 <p> 2909 Besides the Lua state, 2910 the continuation function has two other parameters: 2911 the final status of the call plus the context value (<code>ctx</code>) that 2912 was passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>. 2913 (Lua does not use this context value; 2914 it only passes this value from the original function to the 2915 continuation function.) 2916 For <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 2917 the status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 2918 except that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield 2919 (instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>). 2920 For <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>, 2921 the status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation. 2922 (For these two functions, 2923 Lua will not call the continuation in case of errors, 2924 because they do not handle errors.) 2925 Similarly, when using <a href="#lua_callk"><code>lua_callk</code></a>, 2926 you should call the continuation function 2927 with <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status. 2928 (For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling 2929 directly the continuation function, 2930 because <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.) 2931 2932 2933 <p> 2934 Lua treats the continuation function as if it were the original function. 2935 The continuation function receives the same Lua stack 2936 from the original function, 2937 in the same state it would be if the callee function had returned. 2938 (For instance, 2939 after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are 2940 removed from the stack and replaced by the results from the call.) 2941 It also has the same upvalues. 2942 Whatever it returns is handled by Lua as if it were the return 2943 of the original function. 2944 2945 2946 2947 2948 2949 <h2>4.8 – <a name="4.8">Functions and Types</a></h2> 2950 2951 <p> 2952 Here we list all functions and types from the C API in 2953 alphabetical order. 2954 Each function has an indicator like this: 2955 <span class="apii">[-o, +p, <em>x</em>]</span> 2956 2957 2958 <p> 2959 The first field, <code>o</code>, 2960 is how many elements the function pops from the stack. 2961 The second field, <code>p</code>, 2962 is how many elements the function pushes onto the stack. 2963 (Any function always pushes its results after popping its arguments.) 2964 A field in the form <code>x|y</code> means the function can push (or pop) 2965 <code>x</code> or <code>y</code> elements, 2966 depending on the situation; 2967 an interrogation mark '<code>?</code>' means that 2968 we cannot know how many elements the function pops/pushes 2969 by looking only at its arguments 2970 (e.g., they may depend on what is on the stack). 2971 The third field, <code>x</code>, 2972 tells whether the function may raise errors: 2973 '<code>-</code>' means the function never raises any error; 2974 '<code>e</code>' means the function may raise errors; 2975 '<code>v</code>' means the function may raise an error on purpose. 2976 2977 2978 2979 <hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p> 2980 <span class="apii">[-0, +0, –]</span> 2981 <pre>int lua_absindex (lua_State *L, int idx);</pre> 2982 2983 <p> 2984 Converts the acceptable index <code>idx</code> into an absolute index 2985 (that is, one that does not depend on the stack top). 2986 2987 2988 2989 2990 2991 <hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> 2992 <pre>typedef void * (*lua_Alloc) (void *ud, 2993 void *ptr, 2994 size_t osize, 2995 size_t nsize);</pre> 2996 2997 <p> 2998 The type of the memory-allocation function used by Lua states. 2999 The allocator function must provide a 3000 functionality similar to <code>realloc</code>, 3001 but not exactly the same. 3002 Its arguments are 3003 <code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; 3004 <code>ptr</code>, a pointer to the block being allocated/reallocated/freed; 3005 <code>osize</code>, the original size of the block or some code about what 3006 is being allocated; 3007 and <code>nsize</code>, the new size of the block. 3008 3009 3010 <p> 3011 When <code>ptr</code> is not <code>NULL</code>, 3012 <code>osize</code> is the size of the block pointed by <code>ptr</code>, 3013 that is, the size given when it was allocated or reallocated. 3014 3015 3016 <p> 3017 When <code>ptr</code> is <code>NULL</code>, 3018 <code>osize</code> encodes the kind of object that Lua is allocating. 3019 <code>osize</code> is any of 3020 <a href="#pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, <a href="#pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, <a href="#pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, 3021 <a href="#pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, or <a href="#pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a> when (and only when) 3022 Lua is creating a new object of that type. 3023 When <code>osize</code> is some other value, 3024 Lua is allocating memory for something else. 3025 3026 3027 <p> 3028 Lua assumes the following behavior from the allocator function: 3029 3030 3031 <p> 3032 When <code>nsize</code> is zero, 3033 the allocator must behave like <code>free</code> 3034 and return <code>NULL</code>. 3035 3036 3037 <p> 3038 When <code>nsize</code> is not zero, 3039 the allocator must behave like <code>realloc</code>. 3040 The allocator returns <code>NULL</code> 3041 if and only if it cannot fulfill the request. 3042 Lua assumes that the allocator never fails when 3043 <code>osize >= nsize</code>. 3044 3045 3046 <p> 3047 Here is a simple implementation for the allocator function. 3048 It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. 3049 3050 <pre> 3051 static void *l_alloc (void *ud, void *ptr, size_t osize, 3052 size_t nsize) { 3053 (void)ud; (void)osize; /* not used */ 3054 if (nsize == 0) { 3055 free(ptr); 3056 return NULL; 3057 } 3058 else 3059 return realloc(ptr, nsize); 3060 } 3061 </pre><p> 3062 Note that Standard C ensures 3063 that <code>free(NULL)</code> has no effect and that 3064 <code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>. 3065 This code assumes that <code>realloc</code> does not fail when shrinking a block. 3066 (Although Standard C does not ensure this behavior, 3067 it seems to be a safe assumption.) 3068 3069 3070 3071 3072 3073 <hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p> 3074 <span class="apii">[-(2|1), +1, <em>e</em>]</span> 3075 <pre>void lua_arith (lua_State *L, int op);</pre> 3076 3077 <p> 3078 Performs an arithmetic or bitwise operation over the two values 3079 (or one, in the case of negations) 3080 at the top of the stack, 3081 with the value at the top being the second operand, 3082 pops these values, and pushes the result of the operation. 3083 The function follows the semantics of the corresponding Lua operator 3084 (that is, it may call metamethods). 3085 3086 3087 <p> 3088 The value of <code>op</code> must be one of the following constants: 3089 3090 <ul> 3091 3092 <li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li> 3093 <li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li> 3094 <li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li> 3095 <li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li> 3096 <li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li> 3097 <li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li> 3098 <li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li> 3099 <li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li> 3100 <li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise negation (<code>~</code>)</li> 3101 <li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise and (<code>&</code>)</li> 3102 <li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise or (<code>|</code>)</li> 3103 <li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive or (<code>~</code>)</li> 3104 <li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li> 3105 <li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li> 3106 3107 </ul> 3108 3109 3110 3111 3112 <hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> 3113 <span class="apii">[-0, +0, –]</span> 3114 <pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> 3115 3116 <p> 3117 Sets a new panic function and returns the old one (see <a href="#4.6">§4.6</a>). 3118 3119 3120 3121 3122 3123 <hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> 3124 <span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span> 3125 <pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> 3126 3127 <p> 3128 Calls a function. 3129 3130 3131 <p> 3132 To call a function you must use the following protocol: 3133 first, the function to be called is pushed onto the stack; 3134 then, the arguments to the function are pushed 3135 in direct order; 3136 that is, the first argument is pushed first. 3137 Finally you call <a href="#lua_call"><code>lua_call</code></a>; 3138 <code>nargs</code> is the number of arguments that you pushed onto the stack. 3139 All arguments and the function value are popped from the stack 3140 when the function is called. 3141 The function results are pushed onto the stack when the function returns. 3142 The number of results is adjusted to <code>nresults</code>, 3143 unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. 3144 In this case, all results from the function are pushed. 3145 Lua takes care that the returned values fit into the stack space. 3146 The function results are pushed onto the stack in direct order 3147 (the first result is pushed first), 3148 so that after the call the last result is on the top of the stack. 3149 3150 3151 <p> 3152 Any error inside the called function is propagated upwards 3153 (with a <code>longjmp</code>). 3154 3155 3156 <p> 3157 The following example shows how the host program can do the 3158 equivalent to this Lua code: 3159 3160 <pre> 3161 a = f("how", t.x, 14) 3162 </pre><p> 3163 Here it is in C: 3164 3165 <pre> 3166 lua_getglobal(L, "f"); /* function to be called */ 3167 lua_pushliteral(L, "how"); /* 1st argument */ 3168 lua_getglobal(L, "t"); /* table to be indexed */ 3169 lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 3170 lua_remove(L, -2); /* remove 't' from the stack */ 3171 lua_pushinteger(L, 14); /* 3rd argument */ 3172 lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ 3173 lua_setglobal(L, "a"); /* set global 'a' */ 3174 </pre><p> 3175 Note that the code above is <em>balanced</em>: 3176 at its end, the stack is back to its original configuration. 3177 This is considered good programming practice. 3178 3179 3180 3181 3182 3183 <hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p> 3184 <span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> 3185 <pre>void lua_callk (lua_State *L, 3186 int nargs, 3187 int nresults, 3188 lua_KContext ctx, 3189 lua_KFunction k);</pre> 3190 3191 <p> 3192 This function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>, 3193 but allows the called function to yield (see <a href="#4.7">§4.7</a>). 3194 3195 3196 3197 3198 3199 <hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> 3200 <pre>typedef int (*lua_CFunction) (lua_State *L);</pre> 3201 3202 <p> 3203 Type for C functions. 3204 3205 3206 <p> 3207 In order to communicate properly with Lua, 3208 a C function must use the following protocol, 3209 which defines the way parameters and results are passed: 3210 a C function receives its arguments from Lua in its stack 3211 in direct order (the first argument is pushed first). 3212 So, when the function starts, 3213 <code>lua_gettop(L)</code> returns the number of arguments received by the function. 3214 The first argument (if any) is at index 1 3215 and its last argument is at index <code>lua_gettop(L)</code>. 3216 To return values to Lua, a C function just pushes them onto the stack, 3217 in direct order (the first result is pushed first), 3218 and returns the number of results. 3219 Any other value in the stack below the results will be properly 3220 discarded by Lua. 3221 Like a Lua function, a C function called by Lua can also return 3222 many results. 3223 3224 3225 <p> 3226 As an example, the following function receives a variable number 3227 of numerical arguments and returns their average and their sum: 3228 3229 <pre> 3230 static int foo (lua_State *L) { 3231 int n = lua_gettop(L); /* number of arguments */ 3232 lua_Number sum = 0.0; 3233 int i; 3234 for (i = 1; i <= n; i++) { 3235 if (!lua_isnumber(L, i)) { 3236 lua_pushliteral(L, "incorrect argument"); 3237 lua_error(L); 3238 } 3239 sum += lua_tonumber(L, i); 3240 } 3241 lua_pushnumber(L, sum/n); /* first result */ 3242 lua_pushnumber(L, sum); /* second result */ 3243 return 2; /* number of results */ 3244 } 3245 </pre> 3246 3247 3248 3249 3250 <hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> 3251 <span class="apii">[-0, +0, –]</span> 3252 <pre>int lua_checkstack (lua_State *L, int n);</pre> 3253 3254 <p> 3255 Ensures that the stack has space for at least <code>n</code> extra slots. 3256 It returns false if it cannot fulfill the request, 3257 either because it would cause the stack 3258 to be larger than a fixed maximum size 3259 (typically at least several thousand elements) or 3260 because it cannot allocate memory for the extra space. 3261 This function never shrinks the stack; 3262 if the stack is already larger than the new size, 3263 it is left unchanged. 3264 3265 3266 3267 3268 3269 <hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> 3270 <span class="apii">[-0, +0, –]</span> 3271 <pre>void lua_close (lua_State *L);</pre> 3272 3273 <p> 3274 Destroys all objects in the given Lua state 3275 (calling the corresponding garbage-collection metamethods, if any) 3276 and frees all dynamic memory used by this state. 3277 On several platforms, you may not need to call this function, 3278 because all resources are naturally released when the host program ends. 3279 On the other hand, long-running programs that create multiple states, 3280 such as daemons or web servers, 3281 will probably need to close states as soon as they are not needed. 3282 3283 3284 3285 3286 3287 <hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p> 3288 <span class="apii">[-0, +0, <em>e</em>]</span> 3289 <pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre> 3290 3291 <p> 3292 Compares two Lua values. 3293 Returns 1 if the value at index <code>index1</code> satisfies <code>op</code> 3294 when compared with the value at index <code>index2</code>, 3295 following the semantics of the corresponding Lua operator 3296 (that is, it may call metamethods). 3297 Otherwise returns 0. 3298 Also returns 0 if any of the indices is not valid. 3299 3300 3301 <p> 3302 The value of <code>op</code> must be one of the following constants: 3303 3304 <ul> 3305 3306 <li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li> 3307 <li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li> 3308 <li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li> 3309 3310 </ul> 3311 3312 3313 3314 3315 <hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> 3316 <span class="apii">[-n, +1, <em>e</em>]</span> 3317 <pre>void lua_concat (lua_State *L, int n);</pre> 3318 3319 <p> 3320 Concatenates the <code>n</code> values at the top of the stack, 3321 pops them, and leaves the result at the top. 3322 If <code>n</code> is 1, the result is the single value on the stack 3323 (that is, the function does nothing); 3324 if <code>n</code> is 0, the result is the empty string. 3325 Concatenation is performed following the usual semantics of Lua 3326 (see <a href="#3.4.6">§3.4.6</a>). 3327 3328 3329 3330 3331 3332 <hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p> 3333 <span class="apii">[-0, +0, –]</span> 3334 <pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre> 3335 3336 <p> 3337 Copies the element at index <code>fromidx</code> 3338 into the valid index <code>toidx</code>, 3339 replacing the value at that position. 3340 Values at other positions are not affected. 3341 3342 3343 3344 3345 3346 <hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> 3347 <span class="apii">[-0, +1, <em>e</em>]</span> 3348 <pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> 3349 3350 <p> 3351 Creates a new empty table and pushes it onto the stack. 3352 Parameter <code>narr</code> is a hint for how many elements the table 3353 will have as a sequence; 3354 parameter <code>nrec</code> is a hint for how many other elements 3355 the table will have. 3356 Lua may use these hints to preallocate memory for the new table. 3357 This pre-allocation is useful for performance when you know in advance 3358 how many elements the table will have. 3359 Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. 3360 3361 3362 3363 3364 3365 <hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> 3366 <span class="apii">[-0, +0, <em>e</em>]</span> 3367 <pre>int lua_dump (lua_State *L, 3368 lua_Writer writer, 3369 void *data, 3370 int strip);</pre> 3371 3372 <p> 3373 Dumps a function as a binary chunk. 3374 Receives a Lua function on the top of the stack 3375 and produces a binary chunk that, 3376 if loaded again, 3377 results in a function equivalent to the one dumped. 3378 As it produces parts of the chunk, 3379 <a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>) 3380 with the given <code>data</code> 3381 to write them. 3382 3383 3384 <p> 3385 If <code>strip</code> is true, 3386 the binary representation is created without debug information 3387 about the function. 3388 3389 3390 <p> 3391 The value returned is the error code returned by the last 3392 call to the writer; 3393 0 means no errors. 3394 3395 3396 <p> 3397 This function does not pop the Lua function from the stack. 3398 3399 3400 3401 3402 3403 <hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> 3404 <span class="apii">[-1, +0, <em>v</em>]</span> 3405 <pre>int lua_error (lua_State *L);</pre> 3406 3407 <p> 3408 Generates a Lua error, 3409 using the value at the top of the stack as the error object. 3410 This function does a long jump, 3411 and therefore never returns 3412 (see <a href="#luaL_error"><code>luaL_error</code></a>). 3413 3414 3415 3416 3417 3418 <hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> 3419 <span class="apii">[-0, +0, <em>e</em>]</span> 3420 <pre>int lua_gc (lua_State *L, int what, int data);</pre> 3421 3422 <p> 3423 Controls the garbage collector. 3424 3425 3426 <p> 3427 This function performs several tasks, 3428 according to the value of the parameter <code>what</code>: 3429 3430 <ul> 3431 3432 <li><b><code>LUA_GCSTOP</code>: </b> 3433 stops the garbage collector. 3434 </li> 3435 3436 <li><b><code>LUA_GCRESTART</code>: </b> 3437 restarts the garbage collector. 3438 </li> 3439 3440 <li><b><code>LUA_GCCOLLECT</code>: </b> 3441 performs a full garbage-collection cycle. 3442 </li> 3443 3444 <li><b><code>LUA_GCCOUNT</code>: </b> 3445 returns the current amount of memory (in Kbytes) in use by Lua. 3446 </li> 3447 3448 <li><b><code>LUA_GCCOUNTB</code>: </b> 3449 returns the remainder of dividing the current amount of bytes of 3450 memory in use by Lua by 1024. 3451 </li> 3452 3453 <li><b><code>LUA_GCSTEP</code>: </b> 3454 performs an incremental step of garbage collection. 3455 </li> 3456 3457 <li><b><code>LUA_GCSETPAUSE</code>: </b> 3458 sets <code>data</code> as the new value 3459 for the <em>pause</em> of the collector (see <a href="#2.5">§2.5</a>) 3460 and returns the previous value of the pause. 3461 </li> 3462 3463 <li><b><code>LUA_GCSETSTEPMUL</code>: </b> 3464 sets <code>data</code> as the new value for the <em>step multiplier</em> of 3465 the collector (see <a href="#2.5">§2.5</a>) 3466 and returns the previous value of the step multiplier. 3467 </li> 3468 3469 <li><b><code>LUA_GCISRUNNING</code>: </b> 3470 returns a boolean that tells whether the collector is running 3471 (i.e., not stopped). 3472 </li> 3473 3474 </ul> 3475 3476 <p> 3477 For more details about these options, 3478 see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>. 3479 3480 3481 3482 3483 3484 <hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> 3485 <span class="apii">[-0, +0, –]</span> 3486 <pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> 3487 3488 <p> 3489 Returns the memory-allocation function of a given state. 3490 If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the 3491 opaque pointer given when the memory-allocator function was set. 3492 3493 3494 3495 3496 3497 <hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> 3498 <span class="apii">[-0, +1, <em>e</em>]</span> 3499 <pre>int lua_getfield (lua_State *L, int index, const char *k);</pre> 3500 3501 <p> 3502 Pushes onto the stack the value <code>t[k]</code>, 3503 where <code>t</code> is the value at the given index. 3504 As in Lua, this function may trigger a metamethod 3505 for the "index" event (see <a href="#2.4">§2.4</a>). 3506 3507 3508 <p> 3509 Returns the type of the pushed value. 3510 3511 3512 3513 3514 3515 <hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p> 3516 <span class="apii">[-0, +0, –]</span> 3517 <pre>void *lua_getextraspace (lua_State *L);</pre> 3518 3519 <p> 3520 Returns a pointer to a raw memory area associated with the 3521 given Lua state. 3522 The application can use this area for any purpose; 3523 Lua does not use it for anything. 3524 3525 3526 <p> 3527 Each new thread has this area initialized with a copy 3528 of the area of the main thread. 3529 3530 3531 <p> 3532 By default, this area has the size of a pointer to void, 3533 but you can recompile Lua with a different size for this area. 3534 (See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.) 3535 3536 3537 3538 3539 3540 <hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> 3541 <span class="apii">[-0, +1, <em>e</em>]</span> 3542 <pre>int lua_getglobal (lua_State *L, const char *name);</pre> 3543 3544 <p> 3545 Pushes onto the stack the value of the global <code>name</code>. 3546 Returns the type of that value. 3547 3548 3549 3550 3551 3552 <hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p> 3553 <span class="apii">[-0, +1, <em>e</em>]</span> 3554 <pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre> 3555 3556 <p> 3557 Pushes onto the stack the value <code>t[i]</code>, 3558 where <code>t</code> is the value at the given index. 3559 As in Lua, this function may trigger a metamethod 3560 for the "index" event (see <a href="#2.4">§2.4</a>). 3561 3562 3563 <p> 3564 Returns the type of the pushed value. 3565 3566 3567 3568 3569 3570 <hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> 3571 <span class="apii">[-0, +(0|1), –]</span> 3572 <pre>int lua_getmetatable (lua_State *L, int index);</pre> 3573 3574 <p> 3575 If the value at the given index has a metatable, 3576 the function pushes that metatable onto the stack and returns 1. 3577 Otherwise, 3578 the function returns 0 and pushes nothing on the stack. 3579 3580 3581 3582 3583 3584 <hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> 3585 <span class="apii">[-1, +1, <em>e</em>]</span> 3586 <pre>int lua_gettable (lua_State *L, int index);</pre> 3587 3588 <p> 3589 Pushes onto the stack the value <code>t[k]</code>, 3590 where <code>t</code> is the value at the given index 3591 and <code>k</code> is the value at the top of the stack. 3592 3593 3594 <p> 3595 This function pops the key from the stack, 3596 pushing the resulting value in its place. 3597 As in Lua, this function may trigger a metamethod 3598 for the "index" event (see <a href="#2.4">§2.4</a>). 3599 3600 3601 <p> 3602 Returns the type of the pushed value. 3603 3604 3605 3606 3607 3608 <hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> 3609 <span class="apii">[-0, +0, –]</span> 3610 <pre>int lua_gettop (lua_State *L);</pre> 3611 3612 <p> 3613 Returns the index of the top element in the stack. 3614 Because indices start at 1, 3615 this result is equal to the number of elements in the stack; 3616 in particular, 0 means an empty stack. 3617 3618 3619 3620 3621 3622 <hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p> 3623 <span class="apii">[-0, +1, –]</span> 3624 <pre>int lua_getuservalue (lua_State *L, int index);</pre> 3625 3626 <p> 3627 Pushes onto the stack the Lua value associated with the userdata 3628 at the given index. 3629 3630 3631 <p> 3632 Returns the type of the pushed value. 3633 3634 3635 3636 3637 3638 <hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> 3639 <span class="apii">[-1, +1, –]</span> 3640 <pre>void lua_insert (lua_State *L, int index);</pre> 3641 3642 <p> 3643 Moves the top element into the given valid index, 3644 shifting up the elements above this index to open space. 3645 This function cannot be called with a pseudo-index, 3646 because a pseudo-index is not an actual stack position. 3647 3648 3649 3650 3651 3652 <hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> 3653 <pre>typedef ... lua_Integer;</pre> 3654 3655 <p> 3656 The type of integers in Lua. 3657 3658 3659 <p> 3660 By default this type is <code>long long</code>, 3661 (usually a 64-bit two-complement integer), 3662 but that can be changed to <code>long</code> or <code>int</code> 3663 (usually a 32-bit two-complement integer). 3664 (See <code>LUA_INT</code> in <code>luaconf.h</code>.) 3665 3666 3667 <p> 3668 Lua also defines the constants 3669 <a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>, 3670 with the minimum and the maximum values that fit in this type. 3671 3672 3673 3674 3675 3676 <hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> 3677 <span class="apii">[-0, +0, –]</span> 3678 <pre>int lua_isboolean (lua_State *L, int index);</pre> 3679 3680 <p> 3681 Returns 1 if the value at the given index is a boolean, 3682 and 0 otherwise. 3683 3684 3685 3686 3687 3688 <hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> 3689 <span class="apii">[-0, +0, –]</span> 3690 <pre>int lua_iscfunction (lua_State *L, int index);</pre> 3691 3692 <p> 3693 Returns 1 if the value at the given index is a C function, 3694 and 0 otherwise. 3695 3696 3697 3698 3699 3700 <hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> 3701 <span class="apii">[-0, +0, –]</span> 3702 <pre>int lua_isfunction (lua_State *L, int index);</pre> 3703 3704 <p> 3705 Returns 1 if the value at the given index is a function 3706 (either C or Lua), and 0 otherwise. 3707 3708 3709 3710 3711 3712 <hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p> 3713 <span class="apii">[-0, +0, –]</span> 3714 <pre>int lua_isinteger (lua_State *L, int index);</pre> 3715 3716 <p> 3717 Returns 1 if the value at the given index is an integer 3718 (that is, the value is a number and is represented as an integer), 3719 and 0 otherwise. 3720 3721 3722 3723 3724 3725 <hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> 3726 <span class="apii">[-0, +0, –]</span> 3727 <pre>int lua_islightuserdata (lua_State *L, int index);</pre> 3728 3729 <p> 3730 Returns 1 if the value at the given index is a light userdata, 3731 and 0 otherwise. 3732 3733 3734 3735 3736 3737 <hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> 3738 <span class="apii">[-0, +0, –]</span> 3739 <pre>int lua_isnil (lua_State *L, int index);</pre> 3740 3741 <p> 3742 Returns 1 if the value at the given index is <b>nil</b>, 3743 and 0 otherwise. 3744 3745 3746 3747 3748 3749 <hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> 3750 <span class="apii">[-0, +0, –]</span> 3751 <pre>int lua_isnone (lua_State *L, int index);</pre> 3752 3753 <p> 3754 Returns 1 if the given index is not valid, 3755 and 0 otherwise. 3756 3757 3758 3759 3760 3761 <hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> 3762 <span class="apii">[-0, +0, –]</span> 3763 <pre>int lua_isnoneornil (lua_State *L, int index);</pre> 3764 3765 <p> 3766 Returns 1 if the given index is not valid 3767 or if the value at this index is <b>nil</b>, 3768 and 0 otherwise. 3769 3770 3771 3772 3773 3774 <hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> 3775 <span class="apii">[-0, +0, –]</span> 3776 <pre>int lua_isnumber (lua_State *L, int index);</pre> 3777 3778 <p> 3779 Returns 1 if the value at the given index is a number 3780 or a string convertible to a number, 3781 and 0 otherwise. 3782 3783 3784 3785 3786 3787 <hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> 3788 <span class="apii">[-0, +0, –]</span> 3789 <pre>int lua_isstring (lua_State *L, int index);</pre> 3790 3791 <p> 3792 Returns 1 if the value at the given index is a string 3793 or a number (which is always convertible to a string), 3794 and 0 otherwise. 3795 3796 3797 3798 3799 3800 <hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> 3801 <span class="apii">[-0, +0, –]</span> 3802 <pre>int lua_istable (lua_State *L, int index);</pre> 3803 3804 <p> 3805 Returns 1 if the value at the given index is a table, 3806 and 0 otherwise. 3807 3808 3809 3810 3811 3812 <hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> 3813 <span class="apii">[-0, +0, –]</span> 3814 <pre>int lua_isthread (lua_State *L, int index);</pre> 3815 3816 <p> 3817 Returns 1 if the value at the given index is a thread, 3818 and 0 otherwise. 3819 3820 3821 3822 3823 3824 <hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> 3825 <span class="apii">[-0, +0, –]</span> 3826 <pre>int lua_isuserdata (lua_State *L, int index);</pre> 3827 3828 <p> 3829 Returns 1 if the value at the given index is a userdata 3830 (either full or light), and 0 otherwise. 3831 3832 3833 3834 3835 3836 <hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p> 3837 <span class="apii">[-0, +0, –]</span> 3838 <pre>int lua_isyieldable (lua_State *L);</pre> 3839 3840 <p> 3841 Returns 1 if the given coroutine can yield, 3842 and 0 otherwise. 3843 3844 3845 3846 3847 3848 <hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3> 3849 <pre>typedef ... lua_KContext;</pre> 3850 3851 <p> 3852 The type for continuation-function contexts. 3853 It must be a numerical type. 3854 This type is defined as <code>intptr_t</code> 3855 when <code>intptr_t</code> is available, 3856 so that it can store pointers too. 3857 Otherwise, it is defined as <code>ptrdiff_t</code>. 3858 3859 3860 3861 3862 3863 <hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3> 3864 <pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre> 3865 3866 <p> 3867 Type for continuation functions (see <a href="#4.7">§4.7</a>). 3868 3869 3870 3871 3872 3873 <hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p> 3874 <span class="apii">[-0, +1, <em>e</em>]</span> 3875 <pre>void lua_len (lua_State *L, int index);</pre> 3876 3877 <p> 3878 Returns the length of the value at the given index. 3879 It is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>) and 3880 may trigger a metamethod for the "length" event (see <a href="#2.4">§2.4</a>). 3881 The result is pushed on the stack. 3882 3883 3884 3885 3886 3887 <hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> 3888 <span class="apii">[-0, +1, –]</span> 3889 <pre>int lua_load (lua_State *L, 3890 lua_Reader reader, 3891 void *data, 3892 const char *chunkname, 3893 const char *mode);</pre> 3894 3895 <p> 3896 Loads a Lua chunk without running it. 3897 If there are no errors, 3898 <code>lua_load</code> pushes the compiled chunk as a Lua 3899 function on top of the stack. 3900 Otherwise, it pushes an error message. 3901 3902 3903 <p> 3904 The return values of <code>lua_load</code> are: 3905 3906 <ul> 3907 3908 <li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li> 3909 3910 <li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> 3911 syntax error during precompilation;</li> 3912 3913 <li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 3914 memory allocation error;</li> 3915 3916 <li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> 3917 error while running a <code>__gc</code> metamethod. 3918 (This error has no relation with the chunk being loaded. 3919 It is generated by the garbage collector.) 3920 </li> 3921 3922 </ul> 3923 3924 <p> 3925 The <code>lua_load</code> function uses a user-supplied <code>reader</code> function 3926 to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). 3927 The <code>data</code> argument is an opaque value passed to the reader function. 3928 3929 3930 <p> 3931 The <code>chunkname</code> argument gives a name to the chunk, 3932 which is used for error messages and in debug information (see <a href="#4.9">§4.9</a>). 3933 3934 3935 <p> 3936 <code>lua_load</code> automatically detects whether the chunk is text or binary 3937 and loads it accordingly (see program <code>luac</code>). 3938 The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>, 3939 with the addition that 3940 a <code>NULL</code> value is equivalent to the string "<code>bt</code>". 3941 3942 3943 <p> 3944 <code>lua_load</code> uses the stack internally, 3945 so the reader function must always leave the stack 3946 unmodified when returning. 3947 3948 3949 <p> 3950 If the resulting function has upvalues, 3951 its first upvalue is set to the value of the global environment 3952 stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">§4.5</a>). 3953 When loading main chunks, 3954 this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 3955 Other upvalues are initialized with <b>nil</b>. 3956 3957 3958 3959 3960 3961 <hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> 3962 <span class="apii">[-0, +0, –]</span> 3963 <pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> 3964 3965 <p> 3966 Creates a new thread running in a new, independent state. 3967 Returns <code>NULL</code> if it cannot create the thread or the state 3968 (due to lack of memory). 3969 The argument <code>f</code> is the allocator function; 3970 Lua does all memory allocation for this state through this function. 3971 The second argument, <code>ud</code>, is an opaque pointer that Lua 3972 passes to the allocator in every call. 3973 3974 3975 3976 3977 3978 <hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> 3979 <span class="apii">[-0, +1, <em>e</em>]</span> 3980 <pre>void lua_newtable (lua_State *L);</pre> 3981 3982 <p> 3983 Creates a new empty table and pushes it onto the stack. 3984 It is equivalent to <code>lua_createtable(L, 0, 0)</code>. 3985 3986 3987 3988 3989 3990 <hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> 3991 <span class="apii">[-0, +1, <em>e</em>]</span> 3992 <pre>lua_State *lua_newthread (lua_State *L);</pre> 3993 3994 <p> 3995 Creates a new thread, pushes it on the stack, 3996 and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. 3997 The new thread returned by this function shares with the original thread 3998 its global environment, 3999 but has an independent execution stack. 4000 4001 4002 <p> 4003 There is no explicit function to close or to destroy a thread. 4004 Threads are subject to garbage collection, 4005 like any Lua object. 4006 4007 4008 4009 4010 4011 <hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p> 4012 <span class="apii">[-0, +1, <em>e</em>]</span> 4013 <pre>void *lua_newuserdata (lua_State *L, size_t size);</pre> 4014 4015 <p> 4016 This function allocates a new block of memory with the given size, 4017 pushes onto the stack a new full userdata with the block address, 4018 and returns this address. 4019 The host program can freely use this memory. 4020 4021 4022 4023 4024 4025 <hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> 4026 <span class="apii">[-1, +(2|0), <em>e</em>]</span> 4027 <pre>int lua_next (lua_State *L, int index);</pre> 4028 4029 <p> 4030 Pops a key from the stack, 4031 and pushes a key–value pair from the table at the given index 4032 (the "next" pair after the given key). 4033 If there are no more elements in the table, 4034 then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). 4035 4036 4037 <p> 4038 A typical traversal looks like this: 4039 4040 <pre> 4041 /* table is in the stack at index 't' */ 4042 lua_pushnil(L); /* first key */ 4043 while (lua_next(L, t) != 0) { 4044 /* uses 'key' (at index -2) and 'value' (at index -1) */ 4045 printf("%s - %s\n", 4046 lua_typename(L, lua_type(L, -2)), 4047 lua_typename(L, lua_type(L, -1))); 4048 /* removes 'value'; keeps 'key' for next iteration */ 4049 lua_pop(L, 1); 4050 } 4051 </pre> 4052 4053 <p> 4054 While traversing a table, 4055 do not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, 4056 unless you know that the key is actually a string. 4057 Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change 4058 the value at the given index; 4059 this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. 4060 4061 4062 <p> 4063 See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 4064 the table during its traversal. 4065 4066 4067 4068 4069 4070 <hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> 4071 <pre>typedef double lua_Number;</pre> 4072 4073 <p> 4074 The type of floats in Lua. 4075 4076 4077 <p> 4078 By default this type is double, 4079 but that can be changed to a single float. 4080 (See <code>LUA_REAL</code> in <code>luaconf.h</code>.) 4081 4082 4083 4084 4085 4086 <hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3> 4087 <pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre> 4088 4089 <p> 4090 Converts a Lua float to a Lua integer. 4091 This macro assumes that <code>n</code> has an integral value. 4092 If that value is within the range of Lua integers, 4093 it is converted to an integer and assigned to <code>*p</code>. 4094 The macro results in a boolean indicating whether the 4095 conversion was successful. 4096 (Note that this range test can be tricky to do 4097 correctly without this macro, 4098 due to roundings.) 4099 4100 4101 <p> 4102 This macro may evaluate its arguments more than once. 4103 4104 4105 4106 4107 4108 <hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> 4109 <span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4110 <pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre> 4111 4112 <p> 4113 Calls a function in protected mode. 4114 4115 4116 <p> 4117 Both <code>nargs</code> and <code>nresults</code> have the same meaning as 4118 in <a href="#lua_call"><code>lua_call</code></a>. 4119 If there are no errors during the call, 4120 <a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. 4121 However, if there is any error, 4122 <a href="#lua_pcall"><code>lua_pcall</code></a> catches it, 4123 pushes a single value on the stack (the error message), 4124 and returns an error code. 4125 Like <a href="#lua_call"><code>lua_call</code></a>, 4126 <a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function 4127 and its arguments from the stack. 4128 4129 4130 <p> 4131 If <code>msgh</code> is 0, 4132 then the error message returned on the stack 4133 is exactly the original error message. 4134 Otherwise, <code>msgh</code> is the stack index of a 4135 <em>message handler</em>. 4136 (In the current implementation, this index cannot be a pseudo-index.) 4137 In case of runtime errors, 4138 this function will be called with the error message 4139 and its return value will be the message 4140 returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. 4141 4142 4143 <p> 4144 Typically, the message handler is used to add more debug 4145 information to the error message, such as a stack traceback. 4146 Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, 4147 since by then the stack has unwound. 4148 4149 4150 <p> 4151 The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following constants 4152 (defined in <code>lua.h</code>): 4153 4154 <ul> 4155 4156 <li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> 4157 success.</li> 4158 4159 <li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b> 4160 a runtime error. 4161 </li> 4162 4163 <li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 4164 memory allocation error. 4165 For such errors, Lua does not call the message handler. 4166 </li> 4167 4168 <li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b> 4169 error while running the message handler. 4170 </li> 4171 4172 <li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> 4173 error while running a <code>__gc</code> metamethod. 4174 (This error typically has no relation with the function being called.) 4175 </li> 4176 4177 </ul> 4178 4179 4180 4181 4182 <hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p> 4183 <span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4184 <pre>int lua_pcallk (lua_State *L, 4185 int nargs, 4186 int nresults, 4187 int msgh, 4188 lua_KContext ctx, 4189 lua_KFunction k);</pre> 4190 4191 <p> 4192 This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>, 4193 but allows the called function to yield (see <a href="#4.7">§4.7</a>). 4194 4195 4196 4197 4198 4199 <hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> 4200 <span class="apii">[-n, +0, –]</span> 4201 <pre>void lua_pop (lua_State *L, int n);</pre> 4202 4203 <p> 4204 Pops <code>n</code> elements from the stack. 4205 4206 4207 4208 4209 4210 <hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> 4211 <span class="apii">[-0, +1, –]</span> 4212 <pre>void lua_pushboolean (lua_State *L, int b);</pre> 4213 4214 <p> 4215 Pushes a boolean value with value <code>b</code> onto the stack. 4216 4217 4218 4219 4220 4221 <hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> 4222 <span class="apii">[-n, +1, <em>e</em>]</span> 4223 <pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> 4224 4225 <p> 4226 Pushes a new C closure onto the stack. 4227 4228 4229 <p> 4230 When a C function is created, 4231 it is possible to associate some values with it, 4232 thus creating a C closure (see <a href="#4.4">§4.4</a>); 4233 these values are then accessible to the function whenever it is called. 4234 To associate values with a C function, 4235 first these values must be pushed onto the stack 4236 (when there are multiple values, the first value is pushed first). 4237 Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 4238 is called to create and push the C function onto the stack, 4239 with the argument <code>n</code> telling how many values will be 4240 associated with the function. 4241 <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. 4242 4243 4244 <p> 4245 The maximum value for <code>n</code> is 255. 4246 4247 4248 <p> 4249 When <code>n</code> is zero, 4250 this function creates a <em>light C function</em>, 4251 which is just a pointer to the C function. 4252 In that case, it never raises a memory error. 4253 4254 4255 4256 4257 4258 <hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> 4259 <span class="apii">[-0, +1, –]</span> 4260 <pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> 4261 4262 <p> 4263 Pushes a C function onto the stack. 4264 This function receives a pointer to a C function 4265 and pushes onto the stack a Lua value of type <code>function</code> that, 4266 when called, invokes the corresponding C function. 4267 4268 4269 <p> 4270 Any function to be registered in Lua must 4271 follow the correct protocol to receive its parameters 4272 and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 4273 4274 4275 <p> 4276 <code>lua_pushcfunction</code> is defined as a macro: 4277 4278 <pre> 4279 #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0) 4280 </pre><p> 4281 Note that <code>f</code> is used twice. 4282 4283 4284 4285 4286 4287 <hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> 4288 <span class="apii">[-0, +1, <em>e</em>]</span> 4289 <pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> 4290 4291 <p> 4292 Pushes onto the stack a formatted string 4293 and returns a pointer to this string. 4294 It is similar to the ISO C function <code>sprintf</code>, 4295 but has some important differences: 4296 4297 <ul> 4298 4299 <li> 4300 You do not have to allocate space for the result: 4301 the result is a Lua string and Lua takes care of memory allocation 4302 (and deallocation, through garbage collection). 4303 </li> 4304 4305 <li> 4306 The conversion specifiers are quite restricted. 4307 There are no flags, widths, or precisions. 4308 The conversion specifiers can only be 4309 '<code>%%</code>' (inserts the character '<code>%</code>'), 4310 '<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), 4311 '<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), 4312 '<code>%L</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>), 4313 '<code>%p</code>' (inserts a pointer as a hexadecimal numeral), 4314 '<code>%d</code>' (inserts an <code>int</code>), 4315 '<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and 4316 '<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence). 4317 </li> 4318 4319 </ul> 4320 4321 4322 4323 4324 <hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p> 4325 <span class="apii">[-0, +1, –]</span> 4326 <pre>void lua_pushglobaltable (lua_State *L);</pre> 4327 4328 <p> 4329 Pushes the global environment onto the stack. 4330 4331 4332 4333 4334 4335 <hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> 4336 <span class="apii">[-0, +1, –]</span> 4337 <pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> 4338 4339 <p> 4340 Pushes an integer with value <code>n</code> onto the stack. 4341 4342 4343 4344 4345 4346 <hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> 4347 <span class="apii">[-0, +1, –]</span> 4348 <pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> 4349 4350 <p> 4351 Pushes a light userdata onto the stack. 4352 4353 4354 <p> 4355 Userdata represent C values in Lua. 4356 A <em>light userdata</em> represents a pointer, a <code>void*</code>. 4357 It is a value (like a number): 4358 you do not create it, it has no individual metatable, 4359 and it is not collected (as it was never created). 4360 A light userdata is equal to "any" 4361 light userdata with the same C address. 4362 4363 4364 4365 4366 4367 <hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> 4368 <span class="apii">[-0, +1, <em>e</em>]</span> 4369 <pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre> 4370 4371 <p> 4372 This macro is equivalent to <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>, 4373 but can be used only when <code>s</code> is a literal string. 4374 It automatically provides the string length. 4375 4376 4377 4378 4379 4380 <hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> 4381 <span class="apii">[-0, +1, <em>e</em>]</span> 4382 <pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> 4383 4384 <p> 4385 Pushes the string pointed to by <code>s</code> with size <code>len</code> 4386 onto the stack. 4387 Lua makes (or reuses) an internal copy of the given string, 4388 so the memory at <code>s</code> can be freed or reused immediately after 4389 the function returns. 4390 The string can contain any binary data, 4391 including embedded zeros. 4392 4393 4394 <p> 4395 Returns a pointer to the internal copy of the string. 4396 4397 4398 4399 4400 4401 <hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> 4402 <span class="apii">[-0, +1, –]</span> 4403 <pre>void lua_pushnil (lua_State *L);</pre> 4404 4405 <p> 4406 Pushes a nil value onto the stack. 4407 4408 4409 4410 4411 4412 <hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> 4413 <span class="apii">[-0, +1, –]</span> 4414 <pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> 4415 4416 <p> 4417 Pushes a float with value <code>n</code> onto the stack. 4418 4419 4420 4421 4422 4423 <hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> 4424 <span class="apii">[-0, +1, <em>e</em>]</span> 4425 <pre>const char *lua_pushstring (lua_State *L, const char *s);</pre> 4426 4427 <p> 4428 Pushes the zero-terminated string pointed to by <code>s</code> 4429 onto the stack. 4430 Lua makes (or reuses) an internal copy of the given string, 4431 so the memory at <code>s</code> can be freed or reused immediately after 4432 the function returns. 4433 4434 4435 <p> 4436 Returns a pointer to the internal copy of the string. 4437 4438 4439 <p> 4440 If <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>. 4441 4442 4443 4444 4445 4446 <hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> 4447 <span class="apii">[-0, +1, –]</span> 4448 <pre>int lua_pushthread (lua_State *L);</pre> 4449 4450 <p> 4451 Pushes the thread represented by <code>L</code> onto the stack. 4452 Returns 1 if this thread is the main thread of its state. 4453 4454 4455 4456 4457 4458 <hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> 4459 <span class="apii">[-0, +1, –]</span> 4460 <pre>void lua_pushvalue (lua_State *L, int index);</pre> 4461 4462 <p> 4463 Pushes a copy of the element at the given index 4464 onto the stack. 4465 4466 4467 4468 4469 4470 <hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> 4471 <span class="apii">[-0, +1, <em>e</em>]</span> 4472 <pre>const char *lua_pushvfstring (lua_State *L, 4473 const char *fmt, 4474 va_list argp);</pre> 4475 4476 <p> 4477 Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> 4478 instead of a variable number of arguments. 4479 4480 4481 4482 4483 4484 <hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> 4485 <span class="apii">[-0, +0, –]</span> 4486 <pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> 4487 4488 <p> 4489 Returns 1 if the two values in indices <code>index1</code> and 4490 <code>index2</code> are primitively equal 4491 (that is, without calling metamethods). 4492 Otherwise returns 0. 4493 Also returns 0 if any of the indices are not valid. 4494 4495 4496 4497 4498 4499 <hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> 4500 <span class="apii">[-1, +1, –]</span> 4501 <pre>int lua_rawget (lua_State *L, int index);</pre> 4502 4503 <p> 4504 Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access 4505 (i.e., without metamethods). 4506 4507 4508 4509 4510 4511 <hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> 4512 <span class="apii">[-0, +1, –]</span> 4513 <pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre> 4514 4515 <p> 4516 Pushes onto the stack the value <code>t[n]</code>, 4517 where <code>t</code> is the table at the given index. 4518 The access is raw; 4519 that is, it does not invoke metamethods. 4520 4521 4522 <p> 4523 Returns the type of the pushed value. 4524 4525 4526 4527 4528 4529 <hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p> 4530 <span class="apii">[-0, +1, –]</span> 4531 <pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre> 4532 4533 <p> 4534 Pushes onto the stack the value <code>t[k]</code>, 4535 where <code>t</code> is the table at the given index and 4536 <code>k</code> is the pointer <code>p</code> represented as a light userdata. 4537 The access is raw; 4538 that is, it does not invoke metamethods. 4539 4540 4541 <p> 4542 Returns the type of the pushed value. 4543 4544 4545 4546 4547 4548 <hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p> 4549 <span class="apii">[-0, +0, –]</span> 4550 <pre>size_t lua_rawlen (lua_State *L, int index);</pre> 4551 4552 <p> 4553 Returns the raw "length" of the value at the given index: 4554 for strings, this is the string length; 4555 for tables, this is the result of the length operator ('<code>#</code>') 4556 with no metamethods; 4557 for userdata, this is the size of the block of memory allocated 4558 for the userdata; 4559 for other values, it is 0. 4560 4561 4562 4563 4564 4565 <hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> 4566 <span class="apii">[-2, +0, <em>e</em>]</span> 4567 <pre>void lua_rawset (lua_State *L, int index);</pre> 4568 4569 <p> 4570 Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment 4571 (i.e., without metamethods). 4572 4573 4574 4575 4576 4577 <hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> 4578 <span class="apii">[-1, +0, <em>e</em>]</span> 4579 <pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre> 4580 4581 <p> 4582 Does the equivalent of <code>t[i] = v</code>, 4583 where <code>t</code> is the table at the given index 4584 and <code>v</code> is the value at the top of the stack. 4585 4586 4587 <p> 4588 This function pops the value from the stack. 4589 The assignment is raw; 4590 that is, it does not invoke metamethods. 4591 4592 4593 4594 4595 4596 <hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p> 4597 <span class="apii">[-1, +0, <em>e</em>]</span> 4598 <pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre> 4599 4600 <p> 4601 Does the equivalent of <code>t[k] = v</code>, 4602 where <code>t</code> is the table at the given index, 4603 <code>k</code> is the pointer <code>p</code> represented as a light userdata, 4604 and <code>v</code> is the value at the top of the stack. 4605 4606 4607 <p> 4608 This function pops the value from the stack. 4609 The assignment is raw; 4610 that is, it does not invoke metamethods. 4611 4612 4613 4614 4615 4616 <hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> 4617 <pre>typedef const char * (*lua_Reader) (lua_State *L, 4618 void *data, 4619 size_t *size);</pre> 4620 4621 <p> 4622 The reader function used by <a href="#lua_load"><code>lua_load</code></a>. 4623 Every time it needs another piece of the chunk, 4624 <a href="#lua_load"><code>lua_load</code></a> calls the reader, 4625 passing along its <code>data</code> parameter. 4626 The reader must return a pointer to a block of memory 4627 with a new piece of the chunk 4628 and set <code>size</code> to the block size. 4629 The block must exist until the reader function is called again. 4630 To signal the end of the chunk, 4631 the reader must return <code>NULL</code> or set <code>size</code> to zero. 4632 The reader function may return pieces of any size greater than zero. 4633 4634 4635 4636 4637 4638 <hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> 4639 <span class="apii">[-0, +0, <em>e</em>]</span> 4640 <pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre> 4641 4642 <p> 4643 Sets the C function <code>f</code> as the new value of global <code>name</code>. 4644 It is defined as a macro: 4645 4646 <pre> 4647 #define lua_register(L,n,f) \ 4648 (lua_pushcfunction(L, f), lua_setglobal(L, n)) 4649 </pre> 4650 4651 4652 4653 4654 <hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> 4655 <span class="apii">[-1, +0, –]</span> 4656 <pre>void lua_remove (lua_State *L, int index);</pre> 4657 4658 <p> 4659 Removes the element at the given valid index, 4660 shifting down the elements above this index to fill the gap. 4661 This function cannot be called with a pseudo-index, 4662 because a pseudo-index is not an actual stack position. 4663 4664 4665 4666 4667 4668 <hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> 4669 <span class="apii">[-1, +0, –]</span> 4670 <pre>void lua_replace (lua_State *L, int index);</pre> 4671 4672 <p> 4673 Moves the top element into the given valid index 4674 without shifting any element 4675 (therefore replacing the value at the given index), 4676 and then pops the top element. 4677 4678 4679 4680 4681 4682 <hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> 4683 <span class="apii">[-?, +?, –]</span> 4684 <pre>int lua_resume (lua_State *L, lua_State *from, int nargs);</pre> 4685 4686 <p> 4687 Starts and resumes a coroutine in a given thread. 4688 4689 4690 <p> 4691 To start a coroutine, 4692 you push onto the thread stack the main function plus any arguments; 4693 then you call <a href="#lua_resume"><code>lua_resume</code></a>, 4694 with <code>nargs</code> being the number of arguments. 4695 This call returns when the coroutine suspends or finishes its execution. 4696 When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>, 4697 or all values returned by the body function. 4698 <a href="#lua_resume"><code>lua_resume</code></a> returns 4699 <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, 4700 <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution 4701 without errors, 4702 or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). 4703 4704 4705 <p> 4706 In case of errors, 4707 the stack is not unwound, 4708 so you can use the debug API over it. 4709 The error message is on the top of the stack. 4710 4711 4712 <p> 4713 To resume a coroutine, 4714 you remove any results from the last <a href="#lua_yield"><code>lua_yield</code></a>, 4715 put on its stack only the values to 4716 be passed as results from <code>yield</code>, 4717 and then call <a href="#lua_resume"><code>lua_resume</code></a>. 4718 4719 4720 <p> 4721 The parameter <code>from</code> represents the coroutine that is resuming <code>L</code>. 4722 If there is no such coroutine, 4723 this parameter can be <code>NULL</code>. 4724 4725 4726 4727 4728 4729 <hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p> 4730 <span class="apii">[-0, +0, –]</span> 4731 <pre>void lua_rotate (lua_State *L, int idx, int n);</pre> 4732 4733 <p> 4734 Rotates the stack elements from <code>idx</code> to the top <code>n</code> positions 4735 in the direction of the top, for a positive <code>n</code>, 4736 or <code>-n</code> positions in the direction of the bottom, 4737 for a negative <code>n</code>. 4738 The absolute value of <code>n</code> must not be greater than the size 4739 of the slice being rotated. 4740 4741 4742 4743 4744 4745 <hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> 4746 <span class="apii">[-0, +0, –]</span> 4747 <pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> 4748 4749 <p> 4750 Changes the allocator function of a given state to <code>f</code> 4751 with user data <code>ud</code>. 4752 4753 4754 4755 4756 4757 <hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> 4758 <span class="apii">[-1, +0, <em>e</em>]</span> 4759 <pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> 4760 4761 <p> 4762 Does the equivalent to <code>t[k] = v</code>, 4763 where <code>t</code> is the value at the given index 4764 and <code>v</code> is the value at the top of the stack. 4765 4766 4767 <p> 4768 This function pops the value from the stack. 4769 As in Lua, this function may trigger a metamethod 4770 for the "newindex" event (see <a href="#2.4">§2.4</a>). 4771 4772 4773 4774 4775 4776 <hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> 4777 <span class="apii">[-1, +0, <em>e</em>]</span> 4778 <pre>void lua_setglobal (lua_State *L, const char *name);</pre> 4779 4780 <p> 4781 Pops a value from the stack and 4782 sets it as the new value of global <code>name</code>. 4783 4784 4785 4786 4787 4788 <hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p> 4789 <span class="apii">[-1, +0, <em>e</em>]</span> 4790 <pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre> 4791 4792 <p> 4793 Does the equivalent to <code>t[n] = v</code>, 4794 where <code>t</code> is the value at the given index 4795 and <code>v</code> is the value at the top of the stack. 4796 4797 4798 <p> 4799 This function pops the value from the stack. 4800 As in Lua, this function may trigger a metamethod 4801 for the "newindex" event (see <a href="#2.4">§2.4</a>). 4802 4803 4804 4805 4806 4807 <hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> 4808 <span class="apii">[-1, +0, –]</span> 4809 <pre>void lua_setmetatable (lua_State *L, int index);</pre> 4810 4811 <p> 4812 Pops a table from the stack and 4813 sets it as the new metatable for the value at the given index. 4814 4815 4816 4817 4818 4819 <hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> 4820 <span class="apii">[-2, +0, <em>e</em>]</span> 4821 <pre>void lua_settable (lua_State *L, int index);</pre> 4822 4823 <p> 4824 Does the equivalent to <code>t[k] = v</code>, 4825 where <code>t</code> is the value at the given index, 4826 <code>v</code> is the value at the top of the stack, 4827 and <code>k</code> is the value just below the top. 4828 4829 4830 <p> 4831 This function pops both the key and the value from the stack. 4832 As in Lua, this function may trigger a metamethod 4833 for the "newindex" event (see <a href="#2.4">§2.4</a>). 4834 4835 4836 4837 4838 4839 <hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> 4840 <span class="apii">[-?, +?, –]</span> 4841 <pre>void lua_settop (lua_State *L, int index);</pre> 4842 4843 <p> 4844 Accepts any index, or 0, 4845 and sets the stack top to this index. 4846 If the new top is larger than the old one, 4847 then the new elements are filled with <b>nil</b>. 4848 If <code>index</code> is 0, then all stack elements are removed. 4849 4850 4851 4852 4853 4854 <hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p> 4855 <span class="apii">[-1, +0, –]</span> 4856 <pre>void lua_setuservalue (lua_State *L, int index);</pre> 4857 4858 <p> 4859 Pops a value from the stack and sets it as 4860 the new value associated to the userdata at the given index. 4861 4862 4863 4864 4865 4866 <hr><h3><a name="lua_State"><code>lua_State</code></a></h3> 4867 <pre>typedef struct lua_State lua_State;</pre> 4868 4869 <p> 4870 An opaque structure that points to a thread and indirectly 4871 (through the thread) to the whole state of a Lua interpreter. 4872 The Lua library is fully reentrant: 4873 it has no global variables. 4874 All information about a state is accessible through this structure. 4875 4876 4877 <p> 4878 A pointer to this structure must be passed as the first argument to 4879 every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 4880 which creates a Lua state from scratch. 4881 4882 4883 4884 4885 4886 <hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> 4887 <span class="apii">[-0, +0, –]</span> 4888 <pre>int lua_status (lua_State *L);</pre> 4889 4890 <p> 4891 Returns the status of the thread <code>L</code>. 4892 4893 4894 <p> 4895 The status can be 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) for a normal thread, 4896 an error code if the thread finished the execution 4897 of a <a href="#lua_resume"><code>lua_resume</code></a> with an error, 4898 or <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. 4899 4900 4901 <p> 4902 You can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>. 4903 You can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> 4904 (to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> 4905 (to resume a coroutine). 4906 4907 4908 4909 4910 4911 <hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p> 4912 <span class="apii">[-0, +1, –]</span> 4913 <pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre> 4914 4915 <p> 4916 Converts the zero-terminated string <code>s</code> to a number, 4917 pushes that number into the stack, 4918 and returns the total size of the string, 4919 that is, its length plus one. 4920 The conversion can result in an integer or a float, 4921 according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 4922 The string may have leading and trailing spaces and a sign. 4923 If the string is not a valid numeral, 4924 returns 0 and pushes nothing. 4925 (Note that the result can be used as a boolean, 4926 true if the conversion succeeds.) 4927 4928 4929 4930 4931 4932 <hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> 4933 <span class="apii">[-0, +0, –]</span> 4934 <pre>int lua_toboolean (lua_State *L, int index);</pre> 4935 4936 <p> 4937 Converts the Lua value at the given index to a C boolean 4938 value (0 or 1). 4939 Like all tests in Lua, 4940 <a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value 4941 different from <b>false</b> and <b>nil</b>; 4942 otherwise it returns false. 4943 (If you want to accept only actual boolean values, 4944 use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) 4945 4946 4947 4948 4949 4950 <hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> 4951 <span class="apii">[-0, +0, –]</span> 4952 <pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> 4953 4954 <p> 4955 Converts a value at the given index to a C function. 4956 That value must be a C function; 4957 otherwise, returns <code>NULL</code>. 4958 4959 4960 4961 4962 4963 <hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> 4964 <span class="apii">[-0, +0, –]</span> 4965 <pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> 4966 4967 <p> 4968 Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 4969 4970 4971 4972 4973 4974 <hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p> 4975 <span class="apii">[-0, +0, –]</span> 4976 <pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre> 4977 4978 <p> 4979 Converts the Lua value at the given index 4980 to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. 4981 The Lua value must be an integer, 4982 or a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>); 4983 otherwise, <code>lua_tointegerx</code> returns 0. 4984 4985 4986 <p> 4987 If <code>isnum</code> is not <code>NULL</code>, 4988 its referent is assigned a boolean value that 4989 indicates whether the operation succeeded. 4990 4991 4992 4993 4994 4995 <hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> 4996 <span class="apii">[-0, +0, <em>e</em>]</span> 4997 <pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> 4998 4999 <p> 5000 Converts the Lua value at the given index to a C string. 5001 If <code>len</code> is not <code>NULL</code>, 5002 it also sets <code>*len</code> with the string length. 5003 The Lua value must be a string or a number; 5004 otherwise, the function returns <code>NULL</code>. 5005 If the value is a number, 5006 then <code>lua_tolstring</code> also 5007 <em>changes the actual value in the stack to a string</em>. 5008 (This change confuses <a href="#lua_next"><code>lua_next</code></a> 5009 when <code>lua_tolstring</code> is applied to keys during a table traversal.) 5010 5011 5012 <p> 5013 <code>lua_tolstring</code> returns a fully aligned pointer 5014 to a string inside the Lua state. 5015 This string always has a zero ('<code>\0</code>') 5016 after its last character (as in C), 5017 but can contain other zeros in its body. 5018 5019 5020 <p> 5021 Because Lua has garbage collection, 5022 there is no guarantee that the pointer returned by <code>lua_tolstring</code> 5023 will be valid after the corresponding Lua value is removed from the stack. 5024 5025 5026 5027 5028 5029 <hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> 5030 <span class="apii">[-0, +0, –]</span> 5031 <pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> 5032 5033 <p> 5034 Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5035 5036 5037 5038 5039 5040 <hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p> 5041 <span class="apii">[-0, +0, –]</span> 5042 <pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre> 5043 5044 <p> 5045 Converts the Lua value at the given index 5046 to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). 5047 The Lua value must be a number or a string convertible to a number 5048 (see <a href="#3.4.3">§3.4.3</a>); 5049 otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0. 5050 5051 5052 <p> 5053 If <code>isnum</code> is not <code>NULL</code>, 5054 its referent is assigned a boolean value that 5055 indicates whether the operation succeeded. 5056 5057 5058 5059 5060 5061 <hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> 5062 <span class="apii">[-0, +0, –]</span> 5063 <pre>const void *lua_topointer (lua_State *L, int index);</pre> 5064 5065 <p> 5066 Converts the value at the given index to a generic 5067 C pointer (<code>void*</code>). 5068 The value can be a userdata, a table, a thread, or a function; 5069 otherwise, <code>lua_topointer</code> returns <code>NULL</code>. 5070 Different objects will give different pointers. 5071 There is no way to convert the pointer back to its original value. 5072 5073 5074 <p> 5075 Typically this function is used only for debug information. 5076 5077 5078 5079 5080 5081 <hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> 5082 <span class="apii">[-0, +0, <em>e</em>]</span> 5083 <pre>const char *lua_tostring (lua_State *L, int index);</pre> 5084 5085 <p> 5086 Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. 5087 5088 5089 5090 5091 5092 <hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> 5093 <span class="apii">[-0, +0, –]</span> 5094 <pre>lua_State *lua_tothread (lua_State *L, int index);</pre> 5095 5096 <p> 5097 Converts the value at the given index to a Lua thread 5098 (represented as <code>lua_State*</code>). 5099 This value must be a thread; 5100 otherwise, the function returns <code>NULL</code>. 5101 5102 5103 5104 5105 5106 <hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> 5107 <span class="apii">[-0, +0, –]</span> 5108 <pre>void *lua_touserdata (lua_State *L, int index);</pre> 5109 5110 <p> 5111 If the value at the given index is a full userdata, 5112 returns its block address. 5113 If the value is a light userdata, 5114 returns its pointer. 5115 Otherwise, returns <code>NULL</code>. 5116 5117 5118 5119 5120 5121 <hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> 5122 <span class="apii">[-0, +0, –]</span> 5123 <pre>int lua_type (lua_State *L, int index);</pre> 5124 5125 <p> 5126 Returns the type of the value in the given valid index, 5127 or <code>LUA_TNONE</code> for a non-valid (but acceptable) index. 5128 The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants 5129 defined in <code>lua.h</code>: 5130 <a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a>, 5131 <a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>, 5132 <a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>, 5133 <a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, 5134 <a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, 5135 <a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, 5136 <a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, 5137 <a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>, 5138 and 5139 <a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>. 5140 5141 5142 5143 5144 5145 <hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> 5146 <span class="apii">[-0, +0, –]</span> 5147 <pre>const char *lua_typename (lua_State *L, int tp);</pre> 5148 5149 <p> 5150 Returns the name of the type encoded by the value <code>tp</code>, 5151 which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. 5152 5153 5154 5155 5156 5157 <hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3> 5158 <pre>typedef ... lua_Unsigned;</pre> 5159 5160 <p> 5161 The unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>. 5162 5163 5164 5165 5166 5167 <hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p> 5168 <span class="apii">[-0, +0, –]</span> 5169 <pre>int lua_upvalueindex (int i);</pre> 5170 5171 <p> 5172 Returns the pseudo-index that represents the <code>i</code>-th upvalue of 5173 the running function (see <a href="#4.4">§4.4</a>). 5174 5175 5176 5177 5178 5179 <hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p> 5180 <span class="apii">[-0, +0, <em>v</em>]</span> 5181 <pre>const lua_Number *lua_version (lua_State *L);</pre> 5182 5183 <p> 5184 Returns the address of the version number stored in the Lua core. 5185 When called with a valid <a href="#lua_State"><code>lua_State</code></a>, 5186 returns the address of the version used to create that state. 5187 When called with <code>NULL</code>, 5188 returns the address of the version running the call. 5189 5190 5191 5192 5193 5194 <hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> 5195 <pre>typedef int (*lua_Writer) (lua_State *L, 5196 const void* p, 5197 size_t sz, 5198 void* ud);</pre> 5199 5200 <p> 5201 The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. 5202 Every time it produces another piece of chunk, 5203 <a href="#lua_dump"><code>lua_dump</code></a> calls the writer, 5204 passing along the buffer to be written (<code>p</code>), 5205 its size (<code>sz</code>), 5206 and the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. 5207 5208 5209 <p> 5210 The writer returns an error code: 5211 0 means no errors; 5212 any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from 5213 calling the writer again. 5214 5215 5216 5217 5218 5219 <hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> 5220 <span class="apii">[-?, +?, –]</span> 5221 <pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> 5222 5223 <p> 5224 Exchange values between different threads of the same state. 5225 5226 5227 <p> 5228 This function pops <code>n</code> values from the stack <code>from</code>, 5229 and pushes them onto the stack <code>to</code>. 5230 5231 5232 5233 5234 5235 <hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> 5236 <span class="apii">[-?, +?, <em>e</em>]</span> 5237 <pre>int lua_yield (lua_State *L, int nresults);</pre> 5238 5239 <p> 5240 This function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5241 but it has no continuation (see <a href="#4.7">§4.7</a>). 5242 Therefore, when the thread resumes, 5243 it continues the function that called 5244 the function calling <code>lua_yield</code>. 5245 5246 5247 5248 5249 5250 <hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p> 5251 <span class="apii">[-?, +?, <em>e</em>]</span> 5252 <pre>int lua_yieldk (lua_State *L, 5253 int nresults, 5254 lua_KContext ctx, 5255 lua_KFunction k);</pre> 5256 5257 <p> 5258 Yields a coroutine (thread). 5259 5260 5261 <p> 5262 When a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5263 the running coroutine suspends its execution, 5264 and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. 5265 The parameter <code>nresults</code> is the number of values from the stack 5266 that will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. 5267 5268 5269 <p> 5270 When the coroutine is resumed again, 5271 Lua calls the given continuation function <code>k</code> to continue 5272 the execution of the C function that yielded (see <a href="#4.7">§4.7</a>). 5273 This continuation function receives the same stack 5274 from the previous function, 5275 with the <code>n</code> results removed and 5276 replaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>. 5277 Moreover, 5278 the continuation function receives the value <code>ctx</code> 5279 that was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>. 5280 5281 5282 <p> 5283 Usually, this function does not return; 5284 when the coroutine eventually resumes, 5285 it continues executing the continuation function. 5286 However, there is one special case, 5287 which is when this function is called 5288 from inside a line hook (see <a href="#4.9">§4.9</a>). 5289 In that case, <code>lua_yieldk</code> should be called with no continuation 5290 (probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>), 5291 and the hook should return immediately after the call. 5292 Lua will yield and, 5293 when the coroutine resumes again, 5294 it will continue the normal execution 5295 of the (Lua) function that triggered the hook. 5296 5297 5298 <p> 5299 This function can raise an error if it is called from a thread 5300 with a pending C call with no continuation function, 5301 or it is called from a thread that is not running inside a resume 5302 (e.g., the main thread). 5303 5304 5305 5306 5307 5308 5309 5310 <h2>4.9 – <a name="4.9">The Debug Interface</a></h2> 5311 5312 <p> 5313 Lua has no built-in debugging facilities. 5314 Instead, it offers a special interface 5315 by means of functions and <em>hooks</em>. 5316 This interface allows the construction of different 5317 kinds of debuggers, profilers, and other tools 5318 that need "inside information" from the interpreter. 5319 5320 5321 5322 <hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> 5323 <pre>typedef struct lua_Debug { 5324 int event; 5325 const char *name; /* (n) */ 5326 const char *namewhat; /* (n) */ 5327 const char *what; /* (S) */ 5328 const char *source; /* (S) */ 5329 int currentline; /* (l) */ 5330 int linedefined; /* (S) */ 5331 int lastlinedefined; /* (S) */ 5332 unsigned char nups; /* (u) number of upvalues */ 5333 unsigned char nparams; /* (u) number of parameters */ 5334 char isvararg; /* (u) */ 5335 char istailcall; /* (t) */ 5336 char short_src[LUA_IDSIZE]; /* (S) */ 5337 /* private part */ 5338 <em>other fields</em> 5339 } lua_Debug;</pre> 5340 5341 <p> 5342 A structure used to carry different pieces of 5343 information about a function or an activation record. 5344 <a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part 5345 of this structure, for later use. 5346 To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, 5347 call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 5348 5349 5350 <p> 5351 The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: 5352 5353 <ul> 5354 5355 <li><b><code>source</code>: </b> 5356 the name of the chunk that created the function. 5357 If <code>source</code> starts with a '<code>@</code>', 5358 it means that the function was defined in a file where 5359 the file name follows the '<code>@</code>'. 5360 If <code>source</code> starts with a '<code>=</code>', 5361 the remainder of its contents describe the source in a user-dependent manner. 5362 Otherwise, 5363 the function was defined in a string where 5364 <code>source</code> is that string. 5365 </li> 5366 5367 <li><b><code>short_src</code>: </b> 5368 a "printable" version of <code>source</code>, to be used in error messages. 5369 </li> 5370 5371 <li><b><code>linedefined</code>: </b> 5372 the line number where the definition of the function starts. 5373 </li> 5374 5375 <li><b><code>lastlinedefined</code>: </b> 5376 the line number where the definition of the function ends. 5377 </li> 5378 5379 <li><b><code>what</code>: </b> 5380 the string <code>"Lua"</code> if the function is a Lua function, 5381 <code>"C"</code> if it is a C function, 5382 <code>"main"</code> if it is the main part of a chunk. 5383 </li> 5384 5385 <li><b><code>currentline</code>: </b> 5386 the current line where the given function is executing. 5387 When no line information is available, 5388 <code>currentline</code> is set to -1. 5389 </li> 5390 5391 <li><b><code>name</code>: </b> 5392 a reasonable name for the given function. 5393 Because functions in Lua are first-class values, 5394 they do not have a fixed name: 5395 some functions can be the value of multiple global variables, 5396 while others can be stored only in a table field. 5397 The <code>lua_getinfo</code> function checks how the function was 5398 called to find a suitable name. 5399 If it cannot find a name, 5400 then <code>name</code> is set to <code>NULL</code>. 5401 </li> 5402 5403 <li><b><code>namewhat</code>: </b> 5404 explains the <code>name</code> field. 5405 The value of <code>namewhat</code> can be 5406 <code>"global"</code>, <code>"local"</code>, <code>"method"</code>, 5407 <code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), 5408 according to how the function was called. 5409 (Lua uses the empty string when no other option seems to apply.) 5410 </li> 5411 5412 <li><b><code>istailcall</code>: </b> 5413 true if this function invocation was called by a tail call. 5414 In this case, the caller of this level is not in the stack. 5415 </li> 5416 5417 <li><b><code>nups</code>: </b> 5418 the number of upvalues of the function. 5419 </li> 5420 5421 <li><b><code>nparams</code>: </b> 5422 the number of fixed parameters of the function 5423 (always 0 for C functions). 5424 </li> 5425 5426 <li><b><code>isvararg</code>: </b> 5427 true if the function is a vararg function 5428 (always true for C functions). 5429 </li> 5430 5431 </ul> 5432 5433 5434 5435 5436 <hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> 5437 <span class="apii">[-0, +0, –]</span> 5438 <pre>lua_Hook lua_gethook (lua_State *L);</pre> 5439 5440 <p> 5441 Returns the current hook function. 5442 5443 5444 5445 5446 5447 <hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> 5448 <span class="apii">[-0, +0, –]</span> 5449 <pre>int lua_gethookcount (lua_State *L);</pre> 5450 5451 <p> 5452 Returns the current hook count. 5453 5454 5455 5456 5457 5458 <hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> 5459 <span class="apii">[-0, +0, –]</span> 5460 <pre>int lua_gethookmask (lua_State *L);</pre> 5461 5462 <p> 5463 Returns the current hook mask. 5464 5465 5466 5467 5468 5469 <hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> 5470 <span class="apii">[-(0|1), +(0|1|2), <em>e</em>]</span> 5471 <pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> 5472 5473 <p> 5474 Gets information about a specific function or function invocation. 5475 5476 5477 <p> 5478 To get information about a function invocation, 5479 the parameter <code>ar</code> must be a valid activation record that was 5480 filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 5481 given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 5482 5483 5484 <p> 5485 To get information about a function you push it onto the stack 5486 and start the <code>what</code> string with the character '<code>></code>'. 5487 (In that case, 5488 <code>lua_getinfo</code> pops the function from the top of the stack.) 5489 For instance, to know in which line a function <code>f</code> was defined, 5490 you can write the following code: 5491 5492 <pre> 5493 lua_Debug ar; 5494 lua_getglobal(L, "f"); /* get global 'f' */ 5495 lua_getinfo(L, ">S", &ar); 5496 printf("%d\n", ar.linedefined); 5497 </pre> 5498 5499 <p> 5500 Each character in the string <code>what</code> 5501 selects some fields of the structure <code>ar</code> to be filled or 5502 a value to be pushed on the stack: 5503 5504 <ul> 5505 5506 <li><b>'<code>n</code>': </b> fills in the field <code>name</code> and <code>namewhat</code>; 5507 </li> 5508 5509 <li><b>'<code>S</code>': </b> 5510 fills in the fields <code>source</code>, <code>short_src</code>, 5511 <code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; 5512 </li> 5513 5514 <li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>; 5515 </li> 5516 5517 <li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>; 5518 </li> 5519 5520 <li><b>'<code>u</code>': </b> fills in the fields 5521 <code>nups</code>, <code>nparams</code>, and <code>isvararg</code>; 5522 </li> 5523 5524 <li><b>'<code>f</code>': </b> 5525 pushes onto the stack the function that is 5526 running at the given level; 5527 </li> 5528 5529 <li><b>'<code>L</code>': </b> 5530 pushes onto the stack a table whose indices are the 5531 numbers of the lines that are valid on the function. 5532 (A <em>valid line</em> is a line with some associated code, 5533 that is, a line where you can put a break point. 5534 Non-valid lines include empty lines and comments.) 5535 5536 5537 <p> 5538 If this option is given together with option '<code>f</code>', 5539 its table is pushed after the function. 5540 </li> 5541 5542 </ul> 5543 5544 <p> 5545 This function returns 0 on error 5546 (for instance, an invalid option in <code>what</code>). 5547 5548 5549 5550 5551 5552 <hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> 5553 <span class="apii">[-0, +(0|1), –]</span> 5554 <pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 5555 5556 <p> 5557 Gets information about a local variable of 5558 a given activation record or a given function. 5559 5560 5561 <p> 5562 In the first case, 5563 the parameter <code>ar</code> must be a valid activation record that was 5564 filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 5565 given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 5566 The index <code>n</code> selects which local variable to inspect; 5567 see <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices 5568 and names. 5569 5570 5571 <p> 5572 <a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack 5573 and returns its name. 5574 5575 5576 <p> 5577 In the second case, <code>ar</code> must be <code>NULL</code> and the function 5578 to be inspected must be at the top of the stack. 5579 In this case, only parameters of Lua functions are visible 5580 (as there is no information about what variables are active) 5581 and no values are pushed onto the stack. 5582 5583 5584 <p> 5585 Returns <code>NULL</code> (and pushes nothing) 5586 when the index is greater than 5587 the number of active local variables. 5588 5589 5590 5591 5592 5593 <hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> 5594 <span class="apii">[-0, +0, –]</span> 5595 <pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> 5596 5597 <p> 5598 Gets information about the interpreter runtime stack. 5599 5600 5601 <p> 5602 This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with 5603 an identification of the <em>activation record</em> 5604 of the function executing at a given level. 5605 Level 0 is the current running function, 5606 whereas level <em>n+1</em> is the function that has called level <em>n</em> 5607 (except for tail calls, which do not count on the stack). 5608 When there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1; 5609 when called with a level greater than the stack depth, 5610 it returns 0. 5611 5612 5613 5614 5615 5616 <hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> 5617 <span class="apii">[-0, +(0|1), –]</span> 5618 <pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> 5619 5620 <p> 5621 Gets information about a closure's upvalue. 5622 (For Lua functions, 5623 upvalues are the external local variables that the function uses, 5624 and that are consequently included in its closure.) 5625 <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> gets the index <code>n</code> of an upvalue, 5626 pushes the upvalue's value onto the stack, 5627 and returns its name. 5628 <code>funcindex</code> points to the closure in the stack. 5629 (Upvalues have no particular order, 5630 as they are active through the whole function. 5631 So, they are numbered in an arbitrary order.) 5632 5633 5634 <p> 5635 Returns <code>NULL</code> (and pushes nothing) 5636 when the index is greater than the number of upvalues. 5637 For C functions, this function uses the empty string <code>""</code> 5638 as a name for all upvalues. 5639 5640 5641 5642 5643 5644 <hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> 5645 <pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> 5646 5647 <p> 5648 Type for debugging hook functions. 5649 5650 5651 <p> 5652 Whenever a hook is called, its <code>ar</code> argument has its field 5653 <code>event</code> set to the specific event that triggered the hook. 5654 Lua identifies these events with the following constants: 5655 <a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, 5656 <a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, 5657 and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. 5658 Moreover, for line events, the field <code>currentline</code> is also set. 5659 To get the value of any other field in <code>ar</code>, 5660 the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 5661 5662 5663 <p> 5664 For call events, <code>event</code> can be <code>LUA_HOOKCALL</code>, 5665 the normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call; 5666 in this case, there will be no corresponding return event. 5667 5668 5669 <p> 5670 While Lua is running a hook, it disables other calls to hooks. 5671 Therefore, if a hook calls back Lua to execute a function or a chunk, 5672 this execution occurs without any calls to hooks. 5673 5674 5675 <p> 5676 Hook functions cannot have continuations, 5677 that is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5678 <a href="#lua_pcallk"><code>lua_pcallk</code></a>, or <a href="#lua_callk"><code>lua_callk</code></a> with a non-null <code>k</code>. 5679 5680 5681 <p> 5682 Hook functions can yield under the following conditions: 5683 Only count and line events can yield 5684 and they cannot yield any value; 5685 to yield a hook function must finish its execution 5686 calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero. 5687 5688 5689 5690 5691 5692 <hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> 5693 <span class="apii">[-0, +0, –]</span> 5694 <pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> 5695 5696 <p> 5697 Sets the debugging hook function. 5698 5699 5700 <p> 5701 Argument <code>f</code> is the hook function. 5702 <code>mask</code> specifies on which events the hook will be called: 5703 it is formed by a bitwise or of the constants 5704 <a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, 5705 <a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, 5706 <a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, 5707 and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. 5708 The <code>count</code> argument is only meaningful when the mask 5709 includes <code>LUA_MASKCOUNT</code>. 5710 For each event, the hook is called as explained below: 5711 5712 <ul> 5713 5714 <li><b>The call hook: </b> is called when the interpreter calls a function. 5715 The hook is called just after Lua enters the new function, 5716 before the function gets its arguments. 5717 </li> 5718 5719 <li><b>The return hook: </b> is called when the interpreter returns from a function. 5720 The hook is called just before Lua leaves the function. 5721 There is no standard way to access the values 5722 to be returned by the function. 5723 </li> 5724 5725 <li><b>The line hook: </b> is called when the interpreter is about to 5726 start the execution of a new line of code, 5727 or when it jumps back in the code (even to the same line). 5728 (This event only happens while Lua is executing a Lua function.) 5729 </li> 5730 5731 <li><b>The count hook: </b> is called after the interpreter executes every 5732 <code>count</code> instructions. 5733 (This event only happens while Lua is executing a Lua function.) 5734 </li> 5735 5736 </ul> 5737 5738 <p> 5739 A hook is disabled by setting <code>mask</code> to zero. 5740 5741 5742 5743 5744 5745 <hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> 5746 <span class="apii">[-(0|1), +0, –]</span> 5747 <pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 5748 5749 <p> 5750 Sets the value of a local variable of a given activation record. 5751 Parameters <code>ar</code> and <code>n</code> are as in <a href="#lua_getlocal"><code>lua_getlocal</code></a> 5752 (see <a href="#lua_getlocal"><code>lua_getlocal</code></a>). 5753 <a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack 5754 to the variable and returns its name. 5755 It also pops the value from the stack. 5756 5757 5758 <p> 5759 Returns <code>NULL</code> (and pops nothing) 5760 when the index is greater than 5761 the number of active local variables. 5762 5763 5764 5765 5766 5767 <hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> 5768 <span class="apii">[-(0|1), +0, –]</span> 5769 <pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> 5770 5771 <p> 5772 Sets the value of a closure's upvalue. 5773 It assigns the value at the top of the stack 5774 to the upvalue and returns its name. 5775 It also pops the value from the stack. 5776 Parameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> 5777 (see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>). 5778 5779 5780 <p> 5781 Returns <code>NULL</code> (and pops nothing) 5782 when the index is greater than the number of upvalues. 5783 5784 5785 5786 5787 5788 <hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p> 5789 <span class="apii">[-0, +0, –]</span> 5790 <pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre> 5791 5792 <p> 5793 Returns a unique identifier for the upvalue numbered <code>n</code> 5794 from the closure at index <code>funcindex</code>. 5795 Parameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> 5796 (see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>) 5797 (but <code>n</code> cannot be greater than the number of upvalues). 5798 5799 5800 <p> 5801 These unique identifiers allow a program to check whether different 5802 closures share upvalues. 5803 Lua closures that share an upvalue 5804 (that is, that access a same external local variable) 5805 will return identical ids for those upvalue indices. 5806 5807 5808 5809 5810 5811 <hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p> 5812 <span class="apii">[-0, +0, –]</span> 5813 <pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1, 5814 int funcindex2, int n2);</pre> 5815 5816 <p> 5817 Make the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code> 5818 refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>. 5819 5820 5821 5822 5823 5824 5825 5826 <h1>5 – <a name="5">The Auxiliary Library</a></h1> 5827 5828 <p> 5829 5830 The <em>auxiliary library</em> provides several convenient functions 5831 to interface C with Lua. 5832 While the basic API provides the primitive functions for all 5833 interactions between C and Lua, 5834 the auxiliary library provides higher-level functions for some 5835 common tasks. 5836 5837 5838 <p> 5839 All functions and types from the auxiliary library 5840 are defined in header file <code>lauxlib.h</code> and 5841 have a prefix <code>luaL_</code>. 5842 5843 5844 <p> 5845 All functions in the auxiliary library are built on 5846 top of the basic API, 5847 and so they provide nothing that cannot be done with that API. 5848 Nevertheless, the use of the auxiliary library ensures 5849 more consistency to your code. 5850 5851 5852 <p> 5853 Several functions in the auxiliary library use internally some 5854 extra stack slots. 5855 When a function in the auxiliary library uses less than five slots, 5856 it does not check the stack size; 5857 it simply assumes that there are enough slots. 5858 5859 5860 <p> 5861 Several functions in the auxiliary library are used to 5862 check C function arguments. 5863 Because the error message is formatted for arguments 5864 (e.g., "<code>bad argument #1</code>"), 5865 you should not use these functions for other stack values. 5866 5867 5868 <p> 5869 Functions called <code>luaL_check*</code> 5870 always raise an error if the check is not satisfied. 5871 5872 5873 5874 <h2>5.1 – <a name="5.1">Functions and Types</a></h2> 5875 5876 <p> 5877 Here we list all functions and types from the auxiliary library 5878 in alphabetical order. 5879 5880 5881 5882 <hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> 5883 <span class="apii">[-?, +?, <em>e</em>]</span> 5884 <pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> 5885 5886 <p> 5887 Adds the byte <code>c</code> to the buffer <code>B</code> 5888 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5889 5890 5891 5892 5893 5894 <hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> 5895 <span class="apii">[-?, +?, <em>e</em>]</span> 5896 <pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> 5897 5898 <p> 5899 Adds the string pointed to by <code>s</code> with length <code>l</code> to 5900 the buffer <code>B</code> 5901 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5902 The string can contain embedded zeros. 5903 5904 5905 5906 5907 5908 <hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> 5909 <span class="apii">[-?, +?, <em>e</em>]</span> 5910 <pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> 5911 5912 <p> 5913 Adds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>) 5914 a string of length <code>n</code> previously copied to the 5915 buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). 5916 5917 5918 5919 5920 5921 <hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> 5922 <span class="apii">[-?, +?, <em>e</em>]</span> 5923 <pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> 5924 5925 <p> 5926 Adds the zero-terminated string pointed to by <code>s</code> 5927 to the buffer <code>B</code> 5928 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5929 5930 5931 5932 5933 5934 <hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> 5935 <span class="apii">[-1, +?, <em>e</em>]</span> 5936 <pre>void luaL_addvalue (luaL_Buffer *B);</pre> 5937 5938 <p> 5939 Adds the value at the top of the stack 5940 to the buffer <code>B</code> 5941 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5942 Pops the value. 5943 5944 5945 <p> 5946 This is the only function on string buffers that can (and must) 5947 be called with an extra element on the stack, 5948 which is the value to be added to the buffer. 5949 5950 5951 5952 5953 5954 <hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> 5955 <span class="apii">[-0, +0, <em>v</em>]</span> 5956 <pre>void luaL_argcheck (lua_State *L, 5957 int cond, 5958 int arg, 5959 const char *extramsg);</pre> 5960 5961 <p> 5962 Checks whether <code>cond</code> is true. 5963 If it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>). 5964 5965 5966 5967 5968 5969 <hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> 5970 <span class="apii">[-0, +0, <em>v</em>]</span> 5971 <pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre> 5972 5973 <p> 5974 Raises an error reporting a problem with argument <code>arg</code> 5975 of the C function that called it, 5976 using a standard message 5977 that includes <code>extramsg</code> as a comment: 5978 5979 <pre> 5980 bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>) 5981 </pre><p> 5982 This function never returns. 5983 5984 5985 5986 5987 5988 <hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> 5989 <pre>typedef struct luaL_Buffer luaL_Buffer;</pre> 5990 5991 <p> 5992 Type for a <em>string buffer</em>. 5993 5994 5995 <p> 5996 A string buffer allows C code to build Lua strings piecemeal. 5997 Its pattern of use is as follows: 5998 5999 <ul> 6000 6001 <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6002 6003 <li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> 6004 6005 <li> 6006 Then add string pieces to the buffer calling any of 6007 the <code>luaL_add*</code> functions. 6008 </li> 6009 6010 <li> 6011 Finish by calling <code>luaL_pushresult(&b)</code>. 6012 This call leaves the final string on the top of the stack. 6013 </li> 6014 6015 </ul> 6016 6017 <p> 6018 If you know beforehand the total size of the resulting string, 6019 you can use the buffer like this: 6020 6021 <ul> 6022 6023 <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6024 6025 <li>Then initialize it and preallocate a space of 6026 size <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li> 6027 6028 <li>Then copy the string into that space.</li> 6029 6030 <li> 6031 Finish by calling <code>luaL_pushresultsize(&b, sz)</code>, 6032 where <code>sz</code> is the total size of the resulting string 6033 copied into that space. 6034 </li> 6035 6036 </ul> 6037 6038 <p> 6039 During its normal operation, 6040 a string buffer uses a variable number of stack slots. 6041 So, while using a buffer, you cannot assume that you know where 6042 the top of the stack is. 6043 You can use the stack between successive calls to buffer operations 6044 as long as that use is balanced; 6045 that is, 6046 when you call a buffer operation, 6047 the stack is at the same level 6048 it was immediately after the previous buffer operation. 6049 (The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) 6050 After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its 6051 level when the buffer was initialized, 6052 plus the final string on its top. 6053 6054 6055 6056 6057 6058 <hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> 6059 <span class="apii">[-0, +0, –]</span> 6060 <pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> 6061 6062 <p> 6063 Initializes a buffer <code>B</code>. 6064 This function does not allocate any space; 6065 the buffer must be declared as a variable 6066 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6067 6068 6069 6070 6071 6072 <hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p> 6073 <span class="apii">[-?, +?, <em>e</em>]</span> 6074 <pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre> 6075 6076 <p> 6077 Equivalent to the sequence 6078 <a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>. 6079 6080 6081 6082 6083 6084 <hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> 6085 <span class="apii">[-0, +(0|1), <em>e</em>]</span> 6086 <pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> 6087 6088 <p> 6089 Calls a metamethod. 6090 6091 6092 <p> 6093 If the object at index <code>obj</code> has a metatable and this 6094 metatable has a field <code>e</code>, 6095 this function calls this field passing the object as its only argument. 6096 In this case this function returns true and pushes onto the 6097 stack the value returned by the call. 6098 If there is no metatable or no metamethod, 6099 this function returns false (without pushing any value on the stack). 6100 6101 6102 6103 6104 6105 <hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> 6106 <span class="apii">[-0, +0, <em>v</em>]</span> 6107 <pre>void luaL_checkany (lua_State *L, int arg);</pre> 6108 6109 <p> 6110 Checks whether the function has an argument 6111 of any type (including <b>nil</b>) at position <code>arg</code>. 6112 6113 6114 6115 6116 6117 <hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> 6118 <span class="apii">[-0, +0, <em>v</em>]</span> 6119 <pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre> 6120 6121 <p> 6122 Checks whether the function argument <code>arg</code> is an integer 6123 (or can be converted to an integer) 6124 and returns this integer cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. 6125 6126 6127 6128 6129 6130 <hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> 6131 <span class="apii">[-0, +0, <em>v</em>]</span> 6132 <pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre> 6133 6134 <p> 6135 Checks whether the function argument <code>arg</code> is a string 6136 and returns this string; 6137 if <code>l</code> is not <code>NULL</code> fills <code>*l</code> 6138 with the string's length. 6139 6140 6141 <p> 6142 This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6143 so all conversions and caveats of that function apply here. 6144 6145 6146 6147 6148 6149 <hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> 6150 <span class="apii">[-0, +0, <em>v</em>]</span> 6151 <pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre> 6152 6153 <p> 6154 Checks whether the function argument <code>arg</code> is a number 6155 and returns this number. 6156 6157 6158 6159 6160 6161 <hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> 6162 <span class="apii">[-0, +0, <em>v</em>]</span> 6163 <pre>int luaL_checkoption (lua_State *L, 6164 int arg, 6165 const char *def, 6166 const char *const lst[]);</pre> 6167 6168 <p> 6169 Checks whether the function argument <code>arg</code> is a string and 6170 searches for this string in the array <code>lst</code> 6171 (which must be NULL-terminated). 6172 Returns the index in the array where the string was found. 6173 Raises an error if the argument is not a string or 6174 if the string cannot be found. 6175 6176 6177 <p> 6178 If <code>def</code> is not <code>NULL</code>, 6179 the function uses <code>def</code> as a default value when 6180 there is no argument <code>arg</code> or when this argument is <b>nil</b>. 6181 6182 6183 <p> 6184 This is a useful function for mapping strings to C enums. 6185 (The usual convention in Lua libraries is 6186 to use strings instead of numbers to select options.) 6187 6188 6189 6190 6191 6192 <hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> 6193 <span class="apii">[-0, +0, <em>v</em>]</span> 6194 <pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> 6195 6196 <p> 6197 Grows the stack size to <code>top + sz</code> elements, 6198 raising an error if the stack cannot grow to that size. 6199 <code>msg</code> is an additional text to go into the error message 6200 (or <code>NULL</code> for no additional text). 6201 6202 6203 6204 6205 6206 <hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> 6207 <span class="apii">[-0, +0, <em>v</em>]</span> 6208 <pre>const char *luaL_checkstring (lua_State *L, int arg);</pre> 6209 6210 <p> 6211 Checks whether the function argument <code>arg</code> is a string 6212 and returns this string. 6213 6214 6215 <p> 6216 This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6217 so all conversions and caveats of that function apply here. 6218 6219 6220 6221 6222 6223 <hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> 6224 <span class="apii">[-0, +0, <em>v</em>]</span> 6225 <pre>void luaL_checktype (lua_State *L, int arg, int t);</pre> 6226 6227 <p> 6228 Checks whether the function argument <code>arg</code> has type <code>t</code>. 6229 See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. 6230 6231 6232 6233 6234 6235 <hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> 6236 <span class="apii">[-0, +0, <em>v</em>]</span> 6237 <pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre> 6238 6239 <p> 6240 Checks whether the function argument <code>arg</code> is a userdata 6241 of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and 6242 returns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>). 6243 6244 6245 6246 6247 6248 <hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p> 6249 <span class="apii">[-0, +0, –]</span> 6250 <pre>void luaL_checkversion (lua_State *L);</pre> 6251 6252 <p> 6253 Checks whether the core running the call, 6254 the core that created the Lua state, 6255 and the code making the call are all using the same version of Lua. 6256 Also checks whether the core running the call 6257 and the core that created the Lua state 6258 are using the same address space. 6259 6260 6261 6262 6263 6264 <hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> 6265 <span class="apii">[-0, +?, <em>e</em>]</span> 6266 <pre>int luaL_dofile (lua_State *L, const char *filename);</pre> 6267 6268 <p> 6269 Loads and runs the given file. 6270 It is defined as the following macro: 6271 6272 <pre> 6273 (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6274 </pre><p> 6275 It returns false if there are no errors 6276 or true in case of errors. 6277 6278 6279 6280 6281 6282 <hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> 6283 <span class="apii">[-0, +?, –]</span> 6284 <pre>int luaL_dostring (lua_State *L, const char *str);</pre> 6285 6286 <p> 6287 Loads and runs the given string. 6288 It is defined as the following macro: 6289 6290 <pre> 6291 (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6292 </pre><p> 6293 It returns false if there are no errors 6294 or true in case of errors. 6295 6296 6297 6298 6299 6300 <hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> 6301 <span class="apii">[-0, +0, <em>v</em>]</span> 6302 <pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> 6303 6304 <p> 6305 Raises an error. 6306 The error message format is given by <code>fmt</code> 6307 plus any extra arguments, 6308 following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. 6309 It also adds at the beginning of the message the file name and 6310 the line number where the error occurred, 6311 if this information is available. 6312 6313 6314 <p> 6315 This function never returns, 6316 but it is an idiom to use it in C functions 6317 as <code>return luaL_error(<em>args</em>)</code>. 6318 6319 6320 6321 6322 6323 <hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p> 6324 <span class="apii">[-0, +3, <em>e</em>]</span> 6325 <pre>int luaL_execresult (lua_State *L, int stat);</pre> 6326 6327 <p> 6328 This function produces the return values for 6329 process-related functions in the standard library 6330 (<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>). 6331 6332 6333 6334 6335 6336 <hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p> 6337 <span class="apii">[-0, +(1|3), <em>e</em>]</span> 6338 <pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre> 6339 6340 <p> 6341 This function produces the return values for 6342 file-related functions in the standard library 6343 (<a href="#pdf-io.open"><code>io.open</code></a>, <a href="#pdf-os.rename"><code>os.rename</code></a>, <a href="#pdf-file:seek"><code>file:seek</code></a>, etc.). 6344 6345 6346 6347 6348 6349 <hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> 6350 <span class="apii">[-0, +(0|1), <em>e</em>]</span> 6351 <pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> 6352 6353 <p> 6354 Pushes onto the stack the field <code>e</code> from the metatable 6355 of the object at index <code>obj</code> and returns the type of pushed value. 6356 If the object does not have a metatable, 6357 or if the metatable does not have this field, 6358 pushes nothing and returns <code>LUA_TNIL</code>. 6359 6360 6361 6362 6363 6364 <hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> 6365 <span class="apii">[-0, +1, –]</span> 6366 <pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre> 6367 6368 <p> 6369 Pushes onto the stack the metatable associated with name <code>tname</code> 6370 in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 6371 If there is no metatable associated with <code>tname</code>, 6372 returns false and pushes <b>nil</b>. 6373 6374 6375 6376 6377 6378 <hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p> 6379 <span class="apii">[-0, +1, <em>e</em>]</span> 6380 <pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre> 6381 6382 <p> 6383 Ensures that the value <code>t[fname]</code>, 6384 where <code>t</code> is the value at index <code>idx</code>, 6385 is a table, 6386 and pushes that table onto the stack. 6387 Returns true if it finds a previous table there 6388 and false if it creates a new table. 6389 6390 6391 6392 6393 6394 <hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> 6395 <span class="apii">[-0, +1, <em>e</em>]</span> 6396 <pre>const char *luaL_gsub (lua_State *L, 6397 const char *s, 6398 const char *p, 6399 const char *r);</pre> 6400 6401 <p> 6402 Creates a copy of string <code>s</code> by replacing 6403 any occurrence of the string <code>p</code> 6404 with the string <code>r</code>. 6405 Pushes the resulting string on the stack and returns it. 6406 6407 6408 6409 6410 6411 <hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p> 6412 <span class="apii">[-0, +0, <em>e</em>]</span> 6413 <pre>lua_Integer luaL_len (lua_State *L, int index);</pre> 6414 6415 <p> 6416 Returns the "length" of the value at the given index 6417 as a number; 6418 it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). 6419 Raises an error if the result of the operation is not an integer. 6420 (This case only can happen through metamethods.) 6421 6422 6423 6424 6425 6426 <hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> 6427 <span class="apii">[-0, +1, –]</span> 6428 <pre>int luaL_loadbuffer (lua_State *L, 6429 const char *buff, 6430 size_t sz, 6431 const char *name);</pre> 6432 6433 <p> 6434 Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>. 6435 6436 6437 6438 6439 6440 <hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p> 6441 <span class="apii">[-0, +1, –]</span> 6442 <pre>int luaL_loadbufferx (lua_State *L, 6443 const char *buff, 6444 size_t sz, 6445 const char *name, 6446 const char *mode);</pre> 6447 6448 <p> 6449 Loads a buffer as a Lua chunk. 6450 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the 6451 buffer pointed to by <code>buff</code> with size <code>sz</code>. 6452 6453 6454 <p> 6455 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 6456 <code>name</code> is the chunk name, 6457 used for debug information and error messages. 6458 The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. 6459 6460 6461 6462 6463 6464 <hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> 6465 <span class="apii">[-0, +1, <em>e</em>]</span> 6466 <pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> 6467 6468 <p> 6469 Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>. 6470 6471 6472 6473 6474 6475 <hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p> 6476 <span class="apii">[-0, +1, <em>e</em>]</span> 6477 <pre>int luaL_loadfilex (lua_State *L, const char *filename, 6478 const char *mode);</pre> 6479 6480 <p> 6481 Loads a file as a Lua chunk. 6482 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file 6483 named <code>filename</code>. 6484 If <code>filename</code> is <code>NULL</code>, 6485 then it loads from the standard input. 6486 The first line in the file is ignored if it starts with a <code>#</code>. 6487 6488 6489 <p> 6490 The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. 6491 6492 6493 <p> 6494 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, 6495 but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> 6496 if it cannot open/read the file or the file has a wrong mode. 6497 6498 6499 <p> 6500 As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 6501 it does not run it. 6502 6503 6504 6505 6506 6507 <hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> 6508 <span class="apii">[-0, +1, –]</span> 6509 <pre>int luaL_loadstring (lua_State *L, const char *s);</pre> 6510 6511 <p> 6512 Loads a string as a Lua chunk. 6513 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in 6514 the zero-terminated string <code>s</code>. 6515 6516 6517 <p> 6518 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 6519 6520 6521 <p> 6522 Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 6523 it does not run it. 6524 6525 6526 6527 6528 6529 <hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p> 6530 <span class="apii">[-0, +1, <em>e</em>]</span> 6531 <pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre> 6532 6533 <p> 6534 Creates a new table and registers there 6535 the functions in list <code>l</code>. 6536 6537 6538 <p> 6539 It is implemented as the following macro: 6540 6541 <pre> 6542 (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0)) 6543 </pre><p> 6544 The array <code>l</code> must be the actual array, 6545 not a pointer to it. 6546 6547 6548 6549 6550 6551 <hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p> 6552 <span class="apii">[-0, +1, <em>e</em>]</span> 6553 <pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre> 6554 6555 <p> 6556 Creates a new table with a size optimized 6557 to store all entries in the array <code>l</code> 6558 (but does not actually store them). 6559 It is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> 6560 (see <a href="#luaL_newlib"><code>luaL_newlib</code></a>). 6561 6562 6563 <p> 6564 It is implemented as a macro. 6565 The array <code>l</code> must be the actual array, 6566 not a pointer to it. 6567 6568 6569 6570 6571 6572 <hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> 6573 <span class="apii">[-0, +1, <em>e</em>]</span> 6574 <pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> 6575 6576 <p> 6577 If the registry already has the key <code>tname</code>, 6578 returns 0. 6579 Otherwise, 6580 creates a new table to be used as a metatable for userdata, 6581 adds to this new table the pair <code>__name = tname</code>, 6582 adds to the registry the pair <code>[tname] = new table</code>, 6583 and returns 1. 6584 (The entry <code>__name</code> is used by some error-reporting functions.) 6585 6586 6587 <p> 6588 In both cases pushes onto the stack the final value associated 6589 with <code>tname</code> in the registry. 6590 6591 6592 6593 6594 6595 <hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> 6596 <span class="apii">[-0, +0, –]</span> 6597 <pre>lua_State *luaL_newstate (void);</pre> 6598 6599 <p> 6600 Creates a new Lua state. 6601 It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an 6602 allocator based on the standard C <code>realloc</code> function 6603 and then sets a panic function (see <a href="#4.6">§4.6</a>) that prints 6604 an error message to the standard error output in case of fatal 6605 errors. 6606 6607 6608 <p> 6609 Returns the new state, 6610 or <code>NULL</code> if there is a memory allocation error. 6611 6612 6613 6614 6615 6616 <hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> 6617 <span class="apii">[-0, +0, <em>e</em>]</span> 6618 <pre>void luaL_openlibs (lua_State *L);</pre> 6619 6620 <p> 6621 Opens all standard Lua libraries into the given state. 6622 6623 6624 6625 6626 6627 <hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> 6628 <span class="apii">[-0, +0, <em>v</em>]</span> 6629 <pre>lua_Integer luaL_optinteger (lua_State *L, 6630 int arg, 6631 lua_Integer d);</pre> 6632 6633 <p> 6634 If the function argument <code>arg</code> is an integer 6635 (or convertible to an integer), 6636 returns this integer. 6637 If this argument is absent or is <b>nil</b>, 6638 returns <code>d</code>. 6639 Otherwise, raises an error. 6640 6641 6642 6643 6644 6645 <hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> 6646 <span class="apii">[-0, +0, <em>v</em>]</span> 6647 <pre>const char *luaL_optlstring (lua_State *L, 6648 int arg, 6649 const char *d, 6650 size_t *l);</pre> 6651 6652 <p> 6653 If the function argument <code>arg</code> is a string, 6654 returns this string. 6655 If this argument is absent or is <b>nil</b>, 6656 returns <code>d</code>. 6657 Otherwise, raises an error. 6658 6659 6660 <p> 6661 If <code>l</code> is not <code>NULL</code>, 6662 fills the position <code>*l</code> with the result's length. 6663 6664 6665 6666 6667 6668 <hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> 6669 <span class="apii">[-0, +0, <em>v</em>]</span> 6670 <pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre> 6671 6672 <p> 6673 If the function argument <code>arg</code> is a number, 6674 returns this number. 6675 If this argument is absent or is <b>nil</b>, 6676 returns <code>d</code>. 6677 Otherwise, raises an error. 6678 6679 6680 6681 6682 6683 <hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> 6684 <span class="apii">[-0, +0, <em>v</em>]</span> 6685 <pre>const char *luaL_optstring (lua_State *L, 6686 int arg, 6687 const char *d);</pre> 6688 6689 <p> 6690 If the function argument <code>arg</code> is a string, 6691 returns this string. 6692 If this argument is absent or is <b>nil</b>, 6693 returns <code>d</code>. 6694 Otherwise, raises an error. 6695 6696 6697 6698 6699 6700 <hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> 6701 <span class="apii">[-?, +?, <em>e</em>]</span> 6702 <pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> 6703 6704 <p> 6705 Equivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a> 6706 with the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>. 6707 6708 6709 6710 6711 6712 <hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p> 6713 <span class="apii">[-?, +?, <em>e</em>]</span> 6714 <pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre> 6715 6716 <p> 6717 Returns an address to a space of size <code>sz</code> 6718 where you can copy a string to be added to buffer <code>B</code> 6719 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6720 After copying the string into this space you must call 6721 <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add 6722 it to the buffer. 6723 6724 6725 6726 6727 6728 <hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> 6729 <span class="apii">[-?, +1, <em>e</em>]</span> 6730 <pre>void luaL_pushresult (luaL_Buffer *B);</pre> 6731 6732 <p> 6733 Finishes the use of buffer <code>B</code> leaving the final string on 6734 the top of the stack. 6735 6736 6737 6738 6739 6740 <hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p> 6741 <span class="apii">[-?, +1, <em>e</em>]</span> 6742 <pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre> 6743 6744 <p> 6745 Equivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>. 6746 6747 6748 6749 6750 6751 <hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> 6752 <span class="apii">[-1, +0, <em>e</em>]</span> 6753 <pre>int luaL_ref (lua_State *L, int t);</pre> 6754 6755 <p> 6756 Creates and returns a <em>reference</em>, 6757 in the table at index <code>t</code>, 6758 for the object at the top of the stack (and pops the object). 6759 6760 6761 <p> 6762 A reference is a unique integer key. 6763 As long as you do not manually add integer keys into table <code>t</code>, 6764 <a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. 6765 You can retrieve an object referred by reference <code>r</code> 6766 by calling <code>lua_rawgeti(L, t, r)</code>. 6767 Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object. 6768 6769 6770 <p> 6771 If the object at the top of the stack is <b>nil</b>, 6772 <a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>. 6773 The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different 6774 from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. 6775 6776 6777 6778 6779 6780 <hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> 6781 <pre>typedef struct luaL_Reg { 6782 const char *name; 6783 lua_CFunction func; 6784 } luaL_Reg;</pre> 6785 6786 <p> 6787 Type for arrays of functions to be registered by 6788 <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>. 6789 <code>name</code> is the function name and <code>func</code> is a pointer to 6790 the function. 6791 Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry 6792 in which both <code>name</code> and <code>func</code> are <code>NULL</code>. 6793 6794 6795 6796 6797 6798 <hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p> 6799 <span class="apii">[-0, +1, <em>e</em>]</span> 6800 <pre>void luaL_requiref (lua_State *L, const char *modname, 6801 lua_CFunction openf, int glb);</pre> 6802 6803 <p> 6804 If <code>modname</code> is not already present in <a href="#pdf-package.loaded"><code>package.loaded</code></a>, 6805 calls function <code>openf</code> with string <code>modname</code> as an argument 6806 and sets the call result in <code>package.loaded[modname]</code>, 6807 as if that function has been called through <a href="#pdf-require"><code>require</code></a>. 6808 6809 6810 <p> 6811 If <code>glb</code> is true, 6812 also stores the module into global <code>modname</code>. 6813 6814 6815 <p> 6816 Leaves a copy of the module on the stack. 6817 6818 6819 6820 6821 6822 <hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p> 6823 <span class="apii">[-nup, +0, <em>e</em>]</span> 6824 <pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre> 6825 6826 <p> 6827 Registers all functions in the array <code>l</code> 6828 (see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack 6829 (below optional upvalues, see next). 6830 6831 6832 <p> 6833 When <code>nup</code> is not zero, 6834 all functions are created sharing <code>nup</code> upvalues, 6835 which must be previously pushed on the stack 6836 on top of the library table. 6837 These values are popped from the stack after the registration. 6838 6839 6840 6841 6842 6843 <hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p> 6844 <span class="apii">[-0, +0, –]</span> 6845 <pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre> 6846 6847 <p> 6848 Sets the metatable of the object at the top of the stack 6849 as the metatable associated with name <code>tname</code> 6850 in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 6851 6852 6853 6854 6855 6856 <hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3> 6857 <pre>typedef struct luaL_Stream { 6858 FILE *f; 6859 lua_CFunction closef; 6860 } luaL_Stream;</pre> 6861 6862 <p> 6863 The standard representation for file handles, 6864 which is used by the standard I/O library. 6865 6866 6867 <p> 6868 A file handle is implemented as a full userdata, 6869 with a metatable called <code>LUA_FILEHANDLE</code> 6870 (where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name). 6871 The metatable is created by the I/O library 6872 (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 6873 6874 6875 <p> 6876 This userdata must start with the structure <code>luaL_Stream</code>; 6877 it can contain other data after this initial structure. 6878 Field <code>f</code> points to the corresponding C stream 6879 (or it can be <code>NULL</code> to indicate an incompletely created handle). 6880 Field <code>closef</code> points to a Lua function 6881 that will be called to close the stream 6882 when the handle is closed or collected; 6883 this function receives the file handle as its sole argument and 6884 must return either <b>true</b> (in case of success) 6885 or <b>nil</b> plus an error message (in case of error). 6886 Once Lua calls this field, 6887 the field value is changed to <code>NULL</code> 6888 to signal that the handle is closed. 6889 6890 6891 6892 6893 6894 <hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p> 6895 <span class="apii">[-0, +0, <em>e</em>]</span> 6896 <pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre> 6897 6898 <p> 6899 This function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>, 6900 except that, when the test fails, 6901 it returns <code>NULL</code> instead of raising an error. 6902 6903 6904 6905 6906 6907 <hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p> 6908 <span class="apii">[-0, +1, <em>e</em>]</span> 6909 <pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre> 6910 6911 <p> 6912 Converts any Lua value at the given index to a C string 6913 in a reasonable format. 6914 The resulting string is pushed onto the stack and also 6915 returned by the function. 6916 If <code>len</code> is not <code>NULL</code>, 6917 the function also sets <code>*len</code> with the string length. 6918 6919 6920 <p> 6921 If the value has a metatable with a <code>"__tostring"</code> field, 6922 then <code>luaL_tolstring</code> calls the corresponding metamethod 6923 with the value as argument, 6924 and uses the result of the call as its result. 6925 6926 6927 6928 6929 6930 <hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p> 6931 <span class="apii">[-0, +1, <em>e</em>]</span> 6932 <pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, 6933 int level);</pre> 6934 6935 <p> 6936 Creates and pushes a traceback of the stack <code>L1</code>. 6937 If <code>msg</code> is not <code>NULL</code> it is appended 6938 at the beginning of the traceback. 6939 The <code>level</code> parameter tells at which level 6940 to start the traceback. 6941 6942 6943 6944 6945 6946 <hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> 6947 <span class="apii">[-0, +0, –]</span> 6948 <pre>const char *luaL_typename (lua_State *L, int index);</pre> 6949 6950 <p> 6951 Returns the name of the type of the value at the given index. 6952 6953 6954 6955 6956 6957 <hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> 6958 <span class="apii">[-0, +0, –]</span> 6959 <pre>void luaL_unref (lua_State *L, int t, int ref);</pre> 6960 6961 <p> 6962 Releases reference <code>ref</code> from the table at index <code>t</code> 6963 (see <a href="#luaL_ref"><code>luaL_ref</code></a>). 6964 The entry is removed from the table, 6965 so that the referred object can be collected. 6966 The reference <code>ref</code> is also freed to be used again. 6967 6968 6969 <p> 6970 If <code>ref</code> is <a href="#pdf-LUA_NOREF"><code>LUA_NOREF</code></a> or <a href="#pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>, 6971 <a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. 6972 6973 6974 6975 6976 6977 <hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> 6978 <span class="apii">[-0, +1, <em>e</em>]</span> 6979 <pre>void luaL_where (lua_State *L, int lvl);</pre> 6980 6981 <p> 6982 Pushes onto the stack a string identifying the current position 6983 of the control at level <code>lvl</code> in the call stack. 6984 Typically this string has the following format: 6985 6986 <pre> 6987 <em>chunkname</em>:<em>currentline</em>: 6988 </pre><p> 6989 Level 0 is the running function, 6990 level 1 is the function that called the running function, 6991 etc. 6992 6993 6994 <p> 6995 This function is used to build a prefix for error messages. 6996 6997 6998 6999 7000 7001 7002 7003 <h1>6 – <a name="6">Standard Libraries</a></h1> 7004 7005 <p> 7006 The standard Lua libraries provide useful functions 7007 that are implemented directly through the C API. 7008 Some of these functions provide essential services to the language 7009 (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); 7010 others provide access to "outside" services (e.g., I/O); 7011 and others could be implemented in Lua itself, 7012 but are quite useful or have critical performance requirements that 7013 deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). 7014 7015 7016 <p> 7017 All libraries are implemented through the official C API 7018 and are provided as separate C modules. 7019 Currently, Lua has the following standard libraries: 7020 7021 <ul> 7022 7023 <li>basic library (<a href="#6.1">§6.1</a>);</li> 7024 7025 <li>coroutine library (<a href="#6.2">§6.2</a>);</li> 7026 7027 <li>package library (<a href="#6.3">§6.3</a>);</li> 7028 7029 <li>string manipulation (<a href="#6.4">§6.4</a>);</li> 7030 7031 <li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li> 7032 7033 <li>table manipulation (<a href="#6.6">§6.6</a>);</li> 7034 7035 <li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li> 7036 7037 <li>input and output (<a href="#6.8">§6.8</a>);</li> 7038 7039 <li>operating system facilities (<a href="#6.9">§6.9</a>);</li> 7040 7041 <li>debug facilities (<a href="#6.10">§6.10</a>).</li> 7042 7043 </ul><p> 7044 Except for the basic and the package libraries, 7045 each library provides all its functions as fields of a global table 7046 or as methods of its objects. 7047 7048 7049 <p> 7050 To have access to these libraries, 7051 the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, 7052 which opens all standard libraries. 7053 Alternatively, 7054 the host program can open them individually by using 7055 <a href="#luaL_requiref"><code>luaL_requiref</code></a> to call 7056 <a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), 7057 <a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), 7058 <a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library), 7059 <a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), 7060 <a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF8 library), 7061 <a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), 7062 <a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), 7063 <a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), 7064 <a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library), 7065 and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). 7066 These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>. 7067 7068 7069 7070 <h2>6.1 – <a name="6.1">Basic Functions</a></h2> 7071 7072 <p> 7073 The basic library provides core functions to Lua. 7074 If you do not include this library in your application, 7075 you should check carefully whether you need to provide 7076 implementations for some of its facilities. 7077 7078 7079 <p> 7080 <hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> 7081 7082 7083 <p> 7084 Calls <a href="#pdf-error"><code>error</code></a> if 7085 the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); 7086 otherwise, returns all its arguments. 7087 In case of error, 7088 <code>message</code> is the error object; 7089 when absent, it defaults to "<code>assertion failed!</code>" 7090 7091 7092 7093 7094 <p> 7095 <hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3> 7096 7097 7098 <p> 7099 This function is a generic interface to the garbage collector. 7100 It performs different functions according to its first argument, <code>opt</code>: 7101 7102 <ul> 7103 7104 <li><b>"<code>collect</code>": </b> 7105 performs a full garbage-collection cycle. 7106 This is the default option. 7107 </li> 7108 7109 <li><b>"<code>stop</code>": </b> 7110 stops automatic execution of the garbage collector. 7111 The collector will run only when explicitly invoked, 7112 until a call to restart it. 7113 </li> 7114 7115 <li><b>"<code>restart</code>": </b> 7116 restarts automatic execution of the garbage collector. 7117 </li> 7118 7119 <li><b>"<code>count</code>": </b> 7120 returns the total memory in use by Lua in Kbytes. 7121 The value has a fractional part, 7122 so that it multiplied by 1024 7123 gives the exact number of bytes in use by Lua 7124 (except for overflows). 7125 </li> 7126 7127 <li><b>"<code>step</code>": </b> 7128 performs a garbage-collection step. 7129 The step "size" is controlled by <code>arg</code>. 7130 With a zero value, 7131 the collector will perform one basic (indivisible) step. 7132 For non-zero values, 7133 the collector will perform as if that amount of memory 7134 (in KBytes) had been allocated by Lua. 7135 Returns <b>true</b> if the step finished a collection cycle. 7136 </li> 7137 7138 <li><b>"<code>setpause</code>": </b> 7139 sets <code>arg</code> as the new value for the <em>pause</em> of 7140 the collector (see <a href="#2.5">§2.5</a>). 7141 Returns the previous value for <em>pause</em>. 7142 </li> 7143 7144 <li><b>"<code>setstepmul</code>": </b> 7145 sets <code>arg</code> as the new value for the <em>step multiplier</em> of 7146 the collector (see <a href="#2.5">§2.5</a>). 7147 Returns the previous value for <em>step</em>. 7148 </li> 7149 7150 <li><b>"<code>isrunning</code>": </b> 7151 returns a boolean that tells whether the collector is running 7152 (i.e., not stopped). 7153 </li> 7154 7155 </ul> 7156 7157 7158 7159 <p> 7160 <hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> 7161 Opens the named file and executes its contents as a Lua chunk. 7162 When called without arguments, 7163 <code>dofile</code> executes the contents of the standard input (<code>stdin</code>). 7164 Returns all values returned by the chunk. 7165 In case of errors, <code>dofile</code> propagates the error 7166 to its caller (that is, <code>dofile</code> does not run in protected mode). 7167 7168 7169 7170 7171 <p> 7172 <hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> 7173 Terminates the last protected function called 7174 and returns <code>message</code> as the error object. 7175 Function <code>error</code> never returns. 7176 7177 7178 <p> 7179 Usually, <code>error</code> adds some information about the error position 7180 at the beginning of the message, if the message is a string. 7181 The <code>level</code> argument specifies how to get the error position. 7182 With level 1 (the default), the error position is where the 7183 <code>error</code> function was called. 7184 Level 2 points the error to where the function 7185 that called <code>error</code> was called; and so on. 7186 Passing a level 0 avoids the addition of error position information 7187 to the message. 7188 7189 7190 7191 7192 <p> 7193 <hr><h3><a name="pdf-_G"><code>_G</code></a></h3> 7194 A global variable (not a function) that 7195 holds the global environment (see <a href="#2.2">§2.2</a>). 7196 Lua itself does not use this variable; 7197 changing its value does not affect any environment, 7198 nor vice versa. 7199 7200 7201 7202 7203 <p> 7204 <hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> 7205 7206 7207 <p> 7208 If <code>object</code> does not have a metatable, returns <b>nil</b>. 7209 Otherwise, 7210 if the object's metatable has a <code>"__metatable"</code> field, 7211 returns the associated value. 7212 Otherwise, returns the metatable of the given object. 7213 7214 7215 7216 7217 <p> 7218 <hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> 7219 7220 7221 <p> 7222 Returns three values (an iterator function, the table <code>t</code>, and 0) 7223 so that the construction 7224 7225 <pre> 7226 for i,v in ipairs(t) do <em>body</em> end 7227 </pre><p> 7228 will iterate over the key–value pairs 7229 (<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., 7230 up to the first nil value. 7231 7232 7233 7234 7235 <p> 7236 <hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3> 7237 7238 7239 <p> 7240 Loads a chunk. 7241 7242 7243 <p> 7244 If <code>chunk</code> is a string, the chunk is this string. 7245 If <code>chunk</code> is a function, 7246 <code>load</code> calls it repeatedly to get the chunk pieces. 7247 Each call to <code>chunk</code> must return a string that concatenates 7248 with previous results. 7249 A return of an empty string, <b>nil</b>, or no value signals the end of the chunk. 7250 7251 7252 <p> 7253 If there are no syntactic errors, 7254 returns the compiled chunk as a function; 7255 otherwise, returns <b>nil</b> plus the error message. 7256 7257 7258 <p> 7259 If the resulting function has upvalues, 7260 the first upvalue is set to the value of <code>env</code>, 7261 if that parameter is given, 7262 or to the value of the global environment. 7263 Other upvalues are initialized with <b>nil</b>. 7264 (When you load a main chunk, 7265 the resulting function will always have exactly one upvalue, 7266 the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 7267 However, 7268 when you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>), 7269 the resulting function can have an arbitrary number of upvalues.) 7270 All upvalues are fresh, that is, 7271 they are not shared with any other function. 7272 7273 7274 <p> 7275 <code>chunkname</code> is used as the name of the chunk for error messages 7276 and debug information (see <a href="#4.9">§4.9</a>). 7277 When absent, 7278 it defaults to <code>chunk</code>, if <code>chunk</code> is a string, 7279 or to "<code>=(load)</code>" otherwise. 7280 7281 7282 <p> 7283 The string <code>mode</code> controls whether the chunk can be text or binary 7284 (that is, a precompiled chunk). 7285 It may be the string "<code>b</code>" (only binary chunks), 7286 "<code>t</code>" (only text chunks), 7287 or "<code>bt</code>" (both binary and text). 7288 The default is "<code>bt</code>". 7289 7290 7291 <p> 7292 Lua does not check the consistency of binary chunks. 7293 Maliciously crafted binary chunks can crash 7294 the interpreter. 7295 7296 7297 7298 7299 <p> 7300 <hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3> 7301 7302 7303 <p> 7304 Similar to <a href="#pdf-load"><code>load</code></a>, 7305 but gets the chunk from file <code>filename</code> 7306 or from the standard input, 7307 if no file name is given. 7308 7309 7310 7311 7312 <p> 7313 <hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> 7314 7315 7316 <p> 7317 Allows a program to traverse all fields of a table. 7318 Its first argument is a table and its second argument 7319 is an index in this table. 7320 <code>next</code> returns the next index of the table 7321 and its associated value. 7322 When called with <b>nil</b> as its second argument, 7323 <code>next</code> returns an initial index 7324 and its associated value. 7325 When called with the last index, 7326 or with <b>nil</b> in an empty table, 7327 <code>next</code> returns <b>nil</b>. 7328 If the second argument is absent, then it is interpreted as <b>nil</b>. 7329 In particular, 7330 you can use <code>next(t)</code> to check whether a table is empty. 7331 7332 7333 <p> 7334 The order in which the indices are enumerated is not specified, 7335 <em>even for numeric indices</em>. 7336 (To traverse a table in numeric order, 7337 use a numerical <b>for</b>.) 7338 7339 7340 <p> 7341 The behavior of <code>next</code> is undefined if, 7342 during the traversal, 7343 you assign any value to a non-existent field in the table. 7344 You may however modify existing fields. 7345 In particular, you may clear existing fields. 7346 7347 7348 7349 7350 <p> 7351 <hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> 7352 7353 7354 <p> 7355 If <code>t</code> has a metamethod <code>__pairs</code>, 7356 calls it with <code>t</code> as argument and returns the first three 7357 results from the call. 7358 7359 7360 <p> 7361 Otherwise, 7362 returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, 7363 so that the construction 7364 7365 <pre> 7366 for k,v in pairs(t) do <em>body</em> end 7367 </pre><p> 7368 will iterate over all key–value pairs of table <code>t</code>. 7369 7370 7371 <p> 7372 See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 7373 the table during its traversal. 7374 7375 7376 7377 7378 <p> 7379 <hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3> 7380 7381 7382 <p> 7383 Calls function <code>f</code> with 7384 the given arguments in <em>protected mode</em>. 7385 This means that any error inside <code>f</code> is not propagated; 7386 instead, <code>pcall</code> catches the error 7387 and returns a status code. 7388 Its first result is the status code (a boolean), 7389 which is true if the call succeeds without errors. 7390 In such case, <code>pcall</code> also returns all results from the call, 7391 after this first result. 7392 In case of any error, <code>pcall</code> returns <b>false</b> plus the error message. 7393 7394 7395 7396 7397 <p> 7398 <hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> 7399 Receives any number of arguments 7400 and prints their values to <code>stdout</code>, 7401 using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string. 7402 <code>print</code> is not intended for formatted output, 7403 but only as a quick way to show a value, 7404 for instance for debugging. 7405 For complete control over the output, 7406 use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. 7407 7408 7409 7410 7411 <p> 7412 <hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> 7413 Checks whether <code>v1</code> is equal to <code>v2</code>, 7414 without invoking any metamethod. 7415 Returns a boolean. 7416 7417 7418 7419 7420 <p> 7421 <hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> 7422 Gets the real value of <code>table[index]</code>, 7423 without invoking any metamethod. 7424 <code>table</code> must be a table; 7425 <code>index</code> may be any value. 7426 7427 7428 7429 7430 <p> 7431 <hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3> 7432 Returns the length of the object <code>v</code>, 7433 which must be a table or a string, 7434 without invoking any metamethod. 7435 Returns an integer. 7436 7437 7438 7439 7440 <p> 7441 <hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> 7442 Sets the real value of <code>table[index]</code> to <code>value</code>, 7443 without invoking any metamethod. 7444 <code>table</code> must be a table, 7445 <code>index</code> any value different from <b>nil</b> and NaN, 7446 and <code>value</code> any Lua value. 7447 7448 7449 <p> 7450 This function returns <code>table</code>. 7451 7452 7453 7454 7455 <p> 7456 <hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> 7457 7458 7459 <p> 7460 If <code>index</code> is a number, 7461 returns all arguments after argument number <code>index</code>; 7462 a negative number indexes from the end (-1 is the last argument). 7463 Otherwise, <code>index</code> must be the string <code>"#"</code>, 7464 and <code>select</code> returns the total number of extra arguments it received. 7465 7466 7467 7468 7469 <p> 7470 <hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> 7471 7472 7473 <p> 7474 Sets the metatable for the given table. 7475 (You cannot change the metatable of other types from Lua, only from C.) 7476 If <code>metatable</code> is <b>nil</b>, 7477 removes the metatable of the given table. 7478 If the original metatable has a <code>"__metatable"</code> field, 7479 raises an error. 7480 7481 7482 <p> 7483 This function returns <code>table</code>. 7484 7485 7486 7487 7488 <p> 7489 <hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> 7490 7491 7492 <p> 7493 When called with no <code>base</code>, 7494 <code>tonumber</code> tries to convert its argument to a number. 7495 If the argument is already a number or 7496 a string convertible to a number, 7497 then <code>tonumber</code> returns this number; 7498 otherwise, it returns <b>nil</b>. 7499 7500 7501 <p> 7502 The conversion of strings can result in integers or floats, 7503 according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 7504 (The string may have leading and trailing spaces and a sign.) 7505 7506 7507 <p> 7508 When called with <code>base</code>, 7509 then <code>e</code> must be a string to be interpreted as 7510 an integer numeral in that base. 7511 The base may be any integer between 2 and 36, inclusive. 7512 In bases above 10, the letter '<code>A</code>' (in either upper or lower case) 7513 represents 10, '<code>B</code>' represents 11, and so forth, 7514 with '<code>Z</code>' representing 35. 7515 If the string <code>e</code> is not a valid numeral in the given base, 7516 the function returns <b>nil</b>. 7517 7518 7519 7520 7521 <p> 7522 <hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3> 7523 Receives a value of any type and 7524 converts it to a string in a human-readable format. 7525 Floats always produce strings with some 7526 floating-point indication (either a decimal dot or an exponent). 7527 (For complete control of how numbers are converted, 7528 use <a href="#pdf-string.format"><code>string.format</code></a>.) 7529 7530 7531 <p> 7532 If the metatable of <code>v</code> has a <code>"__tostring"</code> field, 7533 then <code>tostring</code> calls the corresponding value 7534 with <code>v</code> as argument, 7535 and uses the result of the call as its result. 7536 7537 7538 7539 7540 <p> 7541 <hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> 7542 Returns the type of its only argument, coded as a string. 7543 The possible results of this function are 7544 "<code>nil</code>" (a string, not the value <b>nil</b>), 7545 "<code>number</code>", 7546 "<code>string</code>", 7547 "<code>boolean</code>", 7548 "<code>table</code>", 7549 "<code>function</code>", 7550 "<code>thread</code>", 7551 and "<code>userdata</code>". 7552 7553 7554 7555 7556 <p> 7557 <hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> 7558 A global variable (not a function) that 7559 holds a string containing the current interpreter version. 7560 The current value of this variable is "<code>Lua 5.3</code>". 7561 7562 7563 7564 7565 <p> 7566 <hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3> 7567 7568 7569 <p> 7570 This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, 7571 except that it sets a new message handler <code>msgh</code>. 7572 7573 7574 7575 7576 7577 7578 7579 <h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2> 7580 7581 <p> 7582 The operations related to coroutines comprise a sub-library of 7583 the basic library and come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. 7584 See <a href="#2.6">§2.6</a> for a general description of coroutines. 7585 7586 7587 <p> 7588 <hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> 7589 7590 7591 <p> 7592 Creates a new coroutine, with body <code>f</code>. 7593 <code>f</code> must be a Lua function. 7594 Returns this new coroutine, 7595 an object with type <code>"thread"</code>. 7596 7597 7598 7599 7600 <p> 7601 <hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ()</code></a></h3> 7602 7603 7604 <p> 7605 Returns true when the running coroutine can yield. 7606 7607 7608 <p> 7609 A running coroutine is yieldable if it is not the main thread and 7610 it is not inside a non-yieldable C function. 7611 7612 7613 7614 7615 <p> 7616 <hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> 7617 7618 7619 <p> 7620 Starts or continues the execution of coroutine <code>co</code>. 7621 The first time you resume a coroutine, 7622 it starts running its body. 7623 The values <code>val1</code>, ... are passed 7624 as the arguments to the body function. 7625 If the coroutine has yielded, 7626 <code>resume</code> restarts it; 7627 the values <code>val1</code>, ... are passed 7628 as the results from the yield. 7629 7630 7631 <p> 7632 If the coroutine runs without any errors, 7633 <code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> 7634 (when the coroutine yields) or any values returned by the body function 7635 (when the coroutine terminates). 7636 If there is any error, 7637 <code>resume</code> returns <b>false</b> plus the error message. 7638 7639 7640 7641 7642 <p> 7643 <hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> 7644 7645 7646 <p> 7647 Returns the running coroutine plus a boolean, 7648 true when the running coroutine is the main one. 7649 7650 7651 7652 7653 <p> 7654 <hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> 7655 7656 7657 <p> 7658 Returns the status of coroutine <code>co</code>, as a string: 7659 <code>"running"</code>, 7660 if the coroutine is running (that is, it called <code>status</code>); 7661 <code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, 7662 or if it has not started running yet; 7663 <code>"normal"</code> if the coroutine is active but not running 7664 (that is, it has resumed another coroutine); 7665 and <code>"dead"</code> if the coroutine has finished its body function, 7666 or if it has stopped with an error. 7667 7668 7669 7670 7671 <p> 7672 <hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> 7673 7674 7675 <p> 7676 Creates a new coroutine, with body <code>f</code>. 7677 <code>f</code> must be a Lua function. 7678 Returns a function that resumes the coroutine each time it is called. 7679 Any arguments passed to the function behave as the 7680 extra arguments to <code>resume</code>. 7681 Returns the same values returned by <code>resume</code>, 7682 except the first boolean. 7683 In case of error, propagates the error. 7684 7685 7686 7687 7688 <p> 7689 <hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> 7690 7691 7692 <p> 7693 Suspends the execution of the calling coroutine. 7694 Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>. 7695 7696 7697 7698 7699 7700 7701 7702 <h2>6.3 – <a name="6.3">Modules</a></h2> 7703 7704 <p> 7705 The package library provides basic 7706 facilities for loading modules in Lua. 7707 It exports one function directly in the global environment: 7708 <a href="#pdf-require"><code>require</code></a>. 7709 Everything else is exported in a table <a name="pdf-package"><code>package</code></a>. 7710 7711 7712 <p> 7713 <hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> 7714 7715 7716 <p> 7717 Loads the given module. 7718 The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table 7719 to determine whether <code>modname</code> is already loaded. 7720 If it is, then <code>require</code> returns the value stored 7721 at <code>package.loaded[modname]</code>. 7722 Otherwise, it tries to find a <em>loader</em> for the module. 7723 7724 7725 <p> 7726 To find a loader, 7727 <code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence. 7728 By changing this sequence, 7729 we can change how <code>require</code> looks for a module. 7730 The following explanation is based on the default configuration 7731 for <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 7732 7733 7734 <p> 7735 First <code>require</code> queries <code>package.preload[modname]</code>. 7736 If it has a value, 7737 this value (which must be a function) is the loader. 7738 Otherwise <code>require</code> searches for a Lua loader using the 7739 path stored in <a href="#pdf-package.path"><code>package.path</code></a>. 7740 If that also fails, it searches for a C loader using the 7741 path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 7742 If that also fails, 7743 it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>). 7744 7745 7746 <p> 7747 Once a loader is found, 7748 <code>require</code> calls the loader with two arguments: 7749 <code>modname</code> and an extra value dependent on how it got the loader. 7750 (If the loader came from a file, 7751 this extra value is the file name.) 7752 If the loader returns any non-nil value, 7753 <code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. 7754 If the loader does not return a non-nil value and 7755 has not assigned any value to <code>package.loaded[modname]</code>, 7756 then <code>require</code> assigns <b>true</b> to this entry. 7757 In any case, <code>require</code> returns the 7758 final value of <code>package.loaded[modname]</code>. 7759 7760 7761 <p> 7762 If there is any error loading or running the module, 7763 or if it cannot find any loader for the module, 7764 then <code>require</code> raises an error. 7765 7766 7767 7768 7769 <p> 7770 <hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3> 7771 7772 7773 <p> 7774 A string describing some compile-time configurations for packages. 7775 This string is a sequence of lines: 7776 7777 <ul> 7778 7779 <li>The first line is the directory separator string. 7780 Default is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li> 7781 7782 <li>The second line is the character that separates templates in a path. 7783 Default is '<code>;</code>'.</li> 7784 7785 <li>The third line is the string that marks the 7786 substitution points in a template. 7787 Default is '<code>?</code>'.</li> 7788 7789 <li>The fourth line is a string that, in a path in Windows, 7790 is replaced by the executable's directory. 7791 Default is '<code>!</code>'.</li> 7792 7793 <li>The fifth line is a mark to ignore all text after it 7794 when building the <code>luaopen_</code> function name. 7795 Default is '<code>-</code>'.</li> 7796 7797 </ul> 7798 7799 7800 7801 <p> 7802 <hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> 7803 7804 7805 <p> 7806 The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. 7807 7808 7809 <p> 7810 Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way 7811 it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, 7812 using the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a> 7813 or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a> 7814 or a default path defined in <code>luaconf.h</code>. 7815 7816 7817 7818 7819 <p> 7820 <hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> 7821 7822 7823 <p> 7824 A table used by <a href="#pdf-require"><code>require</code></a> to control which 7825 modules are already loaded. 7826 When you require a module <code>modname</code> and 7827 <code>package.loaded[modname]</code> is not false, 7828 <a href="#pdf-require"><code>require</code></a> simply returns the value stored there. 7829 7830 7831 <p> 7832 This variable is only a reference to the real table; 7833 assignments to this variable do not change the 7834 table used by <a href="#pdf-require"><code>require</code></a>. 7835 7836 7837 7838 7839 <p> 7840 <hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> 7841 7842 7843 <p> 7844 Dynamically links the host program with the C library <code>libname</code>. 7845 7846 7847 <p> 7848 If <code>funcname</code> is "<code>*</code>", 7849 then it only links with the library, 7850 making the symbols exported by the library 7851 available to other dynamically linked libraries. 7852 Otherwise, 7853 it looks for a function <code>funcname</code> inside the library 7854 and returns this function as a C function. 7855 So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype 7856 (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 7857 7858 7859 <p> 7860 This is a low-level function. 7861 It completely bypasses the package and module system. 7862 Unlike <a href="#pdf-require"><code>require</code></a>, 7863 it does not perform any path searching and 7864 does not automatically adds extensions. 7865 <code>libname</code> must be the complete file name of the C library, 7866 including if necessary a path and an extension. 7867 <code>funcname</code> must be the exact name exported by the C library 7868 (which may depend on the C compiler and linker used). 7869 7870 7871 <p> 7872 This function is not supported by Standard C. 7873 As such, it is only available on some platforms 7874 (Windows, Linux, Mac OS X, Solaris, BSD, 7875 plus other Unix systems that support the <code>dlfcn</code> standard). 7876 7877 7878 7879 7880 <p> 7881 <hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> 7882 7883 7884 <p> 7885 The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. 7886 7887 7888 <p> 7889 At start-up, Lua initializes this variable with 7890 the value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or 7891 the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or 7892 with a default path defined in <code>luaconf.h</code>, 7893 if those environment variables are not defined. 7894 Any "<code>;;</code>" in the value of the environment variable 7895 is replaced by the default path. 7896 7897 7898 7899 7900 <p> 7901 <hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> 7902 7903 7904 <p> 7905 A table to store loaders for specific modules 7906 (see <a href="#pdf-require"><code>require</code></a>). 7907 7908 7909 <p> 7910 This variable is only a reference to the real table; 7911 assignments to this variable do not change the 7912 table used by <a href="#pdf-require"><code>require</code></a>. 7913 7914 7915 7916 7917 <p> 7918 <hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3> 7919 7920 7921 <p> 7922 A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules. 7923 7924 7925 <p> 7926 Each entry in this table is a <em>searcher function</em>. 7927 When looking for a module, 7928 <a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, 7929 with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its 7930 sole parameter. 7931 The function can return another function (the module <em>loader</em>) 7932 plus an extra value that will be passed to that loader, 7933 or a string explaining why it did not find that module 7934 (or <b>nil</b> if it has nothing to say). 7935 7936 7937 <p> 7938 Lua initializes this table with four searcher functions. 7939 7940 7941 <p> 7942 The first searcher simply looks for a loader in the 7943 <a href="#pdf-package.preload"><code>package.preload</code></a> table. 7944 7945 7946 <p> 7947 The second searcher looks for a loader as a Lua library, 7948 using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. 7949 The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 7950 7951 7952 <p> 7953 The third searcher looks for a loader as a C library, 7954 using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 7955 Again, 7956 the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 7957 For instance, 7958 if the C path is the string 7959 7960 <pre> 7961 "./?.so;./?.dll;/usr/local/?/init.so" 7962 </pre><p> 7963 the searcher for module <code>foo</code> 7964 will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, 7965 and <code>/usr/local/foo/init.so</code>, in that order. 7966 Once it finds a C library, 7967 this searcher first uses a dynamic link facility to link the 7968 application with the library. 7969 Then it tries to find a C function inside the library to 7970 be used as the loader. 7971 The name of this C function is the string "<code>luaopen_</code>" 7972 concatenated with a copy of the module name where each dot 7973 is replaced by an underscore. 7974 Moreover, if the module name has a hyphen, 7975 its suffix after (and including) the first hyphen is removed. 7976 For instance, if the module name is <code>a.b.c-v2.1</code>, 7977 the function name will be <code>luaopen_a_b_c</code>. 7978 7979 7980 <p> 7981 The fourth searcher tries an <em>all-in-one loader</em>. 7982 It searches the C path for a library for 7983 the root name of the given module. 7984 For instance, when requiring <code>a.b.c</code>, 7985 it will search for a C library for <code>a</code>. 7986 If found, it looks into it for an open function for 7987 the submodule; 7988 in our example, that would be <code>luaopen_a_b_c</code>. 7989 With this facility, a package can pack several C submodules 7990 into one single library, 7991 with each submodule keeping its original open function. 7992 7993 7994 <p> 7995 All searchers except the first one (preload) return as the extra value 7996 the file name where the module was found, 7997 as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 7998 The first searcher returns no extra value. 7999 8000 8001 8002 8003 <p> 8004 <hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3> 8005 8006 8007 <p> 8008 Searches for the given <code>name</code> in the given <code>path</code>. 8009 8010 8011 <p> 8012 A path is a string containing a sequence of 8013 <em>templates</em> separated by semicolons. 8014 For each template, 8015 the function replaces each interrogation mark (if any) 8016 in the template with a copy of <code>name</code> 8017 wherein all occurrences of <code>sep</code> 8018 (a dot, by default) 8019 were replaced by <code>rep</code> 8020 (the system's directory separator, by default), 8021 and then tries to open the resulting file name. 8022 8023 8024 <p> 8025 For instance, if the path is the string 8026 8027 <pre> 8028 "./?.lua;./?.lc;/usr/local/?/init.lua" 8029 </pre><p> 8030 the search for the name <code>foo.a</code> 8031 will try to open the files 8032 <code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and 8033 <code>/usr/local/foo/a/init.lua</code>, in that order. 8034 8035 8036 <p> 8037 Returns the resulting name of the first file that it can 8038 open in read mode (after closing the file), 8039 or <b>nil</b> plus an error message if none succeeds. 8040 (This error message lists all file names it tried to open.) 8041 8042 8043 8044 8045 8046 8047 8048 <h2>6.4 – <a name="6.4">String Manipulation</a></h2> 8049 8050 <p> 8051 This library provides generic functions for string manipulation, 8052 such as finding and extracting substrings, and pattern matching. 8053 When indexing a string in Lua, the first character is at position 1 8054 (not at 0, as in C). 8055 Indices are allowed to be negative and are interpreted as indexing backwards, 8056 from the end of the string. 8057 Thus, the last character is at position -1, and so on. 8058 8059 8060 <p> 8061 The string library provides all its functions inside the table 8062 <a name="pdf-string"><code>string</code></a>. 8063 It also sets a metatable for strings 8064 where the <code>__index</code> field points to the <code>string</code> table. 8065 Therefore, you can use the string functions in object-oriented style. 8066 For instance, <code>string.byte(s,i)</code> 8067 can be written as <code>s:byte(i)</code>. 8068 8069 8070 <p> 8071 The string library assumes one-byte character encodings. 8072 8073 8074 <p> 8075 <hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> 8076 Returns the internal numerical codes of the characters <code>s[i]</code>, 8077 <code>s[i+1]</code>, ..., <code>s[j]</code>. 8078 The default value for <code>i</code> is 1; 8079 the default value for <code>j</code> is <code>i</code>. 8080 These indices are corrected 8081 following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>. 8082 8083 8084 <p> 8085 Numerical codes are not necessarily portable across platforms. 8086 8087 8088 8089 8090 <p> 8091 <hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> 8092 Receives zero or more integers. 8093 Returns a string with length equal to the number of arguments, 8094 in which each character has the internal numerical code equal 8095 to its corresponding argument. 8096 8097 8098 <p> 8099 Numerical codes are not necessarily portable across platforms. 8100 8101 8102 8103 8104 <p> 8105 <hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3> 8106 8107 8108 <p> 8109 Returns a string containing a binary representation 8110 (a <em>binary chunk</em>) 8111 of the given function, 8112 so that a later <a href="#pdf-load"><code>load</code></a> on this string returns 8113 a copy of the function (but with new upvalues). 8114 If <code>strip</code> is a true value, 8115 the binary representation is created without debug information 8116 about the function 8117 (local variable names, lines, etc.). 8118 8119 8120 <p> 8121 Functions with upvalues have only their number of upvalues saved. 8122 When (re)loaded, 8123 those upvalues receive fresh instances containing <b>nil</b>. 8124 (You can use the debug library to serialize 8125 and reload the upvalues of a function 8126 in a way adequate to your needs.) 8127 8128 8129 8130 8131 <p> 8132 <hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> 8133 8134 8135 <p> 8136 Looks for the first match of 8137 <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 8138 If it finds a match, then <code>find</code> returns the indices of <code>s</code> 8139 where this occurrence starts and ends; 8140 otherwise, it returns <b>nil</b>. 8141 A third, optional numerical argument <code>init</code> specifies 8142 where to start the search; 8143 its default value is 1 and can be negative. 8144 A value of <b>true</b> as a fourth, optional argument <code>plain</code> 8145 turns off the pattern matching facilities, 8146 so the function does a plain "find substring" operation, 8147 with no characters in <code>pattern</code> being considered magic. 8148 Note that if <code>plain</code> is given, then <code>init</code> must be given as well. 8149 8150 8151 <p> 8152 If the pattern has captures, 8153 then in a successful match 8154 the captured values are also returned, 8155 after the two indices. 8156 8157 8158 8159 8160 <p> 8161 <hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> 8162 8163 8164 <p> 8165 Returns a formatted version of its variable number of arguments 8166 following the description given in its first argument (which must be a string). 8167 The format string follows the same rules as the ISO C function <code>sprintf</code>. 8168 The only differences are that the options/modifiers 8169 <code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>, 8170 and <code>p</code> are not supported 8171 and that there is an extra option, <code>q</code>. 8172 The <code>q</code> option formats a string between double quotes, 8173 using escape sequences when necessary to ensure that 8174 it can safely be read back by the Lua interpreter. 8175 For instance, the call 8176 8177 <pre> 8178 string.format('%q', 'a string with "quotes" and \n new line') 8179 </pre><p> 8180 may produce the string: 8181 8182 <pre> 8183 "a string with \"quotes\" and \ 8184 new line" 8185 </pre> 8186 8187 <p> 8188 Options 8189 <code>A</code> and <code>a</code> (when available), 8190 <code>E</code>, <code>e</code>, <code>f</code>, 8191 <code>G</code>, and <code>g</code> all expect a number as argument. 8192 Options <code>c</code>, <code>d</code>, 8193 <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> 8194 expect an integer. 8195 Option <code>q</code> expects a string; 8196 option <code>s</code> expects a string without embedded zeros. 8197 If the argument to option <code>s</code> is not a string, 8198 it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 8199 8200 8201 8202 8203 <p> 8204 <hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3> 8205 Returns an iterator function that, 8206 each time it is called, 8207 returns the next captures from <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) 8208 over the string <code>s</code>. 8209 If <code>pattern</code> specifies no captures, 8210 then the whole match is produced in each call. 8211 8212 8213 <p> 8214 As an example, the following loop 8215 will iterate over all the words from string <code>s</code>, 8216 printing one per line: 8217 8218 <pre> 8219 s = "hello world from Lua" 8220 for w in string.gmatch(s, "%a+") do 8221 print(w) 8222 end 8223 </pre><p> 8224 The next example collects all pairs <code>key=value</code> from the 8225 given string into a table: 8226 8227 <pre> 8228 t = {} 8229 s = "from=world, to=Lua" 8230 for k, v in string.gmatch(s, "(%w+)=(%w+)") do 8231 t[k] = v 8232 end 8233 </pre> 8234 8235 <p> 8236 For this function, a caret '<code>^</code>' at the start of a pattern does not 8237 work as an anchor, as this would prevent the iteration. 8238 8239 8240 8241 8242 <p> 8243 <hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> 8244 Returns a copy of <code>s</code> 8245 in which all (or the first <code>n</code>, if given) 8246 occurrences of the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) have been 8247 replaced by a replacement string specified by <code>repl</code>, 8248 which can be a string, a table, or a function. 8249 <code>gsub</code> also returns, as its second value, 8250 the total number of matches that occurred. 8251 The name <code>gsub</code> comes from <em>Global SUBstitution</em>. 8252 8253 8254 <p> 8255 If <code>repl</code> is a string, then its value is used for replacement. 8256 The character <code>%</code> works as an escape character: 8257 any sequence in <code>repl</code> of the form <code>%<em>d</em></code>, 8258 with <em>d</em> between 1 and 9, 8259 stands for the value of the <em>d</em>-th captured substring. 8260 The sequence <code>%0</code> stands for the whole match. 8261 The sequence <code>%%</code> stands for a single <code>%</code>. 8262 8263 8264 <p> 8265 If <code>repl</code> is a table, then the table is queried for every match, 8266 using the first capture as the key. 8267 8268 8269 <p> 8270 If <code>repl</code> is a function, then this function is called every time a 8271 match occurs, with all captured substrings passed as arguments, 8272 in order. 8273 8274 8275 <p> 8276 In any case, 8277 if the pattern specifies no captures, 8278 then it behaves as if the whole pattern was inside a capture. 8279 8280 8281 <p> 8282 If the value returned by the table query or by the function call 8283 is a string or a number, 8284 then it is used as the replacement string; 8285 otherwise, if it is <b>false</b> or <b>nil</b>, 8286 then there is no replacement 8287 (that is, the original match is kept in the string). 8288 8289 8290 <p> 8291 Here are some examples: 8292 8293 <pre> 8294 x = string.gsub("hello world", "(%w+)", "%1 %1") 8295 --> x="hello hello world world" 8296 8297 x = string.gsub("hello world", "%w+", "%0 %0", 1) 8298 --> x="hello hello world" 8299 8300 x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 8301 --> x="world hello Lua from" 8302 8303 x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) 8304 --> x="home = /home/roberto, user = roberto" 8305 8306 x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 8307 return load(s)() 8308 end) 8309 --> x="4+5 = 9" 8310 8311 local t = {name="lua", version="5.3"} 8312 x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 8313 --> x="lua-5.3.tar.gz" 8314 </pre> 8315 8316 8317 8318 <p> 8319 <hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> 8320 Receives a string and returns its length. 8321 The empty string <code>""</code> has length 0. 8322 Embedded zeros are counted, 8323 so <code>"a\000bc\000"</code> has length 5. 8324 8325 8326 8327 8328 <p> 8329 <hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> 8330 Receives a string and returns a copy of this string with all 8331 uppercase letters changed to lowercase. 8332 All other characters are left unchanged. 8333 The definition of what an uppercase letter is depends on the current locale. 8334 8335 8336 8337 8338 <p> 8339 <hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> 8340 Looks for the first <em>match</em> of 8341 <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 8342 If it finds one, then <code>match</code> returns 8343 the captures from the pattern; 8344 otherwise it returns <b>nil</b>. 8345 If <code>pattern</code> specifies no captures, 8346 then the whole match is returned. 8347 A third, optional numerical argument <code>init</code> specifies 8348 where to start the search; 8349 its default value is 1 and can be negative. 8350 8351 8352 8353 8354 <p> 8355 <hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, ···)</code></a></h3> 8356 8357 8358 <p> 8359 Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc. 8360 packed (that is, serialized in binary form) 8361 according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 8362 8363 8364 8365 8366 <p> 8367 <hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3> 8368 8369 8370 <p> 8371 Returns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a> 8372 with the given format. 8373 The format string cannot have the variable-length options 8374 '<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">§6.4.2</a>). 8375 8376 8377 8378 8379 <p> 8380 <hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3> 8381 Returns a string that is the concatenation of <code>n</code> copies of 8382 the string <code>s</code> separated by the string <code>sep</code>. 8383 The default value for <code>sep</code> is the empty string 8384 (that is, no separator). 8385 Returns the empty string if <code>n</code> is not positive. 8386 8387 8388 8389 8390 <p> 8391 <hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> 8392 Returns a string that is the string <code>s</code> reversed. 8393 8394 8395 8396 8397 <p> 8398 <hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> 8399 Returns the substring of <code>s</code> that 8400 starts at <code>i</code> and continues until <code>j</code>; 8401 <code>i</code> and <code>j</code> can be negative. 8402 If <code>j</code> is absent, then it is assumed to be equal to -1 8403 (which is the same as the string length). 8404 In particular, 8405 the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 8406 with length <code>j</code>, 8407 and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code> 8408 with length <code>i</code>. 8409 8410 8411 <p> 8412 If, after the translation of negative indices, 8413 <code>i</code> is less than 1, 8414 it is corrected to 1. 8415 If <code>j</code> is greater than the string length, 8416 it is corrected to that length. 8417 If, after these corrections, 8418 <code>i</code> is greater than <code>j</code>, 8419 the function returns the empty string. 8420 8421 8422 8423 8424 <p> 8425 <hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3> 8426 8427 8428 <p> 8429 Returns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>) 8430 according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 8431 An optional <code>pos</code> marks where 8432 to start reading in <code>s</code> (default is 1). 8433 After the read values, 8434 this function also returns the index of the first unread byte in <code>s</code>. 8435 8436 8437 8438 8439 <p> 8440 <hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> 8441 Receives a string and returns a copy of this string with all 8442 lowercase letters changed to uppercase. 8443 All other characters are left unchanged. 8444 The definition of what a lowercase letter is depends on the current locale. 8445 8446 8447 8448 8449 8450 <h3>6.4.1 – <a name="6.4.1">Patterns</a></h3> 8451 8452 <p> 8453 Patterns in Lua are described by regular strings, 8454 which are interpreted as patterns by the pattern-matching functions 8455 <a href="#pdf-string.find"><code>string.find</code></a>, 8456 <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>, 8457 <a href="#pdf-string.gsub"><code>string.gsub</code></a>, 8458 and <a href="#pdf-string.match"><code>string.match</code></a>. 8459 This section describes the syntax and the meaning 8460 (that is, what they match) of these strings. 8461 8462 8463 8464 <h4>Character Class:</h4><p> 8465 A <em>character class</em> is used to represent a set of characters. 8466 The following combinations are allowed in describing a character class: 8467 8468 <ul> 8469 8470 <li><b><em>x</em>: </b> 8471 (where <em>x</em> is not one of the <em>magic characters</em> 8472 <code>^$()%.[]*+-?</code>) 8473 represents the character <em>x</em> itself. 8474 </li> 8475 8476 <li><b><code>.</code>: </b> (a dot) represents all characters.</li> 8477 8478 <li><b><code>%a</code>: </b> represents all letters.</li> 8479 8480 <li><b><code>%c</code>: </b> represents all control characters.</li> 8481 8482 <li><b><code>%d</code>: </b> represents all digits.</li> 8483 8484 <li><b><code>%g</code>: </b> represents all printable characters except space.</li> 8485 8486 <li><b><code>%l</code>: </b> represents all lowercase letters.</li> 8487 8488 <li><b><code>%p</code>: </b> represents all punctuation characters.</li> 8489 8490 <li><b><code>%s</code>: </b> represents all space characters.</li> 8491 8492 <li><b><code>%u</code>: </b> represents all uppercase letters.</li> 8493 8494 <li><b><code>%w</code>: </b> represents all alphanumeric characters.</li> 8495 8496 <li><b><code>%x</code>: </b> represents all hexadecimal digits.</li> 8497 8498 <li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character) 8499 represents the character <em>x</em>. 8500 This is the standard way to escape the magic characters. 8501 Any non-alphanumeric character 8502 (including all punctuations, even the non-magical) 8503 can be preceded by a '<code>%</code>' 8504 when used to represent itself in a pattern. 8505 </li> 8506 8507 <li><b><code>[<em>set</em>]</code>: </b> 8508 represents the class which is the union of all 8509 characters in <em>set</em>. 8510 A range of characters can be specified by 8511 separating the end characters of the range, 8512 in ascending order, with a '<code>-</code>'. 8513 All classes <code>%</code><em>x</em> described above can also be used as 8514 components in <em>set</em>. 8515 All other characters in <em>set</em> represent themselves. 8516 For example, <code>[%w_]</code> (or <code>[_%w]</code>) 8517 represents all alphanumeric characters plus the underscore, 8518 <code>[0-7]</code> represents the octal digits, 8519 and <code>[0-7%l%-]</code> represents the octal digits plus 8520 the lowercase letters plus the '<code>-</code>' character. 8521 8522 8523 <p> 8524 The interaction between ranges and classes is not defined. 8525 Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> 8526 have no meaning. 8527 </li> 8528 8529 <li><b><code>[^<em>set</em>]</code>: </b> 8530 represents the complement of <em>set</em>, 8531 where <em>set</em> is interpreted as above. 8532 </li> 8533 8534 </ul><p> 8535 For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), 8536 the corresponding uppercase letter represents the complement of the class. 8537 For instance, <code>%S</code> represents all non-space characters. 8538 8539 8540 <p> 8541 The definitions of letter, space, and other character groups 8542 depend on the current locale. 8543 In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. 8544 8545 8546 8547 8548 8549 <h4>Pattern Item:</h4><p> 8550 A <em>pattern item</em> can be 8551 8552 <ul> 8553 8554 <li> 8555 a single character class, 8556 which matches any single character in the class; 8557 </li> 8558 8559 <li> 8560 a single character class followed by '<code>*</code>', 8561 which matches zero or more repetitions of characters in the class. 8562 These repetition items will always match the longest possible sequence; 8563 </li> 8564 8565 <li> 8566 a single character class followed by '<code>+</code>', 8567 which matches one or more repetitions of characters in the class. 8568 These repetition items will always match the longest possible sequence; 8569 </li> 8570 8571 <li> 8572 a single character class followed by '<code>-</code>', 8573 which also matches zero or more repetitions of characters in the class. 8574 Unlike '<code>*</code>', 8575 these repetition items will always match the shortest possible sequence; 8576 </li> 8577 8578 <li> 8579 a single character class followed by '<code>?</code>', 8580 which matches zero or one occurrence of a character in the class. 8581 It always matches one occurrence if possible; 8582 </li> 8583 8584 <li> 8585 <code>%<em>n</em></code>, for <em>n</em> between 1 and 9; 8586 such item matches a substring equal to the <em>n</em>-th captured string 8587 (see below); 8588 </li> 8589 8590 <li> 8591 <code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; 8592 such item matches strings that start with <em>x</em>, end with <em>y</em>, 8593 and where the <em>x</em> and <em>y</em> are <em>balanced</em>. 8594 This means that, if one reads the string from left to right, 8595 counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, 8596 the ending <em>y</em> is the first <em>y</em> where the count reaches 0. 8597 For instance, the item <code>%b()</code> matches expressions with 8598 balanced parentheses. 8599 </li> 8600 8601 <li> 8602 <code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>; 8603 such item matches an empty string at any position such that 8604 the next character belongs to <em>set</em> 8605 and the previous character does not belong to <em>set</em>. 8606 The set <em>set</em> is interpreted as previously described. 8607 The beginning and the end of the subject are handled as if 8608 they were the character '<code>\0</code>'. 8609 </li> 8610 8611 </ul> 8612 8613 8614 8615 8616 <h4>Pattern:</h4><p> 8617 A <em>pattern</em> is a sequence of pattern items. 8618 A caret '<code>^</code>' at the beginning of a pattern anchors the match at the 8619 beginning of the subject string. 8620 A '<code>$</code>' at the end of a pattern anchors the match at the 8621 end of the subject string. 8622 At other positions, 8623 '<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. 8624 8625 8626 8627 8628 8629 <h4>Captures:</h4><p> 8630 A pattern can contain sub-patterns enclosed in parentheses; 8631 they describe <em>captures</em>. 8632 When a match succeeds, the substrings of the subject string 8633 that match captures are stored (<em>captured</em>) for future use. 8634 Captures are numbered according to their left parentheses. 8635 For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, 8636 the part of the string matching <code>"a*(.)%w(%s*)"</code> is 8637 stored as the first capture (and therefore has number 1); 8638 the character matching "<code>.</code>" is captured with number 2, 8639 and the part matching "<code>%s*</code>" has number 3. 8640 8641 8642 <p> 8643 As a special case, the empty capture <code>()</code> captures 8644 the current string position (a number). 8645 For instance, if we apply the pattern <code>"()aa()"</code> on the 8646 string <code>"flaaap"</code>, there will be two captures: 3 and 5. 8647 8648 8649 8650 8651 8652 8653 8654 <h3>6.4.2 – <a name="6.4.2">Format Strings for Pack and Unpack</a></h3> 8655 8656 <p> 8657 The first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>, 8658 <a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a> 8659 is a format string, 8660 which describes the layout of the structure being created or read. 8661 8662 8663 <p> 8664 A format string is a sequence of conversion options. 8665 The conversion options are as follows: 8666 8667 <ul> 8668 <li><b><code><</code>: </b>sets little endian</li> 8669 <li><b><code>></code>: </b>sets big endian</li> 8670 <li><b><code>=</code>: </b>sets native endian</li> 8671 <li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code> 8672 (default is native alignment)</li> 8673 <li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li> 8674 <li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li> 8675 <li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li> 8676 <li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li> 8677 <li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li> 8678 <li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li> 8679 <li><b><code>j</code>: </b>a <code>lua_Integer</code></li> 8680 <li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li> 8681 <li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li> 8682 <li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes 8683 (default is native size)</li> 8684 <li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes 8685 (default is native size)</li> 8686 <li><b><code>f</code>: </b>a <code>float</code> (native size)</li> 8687 <li><b><code>d</code>: </b>a <code>double</code> (native size)</li> 8688 <li><b><code>n</code>: </b>a <code>lua_Number</code></li> 8689 <li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li> 8690 <li><b><code>z</code>: </b>a zero-terminated string</li> 8691 <li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length 8692 coded as an unsigned integer with <code>n</code> bytes 8693 (default is a <code>size_t</code>)</li> 8694 <li><b><code>x</code>: </b>one byte of padding</li> 8695 <li><b><code>X<em>op</em></code>: </b>an empty item that aligns 8696 according to option <code>op</code> 8697 (which is otherwise ignored)</li> 8698 <li><b>'<code> </code>': </b>(empty space) ignored</li> 8699 </ul><p> 8700 (A "<code>[<em>n</em>]</code>" means an optional integral numeral.) 8701 Except for padding, spaces, and configurations 8702 (options "<code>xX <=>!</code>"), 8703 each option corresponds to an argument (in <a href="#pdf-string.pack"><code>string.pack</code></a>) 8704 or a result (in <a href="#pdf-string.unpack"><code>string.unpack</code></a>). 8705 8706 8707 <p> 8708 For options "<code>!<em>n</em></code>", "<code>s<em>n</em></code>", "<code>i<em>n</em></code>", and "<code>I<em>n</em></code>", 8709 <code>n</code> can be any integer between 1 and 16. 8710 All integral options check overflows; 8711 <a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size; 8712 <a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer. 8713 8714 8715 <p> 8716 Any format string starts as if prefixed by "<code>!1=</code>", 8717 that is, 8718 with maximum alignment of 1 (no alignment) 8719 and native endianness. 8720 8721 8722 <p> 8723 Alignment works as follows: 8724 For each option, 8725 the format gets extra padding until the data starts 8726 at an offset that is a multiple of the minimum between the 8727 option size and the maximum alignment; 8728 this minimum must be a power of 2. 8729 Options "<code>c</code>" and "<code>z</code>" are not aligned; 8730 option "<code>s</code>" follows the alignment of its starting integer. 8731 8732 8733 <p> 8734 All padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a> 8735 (and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>). 8736 8737 8738 8739 8740 8741 8742 8743 <h2>6.5 – <a name="6.5">UTF-8 Support</a></h2> 8744 8745 <p> 8746 This library provides basic support for UTF-8 encoding. 8747 It provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>. 8748 This library does not provide any support for Unicode other 8749 than the handling of the encoding. 8750 Any operation that needs the meaning of a character, 8751 such as character classification, is outside its scope. 8752 8753 8754 <p> 8755 Unless stated otherwise, 8756 all functions that expect a byte position as a parameter 8757 assume that the given position is either the start of a byte sequence 8758 or one plus the length of the subject string. 8759 As in the string library, 8760 negative indices count from the end of the string. 8761 8762 8763 <p> 8764 <hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3> 8765 Receives zero or more integers, 8766 converts each one to its corresponding UTF-8 byte sequence 8767 and returns a string with the concatenation of all these sequences. 8768 8769 8770 8771 8772 <p> 8773 <hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3> 8774 The pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>" 8775 (see <a href="#6.4.1">§6.4.1</a>), 8776 which matches exactly one UTF-8 byte sequence, 8777 assuming that the subject is a valid UTF-8 string. 8778 8779 8780 8781 8782 <p> 8783 <hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3> 8784 8785 8786 <p> 8787 Returns values so that the construction 8788 8789 <pre> 8790 for p, c in utf8.codes(s) do <em>body</em> end 8791 </pre><p> 8792 will iterate over all characters in string <code>s</code>, 8793 with <code>p</code> being the position (in bytes) and <code>c</code> the code point 8794 of each character. 8795 It raises an error if it meets any invalid byte sequence. 8796 8797 8798 8799 8800 <p> 8801 <hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3> 8802 Returns the codepoints (as integers) from all characters in <code>s</code> 8803 that start between byte position <code>i</code> and <code>j</code> (both included). 8804 The default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>. 8805 It raises an error if it meets any invalid byte sequence. 8806 8807 8808 8809 8810 <p> 8811 <hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j]])</code></a></h3> 8812 Returns the number of UTF-8 characters in string <code>s</code> 8813 that start between positions <code>i</code> and <code>j</code> (both inclusive). 8814 The default for <code>i</code> is 1 and for <code>j</code> is -1. 8815 If it finds any invalid byte sequence, 8816 returns a false value plus the position of the first invalid byte. 8817 8818 8819 8820 8821 <p> 8822 <hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3> 8823 Returns the position (in bytes) where the encoding of the 8824 <code>n</code>-th character of <code>s</code> 8825 (counting from position <code>i</code>) starts. 8826 A negative <code>n</code> gets characters before position <code>i</code>. 8827 The default for <code>i</code> is 1 when <code>n</code> is non-negative 8828 and <code>#s + 1</code> otherwise, 8829 so that <code>utf8.offset(s, -n)</code> gets the offset of the 8830 <code>n</code>-th character from the end of the string. 8831 If the specified character is neither in the subject 8832 nor right after its end, 8833 the function returns <b>nil</b>. 8834 8835 8836 <p> 8837 As a special case, 8838 when <code>n</code> is 0 the function returns the start of the encoding 8839 of the character that contains the <code>i</code>-th byte of <code>s</code>. 8840 8841 8842 <p> 8843 This function assumes that <code>s</code> is a valid UTF-8 string. 8844 8845 8846 8847 8848 8849 8850 8851 <h2>6.6 – <a name="6.6">Table Manipulation</a></h2> 8852 8853 <p> 8854 This library provides generic functions for table manipulation. 8855 It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. 8856 8857 8858 <p> 8859 Remember that, whenever an operation needs the length of a table, 8860 the table must be a proper sequence 8861 or have a <code>__len</code> metamethod (see <a href="#3.4.7">§3.4.7</a>). 8862 All functions ignore non-numeric keys 8863 in the tables given as arguments. 8864 8865 8866 <p> 8867 <hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3> 8868 8869 8870 <p> 8871 Given a list where all elements are strings or numbers, 8872 returns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>. 8873 The default value for <code>sep</code> is the empty string, 8874 the default for <code>i</code> is 1, 8875 and the default for <code>j</code> is <code>#list</code>. 8876 If <code>i</code> is greater than <code>j</code>, returns the empty string. 8877 8878 8879 8880 8881 <p> 8882 <hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3> 8883 8884 8885 <p> 8886 Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>, 8887 shifting up the elements 8888 <code>list[pos], list[pos+1], ···, list[#list]</code>. 8889 The default value for <code>pos</code> is <code>#list+1</code>, 8890 so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end 8891 of list <code>t</code>. 8892 8893 8894 8895 8896 <p> 8897 <hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3> 8898 8899 8900 <p> 8901 Moves elements from table <code>a1</code> to table <code>a2</code>. 8902 This function performs the equivalent to the following 8903 multiple assignment: 8904 <code>a2[t],··· = a1[f],···,a1[e]</code>. 8905 The default for <code>a2</code> is <code>a1</code>. 8906 The destination range can overlap with the source range. 8907 Index <code>f</code> must be positive. 8908 8909 8910 8911 8912 <p> 8913 <hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3> 8914 8915 8916 <p> 8917 Returns a new table with all parameters stored into keys 1, 2, etc. 8918 and with a field "<code>n</code>" with the total number of parameters. 8919 Note that the resulting table may not be a sequence. 8920 8921 8922 8923 8924 <p> 8925 <hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3> 8926 8927 8928 <p> 8929 Removes from <code>list</code> the element at position <code>pos</code>, 8930 returning the value of the removed element. 8931 When <code>pos</code> is an integer between 1 and <code>#list</code>, 8932 it shifts down the elements 8933 <code>list[pos+1], list[pos+2], ···, list[#list]</code> 8934 and erases element <code>list[#list]</code>; 8935 The index <code>pos</code> can also be 0 when <code>#list</code> is 0, 8936 or <code>#list + 1</code>; 8937 in those cases, the function erases the element <code>list[pos]</code>. 8938 8939 8940 <p> 8941 The default value for <code>pos</code> is <code>#list</code>, 8942 so that a call <code>table.remove(l)</code> removes the last element 8943 of list <code>l</code>. 8944 8945 8946 8947 8948 <p> 8949 <hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3> 8950 8951 8952 <p> 8953 Sorts list elements in a given order, <em>in-place</em>, 8954 from <code>list[1]</code> to <code>list[#list]</code>. 8955 If <code>comp</code> is given, 8956 then it must be a function that receives two list elements 8957 and returns true when the first element must come 8958 before the second in the final order 8959 (so that <code>not comp(list[i+1],list[i])</code> will be true after the sort). 8960 If <code>comp</code> is not given, 8961 then the standard Lua operator <code><</code> is used instead. 8962 8963 8964 <p> 8965 The sort algorithm is not stable; 8966 that is, elements considered equal by the given order 8967 may have their relative positions changed by the sort. 8968 8969 8970 8971 8972 <p> 8973 <hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3> 8974 8975 8976 <p> 8977 Returns the elements from the given list. 8978 This function is equivalent to 8979 8980 <pre> 8981 return list[i], list[i+1], ···, list[j] 8982 </pre><p> 8983 By default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>. 8984 8985 8986 8987 8988 8989 8990 8991 <h2>6.7 – <a name="6.7">Mathematical Functions</a></h2> 8992 8993 <p> 8994 This library provides basic mathematical functions. 8995 It provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>. 8996 Functions with the annotation "<code>integer/float</code>" give 8997 integer results for integer arguments 8998 and float results for float (or mixed) arguments. 8999 Rounding functions 9000 (<a href="#pdf-math.ceil"><code>math.ceil</code></a>, <a href="#pdf-math.floor"><code>math.floor</code></a>, and <a href="#pdf-math.modf"><code>math.modf</code></a>) 9001 return an integer when the result fits in the range of an integer, 9002 or a float otherwise. 9003 9004 9005 <p> 9006 <hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> 9007 9008 9009 <p> 9010 Returns the absolute value of <code>x</code>. (integer/float) 9011 9012 9013 9014 9015 <p> 9016 <hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> 9017 9018 9019 <p> 9020 Returns the arc cosine of <code>x</code> (in radians). 9021 9022 9023 9024 9025 <p> 9026 <hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> 9027 9028 9029 <p> 9030 Returns the arc sine of <code>x</code> (in radians). 9031 9032 9033 9034 9035 <p> 9036 <hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3> 9037 9038 9039 <p> 9040 9041 Returns the arc tangent of <code>y/x</code> (in radians), 9042 but uses the signs of both parameters to find the 9043 quadrant of the result. 9044 (It also handles correctly the case of <code>x</code> being zero.) 9045 9046 9047 <p> 9048 The default value for <code>x</code> is 1, 9049 so that the call <code>math.atan(y)</code> 9050 returns the arc tangent of <code>y</code>. 9051 9052 9053 9054 9055 <p> 9056 <hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> 9057 9058 9059 <p> 9060 Returns the smallest integral value larger than or equal to <code>x</code>. 9061 9062 9063 9064 9065 <p> 9066 <hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> 9067 9068 9069 <p> 9070 Returns the cosine of <code>x</code> (assumed to be in radians). 9071 9072 9073 9074 9075 <p> 9076 <hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> 9077 9078 9079 <p> 9080 Converts the angle <code>x</code> from radians to degrees. 9081 9082 9083 9084 9085 <p> 9086 <hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> 9087 9088 9089 <p> 9090 Returns the value <em>e<sup>x</sup></em> 9091 (where <code>e</code> is the base of natural logarithms). 9092 9093 9094 9095 9096 <p> 9097 <hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> 9098 9099 9100 <p> 9101 Returns the largest integral value smaller than or equal to <code>x</code>. 9102 9103 9104 9105 9106 <p> 9107 <hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> 9108 9109 9110 <p> 9111 Returns the remainder of the division of <code>x</code> by <code>y</code> 9112 that rounds the quotient towards zero. (integer/float) 9113 9114 9115 9116 9117 <p> 9118 <hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> 9119 9120 9121 <p> 9122 The float value <code>HUGE_VAL</code>, 9123 a value larger than any other numerical value. 9124 9125 9126 9127 9128 <p> 9129 <hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3> 9130 9131 9132 <p> 9133 Returns the logarithm of <code>x</code> in the given base. 9134 The default for <code>base</code> is <em>e</em> 9135 (so that the function returns the natural logarithm of <code>x</code>). 9136 9137 9138 9139 9140 <p> 9141 <hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> 9142 9143 9144 <p> 9145 Returns the argument with the maximum value, 9146 according to the Lua operator <code><</code>. (integer/float) 9147 9148 9149 9150 9151 <p> 9152 <hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3> 9153 An integer with the maximum value for an integer. 9154 9155 9156 9157 9158 <p> 9159 <hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> 9160 9161 9162 <p> 9163 Returns the argument with the minimum value, 9164 according to the Lua operator <code><</code>. (integer/float) 9165 9166 9167 9168 9169 <p> 9170 <hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3> 9171 An integer with the minimum value for an integer. 9172 9173 9174 9175 9176 <p> 9177 <hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> 9178 9179 9180 <p> 9181 Returns the integral part of <code>x</code> and the fractional part of <code>x</code>. 9182 Its second result is always a float. 9183 9184 9185 9186 9187 <p> 9188 <hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> 9189 9190 9191 <p> 9192 The value of <em>π</em>. 9193 9194 9195 9196 9197 <p> 9198 <hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> 9199 9200 9201 <p> 9202 Converts the angle <code>x</code> from degrees to radians. 9203 9204 9205 9206 9207 <p> 9208 <hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> 9209 9210 9211 <p> 9212 When called without arguments, 9213 returns a pseudo-random float with uniform distribution 9214 in the range <em>[0,1)</em>. 9215 When called with two integers <code>m</code> and <code>n</code>, 9216 <code>math.random</code> returns a pseudo-random integer 9217 with uniform distribution in the range <em>[m, n]</em>. 9218 (The value <em>m-n</em> cannot be negative and must fit in a Lua integer.) 9219 The call <code>math.random(n)</code> is equivalent to <code>math.random(1,n)</code>. 9220 9221 9222 <p> 9223 This function is an interface to the underling 9224 pseudo-random generator function provided by C. 9225 No guarantees can be given for its statistical properties. 9226 9227 9228 9229 9230 <p> 9231 <hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3> 9232 9233 9234 <p> 9235 Sets <code>x</code> as the "seed" 9236 for the pseudo-random generator: 9237 equal seeds produce equal sequences of numbers. 9238 9239 9240 9241 9242 <p> 9243 <hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> 9244 9245 9246 <p> 9247 Returns the sine of <code>x</code> (assumed to be in radians). 9248 9249 9250 9251 9252 <p> 9253 <hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> 9254 9255 9256 <p> 9257 Returns the square root of <code>x</code>. 9258 (You can also use the expression <code>x^0.5</code> to compute this value.) 9259 9260 9261 9262 9263 <p> 9264 <hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> 9265 9266 9267 <p> 9268 Returns the tangent of <code>x</code> (assumed to be in radians). 9269 9270 9271 9272 9273 <p> 9274 <hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3> 9275 9276 9277 <p> 9278 If the value <code>x</code> is convertible to an integer, 9279 returns that integer. 9280 Otherwise, returns <b>nil</b>. 9281 9282 9283 9284 9285 <p> 9286 <hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3> 9287 9288 9289 <p> 9290 Returns "<code>integer</code>" if <code>x</code> is an integer, 9291 "<code>float</code>" if it is a float, 9292 or <b>nil</b> if <code>x</code> is not a number. 9293 9294 9295 9296 9297 <p> 9298 <hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3> 9299 9300 9301 <p> 9302 Returns a boolean, 9303 true if integer <code>m</code> is below integer <code>n</code> when 9304 they are compared as unsigned integers. 9305 9306 9307 9308 9309 9310 9311 9312 <h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2> 9313 9314 <p> 9315 The I/O library provides two different styles for file manipulation. 9316 The first one uses implicit file handles; 9317 that is, there are operations to set a default input file and a 9318 default output file, 9319 and all input/output operations are over these default files. 9320 The second style uses explicit file handles. 9321 9322 9323 <p> 9324 When using implicit file handles, 9325 all operations are supplied by table <a name="pdf-io"><code>io</code></a>. 9326 When using explicit file handles, 9327 the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle 9328 and then all operations are supplied as methods of the file handle. 9329 9330 9331 <p> 9332 The table <code>io</code> also provides 9333 three predefined file handles with their usual meanings from C: 9334 <a name="pdf-io.stdin"><code>io.stdin</code></a>, <a name="pdf-io.stdout"><code>io.stdout</code></a>, and <a name="pdf-io.stderr"><code>io.stderr</code></a>. 9335 The I/O library never closes these files. 9336 9337 9338 <p> 9339 Unless otherwise stated, 9340 all I/O functions return <b>nil</b> on failure 9341 (plus an error message as a second result and 9342 a system-dependent error code as a third result) 9343 and some value different from <b>nil</b> on success. 9344 On non-POSIX systems, 9345 the computation of the error message and error code 9346 in case of errors 9347 may be not thread safe, 9348 because they rely on the global C variable <code>errno</code>. 9349 9350 9351 <p> 9352 <hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> 9353 9354 9355 <p> 9356 Equivalent to <code>file:close()</code>. 9357 Without a <code>file</code>, closes the default output file. 9358 9359 9360 9361 9362 <p> 9363 <hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> 9364 9365 9366 <p> 9367 Equivalent to <code>io.output():flush()</code>. 9368 9369 9370 9371 9372 <p> 9373 <hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> 9374 9375 9376 <p> 9377 When called with a file name, it opens the named file (in text mode), 9378 and sets its handle as the default input file. 9379 When called with a file handle, 9380 it simply sets this file handle as the default input file. 9381 When called without parameters, 9382 it returns the current default input file. 9383 9384 9385 <p> 9386 In case of errors this function raises the error, 9387 instead of returning an error code. 9388 9389 9390 9391 9392 <p> 9393 <hr><h3><a name="pdf-io.lines"><code>io.lines ([filename ···])</code></a></h3> 9394 9395 9396 <p> 9397 Opens the given file name in read mode 9398 and returns an iterator function that 9399 works like <code>file:lines(···)</code> over the opened file. 9400 When the iterator function detects the end of file, 9401 it returns no values (to finish the loop) and automatically closes the file. 9402 9403 9404 <p> 9405 The call <code>io.lines()</code> (with no file name) is equivalent 9406 to <code>io.input():lines("*l")</code>; 9407 that is, it iterates over the lines of the default input file. 9408 In this case it does not close the file when the loop ends. 9409 9410 9411 <p> 9412 In case of errors this function raises the error, 9413 instead of returning an error code. 9414 9415 9416 9417 9418 <p> 9419 <hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> 9420 9421 9422 <p> 9423 This function opens a file, 9424 in the mode specified in the string <code>mode</code>. 9425 It returns a new file handle, 9426 or, in case of errors, <b>nil</b> plus an error message. 9427 9428 9429 <p> 9430 The <code>mode</code> string can be any of the following: 9431 9432 <ul> 9433 <li><b>"<code>r</code>": </b> read mode (the default);</li> 9434 <li><b>"<code>w</code>": </b> write mode;</li> 9435 <li><b>"<code>a</code>": </b> append mode;</li> 9436 <li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li> 9437 <li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li> 9438 <li><b>"<code>a+</code>": </b> append update mode, previous data is preserved, 9439 writing is only allowed at the end of file.</li> 9440 </ul><p> 9441 The <code>mode</code> string can also have a '<code>b</code>' at the end, 9442 which is needed in some systems to open the file in binary mode. 9443 9444 9445 9446 9447 <p> 9448 <hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> 9449 9450 9451 <p> 9452 Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. 9453 9454 9455 9456 9457 <p> 9458 <hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> 9459 9460 9461 <p> 9462 This function is system dependent and is not available 9463 on all platforms. 9464 9465 9466 <p> 9467 Starts program <code>prog</code> in a separated process and returns 9468 a file handle that you can use to read data from this program 9469 (if <code>mode</code> is <code>"r"</code>, the default) 9470 or to write data to this program 9471 (if <code>mode</code> is <code>"w"</code>). 9472 9473 9474 9475 9476 <p> 9477 <hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> 9478 9479 9480 <p> 9481 Equivalent to <code>io.input():read(···)</code>. 9482 9483 9484 9485 9486 <p> 9487 <hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> 9488 9489 9490 <p> 9491 Returns a handle for a temporary file. 9492 This file is opened in update mode 9493 and it is automatically removed when the program ends. 9494 9495 9496 9497 9498 <p> 9499 <hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> 9500 9501 9502 <p> 9503 Checks whether <code>obj</code> is a valid file handle. 9504 Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, 9505 <code>"closed file"</code> if <code>obj</code> is a closed file handle, 9506 or <b>nil</b> if <code>obj</code> is not a file handle. 9507 9508 9509 9510 9511 <p> 9512 <hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> 9513 9514 9515 <p> 9516 Equivalent to <code>io.output():write(···)</code>. 9517 9518 9519 9520 9521 <p> 9522 <hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> 9523 9524 9525 <p> 9526 Closes <code>file</code>. 9527 Note that files are automatically closed when 9528 their handles are garbage collected, 9529 but that takes an unpredictable amount of time to happen. 9530 9531 9532 <p> 9533 When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>, 9534 <a href="#pdf-file:close"><code>file:close</code></a> returns the same values 9535 returned by <a href="#pdf-os.execute"><code>os.execute</code></a>. 9536 9537 9538 9539 9540 <p> 9541 <hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> 9542 9543 9544 <p> 9545 Saves any written data to <code>file</code>. 9546 9547 9548 9549 9550 <p> 9551 <hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3> 9552 9553 9554 <p> 9555 Returns an iterator function that, 9556 each time it is called, 9557 reads the file according to the given formats. 9558 When no format is given, 9559 uses "<code>l</code>" as a default. 9560 As an example, the construction 9561 9562 <pre> 9563 for c in file:lines(1) do <em>body</em> end 9564 </pre><p> 9565 will iterate over all characters of the file, 9566 starting at the current position. 9567 Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file 9568 when the loop ends. 9569 9570 9571 <p> 9572 In case of errors this function raises the error, 9573 instead of returning an error code. 9574 9575 9576 9577 9578 <p> 9579 <hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> 9580 9581 9582 <p> 9583 Reads the file <code>file</code>, 9584 according to the given formats, which specify what to read. 9585 For each format, 9586 the function returns a string or a number with the characters read, 9587 or <b>nil</b> if it cannot read data with the specified format. 9588 (In this latter case, 9589 the function does not read subsequent formats.) 9590 When called without formats, 9591 it uses a default format that reads the next line 9592 (see below). 9593 9594 9595 <p> 9596 The available formats are 9597 9598 <ul> 9599 9600 <li><b>"<code>n</code>": </b> 9601 reads a numeral and returns it as a float or an integer, 9602 following the lexical conventions of Lua. 9603 (The numeral may have leading spaces and a sign.) 9604 This format always reads the longest input sequence that 9605 is a valid prefix for a number; 9606 if that prefix does not form a valid number 9607 (e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"), 9608 it is discarded and the function returns <b>nil</b>. 9609 </li> 9610 9611 <li><b>"<code>i</code>": </b> 9612 reads an integral number and returns it as an integer. 9613 </li> 9614 9615 <li><b>"<code>a</code>": </b> 9616 reads the whole file, starting at the current position. 9617 On end of file, it returns the empty string. 9618 </li> 9619 9620 <li><b>"<code>l</code>": </b> 9621 reads the next line skipping the end of line, 9622 returning <b>nil</b> on end of file. 9623 This is the default format. 9624 </li> 9625 9626 <li><b>"<code>L</code>": </b> 9627 reads the next line keeping the end-of-line character (if present), 9628 returning <b>nil</b> on end of file. 9629 </li> 9630 9631 <li><b><em>number</em>: </b> 9632 reads a string with up to this number of bytes, 9633 returning <b>nil</b> on end of file. 9634 If <code>number</code> is zero, 9635 it reads nothing and returns an empty string, 9636 or <b>nil</b> on end of file. 9637 </li> 9638 9639 </ul><p> 9640 The formats "<code>l</code>" and "<code>L</code>" should be used only for text files. 9641 9642 9643 9644 9645 <p> 9646 <hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3> 9647 9648 9649 <p> 9650 Sets and gets the file position, 9651 measured from the beginning of the file, 9652 to the position given by <code>offset</code> plus a base 9653 specified by the string <code>whence</code>, as follows: 9654 9655 <ul> 9656 <li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li> 9657 <li><b>"<code>cur</code>": </b> base is current position;</li> 9658 <li><b>"<code>end</code>": </b> base is end of file;</li> 9659 </ul><p> 9660 In case of success, <code>seek</code> returns the final file position, 9661 measured in bytes from the beginning of the file. 9662 If <code>seek</code> fails, it returns <b>nil</b>, 9663 plus a string describing the error. 9664 9665 9666 <p> 9667 The default value for <code>whence</code> is <code>"cur"</code>, 9668 and for <code>offset</code> is 0. 9669 Therefore, the call <code>file:seek()</code> returns the current 9670 file position, without changing it; 9671 the call <code>file:seek("set")</code> sets the position to the 9672 beginning of the file (and returns 0); 9673 and the call <code>file:seek("end")</code> sets the position to the 9674 end of the file, and returns its size. 9675 9676 9677 9678 9679 <p> 9680 <hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> 9681 9682 9683 <p> 9684 Sets the buffering mode for an output file. 9685 There are three available modes: 9686 9687 <ul> 9688 9689 <li><b>"<code>no</code>": </b> 9690 no buffering; the result of any output operation appears immediately. 9691 </li> 9692 9693 <li><b>"<code>full</code>": </b> 9694 full buffering; output operation is performed only 9695 when the buffer is full or when 9696 you explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>). 9697 </li> 9698 9699 <li><b>"<code>line</code>": </b> 9700 line buffering; output is buffered until a newline is output 9701 or there is any input from some special files 9702 (such as a terminal device). 9703 </li> 9704 9705 </ul><p> 9706 For the last two cases, <code>size</code> 9707 specifies the size of the buffer, in bytes. 9708 The default is an appropriate size. 9709 9710 9711 9712 9713 <p> 9714 <hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> 9715 9716 9717 <p> 9718 Writes the value of each of its arguments to <code>file</code>. 9719 The arguments must be strings or numbers. 9720 9721 9722 <p> 9723 In case of success, this function returns <code>file</code>. 9724 Otherwise it returns <b>nil</b> plus a string describing the error. 9725 9726 9727 9728 9729 9730 9731 9732 <h2>6.9 – <a name="6.9">Operating System Facilities</a></h2> 9733 9734 <p> 9735 This library is implemented through table <a name="pdf-os"><code>os</code></a>. 9736 9737 9738 <p> 9739 <hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> 9740 9741 9742 <p> 9743 Returns an approximation of the amount in seconds of CPU time 9744 used by the program. 9745 9746 9747 9748 9749 <p> 9750 <hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> 9751 9752 9753 <p> 9754 Returns a string or a table containing date and time, 9755 formatted according to the given string <code>format</code>. 9756 9757 9758 <p> 9759 If the <code>time</code> argument is present, 9760 this is the time to be formatted 9761 (see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). 9762 Otherwise, <code>date</code> formats the current time. 9763 9764 9765 <p> 9766 If <code>format</code> starts with '<code>!</code>', 9767 then the date is formatted in Coordinated Universal Time. 9768 After this optional character, 9769 if <code>format</code> is the string "<code>*t</code>", 9770 then <code>date</code> returns a table with the following fields: 9771 <code>year</code> (four digits), <code>month</code> (1–12), <code>day</code> (1–31), 9772 <code>hour</code> (0–23), <code>min</code> (0–59), <code>sec</code> (0–61), 9773 <code>wday</code> (weekday, Sunday is 1), 9774 <code>yday</code> (day of the year), 9775 and <code>isdst</code> (daylight saving flag, a boolean). 9776 This last field may be absent 9777 if the information is not available. 9778 9779 9780 <p> 9781 If <code>format</code> is not "<code>*t</code>", 9782 then <code>date</code> returns the date as a string, 9783 formatted according to the same rules as the ISO C function <code>strftime</code>. 9784 9785 9786 <p> 9787 When called without arguments, 9788 <code>date</code> returns a reasonable date and time representation that depends on 9789 the host system and on the current locale 9790 (that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>). 9791 9792 9793 <p> 9794 On non-POSIX systems, 9795 this function may be not thread safe 9796 because of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>. 9797 9798 9799 9800 9801 <p> 9802 <hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> 9803 9804 9805 <p> 9806 Returns the difference, in seconds, 9807 from time <code>t1</code> to time <code>t2</code> 9808 (where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>). 9809 In POSIX, Windows, and some other systems, 9810 this value is exactly <code>t2</code><em>-</em><code>t1</code>. 9811 9812 9813 9814 9815 <p> 9816 <hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> 9817 9818 9819 <p> 9820 This function is equivalent to the ISO C function <code>system</code>. 9821 It passes <code>command</code> to be executed by an operating system shell. 9822 Its first result is <b>true</b> 9823 if the command terminated successfully, 9824 or <b>nil</b> otherwise. 9825 After this first result 9826 the function returns a string plus a number, 9827 as follows: 9828 9829 <ul> 9830 9831 <li><b>"<code>exit</code>": </b> 9832 the command terminated normally; 9833 the following number is the exit status of the command. 9834 </li> 9835 9836 <li><b>"<code>signal</code>": </b> 9837 the command was terminated by a signal; 9838 the following number is the signal that terminated the command. 9839 </li> 9840 9841 </ul> 9842 9843 <p> 9844 When called without a <code>command</code>, 9845 <code>os.execute</code> returns a boolean that is true if a shell is available. 9846 9847 9848 9849 9850 <p> 9851 <hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3> 9852 9853 9854 <p> 9855 Calls the ISO C function <code>exit</code> to terminate the host program. 9856 If <code>code</code> is <b>true</b>, 9857 the returned status is <code>EXIT_SUCCESS</code>; 9858 if <code>code</code> is <b>false</b>, 9859 the returned status is <code>EXIT_FAILURE</code>; 9860 if <code>code</code> is a number, 9861 the returned status is this number. 9862 The default value for <code>code</code> is <b>true</b>. 9863 9864 9865 <p> 9866 If the optional second argument <code>close</code> is true, 9867 closes the Lua state before exiting. 9868 9869 9870 9871 9872 <p> 9873 <hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> 9874 9875 9876 <p> 9877 Returns the value of the process environment variable <code>varname</code>, 9878 or <b>nil</b> if the variable is not defined. 9879 9880 9881 9882 9883 <p> 9884 <hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> 9885 9886 9887 <p> 9888 Deletes the file (or empty directory, on POSIX systems) 9889 with the given name. 9890 If this function fails, it returns <b>nil</b>, 9891 plus a string describing the error and the error code. 9892 9893 9894 9895 9896 <p> 9897 <hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> 9898 9899 9900 <p> 9901 Renames file or directory named <code>oldname</code> to <code>newname</code>. 9902 If this function fails, it returns <b>nil</b>, 9903 plus a string describing the error and the error code. 9904 9905 9906 9907 9908 <p> 9909 <hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> 9910 9911 9912 <p> 9913 Sets the current locale of the program. 9914 <code>locale</code> is a system-dependent string specifying a locale; 9915 <code>category</code> is an optional string describing which category to change: 9916 <code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, 9917 <code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; 9918 the default category is <code>"all"</code>. 9919 The function returns the name of the new locale, 9920 or <b>nil</b> if the request cannot be honored. 9921 9922 9923 <p> 9924 If <code>locale</code> is the empty string, 9925 the current locale is set to an implementation-defined native locale. 9926 If <code>locale</code> is the string "<code>C</code>", 9927 the current locale is set to the standard C locale. 9928 9929 9930 <p> 9931 When called with <b>nil</b> as the first argument, 9932 this function only returns the name of the current locale 9933 for the given category. 9934 9935 9936 <p> 9937 This function may be not thread safe 9938 because of its reliance on C function <code>setlocale</code>. 9939 9940 9941 9942 9943 <p> 9944 <hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> 9945 9946 9947 <p> 9948 Returns the current time when called without arguments, 9949 or a time representing the date and time specified by the given table. 9950 This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, 9951 and may have fields 9952 <code>hour</code> (default is 12), 9953 <code>min</code> (default is 0), 9954 <code>sec</code> (default is 0), 9955 and <code>isdst</code> (default is <b>nil</b>). 9956 For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function. 9957 9958 9959 <p> 9960 The returned value is a number, whose meaning depends on your system. 9961 In POSIX, Windows, and some other systems, 9962 this number counts the number 9963 of seconds since some given start time (the "epoch"). 9964 In other systems, the meaning is not specified, 9965 and the number returned by <code>time</code> can be used only as an argument to 9966 <a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. 9967 9968 9969 9970 9971 <p> 9972 <hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> 9973 9974 9975 <p> 9976 Returns a string with a file name that can 9977 be used for a temporary file. 9978 The file must be explicitly opened before its use 9979 and explicitly removed when no longer needed. 9980 9981 9982 <p> 9983 On POSIX systems, 9984 this function also creates a file with that name, 9985 to avoid security risks. 9986 (Someone else might create the file with wrong permissions 9987 in the time between getting the name and creating the file.) 9988 You still have to open the file to use it 9989 and to remove it (even if you do not use it). 9990 9991 9992 <p> 9993 When possible, 9994 you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, 9995 which automatically removes the file when the program ends. 9996 9997 9998 9999 10000 10001 10002 10003 <h2>6.10 – <a name="6.10">The Debug Library</a></h2> 10004 10005 <p> 10006 This library provides 10007 the functionality of the debug interface (<a href="#4.9">§4.9</a>) to Lua programs. 10008 You should exert care when using this library. 10009 Several of its functions 10010 violate basic assumptions about Lua code 10011 (e.g., that variables local to a function 10012 cannot be accessed from outside; 10013 that userdata metatables cannot be changed by Lua code; 10014 that Lua programs do not crash) 10015 and therefore can compromise otherwise secure code. 10016 Moreover, some functions in this library may be slow. 10017 10018 10019 <p> 10020 All functions in this library are provided 10021 inside the <a name="pdf-debug"><code>debug</code></a> table. 10022 All functions that operate over a thread 10023 have an optional first argument which is the 10024 thread to operate over. 10025 The default is always the current thread. 10026 10027 10028 <p> 10029 <hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> 10030 10031 10032 <p> 10033 Enters an interactive mode with the user, 10034 running each string that the user enters. 10035 Using simple commands and other debug facilities, 10036 the user can inspect global and local variables, 10037 change their values, evaluate expressions, and so on. 10038 A line containing only the word <code>cont</code> finishes this function, 10039 so that the caller continues its execution. 10040 10041 10042 <p> 10043 Note that commands for <code>debug.debug</code> are not lexically nested 10044 within any function and so have no direct access to local variables. 10045 10046 10047 10048 10049 <p> 10050 <hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> 10051 10052 10053 <p> 10054 Returns the current hook settings of the thread, as three values: 10055 the current hook function, the current hook mask, 10056 and the current hook count 10057 (as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). 10058 10059 10060 10061 10062 <p> 10063 <hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> 10064 10065 10066 <p> 10067 Returns a table with information about a function. 10068 You can give the function directly 10069 or you can give a number as the value of <code>f</code>, 10070 which means the function running at level <code>f</code> of the call stack 10071 of the given thread: 10072 level 0 is the current function (<code>getinfo</code> itself); 10073 level 1 is the function that called <code>getinfo</code> 10074 (except for tail calls, which do not count on the stack); 10075 and so on. 10076 If <code>f</code> is a number larger than the number of active functions, 10077 then <code>getinfo</code> returns <b>nil</b>. 10078 10079 10080 <p> 10081 The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, 10082 with the string <code>what</code> describing which fields to fill in. 10083 The default for <code>what</code> is to get all information available, 10084 except the table of valid lines. 10085 If present, 10086 the option '<code>f</code>' 10087 adds a field named <code>func</code> with the function itself. 10088 If present, 10089 the option '<code>L</code>' 10090 adds a field named <code>activelines</code> with the table of 10091 valid lines. 10092 10093 10094 <p> 10095 For instance, the expression <code>debug.getinfo(1,"n").name</code> returns 10096 a table with a name for the current function, 10097 if a reasonable name can be found, 10098 and the expression <code>debug.getinfo(print)</code> 10099 returns a table with all available information 10100 about the <a href="#pdf-print"><code>print</code></a> function. 10101 10102 10103 10104 10105 <p> 10106 <hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3> 10107 10108 10109 <p> 10110 This function returns the name and the value of the local variable 10111 with index <code>local</code> of the function at level <code>f</code> of the stack. 10112 This function accesses not only explicit local variables, 10113 but also parameters, temporaries, etc. 10114 10115 10116 <p> 10117 The first parameter or local variable has index 1, and so on, 10118 following the order that they are declared in the code, 10119 counting only the variables that are active 10120 in the current scope of the function. 10121 Negative indices refer to vararg parameters; 10122 -1 is the first vararg parameter. 10123 The function returns <b>nil</b> if there is no variable with the given index, 10124 and raises an error when called with a level out of range. 10125 (You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) 10126 10127 10128 <p> 10129 Variable names starting with '<code>(</code>' (open parenthesis) 10130 represent variables with no known names 10131 (internal variables such as loop control variables, 10132 and variables from chunks saved without debug information). 10133 10134 10135 <p> 10136 The parameter <code>f</code> may also be a function. 10137 In that case, <code>getlocal</code> returns only the name of function parameters. 10138 10139 10140 10141 10142 <p> 10143 <hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3> 10144 10145 10146 <p> 10147 Returns the metatable of the given <code>value</code> 10148 or <b>nil</b> if it does not have a metatable. 10149 10150 10151 10152 10153 <p> 10154 <hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> 10155 10156 10157 <p> 10158 Returns the registry table (see <a href="#4.5">§4.5</a>). 10159 10160 10161 10162 10163 <p> 10164 <hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3> 10165 10166 10167 <p> 10168 This function returns the name and the value of the upvalue 10169 with index <code>up</code> of the function <code>f</code>. 10170 The function returns <b>nil</b> if there is no upvalue with the given index. 10171 10172 10173 <p> 10174 Variable names starting with '<code>(</code>' (open parenthesis) 10175 represent variables with no known names 10176 (variables from chunks saved without debug information). 10177 10178 10179 10180 10181 <p> 10182 <hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3> 10183 10184 10185 <p> 10186 Returns the Lua value associated to <code>u</code>. 10187 If <code>u</code> is not a userdata, 10188 returns <b>nil</b>. 10189 10190 10191 10192 10193 <p> 10194 <hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> 10195 10196 10197 <p> 10198 Sets the given function as a hook. 10199 The string <code>mask</code> and the number <code>count</code> describe 10200 when the hook will be called. 10201 The string mask may have any combination of the following characters, 10202 with the given meaning: 10203 10204 <ul> 10205 <li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li> 10206 <li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li> 10207 <li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li> 10208 </ul><p> 10209 Moreover, 10210 with a <code>count</code> different from zero, 10211 the hook is called also after every <code>count</code> instructions. 10212 10213 10214 <p> 10215 When called without arguments, 10216 <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. 10217 10218 10219 <p> 10220 When the hook is called, its first parameter is a string 10221 describing the event that has triggered its call: 10222 <code>"call"</code> (or <code>"tail call"</code>), 10223 <code>"return"</code>, 10224 <code>"line"</code>, and <code>"count"</code>. 10225 For line events, 10226 the hook also gets the new line number as its second parameter. 10227 Inside a hook, 10228 you can call <code>getinfo</code> with level 2 to get more information about 10229 the running function 10230 (level 0 is the <code>getinfo</code> function, 10231 and level 1 is the hook function). 10232 10233 10234 10235 10236 <p> 10237 <hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> 10238 10239 10240 <p> 10241 This function assigns the value <code>value</code> to the local variable 10242 with index <code>local</code> of the function at level <code>level</code> of the stack. 10243 The function returns <b>nil</b> if there is no local 10244 variable with the given index, 10245 and raises an error when called with a <code>level</code> out of range. 10246 (You can call <code>getinfo</code> to check whether the level is valid.) 10247 Otherwise, it returns the name of the local variable. 10248 10249 10250 <p> 10251 See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about 10252 variable indices and names. 10253 10254 10255 10256 10257 <p> 10258 <hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> 10259 10260 10261 <p> 10262 Sets the metatable for the given <code>value</code> to the given <code>table</code> 10263 (which can be <b>nil</b>). 10264 Returns <code>value</code>. 10265 10266 10267 10268 10269 <p> 10270 <hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> 10271 10272 10273 <p> 10274 This function assigns the value <code>value</code> to the upvalue 10275 with index <code>up</code> of the function <code>f</code>. 10276 The function returns <b>nil</b> if there is no upvalue 10277 with the given index. 10278 Otherwise, it returns the name of the upvalue. 10279 10280 10281 10282 10283 <p> 10284 <hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3> 10285 10286 10287 <p> 10288 Sets the given <code>value</code> as 10289 the Lua value associated to the given <code>udata</code>. 10290 <code>udata</code> must be a full userdata. 10291 10292 10293 <p> 10294 Returns <code>udata</code>. 10295 10296 10297 10298 10299 <p> 10300 <hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> 10301 10302 10303 <p> 10304 If <code>message</code> is present but is neither a string nor <b>nil</b>, 10305 this function returns <code>message</code> without further processing. 10306 Otherwise, 10307 it returns a string with a traceback of the call stack. 10308 The optional <code>message</code> string is appended 10309 at the beginning of the traceback. 10310 An optional <code>level</code> number tells at which level 10311 to start the traceback 10312 (default is 1, the function calling <code>traceback</code>). 10313 10314 10315 10316 10317 <p> 10318 <hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3> 10319 10320 10321 <p> 10322 Returns a unique identifier (as a light userdata) 10323 for the upvalue numbered <code>n</code> 10324 from the given function. 10325 10326 10327 <p> 10328 These unique identifiers allow a program to check whether different 10329 closures share upvalues. 10330 Lua closures that share an upvalue 10331 (that is, that access a same external local variable) 10332 will return identical ids for those upvalue indices. 10333 10334 10335 10336 10337 <p> 10338 <hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3> 10339 10340 10341 <p> 10342 Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code> 10343 refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>. 10344 10345 10346 10347 10348 10349 10350 10351 <h1>7 – <a name="7">Lua Standalone</a></h1> 10352 10353 <p> 10354 Although Lua has been designed as an extension language, 10355 to be embedded in a host C program, 10356 it is also frequently used as a standalone language. 10357 An interpreter for Lua as a standalone language, 10358 called simply <code>lua</code>, 10359 is provided with the standard distribution. 10360 The standalone interpreter includes 10361 all standard libraries, including the debug library. 10362 Its usage is: 10363 10364 <pre> 10365 lua [options] [script [args]] 10366 </pre><p> 10367 The options are: 10368 10369 <ul> 10370 <li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li> 10371 <li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li> 10372 <li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li> 10373 <li><b><code>-v</code>: </b> prints version information;</li> 10374 <li><b><code>-E</code>: </b> ignores environment variables;</li> 10375 <li><b><code>--</code>: </b> stops handling options;</li> 10376 <li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li> 10377 </ul><p> 10378 After handling its options, <code>lua</code> runs the given <em>script</em>. 10379 When called without arguments, 10380 <code>lua</code> behaves as <code>lua -v -i</code> 10381 when the standard input (<code>stdin</code>) is a terminal, 10382 and as <code>lua -</code> otherwise. 10383 10384 10385 <p> 10386 When called without option <code>-E</code>, 10387 the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a> 10388 (or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined) 10389 before running any argument. 10390 If the variable content has the format <code>@<em>filename</em></code>, 10391 then <code>lua</code> executes the file. 10392 Otherwise, <code>lua</code> executes the string itself. 10393 10394 10395 <p> 10396 When called with option <code>-E</code>, 10397 besides ignoring <code>LUA_INIT</code>, 10398 Lua also ignores 10399 the values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>, 10400 setting the values of 10401 <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a> 10402 with the default paths defined in <code>luaconf.h</code>. 10403 10404 10405 <p> 10406 All options are handled in order, except <code>-i</code> and <code>-E</code>. 10407 For instance, an invocation like 10408 10409 <pre> 10410 $ lua -e'a=1' -e 'print(a)' script.lua 10411 </pre><p> 10412 will first set <code>a</code> to 1, then print the value of <code>a</code>, 10413 and finally run the file <code>script.lua</code> with no arguments. 10414 (Here <code>$</code> is the shell prompt. Your prompt may be different.) 10415 10416 10417 <p> 10418 Before running any code, 10419 <code>lua</code> collects all command-line arguments 10420 in a global table called <code>arg</code>. 10421 The script name goes to index 0, 10422 the first argument after the script name goes to index 1, 10423 and so on. 10424 Any arguments before the script name 10425 (that is, the interpreter name plus its options) 10426 go to negative indices. 10427 For instance, in the call 10428 10429 <pre> 10430 $ lua -la b.lua t1 t2 10431 </pre><p> 10432 the table is like this: 10433 10434 <pre> 10435 arg = { [-2] = "lua", [-1] = "-la", 10436 [0] = "b.lua", 10437 [1] = "t1", [2] = "t2" } 10438 </pre><p> 10439 If there is no script in the call, 10440 the interpreter name goes to index 0, 10441 followed by the other arguments. 10442 For instance, the call 10443 10444 <pre> 10445 $ lua -e "print(arg[1])" 10446 </pre><p> 10447 will print "<code>-e</code>". 10448 If there is a script, 10449 the script is called with parameters 10450 <code>arg[1]</code>, ···, <code>arg[#arg]</code>. 10451 (Like all chunks in Lua, 10452 the script is compiled as a vararg function.) 10453 10454 10455 <p> 10456 In interactive mode, 10457 Lua repeatedly prompts and waits for a line. 10458 After reading a line, 10459 Lua first try to interpret the line as an expression. 10460 If it succeeds, it prints its value. 10461 Otherwise, it interprets the line as a statement. 10462 If you write an incomplete statement, 10463 the interpreter waits for its completion 10464 by issuing a different prompt. 10465 10466 10467 <p> 10468 In case of unprotected errors in the script, 10469 the interpreter reports the error to the standard error stream. 10470 If the error object is not a string but 10471 has a metamethod <code>__tostring</code>, 10472 the interpreter calls this metamethod to produce the final message. 10473 Otherwise, the interpreter converts the error object to a string 10474 and adds a stack traceback to it. 10475 10476 10477 <p> 10478 When finishing normally, 10479 the interpreter closes its main Lua state 10480 (see <a href="#lua_close"><code>lua_close</code></a>). 10481 The script can avoid this step by 10482 calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate. 10483 10484 10485 <p> 10486 To allow the use of Lua as a 10487 script interpreter in Unix systems, 10488 the standalone interpreter skips 10489 the first line of a chunk if it starts with <code>#</code>. 10490 Therefore, Lua scripts can be made into executable programs 10491 by using <code>chmod +x</code> and the <code>#!</code> form, 10492 as in 10493 10494 <pre> 10495 #!/usr/local/bin/lua 10496 </pre><p> 10497 (Of course, 10498 the location of the Lua interpreter may be different in your machine. 10499 If <code>lua</code> is in your <code>PATH</code>, 10500 then 10501 10502 <pre> 10503 #!/usr/bin/env lua 10504 </pre><p> 10505 is a more portable solution.) 10506 10507 10508 10509 <h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> 10510 10511 <p> 10512 Here we list the incompatibilities that you may find when moving a program 10513 from Lua 5.2 to Lua 5.3. 10514 You can avoid some incompatibilities by compiling Lua with 10515 appropriate options (see file <code>luaconf.h</code>). 10516 However, 10517 all these compatibility options will be removed in the future. 10518 10519 10520 <p> 10521 Lua versions can always change the C API in ways that 10522 do not imply source-code changes in a program, 10523 such as the numeric values for constants 10524 or the implementation of functions as macros. 10525 Therefore, 10526 you should not assume that binaries are compatible between 10527 different Lua versions. 10528 Always recompile clients of the Lua API when 10529 using a new version. 10530 10531 10532 <p> 10533 Similarly, Lua versions can always change the internal representation 10534 of precompiled chunks; 10535 precompiled chunks are not compatible between different Lua versions. 10536 10537 10538 <p> 10539 The standard paths in the official distribution may 10540 change between versions. 10541 10542 10543 10544 <h2>8.1 – <a name="8.1">Changes in the Language</a></h2> 10545 <ul> 10546 10547 <li> 10548 The main difference between Lua 5.2 and Lua 5.3 is the 10549 introduction of an integer subtype for numbers. 10550 Although this change should not affect "normal" computations, 10551 some computations 10552 (mainly those that involve some kind of overflow) 10553 can give different results. 10554 10555 10556 <p> 10557 You can fix these differences by forcing a number to be a float 10558 (in Lua 5.2 all numbers were float), 10559 in particular writing constants with an ending <code>.0</code> 10560 or using <code>x = x + 0.0</code> to convert a variable. 10561 (This recommendation is only for a quick fix 10562 for an occasional incompatibility; 10563 it is not a general guideline for good programming. 10564 For good programming, 10565 use floats where you need floats 10566 and integers where you need integers.) 10567 </li> 10568 10569 <li> 10570 The conversion of a float to a string now adds a <code>.0</code> suffix 10571 to the result if it looks like an integer. 10572 (For instance, the float 2.0 will be printed as <code>2.0</code>, 10573 not as <code>2</code>.) 10574 You should always use an explicit format 10575 when you need a specific format for numbers. 10576 10577 10578 <p> 10579 (Formally this is not an incompatibility, 10580 because Lua does not specify how numbers are formatted as strings, 10581 but some programs assumed a specific format.) 10582 </li> 10583 10584 <li> 10585 The generational mode for the garbage collector was removed. 10586 (It was an experimental feature in Lua 5.2.) 10587 </li> 10588 10589 </ul> 10590 10591 10592 10593 10594 <h2>8.2 – <a name="8.2">Changes in the Libraries</a></h2> 10595 <ul> 10596 10597 <li> 10598 The <code>bit32</code> library has been deprecated. 10599 It is easy to require a compatible external library or, 10600 better yet, to replace its functions with appropriate bitwise operations. 10601 (Keep in mind that <code>bit32</code> operates on 32-bit integers, 10602 while the bitwise operators in standard Lua operate on 64-bit integers.) 10603 </li> 10604 10605 <li> 10606 The Table library now respects metamethods 10607 for setting and getting elements. 10608 </li> 10609 10610 <li> 10611 The <a href="#pdf-ipairs"><code>ipairs</code></a> iterator now respects metamethods and 10612 its <code>__ipairs</code> metamethod has been deprecated. 10613 </li> 10614 10615 <li> 10616 Option names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore. 10617 For compatibility, Lua will continue to ignore this character. 10618 </li> 10619 10620 <li> 10621 The following functions were deprecated in the mathematical library: 10622 <code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>, 10623 <code>frexp</code>, and <code>ldexp</code>. 10624 You can replace <code>math.pow(x,y)</code> with <code>x^y</code>; 10625 you can replace <code>math.atan2</code> with <code>math.atan</code>, 10626 which now accepts one or two parameters; 10627 you can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>. 10628 For the other operations, 10629 you can either use an external library or 10630 implement them in Lua. 10631 </li> 10632 10633 <li> 10634 The searcher for C loaders used by <a href="#pdf-require"><code>require</code></a> 10635 changed the way it handles versioned names. 10636 Now, the version should come after the module name 10637 (as is usual in most other tools). 10638 For compatibility, that searcher still tries the old format 10639 if it cannot find an open function according to the new style. 10640 (Lua 5.2 already worked that way, 10641 but it did not document the change.) 10642 </li> 10643 10644 </ul> 10645 10646 10647 10648 10649 <h2>8.3 – <a name="8.3">Changes in the API</a></h2> 10650 10651 10652 <ul> 10653 10654 <li> 10655 Continuation functions now receive as parameters what they needed 10656 to get through <code>lua_getctx</code>, 10657 so <code>lua_getctx</code> has been removed. 10658 Adapt your code accordingly. 10659 </li> 10660 10661 <li> 10662 Function <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>. 10663 Use 0 as the value of this parameter to get the old behavior. 10664 </li> 10665 10666 <li> 10667 Functions to inject/project unsigned integers 10668 (<code>lua_pushunsigned</code>, <code>lua_tounsigned</code>, <code>lua_tounsignedx</code>, 10669 <code>luaL_checkunsigned</code>, <code>luaL_optunsigned</code>) 10670 were deprecated. 10671 Use their signed equivalents with a type cast. 10672 </li> 10673 10674 <li> 10675 Macros to project non-default integer types 10676 (<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>) 10677 were deprecated. 10678 Use their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast 10679 (or, when possible, use <a href="#lua_Integer"><code>lua_Integer</code></a> in your code). 10680 </li> 10681 10682 </ul> 10683 10684 10685 10686 10687 <h1>9 – <a name="9">The Complete Syntax of Lua</a></h1> 10688 10689 <p> 10690 Here is the complete syntax of Lua in extended BNF. 10691 As usual in extended BNF, 10692 {A} means 0 or more As, 10693 and [A] means an optional A. 10694 (For operator precedences, see <a href="#3.4.8">§3.4.8</a>; 10695 for a description of the terminals 10696 Name, Numeral, 10697 and LiteralString, see <a href="#3.1">§3.1</a>.) 10698 10699 10700 10701 10702 <pre> 10703 10704 chunk ::= block 10705 10706 block ::= {stat} [retstat] 10707 10708 stat ::= ‘<b>;</b>’ | 10709 varlist ‘<b>=</b>’ explist | 10710 functioncall | 10711 label | 10712 <b>break</b> | 10713 <b>goto</b> Name | 10714 <b>do</b> block <b>end</b> | 10715 <b>while</b> exp <b>do</b> block <b>end</b> | 10716 <b>repeat</b> block <b>until</b> exp | 10717 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 10718 <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> | 10719 <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 10720 <b>function</b> funcname funcbody | 10721 <b>local</b> <b>function</b> Name funcbody | 10722 <b>local</b> namelist [‘<b>=</b>’ explist] 10723 10724 retstat ::= <b>return</b> [explist] [‘<b>;</b>’] 10725 10726 label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 10727 10728 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 10729 10730 varlist ::= var {‘<b>,</b>’ var} 10731 10732 var ::= Name | prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | prefixexp ‘<b>.</b>’ Name 10733 10734 namelist ::= Name {‘<b>,</b>’ Name} 10735 10736 explist ::= exp {‘<b>,</b>’ exp} 10737 10738 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | ‘<b>...</b>’ | functiondef | 10739 prefixexp | tableconstructor | exp binop exp | unop exp 10740 10741 prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 10742 10743 functioncall ::= prefixexp args | prefixexp ‘<b>:</b>’ Name args 10744 10745 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | tableconstructor | LiteralString 10746 10747 functiondef ::= <b>function</b> funcbody 10748 10749 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 10750 10751 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 10752 10753 tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 10754 10755 fieldlist ::= field {fieldsep field} [fieldsep] 10756 10757 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 10758 10759 fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 10760 10761 binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</b>’ | ‘<b>//</b>’ | ‘<b>^</b>’ | ‘<b>%</b>’ | 10762 ‘<b>&</b>’ | ‘<b>~</b>’ | ‘<b>|</b>’ | ‘<b>>></b>’ | ‘<b><<</b>’ | ‘<b>..</b>’ | 10763 ‘<b><</b>’ | ‘<b><=</b>’ | ‘<b>></b>’ | ‘<b>>=</b>’ | ‘<b>==</b>’ | ‘<b>~=</b>’ | 10764 <b>and</b> | <b>or</b> 10765 10766 unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’ | ‘<b>~</b>’ 10767 10768 </pre> 10769 10770 <p> 10771 10772 10773 10774 10775 10776 10777 10778 10779 <HR> 10780 <SMALL CLASS="footer"> 10781 Last update: 10782 Tue Jan 6 10:10:50 BRST 2015 10783 </SMALL> 10784 <!-- 10785 Last change: revised for Lua 5.3.0 (final) 10786 --> 10787 10788 </body></html> 10789 10790
Indexes created Mon May 04 00:23:20 UTC 2026