1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<TITLE>Lua 5.3 Reference Manual</TITLE> 5<LINK REL="stylesheet" TYPE="text/css" HREF="lua.css"> 6<LINK REL="stylesheet" TYPE="text/css" HREF="manual.css"> 7<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> 8</HEAD> 9 10<BODY> 11 12<H1> 13<A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A> 14Lua 5.3 Reference Manual 15</H1> 16 17<P> 18by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes 19 20<P> 21<SMALL> 22Copyright © 2015–2018 Lua.org, PUC-Rio. 23Freely available under the terms of the 24<a href="http://www.lua.org/license.html">Lua license</a>. 25</SMALL> 26 27<DIV CLASS="menubar"> 28<A HREF="contents.html#contents">contents</A> 29· 30<A HREF="contents.html#index">index</A> 31· 32<A HREF="http://www.lua.org/manual/">other versions</A> 33</DIV> 34 35<!-- ====================================================================== --> 36<p> 37 38<!-- $Id: manual.of,v 1.167.1.2 2018/06/26 15:49:07 roberto Exp $ --> 39 40 41 42 43<h1>1 – <a name="1">Introduction</a></h1> 44 45<p> 46Lua is a powerful, efficient, lightweight, embeddable scripting language. 47It supports procedural programming, 48object-oriented programming, functional programming, 49data-driven programming, and data description. 50 51 52<p> 53Lua combines simple procedural syntax with powerful data description 54constructs based on associative arrays and extensible semantics. 55Lua is dynamically typed, 56runs by interpreting bytecode with a register-based 57virtual machine, 58and has automatic memory management with 59incremental garbage collection, 60making it ideal for configuration, scripting, 61and rapid prototyping. 62 63 64<p> 65Lua is implemented as a library, written in <em>clean C</em>, 66the common subset of Standard C and C++. 67The Lua distribution includes a host program called <code>lua</code>, 68which uses the Lua library to offer a complete, 69standalone Lua interpreter, 70for interactive or batch use. 71Lua is intended to be used both as a powerful, lightweight, 72embeddable scripting language for any program that needs one, 73and as a powerful but lightweight and efficient stand-alone language. 74 75 76<p> 77As an extension language, Lua has no notion of a "main" program: 78it works <em>embedded</em> in a host client, 79called the <em>embedding program</em> or simply the <em>host</em>. 80(Frequently, this host is the stand-alone <code>lua</code> program.) 81The host program can invoke functions to execute a piece of Lua code, 82can write and read Lua variables, 83and can register C functions to be called by Lua code. 84Through the use of C functions, Lua can be augmented to cope with 85a wide range of different domains, 86thus creating customized programming languages sharing a syntactical framework. 87 88 89<p> 90Lua is free software, 91and is provided as usual with no guarantees, 92as stated in its license. 93The implementation described in this manual is available 94at Lua's official web site, <code>www.lua.org</code>. 95 96 97<p> 98Like any other reference manual, 99this document is dry in places. 100For a discussion of the decisions behind the design of Lua, 101see the technical papers available at Lua's web site. 102For a detailed introduction to programming in Lua, 103see Roberto's book, <em>Programming in Lua</em>. 104 105 106 107<h1>2 – <a name="2">Basic Concepts</a></h1> 108 109<p> 110This section describes the basic concepts of the language. 111 112 113 114<h2>2.1 – <a name="2.1">Values and Types</a></h2> 115 116<p> 117Lua is a <em>dynamically typed language</em>. 118This means that 119variables do not have types; only values do. 120There are no type definitions in the language. 121All values carry their own type. 122 123 124<p> 125All values in Lua are <em>first-class values</em>. 126This means that all values can be stored in variables, 127passed as arguments to other functions, and returned as results. 128 129 130<p> 131There are eight basic types in Lua: 132<em>nil</em>, <em>boolean</em>, <em>number</em>, 133<em>string</em>, <em>function</em>, <em>userdata</em>, 134<em>thread</em>, and <em>table</em>. 135The type <em>nil</em> has one single value, <b>nil</b>, 136whose main property is to be different from any other value; 137it usually represents the absence of a useful value. 138The type <em>boolean</em> has two values, <b>false</b> and <b>true</b>. 139Both <b>nil</b> and <b>false</b> make a condition false; 140any other value makes it true. 141The type <em>number</em> represents both 142integer numbers and real (floating-point) numbers. 143The type <em>string</em> represents immutable sequences of bytes. 144 145Lua is 8-bit clean: 146strings can contain any 8-bit value, 147including embedded zeros ('<code>\0</code>'). 148Lua is also encoding-agnostic; 149it makes no assumptions about the contents of a string. 150 151 152<p> 153The type <em>number</em> uses two internal representations, 154or two subtypes, 155one called <em>integer</em> and the other called <em>float</em>. 156Lua has explicit rules about when each representation is used, 157but it also converts between them automatically as needed (see <a href="#3.4.3">§3.4.3</a>). 158Therefore, 159the programmer may choose to mostly ignore the difference 160between integers and floats 161or to assume complete control over the representation of each number. 162Standard Lua uses 64-bit integers and double-precision (64-bit) floats, 163but you can also compile Lua so that it 164uses 32-bit integers and/or single-precision (32-bit) floats. 165The option with 32 bits for both integers and floats 166is particularly attractive 167for small machines and embedded systems. 168(See macro <code>LUA_32BITS</code> in file <code>luaconf.h</code>.) 169 170 171<p> 172Lua can call (and manipulate) functions written in Lua and 173functions written in C (see <a href="#3.4.10">§3.4.10</a>). 174Both are represented by the type <em>function</em>. 175 176 177<p> 178The type <em>userdata</em> is provided to allow arbitrary C data to 179be stored in Lua variables. 180A userdata value represents a block of raw memory. 181There are two kinds of userdata: 182<em>full userdata</em>, 183which is an object with a block of memory managed by Lua, 184and <em>light userdata</em>, 185which is simply a C pointer value. 186Userdata has no predefined operations in Lua, 187except assignment and identity test. 188By using <em>metatables</em>, 189the programmer can define operations for full userdata values 190(see <a href="#2.4">§2.4</a>). 191Userdata values cannot be created or modified in Lua, 192only through the C API. 193This guarantees the integrity of data owned by the host program. 194 195 196<p> 197The type <em>thread</em> represents independent threads of execution 198and it is used to implement coroutines (see <a href="#2.6">§2.6</a>). 199Lua threads are not related to operating-system threads. 200Lua supports coroutines on all systems, 201even those that do not support threads natively. 202 203 204<p> 205The type <em>table</em> implements associative arrays, 206that is, arrays that can have as indices not only numbers, 207but any Lua value except <b>nil</b> and NaN. 208(<em>Not a Number</em> is a special value used to represent 209undefined or unrepresentable numerical results, such as <code>0/0</code>.) 210Tables can be <em>heterogeneous</em>; 211that is, they can contain values of all types (except <b>nil</b>). 212Any key with value <b>nil</b> is not considered part of the table. 213Conversely, any key that is not part of a table has 214an associated value <b>nil</b>. 215 216 217<p> 218Tables are the sole data-structuring mechanism in Lua; 219they can be used to represent ordinary arrays, lists, 220symbol tables, sets, records, graphs, trees, etc. 221To represent records, Lua uses the field name as an index. 222The language supports this representation by 223providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. 224There are several convenient ways to create tables in Lua 225(see <a href="#3.4.9">§3.4.9</a>). 226 227 228<p> 229Like indices, 230the values of table fields can be of any type. 231In particular, 232because functions are first-class values, 233table fields can contain functions. 234Thus tables can also carry <em>methods</em> (see <a href="#3.4.11">§3.4.11</a>). 235 236 237<p> 238The indexing of tables follows 239the definition of raw equality in the language. 240The expressions <code>a[i]</code> and <code>a[j]</code> 241denote the same table element 242if and only if <code>i</code> and <code>j</code> are raw equal 243(that is, equal without metamethods). 244In particular, floats with integral values 245are equal to their respective integers 246(e.g., <code>1.0 == 1</code>). 247To avoid ambiguities, 248any float with integral value used as a key 249is converted to its respective integer. 250For instance, if you write <code>a[2.0] = true</code>, 251the actual key inserted into the table will be the 252integer <code>2</code>. 253(On the other hand, 2542 and "<code>2</code>" are different Lua values and therefore 255denote different table entries.) 256 257 258<p> 259Tables, functions, threads, and (full) userdata values are <em>objects</em>: 260variables do not actually <em>contain</em> these values, 261only <em>references</em> to them. 262Assignment, parameter passing, and function returns 263always manipulate references to such values; 264these operations do not imply any kind of copy. 265 266 267<p> 268The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type 269of a given value (see <a href="#6.1">§6.1</a>). 270 271 272 273 274 275<h2>2.2 – <a name="2.2">Environments and the Global Environment</a></h2> 276 277<p> 278As will be discussed in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>, 279any reference to a free name 280(that is, a name not bound to any declaration) <code>var</code> 281is syntactically translated to <code>_ENV.var</code>. 282Moreover, every chunk is compiled in the scope of 283an external local variable named <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>), 284so <code>_ENV</code> itself is never a free name in a chunk. 285 286 287<p> 288Despite the existence of this external <code>_ENV</code> variable and 289the translation of free names, 290<code>_ENV</code> is a completely regular name. 291In particular, 292you can define new variables and parameters with that name. 293Each reference to a free name uses the <code>_ENV</code> that is 294visible at that point in the program, 295following the usual visibility rules of Lua (see <a href="#3.5">§3.5</a>). 296 297 298<p> 299Any table used as the value of <code>_ENV</code> is called an <em>environment</em>. 300 301 302<p> 303Lua keeps a distinguished environment called the <em>global environment</em>. 304This value is kept at a special index in the C registry (see <a href="#4.5">§4.5</a>). 305In Lua, the global variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value. 306(<a href="#pdf-_G"><code>_G</code></a> is never used internally.) 307 308 309<p> 310When Lua loads a chunk, 311the default value for its <code>_ENV</code> upvalue 312is the global environment (see <a href="#pdf-load"><code>load</code></a>). 313Therefore, by default, 314free names in Lua code refer to entries in the global environment 315(and, therefore, they are also called <em>global variables</em>). 316Moreover, all standard libraries are loaded in the global environment 317and some functions there operate on that environment. 318You can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>) 319to load a chunk with a different environment. 320(In C, you have to load the chunk and then change the value 321of its first upvalue.) 322 323 324 325 326 327<h2>2.3 – <a name="2.3">Error Handling</a></h2> 328 329<p> 330Because Lua is an embedded extension language, 331all Lua actions start from C code in the host program 332calling a function from the Lua library. 333(When you use Lua standalone, 334the <code>lua</code> application is the host program.) 335Whenever an error occurs during 336the compilation or execution of a Lua chunk, 337control returns to the host, 338which can take appropriate measures 339(such as printing an error message). 340 341 342<p> 343Lua code can explicitly generate an error by calling the 344<a href="#pdf-error"><code>error</code></a> function. 345If you need to catch errors in Lua, 346you can use <a href="#pdf-pcall"><code>pcall</code></a> or <a href="#pdf-xpcall"><code>xpcall</code></a> 347to call a given function in <em>protected mode</em>. 348 349 350<p> 351Whenever there is an error, 352an <em>error object</em> (also called an <em>error message</em>) 353is propagated with information about the error. 354Lua itself only generates errors whose error object is a string, 355but programs may generate errors with 356any value as the error object. 357It is up to the Lua program or its host to handle such error objects. 358 359 360<p> 361When you use <a href="#pdf-xpcall"><code>xpcall</code></a> or <a href="#lua_pcall"><code>lua_pcall</code></a>, 362you may give a <em>message handler</em> 363to be called in case of errors. 364This function is called with the original error object 365and returns a new error object. 366It is called before the error unwinds the stack, 367so that it can gather more information about the error, 368for instance by inspecting the stack and creating a stack traceback. 369This message handler is still protected by the protected call; 370so, an error inside the message handler 371will call the message handler again. 372If this loop goes on for too long, 373Lua breaks it and returns an appropriate message. 374(The message handler is called only for regular runtime errors. 375It is not called for memory-allocation errors 376nor for errors while running finalizers.) 377 378 379 380 381 382<h2>2.4 – <a name="2.4">Metatables and Metamethods</a></h2> 383 384<p> 385Every value in Lua can have a <em>metatable</em>. 386This <em>metatable</em> is an ordinary Lua table 387that defines the behavior of the original value 388under certain special operations. 389You can change several aspects of the behavior 390of operations over a value by setting specific fields in its metatable. 391For instance, when a non-numeric value is the operand of an addition, 392Lua checks for a function in the field "<code>__add</code>" of the value's metatable. 393If it finds one, 394Lua calls this function to perform the addition. 395 396 397<p> 398The key for each event in a metatable is a string 399with the event name prefixed by two underscores; 400the corresponding values are called <em>metamethods</em>. 401In the previous example, the key is "<code>__add</code>" 402and the metamethod is the function that performs the addition. 403Unless stated otherwise, 404metamethods should be function values. 405 406 407<p> 408You can query the metatable of any value 409using the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function. 410Lua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>). 411So, to retrieve the metamethod for event <code>ev</code> in object <code>o</code>, 412Lua does the equivalent to the following code: 413 414<pre> 415 rawget(getmetatable(<em>o</em>) or {}, "__<em>ev</em>") 416</pre> 417 418<p> 419You can replace the metatable of tables 420using the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function. 421You cannot change the metatable of other types from Lua code 422(except by using the debug library (<a href="#6.10">§6.10</a>)); 423you should use the C API for that. 424 425 426<p> 427Tables and full userdata have individual metatables 428(although multiple tables and userdata can share their metatables). 429Values of all other types share one single metatable per type; 430that is, there is one single metatable for all numbers, 431one for all strings, etc. 432By default, a value has no metatable, 433but the string library sets a metatable for the string type (see <a href="#6.4">§6.4</a>). 434 435 436<p> 437A metatable controls how an object behaves in 438arithmetic operations, bitwise operations, 439order comparisons, concatenation, length operation, calls, and indexing. 440A metatable also can define a function to be called 441when a userdata or a table is garbage collected (<a href="#2.5">§2.5</a>). 442 443 444<p> 445For the unary operators (negation, length, and bitwise NOT), 446the metamethod is computed and called with a dummy second operand, 447equal to the first one. 448This extra operand is only to simplify Lua's internals 449(by making these operators behave like a binary operation) 450and may be removed in future versions. 451(For most uses this extra operand is irrelevant.) 452 453 454<p> 455A detailed list of events controlled by metatables is given next. 456Each operation is identified by its corresponding key. 457 458 459 460<ul> 461 462<li><b><code>__add</code>: </b> 463the addition (<code>+</code>) operation. 464If any operand for an addition is not a number 465(nor a string coercible to a number), 466Lua will try to call a metamethod. 467First, Lua will check the first operand (even if it is valid). 468If that operand does not define a metamethod for <code>__add</code>, 469then Lua will check the second operand. 470If Lua can find a metamethod, 471it calls the metamethod with the two operands as arguments, 472and the result of the call 473(adjusted to one value) 474is the result of the operation. 475Otherwise, 476it raises an error. 477</li> 478 479<li><b><code>__sub</code>: </b> 480the subtraction (<code>-</code>) operation. 481Behavior similar to the addition operation. 482</li> 483 484<li><b><code>__mul</code>: </b> 485the multiplication (<code>*</code>) operation. 486Behavior similar to the addition operation. 487</li> 488 489<li><b><code>__div</code>: </b> 490the division (<code>/</code>) operation. 491Behavior similar to the addition operation. 492</li> 493 494<li><b><code>__mod</code>: </b> 495the modulo (<code>%</code>) operation. 496Behavior similar to the addition operation. 497</li> 498 499<li><b><code>__pow</code>: </b> 500the exponentiation (<code>^</code>) operation. 501Behavior similar to the addition operation. 502</li> 503 504<li><b><code>__unm</code>: </b> 505the negation (unary <code>-</code>) operation. 506Behavior similar to the addition operation. 507</li> 508 509<li><b><code>__idiv</code>: </b> 510the floor division (<code>//</code>) operation. 511Behavior similar to the addition operation. 512</li> 513 514<li><b><code>__band</code>: </b> 515the bitwise AND (<code>&</code>) operation. 516Behavior similar to the addition operation, 517except that Lua will try a metamethod 518if any operand is neither an integer 519nor a value coercible to an integer (see <a href="#3.4.3">§3.4.3</a>). 520</li> 521 522<li><b><code>__bor</code>: </b> 523the bitwise OR (<code>|</code>) operation. 524Behavior similar to the bitwise AND operation. 525</li> 526 527<li><b><code>__bxor</code>: </b> 528the bitwise exclusive OR (binary <code>~</code>) operation. 529Behavior similar to the bitwise AND operation. 530</li> 531 532<li><b><code>__bnot</code>: </b> 533the bitwise NOT (unary <code>~</code>) operation. 534Behavior similar to the bitwise AND operation. 535</li> 536 537<li><b><code>__shl</code>: </b> 538the bitwise left shift (<code><<</code>) operation. 539Behavior similar to the bitwise AND operation. 540</li> 541 542<li><b><code>__shr</code>: </b> 543the bitwise right shift (<code>>></code>) operation. 544Behavior similar to the bitwise AND operation. 545</li> 546 547<li><b><code>__concat</code>: </b> 548the concatenation (<code>..</code>) operation. 549Behavior similar to the addition operation, 550except that Lua will try a metamethod 551if any operand is neither a string nor a number 552(which is always coercible to a string). 553</li> 554 555<li><b><code>__len</code>: </b> 556the length (<code>#</code>) operation. 557If the object is not a string, 558Lua will try its metamethod. 559If there is a metamethod, 560Lua calls it with the object as argument, 561and the result of the call 562(always adjusted to one value) 563is the result of the operation. 564If there is no metamethod but the object is a table, 565then Lua uses the table length operation (see <a href="#3.4.7">§3.4.7</a>). 566Otherwise, Lua raises an error. 567</li> 568 569<li><b><code>__eq</code>: </b> 570the equal (<code>==</code>) operation. 571Behavior similar to the addition operation, 572except that Lua will try a metamethod only when the values 573being compared are either both tables or both full userdata 574and they are not primitively equal. 575The result of the call is always converted to a boolean. 576</li> 577 578<li><b><code>__lt</code>: </b> 579the less than (<code><</code>) operation. 580Behavior similar to the addition operation, 581except that Lua will try a metamethod only when the values 582being compared are neither both numbers nor both strings. 583The result of the call is always converted to a boolean. 584</li> 585 586<li><b><code>__le</code>: </b> 587the less equal (<code><=</code>) operation. 588Unlike other operations, 589the less-equal operation can use two different events. 590First, Lua looks for the <code>__le</code> metamethod in both operands, 591like in the less than operation. 592If it cannot find such a metamethod, 593then it will try the <code>__lt</code> metamethod, 594assuming that <code>a <= b</code> is equivalent to <code>not (b < a)</code>. 595As with the other comparison operators, 596the result is always a boolean. 597(This use of the <code>__lt</code> event can be removed in future versions; 598it is also slower than a real <code>__le</code> metamethod.) 599</li> 600 601<li><b><code>__index</code>: </b> 602The indexing access operation <code>table[key]</code>. 603This event happens when <code>table</code> is not a table or 604when <code>key</code> is not present in <code>table</code>. 605The metamethod is looked up in <code>table</code>. 606 607 608<p> 609Despite the name, 610the metamethod for this event can be either a function or a table. 611If it is a function, 612it is called with <code>table</code> and <code>key</code> as arguments, 613and the result of the call 614(adjusted to one value) 615is the result of the operation. 616If it is a table, 617the final result is the result of indexing this table with <code>key</code>. 618(This indexing is regular, not raw, 619and therefore can trigger another metamethod.) 620</li> 621 622<li><b><code>__newindex</code>: </b> 623The indexing assignment <code>table[key] = value</code>. 624Like the index event, 625this event happens when <code>table</code> is not a table or 626when <code>key</code> is not present in <code>table</code>. 627The metamethod is looked up in <code>table</code>. 628 629 630<p> 631Like with indexing, 632the metamethod for this event can be either a function or a table. 633If it is a function, 634it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments. 635If it is a table, 636Lua does an indexing assignment to this table with the same key and value. 637(This assignment is regular, not raw, 638and therefore can trigger another metamethod.) 639 640 641<p> 642Whenever there is a <code>__newindex</code> metamethod, 643Lua does not perform the primitive assignment. 644(If necessary, 645the metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a> 646to do the assignment.) 647</li> 648 649<li><b><code>__call</code>: </b> 650The call operation <code>func(args)</code>. 651This event happens when Lua tries to call a non-function value 652(that is, <code>func</code> is not a function). 653The metamethod is looked up in <code>func</code>. 654If present, 655the metamethod is called with <code>func</code> as its first argument, 656followed by the arguments of the original call (<code>args</code>). 657All results of the call 658are the result of the operation. 659(This is the only metamethod that allows multiple results.) 660</li> 661 662</ul> 663 664<p> 665It is a good practice to add all needed metamethods to a table 666before setting it as a metatable of some object. 667In particular, the <code>__gc</code> metamethod works only when this order 668is followed (see <a href="#2.5.1">§2.5.1</a>). 669 670 671<p> 672Because metatables are regular tables, 673they can contain arbitrary fields, 674not only the event names defined above. 675Some functions in the standard library 676(e.g., <a href="#pdf-tostring"><code>tostring</code></a>) 677use other fields in metatables for their own purposes. 678 679 680 681 682 683<h2>2.5 – <a name="2.5">Garbage Collection</a></h2> 684 685<p> 686Lua performs automatic memory management. 687This means that 688you do not have to worry about allocating memory for new objects 689or freeing it when the objects are no longer needed. 690Lua manages memory automatically by running 691a <em>garbage collector</em> to collect all <em>dead objects</em> 692(that is, objects that are no longer accessible from Lua). 693All memory used by Lua is subject to automatic management: 694strings, tables, userdata, functions, threads, internal structures, etc. 695 696 697<p> 698Lua implements an incremental mark-and-sweep collector. 699It uses two numbers to control its garbage-collection cycles: 700the <em>garbage-collector pause</em> and 701the <em>garbage-collector step multiplier</em>. 702Both use percentage points as units 703(e.g., a value of 100 means an internal value of 1). 704 705 706<p> 707The garbage-collector pause 708controls how long the collector waits before starting a new cycle. 709Larger values make the collector less aggressive. 710Values smaller than 100 mean the collector will not wait to 711start a new cycle. 712A value of 200 means that the collector waits for the total memory in use 713to double before starting a new cycle. 714 715 716<p> 717The garbage-collector step multiplier 718controls the relative speed of the collector relative to 719memory allocation. 720Larger values make the collector more aggressive but also increase 721the size of each incremental step. 722You should not use values smaller than 100, 723because they make the collector too slow and 724can result in the collector never finishing a cycle. 725The default is 200, 726which means that the collector runs at "twice" 727the speed of memory allocation. 728 729 730<p> 731If you set the step multiplier to a very large number 732(larger than 10% of the maximum number of 733bytes that the program may use), 734the collector behaves like a stop-the-world collector. 735If you then set the pause to 200, 736the collector behaves as in old Lua versions, 737doing a complete collection every time Lua doubles its 738memory usage. 739 740 741<p> 742You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C 743or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. 744You can also use these functions to control 745the collector directly (e.g., stop and restart it). 746 747 748 749<h3>2.5.1 – <a name="2.5.1">Garbage-Collection Metamethods</a></h3> 750 751<p> 752You can set garbage-collector metamethods for tables 753and, using the C API, 754for full userdata (see <a href="#2.4">§2.4</a>). 755These metamethods are also called <em>finalizers</em>. 756Finalizers allow you to coordinate Lua's garbage collection 757with external resource management 758(such as closing files, network or database connections, 759or freeing your own memory). 760 761 762<p> 763For an object (table or userdata) to be finalized when collected, 764you must <em>mark</em> it for finalization. 765 766You mark an object for finalization when you set its metatable 767and the metatable has a field indexed by the string "<code>__gc</code>". 768Note that if you set a metatable without a <code>__gc</code> field 769and later create that field in the metatable, 770the object will not be marked for finalization. 771 772 773<p> 774When a marked object becomes garbage, 775it is not collected immediately by the garbage collector. 776Instead, Lua puts it in a list. 777After the collection, 778Lua goes through that list. 779For each object in the list, 780it checks the object's <code>__gc</code> metamethod: 781If it is a function, 782Lua calls it with the object as its single argument; 783if the metamethod is not a function, 784Lua simply ignores it. 785 786 787<p> 788At the end of each garbage-collection cycle, 789the finalizers for objects are called in 790the reverse order that the objects were marked for finalization, 791among those collected in that cycle; 792that is, the first finalizer to be called is the one associated 793with the object marked last in the program. 794The execution of each finalizer may occur at any point during 795the execution of the regular code. 796 797 798<p> 799Because the object being collected must still be used by the finalizer, 800that object (and other objects accessible only through it) 801must be <em>resurrected</em> by Lua. 802Usually, this resurrection is transient, 803and the object memory is freed in the next garbage-collection cycle. 804However, if the finalizer stores the object in some global place 805(e.g., a global variable), 806then the resurrection is permanent. 807Moreover, if the finalizer marks a finalizing object for finalization again, 808its finalizer will be called again in the next cycle where the 809object is unreachable. 810In any case, 811the object memory is freed only in a GC cycle where 812the object is unreachable and not marked for finalization. 813 814 815<p> 816When you close a state (see <a href="#lua_close"><code>lua_close</code></a>), 817Lua calls the finalizers of all objects marked for finalization, 818following the reverse order that they were marked. 819If any finalizer marks objects for collection during that phase, 820these marks have no effect. 821 822 823 824 825 826<h3>2.5.2 – <a name="2.5.2">Weak Tables</a></h3> 827 828<p> 829A <em>weak table</em> is a table whose elements are 830<em>weak references</em>. 831A weak reference is ignored by the garbage collector. 832In other words, 833if the only references to an object are weak references, 834then the garbage collector will collect that object. 835 836 837<p> 838A weak table can have weak keys, weak values, or both. 839A table with weak values allows the collection of its values, 840but prevents the collection of its keys. 841A table with both weak keys and weak values allows the collection of 842both keys and values. 843In any case, if either the key or the value is collected, 844the whole pair is removed from the table. 845The weakness of a table is controlled by the 846<code>__mode</code> field of its metatable. 847If the <code>__mode</code> field is a string containing the character '<code>k</code>', 848the keys in the table are weak. 849If <code>__mode</code> contains '<code>v</code>', 850the values in the table are weak. 851 852 853<p> 854A table with weak keys and strong values 855is also called an <em>ephemeron table</em>. 856In an ephemeron table, 857a value is considered reachable only if its key is reachable. 858In particular, 859if the only reference to a key comes through its value, 860the pair is removed. 861 862 863<p> 864Any change in the weakness of a table may take effect only 865at the next collect cycle. 866In particular, if you change the weakness to a stronger mode, 867Lua may still collect some items from that table 868before the change takes effect. 869 870 871<p> 872Only objects that have an explicit construction 873are removed from weak tables. 874Values, such as numbers and light C functions, 875are not subject to garbage collection, 876and therefore are not removed from weak tables 877(unless their associated values are collected). 878Although strings are subject to garbage collection, 879they do not have an explicit construction, 880and therefore are not removed from weak tables. 881 882 883<p> 884Resurrected objects 885(that is, objects being finalized 886and objects accessible only through objects being finalized) 887have a special behavior in weak tables. 888They are removed from weak values before running their finalizers, 889but are removed from weak keys only in the next collection 890after running their finalizers, when such objects are actually freed. 891This behavior allows the finalizer to access properties 892associated with the object through weak tables. 893 894 895<p> 896If a weak table is among the resurrected objects in a collection cycle, 897it may not be properly cleared until the next cycle. 898 899 900 901 902 903 904 905<h2>2.6 – <a name="2.6">Coroutines</a></h2> 906 907<p> 908Lua supports coroutines, 909also called <em>collaborative multithreading</em>. 910A coroutine in Lua represents an independent thread of execution. 911Unlike threads in multithread systems, however, 912a coroutine only suspends its execution by explicitly calling 913a yield function. 914 915 916<p> 917You create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>. 918Its sole argument is a function 919that is the main function of the coroutine. 920The <code>create</code> function only creates a new coroutine and 921returns a handle to it (an object of type <em>thread</em>); 922it does not start the coroutine. 923 924 925<p> 926You execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 927When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 928passing as its first argument 929a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 930the coroutine starts its execution by 931calling its main function. 932Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed 933as arguments to that function. 934After the coroutine starts running, 935it runs until it terminates or <em>yields</em>. 936 937 938<p> 939A coroutine can terminate its execution in two ways: 940normally, when its main function returns 941(explicitly or implicitly, after the last instruction); 942and abnormally, if there is an unprotected error. 943In case of normal termination, 944<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>, 945plus any values returned by the coroutine main function. 946In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b> 947plus an error object. 948 949 950<p> 951A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 952When a coroutine yields, 953the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately, 954even if the yield happens inside nested function calls 955(that is, not in the main function, 956but in a function directly or indirectly called by the main function). 957In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>, 958plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 959The next time you resume the same coroutine, 960it continues its execution from the point where it yielded, 961with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra 962arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 963 964 965<p> 966Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 967the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine, 968but instead of returning the coroutine itself, 969it returns a function that, when called, resumes the coroutine. 970Any arguments passed to this function 971go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 972<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>, 973except the first one (the boolean error code). 974Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 975<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors; 976any error is propagated to the caller. 977 978 979<p> 980As an example of how coroutines work, 981consider the following code: 982 983<pre> 984 function foo (a) 985 print("foo", a) 986 return coroutine.yield(2*a) 987 end 988 989 co = coroutine.create(function (a,b) 990 print("co-body", a, b) 991 local r = foo(a+1) 992 print("co-body", r) 993 local r, s = coroutine.yield(a+b, a-b) 994 print("co-body", r, s) 995 return b, "end" 996 end) 997 998 print("main", coroutine.resume(co, 1, 10)) 999 print("main", coroutine.resume(co, "r")) 1000 print("main", coroutine.resume(co, "x", "y")) 1001 print("main", coroutine.resume(co, "x", "y")) 1002</pre><p> 1003When you run it, it produces the following output: 1004 1005<pre> 1006 co-body 1 10 1007 foo 2 1008 main true 4 1009 co-body r 1010 main true 11 -9 1011 co-body x y 1012 main true 10 end 1013 main false cannot resume dead coroutine 1014</pre> 1015 1016<p> 1017You can also create and manipulate coroutines through the C API: 1018see functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>, 1019and <a href="#lua_yield"><code>lua_yield</code></a>. 1020 1021 1022 1023 1024 1025<h1>3 – <a name="3">The Language</a></h1> 1026 1027<p> 1028This section describes the lexis, the syntax, and the semantics of Lua. 1029In other words, 1030this section describes 1031which tokens are valid, 1032how they can be combined, 1033and what their combinations mean. 1034 1035 1036<p> 1037Language constructs will be explained using the usual extended BNF notation, 1038in which 1039{<em>a</em>} means 0 or more <em>a</em>'s, and 1040[<em>a</em>] means an optional <em>a</em>. 1041Non-terminals are shown like non-terminal, 1042keywords are shown like <b>kword</b>, 1043and other terminal symbols are shown like ‘<b>=</b>’. 1044The complete syntax of Lua can be found in <a href="#9">§9</a> 1045at the end of this manual. 1046 1047 1048 1049<h2>3.1 – <a name="3.1">Lexical Conventions</a></h2> 1050 1051<p> 1052Lua is a free-form language. 1053It ignores spaces (including new lines) and comments 1054between lexical elements (tokens), 1055except as delimiters between names and keywords. 1056 1057 1058<p> 1059<em>Names</em> 1060(also called <em>identifiers</em>) 1061in Lua can be any string of letters, 1062digits, and underscores, 1063not beginning with a digit and 1064not being a reserved word. 1065Identifiers are used to name variables, table fields, and labels. 1066 1067 1068<p> 1069The following <em>keywords</em> are reserved 1070and cannot be used as names: 1071 1072 1073<pre> 1074 and break do else elseif end 1075 false for function goto if in 1076 local nil not or repeat return 1077 then true until while 1078</pre> 1079 1080<p> 1081Lua is a case-sensitive language: 1082<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> 1083are two different, valid names. 1084As a convention, 1085programs should avoid creating 1086names that start with an underscore followed by 1087one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>). 1088 1089 1090<p> 1091The following strings denote other tokens: 1092 1093<pre> 1094 + - * / % ^ # 1095 & ~ | << >> // 1096 == ~= <= >= < > = 1097 ( ) { } [ ] :: 1098 ; : , . .. ... 1099</pre> 1100 1101<p> 1102A <em>short literal string</em> 1103can be delimited by matching single or double quotes, 1104and can contain the following C-like escape sequences: 1105'<code>\a</code>' (bell), 1106'<code>\b</code>' (backspace), 1107'<code>\f</code>' (form feed), 1108'<code>\n</code>' (newline), 1109'<code>\r</code>' (carriage return), 1110'<code>\t</code>' (horizontal tab), 1111'<code>\v</code>' (vertical tab), 1112'<code>\\</code>' (backslash), 1113'<code>\"</code>' (quotation mark [double quote]), 1114and '<code>\'</code>' (apostrophe [single quote]). 1115A backslash followed by a line break 1116results in a newline in the string. 1117The escape sequence '<code>\z</code>' skips the following span 1118of white-space characters, 1119including line breaks; 1120it is particularly useful to break and indent a long literal string 1121into multiple lines without adding the newlines and spaces 1122into the string contents. 1123A short literal string cannot contain unescaped line breaks 1124nor escapes not forming a valid escape sequence. 1125 1126 1127<p> 1128We can specify any byte in a short literal string by its numeric value 1129(including embedded zeros). 1130This can be done 1131with the escape sequence <code>\x<em>XX</em></code>, 1132where <em>XX</em> is a sequence of exactly two hexadecimal digits, 1133or with the escape sequence <code>\<em>ddd</em></code>, 1134where <em>ddd</em> is a sequence of up to three decimal digits. 1135(Note that if a decimal escape sequence is to be followed by a digit, 1136it must be expressed using exactly three digits.) 1137 1138 1139<p> 1140The UTF-8 encoding of a Unicode character 1141can be inserted in a literal string with 1142the escape sequence <code>\u{<em>XXX</em>}</code> 1143(note the mandatory enclosing brackets), 1144where <em>XXX</em> is a sequence of one or more hexadecimal digits 1145representing the character code point. 1146 1147 1148<p> 1149Literal strings can also be defined using a long format 1150enclosed by <em>long brackets</em>. 1151We define an <em>opening long bracket of level <em>n</em></em> as an opening 1152square bracket followed by <em>n</em> equal signs followed by another 1153opening square bracket. 1154So, an opening long bracket of level 0 is written as <code>[[</code>, 1155an opening long bracket of level 1 is written as <code>[=[</code>, 1156and so on. 1157A <em>closing long bracket</em> is defined similarly; 1158for instance, 1159a closing long bracket of level 4 is written as <code>]====]</code>. 1160A <em>long literal</em> starts with an opening long bracket of any level and 1161ends at the first closing long bracket of the same level. 1162It can contain any text except a closing bracket of the same level. 1163Literals in this bracketed form can run for several lines, 1164do not interpret any escape sequences, 1165and ignore long brackets of any other level. 1166Any kind of end-of-line sequence 1167(carriage return, newline, carriage return followed by newline, 1168or newline followed by carriage return) 1169is converted to a simple newline. 1170 1171 1172<p> 1173For convenience, 1174when the opening long bracket is immediately followed by a newline, 1175the newline is not included in the string. 1176As an example, in a system using ASCII 1177(in which '<code>a</code>' is coded as 97, 1178newline is coded as 10, and '<code>1</code>' is coded as 49), 1179the five literal strings below denote the same string: 1180 1181<pre> 1182 a = 'alo\n123"' 1183 a = "alo\n123\"" 1184 a = '\97lo\10\04923"' 1185 a = [[alo 1186 123"]] 1187 a = [==[ 1188 alo 1189 123"]==] 1190</pre> 1191 1192<p> 1193Any byte in a literal string not 1194explicitly affected by the previous rules represents itself. 1195However, Lua opens files for parsing in text mode, 1196and the system file functions may have problems with 1197some control characters. 1198So, it is safer to represent 1199non-text data as a quoted literal with 1200explicit escape sequences for the non-text characters. 1201 1202 1203<p> 1204A <em>numeric constant</em> (or <em>numeral</em>) 1205can be written with an optional fractional part 1206and an optional decimal exponent, 1207marked by a letter '<code>e</code>' or '<code>E</code>'. 1208Lua also accepts hexadecimal constants, 1209which start with <code>0x</code> or <code>0X</code>. 1210Hexadecimal constants also accept an optional fractional part 1211plus an optional binary exponent, 1212marked by a letter '<code>p</code>' or '<code>P</code>'. 1213A numeric constant with a radix point or an exponent 1214denotes a float; 1215otherwise, 1216if its value fits in an integer, 1217it denotes an integer. 1218Examples of valid integer constants are 1219 1220<pre> 1221 3 345 0xff 0xBEBADA 1222</pre><p> 1223Examples of valid float constants are 1224 1225<pre> 1226 3.0 3.1416 314.16e-2 0.31416E1 34e1 1227 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 1228</pre> 1229 1230<p> 1231A <em>comment</em> starts with a double hyphen (<code>--</code>) 1232anywhere outside a string. 1233If the text immediately after <code>--</code> is not an opening long bracket, 1234the comment is a <em>short comment</em>, 1235which runs until the end of the line. 1236Otherwise, it is a <em>long comment</em>, 1237which runs until the corresponding closing long bracket. 1238Long comments are frequently used to disable code temporarily. 1239 1240 1241 1242 1243 1244<h2>3.2 – <a name="3.2">Variables</a></h2> 1245 1246<p> 1247Variables are places that store values. 1248There are three kinds of variables in Lua: 1249global variables, local variables, and table fields. 1250 1251 1252<p> 1253A single name can denote a global variable or a local variable 1254(or a function's formal parameter, 1255which is a particular kind of local variable): 1256 1257<pre> 1258 var ::= Name 1259</pre><p> 1260Name denotes identifiers, as defined in <a href="#3.1">§3.1</a>. 1261 1262 1263<p> 1264Any variable name is assumed to be global unless explicitly declared 1265as a local (see <a href="#3.3.7">§3.3.7</a>). 1266Local variables are <em>lexically scoped</em>: 1267local variables can be freely accessed by functions 1268defined inside their scope (see <a href="#3.5">§3.5</a>). 1269 1270 1271<p> 1272Before the first assignment to a variable, its value is <b>nil</b>. 1273 1274 1275<p> 1276Square brackets are used to index a table: 1277 1278<pre> 1279 var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ 1280</pre><p> 1281The meaning of accesses to table fields can be changed via metatables 1282(see <a href="#2.4">§2.4</a>). 1283 1284 1285<p> 1286The syntax <code>var.Name</code> is just syntactic sugar for 1287<code>var["Name"]</code>: 1288 1289<pre> 1290 var ::= prefixexp ‘<b>.</b>’ Name 1291</pre> 1292 1293<p> 1294An access to a global variable <code>x</code> 1295is equivalent to <code>_ENV.x</code>. 1296Due to the way that chunks are compiled, 1297<code>_ENV</code> is never a global name (see <a href="#2.2">§2.2</a>). 1298 1299 1300 1301 1302 1303<h2>3.3 – <a name="3.3">Statements</a></h2> 1304 1305<p> 1306Lua supports an almost conventional set of statements, 1307similar to those in Pascal or C. 1308This set includes 1309assignments, control structures, function calls, 1310and variable declarations. 1311 1312 1313 1314<h3>3.3.1 – <a name="3.3.1">Blocks</a></h3> 1315 1316<p> 1317A block is a list of statements, 1318which are executed sequentially: 1319 1320<pre> 1321 block ::= {stat} 1322</pre><p> 1323Lua has <em>empty statements</em> 1324that allow you to separate statements with semicolons, 1325start a block with a semicolon 1326or write two semicolons in sequence: 1327 1328<pre> 1329 stat ::= ‘<b>;</b>’ 1330</pre> 1331 1332<p> 1333Function calls and assignments 1334can start with an open parenthesis. 1335This possibility leads to an ambiguity in Lua's grammar. 1336Consider the following fragment: 1337 1338<pre> 1339 a = b + c 1340 (print or io.write)('done') 1341</pre><p> 1342The grammar could see it in two ways: 1343 1344<pre> 1345 a = b + c(print or io.write)('done') 1346 1347 a = b + c; (print or io.write)('done') 1348</pre><p> 1349The current parser always sees such constructions 1350in the first way, 1351interpreting the open parenthesis 1352as the start of the arguments to a call. 1353To avoid this ambiguity, 1354it is a good practice to always precede with a semicolon 1355statements that start with a parenthesis: 1356 1357<pre> 1358 ;(print or io.write)('done') 1359</pre> 1360 1361<p> 1362A block can be explicitly delimited to produce a single statement: 1363 1364<pre> 1365 stat ::= <b>do</b> block <b>end</b> 1366</pre><p> 1367Explicit blocks are useful 1368to control the scope of variable declarations. 1369Explicit blocks are also sometimes used to 1370add a <b>return</b> statement in the middle 1371of another block (see <a href="#3.3.4">§3.3.4</a>). 1372 1373 1374 1375 1376 1377<h3>3.3.2 – <a name="3.3.2">Chunks</a></h3> 1378 1379<p> 1380The unit of compilation of Lua is called a <em>chunk</em>. 1381Syntactically, 1382a chunk is simply a block: 1383 1384<pre> 1385 chunk ::= block 1386</pre> 1387 1388<p> 1389Lua handles a chunk as the body of an anonymous function 1390with a variable number of arguments 1391(see <a href="#3.4.11">§3.4.11</a>). 1392As such, chunks can define local variables, 1393receive arguments, and return values. 1394Moreover, such anonymous function is compiled as in the 1395scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>). 1396The resulting function always has <code>_ENV</code> as its only upvalue, 1397even if it does not use that variable. 1398 1399 1400<p> 1401A chunk can be stored in a file or in a string inside the host program. 1402To execute a chunk, 1403Lua first <em>loads</em> it, 1404precompiling the chunk's code into instructions for a virtual machine, 1405and then Lua executes the compiled code 1406with an interpreter for the virtual machine. 1407 1408 1409<p> 1410Chunks can also be precompiled into binary form; 1411see program <code>luac</code> and function <a href="#pdf-string.dump"><code>string.dump</code></a> for details. 1412Programs in source and compiled forms are interchangeable; 1413Lua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>). 1414 1415 1416 1417 1418 1419<h3>3.3.3 – <a name="3.3.3">Assignment</a></h3> 1420 1421<p> 1422Lua allows multiple assignments. 1423Therefore, the syntax for assignment 1424defines a list of variables on the left side 1425and a list of expressions on the right side. 1426The elements in both lists are separated by commas: 1427 1428<pre> 1429 stat ::= varlist ‘<b>=</b>’ explist 1430 varlist ::= var {‘<b>,</b>’ var} 1431 explist ::= exp {‘<b>,</b>’ exp} 1432</pre><p> 1433Expressions are discussed in <a href="#3.4">§3.4</a>. 1434 1435 1436<p> 1437Before the assignment, 1438the list of values is <em>adjusted</em> to the length of 1439the list of variables. 1440If there are more values than needed, 1441the excess values are thrown away. 1442If there are fewer values than needed, 1443the list is extended with as many <b>nil</b>'s as needed. 1444If the list of expressions ends with a function call, 1445then all values returned by that call enter the list of values, 1446before the adjustment 1447(except when the call is enclosed in parentheses; see <a href="#3.4">§3.4</a>). 1448 1449 1450<p> 1451The assignment statement first evaluates all its expressions 1452and only then the assignments are performed. 1453Thus the code 1454 1455<pre> 1456 i = 3 1457 i, a[i] = i+1, 20 1458</pre><p> 1459sets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 1460because the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 1461before it is assigned 4. 1462Similarly, the line 1463 1464<pre> 1465 x, y = y, x 1466</pre><p> 1467exchanges the values of <code>x</code> and <code>y</code>, 1468and 1469 1470<pre> 1471 x, y, z = y, z, x 1472</pre><p> 1473cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 1474 1475 1476<p> 1477An assignment to a global name <code>x = val</code> 1478is equivalent to the assignment 1479<code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>). 1480 1481 1482<p> 1483The meaning of assignments to table fields and 1484global variables (which are actually table fields, too) 1485can be changed via metatables (see <a href="#2.4">§2.4</a>). 1486 1487 1488 1489 1490 1491<h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p> 1492The control structures 1493<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 1494familiar syntax: 1495 1496 1497 1498 1499<pre> 1500 stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 1501 stat ::= <b>repeat</b> block <b>until</b> exp 1502 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> 1503</pre><p> 1504Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>). 1505 1506 1507<p> 1508The condition expression of a 1509control structure can return any value. 1510Both <b>false</b> and <b>nil</b> are considered false. 1511All values different from <b>nil</b> and <b>false</b> are considered true 1512(in particular, the number 0 and the empty string are also true). 1513 1514 1515<p> 1516In the <b>repeat</b>–<b>until</b> loop, 1517the inner block does not end at the <b>until</b> keyword, 1518but only after the condition. 1519So, the condition can refer to local variables 1520declared inside the loop block. 1521 1522 1523<p> 1524The <b>goto</b> statement transfers the program control to a label. 1525For syntactical reasons, 1526labels in Lua are considered statements too: 1527 1528 1529 1530<pre> 1531 stat ::= <b>goto</b> Name 1532 stat ::= label 1533 label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 1534</pre> 1535 1536<p> 1537A label is visible in the entire block where it is defined, 1538except 1539inside nested blocks where a label with the same name is defined and 1540inside nested functions. 1541A goto may jump to any visible label as long as it does not 1542enter into the scope of a local variable. 1543 1544 1545<p> 1546Labels and empty statements are called <em>void statements</em>, 1547as they perform no actions. 1548 1549 1550<p> 1551The <b>break</b> statement terminates the execution of a 1552<b>while</b>, <b>repeat</b>, or <b>for</b> loop, 1553skipping to the next statement after the loop: 1554 1555 1556<pre> 1557 stat ::= <b>break</b> 1558</pre><p> 1559A <b>break</b> ends the innermost enclosing loop. 1560 1561 1562<p> 1563The <b>return</b> statement is used to return values 1564from a function or a chunk 1565(which is an anonymous function). 1566 1567Functions can return more than one value, 1568so the syntax for the <b>return</b> statement is 1569 1570<pre> 1571 stat ::= <b>return</b> [explist] [‘<b>;</b>’] 1572</pre> 1573 1574<p> 1575The <b>return</b> statement can only be written 1576as the last statement of a block. 1577If it is really necessary to <b>return</b> in the middle of a block, 1578then an explicit inner block can be used, 1579as in the idiom <code>do return end</code>, 1580because now <b>return</b> is the last statement in its (inner) block. 1581 1582 1583 1584 1585 1586<h3>3.3.5 – <a name="3.3.5">For Statement</a></h3> 1587 1588<p> 1589 1590The <b>for</b> statement has two forms: 1591one numerical and one generic. 1592 1593 1594<p> 1595The numerical <b>for</b> loop repeats a block of code while a 1596control variable runs through an arithmetic progression. 1597It has the following syntax: 1598 1599<pre> 1600 stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> 1601</pre><p> 1602The <em>block</em> is repeated for <em>name</em> starting at the value of 1603the first <em>exp</em>, until it passes the second <em>exp</em> by steps of the 1604third <em>exp</em>. 1605More precisely, a <b>for</b> statement like 1606 1607<pre> 1608 for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end 1609</pre><p> 1610is equivalent to the code: 1611 1612<pre> 1613 do 1614 local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>) 1615 if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end 1616 <em>var</em> = <em>var</em> - <em>step</em> 1617 while true do 1618 <em>var</em> = <em>var</em> + <em>step</em> 1619 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 1620 break 1621 end 1622 local v = <em>var</em> 1623 <em>block</em> 1624 end 1625 end 1626</pre> 1627 1628<p> 1629Note the following: 1630 1631<ul> 1632 1633<li> 1634All three control expressions are evaluated only once, 1635before the loop starts. 1636They must all result in numbers. 1637</li> 1638 1639<li> 1640<code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables. 1641The names shown here are for explanatory purposes only. 1642</li> 1643 1644<li> 1645If the third expression (the step) is absent, 1646then a step of 1 is used. 1647</li> 1648 1649<li> 1650You can use <b>break</b> and <b>goto</b> to exit a <b>for</b> loop. 1651</li> 1652 1653<li> 1654The loop variable <code>v</code> is local to the loop body. 1655If you need its value after the loop, 1656assign it to another variable before exiting the loop. 1657</li> 1658 1659</ul> 1660 1661<p> 1662The generic <b>for</b> statement works over functions, 1663called <em>iterators</em>. 1664On each iteration, the iterator function is called to produce a new value, 1665stopping when this new value is <b>nil</b>. 1666The generic <b>for</b> loop has the following syntax: 1667 1668<pre> 1669 stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> 1670 namelist ::= Name {‘<b>,</b>’ Name} 1671</pre><p> 1672A <b>for</b> statement like 1673 1674<pre> 1675 for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end 1676</pre><p> 1677is equivalent to the code: 1678 1679<pre> 1680 do 1681 local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em> 1682 while true do 1683 local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>) 1684 if <em>var_1</em> == nil then break end 1685 <em>var</em> = <em>var_1</em> 1686 <em>block</em> 1687 end 1688 end 1689</pre><p> 1690Note the following: 1691 1692<ul> 1693 1694<li> 1695<code><em>explist</em></code> is evaluated only once. 1696Its results are an <em>iterator</em> function, 1697a <em>state</em>, 1698and an initial value for the first <em>iterator variable</em>. 1699</li> 1700 1701<li> 1702<code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables. 1703The names are here for explanatory purposes only. 1704</li> 1705 1706<li> 1707You can use <b>break</b> to exit a <b>for</b> loop. 1708</li> 1709 1710<li> 1711The loop variables <code><em>var_i</em></code> are local to the loop; 1712you cannot use their values after the <b>for</b> ends. 1713If you need these values, 1714then assign them to other variables before breaking or exiting the loop. 1715</li> 1716 1717</ul> 1718 1719 1720 1721 1722<h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p> 1723To allow possible side-effects, 1724function calls can be executed as statements: 1725 1726<pre> 1727 stat ::= functioncall 1728</pre><p> 1729In this case, all returned values are thrown away. 1730Function calls are explained in <a href="#3.4.10">§3.4.10</a>. 1731 1732 1733 1734 1735 1736<h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p> 1737Local variables can be declared anywhere inside a block. 1738The declaration can include an initial assignment: 1739 1740<pre> 1741 stat ::= <b>local</b> namelist [‘<b>=</b>’ explist] 1742</pre><p> 1743If present, an initial assignment has the same semantics 1744of a multiple assignment (see <a href="#3.3.3">§3.3.3</a>). 1745Otherwise, all variables are initialized with <b>nil</b>. 1746 1747 1748<p> 1749A chunk is also a block (see <a href="#3.3.2">§3.3.2</a>), 1750and so local variables can be declared in a chunk outside any explicit block. 1751 1752 1753<p> 1754The visibility rules for local variables are explained in <a href="#3.5">§3.5</a>. 1755 1756 1757 1758 1759 1760 1761 1762<h2>3.4 – <a name="3.4">Expressions</a></h2> 1763 1764<p> 1765The basic expressions in Lua are the following: 1766 1767<pre> 1768 exp ::= prefixexp 1769 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 1770 exp ::= Numeral 1771 exp ::= LiteralString 1772 exp ::= functiondef 1773 exp ::= tableconstructor 1774 exp ::= ‘<b>...</b>’ 1775 exp ::= exp binop exp 1776 exp ::= unop exp 1777 prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 1778</pre> 1779 1780<p> 1781Numerals and literal strings are explained in <a href="#3.1">§3.1</a>; 1782variables are explained in <a href="#3.2">§3.2</a>; 1783function definitions are explained in <a href="#3.4.11">§3.4.11</a>; 1784function calls are explained in <a href="#3.4.10">§3.4.10</a>; 1785table constructors are explained in <a href="#3.4.9">§3.4.9</a>. 1786Vararg expressions, 1787denoted by three dots ('<code>...</code>'), can only be used when 1788directly inside a vararg function; 1789they are explained in <a href="#3.4.11">§3.4.11</a>. 1790 1791 1792<p> 1793Binary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), 1794bitwise operators (see <a href="#3.4.2">§3.4.2</a>), 1795relational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>), 1796and the concatenation operator (see <a href="#3.4.6">§3.4.6</a>). 1797Unary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), 1798the unary bitwise NOT (see <a href="#3.4.2">§3.4.2</a>), 1799the unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), 1800and the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). 1801 1802 1803<p> 1804Both function calls and vararg expressions can result in multiple values. 1805If a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>), 1806then its return list is adjusted to zero elements, 1807thus discarding all returned values. 1808If an expression is used as the last (or the only) element 1809of a list of expressions, 1810then no adjustment is made 1811(unless the expression is enclosed in parentheses). 1812In all other contexts, 1813Lua adjusts the result list to one element, 1814either discarding all values except the first one 1815or adding a single <b>nil</b> if there are no values. 1816 1817 1818<p> 1819Here are some examples: 1820 1821<pre> 1822 f() -- adjusted to 0 results 1823 g(f(), x) -- f() is adjusted to 1 result 1824 g(x, f()) -- g gets x plus all results from f() 1825 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) 1826 a,b = ... -- a gets the first vararg argument, b gets 1827 -- the second (both a and b can get nil if there 1828 -- is no corresponding vararg argument) 1829 1830 a,b,c = x, f() -- f() is adjusted to 2 results 1831 a,b,c = f() -- f() is adjusted to 3 results 1832 return f() -- returns all results from f() 1833 return ... -- returns all received vararg arguments 1834 return x,y,f() -- returns x, y, and all results from f() 1835 {f()} -- creates a list with all results from f() 1836 {...} -- creates a list with all vararg arguments 1837 {f(), nil} -- f() is adjusted to 1 result 1838</pre> 1839 1840<p> 1841Any expression enclosed in parentheses always results in only one value. 1842Thus, 1843<code>(f(x,y,z))</code> is always a single value, 1844even if <code>f</code> returns several values. 1845(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> 1846or <b>nil</b> if <code>f</code> does not return any values.) 1847 1848 1849 1850<h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p> 1851Lua supports the following arithmetic operators: 1852 1853<ul> 1854<li><b><code>+</code>: </b>addition</li> 1855<li><b><code>-</code>: </b>subtraction</li> 1856<li><b><code>*</code>: </b>multiplication</li> 1857<li><b><code>/</code>: </b>float division</li> 1858<li><b><code>//</code>: </b>floor division</li> 1859<li><b><code>%</code>: </b>modulo</li> 1860<li><b><code>^</code>: </b>exponentiation</li> 1861<li><b><code>-</code>: </b>unary minus</li> 1862</ul> 1863 1864<p> 1865With the exception of exponentiation and float division, 1866the arithmetic operators work as follows: 1867If both operands are integers, 1868the operation is performed over integers and the result is an integer. 1869Otherwise, if both operands are numbers 1870or strings that can be converted to 1871numbers (see <a href="#3.4.3">§3.4.3</a>), 1872then they are converted to floats, 1873the operation is performed following the usual rules 1874for floating-point arithmetic 1875(usually the IEEE 754 standard), 1876and the result is a float. 1877 1878 1879<p> 1880Exponentiation and float division (<code>/</code>) 1881always convert their operands to floats 1882and the result is always a float. 1883Exponentiation uses the ISO C function <code>pow</code>, 1884so that it works for non-integer exponents too. 1885 1886 1887<p> 1888Floor division (<code>//</code>) is a division 1889that rounds the quotient towards minus infinity, 1890that is, the floor of the division of its operands. 1891 1892 1893<p> 1894Modulo is defined as the remainder of a division 1895that rounds the quotient towards minus infinity (floor division). 1896 1897 1898<p> 1899In case of overflows in integer arithmetic, 1900all operations <em>wrap around</em>, 1901according to the usual rules of two-complement arithmetic. 1902(In other words, 1903they return the unique representable integer 1904that is equal modulo <em>2<sup>64</sup></em> to the mathematical result.) 1905 1906 1907 1908<h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p> 1909Lua supports the following bitwise operators: 1910 1911<ul> 1912<li><b><code>&</code>: </b>bitwise AND</li> 1913<li><b><code>|</code>: </b>bitwise OR</li> 1914<li><b><code>~</code>: </b>bitwise exclusive OR</li> 1915<li><b><code>>></code>: </b>right shift</li> 1916<li><b><code><<</code>: </b>left shift</li> 1917<li><b><code>~</code>: </b>unary bitwise NOT</li> 1918</ul> 1919 1920<p> 1921All bitwise operations convert its operands to integers 1922(see <a href="#3.4.3">§3.4.3</a>), 1923operate on all bits of those integers, 1924and result in an integer. 1925 1926 1927<p> 1928Both right and left shifts fill the vacant bits with zeros. 1929Negative displacements shift to the other direction; 1930displacements with absolute values equal to or higher than 1931the number of bits in an integer 1932result in zero (as all bits are shifted out). 1933 1934 1935 1936 1937 1938<h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p> 1939Lua provides some automatic conversions between some 1940types and representations at run time. 1941Bitwise operators always convert float operands to integers. 1942Exponentiation and float division 1943always convert integer operands to floats. 1944All other arithmetic operations applied to mixed numbers 1945(integers and floats) convert the integer operand to a float; 1946this is called the <em>usual rule</em>. 1947The C API also converts both integers to floats and 1948floats to integers, as needed. 1949Moreover, string concatenation accepts numbers as arguments, 1950besides strings. 1951 1952 1953<p> 1954Lua also converts strings to numbers, 1955whenever a number is expected. 1956 1957 1958<p> 1959In a conversion from integer to float, 1960if the integer value has an exact representation as a float, 1961that is the result. 1962Otherwise, 1963the conversion gets the nearest higher or 1964the nearest lower representable value. 1965This kind of conversion never fails. 1966 1967 1968<p> 1969The conversion from float to integer 1970checks whether the float has an exact representation as an integer 1971(that is, the float has an integral value and 1972it is in the range of integer representation). 1973If it does, that representation is the result. 1974Otherwise, the conversion fails. 1975 1976 1977<p> 1978The conversion from strings to numbers goes as follows: 1979First, the string is converted to an integer or a float, 1980following its syntax and the rules of the Lua lexer. 1981(The string may have also leading and trailing spaces and a sign.) 1982Then, the resulting number (float or integer) 1983is converted to the type (float or integer) required by the context 1984(e.g., the operation that forced the conversion). 1985 1986 1987<p> 1988All conversions from strings to numbers 1989accept both a dot and the current locale mark 1990as the radix character. 1991(The Lua lexer, however, accepts only a dot.) 1992 1993 1994<p> 1995The conversion from numbers to strings uses a 1996non-specified human-readable format. 1997For complete control over how numbers are converted to strings, 1998use the <code>format</code> function from the string library 1999(see <a href="#pdf-string.format"><code>string.format</code></a>). 2000 2001 2002 2003 2004 2005<h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p> 2006Lua supports the following relational operators: 2007 2008<ul> 2009<li><b><code>==</code>: </b>equality</li> 2010<li><b><code>~=</code>: </b>inequality</li> 2011<li><b><code><</code>: </b>less than</li> 2012<li><b><code>></code>: </b>greater than</li> 2013<li><b><code><=</code>: </b>less or equal</li> 2014<li><b><code>>=</code>: </b>greater or equal</li> 2015</ul><p> 2016These operators always result in <b>false</b> or <b>true</b>. 2017 2018 2019<p> 2020Equality (<code>==</code>) first compares the type of its operands. 2021If the types are different, then the result is <b>false</b>. 2022Otherwise, the values of the operands are compared. 2023Strings are compared in the obvious way. 2024Numbers are equal if they denote the same mathematical value. 2025 2026 2027<p> 2028Tables, userdata, and threads 2029are compared by reference: 2030two objects are considered equal only if they are the same object. 2031Every time you create a new object 2032(a table, userdata, or thread), 2033this new object is different from any previously existing object. 2034A closure is always equal to itself. 2035Closures with any detectable difference 2036(different behavior, different definition) are always different. 2037Closures created at different times but with no detectable differences 2038may be classified as equal or not 2039(depending on internal caching details). 2040 2041 2042<p> 2043You can change the way that Lua compares tables and userdata 2044by using the "eq" metamethod (see <a href="#2.4">§2.4</a>). 2045 2046 2047<p> 2048Equality comparisons do not convert strings to numbers 2049or vice versa. 2050Thus, <code>"0"==0</code> evaluates to <b>false</b>, 2051and <code>t[0]</code> and <code>t["0"]</code> denote different 2052entries in a table. 2053 2054 2055<p> 2056The operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 2057 2058 2059<p> 2060The order operators work as follows. 2061If both arguments are numbers, 2062then they are compared according to their mathematical values 2063(regardless of their subtypes). 2064Otherwise, if both arguments are strings, 2065then their values are compared according to the current locale. 2066Otherwise, Lua tries to call the "lt" or the "le" 2067metamethod (see <a href="#2.4">§2.4</a>). 2068A comparison <code>a > b</code> is translated to <code>b < a</code> 2069and <code>a >= b</code> is translated to <code>b <= a</code>. 2070 2071 2072<p> 2073Following the IEEE 754 standard, 2074NaN is considered neither smaller than, 2075nor equal to, nor greater than any value (including itself). 2076 2077 2078 2079 2080 2081<h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p> 2082The logical operators in Lua are 2083<b>and</b>, <b>or</b>, and <b>not</b>. 2084Like the control structures (see <a href="#3.3.4">§3.3.4</a>), 2085all logical operators consider both <b>false</b> and <b>nil</b> as false 2086and anything else as true. 2087 2088 2089<p> 2090The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 2091The conjunction operator <b>and</b> returns its first argument 2092if this value is <b>false</b> or <b>nil</b>; 2093otherwise, <b>and</b> returns its second argument. 2094The disjunction operator <b>or</b> returns its first argument 2095if this value is different from <b>nil</b> and <b>false</b>; 2096otherwise, <b>or</b> returns its second argument. 2097Both <b>and</b> and <b>or</b> use short-circuit evaluation; 2098that is, 2099the second operand is evaluated only if necessary. 2100Here are some examples: 2101 2102<pre> 2103 10 or 20 --> 10 2104 10 or error() --> 10 2105 nil or "a" --> "a" 2106 nil and 10 --> nil 2107 false and error() --> false 2108 false and nil --> false 2109 false or nil --> nil 2110 10 and 20 --> 20 2111</pre><p> 2112(In this manual, 2113<code>--></code> indicates the result of the preceding expression.) 2114 2115 2116 2117 2118 2119<h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p> 2120The string concatenation operator in Lua is 2121denoted by two dots ('<code>..</code>'). 2122If both operands are strings or numbers, then they are converted to 2123strings according to the rules described in <a href="#3.4.3">§3.4.3</a>. 2124Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). 2125 2126 2127 2128 2129 2130<h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3> 2131 2132<p> 2133The length operator is denoted by the unary prefix operator <code>#</code>. 2134 2135 2136<p> 2137The length of a string is its number of bytes 2138(that is, the usual meaning of string length when each 2139character is one byte). 2140 2141 2142<p> 2143The length operator applied on a table 2144returns a border in that table. 2145A <em>border</em> in a table <code>t</code> is any natural number 2146that satisfies the following condition: 2147 2148<pre> 2149 (border == 0 or t[border] ~= nil) and t[border + 1] == nil 2150</pre><p> 2151In words, 2152a border is any (natural) index in a table 2153where a non-nil value is followed by a nil value 2154(or zero, when index 1 is nil). 2155 2156 2157<p> 2158A table with exactly one border is called a <em>sequence</em>. 2159For instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence, 2160as it has only one border (5). 2161The table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5), 2162and therefore it is not a sequence. 2163The table <code>{nil, 20, 30, nil, nil, 60, nil}</code> 2164has three borders (0, 3, and 6), 2165so it is not a sequence, too. 2166The table <code>{}</code> is a sequence with border 0. 2167Note that non-natural keys do not interfere 2168with whether a table is a sequence. 2169 2170 2171<p> 2172When <code>t</code> is a sequence, 2173<code>#t</code> returns its only border, 2174which corresponds to the intuitive notion of the length of the sequence. 2175When <code>t</code> is not a sequence, 2176<code>#t</code> can return any of its borders. 2177(The exact one depends on details of 2178the internal representation of the table, 2179which in turn can depend on how the table was populated and 2180the memory addresses of its non-numeric keys.) 2181 2182 2183<p> 2184The computation of the length of a table 2185has a guaranteed worst time of <em>O(log n)</em>, 2186where <em>n</em> is the largest natural key in the table. 2187 2188 2189<p> 2190A program can modify the behavior of the length operator for 2191any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>). 2192 2193 2194 2195 2196 2197<h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p> 2198Operator precedence in Lua follows the table below, 2199from lower to higher priority: 2200 2201<pre> 2202 or 2203 and 2204 < > <= >= ~= == 2205 | 2206 ~ 2207 & 2208 << >> 2209 .. 2210 + - 2211 * / // % 2212 unary operators (not # - ~) 2213 ^ 2214</pre><p> 2215As usual, 2216you can use parentheses to change the precedences of an expression. 2217The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 2218operators are right associative. 2219All other binary operators are left associative. 2220 2221 2222 2223 2224 2225<h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p> 2226Table constructors are expressions that create tables. 2227Every time a constructor is evaluated, a new table is created. 2228A constructor can be used to create an empty table 2229or to create a table and initialize some of its fields. 2230The general syntax for constructors is 2231 2232<pre> 2233 tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 2234 fieldlist ::= field {fieldsep field} [fieldsep] 2235 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 2236 fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 2237</pre> 2238 2239<p> 2240Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry 2241with key <code>exp1</code> and value <code>exp2</code>. 2242A field of the form <code>name = exp</code> is equivalent to 2243<code>["name"] = exp</code>. 2244Finally, fields of the form <code>exp</code> are equivalent to 2245<code>[i] = exp</code>, where <code>i</code> are consecutive integers 2246starting with 1. 2247Fields in the other formats do not affect this counting. 2248For example, 2249 2250<pre> 2251 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 2252</pre><p> 2253is equivalent to 2254 2255<pre> 2256 do 2257 local t = {} 2258 t[f(1)] = g 2259 t[1] = "x" -- 1st exp 2260 t[2] = "y" -- 2nd exp 2261 t.x = 1 -- t["x"] = 1 2262 t[3] = f(x) -- 3rd exp 2263 t[30] = 23 2264 t[4] = 45 -- 4th exp 2265 a = t 2266 end 2267</pre> 2268 2269<p> 2270The order of the assignments in a constructor is undefined. 2271(This order would be relevant only when there are repeated keys.) 2272 2273 2274<p> 2275If the last field in the list has the form <code>exp</code> 2276and the expression is a function call or a vararg expression, 2277then all values returned by this expression enter the list consecutively 2278(see <a href="#3.4.10">§3.4.10</a>). 2279 2280 2281<p> 2282The field list can have an optional trailing separator, 2283as a convenience for machine-generated code. 2284 2285 2286 2287 2288 2289<h3>3.4.10 – <a name="3.4.10">Function Calls</a></h3><p> 2290A function call in Lua has the following syntax: 2291 2292<pre> 2293 functioncall ::= prefixexp args 2294</pre><p> 2295In a function call, 2296first prefixexp and args are evaluated. 2297If the value of prefixexp has type <em>function</em>, 2298then this function is called 2299with the given arguments. 2300Otherwise, the prefixexp "call" metamethod is called, 2301having as first argument the value of prefixexp, 2302followed by the original call arguments 2303(see <a href="#2.4">§2.4</a>). 2304 2305 2306<p> 2307The form 2308 2309<pre> 2310 functioncall ::= prefixexp ‘<b>:</b>’ Name args 2311</pre><p> 2312can be used to call "methods". 2313A call <code>v:name(<em>args</em>)</code> 2314is syntactic sugar for <code>v.name(v,<em>args</em>)</code>, 2315except that <code>v</code> is evaluated only once. 2316 2317 2318<p> 2319Arguments have the following syntax: 2320 2321<pre> 2322 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ 2323 args ::= tableconstructor 2324 args ::= LiteralString 2325</pre><p> 2326All argument expressions are evaluated before the call. 2327A call of the form <code>f{<em>fields</em>}</code> is 2328syntactic sugar for <code>f({<em>fields</em>})</code>; 2329that is, the argument list is a single new table. 2330A call of the form <code>f'<em>string</em>'</code> 2331(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 2332is syntactic sugar for <code>f('<em>string</em>')</code>; 2333that is, the argument list is a single literal string. 2334 2335 2336<p> 2337A call of the form <code>return <em>functioncall</em></code> is called 2338a <em>tail call</em>. 2339Lua implements <em>proper tail calls</em> 2340(or <em>proper tail recursion</em>): 2341in a tail call, 2342the called function reuses the stack entry of the calling function. 2343Therefore, there is no limit on the number of nested tail calls that 2344a program can execute. 2345However, a tail call erases any debug information about the 2346calling function. 2347Note that a tail call only happens with a particular syntax, 2348where the <b>return</b> has one single function call as argument; 2349this syntax makes the calling function return exactly 2350the returns of the called function. 2351So, none of the following examples are tail calls: 2352 2353<pre> 2354 return (f(x)) -- results adjusted to 1 2355 return 2 * f(x) 2356 return x, f(x) -- additional results 2357 f(x); return -- results discarded 2358 return x or f(x) -- results adjusted to 1 2359</pre> 2360 2361 2362 2363 2364<h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3> 2365 2366<p> 2367The syntax for function definition is 2368 2369<pre> 2370 functiondef ::= <b>function</b> funcbody 2371 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 2372</pre> 2373 2374<p> 2375The following syntactic sugar simplifies function definitions: 2376 2377<pre> 2378 stat ::= <b>function</b> funcname funcbody 2379 stat ::= <b>local</b> <b>function</b> Name funcbody 2380 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 2381</pre><p> 2382The statement 2383 2384<pre> 2385 function f () <em>body</em> end 2386</pre><p> 2387translates to 2388 2389<pre> 2390 f = function () <em>body</em> end 2391</pre><p> 2392The statement 2393 2394<pre> 2395 function t.a.b.c.f () <em>body</em> end 2396</pre><p> 2397translates to 2398 2399<pre> 2400 t.a.b.c.f = function () <em>body</em> end 2401</pre><p> 2402The statement 2403 2404<pre> 2405 local function f () <em>body</em> end 2406</pre><p> 2407translates to 2408 2409<pre> 2410 local f; f = function () <em>body</em> end 2411</pre><p> 2412not to 2413 2414<pre> 2415 local f = function () <em>body</em> end 2416</pre><p> 2417(This only makes a difference when the body of the function 2418contains references to <code>f</code>.) 2419 2420 2421<p> 2422A function definition is an executable expression, 2423whose value has type <em>function</em>. 2424When Lua precompiles a chunk, 2425all its function bodies are precompiled too. 2426Then, whenever Lua executes the function definition, 2427the function is <em>instantiated</em> (or <em>closed</em>). 2428This function instance (or <em>closure</em>) 2429is the final value of the expression. 2430 2431 2432<p> 2433Parameters act as local variables that are 2434initialized with the argument values: 2435 2436<pre> 2437 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 2438</pre><p> 2439When a function is called, 2440the list of arguments is adjusted to 2441the length of the list of parameters, 2442unless the function is a <em>vararg function</em>, 2443which is indicated by three dots ('<code>...</code>') 2444at the end of its parameter list. 2445A vararg function does not adjust its argument list; 2446instead, it collects all extra arguments and supplies them 2447to the function through a <em>vararg expression</em>, 2448which is also written as three dots. 2449The value of this expression is a list of all actual extra arguments, 2450similar to a function with multiple results. 2451If a vararg expression is used inside another expression 2452or in the middle of a list of expressions, 2453then its return list is adjusted to one element. 2454If the expression is used as the last element of a list of expressions, 2455then no adjustment is made 2456(unless that last expression is enclosed in parentheses). 2457 2458 2459<p> 2460As an example, consider the following definitions: 2461 2462<pre> 2463 function f(a, b) end 2464 function g(a, b, ...) end 2465 function r() return 1,2,3 end 2466</pre><p> 2467Then, we have the following mapping from arguments to parameters and 2468to the vararg expression: 2469 2470<pre> 2471 CALL PARAMETERS 2472 2473 f(3) a=3, b=nil 2474 f(3, 4) a=3, b=4 2475 f(3, 4, 5) a=3, b=4 2476 f(r(), 10) a=1, b=10 2477 f(r()) a=1, b=2 2478 2479 g(3) a=3, b=nil, ... --> (nothing) 2480 g(3, 4) a=3, b=4, ... --> (nothing) 2481 g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 2482 g(5, r()) a=5, b=1, ... --> 2 3 2483</pre> 2484 2485<p> 2486Results are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>). 2487If control reaches the end of a function 2488without encountering a <b>return</b> statement, 2489then the function returns with no results. 2490 2491 2492<p> 2493 2494There is a system-dependent limit on the number of values 2495that a function may return. 2496This limit is guaranteed to be larger than 1000. 2497 2498 2499<p> 2500The <em>colon</em> syntax 2501is used for defining <em>methods</em>, 2502that is, functions that have an implicit extra parameter <code>self</code>. 2503Thus, the statement 2504 2505<pre> 2506 function t.a.b.c:f (<em>params</em>) <em>body</em> end 2507</pre><p> 2508is syntactic sugar for 2509 2510<pre> 2511 t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end 2512</pre> 2513 2514 2515 2516 2517 2518 2519<h2>3.5 – <a name="3.5">Visibility Rules</a></h2> 2520 2521<p> 2522 2523Lua is a lexically scoped language. 2524The scope of a local variable begins at the first statement after 2525its declaration and lasts until the last non-void statement 2526of the innermost block that includes the declaration. 2527Consider the following example: 2528 2529<pre> 2530 x = 10 -- global variable 2531 do -- new block 2532 local x = x -- new 'x', with value 10 2533 print(x) --> 10 2534 x = x+1 2535 do -- another block 2536 local x = x+1 -- another 'x' 2537 print(x) --> 12 2538 end 2539 print(x) --> 11 2540 end 2541 print(x) --> 10 (the global one) 2542</pre> 2543 2544<p> 2545Notice that, in a declaration like <code>local x = x</code>, 2546the new <code>x</code> being declared is not in scope yet, 2547and so the second <code>x</code> refers to the outside variable. 2548 2549 2550<p> 2551Because of the lexical scoping rules, 2552local variables can be freely accessed by functions 2553defined inside their scope. 2554A local variable used by an inner function is called 2555an <em>upvalue</em>, or <em>external local variable</em>, 2556inside the inner function. 2557 2558 2559<p> 2560Notice that each execution of a <b>local</b> statement 2561defines new local variables. 2562Consider the following example: 2563 2564<pre> 2565 a = {} 2566 local x = 20 2567 for i=1,10 do 2568 local y = 0 2569 a[i] = function () y=y+1; return x+y end 2570 end 2571</pre><p> 2572The loop creates ten closures 2573(that is, ten instances of the anonymous function). 2574Each of these closures uses a different <code>y</code> variable, 2575while all of them share the same <code>x</code>. 2576 2577 2578 2579 2580 2581<h1>4 – <a name="4">The Application Program Interface</a></h1> 2582 2583<p> 2584 2585This section describes the C API for Lua, that is, 2586the set of C functions available to the host program to communicate 2587with Lua. 2588All API functions and related types and constants 2589are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. 2590 2591 2592<p> 2593Even when we use the term "function", 2594any facility in the API may be provided as a macro instead. 2595Except where stated otherwise, 2596all such macros use each of their arguments exactly once 2597(except for the first argument, which is always a Lua state), 2598and so do not generate any hidden side-effects. 2599 2600 2601<p> 2602As in most C libraries, 2603the Lua API functions do not check their arguments for validity or consistency. 2604However, you can change this behavior by compiling Lua 2605with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined. 2606 2607 2608<p> 2609The Lua library is fully reentrant: 2610it has no global variables. 2611It keeps all information it needs in a dynamic structure, 2612called the <em>Lua state</em>. 2613 2614 2615<p> 2616Each Lua state has one or more threads, 2617which correspond to independent, cooperative lines of execution. 2618The type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread. 2619(Indirectly, through the thread, it also refers to the 2620Lua state associated to the thread.) 2621 2622 2623<p> 2624A pointer to a thread must be passed as the first argument to 2625every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 2626which creates a Lua state from scratch and returns a pointer 2627to the <em>main thread</em> in the new state. 2628 2629 2630 2631<h2>4.1 – <a name="4.1">The Stack</a></h2> 2632 2633<p> 2634Lua uses a <em>virtual stack</em> to pass values to and from C. 2635Each element in this stack represents a Lua value 2636(<b>nil</b>, number, string, etc.). 2637Functions in the API can access this stack through the 2638Lua state parameter that they receive. 2639 2640 2641<p> 2642Whenever Lua calls C, the called function gets a new stack, 2643which is independent of previous stacks and of stacks of 2644C functions that are still active. 2645This stack initially contains any arguments to the C function 2646and it is where the C function can store temporary 2647Lua values and must push its results 2648to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 2649 2650 2651<p> 2652For convenience, 2653most query operations in the API do not follow a strict stack discipline. 2654Instead, they can refer to any element in the stack 2655by using an <em>index</em>: 2656A positive index represents an absolute stack position 2657(starting at 1); 2658a negative index represents an offset relative to the top of the stack. 2659More specifically, if the stack has <em>n</em> elements, 2660then index 1 represents the first element 2661(that is, the element that was pushed onto the stack first) 2662and 2663index <em>n</em> represents the last element; 2664index -1 also represents the last element 2665(that is, the element at the top) 2666and index <em>-n</em> represents the first element. 2667 2668 2669 2670 2671 2672<h2>4.2 – <a name="4.2">Stack Size</a></h2> 2673 2674<p> 2675When you interact with the Lua API, 2676you are responsible for ensuring consistency. 2677In particular, 2678<em>you are responsible for controlling stack overflow</em>. 2679You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> 2680to ensure that the stack has enough space for pushing new elements. 2681 2682 2683<p> 2684Whenever Lua calls C, 2685it ensures that the stack has space for 2686at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots. 2687<code>LUA_MINSTACK</code> is defined as 20, 2688so that usually you do not have to worry about stack space 2689unless your code has loops pushing elements onto the stack. 2690 2691 2692<p> 2693When you call a Lua function 2694without a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>), 2695Lua ensures that the stack has enough space for all results, 2696but it does not ensure any extra space. 2697So, before pushing anything in the stack after such a call 2698you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>. 2699 2700 2701 2702 2703 2704<h2>4.3 – <a name="4.3">Valid and Acceptable Indices</a></h2> 2705 2706<p> 2707Any function in the API that receives stack indices 2708works only with <em>valid indices</em> or <em>acceptable indices</em>. 2709 2710 2711<p> 2712A <em>valid index</em> is an index that refers to a 2713position that stores a modifiable Lua value. 2714It comprises stack indices between 1 and the stack top 2715(<code>1 ≤ abs(index) ≤ top</code>) 2716 2717plus <em>pseudo-indices</em>, 2718which represent some positions that are accessible to C code 2719but that are not in the stack. 2720Pseudo-indices are used to access the registry (see <a href="#4.5">§4.5</a>) 2721and the upvalues of a C function (see <a href="#4.4">§4.4</a>). 2722 2723 2724<p> 2725Functions that do not need a specific mutable position, 2726but only a value (e.g., query functions), 2727can be called with acceptable indices. 2728An <em>acceptable index</em> can be any valid index, 2729but it also can be any positive index after the stack top 2730within the space allocated for the stack, 2731that is, indices up to the stack size. 2732(Note that 0 is never an acceptable index.) 2733Except when noted otherwise, 2734functions in the API work with acceptable indices. 2735 2736 2737<p> 2738Acceptable indices serve to avoid extra tests 2739against the stack top when querying the stack. 2740For instance, a C function can query its third argument 2741without the need to first check whether there is a third argument, 2742that is, without the need to check whether 3 is a valid index. 2743 2744 2745<p> 2746For functions that can be called with acceptable indices, 2747any non-valid index is treated as if it 2748contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>, 2749which behaves like a nil value. 2750 2751 2752 2753 2754 2755<h2>4.4 – <a name="4.4">C Closures</a></h2> 2756 2757<p> 2758When a C function is created, 2759it is possible to associate some values with it, 2760thus creating a <em>C closure</em> 2761(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>); 2762these values are called <em>upvalues</em> and are 2763accessible to the function whenever it is called. 2764 2765 2766<p> 2767Whenever a C function is called, 2768its upvalues are located at specific pseudo-indices. 2769These pseudo-indices are produced by the macro 2770<a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>. 2771The first upvalue associated with a function is at index 2772<code>lua_upvalueindex(1)</code>, and so on. 2773Any access to <code>lua_upvalueindex(<em>n</em>)</code>, 2774where <em>n</em> is greater than the number of upvalues of the 2775current function 2776(but not greater than 256, 2777which is one plus the maximum number of upvalues in a closure), 2778produces an acceptable but invalid index. 2779 2780 2781 2782 2783 2784<h2>4.5 – <a name="4.5">Registry</a></h2> 2785 2786<p> 2787Lua provides a <em>registry</em>, 2788a predefined table that can be used by any C code to 2789store whatever Lua values it needs to store. 2790The registry table is always located at pseudo-index 2791<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. 2792Any C library can store data into this table, 2793but it must take care to choose keys 2794that are different from those used 2795by other libraries, to avoid collisions. 2796Typically, you should use as key a string containing your library name, 2797or a light userdata with the address of a C object in your code, 2798or any Lua object created by your code. 2799As with variable names, 2800string keys starting with an underscore followed by 2801uppercase letters are reserved for Lua. 2802 2803 2804<p> 2805The integer keys in the registry are used 2806by the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>) 2807and by some predefined values. 2808Therefore, integer keys must not be used for other purposes. 2809 2810 2811<p> 2812When you create a new Lua state, 2813its registry comes with some predefined values. 2814These predefined values are indexed with integer keys 2815defined as constants in <code>lua.h</code>. 2816The following constants are defined: 2817 2818<ul> 2819<li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has 2820the main thread of the state. 2821(The main thread is the one created together with the state.) 2822</li> 2823 2824<li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has 2825the global environment. 2826</li> 2827</ul> 2828 2829 2830 2831 2832<h2>4.6 – <a name="4.6">Error Handling in C</a></h2> 2833 2834<p> 2835Internally, Lua uses the C <code>longjmp</code> facility to handle errors. 2836(Lua will use exceptions if you compile it as C++; 2837search for <code>LUAI_THROW</code> in the source code for details.) 2838When Lua faces any error 2839(such as a memory allocation error or a type error) 2840it <em>raises</em> an error; 2841that is, it does a long jump. 2842A <em>protected environment</em> uses <code>setjmp</code> 2843to set a recovery point; 2844any error jumps to the most recent active recovery point. 2845 2846 2847<p> 2848Inside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>. 2849 2850 2851<p> 2852Most functions in the API can raise an error, 2853for instance due to a memory allocation error. 2854The documentation for each function indicates whether 2855it can raise errors. 2856 2857 2858<p> 2859If an error happens outside any protected environment, 2860Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) 2861and then calls <code>abort</code>, 2862thus exiting the host application. 2863Your panic function can avoid this exit by 2864never returning 2865(e.g., doing a long jump to your own recovery point outside Lua). 2866 2867 2868<p> 2869The panic function, 2870as its name implies, 2871is a mechanism of last resort. 2872Programs should avoid it. 2873As a general rule, 2874when a C function is called by Lua with a Lua state, 2875it can do whatever it wants on that Lua state, 2876as it should be already protected. 2877However, 2878when C code operates on other Lua states 2879(e.g., a Lua argument to the function, 2880a Lua state stored in the registry, or 2881the result of <a href="#lua_newthread"><code>lua_newthread</code></a>), 2882it should use them only in API calls that cannot raise errors. 2883 2884 2885<p> 2886The panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>); 2887in particular, the error object is at the top of the stack. 2888However, there is no guarantee about stack space. 2889To push anything on the stack, 2890the panic function must first check the available space (see <a href="#4.2">§4.2</a>). 2891 2892 2893 2894 2895 2896<h2>4.7 – <a name="4.7">Handling Yields in C</a></h2> 2897 2898<p> 2899Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine. 2900Therefore, if a C function <code>foo</code> calls an API function 2901and this API function yields 2902(directly or indirectly by calling another function that yields), 2903Lua cannot return to <code>foo</code> any more, 2904because the <code>longjmp</code> removes its frame from the C stack. 2905 2906 2907<p> 2908To avoid this kind of problem, 2909Lua raises an error whenever it tries to yield across an API call, 2910except for three functions: 2911<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>. 2912All those functions receive a <em>continuation function</em> 2913(as a parameter named <code>k</code>) to continue execution after a yield. 2914 2915 2916<p> 2917We need to set some terminology to explain continuations. 2918We have a C function called from Lua which we will call 2919the <em>original function</em>. 2920This original function then calls one of those three functions in the C API, 2921which we will call the <em>callee function</em>, 2922that then yields the current thread. 2923(This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 2924or 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> 2925and the function called by them yields.) 2926 2927 2928<p> 2929Suppose the running thread yields while executing the callee function. 2930After the thread resumes, 2931it eventually will finish running the callee function. 2932However, 2933the callee function cannot return to the original function, 2934because its frame in the C stack was destroyed by the yield. 2935Instead, Lua calls a <em>continuation function</em>, 2936which was given as an argument to the callee function. 2937As the name implies, 2938the continuation function should continue the task 2939of the original function. 2940 2941 2942<p> 2943As an illustration, consider the following function: 2944 2945<pre> 2946 int original_function (lua_State *L) { 2947 ... /* code 1 */ 2948 status = lua_pcall(L, n, m, h); /* calls Lua */ 2949 ... /* code 2 */ 2950 } 2951</pre><p> 2952Now we want to allow 2953the Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield. 2954First, we can rewrite our function like here: 2955 2956<pre> 2957 int k (lua_State *L, int status, lua_KContext ctx) { 2958 ... /* code 2 */ 2959 } 2960 2961 int original_function (lua_State *L) { 2962 ... /* code 1 */ 2963 return k(L, lua_pcall(L, n, m, h), ctx); 2964 } 2965</pre><p> 2966In the above code, 2967the new function <code>k</code> is a 2968<em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>), 2969which should do all the work that the original function 2970was doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>. 2971Now, we must inform Lua that it must call <code>k</code> if the Lua code 2972being executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way 2973(errors or yielding), 2974so we rewrite the code as here, 2975replacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>: 2976 2977<pre> 2978 int original_function (lua_State *L) { 2979 ... /* code 1 */ 2980 return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1); 2981 } 2982</pre><p> 2983Note the external, explicit call to the continuation: 2984Lua will call the continuation only if needed, that is, 2985in case of errors or resuming after a yield. 2986If the called function returns normally without ever yielding, 2987<a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally. 2988(Of course, instead of calling the continuation in that case, 2989you can do the equivalent work directly inside the original function.) 2990 2991 2992<p> 2993Besides the Lua state, 2994the continuation function has two other parameters: 2995the final status of the call plus the context value (<code>ctx</code>) that 2996was passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>. 2997(Lua does not use this context value; 2998it only passes this value from the original function to the 2999continuation function.) 3000For <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 3001the status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 3002except that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield 3003(instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>). 3004For <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>, 3005the status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation. 3006(For these two functions, 3007Lua will not call the continuation in case of errors, 3008because they do not handle errors.) 3009Similarly, when using <a href="#lua_callk"><code>lua_callk</code></a>, 3010you should call the continuation function 3011with <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status. 3012(For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling 3013directly the continuation function, 3014because <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.) 3015 3016 3017<p> 3018Lua treats the continuation function as if it were the original function. 3019The continuation function receives the same Lua stack 3020from the original function, 3021in the same state it would be if the callee function had returned. 3022(For instance, 3023after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are 3024removed from the stack and replaced by the results from the call.) 3025It also has the same upvalues. 3026Whatever it returns is handled by Lua as if it were the return 3027of the original function. 3028 3029 3030 3031 3032 3033<h2>4.8 – <a name="4.8">Functions and Types</a></h2> 3034 3035<p> 3036Here we list all functions and types from the C API in 3037alphabetical order. 3038Each function has an indicator like this: 3039<span class="apii">[-o, +p, <em>x</em>]</span> 3040 3041 3042<p> 3043The first field, <code>o</code>, 3044is how many elements the function pops from the stack. 3045The second field, <code>p</code>, 3046is how many elements the function pushes onto the stack. 3047(Any function always pushes its results after popping its arguments.) 3048A field in the form <code>x|y</code> means the function can push (or pop) 3049<code>x</code> or <code>y</code> elements, 3050depending on the situation; 3051an interrogation mark '<code>?</code>' means that 3052we cannot know how many elements the function pops/pushes 3053by looking only at its arguments 3054(e.g., they may depend on what is on the stack). 3055The third field, <code>x</code>, 3056tells whether the function may raise errors: 3057'<code>-</code>' means the function never raises any error; 3058'<code>m</code>' means the function may raise out-of-memory errors 3059and errors running a <code>__gc</code> metamethod; 3060'<code>e</code>' means the function may raise any errors 3061(it can run arbitrary Lua code, 3062either directly or through metamethods); 3063'<code>v</code>' means the function may raise an error on purpose. 3064 3065 3066 3067<hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p> 3068<span class="apii">[-0, +0, –]</span> 3069<pre>int lua_absindex (lua_State *L, int idx);</pre> 3070 3071<p> 3072Converts the acceptable index <code>idx</code> 3073into an equivalent absolute index 3074(that is, one that does not depend on the stack top). 3075 3076 3077 3078 3079 3080<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> 3081<pre>typedef void * (*lua_Alloc) (void *ud, 3082 void *ptr, 3083 size_t osize, 3084 size_t nsize);</pre> 3085 3086<p> 3087The type of the memory-allocation function used by Lua states. 3088The allocator function must provide a 3089functionality similar to <code>realloc</code>, 3090but not exactly the same. 3091Its arguments are 3092<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; 3093<code>ptr</code>, a pointer to the block being allocated/reallocated/freed; 3094<code>osize</code>, the original size of the block or some code about what 3095is being allocated; 3096and <code>nsize</code>, the new size of the block. 3097 3098 3099<p> 3100When <code>ptr</code> is not <code>NULL</code>, 3101<code>osize</code> is the size of the block pointed by <code>ptr</code>, 3102that is, the size given when it was allocated or reallocated. 3103 3104 3105<p> 3106When <code>ptr</code> is <code>NULL</code>, 3107<code>osize</code> encodes the kind of object that Lua is allocating. 3108<code>osize</code> is any of 3109<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>, 3110<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) 3111Lua is creating a new object of that type. 3112When <code>osize</code> is some other value, 3113Lua is allocating memory for something else. 3114 3115 3116<p> 3117Lua assumes the following behavior from the allocator function: 3118 3119 3120<p> 3121When <code>nsize</code> is zero, 3122the allocator must behave like <code>free</code> 3123and return <code>NULL</code>. 3124 3125 3126<p> 3127When <code>nsize</code> is not zero, 3128the allocator must behave like <code>realloc</code>. 3129The allocator returns <code>NULL</code> 3130if and only if it cannot fulfill the request. 3131Lua assumes that the allocator never fails when 3132<code>osize >= nsize</code>. 3133 3134 3135<p> 3136Here is a simple implementation for the allocator function. 3137It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. 3138 3139<pre> 3140 static void *l_alloc (void *ud, void *ptr, size_t osize, 3141 size_t nsize) { 3142 (void)ud; (void)osize; /* not used */ 3143 if (nsize == 0) { 3144 free(ptr); 3145 return NULL; 3146 } 3147 else 3148 return realloc(ptr, nsize); 3149 } 3150</pre><p> 3151Note that Standard C ensures 3152that <code>free(NULL)</code> has no effect and that 3153<code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>. 3154This code assumes that <code>realloc</code> does not fail when shrinking a block. 3155(Although Standard C does not ensure this behavior, 3156it seems to be a safe assumption.) 3157 3158 3159 3160 3161 3162<hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p> 3163<span class="apii">[-(2|1), +1, <em>e</em>]</span> 3164<pre>void lua_arith (lua_State *L, int op);</pre> 3165 3166<p> 3167Performs an arithmetic or bitwise operation over the two values 3168(or one, in the case of negations) 3169at the top of the stack, 3170with the value at the top being the second operand, 3171pops these values, and pushes the result of the operation. 3172The function follows the semantics of the corresponding Lua operator 3173(that is, it may call metamethods). 3174 3175 3176<p> 3177The value of <code>op</code> must be one of the following constants: 3178 3179<ul> 3180 3181<li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li> 3182<li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li> 3183<li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li> 3184<li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li> 3185<li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li> 3186<li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li> 3187<li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li> 3188<li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li> 3189<li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li> 3190<li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&</code>)</li> 3191<li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li> 3192<li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li> 3193<li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li> 3194<li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li> 3195 3196</ul> 3197 3198 3199 3200 3201<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> 3202<span class="apii">[-0, +0, –]</span> 3203<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> 3204 3205<p> 3206Sets a new panic function and returns the old one (see <a href="#4.6">§4.6</a>). 3207 3208 3209 3210 3211 3212<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> 3213<span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span> 3214<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> 3215 3216<p> 3217Calls a function. 3218 3219 3220<p> 3221To call a function you must use the following protocol: 3222first, the function to be called is pushed onto the stack; 3223then, the arguments to the function are pushed 3224in direct order; 3225that is, the first argument is pushed first. 3226Finally you call <a href="#lua_call"><code>lua_call</code></a>; 3227<code>nargs</code> is the number of arguments that you pushed onto the stack. 3228All arguments and the function value are popped from the stack 3229when the function is called. 3230The function results are pushed onto the stack when the function returns. 3231The number of results is adjusted to <code>nresults</code>, 3232unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. 3233In this case, all results from the function are pushed; 3234Lua takes care that the returned values fit into the stack space, 3235but it does not ensure any extra space in the stack. 3236The function results are pushed onto the stack in direct order 3237(the first result is pushed first), 3238so that after the call the last result is on the top of the stack. 3239 3240 3241<p> 3242Any error inside the called function is propagated upwards 3243(with a <code>longjmp</code>). 3244 3245 3246<p> 3247The following example shows how the host program can do the 3248equivalent to this Lua code: 3249 3250<pre> 3251 a = f("how", t.x, 14) 3252</pre><p> 3253Here it is in C: 3254 3255<pre> 3256 lua_getglobal(L, "f"); /* function to be called */ 3257 lua_pushliteral(L, "how"); /* 1st argument */ 3258 lua_getglobal(L, "t"); /* table to be indexed */ 3259 lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 3260 lua_remove(L, -2); /* remove 't' from the stack */ 3261 lua_pushinteger(L, 14); /* 3rd argument */ 3262 lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ 3263 lua_setglobal(L, "a"); /* set global 'a' */ 3264</pre><p> 3265Note that the code above is <em>balanced</em>: 3266at its end, the stack is back to its original configuration. 3267This is considered good programming practice. 3268 3269 3270 3271 3272 3273<hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p> 3274<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> 3275<pre>void lua_callk (lua_State *L, 3276 int nargs, 3277 int nresults, 3278 lua_KContext ctx, 3279 lua_KFunction k);</pre> 3280 3281<p> 3282This function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>, 3283but allows the called function to yield (see <a href="#4.7">§4.7</a>). 3284 3285 3286 3287 3288 3289<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> 3290<pre>typedef int (*lua_CFunction) (lua_State *L);</pre> 3291 3292<p> 3293Type for C functions. 3294 3295 3296<p> 3297In order to communicate properly with Lua, 3298a C function must use the following protocol, 3299which defines the way parameters and results are passed: 3300a C function receives its arguments from Lua in its stack 3301in direct order (the first argument is pushed first). 3302So, when the function starts, 3303<code>lua_gettop(L)</code> returns the number of arguments received by the function. 3304The first argument (if any) is at index 1 3305and its last argument is at index <code>lua_gettop(L)</code>. 3306To return values to Lua, a C function just pushes them onto the stack, 3307in direct order (the first result is pushed first), 3308and returns the number of results. 3309Any other value in the stack below the results will be properly 3310discarded by Lua. 3311Like a Lua function, a C function called by Lua can also return 3312many results. 3313 3314 3315<p> 3316As an example, the following function receives a variable number 3317of numeric arguments and returns their average and their sum: 3318 3319<pre> 3320 static int foo (lua_State *L) { 3321 int n = lua_gettop(L); /* number of arguments */ 3322 lua_Number sum = 0.0; 3323 int i; 3324 for (i = 1; i <= n; i++) { 3325 if (!lua_isnumber(L, i)) { 3326 lua_pushliteral(L, "incorrect argument"); 3327 lua_error(L); 3328 } 3329 sum += lua_tonumber(L, i); 3330 } 3331 lua_pushnumber(L, sum/n); /* first result */ 3332 lua_pushnumber(L, sum); /* second result */ 3333 return 2; /* number of results */ 3334 } 3335</pre> 3336 3337 3338 3339 3340<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> 3341<span class="apii">[-0, +0, –]</span> 3342<pre>int lua_checkstack (lua_State *L, int n);</pre> 3343 3344<p> 3345Ensures that the stack has space for at least <code>n</code> extra slots 3346(that is, that you can safely push up to <code>n</code> values into it). 3347It returns false if it cannot fulfill the request, 3348either because it would cause the stack 3349to be larger than a fixed maximum size 3350(typically at least several thousand elements) or 3351because it cannot allocate memory for the extra space. 3352This function never shrinks the stack; 3353if the stack already has space for the extra slots, 3354it is left unchanged. 3355 3356 3357 3358 3359 3360<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> 3361<span class="apii">[-0, +0, –]</span> 3362<pre>void lua_close (lua_State *L);</pre> 3363 3364<p> 3365Destroys all objects in the given Lua state 3366(calling the corresponding garbage-collection metamethods, if any) 3367and frees all dynamic memory used by this state. 3368In several platforms, you may not need to call this function, 3369because all resources are naturally released when the host program ends. 3370On the other hand, long-running programs that create multiple states, 3371such as daemons or web servers, 3372will probably need to close states as soon as they are not needed. 3373 3374 3375 3376 3377 3378<hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p> 3379<span class="apii">[-0, +0, <em>e</em>]</span> 3380<pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre> 3381 3382<p> 3383Compares two Lua values. 3384Returns 1 if the value at index <code>index1</code> satisfies <code>op</code> 3385when compared with the value at index <code>index2</code>, 3386following the semantics of the corresponding Lua operator 3387(that is, it may call metamethods). 3388Otherwise returns 0. 3389Also returns 0 if any of the indices is not valid. 3390 3391 3392<p> 3393The value of <code>op</code> must be one of the following constants: 3394 3395<ul> 3396 3397<li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li> 3398<li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li> 3399<li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li> 3400 3401</ul> 3402 3403 3404 3405 3406<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> 3407<span class="apii">[-n, +1, <em>e</em>]</span> 3408<pre>void lua_concat (lua_State *L, int n);</pre> 3409 3410<p> 3411Concatenates the <code>n</code> values at the top of the stack, 3412pops them, and leaves the result at the top. 3413If <code>n</code> is 1, the result is the single value on the stack 3414(that is, the function does nothing); 3415if <code>n</code> is 0, the result is the empty string. 3416Concatenation is performed following the usual semantics of Lua 3417(see <a href="#3.4.6">§3.4.6</a>). 3418 3419 3420 3421 3422 3423<hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p> 3424<span class="apii">[-0, +0, –]</span> 3425<pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre> 3426 3427<p> 3428Copies the element at index <code>fromidx</code> 3429into the valid index <code>toidx</code>, 3430replacing the value at that position. 3431Values at other positions are not affected. 3432 3433 3434 3435 3436 3437<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> 3438<span class="apii">[-0, +1, <em>m</em>]</span> 3439<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> 3440 3441<p> 3442Creates a new empty table and pushes it onto the stack. 3443Parameter <code>narr</code> is a hint for how many elements the table 3444will have as a sequence; 3445parameter <code>nrec</code> is a hint for how many other elements 3446the table will have. 3447Lua may use these hints to preallocate memory for the new table. 3448This preallocation is useful for performance when you know in advance 3449how many elements the table will have. 3450Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. 3451 3452 3453 3454 3455 3456<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> 3457<span class="apii">[-0, +0, –]</span> 3458<pre>int lua_dump (lua_State *L, 3459 lua_Writer writer, 3460 void *data, 3461 int strip);</pre> 3462 3463<p> 3464Dumps a function as a binary chunk. 3465Receives a Lua function on the top of the stack 3466and produces a binary chunk that, 3467if loaded again, 3468results in a function equivalent to the one dumped. 3469As it produces parts of the chunk, 3470<a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>) 3471with the given <code>data</code> 3472to write them. 3473 3474 3475<p> 3476If <code>strip</code> is true, 3477the binary representation may not include all debug information 3478about the function, 3479to save space. 3480 3481 3482<p> 3483The value returned is the error code returned by the last 3484call to the writer; 34850 means no errors. 3486 3487 3488<p> 3489This function does not pop the Lua function from the stack. 3490 3491 3492 3493 3494 3495<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> 3496<span class="apii">[-1, +0, <em>v</em>]</span> 3497<pre>int lua_error (lua_State *L);</pre> 3498 3499<p> 3500Generates a Lua error, 3501using the value at the top of the stack as the error object. 3502This function does a long jump, 3503and therefore never returns 3504(see <a href="#luaL_error"><code>luaL_error</code></a>). 3505 3506 3507 3508 3509 3510<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> 3511<span class="apii">[-0, +0, <em>m</em>]</span> 3512<pre>int lua_gc (lua_State *L, int what, int data);</pre> 3513 3514<p> 3515Controls the garbage collector. 3516 3517 3518<p> 3519This function performs several tasks, 3520according to the value of the parameter <code>what</code>: 3521 3522<ul> 3523 3524<li><b><code>LUA_GCSTOP</code>: </b> 3525stops the garbage collector. 3526</li> 3527 3528<li><b><code>LUA_GCRESTART</code>: </b> 3529restarts the garbage collector. 3530</li> 3531 3532<li><b><code>LUA_GCCOLLECT</code>: </b> 3533performs a full garbage-collection cycle. 3534</li> 3535 3536<li><b><code>LUA_GCCOUNT</code>: </b> 3537returns the current amount of memory (in Kbytes) in use by Lua. 3538</li> 3539 3540<li><b><code>LUA_GCCOUNTB</code>: </b> 3541returns the remainder of dividing the current amount of bytes of 3542memory in use by Lua by 1024. 3543</li> 3544 3545<li><b><code>LUA_GCSTEP</code>: </b> 3546performs an incremental step of garbage collection. 3547</li> 3548 3549<li><b><code>LUA_GCSETPAUSE</code>: </b> 3550sets <code>data</code> as the new value 3551for the <em>pause</em> of the collector (see <a href="#2.5">§2.5</a>) 3552and returns the previous value of the pause. 3553</li> 3554 3555<li><b><code>LUA_GCSETSTEPMUL</code>: </b> 3556sets <code>data</code> as the new value for the <em>step multiplier</em> of 3557the collector (see <a href="#2.5">§2.5</a>) 3558and returns the previous value of the step multiplier. 3559</li> 3560 3561<li><b><code>LUA_GCISRUNNING</code>: </b> 3562returns a boolean that tells whether the collector is running 3563(i.e., not stopped). 3564</li> 3565 3566</ul> 3567 3568<p> 3569For more details about these options, 3570see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>. 3571 3572 3573 3574 3575 3576<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> 3577<span class="apii">[-0, +0, –]</span> 3578<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> 3579 3580<p> 3581Returns the memory-allocation function of a given state. 3582If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the 3583opaque pointer given when the memory-allocator function was set. 3584 3585 3586 3587 3588 3589<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> 3590<span class="apii">[-0, +1, <em>e</em>]</span> 3591<pre>int lua_getfield (lua_State *L, int index, const char *k);</pre> 3592 3593<p> 3594Pushes onto the stack the value <code>t[k]</code>, 3595where <code>t</code> is the value at the given index. 3596As in Lua, this function may trigger a metamethod 3597for the "index" event (see <a href="#2.4">§2.4</a>). 3598 3599 3600<p> 3601Returns the type of the pushed value. 3602 3603 3604 3605 3606 3607<hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p> 3608<span class="apii">[-0, +0, –]</span> 3609<pre>void *lua_getextraspace (lua_State *L);</pre> 3610 3611<p> 3612Returns a pointer to a raw memory area associated with the 3613given Lua state. 3614The application can use this area for any purpose; 3615Lua does not use it for anything. 3616 3617 3618<p> 3619Each new thread has this area initialized with a copy 3620of the area of the main thread. 3621 3622 3623<p> 3624By default, this area has the size of a pointer to void, 3625but you can recompile Lua with a different size for this area. 3626(See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.) 3627 3628 3629 3630 3631 3632<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> 3633<span class="apii">[-0, +1, <em>e</em>]</span> 3634<pre>int lua_getglobal (lua_State *L, const char *name);</pre> 3635 3636<p> 3637Pushes onto the stack the value of the global <code>name</code>. 3638Returns the type of that value. 3639 3640 3641 3642 3643 3644<hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p> 3645<span class="apii">[-0, +1, <em>e</em>]</span> 3646<pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre> 3647 3648<p> 3649Pushes onto the stack the value <code>t[i]</code>, 3650where <code>t</code> is the value at the given index. 3651As in Lua, this function may trigger a metamethod 3652for the "index" event (see <a href="#2.4">§2.4</a>). 3653 3654 3655<p> 3656Returns the type of the pushed value. 3657 3658 3659 3660 3661 3662<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> 3663<span class="apii">[-0, +(0|1), –]</span> 3664<pre>int lua_getmetatable (lua_State *L, int index);</pre> 3665 3666<p> 3667If the value at the given index has a metatable, 3668the function pushes that metatable onto the stack and returns 1. 3669Otherwise, 3670the function returns 0 and pushes nothing on the stack. 3671 3672 3673 3674 3675 3676<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> 3677<span class="apii">[-1, +1, <em>e</em>]</span> 3678<pre>int lua_gettable (lua_State *L, int index);</pre> 3679 3680<p> 3681Pushes onto the stack the value <code>t[k]</code>, 3682where <code>t</code> is the value at the given index 3683and <code>k</code> is the value at the top of the stack. 3684 3685 3686<p> 3687This function pops the key from the stack, 3688pushing the resulting value in its place. 3689As in Lua, this function may trigger a metamethod 3690for the "index" event (see <a href="#2.4">§2.4</a>). 3691 3692 3693<p> 3694Returns the type of the pushed value. 3695 3696 3697 3698 3699 3700<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> 3701<span class="apii">[-0, +0, –]</span> 3702<pre>int lua_gettop (lua_State *L);</pre> 3703 3704<p> 3705Returns the index of the top element in the stack. 3706Because indices start at 1, 3707this result is equal to the number of elements in the stack; 3708in particular, 0 means an empty stack. 3709 3710 3711 3712 3713 3714<hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p> 3715<span class="apii">[-0, +1, –]</span> 3716<pre>int lua_getuservalue (lua_State *L, int index);</pre> 3717 3718<p> 3719Pushes onto the stack the Lua value associated with the full userdata 3720at the given index. 3721 3722 3723<p> 3724Returns the type of the pushed value. 3725 3726 3727 3728 3729 3730<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> 3731<span class="apii">[-1, +1, –]</span> 3732<pre>void lua_insert (lua_State *L, int index);</pre> 3733 3734<p> 3735Moves the top element into the given valid index, 3736shifting up the elements above this index to open space. 3737This function cannot be called with a pseudo-index, 3738because a pseudo-index is not an actual stack position. 3739 3740 3741 3742 3743 3744<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> 3745<pre>typedef ... lua_Integer;</pre> 3746 3747<p> 3748The type of integers in Lua. 3749 3750 3751<p> 3752By default this type is <code>long long</code>, 3753(usually a 64-bit two-complement integer), 3754but that can be changed to <code>long</code> or <code>int</code> 3755(usually a 32-bit two-complement integer). 3756(See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.) 3757 3758 3759<p> 3760Lua also defines the constants 3761<a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>, 3762with the minimum and the maximum values that fit in this type. 3763 3764 3765 3766 3767 3768<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> 3769<span class="apii">[-0, +0, –]</span> 3770<pre>int lua_isboolean (lua_State *L, int index);</pre> 3771 3772<p> 3773Returns 1 if the value at the given index is a boolean, 3774and 0 otherwise. 3775 3776 3777 3778 3779 3780<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> 3781<span class="apii">[-0, +0, –]</span> 3782<pre>int lua_iscfunction (lua_State *L, int index);</pre> 3783 3784<p> 3785Returns 1 if the value at the given index is a C function, 3786and 0 otherwise. 3787 3788 3789 3790 3791 3792<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> 3793<span class="apii">[-0, +0, –]</span> 3794<pre>int lua_isfunction (lua_State *L, int index);</pre> 3795 3796<p> 3797Returns 1 if the value at the given index is a function 3798(either C or Lua), and 0 otherwise. 3799 3800 3801 3802 3803 3804<hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p> 3805<span class="apii">[-0, +0, –]</span> 3806<pre>int lua_isinteger (lua_State *L, int index);</pre> 3807 3808<p> 3809Returns 1 if the value at the given index is an integer 3810(that is, the value is a number and is represented as an integer), 3811and 0 otherwise. 3812 3813 3814 3815 3816 3817<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> 3818<span class="apii">[-0, +0, –]</span> 3819<pre>int lua_islightuserdata (lua_State *L, int index);</pre> 3820 3821<p> 3822Returns 1 if the value at the given index is a light userdata, 3823and 0 otherwise. 3824 3825 3826 3827 3828 3829<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> 3830<span class="apii">[-0, +0, –]</span> 3831<pre>int lua_isnil (lua_State *L, int index);</pre> 3832 3833<p> 3834Returns 1 if the value at the given index is <b>nil</b>, 3835and 0 otherwise. 3836 3837 3838 3839 3840 3841<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> 3842<span class="apii">[-0, +0, –]</span> 3843<pre>int lua_isnone (lua_State *L, int index);</pre> 3844 3845<p> 3846Returns 1 if the given index is not valid, 3847and 0 otherwise. 3848 3849 3850 3851 3852 3853<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> 3854<span class="apii">[-0, +0, –]</span> 3855<pre>int lua_isnoneornil (lua_State *L, int index);</pre> 3856 3857<p> 3858Returns 1 if the given index is not valid 3859or if the value at this index is <b>nil</b>, 3860and 0 otherwise. 3861 3862 3863 3864 3865 3866<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> 3867<span class="apii">[-0, +0, –]</span> 3868<pre>int lua_isnumber (lua_State *L, int index);</pre> 3869 3870<p> 3871Returns 1 if the value at the given index is a number 3872or a string convertible to a number, 3873and 0 otherwise. 3874 3875 3876 3877 3878 3879<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> 3880<span class="apii">[-0, +0, –]</span> 3881<pre>int lua_isstring (lua_State *L, int index);</pre> 3882 3883<p> 3884Returns 1 if the value at the given index is a string 3885or a number (which is always convertible to a string), 3886and 0 otherwise. 3887 3888 3889 3890 3891 3892<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> 3893<span class="apii">[-0, +0, –]</span> 3894<pre>int lua_istable (lua_State *L, int index);</pre> 3895 3896<p> 3897Returns 1 if the value at the given index is a table, 3898and 0 otherwise. 3899 3900 3901 3902 3903 3904<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> 3905<span class="apii">[-0, +0, –]</span> 3906<pre>int lua_isthread (lua_State *L, int index);</pre> 3907 3908<p> 3909Returns 1 if the value at the given index is a thread, 3910and 0 otherwise. 3911 3912 3913 3914 3915 3916<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> 3917<span class="apii">[-0, +0, –]</span> 3918<pre>int lua_isuserdata (lua_State *L, int index);</pre> 3919 3920<p> 3921Returns 1 if the value at the given index is a userdata 3922(either full or light), and 0 otherwise. 3923 3924 3925 3926 3927 3928<hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p> 3929<span class="apii">[-0, +0, –]</span> 3930<pre>int lua_isyieldable (lua_State *L);</pre> 3931 3932<p> 3933Returns 1 if the given coroutine can yield, 3934and 0 otherwise. 3935 3936 3937 3938 3939 3940<hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3> 3941<pre>typedef ... lua_KContext;</pre> 3942 3943<p> 3944The type for continuation-function contexts. 3945It must be a numeric type. 3946This type is defined as <code>intptr_t</code> 3947when <code>intptr_t</code> is available, 3948so that it can store pointers too. 3949Otherwise, it is defined as <code>ptrdiff_t</code>. 3950 3951 3952 3953 3954 3955<hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3> 3956<pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre> 3957 3958<p> 3959Type for continuation functions (see <a href="#4.7">§4.7</a>). 3960 3961 3962 3963 3964 3965<hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p> 3966<span class="apii">[-0, +1, <em>e</em>]</span> 3967<pre>void lua_len (lua_State *L, int index);</pre> 3968 3969<p> 3970Returns the length of the value at the given index. 3971It is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>) and 3972may trigger a metamethod for the "length" event (see <a href="#2.4">§2.4</a>). 3973The result is pushed on the stack. 3974 3975 3976 3977 3978 3979<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> 3980<span class="apii">[-0, +1, –]</span> 3981<pre>int lua_load (lua_State *L, 3982 lua_Reader reader, 3983 void *data, 3984 const char *chunkname, 3985 const char *mode);</pre> 3986 3987<p> 3988Loads a Lua chunk without running it. 3989If there are no errors, 3990<code>lua_load</code> pushes the compiled chunk as a Lua 3991function on top of the stack. 3992Otherwise, it pushes an error message. 3993 3994 3995<p> 3996The return values of <code>lua_load</code> are: 3997 3998<ul> 3999 4000<li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li> 4001 4002<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> 4003syntax error during precompilation;</li> 4004 4005<li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 4006memory allocation (out-of-memory) error;</li> 4007 4008<li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> 4009error while running a <code>__gc</code> metamethod. 4010(This error has no relation with the chunk being loaded. 4011It is generated by the garbage collector.) 4012</li> 4013 4014</ul> 4015 4016<p> 4017The <code>lua_load</code> function uses a user-supplied <code>reader</code> function 4018to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). 4019The <code>data</code> argument is an opaque value passed to the reader function. 4020 4021 4022<p> 4023The <code>chunkname</code> argument gives a name to the chunk, 4024which is used for error messages and in debug information (see <a href="#4.9">§4.9</a>). 4025 4026 4027<p> 4028<code>lua_load</code> automatically detects whether the chunk is text or binary 4029and loads it accordingly (see program <code>luac</code>). 4030The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>, 4031with the addition that 4032a <code>NULL</code> value is equivalent to the string "<code>bt</code>". 4033 4034 4035<p> 4036<code>lua_load</code> uses the stack internally, 4037so the reader function must always leave the stack 4038unmodified when returning. 4039 4040 4041<p> 4042If the resulting function has upvalues, 4043its first upvalue is set to the value of the global environment 4044stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">§4.5</a>). 4045When loading main chunks, 4046this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 4047Other upvalues are initialized with <b>nil</b>. 4048 4049 4050 4051 4052 4053<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> 4054<span class="apii">[-0, +0, –]</span> 4055<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> 4056 4057<p> 4058Creates a new thread running in a new, independent state. 4059Returns <code>NULL</code> if it cannot create the thread or the state 4060(due to lack of memory). 4061The argument <code>f</code> is the allocator function; 4062Lua does all memory allocation for this state 4063through this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>). 4064The second argument, <code>ud</code>, is an opaque pointer that Lua 4065passes to the allocator in every call. 4066 4067 4068 4069 4070 4071<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> 4072<span class="apii">[-0, +1, <em>m</em>]</span> 4073<pre>void lua_newtable (lua_State *L);</pre> 4074 4075<p> 4076Creates a new empty table and pushes it onto the stack. 4077It is equivalent to <code>lua_createtable(L, 0, 0)</code>. 4078 4079 4080 4081 4082 4083<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> 4084<span class="apii">[-0, +1, <em>m</em>]</span> 4085<pre>lua_State *lua_newthread (lua_State *L);</pre> 4086 4087<p> 4088Creates a new thread, pushes it on the stack, 4089and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. 4090The new thread returned by this function shares with the original thread 4091its global environment, 4092but has an independent execution stack. 4093 4094 4095<p> 4096There is no explicit function to close or to destroy a thread. 4097Threads are subject to garbage collection, 4098like any Lua object. 4099 4100 4101 4102 4103 4104<hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p> 4105<span class="apii">[-0, +1, <em>m</em>]</span> 4106<pre>void *lua_newuserdata (lua_State *L, size_t size);</pre> 4107 4108<p> 4109This function allocates a new block of memory with the given size, 4110pushes onto the stack a new full userdata with the block address, 4111and returns this address. 4112The host program can freely use this memory. 4113 4114 4115 4116 4117 4118<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> 4119<span class="apii">[-1, +(2|0), <em>e</em>]</span> 4120<pre>int lua_next (lua_State *L, int index);</pre> 4121 4122<p> 4123Pops a key from the stack, 4124and pushes a key–value pair from the table at the given index 4125(the "next" pair after the given key). 4126If there are no more elements in the table, 4127then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). 4128 4129 4130<p> 4131A typical traversal looks like this: 4132 4133<pre> 4134 /* table is in the stack at index 't' */ 4135 lua_pushnil(L); /* first key */ 4136 while (lua_next(L, t) != 0) { 4137 /* uses 'key' (at index -2) and 'value' (at index -1) */ 4138 printf("%s - %s\n", 4139 lua_typename(L, lua_type(L, -2)), 4140 lua_typename(L, lua_type(L, -1))); 4141 /* removes 'value'; keeps 'key' for next iteration */ 4142 lua_pop(L, 1); 4143 } 4144</pre> 4145 4146<p> 4147While traversing a table, 4148do not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, 4149unless you know that the key is actually a string. 4150Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change 4151the value at the given index; 4152this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. 4153 4154 4155<p> 4156See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 4157the table during its traversal. 4158 4159 4160 4161 4162 4163<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> 4164<pre>typedef ... lua_Number;</pre> 4165 4166<p> 4167The type of floats in Lua. 4168 4169 4170<p> 4171By default this type is double, 4172but that can be changed to a single float or a long double. 4173(See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.) 4174 4175 4176 4177 4178 4179<hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3> 4180<pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre> 4181 4182<p> 4183Converts a Lua float to a Lua integer. 4184This macro assumes that <code>n</code> has an integral value. 4185If that value is within the range of Lua integers, 4186it is converted to an integer and assigned to <code>*p</code>. 4187The macro results in a boolean indicating whether the 4188conversion was successful. 4189(Note that this range test can be tricky to do 4190correctly without this macro, 4191due to roundings.) 4192 4193 4194<p> 4195This macro may evaluate its arguments more than once. 4196 4197 4198 4199 4200 4201<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> 4202<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4203<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre> 4204 4205<p> 4206Calls a function in protected mode. 4207 4208 4209<p> 4210Both <code>nargs</code> and <code>nresults</code> have the same meaning as 4211in <a href="#lua_call"><code>lua_call</code></a>. 4212If there are no errors during the call, 4213<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. 4214However, if there is any error, 4215<a href="#lua_pcall"><code>lua_pcall</code></a> catches it, 4216pushes a single value on the stack (the error object), 4217and returns an error code. 4218Like <a href="#lua_call"><code>lua_call</code></a>, 4219<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function 4220and its arguments from the stack. 4221 4222 4223<p> 4224If <code>msgh</code> is 0, 4225then the error object returned on the stack 4226is exactly the original error object. 4227Otherwise, <code>msgh</code> is the stack index of a 4228<em>message handler</em>. 4229(This index cannot be a pseudo-index.) 4230In case of runtime errors, 4231this function will be called with the error object 4232and its return value will be the object 4233returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. 4234 4235 4236<p> 4237Typically, the message handler is used to add more debug 4238information to the error object, such as a stack traceback. 4239Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, 4240since by then the stack has unwound. 4241 4242 4243<p> 4244The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following constants 4245(defined in <code>lua.h</code>): 4246 4247<ul> 4248 4249<li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> 4250success.</li> 4251 4252<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b> 4253a runtime error. 4254</li> 4255 4256<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 4257memory allocation error. 4258For such errors, Lua does not call the message handler. 4259</li> 4260 4261<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b> 4262error while running the message handler. 4263</li> 4264 4265<li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> 4266error while running a <code>__gc</code> metamethod. 4267For such errors, Lua does not call the message handler 4268(as this kind of error typically has no relation 4269with the function being called). 4270</li> 4271 4272</ul> 4273 4274 4275 4276 4277<hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p> 4278<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4279<pre>int lua_pcallk (lua_State *L, 4280 int nargs, 4281 int nresults, 4282 int msgh, 4283 lua_KContext ctx, 4284 lua_KFunction k);</pre> 4285 4286<p> 4287This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>, 4288but allows the called function to yield (see <a href="#4.7">§4.7</a>). 4289 4290 4291 4292 4293 4294<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> 4295<span class="apii">[-n, +0, –]</span> 4296<pre>void lua_pop (lua_State *L, int n);</pre> 4297 4298<p> 4299Pops <code>n</code> elements from the stack. 4300 4301 4302 4303 4304 4305<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> 4306<span class="apii">[-0, +1, –]</span> 4307<pre>void lua_pushboolean (lua_State *L, int b);</pre> 4308 4309<p> 4310Pushes a boolean value with value <code>b</code> onto the stack. 4311 4312 4313 4314 4315 4316<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> 4317<span class="apii">[-n, +1, <em>m</em>]</span> 4318<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> 4319 4320<p> 4321Pushes a new C closure onto the stack. 4322 4323 4324<p> 4325When a C function is created, 4326it is possible to associate some values with it, 4327thus creating a C closure (see <a href="#4.4">§4.4</a>); 4328these values are then accessible to the function whenever it is called. 4329To associate values with a C function, 4330first these values must be pushed onto the stack 4331(when there are multiple values, the first value is pushed first). 4332Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 4333is called to create and push the C function onto the stack, 4334with the argument <code>n</code> telling how many values will be 4335associated with the function. 4336<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. 4337 4338 4339<p> 4340The maximum value for <code>n</code> is 255. 4341 4342 4343<p> 4344When <code>n</code> is zero, 4345this function creates a <em>light C function</em>, 4346which is just a pointer to the C function. 4347In that case, it never raises a memory error. 4348 4349 4350 4351 4352 4353<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> 4354<span class="apii">[-0, +1, –]</span> 4355<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> 4356 4357<p> 4358Pushes a C function onto the stack. 4359This function receives a pointer to a C function 4360and pushes onto the stack a Lua value of type <code>function</code> that, 4361when called, invokes the corresponding C function. 4362 4363 4364<p> 4365Any function to be callable by Lua must 4366follow the correct protocol to receive its parameters 4367and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 4368 4369 4370 4371 4372 4373<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> 4374<span class="apii">[-0, +1, <em>e</em>]</span> 4375<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> 4376 4377<p> 4378Pushes onto the stack a formatted string 4379and returns a pointer to this string. 4380It is similar to the ISO C function <code>sprintf</code>, 4381but has some important differences: 4382 4383<ul> 4384 4385<li> 4386You do not have to allocate space for the result: 4387the result is a Lua string and Lua takes care of memory allocation 4388(and deallocation, through garbage collection). 4389</li> 4390 4391<li> 4392The conversion specifiers are quite restricted. 4393There are no flags, widths, or precisions. 4394The conversion specifiers can only be 4395'<code>%%</code>' (inserts the character '<code>%</code>'), 4396'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), 4397'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), 4398'<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>), 4399'<code>%p</code>' (inserts a pointer as a hexadecimal numeral), 4400'<code>%d</code>' (inserts an <code>int</code>), 4401'<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and 4402'<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence). 4403</li> 4404 4405</ul> 4406 4407<p> 4408Unlike other push functions, 4409this function checks for the stack space it needs, 4410including the slot for its result. 4411 4412 4413 4414 4415 4416<hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p> 4417<span class="apii">[-0, +1, –]</span> 4418<pre>void lua_pushglobaltable (lua_State *L);</pre> 4419 4420<p> 4421Pushes the global environment onto the stack. 4422 4423 4424 4425 4426 4427<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> 4428<span class="apii">[-0, +1, –]</span> 4429<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> 4430 4431<p> 4432Pushes an integer with value <code>n</code> onto the stack. 4433 4434 4435 4436 4437 4438<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> 4439<span class="apii">[-0, +1, –]</span> 4440<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> 4441 4442<p> 4443Pushes a light userdata onto the stack. 4444 4445 4446<p> 4447Userdata represent C values in Lua. 4448A <em>light userdata</em> represents a pointer, a <code>void*</code>. 4449It is a value (like a number): 4450you do not create it, it has no individual metatable, 4451and it is not collected (as it was never created). 4452A light userdata is equal to "any" 4453light userdata with the same C address. 4454 4455 4456 4457 4458 4459<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> 4460<span class="apii">[-0, +1, <em>m</em>]</span> 4461<pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre> 4462 4463<p> 4464This macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>, 4465but should be used only when <code>s</code> is a literal string. 4466 4467 4468 4469 4470 4471<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> 4472<span class="apii">[-0, +1, <em>m</em>]</span> 4473<pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> 4474 4475<p> 4476Pushes the string pointed to by <code>s</code> with size <code>len</code> 4477onto the stack. 4478Lua makes (or reuses) an internal copy of the given string, 4479so the memory at <code>s</code> can be freed or reused immediately after 4480the function returns. 4481The string can contain any binary data, 4482including embedded zeros. 4483 4484 4485<p> 4486Returns a pointer to the internal copy of the string. 4487 4488 4489 4490 4491 4492<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> 4493<span class="apii">[-0, +1, –]</span> 4494<pre>void lua_pushnil (lua_State *L);</pre> 4495 4496<p> 4497Pushes a nil value onto the stack. 4498 4499 4500 4501 4502 4503<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> 4504<span class="apii">[-0, +1, –]</span> 4505<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> 4506 4507<p> 4508Pushes a float with value <code>n</code> onto the stack. 4509 4510 4511 4512 4513 4514<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> 4515<span class="apii">[-0, +1, <em>m</em>]</span> 4516<pre>const char *lua_pushstring (lua_State *L, const char *s);</pre> 4517 4518<p> 4519Pushes the zero-terminated string pointed to by <code>s</code> 4520onto the stack. 4521Lua makes (or reuses) an internal copy of the given string, 4522so the memory at <code>s</code> can be freed or reused immediately after 4523the function returns. 4524 4525 4526<p> 4527Returns a pointer to the internal copy of the string. 4528 4529 4530<p> 4531If <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>. 4532 4533 4534 4535 4536 4537<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> 4538<span class="apii">[-0, +1, –]</span> 4539<pre>int lua_pushthread (lua_State *L);</pre> 4540 4541<p> 4542Pushes the thread represented by <code>L</code> onto the stack. 4543Returns 1 if this thread is the main thread of its state. 4544 4545 4546 4547 4548 4549<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> 4550<span class="apii">[-0, +1, –]</span> 4551<pre>void lua_pushvalue (lua_State *L, int index);</pre> 4552 4553<p> 4554Pushes a copy of the element at the given index 4555onto the stack. 4556 4557 4558 4559 4560 4561<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> 4562<span class="apii">[-0, +1, <em>m</em>]</span> 4563<pre>const char *lua_pushvfstring (lua_State *L, 4564 const char *fmt, 4565 va_list argp);</pre> 4566 4567<p> 4568Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> 4569instead of a variable number of arguments. 4570 4571 4572 4573 4574 4575<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> 4576<span class="apii">[-0, +0, –]</span> 4577<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> 4578 4579<p> 4580Returns 1 if the two values in indices <code>index1</code> and 4581<code>index2</code> are primitively equal 4582(that is, without calling the <code>__eq</code> metamethod). 4583Otherwise returns 0. 4584Also returns 0 if any of the indices are not valid. 4585 4586 4587 4588 4589 4590<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> 4591<span class="apii">[-1, +1, –]</span> 4592<pre>int lua_rawget (lua_State *L, int index);</pre> 4593 4594<p> 4595Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access 4596(i.e., without metamethods). 4597 4598 4599 4600 4601 4602<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> 4603<span class="apii">[-0, +1, –]</span> 4604<pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre> 4605 4606<p> 4607Pushes onto the stack the value <code>t[n]</code>, 4608where <code>t</code> is the table at the given index. 4609The access is raw, 4610that is, it does not invoke the <code>__index</code> metamethod. 4611 4612 4613<p> 4614Returns the type of the pushed value. 4615 4616 4617 4618 4619 4620<hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p> 4621<span class="apii">[-0, +1, –]</span> 4622<pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre> 4623 4624<p> 4625Pushes onto the stack the value <code>t[k]</code>, 4626where <code>t</code> is the table at the given index and 4627<code>k</code> is the pointer <code>p</code> represented as a light userdata. 4628The access is raw; 4629that is, it does not invoke the <code>__index</code> metamethod. 4630 4631 4632<p> 4633Returns the type of the pushed value. 4634 4635 4636 4637 4638 4639<hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p> 4640<span class="apii">[-0, +0, –]</span> 4641<pre>size_t lua_rawlen (lua_State *L, int index);</pre> 4642 4643<p> 4644Returns the raw "length" of the value at the given index: 4645for strings, this is the string length; 4646for tables, this is the result of the length operator ('<code>#</code>') 4647with no metamethods; 4648for userdata, this is the size of the block of memory allocated 4649for the userdata; 4650for other values, it is 0. 4651 4652 4653 4654 4655 4656<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> 4657<span class="apii">[-2, +0, <em>m</em>]</span> 4658<pre>void lua_rawset (lua_State *L, int index);</pre> 4659 4660<p> 4661Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment 4662(i.e., without metamethods). 4663 4664 4665 4666 4667 4668<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> 4669<span class="apii">[-1, +0, <em>m</em>]</span> 4670<pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre> 4671 4672<p> 4673Does the equivalent of <code>t[i] = v</code>, 4674where <code>t</code> is the table at the given index 4675and <code>v</code> is the value at the top of the stack. 4676 4677 4678<p> 4679This function pops the value from the stack. 4680The assignment is raw, 4681that is, it does not invoke the <code>__newindex</code> metamethod. 4682 4683 4684 4685 4686 4687<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p> 4688<span class="apii">[-1, +0, <em>m</em>]</span> 4689<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre> 4690 4691<p> 4692Does the equivalent of <code>t[p] = v</code>, 4693where <code>t</code> is the table at the given index, 4694<code>p</code> is encoded as a light userdata, 4695and <code>v</code> is the value at the top of the stack. 4696 4697 4698<p> 4699This function pops the value from the stack. 4700The assignment is raw, 4701that is, it does not invoke <code>__newindex</code> metamethod. 4702 4703 4704 4705 4706 4707<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> 4708<pre>typedef const char * (*lua_Reader) (lua_State *L, 4709 void *data, 4710 size_t *size);</pre> 4711 4712<p> 4713The reader function used by <a href="#lua_load"><code>lua_load</code></a>. 4714Every time it needs another piece of the chunk, 4715<a href="#lua_load"><code>lua_load</code></a> calls the reader, 4716passing along its <code>data</code> parameter. 4717The reader must return a pointer to a block of memory 4718with a new piece of the chunk 4719and set <code>size</code> to the block size. 4720The block must exist until the reader function is called again. 4721To signal the end of the chunk, 4722the reader must return <code>NULL</code> or set <code>size</code> to zero. 4723The reader function may return pieces of any size greater than zero. 4724 4725 4726 4727 4728 4729<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> 4730<span class="apii">[-0, +0, <em>e</em>]</span> 4731<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre> 4732 4733<p> 4734Sets the C function <code>f</code> as the new value of global <code>name</code>. 4735It is defined as a macro: 4736 4737<pre> 4738 #define lua_register(L,n,f) \ 4739 (lua_pushcfunction(L, f), lua_setglobal(L, n)) 4740</pre> 4741 4742 4743 4744 4745<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> 4746<span class="apii">[-1, +0, –]</span> 4747<pre>void lua_remove (lua_State *L, int index);</pre> 4748 4749<p> 4750Removes the element at the given valid index, 4751shifting down the elements above this index to fill the gap. 4752This function cannot be called with a pseudo-index, 4753because a pseudo-index is not an actual stack position. 4754 4755 4756 4757 4758 4759<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> 4760<span class="apii">[-1, +0, –]</span> 4761<pre>void lua_replace (lua_State *L, int index);</pre> 4762 4763<p> 4764Moves the top element into the given valid index 4765without shifting any element 4766(therefore replacing the value at that given index), 4767and then pops the top element. 4768 4769 4770 4771 4772 4773<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> 4774<span class="apii">[-?, +?, –]</span> 4775<pre>int lua_resume (lua_State *L, lua_State *from, int nargs);</pre> 4776 4777<p> 4778Starts and resumes a coroutine in the given thread <code>L</code>. 4779 4780 4781<p> 4782To start a coroutine, 4783you push onto the thread stack the main function plus any arguments; 4784then you call <a href="#lua_resume"><code>lua_resume</code></a>, 4785with <code>nargs</code> being the number of arguments. 4786This call returns when the coroutine suspends or finishes its execution. 4787When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>, 4788or all values returned by the body function. 4789<a href="#lua_resume"><code>lua_resume</code></a> returns 4790<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, 4791<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution 4792without errors, 4793or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). 4794 4795 4796<p> 4797In case of errors, 4798the stack is not unwound, 4799so you can use the debug API over it. 4800The error object is on the top of the stack. 4801 4802 4803<p> 4804To resume a coroutine, 4805you remove any results from the last <a href="#lua_yield"><code>lua_yield</code></a>, 4806put on its stack only the values to 4807be passed as results from <code>yield</code>, 4808and then call <a href="#lua_resume"><code>lua_resume</code></a>. 4809 4810 4811<p> 4812The parameter <code>from</code> represents the coroutine that is resuming <code>L</code>. 4813If there is no such coroutine, 4814this parameter can be <code>NULL</code>. 4815 4816 4817 4818 4819 4820<hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p> 4821<span class="apii">[-0, +0, –]</span> 4822<pre>void lua_rotate (lua_State *L, int idx, int n);</pre> 4823 4824<p> 4825Rotates the stack elements between the valid index <code>idx</code> 4826and the top of the stack. 4827The elements are rotated <code>n</code> positions in the direction of the top, 4828for a positive <code>n</code>, 4829or <code>-n</code> positions in the direction of the bottom, 4830for a negative <code>n</code>. 4831The absolute value of <code>n</code> must not be greater than the size 4832of the slice being rotated. 4833This function cannot be called with a pseudo-index, 4834because a pseudo-index is not an actual stack position. 4835 4836 4837 4838 4839 4840<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> 4841<span class="apii">[-0, +0, –]</span> 4842<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> 4843 4844<p> 4845Changes the allocator function of a given state to <code>f</code> 4846with user data <code>ud</code>. 4847 4848 4849 4850 4851 4852<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> 4853<span class="apii">[-1, +0, <em>e</em>]</span> 4854<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> 4855 4856<p> 4857Does the equivalent to <code>t[k] = v</code>, 4858where <code>t</code> is the value at the given index 4859and <code>v</code> is the value at the top of the stack. 4860 4861 4862<p> 4863This function pops the value from the stack. 4864As in Lua, this function may trigger a metamethod 4865for the "newindex" event (see <a href="#2.4">§2.4</a>). 4866 4867 4868 4869 4870 4871<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> 4872<span class="apii">[-1, +0, <em>e</em>]</span> 4873<pre>void lua_setglobal (lua_State *L, const char *name);</pre> 4874 4875<p> 4876Pops a value from the stack and 4877sets it as the new value of global <code>name</code>. 4878 4879 4880 4881 4882 4883<hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p> 4884<span class="apii">[-1, +0, <em>e</em>]</span> 4885<pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre> 4886 4887<p> 4888Does the equivalent to <code>t[n] = v</code>, 4889where <code>t</code> is the value at the given index 4890and <code>v</code> is the value at the top of the stack. 4891 4892 4893<p> 4894This function pops the value from the stack. 4895As in Lua, this function may trigger a metamethod 4896for the "newindex" event (see <a href="#2.4">§2.4</a>). 4897 4898 4899 4900 4901 4902<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> 4903<span class="apii">[-1, +0, –]</span> 4904<pre>void lua_setmetatable (lua_State *L, int index);</pre> 4905 4906<p> 4907Pops a table from the stack and 4908sets it as the new metatable for the value at the given index. 4909 4910 4911 4912 4913 4914<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> 4915<span class="apii">[-2, +0, <em>e</em>]</span> 4916<pre>void lua_settable (lua_State *L, int index);</pre> 4917 4918<p> 4919Does the equivalent to <code>t[k] = v</code>, 4920where <code>t</code> is the value at the given index, 4921<code>v</code> is the value at the top of the stack, 4922and <code>k</code> is the value just below the top. 4923 4924 4925<p> 4926This function pops both the key and the value from the stack. 4927As in Lua, this function may trigger a metamethod 4928for the "newindex" event (see <a href="#2.4">§2.4</a>). 4929 4930 4931 4932 4933 4934<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> 4935<span class="apii">[-?, +?, –]</span> 4936<pre>void lua_settop (lua_State *L, int index);</pre> 4937 4938<p> 4939Accepts any index, or 0, 4940and sets the stack top to this index. 4941If the new top is larger than the old one, 4942then the new elements are filled with <b>nil</b>. 4943If <code>index</code> is 0, then all stack elements are removed. 4944 4945 4946 4947 4948 4949<hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p> 4950<span class="apii">[-1, +0, –]</span> 4951<pre>void lua_setuservalue (lua_State *L, int index);</pre> 4952 4953<p> 4954Pops a value from the stack and sets it as 4955the new value associated to the full userdata at the given index. 4956 4957 4958 4959 4960 4961<hr><h3><a name="lua_State"><code>lua_State</code></a></h3> 4962<pre>typedef struct lua_State lua_State;</pre> 4963 4964<p> 4965An opaque structure that points to a thread and indirectly 4966(through the thread) to the whole state of a Lua interpreter. 4967The Lua library is fully reentrant: 4968it has no global variables. 4969All information about a state is accessible through this structure. 4970 4971 4972<p> 4973A pointer to this structure must be passed as the first argument to 4974every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 4975which creates a Lua state from scratch. 4976 4977 4978 4979 4980 4981<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> 4982<span class="apii">[-0, +0, –]</span> 4983<pre>int lua_status (lua_State *L);</pre> 4984 4985<p> 4986Returns the status of the thread <code>L</code>. 4987 4988 4989<p> 4990The status can be 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) for a normal thread, 4991an error code if the thread finished the execution 4992of a <a href="#lua_resume"><code>lua_resume</code></a> with an error, 4993or <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. 4994 4995 4996<p> 4997You can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>. 4998You can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> 4999(to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> 5000(to resume a coroutine). 5001 5002 5003 5004 5005 5006<hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p> 5007<span class="apii">[-0, +1, –]</span> 5008<pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre> 5009 5010<p> 5011Converts the zero-terminated string <code>s</code> to a number, 5012pushes that number into the stack, 5013and returns the total size of the string, 5014that is, its length plus one. 5015The conversion can result in an integer or a float, 5016according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 5017The string may have leading and trailing spaces and a sign. 5018If the string is not a valid numeral, 5019returns 0 and pushes nothing. 5020(Note that the result can be used as a boolean, 5021true if the conversion succeeds.) 5022 5023 5024 5025 5026 5027<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> 5028<span class="apii">[-0, +0, –]</span> 5029<pre>int lua_toboolean (lua_State *L, int index);</pre> 5030 5031<p> 5032Converts the Lua value at the given index to a C boolean 5033value (0 or 1). 5034Like all tests in Lua, 5035<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value 5036different from <b>false</b> and <b>nil</b>; 5037otherwise it returns false. 5038(If you want to accept only actual boolean values, 5039use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) 5040 5041 5042 5043 5044 5045<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> 5046<span class="apii">[-0, +0, –]</span> 5047<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> 5048 5049<p> 5050Converts a value at the given index to a C function. 5051That value must be a C function; 5052otherwise, returns <code>NULL</code>. 5053 5054 5055 5056 5057 5058<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> 5059<span class="apii">[-0, +0, –]</span> 5060<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> 5061 5062<p> 5063Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5064 5065 5066 5067 5068 5069<hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p> 5070<span class="apii">[-0, +0, –]</span> 5071<pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre> 5072 5073<p> 5074Converts the Lua value at the given index 5075to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. 5076The Lua value must be an integer, 5077or a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>); 5078otherwise, <code>lua_tointegerx</code> returns 0. 5079 5080 5081<p> 5082If <code>isnum</code> is not <code>NULL</code>, 5083its referent is assigned a boolean value that 5084indicates whether the operation succeeded. 5085 5086 5087 5088 5089 5090<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> 5091<span class="apii">[-0, +0, <em>m</em>]</span> 5092<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> 5093 5094<p> 5095Converts the Lua value at the given index to a C string. 5096If <code>len</code> is not <code>NULL</code>, 5097it sets <code>*len</code> with the string length. 5098The Lua value must be a string or a number; 5099otherwise, the function returns <code>NULL</code>. 5100If the value is a number, 5101then <code>lua_tolstring</code> also 5102<em>changes the actual value in the stack to a string</em>. 5103(This change confuses <a href="#lua_next"><code>lua_next</code></a> 5104when <code>lua_tolstring</code> is applied to keys during a table traversal.) 5105 5106 5107<p> 5108<code>lua_tolstring</code> returns a pointer 5109to a string inside the Lua state. 5110This string always has a zero ('<code>\0</code>') 5111after its last character (as in C), 5112but can contain other zeros in its body. 5113 5114 5115<p> 5116Because Lua has garbage collection, 5117there is no guarantee that the pointer returned by <code>lua_tolstring</code> 5118will be valid after the corresponding Lua value is removed from the stack. 5119 5120 5121 5122 5123 5124<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> 5125<span class="apii">[-0, +0, –]</span> 5126<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> 5127 5128<p> 5129Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5130 5131 5132 5133 5134 5135<hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p> 5136<span class="apii">[-0, +0, –]</span> 5137<pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre> 5138 5139<p> 5140Converts the Lua value at the given index 5141to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). 5142The Lua value must be a number or a string convertible to a number 5143(see <a href="#3.4.3">§3.4.3</a>); 5144otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0. 5145 5146 5147<p> 5148If <code>isnum</code> is not <code>NULL</code>, 5149its referent is assigned a boolean value that 5150indicates whether the operation succeeded. 5151 5152 5153 5154 5155 5156<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> 5157<span class="apii">[-0, +0, –]</span> 5158<pre>const void *lua_topointer (lua_State *L, int index);</pre> 5159 5160<p> 5161Converts the value at the given index to a generic 5162C pointer (<code>void*</code>). 5163The value can be a userdata, a table, a thread, or a function; 5164otherwise, <code>lua_topointer</code> returns <code>NULL</code>. 5165Different objects will give different pointers. 5166There is no way to convert the pointer back to its original value. 5167 5168 5169<p> 5170Typically this function is used only for hashing and debug information. 5171 5172 5173 5174 5175 5176<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> 5177<span class="apii">[-0, +0, <em>m</em>]</span> 5178<pre>const char *lua_tostring (lua_State *L, int index);</pre> 5179 5180<p> 5181Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. 5182 5183 5184 5185 5186 5187<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> 5188<span class="apii">[-0, +0, –]</span> 5189<pre>lua_State *lua_tothread (lua_State *L, int index);</pre> 5190 5191<p> 5192Converts the value at the given index to a Lua thread 5193(represented as <code>lua_State*</code>). 5194This value must be a thread; 5195otherwise, the function returns <code>NULL</code>. 5196 5197 5198 5199 5200 5201<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> 5202<span class="apii">[-0, +0, –]</span> 5203<pre>void *lua_touserdata (lua_State *L, int index);</pre> 5204 5205<p> 5206If the value at the given index is a full userdata, 5207returns its block address. 5208If the value is a light userdata, 5209returns its pointer. 5210Otherwise, returns <code>NULL</code>. 5211 5212 5213 5214 5215 5216<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> 5217<span class="apii">[-0, +0, –]</span> 5218<pre>int lua_type (lua_State *L, int index);</pre> 5219 5220<p> 5221Returns the type of the value in the given valid index, 5222or <code>LUA_TNONE</code> for a non-valid (but acceptable) index. 5223The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants 5224defined in <code>lua.h</code>: 5225<a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a> (0), 5226<a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>, 5227<a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>, 5228<a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, 5229<a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, 5230<a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, 5231<a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, 5232<a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>, 5233and 5234<a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>. 5235 5236 5237 5238 5239 5240<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> 5241<span class="apii">[-0, +0, –]</span> 5242<pre>const char *lua_typename (lua_State *L, int tp);</pre> 5243 5244<p> 5245Returns the name of the type encoded by the value <code>tp</code>, 5246which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. 5247 5248 5249 5250 5251 5252<hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3> 5253<pre>typedef ... lua_Unsigned;</pre> 5254 5255<p> 5256The unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>. 5257 5258 5259 5260 5261 5262<hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p> 5263<span class="apii">[-0, +0, –]</span> 5264<pre>int lua_upvalueindex (int i);</pre> 5265 5266<p> 5267Returns the pseudo-index that represents the <code>i</code>-th upvalue of 5268the running function (see <a href="#4.4">§4.4</a>). 5269 5270 5271 5272 5273 5274<hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p> 5275<span class="apii">[-0, +0, –]</span> 5276<pre>const lua_Number *lua_version (lua_State *L);</pre> 5277 5278<p> 5279Returns the address of the version number 5280(a C static variable) 5281stored in the Lua core. 5282When called with a valid <a href="#lua_State"><code>lua_State</code></a>, 5283returns the address of the version used to create that state. 5284When called with <code>NULL</code>, 5285returns the address of the version running the call. 5286 5287 5288 5289 5290 5291<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> 5292<pre>typedef int (*lua_Writer) (lua_State *L, 5293 const void* p, 5294 size_t sz, 5295 void* ud);</pre> 5296 5297<p> 5298The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. 5299Every time it produces another piece of chunk, 5300<a href="#lua_dump"><code>lua_dump</code></a> calls the writer, 5301passing along the buffer to be written (<code>p</code>), 5302its size (<code>sz</code>), 5303and the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. 5304 5305 5306<p> 5307The writer returns an error code: 53080 means no errors; 5309any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from 5310calling the writer again. 5311 5312 5313 5314 5315 5316<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> 5317<span class="apii">[-?, +?, –]</span> 5318<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> 5319 5320<p> 5321Exchange values between different threads of the same state. 5322 5323 5324<p> 5325This function pops <code>n</code> values from the stack <code>from</code>, 5326and pushes them onto the stack <code>to</code>. 5327 5328 5329 5330 5331 5332<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> 5333<span class="apii">[-?, +?, <em>e</em>]</span> 5334<pre>int lua_yield (lua_State *L, int nresults);</pre> 5335 5336<p> 5337This function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5338but it has no continuation (see <a href="#4.7">§4.7</a>). 5339Therefore, when the thread resumes, 5340it continues the function that called 5341the function calling <code>lua_yield</code>. 5342 5343 5344 5345 5346 5347<hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p> 5348<span class="apii">[-?, +?, <em>e</em>]</span> 5349<pre>int lua_yieldk (lua_State *L, 5350 int nresults, 5351 lua_KContext ctx, 5352 lua_KFunction k);</pre> 5353 5354<p> 5355Yields a coroutine (thread). 5356 5357 5358<p> 5359When a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5360the running coroutine suspends its execution, 5361and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. 5362The parameter <code>nresults</code> is the number of values from the stack 5363that will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. 5364 5365 5366<p> 5367When the coroutine is resumed again, 5368Lua calls the given continuation function <code>k</code> to continue 5369the execution of the C function that yielded (see <a href="#4.7">§4.7</a>). 5370This continuation function receives the same stack 5371from the previous function, 5372with the <code>n</code> results removed and 5373replaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>. 5374Moreover, 5375the continuation function receives the value <code>ctx</code> 5376that was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>. 5377 5378 5379<p> 5380Usually, this function does not return; 5381when the coroutine eventually resumes, 5382it continues executing the continuation function. 5383However, there is one special case, 5384which is when this function is called 5385from inside a line or a count hook (see <a href="#4.9">§4.9</a>). 5386In that case, <code>lua_yieldk</code> should be called with no continuation 5387(probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results, 5388and the hook should return immediately after the call. 5389Lua will yield and, 5390when the coroutine resumes again, 5391it will continue the normal execution 5392of the (Lua) function that triggered the hook. 5393 5394 5395<p> 5396This function can raise an error if it is called from a thread 5397with a pending C call with no continuation function, 5398or it is called from a thread that is not running inside a resume 5399(e.g., the main thread). 5400 5401 5402 5403 5404 5405 5406 5407<h2>4.9 – <a name="4.9">The Debug Interface</a></h2> 5408 5409<p> 5410Lua has no built-in debugging facilities. 5411Instead, it offers a special interface 5412by means of functions and <em>hooks</em>. 5413This interface allows the construction of different 5414kinds of debuggers, profilers, and other tools 5415that need "inside information" from the interpreter. 5416 5417 5418 5419<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> 5420<pre>typedef struct lua_Debug { 5421 int event; 5422 const char *name; /* (n) */ 5423 const char *namewhat; /* (n) */ 5424 const char *what; /* (S) */ 5425 const char *source; /* (S) */ 5426 int currentline; /* (l) */ 5427 int linedefined; /* (S) */ 5428 int lastlinedefined; /* (S) */ 5429 unsigned char nups; /* (u) number of upvalues */ 5430 unsigned char nparams; /* (u) number of parameters */ 5431 char isvararg; /* (u) */ 5432 char istailcall; /* (t) */ 5433 char short_src[LUA_IDSIZE]; /* (S) */ 5434 /* private part */ 5435 <em>other fields</em> 5436} lua_Debug;</pre> 5437 5438<p> 5439A structure used to carry different pieces of 5440information about a function or an activation record. 5441<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part 5442of this structure, for later use. 5443To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, 5444call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 5445 5446 5447<p> 5448The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: 5449 5450<ul> 5451 5452<li><b><code>source</code>: </b> 5453the name of the chunk that created the function. 5454If <code>source</code> starts with a '<code>@</code>', 5455it means that the function was defined in a file where 5456the file name follows the '<code>@</code>'. 5457If <code>source</code> starts with a '<code>=</code>', 5458the remainder of its contents describe the source in a user-dependent manner. 5459Otherwise, 5460the function was defined in a string where 5461<code>source</code> is that string. 5462</li> 5463 5464<li><b><code>short_src</code>: </b> 5465a "printable" version of <code>source</code>, to be used in error messages. 5466</li> 5467 5468<li><b><code>linedefined</code>: </b> 5469the line number where the definition of the function starts. 5470</li> 5471 5472<li><b><code>lastlinedefined</code>: </b> 5473the line number where the definition of the function ends. 5474</li> 5475 5476<li><b><code>what</code>: </b> 5477the string <code>"Lua"</code> if the function is a Lua function, 5478<code>"C"</code> if it is a C function, 5479<code>"main"</code> if it is the main part of a chunk. 5480</li> 5481 5482<li><b><code>currentline</code>: </b> 5483the current line where the given function is executing. 5484When no line information is available, 5485<code>currentline</code> is set to -1. 5486</li> 5487 5488<li><b><code>name</code>: </b> 5489a reasonable name for the given function. 5490Because functions in Lua are first-class values, 5491they do not have a fixed name: 5492some functions can be the value of multiple global variables, 5493while others can be stored only in a table field. 5494The <code>lua_getinfo</code> function checks how the function was 5495called to find a suitable name. 5496If it cannot find a name, 5497then <code>name</code> is set to <code>NULL</code>. 5498</li> 5499 5500<li><b><code>namewhat</code>: </b> 5501explains the <code>name</code> field. 5502The value of <code>namewhat</code> can be 5503<code>"global"</code>, <code>"local"</code>, <code>"method"</code>, 5504<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), 5505according to how the function was called. 5506(Lua uses the empty string when no other option seems to apply.) 5507</li> 5508 5509<li><b><code>istailcall</code>: </b> 5510true if this function invocation was called by a tail call. 5511In this case, the caller of this level is not in the stack. 5512</li> 5513 5514<li><b><code>nups</code>: </b> 5515the number of upvalues of the function. 5516</li> 5517 5518<li><b><code>nparams</code>: </b> 5519the number of fixed parameters of the function 5520(always 0 for C functions). 5521</li> 5522 5523<li><b><code>isvararg</code>: </b> 5524true if the function is a vararg function 5525(always true for C functions). 5526</li> 5527 5528</ul> 5529 5530 5531 5532 5533<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> 5534<span class="apii">[-0, +0, –]</span> 5535<pre>lua_Hook lua_gethook (lua_State *L);</pre> 5536 5537<p> 5538Returns the current hook function. 5539 5540 5541 5542 5543 5544<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> 5545<span class="apii">[-0, +0, –]</span> 5546<pre>int lua_gethookcount (lua_State *L);</pre> 5547 5548<p> 5549Returns the current hook count. 5550 5551 5552 5553 5554 5555<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> 5556<span class="apii">[-0, +0, –]</span> 5557<pre>int lua_gethookmask (lua_State *L);</pre> 5558 5559<p> 5560Returns the current hook mask. 5561 5562 5563 5564 5565 5566<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> 5567<span class="apii">[-(0|1), +(0|1|2), <em>e</em>]</span> 5568<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> 5569 5570<p> 5571Gets information about a specific function or function invocation. 5572 5573 5574<p> 5575To get information about a function invocation, 5576the parameter <code>ar</code> must be a valid activation record that was 5577filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 5578given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 5579 5580 5581<p> 5582To get information about a function, you push it onto the stack 5583and start the <code>what</code> string with the character '<code>></code>'. 5584(In that case, 5585<code>lua_getinfo</code> pops the function from the top of the stack.) 5586For instance, to know in which line a function <code>f</code> was defined, 5587you can write the following code: 5588 5589<pre> 5590 lua_Debug ar; 5591 lua_getglobal(L, "f"); /* get global 'f' */ 5592 lua_getinfo(L, ">S", &ar); 5593 printf("%d\n", ar.linedefined); 5594</pre> 5595 5596<p> 5597Each character in the string <code>what</code> 5598selects some fields of the structure <code>ar</code> to be filled or 5599a value to be pushed on the stack: 5600 5601<ul> 5602 5603<li><b>'<code>n</code>': </b> fills in the field <code>name</code> and <code>namewhat</code>; 5604</li> 5605 5606<li><b>'<code>S</code>': </b> 5607fills in the fields <code>source</code>, <code>short_src</code>, 5608<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; 5609</li> 5610 5611<li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>; 5612</li> 5613 5614<li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>; 5615</li> 5616 5617<li><b>'<code>u</code>': </b> fills in the fields 5618<code>nups</code>, <code>nparams</code>, and <code>isvararg</code>; 5619</li> 5620 5621<li><b>'<code>f</code>': </b> 5622pushes onto the stack the function that is 5623running at the given level; 5624</li> 5625 5626<li><b>'<code>L</code>': </b> 5627pushes onto the stack a table whose indices are the 5628numbers of the lines that are valid on the function. 5629(A <em>valid line</em> is a line with some associated code, 5630that is, a line where you can put a break point. 5631Non-valid lines include empty lines and comments.) 5632 5633 5634<p> 5635If this option is given together with option '<code>f</code>', 5636its table is pushed after the function. 5637</li> 5638 5639</ul> 5640 5641<p> 5642This function returns 0 on error 5643(for instance, an invalid option in <code>what</code>). 5644 5645 5646 5647 5648 5649<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> 5650<span class="apii">[-0, +(0|1), –]</span> 5651<pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 5652 5653<p> 5654Gets information about a local variable of 5655a given activation record or a given function. 5656 5657 5658<p> 5659In the first case, 5660the parameter <code>ar</code> must be a valid activation record that was 5661filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 5662given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 5663The index <code>n</code> selects which local variable to inspect; 5664see <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices 5665and names. 5666 5667 5668<p> 5669<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack 5670and returns its name. 5671 5672 5673<p> 5674In the second case, <code>ar</code> must be <code>NULL</code> and the function 5675to be inspected must be at the top of the stack. 5676In this case, only parameters of Lua functions are visible 5677(as there is no information about what variables are active) 5678and no values are pushed onto the stack. 5679 5680 5681<p> 5682Returns <code>NULL</code> (and pushes nothing) 5683when the index is greater than 5684the number of active local variables. 5685 5686 5687 5688 5689 5690<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> 5691<span class="apii">[-0, +0, –]</span> 5692<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> 5693 5694<p> 5695Gets information about the interpreter runtime stack. 5696 5697 5698<p> 5699This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with 5700an identification of the <em>activation record</em> 5701of the function executing at a given level. 5702Level 0 is the current running function, 5703whereas level <em>n+1</em> is the function that has called level <em>n</em> 5704(except for tail calls, which do not count on the stack). 5705When there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1; 5706when called with a level greater than the stack depth, 5707it returns 0. 5708 5709 5710 5711 5712 5713<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> 5714<span class="apii">[-0, +(0|1), –]</span> 5715<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> 5716 5717<p> 5718Gets information about the <code>n</code>-th upvalue 5719of the closure at index <code>funcindex</code>. 5720It pushes the upvalue's value onto the stack 5721and returns its name. 5722Returns <code>NULL</code> (and pushes nothing) 5723when the index <code>n</code> is greater than the number of upvalues. 5724 5725 5726<p> 5727For C functions, this function uses the empty string <code>""</code> 5728as a name for all upvalues. 5729(For Lua functions, 5730upvalues are the external local variables that the function uses, 5731and that are consequently included in its closure.) 5732 5733 5734<p> 5735Upvalues have no particular order, 5736as they are active through the whole function. 5737They are numbered in an arbitrary order. 5738 5739 5740 5741 5742 5743<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> 5744<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> 5745 5746<p> 5747Type for debugging hook functions. 5748 5749 5750<p> 5751Whenever a hook is called, its <code>ar</code> argument has its field 5752<code>event</code> set to the specific event that triggered the hook. 5753Lua identifies these events with the following constants: 5754<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, 5755<a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, 5756and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. 5757Moreover, for line events, the field <code>currentline</code> is also set. 5758To get the value of any other field in <code>ar</code>, 5759the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 5760 5761 5762<p> 5763For call events, <code>event</code> can be <code>LUA_HOOKCALL</code>, 5764the normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call; 5765in this case, there will be no corresponding return event. 5766 5767 5768<p> 5769While Lua is running a hook, it disables other calls to hooks. 5770Therefore, if a hook calls back Lua to execute a function or a chunk, 5771this execution occurs without any calls to hooks. 5772 5773 5774<p> 5775Hook functions cannot have continuations, 5776that is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5777<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>. 5778 5779 5780<p> 5781Hook functions can yield under the following conditions: 5782Only count and line events can yield; 5783to yield, a hook function must finish its execution 5784calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero 5785(that is, with no values). 5786 5787 5788 5789 5790 5791<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> 5792<span class="apii">[-0, +0, –]</span> 5793<pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> 5794 5795<p> 5796Sets the debugging hook function. 5797 5798 5799<p> 5800Argument <code>f</code> is the hook function. 5801<code>mask</code> specifies on which events the hook will be called: 5802it is formed by a bitwise OR of the constants 5803<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, 5804<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, 5805<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, 5806and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. 5807The <code>count</code> argument is only meaningful when the mask 5808includes <code>LUA_MASKCOUNT</code>. 5809For each event, the hook is called as explained below: 5810 5811<ul> 5812 5813<li><b>The call hook: </b> is called when the interpreter calls a function. 5814The hook is called just after Lua enters the new function, 5815before the function gets its arguments. 5816</li> 5817 5818<li><b>The return hook: </b> is called when the interpreter returns from a function. 5819The hook is called just before Lua leaves the function. 5820There is no standard way to access the values 5821to be returned by the function. 5822</li> 5823 5824<li><b>The line hook: </b> is called when the interpreter is about to 5825start the execution of a new line of code, 5826or when it jumps back in the code (even to the same line). 5827(This event only happens while Lua is executing a Lua function.) 5828</li> 5829 5830<li><b>The count hook: </b> is called after the interpreter executes every 5831<code>count</code> instructions. 5832(This event only happens while Lua is executing a Lua function.) 5833</li> 5834 5835</ul> 5836 5837<p> 5838A hook is disabled by setting <code>mask</code> to zero. 5839 5840 5841 5842 5843 5844<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> 5845<span class="apii">[-(0|1), +0, –]</span> 5846<pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 5847 5848<p> 5849Sets the value of a local variable of a given activation record. 5850It assigns the value at the top of the stack 5851to the variable and returns its name. 5852It also pops the value from the stack. 5853 5854 5855<p> 5856Returns <code>NULL</code> (and pops nothing) 5857when the index is greater than 5858the number of active local variables. 5859 5860 5861<p> 5862Parameters <code>ar</code> and <code>n</code> are as in function <a href="#lua_getlocal"><code>lua_getlocal</code></a>. 5863 5864 5865 5866 5867 5868<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> 5869<span class="apii">[-(0|1), +0, –]</span> 5870<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> 5871 5872<p> 5873Sets the value of a closure's upvalue. 5874It assigns the value at the top of the stack 5875to the upvalue and returns its name. 5876It also pops the value from the stack. 5877 5878 5879<p> 5880Returns <code>NULL</code> (and pops nothing) 5881when the index <code>n</code> is greater than the number of upvalues. 5882 5883 5884<p> 5885Parameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>. 5886 5887 5888 5889 5890 5891<hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p> 5892<span class="apii">[-0, +0, –]</span> 5893<pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre> 5894 5895<p> 5896Returns a unique identifier for the upvalue numbered <code>n</code> 5897from the closure at index <code>funcindex</code>. 5898 5899 5900<p> 5901These unique identifiers allow a program to check whether different 5902closures share upvalues. 5903Lua closures that share an upvalue 5904(that is, that access a same external local variable) 5905will return identical ids for those upvalue indices. 5906 5907 5908<p> 5909Parameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, 5910but <code>n</code> cannot be greater than the number of upvalues. 5911 5912 5913 5914 5915 5916<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p> 5917<span class="apii">[-0, +0, –]</span> 5918<pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1, 5919 int funcindex2, int n2);</pre> 5920 5921<p> 5922Make the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code> 5923refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>. 5924 5925 5926 5927 5928 5929 5930 5931<h1>5 – <a name="5">The Auxiliary Library</a></h1> 5932 5933<p> 5934 5935The <em>auxiliary library</em> provides several convenient functions 5936to interface C with Lua. 5937While the basic API provides the primitive functions for all 5938interactions between C and Lua, 5939the auxiliary library provides higher-level functions for some 5940common tasks. 5941 5942 5943<p> 5944All functions and types from the auxiliary library 5945are defined in header file <code>lauxlib.h</code> and 5946have a prefix <code>luaL_</code>. 5947 5948 5949<p> 5950All functions in the auxiliary library are built on 5951top of the basic API, 5952and so they provide nothing that cannot be done with that API. 5953Nevertheless, the use of the auxiliary library ensures 5954more consistency to your code. 5955 5956 5957<p> 5958Several functions in the auxiliary library use internally some 5959extra stack slots. 5960When a function in the auxiliary library uses less than five slots, 5961it does not check the stack size; 5962it simply assumes that there are enough slots. 5963 5964 5965<p> 5966Several functions in the auxiliary library are used to 5967check C function arguments. 5968Because the error message is formatted for arguments 5969(e.g., "<code>bad argument #1</code>"), 5970you should not use these functions for other stack values. 5971 5972 5973<p> 5974Functions called <code>luaL_check*</code> 5975always raise an error if the check is not satisfied. 5976 5977 5978 5979<h2>5.1 – <a name="5.1">Functions and Types</a></h2> 5980 5981<p> 5982Here we list all functions and types from the auxiliary library 5983in alphabetical order. 5984 5985 5986 5987<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> 5988<span class="apii">[-?, +?, <em>m</em>]</span> 5989<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> 5990 5991<p> 5992Adds the byte <code>c</code> to the buffer <code>B</code> 5993(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5994 5995 5996 5997 5998 5999<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> 6000<span class="apii">[-?, +?, <em>m</em>]</span> 6001<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> 6002 6003<p> 6004Adds the string pointed to by <code>s</code> with length <code>l</code> to 6005the buffer <code>B</code> 6006(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6007The string can contain embedded zeros. 6008 6009 6010 6011 6012 6013<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> 6014<span class="apii">[-?, +?, –]</span> 6015<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> 6016 6017<p> 6018Adds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>) 6019a string of length <code>n</code> previously copied to the 6020buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). 6021 6022 6023 6024 6025 6026<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> 6027<span class="apii">[-?, +?, <em>m</em>]</span> 6028<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> 6029 6030<p> 6031Adds the zero-terminated string pointed to by <code>s</code> 6032to the buffer <code>B</code> 6033(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6034 6035 6036 6037 6038 6039<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> 6040<span class="apii">[-1, +?, <em>m</em>]</span> 6041<pre>void luaL_addvalue (luaL_Buffer *B);</pre> 6042 6043<p> 6044Adds the value at the top of the stack 6045to the buffer <code>B</code> 6046(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6047Pops the value. 6048 6049 6050<p> 6051This is the only function on string buffers that can (and must) 6052be called with an extra element on the stack, 6053which is the value to be added to the buffer. 6054 6055 6056 6057 6058 6059<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> 6060<span class="apii">[-0, +0, <em>v</em>]</span> 6061<pre>void luaL_argcheck (lua_State *L, 6062 int cond, 6063 int arg, 6064 const char *extramsg);</pre> 6065 6066<p> 6067Checks whether <code>cond</code> is true. 6068If it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>). 6069 6070 6071 6072 6073 6074<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> 6075<span class="apii">[-0, +0, <em>v</em>]</span> 6076<pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre> 6077 6078<p> 6079Raises an error reporting a problem with argument <code>arg</code> 6080of the C function that called it, 6081using a standard message 6082that includes <code>extramsg</code> as a comment: 6083 6084<pre> 6085 bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>) 6086</pre><p> 6087This function never returns. 6088 6089 6090 6091 6092 6093<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> 6094<pre>typedef struct luaL_Buffer luaL_Buffer;</pre> 6095 6096<p> 6097Type for a <em>string buffer</em>. 6098 6099 6100<p> 6101A string buffer allows C code to build Lua strings piecemeal. 6102Its pattern of use is as follows: 6103 6104<ul> 6105 6106<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6107 6108<li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> 6109 6110<li> 6111Then add string pieces to the buffer calling any of 6112the <code>luaL_add*</code> functions. 6113</li> 6114 6115<li> 6116Finish by calling <code>luaL_pushresult(&b)</code>. 6117This call leaves the final string on the top of the stack. 6118</li> 6119 6120</ul> 6121 6122<p> 6123If you know beforehand the total size of the resulting string, 6124you can use the buffer like this: 6125 6126<ul> 6127 6128<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6129 6130<li>Then initialize it and preallocate a space of 6131size <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li> 6132 6133<li>Then copy the string into that space.</li> 6134 6135<li> 6136Finish by calling <code>luaL_pushresultsize(&b, sz)</code>, 6137where <code>sz</code> is the total size of the resulting string 6138copied into that space. 6139</li> 6140 6141</ul> 6142 6143<p> 6144During its normal operation, 6145a string buffer uses a variable number of stack slots. 6146So, while using a buffer, you cannot assume that you know where 6147the top of the stack is. 6148You can use the stack between successive calls to buffer operations 6149as long as that use is balanced; 6150that is, 6151when you call a buffer operation, 6152the stack is at the same level 6153it was immediately after the previous buffer operation. 6154(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) 6155After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its 6156level when the buffer was initialized, 6157plus the final string on its top. 6158 6159 6160 6161 6162 6163<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> 6164<span class="apii">[-0, +0, –]</span> 6165<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> 6166 6167<p> 6168Initializes a buffer <code>B</code>. 6169This function does not allocate any space; 6170the buffer must be declared as a variable 6171(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6172 6173 6174 6175 6176 6177<hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p> 6178<span class="apii">[-?, +?, <em>m</em>]</span> 6179<pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre> 6180 6181<p> 6182Equivalent to the sequence 6183<a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>. 6184 6185 6186 6187 6188 6189<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> 6190<span class="apii">[-0, +(0|1), <em>e</em>]</span> 6191<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> 6192 6193<p> 6194Calls a metamethod. 6195 6196 6197<p> 6198If the object at index <code>obj</code> has a metatable and this 6199metatable has a field <code>e</code>, 6200this function calls this field passing the object as its only argument. 6201In this case this function returns true and pushes onto the 6202stack the value returned by the call. 6203If there is no metatable or no metamethod, 6204this function returns false (without pushing any value on the stack). 6205 6206 6207 6208 6209 6210<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> 6211<span class="apii">[-0, +0, <em>v</em>]</span> 6212<pre>void luaL_checkany (lua_State *L, int arg);</pre> 6213 6214<p> 6215Checks whether the function has an argument 6216of any type (including <b>nil</b>) at position <code>arg</code>. 6217 6218 6219 6220 6221 6222<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> 6223<span class="apii">[-0, +0, <em>v</em>]</span> 6224<pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre> 6225 6226<p> 6227Checks whether the function argument <code>arg</code> is an integer 6228(or can be converted to an integer) 6229and returns this integer cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. 6230 6231 6232 6233 6234 6235<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> 6236<span class="apii">[-0, +0, <em>v</em>]</span> 6237<pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre> 6238 6239<p> 6240Checks whether the function argument <code>arg</code> is a string 6241and returns this string; 6242if <code>l</code> is not <code>NULL</code> fills <code>*l</code> 6243with the string's length. 6244 6245 6246<p> 6247This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6248so all conversions and caveats of that function apply here. 6249 6250 6251 6252 6253 6254<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> 6255<span class="apii">[-0, +0, <em>v</em>]</span> 6256<pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre> 6257 6258<p> 6259Checks whether the function argument <code>arg</code> is a number 6260and returns this number. 6261 6262 6263 6264 6265 6266<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> 6267<span class="apii">[-0, +0, <em>v</em>]</span> 6268<pre>int luaL_checkoption (lua_State *L, 6269 int arg, 6270 const char *def, 6271 const char *const lst[]);</pre> 6272 6273<p> 6274Checks whether the function argument <code>arg</code> is a string and 6275searches for this string in the array <code>lst</code> 6276(which must be NULL-terminated). 6277Returns the index in the array where the string was found. 6278Raises an error if the argument is not a string or 6279if the string cannot be found. 6280 6281 6282<p> 6283If <code>def</code> is not <code>NULL</code>, 6284the function uses <code>def</code> as a default value when 6285there is no argument <code>arg</code> or when this argument is <b>nil</b>. 6286 6287 6288<p> 6289This is a useful function for mapping strings to C enums. 6290(The usual convention in Lua libraries is 6291to use strings instead of numbers to select options.) 6292 6293 6294 6295 6296 6297<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> 6298<span class="apii">[-0, +0, <em>v</em>]</span> 6299<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> 6300 6301<p> 6302Grows the stack size to <code>top + sz</code> elements, 6303raising an error if the stack cannot grow to that size. 6304<code>msg</code> is an additional text to go into the error message 6305(or <code>NULL</code> for no additional text). 6306 6307 6308 6309 6310 6311<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> 6312<span class="apii">[-0, +0, <em>v</em>]</span> 6313<pre>const char *luaL_checkstring (lua_State *L, int arg);</pre> 6314 6315<p> 6316Checks whether the function argument <code>arg</code> is a string 6317and returns this string. 6318 6319 6320<p> 6321This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6322so all conversions and caveats of that function apply here. 6323 6324 6325 6326 6327 6328<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> 6329<span class="apii">[-0, +0, <em>v</em>]</span> 6330<pre>void luaL_checktype (lua_State *L, int arg, int t);</pre> 6331 6332<p> 6333Checks whether the function argument <code>arg</code> has type <code>t</code>. 6334See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. 6335 6336 6337 6338 6339 6340<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> 6341<span class="apii">[-0, +0, <em>v</em>]</span> 6342<pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre> 6343 6344<p> 6345Checks whether the function argument <code>arg</code> is a userdata 6346of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and 6347returns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>). 6348 6349 6350 6351 6352 6353<hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p> 6354<span class="apii">[-0, +0, <em>v</em>]</span> 6355<pre>void luaL_checkversion (lua_State *L);</pre> 6356 6357<p> 6358Checks whether the core running the call, 6359the core that created the Lua state, 6360and the code making the call are all using the same version of Lua. 6361Also checks whether the core running the call 6362and the core that created the Lua state 6363are using the same address space. 6364 6365 6366 6367 6368 6369<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> 6370<span class="apii">[-0, +?, <em>e</em>]</span> 6371<pre>int luaL_dofile (lua_State *L, const char *filename);</pre> 6372 6373<p> 6374Loads and runs the given file. 6375It is defined as the following macro: 6376 6377<pre> 6378 (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6379</pre><p> 6380It returns false if there are no errors 6381or true in case of errors. 6382 6383 6384 6385 6386 6387<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> 6388<span class="apii">[-0, +?, –]</span> 6389<pre>int luaL_dostring (lua_State *L, const char *str);</pre> 6390 6391<p> 6392Loads and runs the given string. 6393It is defined as the following macro: 6394 6395<pre> 6396 (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6397</pre><p> 6398It returns false if there are no errors 6399or true in case of errors. 6400 6401 6402 6403 6404 6405<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> 6406<span class="apii">[-0, +0, <em>v</em>]</span> 6407<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> 6408 6409<p> 6410Raises an error. 6411The error message format is given by <code>fmt</code> 6412plus any extra arguments, 6413following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. 6414It also adds at the beginning of the message the file name and 6415the line number where the error occurred, 6416if this information is available. 6417 6418 6419<p> 6420This function never returns, 6421but it is an idiom to use it in C functions 6422as <code>return luaL_error(<em>args</em>)</code>. 6423 6424 6425 6426 6427 6428<hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p> 6429<span class="apii">[-0, +3, <em>m</em>]</span> 6430<pre>int luaL_execresult (lua_State *L, int stat);</pre> 6431 6432<p> 6433This function produces the return values for 6434process-related functions in the standard library 6435(<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>). 6436 6437 6438 6439 6440 6441<hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p> 6442<span class="apii">[-0, +(1|3), <em>m</em>]</span> 6443<pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre> 6444 6445<p> 6446This function produces the return values for 6447file-related functions in the standard library 6448(<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.). 6449 6450 6451 6452 6453 6454<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> 6455<span class="apii">[-0, +(0|1), <em>m</em>]</span> 6456<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> 6457 6458<p> 6459Pushes onto the stack the field <code>e</code> from the metatable 6460of the object at index <code>obj</code> and returns the type of the pushed value. 6461If the object does not have a metatable, 6462or if the metatable does not have this field, 6463pushes nothing and returns <code>LUA_TNIL</code>. 6464 6465 6466 6467 6468 6469<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> 6470<span class="apii">[-0, +1, <em>m</em>]</span> 6471<pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre> 6472 6473<p> 6474Pushes onto the stack the metatable associated with name <code>tname</code> 6475in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) 6476(<b>nil</b> if there is no metatable associated with that name). 6477Returns the type of the pushed value. 6478 6479 6480 6481 6482 6483<hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p> 6484<span class="apii">[-0, +1, <em>e</em>]</span> 6485<pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre> 6486 6487<p> 6488Ensures that the value <code>t[fname]</code>, 6489where <code>t</code> is the value at index <code>idx</code>, 6490is a table, 6491and pushes that table onto the stack. 6492Returns true if it finds a previous table there 6493and false if it creates a new table. 6494 6495 6496 6497 6498 6499<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> 6500<span class="apii">[-0, +1, <em>m</em>]</span> 6501<pre>const char *luaL_gsub (lua_State *L, 6502 const char *s, 6503 const char *p, 6504 const char *r);</pre> 6505 6506<p> 6507Creates a copy of string <code>s</code> by replacing 6508any occurrence of the string <code>p</code> 6509with the string <code>r</code>. 6510Pushes the resulting string on the stack and returns it. 6511 6512 6513 6514 6515 6516<hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p> 6517<span class="apii">[-0, +0, <em>e</em>]</span> 6518<pre>lua_Integer luaL_len (lua_State *L, int index);</pre> 6519 6520<p> 6521Returns the "length" of the value at the given index 6522as a number; 6523it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). 6524Raises an error if the result of the operation is not an integer. 6525(This case only can happen through metamethods.) 6526 6527 6528 6529 6530 6531<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> 6532<span class="apii">[-0, +1, –]</span> 6533<pre>int luaL_loadbuffer (lua_State *L, 6534 const char *buff, 6535 size_t sz, 6536 const char *name);</pre> 6537 6538<p> 6539Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>. 6540 6541 6542 6543 6544 6545<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p> 6546<span class="apii">[-0, +1, –]</span> 6547<pre>int luaL_loadbufferx (lua_State *L, 6548 const char *buff, 6549 size_t sz, 6550 const char *name, 6551 const char *mode);</pre> 6552 6553<p> 6554Loads a buffer as a Lua chunk. 6555This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the 6556buffer pointed to by <code>buff</code> with size <code>sz</code>. 6557 6558 6559<p> 6560This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 6561<code>name</code> is the chunk name, 6562used for debug information and error messages. 6563The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. 6564 6565 6566 6567 6568 6569<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> 6570<span class="apii">[-0, +1, <em>m</em>]</span> 6571<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> 6572 6573<p> 6574Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>. 6575 6576 6577 6578 6579 6580<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p> 6581<span class="apii">[-0, +1, <em>m</em>]</span> 6582<pre>int luaL_loadfilex (lua_State *L, const char *filename, 6583 const char *mode);</pre> 6584 6585<p> 6586Loads a file as a Lua chunk. 6587This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file 6588named <code>filename</code>. 6589If <code>filename</code> is <code>NULL</code>, 6590then it loads from the standard input. 6591The first line in the file is ignored if it starts with a <code>#</code>. 6592 6593 6594<p> 6595The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. 6596 6597 6598<p> 6599This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, 6600but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> 6601for file-related errors 6602(e.g., it cannot open or read the file). 6603 6604 6605<p> 6606As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 6607it does not run it. 6608 6609 6610 6611 6612 6613<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> 6614<span class="apii">[-0, +1, –]</span> 6615<pre>int luaL_loadstring (lua_State *L, const char *s);</pre> 6616 6617<p> 6618Loads a string as a Lua chunk. 6619This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in 6620the zero-terminated string <code>s</code>. 6621 6622 6623<p> 6624This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 6625 6626 6627<p> 6628Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 6629it does not run it. 6630 6631 6632 6633 6634 6635<hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p> 6636<span class="apii">[-0, +1, <em>m</em>]</span> 6637<pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre> 6638 6639<p> 6640Creates a new table and registers there 6641the functions in list <code>l</code>. 6642 6643 6644<p> 6645It is implemented as the following macro: 6646 6647<pre> 6648 (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0)) 6649</pre><p> 6650The array <code>l</code> must be the actual array, 6651not a pointer to it. 6652 6653 6654 6655 6656 6657<hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p> 6658<span class="apii">[-0, +1, <em>m</em>]</span> 6659<pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre> 6660 6661<p> 6662Creates a new table with a size optimized 6663to store all entries in the array <code>l</code> 6664(but does not actually store them). 6665It is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> 6666(see <a href="#luaL_newlib"><code>luaL_newlib</code></a>). 6667 6668 6669<p> 6670It is implemented as a macro. 6671The array <code>l</code> must be the actual array, 6672not a pointer to it. 6673 6674 6675 6676 6677 6678<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> 6679<span class="apii">[-0, +1, <em>m</em>]</span> 6680<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> 6681 6682<p> 6683If the registry already has the key <code>tname</code>, 6684returns 0. 6685Otherwise, 6686creates a new table to be used as a metatable for userdata, 6687adds to this new table the pair <code>__name = tname</code>, 6688adds to the registry the pair <code>[tname] = new table</code>, 6689and returns 1. 6690(The entry <code>__name</code> is used by some error-reporting functions.) 6691 6692 6693<p> 6694In both cases pushes onto the stack the final value associated 6695with <code>tname</code> in the registry. 6696 6697 6698 6699 6700 6701<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> 6702<span class="apii">[-0, +0, –]</span> 6703<pre>lua_State *luaL_newstate (void);</pre> 6704 6705<p> 6706Creates a new Lua state. 6707It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an 6708allocator based on the standard C <code>realloc</code> function 6709and then sets a panic function (see <a href="#4.6">§4.6</a>) that prints 6710an error message to the standard error output in case of fatal 6711errors. 6712 6713 6714<p> 6715Returns the new state, 6716or <code>NULL</code> if there is a memory allocation error. 6717 6718 6719 6720 6721 6722<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> 6723<span class="apii">[-0, +0, <em>e</em>]</span> 6724<pre>void luaL_openlibs (lua_State *L);</pre> 6725 6726<p> 6727Opens all standard Lua libraries into the given state. 6728 6729 6730 6731 6732 6733<hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p> 6734<span class="apii">[-0, +0, <em>e</em>]</span> 6735<pre>T luaL_opt (L, func, arg, dflt);</pre> 6736 6737<p> 6738This macro is defined as follows: 6739 6740<pre> 6741 (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg))) 6742</pre><p> 6743In words, if the argument <code>arg</code> is nil or absent, 6744the macro results in the default <code>dflt</code>. 6745Otherwise, it results in the result of calling <code>func</code> 6746with the state <code>L</code> and the argument index <code>arg</code> as 6747arguments. 6748Note that it evaluates the expression <code>dflt</code> only if needed. 6749 6750 6751 6752 6753 6754<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> 6755<span class="apii">[-0, +0, <em>v</em>]</span> 6756<pre>lua_Integer luaL_optinteger (lua_State *L, 6757 int arg, 6758 lua_Integer d);</pre> 6759 6760<p> 6761If the function argument <code>arg</code> is an integer 6762(or convertible to an integer), 6763returns this integer. 6764If this argument is absent or is <b>nil</b>, 6765returns <code>d</code>. 6766Otherwise, raises an error. 6767 6768 6769 6770 6771 6772<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> 6773<span class="apii">[-0, +0, <em>v</em>]</span> 6774<pre>const char *luaL_optlstring (lua_State *L, 6775 int arg, 6776 const char *d, 6777 size_t *l);</pre> 6778 6779<p> 6780If the function argument <code>arg</code> is a string, 6781returns this string. 6782If this argument is absent or is <b>nil</b>, 6783returns <code>d</code>. 6784Otherwise, raises an error. 6785 6786 6787<p> 6788If <code>l</code> is not <code>NULL</code>, 6789fills the position <code>*l</code> with the result's length. 6790If the result is <code>NULL</code> 6791(only possible when returning <code>d</code> and <code>d == NULL</code>), 6792its length is considered zero. 6793 6794 6795<p> 6796This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6797so all conversions and caveats of that function apply here. 6798 6799 6800 6801 6802 6803<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> 6804<span class="apii">[-0, +0, <em>v</em>]</span> 6805<pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre> 6806 6807<p> 6808If the function argument <code>arg</code> is a number, 6809returns this number. 6810If this argument is absent or is <b>nil</b>, 6811returns <code>d</code>. 6812Otherwise, raises an error. 6813 6814 6815 6816 6817 6818<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> 6819<span class="apii">[-0, +0, <em>v</em>]</span> 6820<pre>const char *luaL_optstring (lua_State *L, 6821 int arg, 6822 const char *d);</pre> 6823 6824<p> 6825If the function argument <code>arg</code> is a string, 6826returns this string. 6827If this argument is absent or is <b>nil</b>, 6828returns <code>d</code>. 6829Otherwise, raises an error. 6830 6831 6832 6833 6834 6835<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> 6836<span class="apii">[-?, +?, <em>m</em>]</span> 6837<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> 6838 6839<p> 6840Equivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a> 6841with the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>. 6842 6843 6844 6845 6846 6847<hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p> 6848<span class="apii">[-?, +?, <em>m</em>]</span> 6849<pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre> 6850 6851<p> 6852Returns an address to a space of size <code>sz</code> 6853where you can copy a string to be added to buffer <code>B</code> 6854(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6855After copying the string into this space you must call 6856<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add 6857it to the buffer. 6858 6859 6860 6861 6862 6863<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> 6864<span class="apii">[-?, +1, <em>m</em>]</span> 6865<pre>void luaL_pushresult (luaL_Buffer *B);</pre> 6866 6867<p> 6868Finishes the use of buffer <code>B</code> leaving the final string on 6869the top of the stack. 6870 6871 6872 6873 6874 6875<hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p> 6876<span class="apii">[-?, +1, <em>m</em>]</span> 6877<pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre> 6878 6879<p> 6880Equivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>. 6881 6882 6883 6884 6885 6886<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> 6887<span class="apii">[-1, +0, <em>m</em>]</span> 6888<pre>int luaL_ref (lua_State *L, int t);</pre> 6889 6890<p> 6891Creates and returns a <em>reference</em>, 6892in the table at index <code>t</code>, 6893for the object at the top of the stack (and pops the object). 6894 6895 6896<p> 6897A reference is a unique integer key. 6898As long as you do not manually add integer keys into table <code>t</code>, 6899<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. 6900You can retrieve an object referred by reference <code>r</code> 6901by calling <code>lua_rawgeti(L, t, r)</code>. 6902Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object. 6903 6904 6905<p> 6906If the object at the top of the stack is <b>nil</b>, 6907<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>. 6908The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different 6909from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. 6910 6911 6912 6913 6914 6915<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> 6916<pre>typedef struct luaL_Reg { 6917 const char *name; 6918 lua_CFunction func; 6919} luaL_Reg;</pre> 6920 6921<p> 6922Type for arrays of functions to be registered by 6923<a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>. 6924<code>name</code> is the function name and <code>func</code> is a pointer to 6925the function. 6926Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry 6927in which both <code>name</code> and <code>func</code> are <code>NULL</code>. 6928 6929 6930 6931 6932 6933<hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p> 6934<span class="apii">[-0, +1, <em>e</em>]</span> 6935<pre>void luaL_requiref (lua_State *L, const char *modname, 6936 lua_CFunction openf, int glb);</pre> 6937 6938<p> 6939If <code>modname</code> is not already present in <a href="#pdf-package.loaded"><code>package.loaded</code></a>, 6940calls function <code>openf</code> with string <code>modname</code> as an argument 6941and sets the call result in <code>package.loaded[modname]</code>, 6942as if that function has been called through <a href="#pdf-require"><code>require</code></a>. 6943 6944 6945<p> 6946If <code>glb</code> is true, 6947also stores the module into global <code>modname</code>. 6948 6949 6950<p> 6951Leaves a copy of the module on the stack. 6952 6953 6954 6955 6956 6957<hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p> 6958<span class="apii">[-nup, +0, <em>m</em>]</span> 6959<pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre> 6960 6961<p> 6962Registers all functions in the array <code>l</code> 6963(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack 6964(below optional upvalues, see next). 6965 6966 6967<p> 6968When <code>nup</code> is not zero, 6969all functions are created sharing <code>nup</code> upvalues, 6970which must be previously pushed on the stack 6971on top of the library table. 6972These values are popped from the stack after the registration. 6973 6974 6975 6976 6977 6978<hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p> 6979<span class="apii">[-0, +0, –]</span> 6980<pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre> 6981 6982<p> 6983Sets the metatable of the object at the top of the stack 6984as the metatable associated with name <code>tname</code> 6985in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 6986 6987 6988 6989 6990 6991<hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3> 6992<pre>typedef struct luaL_Stream { 6993 FILE *f; 6994 lua_CFunction closef; 6995} luaL_Stream;</pre> 6996 6997<p> 6998The standard representation for file handles, 6999which is used by the standard I/O library. 7000 7001 7002<p> 7003A file handle is implemented as a full userdata, 7004with a metatable called <code>LUA_FILEHANDLE</code> 7005(where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name). 7006The metatable is created by the I/O library 7007(see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 7008 7009 7010<p> 7011This userdata must start with the structure <code>luaL_Stream</code>; 7012it can contain other data after this initial structure. 7013Field <code>f</code> points to the corresponding C stream 7014(or it can be <code>NULL</code> to indicate an incompletely created handle). 7015Field <code>closef</code> points to a Lua function 7016that will be called to close the stream 7017when the handle is closed or collected; 7018this function receives the file handle as its sole argument and 7019must return either <b>true</b> (in case of success) 7020or <b>nil</b> plus an error message (in case of error). 7021Once Lua calls this field, 7022it changes the field value to <code>NULL</code> 7023to signal that the handle is closed. 7024 7025 7026 7027 7028 7029<hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p> 7030<span class="apii">[-0, +0, <em>m</em>]</span> 7031<pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre> 7032 7033<p> 7034This function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>, 7035except that, when the test fails, 7036it returns <code>NULL</code> instead of raising an error. 7037 7038 7039 7040 7041 7042<hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p> 7043<span class="apii">[-0, +1, <em>e</em>]</span> 7044<pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre> 7045 7046<p> 7047Converts any Lua value at the given index to a C string 7048in a reasonable format. 7049The resulting string is pushed onto the stack and also 7050returned by the function. 7051If <code>len</code> is not <code>NULL</code>, 7052the function also sets <code>*len</code> with the string length. 7053 7054 7055<p> 7056If the value has a metatable with a <code>__tostring</code> field, 7057then <code>luaL_tolstring</code> calls the corresponding metamethod 7058with the value as argument, 7059and uses the result of the call as its result. 7060 7061 7062 7063 7064 7065<hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p> 7066<span class="apii">[-0, +1, <em>m</em>]</span> 7067<pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, 7068 int level);</pre> 7069 7070<p> 7071Creates and pushes a traceback of the stack <code>L1</code>. 7072If <code>msg</code> is not <code>NULL</code> it is appended 7073at the beginning of the traceback. 7074The <code>level</code> parameter tells at which level 7075to start the traceback. 7076 7077 7078 7079 7080 7081<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> 7082<span class="apii">[-0, +0, –]</span> 7083<pre>const char *luaL_typename (lua_State *L, int index);</pre> 7084 7085<p> 7086Returns the name of the type of the value at the given index. 7087 7088 7089 7090 7091 7092<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> 7093<span class="apii">[-0, +0, –]</span> 7094<pre>void luaL_unref (lua_State *L, int t, int ref);</pre> 7095 7096<p> 7097Releases reference <code>ref</code> from the table at index <code>t</code> 7098(see <a href="#luaL_ref"><code>luaL_ref</code></a>). 7099The entry is removed from the table, 7100so that the referred object can be collected. 7101The reference <code>ref</code> is also freed to be used again. 7102 7103 7104<p> 7105If <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>, 7106<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. 7107 7108 7109 7110 7111 7112<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> 7113<span class="apii">[-0, +1, <em>m</em>]</span> 7114<pre>void luaL_where (lua_State *L, int lvl);</pre> 7115 7116<p> 7117Pushes onto the stack a string identifying the current position 7118of the control at level <code>lvl</code> in the call stack. 7119Typically this string has the following format: 7120 7121<pre> 7122 <em>chunkname</em>:<em>currentline</em>: 7123</pre><p> 7124Level 0 is the running function, 7125level 1 is the function that called the running function, 7126etc. 7127 7128 7129<p> 7130This function is used to build a prefix for error messages. 7131 7132 7133 7134 7135 7136 7137 7138<h1>6 – <a name="6">Standard Libraries</a></h1> 7139 7140<p> 7141The standard Lua libraries provide useful functions 7142that are implemented directly through the C API. 7143Some of these functions provide essential services to the language 7144(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); 7145others provide access to "outside" services (e.g., I/O); 7146and others could be implemented in Lua itself, 7147but are quite useful or have critical performance requirements that 7148deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). 7149 7150 7151<p> 7152All libraries are implemented through the official C API 7153and are provided as separate C modules. 7154Currently, Lua has the following standard libraries: 7155 7156<ul> 7157 7158<li>basic library (<a href="#6.1">§6.1</a>);</li> 7159 7160<li>coroutine library (<a href="#6.2">§6.2</a>);</li> 7161 7162<li>package library (<a href="#6.3">§6.3</a>);</li> 7163 7164<li>string manipulation (<a href="#6.4">§6.4</a>);</li> 7165 7166<li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li> 7167 7168<li>table manipulation (<a href="#6.6">§6.6</a>);</li> 7169 7170<li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li> 7171 7172<li>input and output (<a href="#6.8">§6.8</a>);</li> 7173 7174<li>operating system facilities (<a href="#6.9">§6.9</a>);</li> 7175 7176<li>debug facilities (<a href="#6.10">§6.10</a>).</li> 7177 7178</ul><p> 7179Except for the basic and the package libraries, 7180each library provides all its functions as fields of a global table 7181or as methods of its objects. 7182 7183 7184<p> 7185To have access to these libraries, 7186the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, 7187which opens all standard libraries. 7188Alternatively, 7189the host program can open them individually by using 7190<a href="#luaL_requiref"><code>luaL_requiref</code></a> to call 7191<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), 7192<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), 7193<a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library), 7194<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), 7195<a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF8 library), 7196<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), 7197<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), 7198<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), 7199<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library), 7200and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). 7201These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>. 7202 7203 7204 7205<h2>6.1 – <a name="6.1">Basic Functions</a></h2> 7206 7207<p> 7208The basic library provides core functions to Lua. 7209If you do not include this library in your application, 7210you should check carefully whether you need to provide 7211implementations for some of its facilities. 7212 7213 7214<p> 7215<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> 7216 7217 7218<p> 7219Calls <a href="#pdf-error"><code>error</code></a> if 7220the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); 7221otherwise, returns all its arguments. 7222In case of error, 7223<code>message</code> is the error object; 7224when absent, it defaults to "<code>assertion failed!</code>" 7225 7226 7227 7228 7229<p> 7230<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3> 7231 7232 7233<p> 7234This function is a generic interface to the garbage collector. 7235It performs different functions according to its first argument, <code>opt</code>: 7236 7237<ul> 7238 7239<li><b>"<code>collect</code>": </b> 7240performs a full garbage-collection cycle. 7241This is the default option. 7242</li> 7243 7244<li><b>"<code>stop</code>": </b> 7245stops automatic execution of the garbage collector. 7246The collector will run only when explicitly invoked, 7247until a call to restart it. 7248</li> 7249 7250<li><b>"<code>restart</code>": </b> 7251restarts automatic execution of the garbage collector. 7252</li> 7253 7254<li><b>"<code>count</code>": </b> 7255returns the total memory in use by Lua in Kbytes. 7256The value has a fractional part, 7257so that it multiplied by 1024 7258gives the exact number of bytes in use by Lua 7259(except for overflows). 7260</li> 7261 7262<li><b>"<code>step</code>": </b> 7263performs a garbage-collection step. 7264The step "size" is controlled by <code>arg</code>. 7265With a zero value, 7266the collector will perform one basic (indivisible) step. 7267For non-zero values, 7268the collector will perform as if that amount of memory 7269(in KBytes) had been allocated by Lua. 7270Returns <b>true</b> if the step finished a collection cycle. 7271</li> 7272 7273<li><b>"<code>setpause</code>": </b> 7274sets <code>arg</code> as the new value for the <em>pause</em> of 7275the collector (see <a href="#2.5">§2.5</a>). 7276Returns the previous value for <em>pause</em>. 7277</li> 7278 7279<li><b>"<code>setstepmul</code>": </b> 7280sets <code>arg</code> as the new value for the <em>step multiplier</em> of 7281the collector (see <a href="#2.5">§2.5</a>). 7282Returns the previous value for <em>step</em>. 7283</li> 7284 7285<li><b>"<code>isrunning</code>": </b> 7286returns a boolean that tells whether the collector is running 7287(i.e., not stopped). 7288</li> 7289 7290</ul> 7291 7292 7293 7294<p> 7295<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> 7296Opens the named file and executes its contents as a Lua chunk. 7297When called without arguments, 7298<code>dofile</code> executes the contents of the standard input (<code>stdin</code>). 7299Returns all values returned by the chunk. 7300In case of errors, <code>dofile</code> propagates the error 7301to its caller (that is, <code>dofile</code> does not run in protected mode). 7302 7303 7304 7305 7306<p> 7307<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> 7308Terminates the last protected function called 7309and returns <code>message</code> as the error object. 7310Function <code>error</code> never returns. 7311 7312 7313<p> 7314Usually, <code>error</code> adds some information about the error position 7315at the beginning of the message, if the message is a string. 7316The <code>level</code> argument specifies how to get the error position. 7317With level 1 (the default), the error position is where the 7318<code>error</code> function was called. 7319Level 2 points the error to where the function 7320that called <code>error</code> was called; and so on. 7321Passing a level 0 avoids the addition of error position information 7322to the message. 7323 7324 7325 7326 7327<p> 7328<hr><h3><a name="pdf-_G"><code>_G</code></a></h3> 7329A global variable (not a function) that 7330holds the global environment (see <a href="#2.2">§2.2</a>). 7331Lua itself does not use this variable; 7332changing its value does not affect any environment, 7333nor vice versa. 7334 7335 7336 7337 7338<p> 7339<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> 7340 7341 7342<p> 7343If <code>object</code> does not have a metatable, returns <b>nil</b>. 7344Otherwise, 7345if the object's metatable has a <code>__metatable</code> field, 7346returns the associated value. 7347Otherwise, returns the metatable of the given object. 7348 7349 7350 7351 7352<p> 7353<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> 7354 7355 7356<p> 7357Returns three values (an iterator function, the table <code>t</code>, and 0) 7358so that the construction 7359 7360<pre> 7361 for i,v in ipairs(t) do <em>body</em> end 7362</pre><p> 7363will iterate over the key–value pairs 7364(<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., 7365up to the first nil value. 7366 7367 7368 7369 7370<p> 7371<hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3> 7372 7373 7374<p> 7375Loads a chunk. 7376 7377 7378<p> 7379If <code>chunk</code> is a string, the chunk is this string. 7380If <code>chunk</code> is a function, 7381<code>load</code> calls it repeatedly to get the chunk pieces. 7382Each call to <code>chunk</code> must return a string that concatenates 7383with previous results. 7384A return of an empty string, <b>nil</b>, or no value signals the end of the chunk. 7385 7386 7387<p> 7388If there are no syntactic errors, 7389returns the compiled chunk as a function; 7390otherwise, returns <b>nil</b> plus the error message. 7391 7392 7393<p> 7394If the resulting function has upvalues, 7395the first upvalue is set to the value of <code>env</code>, 7396if that parameter is given, 7397or to the value of the global environment. 7398Other upvalues are initialized with <b>nil</b>. 7399(When you load a main chunk, 7400the resulting function will always have exactly one upvalue, 7401the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 7402However, 7403when you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>), 7404the resulting function can have an arbitrary number of upvalues.) 7405All upvalues are fresh, that is, 7406they are not shared with any other function. 7407 7408 7409<p> 7410<code>chunkname</code> is used as the name of the chunk for error messages 7411and debug information (see <a href="#4.9">§4.9</a>). 7412When absent, 7413it defaults to <code>chunk</code>, if <code>chunk</code> is a string, 7414or to "<code>=(load)</code>" otherwise. 7415 7416 7417<p> 7418The string <code>mode</code> controls whether the chunk can be text or binary 7419(that is, a precompiled chunk). 7420It may be the string "<code>b</code>" (only binary chunks), 7421"<code>t</code>" (only text chunks), 7422or "<code>bt</code>" (both binary and text). 7423The default is "<code>bt</code>". 7424 7425 7426<p> 7427Lua does not check the consistency of binary chunks. 7428Maliciously crafted binary chunks can crash 7429the interpreter. 7430 7431 7432 7433 7434<p> 7435<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3> 7436 7437 7438<p> 7439Similar to <a href="#pdf-load"><code>load</code></a>, 7440but gets the chunk from file <code>filename</code> 7441or from the standard input, 7442if no file name is given. 7443 7444 7445 7446 7447<p> 7448<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> 7449 7450 7451<p> 7452Allows a program to traverse all fields of a table. 7453Its first argument is a table and its second argument 7454is an index in this table. 7455<code>next</code> returns the next index of the table 7456and its associated value. 7457When called with <b>nil</b> as its second argument, 7458<code>next</code> returns an initial index 7459and its associated value. 7460When called with the last index, 7461or with <b>nil</b> in an empty table, 7462<code>next</code> returns <b>nil</b>. 7463If the second argument is absent, then it is interpreted as <b>nil</b>. 7464In particular, 7465you can use <code>next(t)</code> to check whether a table is empty. 7466 7467 7468<p> 7469The order in which the indices are enumerated is not specified, 7470<em>even for numeric indices</em>. 7471(To traverse a table in numerical order, 7472use a numerical <b>for</b>.) 7473 7474 7475<p> 7476The behavior of <code>next</code> is undefined if, 7477during the traversal, 7478you assign any value to a non-existent field in the table. 7479You may however modify existing fields. 7480In particular, you may clear existing fields. 7481 7482 7483 7484 7485<p> 7486<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> 7487 7488 7489<p> 7490If <code>t</code> has a metamethod <code>__pairs</code>, 7491calls it with <code>t</code> as argument and returns the first three 7492results from the call. 7493 7494 7495<p> 7496Otherwise, 7497returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, 7498so that the construction 7499 7500<pre> 7501 for k,v in pairs(t) do <em>body</em> end 7502</pre><p> 7503will iterate over all key–value pairs of table <code>t</code>. 7504 7505 7506<p> 7507See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 7508the table during its traversal. 7509 7510 7511 7512 7513<p> 7514<hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3> 7515 7516 7517<p> 7518Calls function <code>f</code> with 7519the given arguments in <em>protected mode</em>. 7520This means that any error inside <code>f</code> is not propagated; 7521instead, <code>pcall</code> catches the error 7522and returns a status code. 7523Its first result is the status code (a boolean), 7524which is true if the call succeeds without errors. 7525In such case, <code>pcall</code> also returns all results from the call, 7526after this first result. 7527In case of any error, <code>pcall</code> returns <b>false</b> plus the error message. 7528 7529 7530 7531 7532<p> 7533<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> 7534Receives any number of arguments 7535and prints their values to <code>stdout</code>, 7536using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string. 7537<code>print</code> is not intended for formatted output, 7538but only as a quick way to show a value, 7539for instance for debugging. 7540For complete control over the output, 7541use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. 7542 7543 7544 7545 7546<p> 7547<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> 7548Checks whether <code>v1</code> is equal to <code>v2</code>, 7549without invoking the <code>__eq</code> metamethod. 7550Returns a boolean. 7551 7552 7553 7554 7555<p> 7556<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> 7557Gets the real value of <code>table[index]</code>, 7558without invoking the <code>__index</code> metamethod. 7559<code>table</code> must be a table; 7560<code>index</code> may be any value. 7561 7562 7563 7564 7565<p> 7566<hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3> 7567Returns the length of the object <code>v</code>, 7568which must be a table or a string, 7569without invoking the <code>__len</code> metamethod. 7570Returns an integer. 7571 7572 7573 7574 7575<p> 7576<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> 7577Sets the real value of <code>table[index]</code> to <code>value</code>, 7578without invoking the <code>__newindex</code> metamethod. 7579<code>table</code> must be a table, 7580<code>index</code> any value different from <b>nil</b> and NaN, 7581and <code>value</code> any Lua value. 7582 7583 7584<p> 7585This function returns <code>table</code>. 7586 7587 7588 7589 7590<p> 7591<hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> 7592 7593 7594<p> 7595If <code>index</code> is a number, 7596returns all arguments after argument number <code>index</code>; 7597a negative number indexes from the end (-1 is the last argument). 7598Otherwise, <code>index</code> must be the string <code>"#"</code>, 7599and <code>select</code> returns the total number of extra arguments it received. 7600 7601 7602 7603 7604<p> 7605<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> 7606 7607 7608<p> 7609Sets the metatable for the given table. 7610(To change the metatable of other types from Lua code, 7611you must use the debug library (<a href="#6.10">§6.10</a>).) 7612If <code>metatable</code> is <b>nil</b>, 7613removes the metatable of the given table. 7614If the original metatable has a <code>__metatable</code> field, 7615raises an error. 7616 7617 7618<p> 7619This function returns <code>table</code>. 7620 7621 7622 7623 7624<p> 7625<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> 7626 7627 7628<p> 7629When called with no <code>base</code>, 7630<code>tonumber</code> tries to convert its argument to a number. 7631If the argument is already a number or 7632a string convertible to a number, 7633then <code>tonumber</code> returns this number; 7634otherwise, it returns <b>nil</b>. 7635 7636 7637<p> 7638The conversion of strings can result in integers or floats, 7639according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 7640(The string may have leading and trailing spaces and a sign.) 7641 7642 7643<p> 7644When called with <code>base</code>, 7645then <code>e</code> must be a string to be interpreted as 7646an integer numeral in that base. 7647The base may be any integer between 2 and 36, inclusive. 7648In bases above 10, the letter '<code>A</code>' (in either upper or lower case) 7649represents 10, '<code>B</code>' represents 11, and so forth, 7650with '<code>Z</code>' representing 35. 7651If the string <code>e</code> is not a valid numeral in the given base, 7652the function returns <b>nil</b>. 7653 7654 7655 7656 7657<p> 7658<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3> 7659Receives a value of any type and 7660converts it to a string in a human-readable format. 7661(For complete control of how numbers are converted, 7662use <a href="#pdf-string.format"><code>string.format</code></a>.) 7663 7664 7665<p> 7666If the metatable of <code>v</code> has a <code>__tostring</code> field, 7667then <code>tostring</code> calls the corresponding value 7668with <code>v</code> as argument, 7669and uses the result of the call as its result. 7670 7671 7672 7673 7674<p> 7675<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> 7676Returns the type of its only argument, coded as a string. 7677The possible results of this function are 7678"<code>nil</code>" (a string, not the value <b>nil</b>), 7679"<code>number</code>", 7680"<code>string</code>", 7681"<code>boolean</code>", 7682"<code>table</code>", 7683"<code>function</code>", 7684"<code>thread</code>", 7685and "<code>userdata</code>". 7686 7687 7688 7689 7690<p> 7691<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> 7692 7693 7694<p> 7695A global variable (not a function) that 7696holds a string containing the running Lua version. 7697The current value of this variable is "<code>Lua 5.3</code>". 7698 7699 7700 7701 7702<p> 7703<hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3> 7704 7705 7706<p> 7707This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, 7708except that it sets a new message handler <code>msgh</code>. 7709 7710 7711 7712 7713 7714 7715 7716<h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2> 7717 7718<p> 7719This library comprises the operations to manipulate coroutines, 7720which come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. 7721See <a href="#2.6">§2.6</a> for a general description of coroutines. 7722 7723 7724<p> 7725<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> 7726 7727 7728<p> 7729Creates a new coroutine, with body <code>f</code>. 7730<code>f</code> must be a function. 7731Returns this new coroutine, 7732an object with type <code>"thread"</code>. 7733 7734 7735 7736 7737<p> 7738<hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ()</code></a></h3> 7739 7740 7741<p> 7742Returns true when the running coroutine can yield. 7743 7744 7745<p> 7746A running coroutine is yieldable if it is not the main thread and 7747it is not inside a non-yieldable C function. 7748 7749 7750 7751 7752<p> 7753<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> 7754 7755 7756<p> 7757Starts or continues the execution of coroutine <code>co</code>. 7758The first time you resume a coroutine, 7759it starts running its body. 7760The values <code>val1</code>, ... are passed 7761as the arguments to the body function. 7762If the coroutine has yielded, 7763<code>resume</code> restarts it; 7764the values <code>val1</code>, ... are passed 7765as the results from the yield. 7766 7767 7768<p> 7769If the coroutine runs without any errors, 7770<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> 7771(when the coroutine yields) or any values returned by the body function 7772(when the coroutine terminates). 7773If there is any error, 7774<code>resume</code> returns <b>false</b> plus the error message. 7775 7776 7777 7778 7779<p> 7780<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> 7781 7782 7783<p> 7784Returns the running coroutine plus a boolean, 7785true when the running coroutine is the main one. 7786 7787 7788 7789 7790<p> 7791<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> 7792 7793 7794<p> 7795Returns the status of coroutine <code>co</code>, as a string: 7796<code>"running"</code>, 7797if the coroutine is running (that is, it called <code>status</code>); 7798<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, 7799or if it has not started running yet; 7800<code>"normal"</code> if the coroutine is active but not running 7801(that is, it has resumed another coroutine); 7802and <code>"dead"</code> if the coroutine has finished its body function, 7803or if it has stopped with an error. 7804 7805 7806 7807 7808<p> 7809<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> 7810 7811 7812<p> 7813Creates a new coroutine, with body <code>f</code>. 7814<code>f</code> must be a function. 7815Returns a function that resumes the coroutine each time it is called. 7816Any arguments passed to the function behave as the 7817extra arguments to <code>resume</code>. 7818Returns the same values returned by <code>resume</code>, 7819except the first boolean. 7820In case of error, propagates the error. 7821 7822 7823 7824 7825<p> 7826<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> 7827 7828 7829<p> 7830Suspends the execution of the calling coroutine. 7831Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>. 7832 7833 7834 7835 7836 7837 7838 7839<h2>6.3 – <a name="6.3">Modules</a></h2> 7840 7841<p> 7842The package library provides basic 7843facilities for loading modules in Lua. 7844It exports one function directly in the global environment: 7845<a href="#pdf-require"><code>require</code></a>. 7846Everything else is exported in a table <a name="pdf-package"><code>package</code></a>. 7847 7848 7849<p> 7850<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> 7851 7852 7853<p> 7854Loads the given module. 7855The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table 7856to determine whether <code>modname</code> is already loaded. 7857If it is, then <code>require</code> returns the value stored 7858at <code>package.loaded[modname]</code>. 7859Otherwise, it tries to find a <em>loader</em> for the module. 7860 7861 7862<p> 7863To find a loader, 7864<code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence. 7865By changing this sequence, 7866we can change how <code>require</code> looks for a module. 7867The following explanation is based on the default configuration 7868for <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 7869 7870 7871<p> 7872First <code>require</code> queries <code>package.preload[modname]</code>. 7873If it has a value, 7874this value (which must be a function) is the loader. 7875Otherwise <code>require</code> searches for a Lua loader using the 7876path stored in <a href="#pdf-package.path"><code>package.path</code></a>. 7877If that also fails, it searches for a C loader using the 7878path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 7879If that also fails, 7880it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>). 7881 7882 7883<p> 7884Once a loader is found, 7885<code>require</code> calls the loader with two arguments: 7886<code>modname</code> and an extra value dependent on how it got the loader. 7887(If the loader came from a file, 7888this extra value is the file name.) 7889If the loader returns any non-nil value, 7890<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. 7891If the loader does not return a non-nil value and 7892has not assigned any value to <code>package.loaded[modname]</code>, 7893then <code>require</code> assigns <b>true</b> to this entry. 7894In any case, <code>require</code> returns the 7895final value of <code>package.loaded[modname]</code>. 7896 7897 7898<p> 7899If there is any error loading or running the module, 7900or if it cannot find any loader for the module, 7901then <code>require</code> raises an error. 7902 7903 7904 7905 7906<p> 7907<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3> 7908 7909 7910<p> 7911A string describing some compile-time configurations for packages. 7912This string is a sequence of lines: 7913 7914<ul> 7915 7916<li>The first line is the directory separator string. 7917Default is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li> 7918 7919<li>The second line is the character that separates templates in a path. 7920Default is '<code>;</code>'.</li> 7921 7922<li>The third line is the string that marks the 7923substitution points in a template. 7924Default is '<code>?</code>'.</li> 7925 7926<li>The fourth line is a string that, in a path in Windows, 7927is replaced by the executable's directory. 7928Default is '<code>!</code>'.</li> 7929 7930<li>The fifth line is a mark to ignore all text after it 7931when building the <code>luaopen_</code> function name. 7932Default is '<code>-</code>'.</li> 7933 7934</ul> 7935 7936 7937 7938<p> 7939<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> 7940 7941 7942<p> 7943The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. 7944 7945 7946<p> 7947Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way 7948it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, 7949using the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>, 7950or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>, 7951or a default path defined in <code>luaconf.h</code>. 7952 7953 7954 7955 7956<p> 7957<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> 7958 7959 7960<p> 7961A table used by <a href="#pdf-require"><code>require</code></a> to control which 7962modules are already loaded. 7963When you require a module <code>modname</code> and 7964<code>package.loaded[modname]</code> is not false, 7965<a href="#pdf-require"><code>require</code></a> simply returns the value stored there. 7966 7967 7968<p> 7969This variable is only a reference to the real table; 7970assignments to this variable do not change the 7971table used by <a href="#pdf-require"><code>require</code></a>. 7972 7973 7974 7975 7976<p> 7977<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> 7978 7979 7980<p> 7981Dynamically links the host program with the C library <code>libname</code>. 7982 7983 7984<p> 7985If <code>funcname</code> is "<code>*</code>", 7986then it only links with the library, 7987making the symbols exported by the library 7988available to other dynamically linked libraries. 7989Otherwise, 7990it looks for a function <code>funcname</code> inside the library 7991and returns this function as a C function. 7992So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype 7993(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 7994 7995 7996<p> 7997This is a low-level function. 7998It completely bypasses the package and module system. 7999Unlike <a href="#pdf-require"><code>require</code></a>, 8000it does not perform any path searching and 8001does not automatically adds extensions. 8002<code>libname</code> must be the complete file name of the C library, 8003including if necessary a path and an extension. 8004<code>funcname</code> must be the exact name exported by the C library 8005(which may depend on the C compiler and linker used). 8006 8007 8008<p> 8009This function is not supported by Standard C. 8010As such, it is only available on some platforms 8011(Windows, Linux, Mac OS X, Solaris, BSD, 8012plus other Unix systems that support the <code>dlfcn</code> standard). 8013 8014 8015 8016 8017<p> 8018<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> 8019 8020 8021<p> 8022The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. 8023 8024 8025<p> 8026At start-up, Lua initializes this variable with 8027the value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or 8028the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or 8029with a default path defined in <code>luaconf.h</code>, 8030if those environment variables are not defined. 8031Any "<code>;;</code>" in the value of the environment variable 8032is replaced by the default path. 8033 8034 8035 8036 8037<p> 8038<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> 8039 8040 8041<p> 8042A table to store loaders for specific modules 8043(see <a href="#pdf-require"><code>require</code></a>). 8044 8045 8046<p> 8047This variable is only a reference to the real table; 8048assignments to this variable do not change the 8049table used by <a href="#pdf-require"><code>require</code></a>. 8050 8051 8052 8053 8054<p> 8055<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3> 8056 8057 8058<p> 8059A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules. 8060 8061 8062<p> 8063Each entry in this table is a <em>searcher function</em>. 8064When looking for a module, 8065<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, 8066with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its 8067sole parameter. 8068The function can return another function (the module <em>loader</em>) 8069plus an extra value that will be passed to that loader, 8070or a string explaining why it did not find that module 8071(or <b>nil</b> if it has nothing to say). 8072 8073 8074<p> 8075Lua initializes this table with four searcher functions. 8076 8077 8078<p> 8079The first searcher simply looks for a loader in the 8080<a href="#pdf-package.preload"><code>package.preload</code></a> table. 8081 8082 8083<p> 8084The second searcher looks for a loader as a Lua library, 8085using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. 8086The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8087 8088 8089<p> 8090The third searcher looks for a loader as a C library, 8091using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 8092Again, 8093the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8094For instance, 8095if the C path is the string 8096 8097<pre> 8098 "./?.so;./?.dll;/usr/local/?/init.so" 8099</pre><p> 8100the searcher for module <code>foo</code> 8101will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, 8102and <code>/usr/local/foo/init.so</code>, in that order. 8103Once it finds a C library, 8104this searcher first uses a dynamic link facility to link the 8105application with the library. 8106Then it tries to find a C function inside the library to 8107be used as the loader. 8108The name of this C function is the string "<code>luaopen_</code>" 8109concatenated with a copy of the module name where each dot 8110is replaced by an underscore. 8111Moreover, if the module name has a hyphen, 8112its suffix after (and including) the first hyphen is removed. 8113For instance, if the module name is <code>a.b.c-v2.1</code>, 8114the function name will be <code>luaopen_a_b_c</code>. 8115 8116 8117<p> 8118The fourth searcher tries an <em>all-in-one loader</em>. 8119It searches the C path for a library for 8120the root name of the given module. 8121For instance, when requiring <code>a.b.c</code>, 8122it will search for a C library for <code>a</code>. 8123If found, it looks into it for an open function for 8124the submodule; 8125in our example, that would be <code>luaopen_a_b_c</code>. 8126With this facility, a package can pack several C submodules 8127into one single library, 8128with each submodule keeping its original open function. 8129 8130 8131<p> 8132All searchers except the first one (preload) return as the extra value 8133the file name where the module was found, 8134as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8135The first searcher returns no extra value. 8136 8137 8138 8139 8140<p> 8141<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3> 8142 8143 8144<p> 8145Searches for the given <code>name</code> in the given <code>path</code>. 8146 8147 8148<p> 8149A path is a string containing a sequence of 8150<em>templates</em> separated by semicolons. 8151For each template, 8152the function replaces each interrogation mark (if any) 8153in the template with a copy of <code>name</code> 8154wherein all occurrences of <code>sep</code> 8155(a dot, by default) 8156were replaced by <code>rep</code> 8157(the system's directory separator, by default), 8158and then tries to open the resulting file name. 8159 8160 8161<p> 8162For instance, if the path is the string 8163 8164<pre> 8165 "./?.lua;./?.lc;/usr/local/?/init.lua" 8166</pre><p> 8167the search for the name <code>foo.a</code> 8168will try to open the files 8169<code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and 8170<code>/usr/local/foo/a/init.lua</code>, in that order. 8171 8172 8173<p> 8174Returns the resulting name of the first file that it can 8175open in read mode (after closing the file), 8176or <b>nil</b> plus an error message if none succeeds. 8177(This error message lists all file names it tried to open.) 8178 8179 8180 8181 8182 8183 8184 8185<h2>6.4 – <a name="6.4">String Manipulation</a></h2> 8186 8187<p> 8188This library provides generic functions for string manipulation, 8189such as finding and extracting substrings, and pattern matching. 8190When indexing a string in Lua, the first character is at position 1 8191(not at 0, as in C). 8192Indices are allowed to be negative and are interpreted as indexing backwards, 8193from the end of the string. 8194Thus, the last character is at position -1, and so on. 8195 8196 8197<p> 8198The string library provides all its functions inside the table 8199<a name="pdf-string"><code>string</code></a>. 8200It also sets a metatable for strings 8201where the <code>__index</code> field points to the <code>string</code> table. 8202Therefore, you can use the string functions in object-oriented style. 8203For instance, <code>string.byte(s,i)</code> 8204can be written as <code>s:byte(i)</code>. 8205 8206 8207<p> 8208The string library assumes one-byte character encodings. 8209 8210 8211<p> 8212<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> 8213Returns the internal numeric codes of the characters <code>s[i]</code>, 8214<code>s[i+1]</code>, ..., <code>s[j]</code>. 8215The default value for <code>i</code> is 1; 8216the default value for <code>j</code> is <code>i</code>. 8217These indices are corrected 8218following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>. 8219 8220 8221<p> 8222Numeric codes are not necessarily portable across platforms. 8223 8224 8225 8226 8227<p> 8228<hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> 8229Receives zero or more integers. 8230Returns a string with length equal to the number of arguments, 8231in which each character has the internal numeric code equal 8232to its corresponding argument. 8233 8234 8235<p> 8236Numeric codes are not necessarily portable across platforms. 8237 8238 8239 8240 8241<p> 8242<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3> 8243 8244 8245<p> 8246Returns a string containing a binary representation 8247(a <em>binary chunk</em>) 8248of the given function, 8249so that a later <a href="#pdf-load"><code>load</code></a> on this string returns 8250a copy of the function (but with new upvalues). 8251If <code>strip</code> is a true value, 8252the binary representation may not include all debug information 8253about the function, 8254to save space. 8255 8256 8257<p> 8258Functions with upvalues have only their number of upvalues saved. 8259When (re)loaded, 8260those upvalues receive fresh instances containing <b>nil</b>. 8261(You can use the debug library to serialize 8262and reload the upvalues of a function 8263in a way adequate to your needs.) 8264 8265 8266 8267 8268<p> 8269<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> 8270 8271 8272<p> 8273Looks for the first match of 8274<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 8275If it finds a match, then <code>find</code> returns the indices of <code>s</code> 8276where this occurrence starts and ends; 8277otherwise, it returns <b>nil</b>. 8278A third, optional numeric argument <code>init</code> specifies 8279where to start the search; 8280its default value is 1 and can be negative. 8281A value of <b>true</b> as a fourth, optional argument <code>plain</code> 8282turns off the pattern matching facilities, 8283so the function does a plain "find substring" operation, 8284with no characters in <code>pattern</code> being considered magic. 8285Note that if <code>plain</code> is given, then <code>init</code> must be given as well. 8286 8287 8288<p> 8289If the pattern has captures, 8290then in a successful match 8291the captured values are also returned, 8292after the two indices. 8293 8294 8295 8296 8297<p> 8298<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> 8299 8300 8301<p> 8302Returns a formatted version of its variable number of arguments 8303following the description given in its first argument (which must be a string). 8304The format string follows the same rules as the ISO C function <code>sprintf</code>. 8305The only differences are that the options/modifiers 8306<code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>, 8307and <code>p</code> are not supported 8308and that there is an extra option, <code>q</code>. 8309 8310 8311<p> 8312The <code>q</code> option formats a string between double quotes, 8313using escape sequences when necessary to ensure that 8314it can safely be read back by the Lua interpreter. 8315For instance, the call 8316 8317<pre> 8318 string.format('%q', 'a string with "quotes" and \n new line') 8319</pre><p> 8320may produce the string: 8321 8322<pre> 8323 "a string with \"quotes\" and \ 8324 new line" 8325</pre> 8326 8327<p> 8328Options 8329<code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>, 8330<code>G</code>, and <code>g</code> all expect a number as argument. 8331Options <code>c</code>, <code>d</code>, 8332<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> 8333expect an integer. 8334When Lua is compiled with a C89 compiler, 8335options <code>A</code> and <code>a</code> (hexadecimal floats) 8336do not support any modifier (flags, width, length). 8337 8338 8339<p> 8340Option <code>s</code> expects a string; 8341if its argument is not a string, 8342it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 8343If the option has any modifier (flags, width, length), 8344the string argument should not contain embedded zeros. 8345 8346 8347 8348 8349<p> 8350<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3> 8351Returns an iterator function that, 8352each time it is called, 8353returns the next captures from <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) 8354over the string <code>s</code>. 8355If <code>pattern</code> specifies no captures, 8356then the whole match is produced in each call. 8357 8358 8359<p> 8360As an example, the following loop 8361will iterate over all the words from string <code>s</code>, 8362printing one per line: 8363 8364<pre> 8365 s = "hello world from Lua" 8366 for w in string.gmatch(s, "%a+") do 8367 print(w) 8368 end 8369</pre><p> 8370The next example collects all pairs <code>key=value</code> from the 8371given string into a table: 8372 8373<pre> 8374 t = {} 8375 s = "from=world, to=Lua" 8376 for k, v in string.gmatch(s, "(%w+)=(%w+)") do 8377 t[k] = v 8378 end 8379</pre> 8380 8381<p> 8382For this function, a caret '<code>^</code>' at the start of a pattern does not 8383work as an anchor, as this would prevent the iteration. 8384 8385 8386 8387 8388<p> 8389<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> 8390Returns a copy of <code>s</code> 8391in which all (or the first <code>n</code>, if given) 8392occurrences of the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) have been 8393replaced by a replacement string specified by <code>repl</code>, 8394which can be a string, a table, or a function. 8395<code>gsub</code> also returns, as its second value, 8396the total number of matches that occurred. 8397The name <code>gsub</code> comes from <em>Global SUBstitution</em>. 8398 8399 8400<p> 8401If <code>repl</code> is a string, then its value is used for replacement. 8402The character <code>%</code> works as an escape character: 8403any sequence in <code>repl</code> of the form <code>%<em>d</em></code>, 8404with <em>d</em> between 1 and 9, 8405stands for the value of the <em>d</em>-th captured substring. 8406The sequence <code>%0</code> stands for the whole match. 8407The sequence <code>%%</code> stands for a single <code>%</code>. 8408 8409 8410<p> 8411If <code>repl</code> is a table, then the table is queried for every match, 8412using the first capture as the key. 8413 8414 8415<p> 8416If <code>repl</code> is a function, then this function is called every time a 8417match occurs, with all captured substrings passed as arguments, 8418in order. 8419 8420 8421<p> 8422In any case, 8423if the pattern specifies no captures, 8424then it behaves as if the whole pattern was inside a capture. 8425 8426 8427<p> 8428If the value returned by the table query or by the function call 8429is a string or a number, 8430then it is used as the replacement string; 8431otherwise, if it is <b>false</b> or <b>nil</b>, 8432then there is no replacement 8433(that is, the original match is kept in the string). 8434 8435 8436<p> 8437Here are some examples: 8438 8439<pre> 8440 x = string.gsub("hello world", "(%w+)", "%1 %1") 8441 --> x="hello hello world world" 8442 8443 x = string.gsub("hello world", "%w+", "%0 %0", 1) 8444 --> x="hello hello world" 8445 8446 x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 8447 --> x="world hello Lua from" 8448 8449 x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) 8450 --> x="home = /home/roberto, user = roberto" 8451 8452 x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 8453 return load(s)() 8454 end) 8455 --> x="4+5 = 9" 8456 8457 local t = {name="lua", version="5.3"} 8458 x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 8459 --> x="lua-5.3.tar.gz" 8460</pre> 8461 8462 8463 8464<p> 8465<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> 8466Receives a string and returns its length. 8467The empty string <code>""</code> has length 0. 8468Embedded zeros are counted, 8469so <code>"a\000bc\000"</code> has length 5. 8470 8471 8472 8473 8474<p> 8475<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> 8476Receives a string and returns a copy of this string with all 8477uppercase letters changed to lowercase. 8478All other characters are left unchanged. 8479The definition of what an uppercase letter is depends on the current locale. 8480 8481 8482 8483 8484<p> 8485<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> 8486Looks for the first <em>match</em> of 8487<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 8488If it finds one, then <code>match</code> returns 8489the captures from the pattern; 8490otherwise it returns <b>nil</b>. 8491If <code>pattern</code> specifies no captures, 8492then the whole match is returned. 8493A third, optional numeric argument <code>init</code> specifies 8494where to start the search; 8495its default value is 1 and can be negative. 8496 8497 8498 8499 8500<p> 8501<hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, ···)</code></a></h3> 8502 8503 8504<p> 8505Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc. 8506packed (that is, serialized in binary form) 8507according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 8508 8509 8510 8511 8512<p> 8513<hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3> 8514 8515 8516<p> 8517Returns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a> 8518with the given format. 8519The format string cannot have the variable-length options 8520'<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">§6.4.2</a>). 8521 8522 8523 8524 8525<p> 8526<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3> 8527Returns a string that is the concatenation of <code>n</code> copies of 8528the string <code>s</code> separated by the string <code>sep</code>. 8529The default value for <code>sep</code> is the empty string 8530(that is, no separator). 8531Returns the empty string if <code>n</code> is not positive. 8532 8533 8534<p> 8535(Note that it is very easy to exhaust the memory of your machine 8536with a single call to this function.) 8537 8538 8539 8540 8541<p> 8542<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> 8543Returns a string that is the string <code>s</code> reversed. 8544 8545 8546 8547 8548<p> 8549<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> 8550Returns the substring of <code>s</code> that 8551starts at <code>i</code> and continues until <code>j</code>; 8552<code>i</code> and <code>j</code> can be negative. 8553If <code>j</code> is absent, then it is assumed to be equal to -1 8554(which is the same as the string length). 8555In particular, 8556the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 8557with length <code>j</code>, 8558and <code>string.sub(s, -i)</code> (for a positive <code>i</code>) 8559returns a suffix of <code>s</code> 8560with length <code>i</code>. 8561 8562 8563<p> 8564If, after the translation of negative indices, 8565<code>i</code> is less than 1, 8566it is corrected to 1. 8567If <code>j</code> is greater than the string length, 8568it is corrected to that length. 8569If, after these corrections, 8570<code>i</code> is greater than <code>j</code>, 8571the function returns the empty string. 8572 8573 8574 8575 8576<p> 8577<hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3> 8578 8579 8580<p> 8581Returns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>) 8582according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 8583An optional <code>pos</code> marks where 8584to start reading in <code>s</code> (default is 1). 8585After the read values, 8586this function also returns the index of the first unread byte in <code>s</code>. 8587 8588 8589 8590 8591<p> 8592<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> 8593Receives a string and returns a copy of this string with all 8594lowercase letters changed to uppercase. 8595All other characters are left unchanged. 8596The definition of what a lowercase letter is depends on the current locale. 8597 8598 8599 8600 8601 8602<h3>6.4.1 – <a name="6.4.1">Patterns</a></h3> 8603 8604<p> 8605Patterns in Lua are described by regular strings, 8606which are interpreted as patterns by the pattern-matching functions 8607<a href="#pdf-string.find"><code>string.find</code></a>, 8608<a href="#pdf-string.gmatch"><code>string.gmatch</code></a>, 8609<a href="#pdf-string.gsub"><code>string.gsub</code></a>, 8610and <a href="#pdf-string.match"><code>string.match</code></a>. 8611This section describes the syntax and the meaning 8612(that is, what they match) of these strings. 8613 8614 8615 8616<h4>Character Class:</h4><p> 8617A <em>character class</em> is used to represent a set of characters. 8618The following combinations are allowed in describing a character class: 8619 8620<ul> 8621 8622<li><b><em>x</em>: </b> 8623(where <em>x</em> is not one of the <em>magic characters</em> 8624<code>^$()%.[]*+-?</code>) 8625represents the character <em>x</em> itself. 8626</li> 8627 8628<li><b><code>.</code>: </b> (a dot) represents all characters.</li> 8629 8630<li><b><code>%a</code>: </b> represents all letters.</li> 8631 8632<li><b><code>%c</code>: </b> represents all control characters.</li> 8633 8634<li><b><code>%d</code>: </b> represents all digits.</li> 8635 8636<li><b><code>%g</code>: </b> represents all printable characters except space.</li> 8637 8638<li><b><code>%l</code>: </b> represents all lowercase letters.</li> 8639 8640<li><b><code>%p</code>: </b> represents all punctuation characters.</li> 8641 8642<li><b><code>%s</code>: </b> represents all space characters.</li> 8643 8644<li><b><code>%u</code>: </b> represents all uppercase letters.</li> 8645 8646<li><b><code>%w</code>: </b> represents all alphanumeric characters.</li> 8647 8648<li><b><code>%x</code>: </b> represents all hexadecimal digits.</li> 8649 8650<li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character) 8651represents the character <em>x</em>. 8652This is the standard way to escape the magic characters. 8653Any non-alphanumeric character 8654(including all punctuation characters, even the non-magical) 8655can be preceded by a '<code>%</code>' 8656when used to represent itself in a pattern. 8657</li> 8658 8659<li><b><code>[<em>set</em>]</code>: </b> 8660represents the class which is the union of all 8661characters in <em>set</em>. 8662A range of characters can be specified by 8663separating the end characters of the range, 8664in ascending order, with a '<code>-</code>'. 8665All classes <code>%</code><em>x</em> described above can also be used as 8666components in <em>set</em>. 8667All other characters in <em>set</em> represent themselves. 8668For example, <code>[%w_]</code> (or <code>[_%w]</code>) 8669represents all alphanumeric characters plus the underscore, 8670<code>[0-7]</code> represents the octal digits, 8671and <code>[0-7%l%-]</code> represents the octal digits plus 8672the lowercase letters plus the '<code>-</code>' character. 8673 8674 8675<p> 8676You can put a closing square bracket in a set 8677by positioning it as the first character in the set. 8678You can put a hyphen in a set 8679by positioning it as the first or the last character in the set. 8680(You can also use an escape for both cases.) 8681 8682 8683<p> 8684The interaction between ranges and classes is not defined. 8685Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> 8686have no meaning. 8687</li> 8688 8689<li><b><code>[^<em>set</em>]</code>: </b> 8690represents the complement of <em>set</em>, 8691where <em>set</em> is interpreted as above. 8692</li> 8693 8694</ul><p> 8695For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), 8696the corresponding uppercase letter represents the complement of the class. 8697For instance, <code>%S</code> represents all non-space characters. 8698 8699 8700<p> 8701The definitions of letter, space, and other character groups 8702depend on the current locale. 8703In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. 8704 8705 8706 8707 8708 8709<h4>Pattern Item:</h4><p> 8710A <em>pattern item</em> can be 8711 8712<ul> 8713 8714<li> 8715a single character class, 8716which matches any single character in the class; 8717</li> 8718 8719<li> 8720a single character class followed by '<code>*</code>', 8721which matches zero or more repetitions of characters in the class. 8722These repetition items will always match the longest possible sequence; 8723</li> 8724 8725<li> 8726a single character class followed by '<code>+</code>', 8727which matches one or more repetitions of characters in the class. 8728These repetition items will always match the longest possible sequence; 8729</li> 8730 8731<li> 8732a single character class followed by '<code>-</code>', 8733which also matches zero or more repetitions of characters in the class. 8734Unlike '<code>*</code>', 8735these repetition items will always match the shortest possible sequence; 8736</li> 8737 8738<li> 8739a single character class followed by '<code>?</code>', 8740which matches zero or one occurrence of a character in the class. 8741It always matches one occurrence if possible; 8742</li> 8743 8744<li> 8745<code>%<em>n</em></code>, for <em>n</em> between 1 and 9; 8746such item matches a substring equal to the <em>n</em>-th captured string 8747(see below); 8748</li> 8749 8750<li> 8751<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; 8752such item matches strings that start with <em>x</em>, end with <em>y</em>, 8753and where the <em>x</em> and <em>y</em> are <em>balanced</em>. 8754This means that, if one reads the string from left to right, 8755counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, 8756the ending <em>y</em> is the first <em>y</em> where the count reaches 0. 8757For instance, the item <code>%b()</code> matches expressions with 8758balanced parentheses. 8759</li> 8760 8761<li> 8762<code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>; 8763such item matches an empty string at any position such that 8764the next character belongs to <em>set</em> 8765and the previous character does not belong to <em>set</em>. 8766The set <em>set</em> is interpreted as previously described. 8767The beginning and the end of the subject are handled as if 8768they were the character '<code>\0</code>'. 8769</li> 8770 8771</ul> 8772 8773 8774 8775 8776<h4>Pattern:</h4><p> 8777A <em>pattern</em> is a sequence of pattern items. 8778A caret '<code>^</code>' at the beginning of a pattern anchors the match at the 8779beginning of the subject string. 8780A '<code>$</code>' at the end of a pattern anchors the match at the 8781end of the subject string. 8782At other positions, 8783'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. 8784 8785 8786 8787 8788 8789<h4>Captures:</h4><p> 8790A pattern can contain sub-patterns enclosed in parentheses; 8791they describe <em>captures</em>. 8792When a match succeeds, the substrings of the subject string 8793that match captures are stored (<em>captured</em>) for future use. 8794Captures are numbered according to their left parentheses. 8795For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, 8796the part of the string matching <code>"a*(.)%w(%s*)"</code> is 8797stored as the first capture (and therefore has number 1); 8798the character matching "<code>.</code>" is captured with number 2, 8799and the part matching "<code>%s*</code>" has number 3. 8800 8801 8802<p> 8803As a special case, the empty capture <code>()</code> captures 8804the current string position (a number). 8805For instance, if we apply the pattern <code>"()aa()"</code> on the 8806string <code>"flaaap"</code>, there will be two captures: 3 and 5. 8807 8808 8809 8810 8811 8812 8813 8814<h3>6.4.2 – <a name="6.4.2">Format Strings for Pack and Unpack</a></h3> 8815 8816<p> 8817The first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>, 8818<a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a> 8819is a format string, 8820which describes the layout of the structure being created or read. 8821 8822 8823<p> 8824A format string is a sequence of conversion options. 8825The conversion options are as follows: 8826 8827<ul> 8828<li><b><code><</code>: </b>sets little endian</li> 8829<li><b><code>></code>: </b>sets big endian</li> 8830<li><b><code>=</code>: </b>sets native endian</li> 8831<li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code> 8832(default is native alignment)</li> 8833<li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li> 8834<li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li> 8835<li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li> 8836<li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li> 8837<li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li> 8838<li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li> 8839<li><b><code>j</code>: </b>a <code>lua_Integer</code></li> 8840<li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li> 8841<li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li> 8842<li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes 8843(default is native size)</li> 8844<li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes 8845(default is native size)</li> 8846<li><b><code>f</code>: </b>a <code>float</code> (native size)</li> 8847<li><b><code>d</code>: </b>a <code>double</code> (native size)</li> 8848<li><b><code>n</code>: </b>a <code>lua_Number</code></li> 8849<li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li> 8850<li><b><code>z</code>: </b>a zero-terminated string</li> 8851<li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length 8852coded as an unsigned integer with <code>n</code> bytes 8853(default is a <code>size_t</code>)</li> 8854<li><b><code>x</code>: </b>one byte of padding</li> 8855<li><b><code>X<em>op</em></code>: </b>an empty item that aligns 8856according to option <code>op</code> 8857(which is otherwise ignored)</li> 8858<li><b>'<code> </code>': </b>(empty space) ignored</li> 8859</ul><p> 8860(A "<code>[<em>n</em>]</code>" means an optional integral numeral.) 8861Except for padding, spaces, and configurations 8862(options "<code>xX <=>!</code>"), 8863each option corresponds to an argument (in <a href="#pdf-string.pack"><code>string.pack</code></a>) 8864or a result (in <a href="#pdf-string.unpack"><code>string.unpack</code></a>). 8865 8866 8867<p> 8868For 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>", 8869<code>n</code> can be any integer between 1 and 16. 8870All integral options check overflows; 8871<a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size; 8872<a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer. 8873 8874 8875<p> 8876Any format string starts as if prefixed by "<code>!1=</code>", 8877that is, 8878with maximum alignment of 1 (no alignment) 8879and native endianness. 8880 8881 8882<p> 8883Alignment works as follows: 8884For each option, 8885the format gets extra padding until the data starts 8886at an offset that is a multiple of the minimum between the 8887option size and the maximum alignment; 8888this minimum must be a power of 2. 8889Options "<code>c</code>" and "<code>z</code>" are not aligned; 8890option "<code>s</code>" follows the alignment of its starting integer. 8891 8892 8893<p> 8894All padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a> 8895(and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>). 8896 8897 8898 8899 8900 8901 8902 8903<h2>6.5 – <a name="6.5">UTF-8 Support</a></h2> 8904 8905<p> 8906This library provides basic support for UTF-8 encoding. 8907It provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>. 8908This library does not provide any support for Unicode other 8909than the handling of the encoding. 8910Any operation that needs the meaning of a character, 8911such as character classification, is outside its scope. 8912 8913 8914<p> 8915Unless stated otherwise, 8916all functions that expect a byte position as a parameter 8917assume that the given position is either the start of a byte sequence 8918or one plus the length of the subject string. 8919As in the string library, 8920negative indices count from the end of the string. 8921 8922 8923<p> 8924<hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3> 8925Receives zero or more integers, 8926converts each one to its corresponding UTF-8 byte sequence 8927and returns a string with the concatenation of all these sequences. 8928 8929 8930 8931 8932<p> 8933<hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3> 8934The pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>" 8935(see <a href="#6.4.1">§6.4.1</a>), 8936which matches exactly one UTF-8 byte sequence, 8937assuming that the subject is a valid UTF-8 string. 8938 8939 8940 8941 8942<p> 8943<hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3> 8944 8945 8946<p> 8947Returns values so that the construction 8948 8949<pre> 8950 for p, c in utf8.codes(s) do <em>body</em> end 8951</pre><p> 8952will iterate over all characters in string <code>s</code>, 8953with <code>p</code> being the position (in bytes) and <code>c</code> the code point 8954of each character. 8955It raises an error if it meets any invalid byte sequence. 8956 8957 8958 8959 8960<p> 8961<hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3> 8962Returns the codepoints (as integers) from all characters in <code>s</code> 8963that start between byte position <code>i</code> and <code>j</code> (both included). 8964The default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>. 8965It raises an error if it meets any invalid byte sequence. 8966 8967 8968 8969 8970<p> 8971<hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j]])</code></a></h3> 8972Returns the number of UTF-8 characters in string <code>s</code> 8973that start between positions <code>i</code> and <code>j</code> (both inclusive). 8974The default for <code>i</code> is 1 and for <code>j</code> is -1. 8975If it finds any invalid byte sequence, 8976returns a false value plus the position of the first invalid byte. 8977 8978 8979 8980 8981<p> 8982<hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3> 8983Returns the position (in bytes) where the encoding of the 8984<code>n</code>-th character of <code>s</code> 8985(counting from position <code>i</code>) starts. 8986A negative <code>n</code> gets characters before position <code>i</code>. 8987The default for <code>i</code> is 1 when <code>n</code> is non-negative 8988and <code>#s + 1</code> otherwise, 8989so that <code>utf8.offset(s, -n)</code> gets the offset of the 8990<code>n</code>-th character from the end of the string. 8991If the specified character is neither in the subject 8992nor right after its end, 8993the function returns <b>nil</b>. 8994 8995 8996<p> 8997As a special case, 8998when <code>n</code> is 0 the function returns the start of the encoding 8999of the character that contains the <code>i</code>-th byte of <code>s</code>. 9000 9001 9002<p> 9003This function assumes that <code>s</code> is a valid UTF-8 string. 9004 9005 9006 9007 9008 9009 9010 9011<h2>6.6 – <a name="6.6">Table Manipulation</a></h2> 9012 9013<p> 9014This library provides generic functions for table manipulation. 9015It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. 9016 9017 9018<p> 9019Remember that, whenever an operation needs the length of a table, 9020all caveats about the length operator apply (see <a href="#3.4.7">§3.4.7</a>). 9021All functions ignore non-numeric keys 9022in the tables given as arguments. 9023 9024 9025<p> 9026<hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3> 9027 9028 9029<p> 9030Given a list where all elements are strings or numbers, 9031returns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>. 9032The default value for <code>sep</code> is the empty string, 9033the default for <code>i</code> is 1, 9034and the default for <code>j</code> is <code>#list</code>. 9035If <code>i</code> is greater than <code>j</code>, returns the empty string. 9036 9037 9038 9039 9040<p> 9041<hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3> 9042 9043 9044<p> 9045Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>, 9046shifting up the elements 9047<code>list[pos], list[pos+1], ···, list[#list]</code>. 9048The default value for <code>pos</code> is <code>#list+1</code>, 9049so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end 9050of list <code>t</code>. 9051 9052 9053 9054 9055<p> 9056<hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3> 9057 9058 9059<p> 9060Moves elements from table <code>a1</code> to table <code>a2</code>, 9061performing the equivalent to the following 9062multiple assignment: 9063<code>a2[t],··· = a1[f],···,a1[e]</code>. 9064The default for <code>a2</code> is <code>a1</code>. 9065The destination range can overlap with the source range. 9066The number of elements to be moved must fit in a Lua integer. 9067 9068 9069<p> 9070Returns the destination table <code>a2</code>. 9071 9072 9073 9074 9075<p> 9076<hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3> 9077 9078 9079<p> 9080Returns a new table with all arguments stored into keys 1, 2, etc. 9081and with a field "<code>n</code>" with the total number of arguments. 9082Note that the resulting table may not be a sequence. 9083 9084 9085 9086 9087<p> 9088<hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3> 9089 9090 9091<p> 9092Removes from <code>list</code> the element at position <code>pos</code>, 9093returning the value of the removed element. 9094When <code>pos</code> is an integer between 1 and <code>#list</code>, 9095it shifts down the elements 9096<code>list[pos+1], list[pos+2], ···, list[#list]</code> 9097and erases element <code>list[#list]</code>; 9098The index <code>pos</code> can also be 0 when <code>#list</code> is 0, 9099or <code>#list + 1</code>; 9100in those cases, the function erases the element <code>list[pos]</code>. 9101 9102 9103<p> 9104The default value for <code>pos</code> is <code>#list</code>, 9105so that a call <code>table.remove(l)</code> removes the last element 9106of list <code>l</code>. 9107 9108 9109 9110 9111<p> 9112<hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3> 9113 9114 9115<p> 9116Sorts list elements in a given order, <em>in-place</em>, 9117from <code>list[1]</code> to <code>list[#list]</code>. 9118If <code>comp</code> is given, 9119then it must be a function that receives two list elements 9120and returns true when the first element must come 9121before the second in the final order 9122(so that, after the sort, 9123<code>i < j</code> implies <code>not comp(list[j],list[i])</code>). 9124If <code>comp</code> is not given, 9125then the standard Lua operator <code><</code> is used instead. 9126 9127 9128<p> 9129Note that the <code>comp</code> function must define 9130a strict partial order over the elements in the list; 9131that is, it must be asymmetric and transitive. 9132Otherwise, no valid sort may be possible. 9133 9134 9135<p> 9136The sort algorithm is not stable: 9137elements considered equal by the given order 9138may have their relative positions changed by the sort. 9139 9140 9141 9142 9143<p> 9144<hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3> 9145 9146 9147<p> 9148Returns the elements from the given list. 9149This function is equivalent to 9150 9151<pre> 9152 return list[i], list[i+1], ···, list[j] 9153</pre><p> 9154By default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>. 9155 9156 9157 9158 9159 9160 9161 9162<h2>6.7 – <a name="6.7">Mathematical Functions</a></h2> 9163 9164<p> 9165This library provides basic mathematical functions. 9166It provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>. 9167Functions with the annotation "<code>integer/float</code>" give 9168integer results for integer arguments 9169and float results for float (or mixed) arguments. 9170Rounding functions 9171(<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>) 9172return an integer when the result fits in the range of an integer, 9173or a float otherwise. 9174 9175 9176<p> 9177<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> 9178 9179 9180<p> 9181Returns the absolute value of <code>x</code>. (integer/float) 9182 9183 9184 9185 9186<p> 9187<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> 9188 9189 9190<p> 9191Returns the arc cosine of <code>x</code> (in radians). 9192 9193 9194 9195 9196<p> 9197<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> 9198 9199 9200<p> 9201Returns the arc sine of <code>x</code> (in radians). 9202 9203 9204 9205 9206<p> 9207<hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3> 9208 9209 9210<p> 9211 9212Returns the arc tangent of <code>y/x</code> (in radians), 9213but uses the signs of both arguments to find the 9214quadrant of the result. 9215(It also handles correctly the case of <code>x</code> being zero.) 9216 9217 9218<p> 9219The default value for <code>x</code> is 1, 9220so that the call <code>math.atan(y)</code> 9221returns the arc tangent of <code>y</code>. 9222 9223 9224 9225 9226<p> 9227<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> 9228 9229 9230<p> 9231Returns the smallest integral value larger than or equal to <code>x</code>. 9232 9233 9234 9235 9236<p> 9237<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> 9238 9239 9240<p> 9241Returns the cosine of <code>x</code> (assumed to be in radians). 9242 9243 9244 9245 9246<p> 9247<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> 9248 9249 9250<p> 9251Converts the angle <code>x</code> from radians to degrees. 9252 9253 9254 9255 9256<p> 9257<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> 9258 9259 9260<p> 9261Returns the value <em>e<sup>x</sup></em> 9262(where <code>e</code> is the base of natural logarithms). 9263 9264 9265 9266 9267<p> 9268<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> 9269 9270 9271<p> 9272Returns the largest integral value smaller than or equal to <code>x</code>. 9273 9274 9275 9276 9277<p> 9278<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> 9279 9280 9281<p> 9282Returns the remainder of the division of <code>x</code> by <code>y</code> 9283that rounds the quotient towards zero. (integer/float) 9284 9285 9286 9287 9288<p> 9289<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> 9290 9291 9292<p> 9293The float value <code>HUGE_VAL</code>, 9294a value larger than any other numeric value. 9295 9296 9297 9298 9299<p> 9300<hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3> 9301 9302 9303<p> 9304Returns the logarithm of <code>x</code> in the given base. 9305The default for <code>base</code> is <em>e</em> 9306(so that the function returns the natural logarithm of <code>x</code>). 9307 9308 9309 9310 9311<p> 9312<hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> 9313 9314 9315<p> 9316Returns the argument with the maximum value, 9317according to the Lua operator <code><</code>. (integer/float) 9318 9319 9320 9321 9322<p> 9323<hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3> 9324An integer with the maximum value for an integer. 9325 9326 9327 9328 9329<p> 9330<hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> 9331 9332 9333<p> 9334Returns the argument with the minimum value, 9335according to the Lua operator <code><</code>. (integer/float) 9336 9337 9338 9339 9340<p> 9341<hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3> 9342An integer with the minimum value for an integer. 9343 9344 9345 9346 9347<p> 9348<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> 9349 9350 9351<p> 9352Returns the integral part of <code>x</code> and the fractional part of <code>x</code>. 9353Its second result is always a float. 9354 9355 9356 9357 9358<p> 9359<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> 9360 9361 9362<p> 9363The value of <em>π</em>. 9364 9365 9366 9367 9368<p> 9369<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> 9370 9371 9372<p> 9373Converts the angle <code>x</code> from degrees to radians. 9374 9375 9376 9377 9378<p> 9379<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> 9380 9381 9382<p> 9383When called without arguments, 9384returns a pseudo-random float with uniform distribution 9385in the range <em>[0,1)</em>. 9386When called with two integers <code>m</code> and <code>n</code>, 9387<code>math.random</code> returns a pseudo-random integer 9388with uniform distribution in the range <em>[m, n]</em>. 9389(The value <em>n-m</em> cannot be negative and must fit in a Lua integer.) 9390The call <code>math.random(n)</code> is equivalent to <code>math.random(1,n)</code>. 9391 9392 9393<p> 9394This function is an interface to the underling 9395pseudo-random generator function provided by C. 9396 9397 9398 9399 9400<p> 9401<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3> 9402 9403 9404<p> 9405Sets <code>x</code> as the "seed" 9406for the pseudo-random generator: 9407equal seeds produce equal sequences of numbers. 9408 9409 9410 9411 9412<p> 9413<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> 9414 9415 9416<p> 9417Returns the sine of <code>x</code> (assumed to be in radians). 9418 9419 9420 9421 9422<p> 9423<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> 9424 9425 9426<p> 9427Returns the square root of <code>x</code>. 9428(You can also use the expression <code>x^0.5</code> to compute this value.) 9429 9430 9431 9432 9433<p> 9434<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> 9435 9436 9437<p> 9438Returns the tangent of <code>x</code> (assumed to be in radians). 9439 9440 9441 9442 9443<p> 9444<hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3> 9445 9446 9447<p> 9448If the value <code>x</code> is convertible to an integer, 9449returns that integer. 9450Otherwise, returns <b>nil</b>. 9451 9452 9453 9454 9455<p> 9456<hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3> 9457 9458 9459<p> 9460Returns "<code>integer</code>" if <code>x</code> is an integer, 9461"<code>float</code>" if it is a float, 9462or <b>nil</b> if <code>x</code> is not a number. 9463 9464 9465 9466 9467<p> 9468<hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3> 9469 9470 9471<p> 9472Returns a boolean, 9473true if and only if integer <code>m</code> is below integer <code>n</code> when 9474they are compared as unsigned integers. 9475 9476 9477 9478 9479 9480 9481 9482<h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2> 9483 9484<p> 9485The I/O library provides two different styles for file manipulation. 9486The first one uses implicit file handles; 9487that is, there are operations to set a default input file and a 9488default output file, 9489and all input/output operations are over these default files. 9490The second style uses explicit file handles. 9491 9492 9493<p> 9494When using implicit file handles, 9495all operations are supplied by table <a name="pdf-io"><code>io</code></a>. 9496When using explicit file handles, 9497the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle 9498and then all operations are supplied as methods of the file handle. 9499 9500 9501<p> 9502The table <code>io</code> also provides 9503three predefined file handles with their usual meanings from C: 9504<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>. 9505The I/O library never closes these files. 9506 9507 9508<p> 9509Unless otherwise stated, 9510all I/O functions return <b>nil</b> on failure 9511(plus an error message as a second result and 9512a system-dependent error code as a third result) 9513and some value different from <b>nil</b> on success. 9514In non-POSIX systems, 9515the computation of the error message and error code 9516in case of errors 9517may be not thread safe, 9518because they rely on the global C variable <code>errno</code>. 9519 9520 9521<p> 9522<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> 9523 9524 9525<p> 9526Equivalent to <code>file:close()</code>. 9527Without a <code>file</code>, closes the default output file. 9528 9529 9530 9531 9532<p> 9533<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> 9534 9535 9536<p> 9537Equivalent to <code>io.output():flush()</code>. 9538 9539 9540 9541 9542<p> 9543<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> 9544 9545 9546<p> 9547When called with a file name, it opens the named file (in text mode), 9548and sets its handle as the default input file. 9549When called with a file handle, 9550it simply sets this file handle as the default input file. 9551When called without arguments, 9552it returns the current default input file. 9553 9554 9555<p> 9556In case of errors this function raises the error, 9557instead of returning an error code. 9558 9559 9560 9561 9562<p> 9563<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, ···])</code></a></h3> 9564 9565 9566<p> 9567Opens the given file name in read mode 9568and returns an iterator function that 9569works like <code>file:lines(···)</code> over the opened file. 9570When the iterator function detects the end of file, 9571it returns no values (to finish the loop) and automatically closes the file. 9572 9573 9574<p> 9575The call <code>io.lines()</code> (with no file name) is equivalent 9576to <code>io.input():lines("*l")</code>; 9577that is, it iterates over the lines of the default input file. 9578In this case, the iterator does not close the file when the loop ends. 9579 9580 9581<p> 9582In case of errors this function raises the error, 9583instead of returning an error code. 9584 9585 9586 9587 9588<p> 9589<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> 9590 9591 9592<p> 9593This function opens a file, 9594in the mode specified in the string <code>mode</code>. 9595In case of success, 9596it returns a new file handle. 9597 9598 9599<p> 9600The <code>mode</code> string can be any of the following: 9601 9602<ul> 9603<li><b>"<code>r</code>": </b> read mode (the default);</li> 9604<li><b>"<code>w</code>": </b> write mode;</li> 9605<li><b>"<code>a</code>": </b> append mode;</li> 9606<li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li> 9607<li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li> 9608<li><b>"<code>a+</code>": </b> append update mode, previous data is preserved, 9609 writing is only allowed at the end of file.</li> 9610</ul><p> 9611The <code>mode</code> string can also have a '<code>b</code>' at the end, 9612which is needed in some systems to open the file in binary mode. 9613 9614 9615 9616 9617<p> 9618<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> 9619 9620 9621<p> 9622Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. 9623 9624 9625 9626 9627<p> 9628<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> 9629 9630 9631<p> 9632This function is system dependent and is not available 9633on all platforms. 9634 9635 9636<p> 9637Starts program <code>prog</code> in a separated process and returns 9638a file handle that you can use to read data from this program 9639(if <code>mode</code> is <code>"r"</code>, the default) 9640or to write data to this program 9641(if <code>mode</code> is <code>"w"</code>). 9642 9643 9644 9645 9646<p> 9647<hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> 9648 9649 9650<p> 9651Equivalent to <code>io.input():read(···)</code>. 9652 9653 9654 9655 9656<p> 9657<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> 9658 9659 9660<p> 9661In case of success, 9662returns a handle for a temporary file. 9663This file is opened in update mode 9664and it is automatically removed when the program ends. 9665 9666 9667 9668 9669<p> 9670<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> 9671 9672 9673<p> 9674Checks whether <code>obj</code> is a valid file handle. 9675Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, 9676<code>"closed file"</code> if <code>obj</code> is a closed file handle, 9677or <b>nil</b> if <code>obj</code> is not a file handle. 9678 9679 9680 9681 9682<p> 9683<hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> 9684 9685 9686<p> 9687Equivalent to <code>io.output():write(···)</code>. 9688 9689 9690 9691 9692<p> 9693<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> 9694 9695 9696<p> 9697Closes <code>file</code>. 9698Note that files are automatically closed when 9699their handles are garbage collected, 9700but that takes an unpredictable amount of time to happen. 9701 9702 9703<p> 9704When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>, 9705<a href="#pdf-file:close"><code>file:close</code></a> returns the same values 9706returned by <a href="#pdf-os.execute"><code>os.execute</code></a>. 9707 9708 9709 9710 9711<p> 9712<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> 9713 9714 9715<p> 9716Saves any written data to <code>file</code>. 9717 9718 9719 9720 9721<p> 9722<hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3> 9723 9724 9725<p> 9726Returns an iterator function that, 9727each time it is called, 9728reads the file according to the given formats. 9729When no format is given, 9730uses "<code>l</code>" as a default. 9731As an example, the construction 9732 9733<pre> 9734 for c in file:lines(1) do <em>body</em> end 9735</pre><p> 9736will iterate over all characters of the file, 9737starting at the current position. 9738Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file 9739when the loop ends. 9740 9741 9742<p> 9743In case of errors this function raises the error, 9744instead of returning an error code. 9745 9746 9747 9748 9749<p> 9750<hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> 9751 9752 9753<p> 9754Reads the file <code>file</code>, 9755according to the given formats, which specify what to read. 9756For each format, 9757the function returns a string or a number with the characters read, 9758or <b>nil</b> if it cannot read data with the specified format. 9759(In this latter case, 9760the function does not read subsequent formats.) 9761When called without formats, 9762it uses a default format that reads the next line 9763(see below). 9764 9765 9766<p> 9767The available formats are 9768 9769<ul> 9770 9771<li><b>"<code>n</code>": </b> 9772reads a numeral and returns it as a float or an integer, 9773following the lexical conventions of Lua. 9774(The numeral may have leading spaces and a sign.) 9775This format always reads the longest input sequence that 9776is a valid prefix for a numeral; 9777if that prefix does not form a valid numeral 9778(e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"), 9779it is discarded and the function returns <b>nil</b>. 9780</li> 9781 9782<li><b>"<code>a</code>": </b> 9783reads the whole file, starting at the current position. 9784On end of file, it returns the empty string. 9785</li> 9786 9787<li><b>"<code>l</code>": </b> 9788reads the next line skipping the end of line, 9789returning <b>nil</b> on end of file. 9790This is the default format. 9791</li> 9792 9793<li><b>"<code>L</code>": </b> 9794reads the next line keeping the end-of-line character (if present), 9795returning <b>nil</b> on end of file. 9796</li> 9797 9798<li><b><em>number</em>: </b> 9799reads a string with up to this number of bytes, 9800returning <b>nil</b> on end of file. 9801If <code>number</code> is zero, 9802it reads nothing and returns an empty string, 9803or <b>nil</b> on end of file. 9804</li> 9805 9806</ul><p> 9807The formats "<code>l</code>" and "<code>L</code>" should be used only for text files. 9808 9809 9810 9811 9812<p> 9813<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3> 9814 9815 9816<p> 9817Sets and gets the file position, 9818measured from the beginning of the file, 9819to the position given by <code>offset</code> plus a base 9820specified by the string <code>whence</code>, as follows: 9821 9822<ul> 9823<li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li> 9824<li><b>"<code>cur</code>": </b> base is current position;</li> 9825<li><b>"<code>end</code>": </b> base is end of file;</li> 9826</ul><p> 9827In case of success, <code>seek</code> returns the final file position, 9828measured in bytes from the beginning of the file. 9829If <code>seek</code> fails, it returns <b>nil</b>, 9830plus a string describing the error. 9831 9832 9833<p> 9834The default value for <code>whence</code> is <code>"cur"</code>, 9835and for <code>offset</code> is 0. 9836Therefore, the call <code>file:seek()</code> returns the current 9837file position, without changing it; 9838the call <code>file:seek("set")</code> sets the position to the 9839beginning of the file (and returns 0); 9840and the call <code>file:seek("end")</code> sets the position to the 9841end of the file, and returns its size. 9842 9843 9844 9845 9846<p> 9847<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> 9848 9849 9850<p> 9851Sets the buffering mode for an output file. 9852There are three available modes: 9853 9854<ul> 9855 9856<li><b>"<code>no</code>": </b> 9857no buffering; the result of any output operation appears immediately. 9858</li> 9859 9860<li><b>"<code>full</code>": </b> 9861full buffering; output operation is performed only 9862when the buffer is full or when 9863you explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>). 9864</li> 9865 9866<li><b>"<code>line</code>": </b> 9867line buffering; output is buffered until a newline is output 9868or there is any input from some special files 9869(such as a terminal device). 9870</li> 9871 9872</ul><p> 9873For the last two cases, <code>size</code> 9874specifies the size of the buffer, in bytes. 9875The default is an appropriate size. 9876 9877 9878 9879 9880<p> 9881<hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> 9882 9883 9884<p> 9885Writes the value of each of its arguments to <code>file</code>. 9886The arguments must be strings or numbers. 9887 9888 9889<p> 9890In case of success, this function returns <code>file</code>. 9891Otherwise it returns <b>nil</b> plus a string describing the error. 9892 9893 9894 9895 9896 9897 9898 9899<h2>6.9 – <a name="6.9">Operating System Facilities</a></h2> 9900 9901<p> 9902This library is implemented through table <a name="pdf-os"><code>os</code></a>. 9903 9904 9905<p> 9906<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> 9907 9908 9909<p> 9910Returns an approximation of the amount in seconds of CPU time 9911used by the program. 9912 9913 9914 9915 9916<p> 9917<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> 9918 9919 9920<p> 9921Returns a string or a table containing date and time, 9922formatted according to the given string <code>format</code>. 9923 9924 9925<p> 9926If the <code>time</code> argument is present, 9927this is the time to be formatted 9928(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). 9929Otherwise, <code>date</code> formats the current time. 9930 9931 9932<p> 9933If <code>format</code> starts with '<code>!</code>', 9934then the date is formatted in Coordinated Universal Time. 9935After this optional character, 9936if <code>format</code> is the string "<code>*t</code>", 9937then <code>date</code> returns a table with the following fields: 9938<code>year</code>, <code>month</code> (1–12), <code>day</code> (1–31), 9939<code>hour</code> (0–23), <code>min</code> (0–59), <code>sec</code> (0–61), 9940<code>wday</code> (weekday, 1–7, Sunday is 1), 9941<code>yday</code> (day of the year, 1–366), 9942and <code>isdst</code> (daylight saving flag, a boolean). 9943This last field may be absent 9944if the information is not available. 9945 9946 9947<p> 9948If <code>format</code> is not "<code>*t</code>", 9949then <code>date</code> returns the date as a string, 9950formatted according to the same rules as the ISO C function <code>strftime</code>. 9951 9952 9953<p> 9954When called without arguments, 9955<code>date</code> returns a reasonable date and time representation that depends on 9956the host system and on the current locale. 9957(More specifically, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>.) 9958 9959 9960<p> 9961In non-POSIX systems, 9962this function may be not thread safe 9963because of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>. 9964 9965 9966 9967 9968<p> 9969<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> 9970 9971 9972<p> 9973Returns the difference, in seconds, 9974from time <code>t1</code> to time <code>t2</code> 9975(where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>). 9976In POSIX, Windows, and some other systems, 9977this value is exactly <code>t2</code><em>-</em><code>t1</code>. 9978 9979 9980 9981 9982<p> 9983<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> 9984 9985 9986<p> 9987This function is equivalent to the ISO C function <code>system</code>. 9988It passes <code>command</code> to be executed by an operating system shell. 9989Its first result is <b>true</b> 9990if the command terminated successfully, 9991or <b>nil</b> otherwise. 9992After this first result 9993the function returns a string plus a number, 9994as follows: 9995 9996<ul> 9997 9998<li><b>"<code>exit</code>": </b> 9999the command terminated normally; 10000the following number is the exit status of the command. 10001</li> 10002 10003<li><b>"<code>signal</code>": </b> 10004the command was terminated by a signal; 10005the following number is the signal that terminated the command. 10006</li> 10007 10008</ul> 10009 10010<p> 10011When called without a <code>command</code>, 10012<code>os.execute</code> returns a boolean that is true if a shell is available. 10013 10014 10015 10016 10017<p> 10018<hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3> 10019 10020 10021<p> 10022Calls the ISO C function <code>exit</code> to terminate the host program. 10023If <code>code</code> is <b>true</b>, 10024the returned status is <code>EXIT_SUCCESS</code>; 10025if <code>code</code> is <b>false</b>, 10026the returned status is <code>EXIT_FAILURE</code>; 10027if <code>code</code> is a number, 10028the returned status is this number. 10029The default value for <code>code</code> is <b>true</b>. 10030 10031 10032<p> 10033If the optional second argument <code>close</code> is true, 10034closes the Lua state before exiting. 10035 10036 10037 10038 10039<p> 10040<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> 10041 10042 10043<p> 10044Returns the value of the process environment variable <code>varname</code>, 10045or <b>nil</b> if the variable is not defined. 10046 10047 10048 10049 10050<p> 10051<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> 10052 10053 10054<p> 10055Deletes the file (or empty directory, on POSIX systems) 10056with the given name. 10057If this function fails, it returns <b>nil</b>, 10058plus a string describing the error and the error code. 10059Otherwise, it returns true. 10060 10061 10062 10063 10064<p> 10065<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> 10066 10067 10068<p> 10069Renames the file or directory named <code>oldname</code> to <code>newname</code>. 10070If this function fails, it returns <b>nil</b>, 10071plus a string describing the error and the error code. 10072Otherwise, it returns true. 10073 10074 10075 10076 10077<p> 10078<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> 10079 10080 10081<p> 10082Sets the current locale of the program. 10083<code>locale</code> is a system-dependent string specifying a locale; 10084<code>category</code> is an optional string describing which category to change: 10085<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, 10086<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; 10087the default category is <code>"all"</code>. 10088The function returns the name of the new locale, 10089or <b>nil</b> if the request cannot be honored. 10090 10091 10092<p> 10093If <code>locale</code> is the empty string, 10094the current locale is set to an implementation-defined native locale. 10095If <code>locale</code> is the string "<code>C</code>", 10096the current locale is set to the standard C locale. 10097 10098 10099<p> 10100When called with <b>nil</b> as the first argument, 10101this function only returns the name of the current locale 10102for the given category. 10103 10104 10105<p> 10106This function may be not thread safe 10107because of its reliance on C function <code>setlocale</code>. 10108 10109 10110 10111 10112<p> 10113<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> 10114 10115 10116<p> 10117Returns the current time when called without arguments, 10118or a time representing the local date and time specified by the given table. 10119This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, 10120and may have fields 10121<code>hour</code> (default is 12), 10122<code>min</code> (default is 0), 10123<code>sec</code> (default is 0), 10124and <code>isdst</code> (default is <b>nil</b>). 10125Other fields are ignored. 10126For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function. 10127 10128 10129<p> 10130The values in these fields do not need to be inside their valid ranges. 10131For instance, if <code>sec</code> is -10, 10132it means -10 seconds from the time specified by the other fields; 10133if <code>hour</code> is 1000, 10134it means +1000 hours from the time specified by the other fields. 10135 10136 10137<p> 10138The returned value is a number, whose meaning depends on your system. 10139In POSIX, Windows, and some other systems, 10140this number counts the number 10141of seconds since some given start time (the "epoch"). 10142In other systems, the meaning is not specified, 10143and the number returned by <code>time</code> can be used only as an argument to 10144<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. 10145 10146 10147 10148 10149<p> 10150<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> 10151 10152 10153<p> 10154Returns a string with a file name that can 10155be used for a temporary file. 10156The file must be explicitly opened before its use 10157and explicitly removed when no longer needed. 10158 10159 10160<p> 10161In POSIX systems, 10162this function also creates a file with that name, 10163to avoid security risks. 10164(Someone else might create the file with wrong permissions 10165in the time between getting the name and creating the file.) 10166You still have to open the file to use it 10167and to remove it (even if you do not use it). 10168 10169 10170<p> 10171When possible, 10172you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, 10173which automatically removes the file when the program ends. 10174 10175 10176 10177 10178 10179 10180 10181<h2>6.10 – <a name="6.10">The Debug Library</a></h2> 10182 10183<p> 10184This library provides 10185the functionality of the debug interface (<a href="#4.9">§4.9</a>) to Lua programs. 10186You should exert care when using this library. 10187Several of its functions 10188violate basic assumptions about Lua code 10189(e.g., that variables local to a function 10190cannot be accessed from outside; 10191that userdata metatables cannot be changed by Lua code; 10192that Lua programs do not crash) 10193and therefore can compromise otherwise secure code. 10194Moreover, some functions in this library may be slow. 10195 10196 10197<p> 10198All functions in this library are provided 10199inside the <a name="pdf-debug"><code>debug</code></a> table. 10200All functions that operate over a thread 10201have an optional first argument which is the 10202thread to operate over. 10203The default is always the current thread. 10204 10205 10206<p> 10207<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> 10208 10209 10210<p> 10211Enters an interactive mode with the user, 10212running each string that the user enters. 10213Using simple commands and other debug facilities, 10214the user can inspect global and local variables, 10215change their values, evaluate expressions, and so on. 10216A line containing only the word <code>cont</code> finishes this function, 10217so that the caller continues its execution. 10218 10219 10220<p> 10221Note that commands for <code>debug.debug</code> are not lexically nested 10222within any function and so have no direct access to local variables. 10223 10224 10225 10226 10227<p> 10228<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> 10229 10230 10231<p> 10232Returns the current hook settings of the thread, as three values: 10233the current hook function, the current hook mask, 10234and the current hook count 10235(as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). 10236 10237 10238 10239 10240<p> 10241<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> 10242 10243 10244<p> 10245Returns a table with information about a function. 10246You can give the function directly 10247or you can give a number as the value of <code>f</code>, 10248which means the function running at level <code>f</code> of the call stack 10249of the given thread: 10250level 0 is the current function (<code>getinfo</code> itself); 10251level 1 is the function that called <code>getinfo</code> 10252(except for tail calls, which do not count on the stack); 10253and so on. 10254If <code>f</code> is a number larger than the number of active functions, 10255then <code>getinfo</code> returns <b>nil</b>. 10256 10257 10258<p> 10259The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, 10260with the string <code>what</code> describing which fields to fill in. 10261The default for <code>what</code> is to get all information available, 10262except the table of valid lines. 10263If present, 10264the option '<code>f</code>' 10265adds a field named <code>func</code> with the function itself. 10266If present, 10267the option '<code>L</code>' 10268adds a field named <code>activelines</code> with the table of 10269valid lines. 10270 10271 10272<p> 10273For instance, the expression <code>debug.getinfo(1,"n").name</code> returns 10274a name for the current function, 10275if a reasonable name can be found, 10276and the expression <code>debug.getinfo(print)</code> 10277returns a table with all available information 10278about the <a href="#pdf-print"><code>print</code></a> function. 10279 10280 10281 10282 10283<p> 10284<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3> 10285 10286 10287<p> 10288This function returns the name and the value of the local variable 10289with index <code>local</code> of the function at level <code>f</code> of the stack. 10290This function accesses not only explicit local variables, 10291but also parameters, temporaries, etc. 10292 10293 10294<p> 10295The first parameter or local variable has index 1, and so on, 10296following the order that they are declared in the code, 10297counting only the variables that are active 10298in the current scope of the function. 10299Negative indices refer to vararg arguments; 10300-1 is the first vararg argument. 10301The function returns <b>nil</b> if there is no variable with the given index, 10302and raises an error when called with a level out of range. 10303(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) 10304 10305 10306<p> 10307Variable names starting with '<code>(</code>' (open parenthesis) 10308represent variables with no known names 10309(internal variables such as loop control variables, 10310and variables from chunks saved without debug information). 10311 10312 10313<p> 10314The parameter <code>f</code> may also be a function. 10315In that case, <code>getlocal</code> returns only the name of function parameters. 10316 10317 10318 10319 10320<p> 10321<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3> 10322 10323 10324<p> 10325Returns the metatable of the given <code>value</code> 10326or <b>nil</b> if it does not have a metatable. 10327 10328 10329 10330 10331<p> 10332<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> 10333 10334 10335<p> 10336Returns the registry table (see <a href="#4.5">§4.5</a>). 10337 10338 10339 10340 10341<p> 10342<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3> 10343 10344 10345<p> 10346This function returns the name and the value of the upvalue 10347with index <code>up</code> of the function <code>f</code>. 10348The function returns <b>nil</b> if there is no upvalue with the given index. 10349 10350 10351<p> 10352Variable names starting with '<code>(</code>' (open parenthesis) 10353represent variables with no known names 10354(variables from chunks saved without debug information). 10355 10356 10357 10358 10359<p> 10360<hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3> 10361 10362 10363<p> 10364Returns the Lua value associated to <code>u</code>. 10365If <code>u</code> is not a full userdata, 10366returns <b>nil</b>. 10367 10368 10369 10370 10371<p> 10372<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> 10373 10374 10375<p> 10376Sets the given function as a hook. 10377The string <code>mask</code> and the number <code>count</code> describe 10378when the hook will be called. 10379The string mask may have any combination of the following characters, 10380with the given meaning: 10381 10382<ul> 10383<li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li> 10384<li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li> 10385<li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li> 10386</ul><p> 10387Moreover, 10388with a <code>count</code> different from zero, 10389the hook is called also after every <code>count</code> instructions. 10390 10391 10392<p> 10393When called without arguments, 10394<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. 10395 10396 10397<p> 10398When the hook is called, its first argument is a string 10399describing the event that has triggered its call: 10400<code>"call"</code> (or <code>"tail call"</code>), 10401<code>"return"</code>, 10402<code>"line"</code>, and <code>"count"</code>. 10403For line events, 10404the hook also gets the new line number as its second parameter. 10405Inside a hook, 10406you can call <code>getinfo</code> with level 2 to get more information about 10407the running function 10408(level 0 is the <code>getinfo</code> function, 10409and level 1 is the hook function). 10410 10411 10412 10413 10414<p> 10415<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> 10416 10417 10418<p> 10419This function assigns the value <code>value</code> to the local variable 10420with index <code>local</code> of the function at level <code>level</code> of the stack. 10421The function returns <b>nil</b> if there is no local 10422variable with the given index, 10423and raises an error when called with a <code>level</code> out of range. 10424(You can call <code>getinfo</code> to check whether the level is valid.) 10425Otherwise, it returns the name of the local variable. 10426 10427 10428<p> 10429See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about 10430variable indices and names. 10431 10432 10433 10434 10435<p> 10436<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> 10437 10438 10439<p> 10440Sets the metatable for the given <code>value</code> to the given <code>table</code> 10441(which can be <b>nil</b>). 10442Returns <code>value</code>. 10443 10444 10445 10446 10447<p> 10448<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> 10449 10450 10451<p> 10452This function assigns the value <code>value</code> to the upvalue 10453with index <code>up</code> of the function <code>f</code>. 10454The function returns <b>nil</b> if there is no upvalue 10455with the given index. 10456Otherwise, it returns the name of the upvalue. 10457 10458 10459 10460 10461<p> 10462<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3> 10463 10464 10465<p> 10466Sets the given <code>value</code> as 10467the Lua value associated to the given <code>udata</code>. 10468<code>udata</code> must be a full userdata. 10469 10470 10471<p> 10472Returns <code>udata</code>. 10473 10474 10475 10476 10477<p> 10478<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> 10479 10480 10481<p> 10482If <code>message</code> is present but is neither a string nor <b>nil</b>, 10483this function returns <code>message</code> without further processing. 10484Otherwise, 10485it returns a string with a traceback of the call stack. 10486The optional <code>message</code> string is appended 10487at the beginning of the traceback. 10488An optional <code>level</code> number tells at which level 10489to start the traceback 10490(default is 1, the function calling <code>traceback</code>). 10491 10492 10493 10494 10495<p> 10496<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3> 10497 10498 10499<p> 10500Returns a unique identifier (as a light userdata) 10501for the upvalue numbered <code>n</code> 10502from the given function. 10503 10504 10505<p> 10506These unique identifiers allow a program to check whether different 10507closures share upvalues. 10508Lua closures that share an upvalue 10509(that is, that access a same external local variable) 10510will return identical ids for those upvalue indices. 10511 10512 10513 10514 10515<p> 10516<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3> 10517 10518 10519<p> 10520Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code> 10521refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>. 10522 10523 10524 10525 10526 10527 10528 10529<h1>7 – <a name="7">Lua Standalone</a></h1> 10530 10531<p> 10532Although Lua has been designed as an extension language, 10533to be embedded in a host C program, 10534it is also frequently used as a standalone language. 10535An interpreter for Lua as a standalone language, 10536called simply <code>lua</code>, 10537is provided with the standard distribution. 10538The standalone interpreter includes 10539all standard libraries, including the debug library. 10540Its usage is: 10541 10542<pre> 10543 lua [options] [script [args]] 10544</pre><p> 10545The options are: 10546 10547<ul> 10548<li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li> 10549<li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em> and assigns the 10550 result to global @<em>mod</em>;</li> 10551<li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li> 10552<li><b><code>-v</code>: </b> prints version information;</li> 10553<li><b><code>-E</code>: </b> ignores environment variables;</li> 10554<li><b><code>--</code>: </b> stops handling options;</li> 10555<li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li> 10556</ul><p> 10557After handling its options, <code>lua</code> runs the given <em>script</em>. 10558When called without arguments, 10559<code>lua</code> behaves as <code>lua -v -i</code> 10560when the standard input (<code>stdin</code>) is a terminal, 10561and as <code>lua -</code> otherwise. 10562 10563 10564<p> 10565When called without option <code>-E</code>, 10566the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a> 10567(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined) 10568before running any argument. 10569If the variable content has the format <code>@<em>filename</em></code>, 10570then <code>lua</code> executes the file. 10571Otherwise, <code>lua</code> executes the string itself. 10572 10573 10574<p> 10575When called with option <code>-E</code>, 10576besides ignoring <code>LUA_INIT</code>, 10577Lua also ignores 10578the values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>, 10579setting the values of 10580<a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a> 10581with the default paths defined in <code>luaconf.h</code>. 10582 10583 10584<p> 10585All options are handled in order, except <code>-i</code> and <code>-E</code>. 10586For instance, an invocation like 10587 10588<pre> 10589 $ lua -e'a=1' -e 'print(a)' script.lua 10590</pre><p> 10591will first set <code>a</code> to 1, then print the value of <code>a</code>, 10592and finally run the file <code>script.lua</code> with no arguments. 10593(Here <code>$</code> is the shell prompt. Your prompt may be different.) 10594 10595 10596<p> 10597Before running any code, 10598<code>lua</code> collects all command-line arguments 10599in a global table called <code>arg</code>. 10600The script name goes to index 0, 10601the first argument after the script name goes to index 1, 10602and so on. 10603Any arguments before the script name 10604(that is, the interpreter name plus its options) 10605go to negative indices. 10606For instance, in the call 10607 10608<pre> 10609 $ lua -la b.lua t1 t2 10610</pre><p> 10611the table is like this: 10612 10613<pre> 10614 arg = { [-2] = "lua", [-1] = "-la", 10615 [0] = "b.lua", 10616 [1] = "t1", [2] = "t2" } 10617</pre><p> 10618If there is no script in the call, 10619the interpreter name goes to index 0, 10620followed by the other arguments. 10621For instance, the call 10622 10623<pre> 10624 $ lua -e "print(arg[1])" 10625</pre><p> 10626will print "<code>-e</code>". 10627If there is a script, 10628the script is called with arguments 10629<code>arg[1]</code>, ···, <code>arg[#arg]</code>. 10630(Like all chunks in Lua, 10631the script is compiled as a vararg function.) 10632 10633 10634<p> 10635In interactive mode, 10636Lua repeatedly prompts and waits for a line. 10637After reading a line, 10638Lua first try to interpret the line as an expression. 10639If it succeeds, it prints its value. 10640Otherwise, it interprets the line as a statement. 10641If you write an incomplete statement, 10642the interpreter waits for its completion 10643by issuing a different prompt. 10644 10645 10646<p> 10647If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, 10648then its value is used as the prompt. 10649Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, 10650its value is used as the secondary prompt 10651(issued during incomplete statements). 10652 10653 10654<p> 10655In case of unprotected errors in the script, 10656the interpreter reports the error to the standard error stream. 10657If the error object is not a string but 10658has a metamethod <code>__tostring</code>, 10659the interpreter calls this metamethod to produce the final message. 10660Otherwise, the interpreter converts the error object to a string 10661and adds a stack traceback to it. 10662 10663 10664<p> 10665When finishing normally, 10666the interpreter closes its main Lua state 10667(see <a href="#lua_close"><code>lua_close</code></a>). 10668The script can avoid this step by 10669calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate. 10670 10671 10672<p> 10673To allow the use of Lua as a 10674script interpreter in Unix systems, 10675the standalone interpreter skips 10676the first line of a chunk if it starts with <code>#</code>. 10677Therefore, Lua scripts can be made into executable programs 10678by using <code>chmod +x</code> and the <code>#!</code> form, 10679as in 10680 10681<pre> 10682 #!/usr/local/bin/lua 10683</pre><p> 10684(Of course, 10685the location of the Lua interpreter may be different in your machine. 10686If <code>lua</code> is in your <code>PATH</code>, 10687then 10688 10689<pre> 10690 #!/usr/bin/env lua 10691</pre><p> 10692is a more portable solution.) 10693 10694 10695 10696<h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> 10697 10698<p> 10699Here we list the incompatibilities that you may find when moving a program 10700from Lua 5.2 to Lua 5.3. 10701You can avoid some incompatibilities by compiling Lua with 10702appropriate options (see file <code>luaconf.h</code>). 10703However, 10704all these compatibility options will be removed in the future. 10705 10706 10707<p> 10708Lua versions can always change the C API in ways that 10709do not imply source-code changes in a program, 10710such as the numeric values for constants 10711or the implementation of functions as macros. 10712Therefore, 10713you should not assume that binaries are compatible between 10714different Lua versions. 10715Always recompile clients of the Lua API when 10716using a new version. 10717 10718 10719<p> 10720Similarly, Lua versions can always change the internal representation 10721of precompiled chunks; 10722precompiled chunks are not compatible between different Lua versions. 10723 10724 10725<p> 10726The standard paths in the official distribution may 10727change between versions. 10728 10729 10730 10731<h2>8.1 – <a name="8.1">Changes in the Language</a></h2> 10732<ul> 10733 10734<li> 10735The main difference between Lua 5.2 and Lua 5.3 is the 10736introduction of an integer subtype for numbers. 10737Although this change should not affect "normal" computations, 10738some computations 10739(mainly those that involve some kind of overflow) 10740can give different results. 10741 10742 10743<p> 10744You can fix these differences by forcing a number to be a float 10745(in Lua 5.2 all numbers were float), 10746in particular writing constants with an ending <code>.0</code> 10747or using <code>x = x + 0.0</code> to convert a variable. 10748(This recommendation is only for a quick fix 10749for an occasional incompatibility; 10750it is not a general guideline for good programming. 10751For good programming, 10752use floats where you need floats 10753and integers where you need integers.) 10754</li> 10755 10756<li> 10757The conversion of a float to a string now adds a <code>.0</code> suffix 10758to the result if it looks like an integer. 10759(For instance, the float 2.0 will be printed as <code>2.0</code>, 10760not as <code>2</code>.) 10761You should always use an explicit format 10762when you need a specific format for numbers. 10763 10764 10765<p> 10766(Formally this is not an incompatibility, 10767because Lua does not specify how numbers are formatted as strings, 10768but some programs assumed a specific format.) 10769</li> 10770 10771<li> 10772The generational mode for the garbage collector was removed. 10773(It was an experimental feature in Lua 5.2.) 10774</li> 10775 10776</ul> 10777 10778 10779 10780 10781<h2>8.2 – <a name="8.2">Changes in the Libraries</a></h2> 10782<ul> 10783 10784<li> 10785The <code>bit32</code> library has been deprecated. 10786It is easy to require a compatible external library or, 10787better yet, to replace its functions with appropriate bitwise operations. 10788(Keep in mind that <code>bit32</code> operates on 32-bit integers, 10789while the bitwise operators in Lua 5.3 operate on Lua integers, 10790which by default have 64 bits.) 10791</li> 10792 10793<li> 10794The Table library now respects metamethods 10795for setting and getting elements. 10796</li> 10797 10798<li> 10799The <a href="#pdf-ipairs"><code>ipairs</code></a> iterator now respects metamethods and 10800its <code>__ipairs</code> metamethod has been deprecated. 10801</li> 10802 10803<li> 10804Option names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore. 10805For compatibility, Lua will continue to accept (and ignore) this character. 10806</li> 10807 10808<li> 10809The following functions were deprecated in the mathematical library: 10810<code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>, 10811<code>frexp</code>, and <code>ldexp</code>. 10812You can replace <code>math.pow(x,y)</code> with <code>x^y</code>; 10813you can replace <code>math.atan2</code> with <code>math.atan</code>, 10814which now accepts one or two arguments; 10815you can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>. 10816For the other operations, 10817you can either use an external library or 10818implement them in Lua. 10819</li> 10820 10821<li> 10822The searcher for C loaders used by <a href="#pdf-require"><code>require</code></a> 10823changed the way it handles versioned names. 10824Now, the version should come after the module name 10825(as is usual in most other tools). 10826For compatibility, that searcher still tries the old format 10827if it cannot find an open function according to the new style. 10828(Lua 5.2 already worked that way, 10829but it did not document the change.) 10830</li> 10831 10832<li> 10833The call <code>collectgarbage("count")</code> now returns only one result. 10834(You can compute that second result from the fractional part 10835of the first result.) 10836</li> 10837 10838</ul> 10839 10840 10841 10842 10843<h2>8.3 – <a name="8.3">Changes in the API</a></h2> 10844 10845 10846<ul> 10847 10848<li> 10849Continuation functions now receive as arguments what they needed 10850to get through <code>lua_getctx</code>, 10851so <code>lua_getctx</code> has been removed. 10852Adapt your code accordingly. 10853</li> 10854 10855<li> 10856Function <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>. 10857Use 0 as the value of this parameter to get the old behavior. 10858</li> 10859 10860<li> 10861Functions to inject/project unsigned integers 10862(<code>lua_pushunsigned</code>, <code>lua_tounsigned</code>, <code>lua_tounsignedx</code>, 10863<code>luaL_checkunsigned</code>, <code>luaL_optunsigned</code>) 10864were deprecated. 10865Use their signed equivalents with a type cast. 10866</li> 10867 10868<li> 10869Macros to project non-default integer types 10870(<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>) 10871were deprecated. 10872Use their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast 10873(or, when possible, use <a href="#lua_Integer"><code>lua_Integer</code></a> in your code). 10874</li> 10875 10876</ul> 10877 10878 10879 10880 10881<h1>9 – <a name="9">The Complete Syntax of Lua</a></h1> 10882 10883<p> 10884Here is the complete syntax of Lua in extended BNF. 10885As usual in extended BNF, 10886{A} means 0 or more As, 10887and [A] means an optional A. 10888(For operator precedences, see <a href="#3.4.8">§3.4.8</a>; 10889for a description of the terminals 10890Name, Numeral, 10891and LiteralString, see <a href="#3.1">§3.1</a>.) 10892 10893 10894 10895 10896<pre> 10897 10898 chunk ::= block 10899 10900 block ::= {stat} [retstat] 10901 10902 stat ::= ‘<b>;</b>’ | 10903 varlist ‘<b>=</b>’ explist | 10904 functioncall | 10905 label | 10906 <b>break</b> | 10907 <b>goto</b> Name | 10908 <b>do</b> block <b>end</b> | 10909 <b>while</b> exp <b>do</b> block <b>end</b> | 10910 <b>repeat</b> block <b>until</b> exp | 10911 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 10912 <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> | 10913 <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 10914 <b>function</b> funcname funcbody | 10915 <b>local</b> <b>function</b> Name funcbody | 10916 <b>local</b> namelist [‘<b>=</b>’ explist] 10917 10918 retstat ::= <b>return</b> [explist] [‘<b>;</b>’] 10919 10920 label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 10921 10922 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 10923 10924 varlist ::= var {‘<b>,</b>’ var} 10925 10926 var ::= Name | prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | prefixexp ‘<b>.</b>’ Name 10927 10928 namelist ::= Name {‘<b>,</b>’ Name} 10929 10930 explist ::= exp {‘<b>,</b>’ exp} 10931 10932 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | ‘<b>...</b>’ | functiondef | 10933 prefixexp | tableconstructor | exp binop exp | unop exp 10934 10935 prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 10936 10937 functioncall ::= prefixexp args | prefixexp ‘<b>:</b>’ Name args 10938 10939 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | tableconstructor | LiteralString 10940 10941 functiondef ::= <b>function</b> funcbody 10942 10943 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 10944 10945 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 10946 10947 tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 10948 10949 fieldlist ::= field {fieldsep field} [fieldsep] 10950 10951 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 10952 10953 fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 10954 10955 binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</b>’ | ‘<b>//</b>’ | ‘<b>^</b>’ | ‘<b>%</b>’ | 10956 ‘<b>&</b>’ | ‘<b>~</b>’ | ‘<b>|</b>’ | ‘<b>>></b>’ | ‘<b><<</b>’ | ‘<b>..</b>’ | 10957 ‘<b><</b>’ | ‘<b><=</b>’ | ‘<b>></b>’ | ‘<b>>=</b>’ | ‘<b>==</b>’ | ‘<b>~=</b>’ | 10958 <b>and</b> | <b>or</b> 10959 10960 unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’ | ‘<b>~</b>’ 10961 10962</pre> 10963 10964<p> 10965 10966 10967 10968 10969 10970 10971 10972 10973<P CLASS="footer"> 10974Last update: 10975Tue Jun 26 13:16:37 -03 2018 10976</P> 10977<!-- 10978Last change: revised for Lua 5.3.5 10979--> 10980 10981</body></html> 10982 10983
