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–2017 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 2017/01/09 15:18:11 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 be indexed not only with numbers, 207but with 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. 403 404 405<p> 406You can query the metatable of any value 407using the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function. 408Lua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>). 409So, to retrieve the metamethod for event <code>ev</code> in object <code>o</code>, 410Lua does the equivalent to the following code: 411 412<pre> 413 rawget(getmetatable(<em>o</em>) or {}, "__<em>ev</em>") 414</pre> 415 416<p> 417You can replace the metatable of tables 418using the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function. 419You cannot change the metatable of other types from Lua code 420(except by using the debug library (<a href="#6.10">§6.10</a>)); 421you should use the C API for that. 422 423 424<p> 425Tables and full userdata have individual metatables 426(although multiple tables and userdata can share their metatables). 427Values of all other types share one single metatable per type; 428that is, there is one single metatable for all numbers, 429one for all strings, etc. 430By default, a value has no metatable, 431but the string library sets a metatable for the string type (see <a href="#6.4">§6.4</a>). 432 433 434<p> 435A metatable controls how an object behaves in 436arithmetic operations, bitwise operations, 437order comparisons, concatenation, length operation, calls, and indexing. 438A metatable also can define a function to be called 439when a userdata or a table is garbage collected (<a href="#2.5">§2.5</a>). 440 441 442<p> 443For the unary operators (negation, length, and bitwise NOT), 444the metamethod is computed and called with a dummy second operand, 445equal to the first one. 446This extra operand is only to simplify Lua's internals 447(by making these operators behave like a binary operation) 448and may be removed in future versions. 449(For most uses this extra operand is irrelevant.) 450 451 452<p> 453A detailed list of events controlled by metatables is given next. 454Each operation is identified by its corresponding key. 455 456 457 458<ul> 459 460<li><b><code>__add</code>: </b> 461the addition (<code>+</code>) operation. 462If any operand for an addition is not a number 463(nor a string coercible to a number), 464Lua will try to call a metamethod. 465First, Lua will check the first operand (even if it is valid). 466If that operand does not define a metamethod for <code>__add</code>, 467then Lua will check the second operand. 468If Lua can find a metamethod, 469it calls the metamethod with the two operands as arguments, 470and the result of the call 471(adjusted to one value) 472is the result of the operation. 473Otherwise, 474it raises an error. 475</li> 476 477<li><b><code>__sub</code>: </b> 478the subtraction (<code>-</code>) operation. 479Behavior similar to the addition operation. 480</li> 481 482<li><b><code>__mul</code>: </b> 483the multiplication (<code>*</code>) operation. 484Behavior similar to the addition operation. 485</li> 486 487<li><b><code>__div</code>: </b> 488the division (<code>/</code>) operation. 489Behavior similar to the addition operation. 490</li> 491 492<li><b><code>__mod</code>: </b> 493the modulo (<code>%</code>) operation. 494Behavior similar to the addition operation. 495</li> 496 497<li><b><code>__pow</code>: </b> 498the exponentiation (<code>^</code>) operation. 499Behavior similar to the addition operation. 500</li> 501 502<li><b><code>__unm</code>: </b> 503the negation (unary <code>-</code>) operation. 504Behavior similar to the addition operation. 505</li> 506 507<li><b><code>__idiv</code>: </b> 508the floor division (<code>//</code>) operation. 509Behavior similar to the addition operation. 510</li> 511 512<li><b><code>__band</code>: </b> 513the bitwise AND (<code>&</code>) operation. 514Behavior similar to the addition operation, 515except that Lua will try a metamethod 516if any operand is neither an integer 517nor a value coercible to an integer (see <a href="#3.4.3">§3.4.3</a>). 518</li> 519 520<li><b><code>__bor</code>: </b> 521the bitwise OR (<code>|</code>) operation. 522Behavior similar to the bitwise AND operation. 523</li> 524 525<li><b><code>__bxor</code>: </b> 526the bitwise exclusive OR (binary <code>~</code>) operation. 527Behavior similar to the bitwise AND operation. 528</li> 529 530<li><b><code>__bnot</code>: </b> 531the bitwise NOT (unary <code>~</code>) operation. 532Behavior similar to the bitwise AND operation. 533</li> 534 535<li><b><code>__shl</code>: </b> 536the bitwise left shift (<code><<</code>) operation. 537Behavior similar to the bitwise AND operation. 538</li> 539 540<li><b><code>__shr</code>: </b> 541the bitwise right shift (<code>>></code>) operation. 542Behavior similar to the bitwise AND operation. 543</li> 544 545<li><b><code>__concat</code>: </b> 546the concatenation (<code>..</code>) operation. 547Behavior similar to the addition operation, 548except that Lua will try a metamethod 549if any operand is neither a string nor a number 550(which is always coercible to a string). 551</li> 552 553<li><b><code>__len</code>: </b> 554the length (<code>#</code>) operation. 555If the object is not a string, 556Lua will try its metamethod. 557If there is a metamethod, 558Lua calls it with the object as argument, 559and the result of the call 560(always adjusted to one value) 561is the result of the operation. 562If there is no metamethod but the object is a table, 563then Lua uses the table length operation (see <a href="#3.4.7">§3.4.7</a>). 564Otherwise, Lua raises an error. 565</li> 566 567<li><b><code>__eq</code>: </b> 568the equal (<code>==</code>) operation. 569Behavior similar to the addition operation, 570except that Lua will try a metamethod only when the values 571being compared are either both tables or both full userdata 572and they are not primitively equal. 573The result of the call is always converted to a boolean. 574</li> 575 576<li><b><code>__lt</code>: </b> 577the less than (<code><</code>) operation. 578Behavior similar to the addition operation, 579except that Lua will try a metamethod only when the values 580being compared are neither both numbers nor both strings. 581The result of the call is always converted to a boolean. 582</li> 583 584<li><b><code>__le</code>: </b> 585the less equal (<code><=</code>) operation. 586Unlike other operations, 587the less-equal operation can use two different events. 588First, Lua looks for the <code>__le</code> metamethod in both operands, 589like in the less than operation. 590If it cannot find such a metamethod, 591then it will try the <code>__lt</code> metamethod, 592assuming that <code>a <= b</code> is equivalent to <code>not (b < a)</code>. 593As with the other comparison operators, 594the result is always a boolean. 595(This use of the <code>__lt</code> event can be removed in future versions; 596it is also slower than a real <code>__le</code> metamethod.) 597</li> 598 599<li><b><code>__index</code>: </b> 600The indexing access <code>table[key]</code>. 601This event happens when <code>table</code> is not a table or 602when <code>key</code> is not present in <code>table</code>. 603The metamethod is looked up in <code>table</code>. 604 605 606<p> 607Despite the name, 608the metamethod for this event can be either a function or a table. 609If it is a function, 610it is called with <code>table</code> and <code>key</code> as arguments, 611and the result of the call 612(adjusted to one value) 613is the result of the operation. 614If it is a table, 615the final result is the result of indexing this table with <code>key</code>. 616(This indexing is regular, not raw, 617and therefore can trigger another metamethod.) 618</li> 619 620<li><b><code>__newindex</code>: </b> 621The indexing assignment <code>table[key] = value</code>. 622Like the index event, 623this event happens when <code>table</code> is not a table or 624when <code>key</code> is not present in <code>table</code>. 625The metamethod is looked up in <code>table</code>. 626 627 628<p> 629Like with indexing, 630the metamethod for this event can be either a function or a table. 631If it is a function, 632it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments. 633If it is a table, 634Lua does an indexing assignment to this table with the same key and value. 635(This assignment is regular, not raw, 636and therefore can trigger another metamethod.) 637 638 639<p> 640Whenever there is a <code>__newindex</code> metamethod, 641Lua does not perform the primitive assignment. 642(If necessary, 643the metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a> 644to do the assignment.) 645</li> 646 647<li><b><code>__call</code>: </b> 648The call operation <code>func(args)</code>. 649This event happens when Lua tries to call a non-function value 650(that is, <code>func</code> is not a function). 651The metamethod is looked up in <code>func</code>. 652If present, 653the metamethod is called with <code>func</code> as its first argument, 654followed by the arguments of the original call (<code>args</code>). 655All results of the call 656are the result of the operation. 657(This is the only metamethod that allows multiple results.) 658</li> 659 660</ul> 661 662<p> 663It is a good practice to add all needed metamethods to a table 664before setting it as a metatable of some object. 665In particular, the <code>__gc</code> metamethod works only when this order 666is followed (see <a href="#2.5.1">§2.5.1</a>). 667 668 669<p> 670Because metatables are regular tables, 671they can contain arbitrary fields, 672not only the event names defined above. 673Some functions in the standard library 674(e.g., <a href="#pdf-tostring"><code>tostring</code></a>) 675use other fields in metatables for their own purposes. 676 677 678 679 680 681<h2>2.5 – <a name="2.5">Garbage Collection</a></h2> 682 683<p> 684Lua performs automatic memory management. 685This means that 686you do not have to worry about allocating memory for new objects 687or freeing it when the objects are no longer needed. 688Lua manages memory automatically by running 689a <em>garbage collector</em> to collect all <em>dead objects</em> 690(that is, objects that are no longer accessible from Lua). 691All memory used by Lua is subject to automatic management: 692strings, tables, userdata, functions, threads, internal structures, etc. 693 694 695<p> 696Lua implements an incremental mark-and-sweep collector. 697It uses two numbers to control its garbage-collection cycles: 698the <em>garbage-collector pause</em> and 699the <em>garbage-collector step multiplier</em>. 700Both use percentage points as units 701(e.g., a value of 100 means an internal value of 1). 702 703 704<p> 705The garbage-collector pause 706controls how long the collector waits before starting a new cycle. 707Larger values make the collector less aggressive. 708Values smaller than 100 mean the collector will not wait to 709start a new cycle. 710A value of 200 means that the collector waits for the total memory in use 711to double before starting a new cycle. 712 713 714<p> 715The garbage-collector step multiplier 716controls the relative speed of the collector relative to 717memory allocation. 718Larger values make the collector more aggressive but also increase 719the size of each incremental step. 720You should not use values smaller than 100, 721because they make the collector too slow and 722can result in the collector never finishing a cycle. 723The default is 200, 724which means that the collector runs at "twice" 725the speed of memory allocation. 726 727 728<p> 729If you set the step multiplier to a very large number 730(larger than 10% of the maximum number of 731bytes that the program may use), 732the collector behaves like a stop-the-world collector. 733If you then set the pause to 200, 734the collector behaves as in old Lua versions, 735doing a complete collection every time Lua doubles its 736memory usage. 737 738 739<p> 740You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C 741or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. 742You can also use these functions to control 743the collector directly (e.g., stop and restart it). 744 745 746 747<h3>2.5.1 – <a name="2.5.1">Garbage-Collection Metamethods</a></h3> 748 749<p> 750You can set garbage-collector metamethods for tables 751and, using the C API, 752for full userdata (see <a href="#2.4">§2.4</a>). 753These metamethods are also called <em>finalizers</em>. 754Finalizers allow you to coordinate Lua's garbage collection 755with external resource management 756(such as closing files, network or database connections, 757or freeing your own memory). 758 759 760<p> 761For an object (table or userdata) to be finalized when collected, 762you must <em>mark</em> it for finalization. 763 764You mark an object for finalization when you set its metatable 765and the metatable has a field indexed by the string "<code>__gc</code>". 766Note that if you set a metatable without a <code>__gc</code> field 767and later create that field in the metatable, 768the object will not be marked for finalization. 769 770 771<p> 772When a marked object becomes garbage, 773it is not collected immediately by the garbage collector. 774Instead, Lua puts it in a list. 775After the collection, 776Lua goes through that list. 777For each object in the list, 778it checks the object's <code>__gc</code> metamethod: 779If it is a function, 780Lua calls it with the object as its single argument; 781if the metamethod is not a function, 782Lua simply ignores it. 783 784 785<p> 786At the end of each garbage-collection cycle, 787the finalizers for objects are called in 788the reverse order that the objects were marked for finalization, 789among those collected in that cycle; 790that is, the first finalizer to be called is the one associated 791with the object marked last in the program. 792The execution of each finalizer may occur at any point during 793the execution of the regular code. 794 795 796<p> 797Because the object being collected must still be used by the finalizer, 798that object (and other objects accessible only through it) 799must be <em>resurrected</em> by Lua. 800Usually, this resurrection is transient, 801and the object memory is freed in the next garbage-collection cycle. 802However, if the finalizer stores the object in some global place 803(e.g., a global variable), 804then the resurrection is permanent. 805Moreover, if the finalizer marks a finalizing object for finalization again, 806its finalizer will be called again in the next cycle where the 807object is unreachable. 808In any case, 809the object memory is freed only in a GC cycle where 810the object is unreachable and not marked for finalization. 811 812 813<p> 814When you close a state (see <a href="#lua_close"><code>lua_close</code></a>), 815Lua calls the finalizers of all objects marked for finalization, 816following the reverse order that they were marked. 817If any finalizer marks objects for collection during that phase, 818these marks have no effect. 819 820 821 822 823 824<h3>2.5.2 – <a name="2.5.2">Weak Tables</a></h3> 825 826<p> 827A <em>weak table</em> is a table whose elements are 828<em>weak references</em>. 829A weak reference is ignored by the garbage collector. 830In other words, 831if the only references to an object are weak references, 832then the garbage collector will collect that object. 833 834 835<p> 836A weak table can have weak keys, weak values, or both. 837A table with weak values allows the collection of its values, 838but prevents the collection of its keys. 839A table with both weak keys and weak values allows the collection of 840both keys and values. 841In any case, if either the key or the value is collected, 842the whole pair is removed from the table. 843The weakness of a table is controlled by the 844<code>__mode</code> field of its metatable. 845If the <code>__mode</code> field is a string containing the character '<code>k</code>', 846the keys in the table are weak. 847If <code>__mode</code> contains '<code>v</code>', 848the values in the table are weak. 849 850 851<p> 852A table with weak keys and strong values 853is also called an <em>ephemeron table</em>. 854In an ephemeron table, 855a value is considered reachable only if its key is reachable. 856In particular, 857if the only reference to a key comes through its value, 858the pair is removed. 859 860 861<p> 862Any change in the weakness of a table may take effect only 863at the next collect cycle. 864In particular, if you change the weakness to a stronger mode, 865Lua may still collect some items from that table 866before the change takes effect. 867 868 869<p> 870Only objects that have an explicit construction 871are removed from weak tables. 872Values, such as numbers and light C functions, 873are not subject to garbage collection, 874and therefore are not removed from weak tables 875(unless their associated values are collected). 876Although strings are subject to garbage collection, 877they do not have an explicit construction, 878and therefore are not removed from weak tables. 879 880 881<p> 882Resurrected objects 883(that is, objects being finalized 884and objects accessible only through objects being finalized) 885have a special behavior in weak tables. 886They are removed from weak values before running their finalizers, 887but are removed from weak keys only in the next collection 888after running their finalizers, when such objects are actually freed. 889This behavior allows the finalizer to access properties 890associated with the object through weak tables. 891 892 893<p> 894If a weak table is among the resurrected objects in a collection cycle, 895it may not be properly cleared until the next cycle. 896 897 898 899 900 901 902 903<h2>2.6 – <a name="2.6">Coroutines</a></h2> 904 905<p> 906Lua supports coroutines, 907also called <em>collaborative multithreading</em>. 908A coroutine in Lua represents an independent thread of execution. 909Unlike threads in multithread systems, however, 910a coroutine only suspends its execution by explicitly calling 911a yield function. 912 913 914<p> 915You create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>. 916Its sole argument is a function 917that is the main function of the coroutine. 918The <code>create</code> function only creates a new coroutine and 919returns a handle to it (an object of type <em>thread</em>); 920it does not start the coroutine. 921 922 923<p> 924You execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 925When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 926passing as its first argument 927a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 928the coroutine starts its execution by 929calling its main function. 930Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed 931as arguments to that function. 932After the coroutine starts running, 933it runs until it terminates or <em>yields</em>. 934 935 936<p> 937A coroutine can terminate its execution in two ways: 938normally, when its main function returns 939(explicitly or implicitly, after the last instruction); 940and abnormally, if there is an unprotected error. 941In case of normal termination, 942<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>, 943plus any values returned by the coroutine main function. 944In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b> 945plus an error object. 946 947 948<p> 949A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 950When a coroutine yields, 951the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately, 952even if the yield happens inside nested function calls 953(that is, not in the main function, 954but in a function directly or indirectly called by the main function). 955In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>, 956plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 957The next time you resume the same coroutine, 958it continues its execution from the point where it yielded, 959with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra 960arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 961 962 963<p> 964Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 965the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine, 966but instead of returning the coroutine itself, 967it returns a function that, when called, resumes the coroutine. 968Any arguments passed to this function 969go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 970<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>, 971except the first one (the boolean error code). 972Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 973<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors; 974any error is propagated to the caller. 975 976 977<p> 978As an example of how coroutines work, 979consider the following code: 980 981<pre> 982 function foo (a) 983 print("foo", a) 984 return coroutine.yield(2*a) 985 end 986 987 co = coroutine.create(function (a,b) 988 print("co-body", a, b) 989 local r = foo(a+1) 990 print("co-body", r) 991 local r, s = coroutine.yield(a+b, a-b) 992 print("co-body", r, s) 993 return b, "end" 994 end) 995 996 print("main", coroutine.resume(co, 1, 10)) 997 print("main", coroutine.resume(co, "r")) 998 print("main", coroutine.resume(co, "x", "y")) 999 print("main", coroutine.resume(co, "x", "y")) 1000</pre><p> 1001When you run it, it produces the following output: 1002 1003<pre> 1004 co-body 1 10 1005 foo 2 1006 main true 4 1007 co-body r 1008 main true 11 -9 1009 co-body x y 1010 main true 10 end 1011 main false cannot resume dead coroutine 1012</pre> 1013 1014<p> 1015You can also create and manipulate coroutines through the C API: 1016see functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>, 1017and <a href="#lua_yield"><code>lua_yield</code></a>. 1018 1019 1020 1021 1022 1023<h1>3 – <a name="3">The Language</a></h1> 1024 1025<p> 1026This section describes the lexis, the syntax, and the semantics of Lua. 1027In other words, 1028this section describes 1029which tokens are valid, 1030how they can be combined, 1031and what their combinations mean. 1032 1033 1034<p> 1035Language constructs will be explained using the usual extended BNF notation, 1036in which 1037{<em>a</em>} means 0 or more <em>a</em>'s, and 1038[<em>a</em>] means an optional <em>a</em>. 1039Non-terminals are shown like non-terminal, 1040keywords are shown like <b>kword</b>, 1041and other terminal symbols are shown like ‘<b>=</b>’. 1042The complete syntax of Lua can be found in <a href="#9">§9</a> 1043at the end of this manual. 1044 1045 1046 1047<h2>3.1 – <a name="3.1">Lexical Conventions</a></h2> 1048 1049<p> 1050Lua is a free-form language. 1051It ignores spaces (including new lines) and comments 1052between lexical elements (tokens), 1053except as delimiters between names and keywords. 1054 1055 1056<p> 1057<em>Names</em> 1058(also called <em>identifiers</em>) 1059in Lua can be any string of letters, 1060digits, and underscores, 1061not beginning with a digit and 1062not being a reserved word. 1063Identifiers are used to name variables, table fields, and labels. 1064 1065 1066<p> 1067The following <em>keywords</em> are reserved 1068and cannot be used as names: 1069 1070 1071<pre> 1072 and break do else elseif end 1073 false for function goto if in 1074 local nil not or repeat return 1075 then true until while 1076</pre> 1077 1078<p> 1079Lua is a case-sensitive language: 1080<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> 1081are two different, valid names. 1082As a convention, 1083programs should avoid creating 1084names that start with an underscore followed by 1085one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>). 1086 1087 1088<p> 1089The following strings denote other tokens: 1090 1091<pre> 1092 + - * / % ^ # 1093 & ~ | << >> // 1094 == ~= <= >= < > = 1095 ( ) { } [ ] :: 1096 ; : , . .. ... 1097</pre> 1098 1099<p> 1100A <em>short literal string</em> 1101can be delimited by matching single or double quotes, 1102and can contain the following C-like escape sequences: 1103'<code>\a</code>' (bell), 1104'<code>\b</code>' (backspace), 1105'<code>\f</code>' (form feed), 1106'<code>\n</code>' (newline), 1107'<code>\r</code>' (carriage return), 1108'<code>\t</code>' (horizontal tab), 1109'<code>\v</code>' (vertical tab), 1110'<code>\\</code>' (backslash), 1111'<code>\"</code>' (quotation mark [double quote]), 1112and '<code>\'</code>' (apostrophe [single quote]). 1113A backslash followed by a line break 1114results in a newline in the string. 1115The escape sequence '<code>\z</code>' skips the following span 1116of white-space characters, 1117including line breaks; 1118it is particularly useful to break and indent a long literal string 1119into multiple lines without adding the newlines and spaces 1120into the string contents. 1121A short literal string cannot contain unescaped line breaks 1122nor escapes not forming a valid escape sequence. 1123 1124 1125<p> 1126We can specify any byte in a short literal string by its numeric value 1127(including embedded zeros). 1128This can be done 1129with the escape sequence <code>\x<em>XX</em></code>, 1130where <em>XX</em> is a sequence of exactly two hexadecimal digits, 1131or with the escape sequence <code>\<em>ddd</em></code>, 1132where <em>ddd</em> is a sequence of up to three decimal digits. 1133(Note that if a decimal escape sequence is to be followed by a digit, 1134it must be expressed using exactly three digits.) 1135 1136 1137<p> 1138The UTF-8 encoding of a Unicode character 1139can be inserted in a literal string with 1140the escape sequence <code>\u{<em>XXX</em>}</code> 1141(note the mandatory enclosing brackets), 1142where <em>XXX</em> is a sequence of one or more hexadecimal digits 1143representing the character code point. 1144 1145 1146<p> 1147Literal strings can also be defined using a long format 1148enclosed by <em>long brackets</em>. 1149We define an <em>opening long bracket of level <em>n</em></em> as an opening 1150square bracket followed by <em>n</em> equal signs followed by another 1151opening square bracket. 1152So, an opening long bracket of level 0 is written as <code>[[</code>, 1153an opening long bracket of level 1 is written as <code>[=[</code>, 1154and so on. 1155A <em>closing long bracket</em> is defined similarly; 1156for instance, 1157a closing long bracket of level 4 is written as <code>]====]</code>. 1158A <em>long literal</em> starts with an opening long bracket of any level and 1159ends at the first closing long bracket of the same level. 1160It can contain any text except a closing bracket of the same level. 1161Literals in this bracketed form can run for several lines, 1162do not interpret any escape sequences, 1163and ignore long brackets of any other level. 1164Any kind of end-of-line sequence 1165(carriage return, newline, carriage return followed by newline, 1166or newline followed by carriage return) 1167is converted to a simple newline. 1168 1169 1170<p> 1171For convenience, 1172when the opening long bracket is immediately followed by a newline, 1173the newline is not included in the string. 1174As an example, in a system using ASCII 1175(in which '<code>a</code>' is coded as 97, 1176newline is coded as 10, and '<code>1</code>' is coded as 49), 1177the five literal strings below denote the same string: 1178 1179<pre> 1180 a = 'alo\n123"' 1181 a = "alo\n123\"" 1182 a = '\97lo\10\04923"' 1183 a = [[alo 1184 123"]] 1185 a = [==[ 1186 alo 1187 123"]==] 1188</pre> 1189 1190<p> 1191Any byte in a literal string not 1192explicitly affected by the previous rules represents itself. 1193However, Lua opens files for parsing in text mode, 1194and the system file functions may have problems with 1195some control characters. 1196So, it is safer to represent 1197non-text data as a quoted literal with 1198explicit escape sequences for the non-text characters. 1199 1200 1201<p> 1202A <em>numeric constant</em> (or <em>numeral</em>) 1203can be written with an optional fractional part 1204and an optional decimal exponent, 1205marked by a letter '<code>e</code>' or '<code>E</code>'. 1206Lua also accepts hexadecimal constants, 1207which start with <code>0x</code> or <code>0X</code>. 1208Hexadecimal constants also accept an optional fractional part 1209plus an optional binary exponent, 1210marked by a letter '<code>p</code>' or '<code>P</code>'. 1211A numeric constant with a radix point or an exponent 1212denotes a float; 1213otherwise, 1214if its value fits in an integer, 1215it denotes an integer. 1216Examples of valid integer constants are 1217 1218<pre> 1219 3 345 0xff 0xBEBADA 1220</pre><p> 1221Examples of valid float constants are 1222 1223<pre> 1224 3.0 3.1416 314.16e-2 0.31416E1 34e1 1225 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 1226</pre> 1227 1228<p> 1229A <em>comment</em> starts with a double hyphen (<code>--</code>) 1230anywhere outside a string. 1231If the text immediately after <code>--</code> is not an opening long bracket, 1232the comment is a <em>short comment</em>, 1233which runs until the end of the line. 1234Otherwise, it is a <em>long comment</em>, 1235which runs until the corresponding closing long bracket. 1236Long comments are frequently used to disable code temporarily. 1237 1238 1239 1240 1241 1242<h2>3.2 – <a name="3.2">Variables</a></h2> 1243 1244<p> 1245Variables are places that store values. 1246There are three kinds of variables in Lua: 1247global variables, local variables, and table fields. 1248 1249 1250<p> 1251A single name can denote a global variable or a local variable 1252(or a function's formal parameter, 1253which is a particular kind of local variable): 1254 1255<pre> 1256 var ::= Name 1257</pre><p> 1258Name denotes identifiers, as defined in <a href="#3.1">§3.1</a>. 1259 1260 1261<p> 1262Any variable name is assumed to be global unless explicitly declared 1263as a local (see <a href="#3.3.7">§3.3.7</a>). 1264Local variables are <em>lexically scoped</em>: 1265local variables can be freely accessed by functions 1266defined inside their scope (see <a href="#3.5">§3.5</a>). 1267 1268 1269<p> 1270Before the first assignment to a variable, its value is <b>nil</b>. 1271 1272 1273<p> 1274Square brackets are used to index a table: 1275 1276<pre> 1277 var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ 1278</pre><p> 1279The meaning of accesses to table fields can be changed via metatables. 1280An access to an indexed variable <code>t[i]</code> is equivalent to 1281a call <code>gettable_event(t,i)</code>. 1282(See <a href="#2.4">§2.4</a> for a complete description of the 1283<code>gettable_event</code> function. 1284This function is not defined or callable in Lua. 1285We use it here only for explanatory purposes.) 1286 1287 1288<p> 1289The syntax <code>var.Name</code> is just syntactic sugar for 1290<code>var["Name"]</code>: 1291 1292<pre> 1293 var ::= prefixexp ‘<b>.</b>’ Name 1294</pre> 1295 1296<p> 1297An access to a global variable <code>x</code> 1298is equivalent to <code>_ENV.x</code>. 1299Due to the way that chunks are compiled, 1300<code>_ENV</code> is never a global name (see <a href="#2.2">§2.2</a>). 1301 1302 1303 1304 1305 1306<h2>3.3 – <a name="3.3">Statements</a></h2> 1307 1308<p> 1309Lua supports an almost conventional set of statements, 1310similar to those in Pascal or C. 1311This set includes 1312assignments, control structures, function calls, 1313and variable declarations. 1314 1315 1316 1317<h3>3.3.1 – <a name="3.3.1">Blocks</a></h3> 1318 1319<p> 1320A block is a list of statements, 1321which are executed sequentially: 1322 1323<pre> 1324 block ::= {stat} 1325</pre><p> 1326Lua has <em>empty statements</em> 1327that allow you to separate statements with semicolons, 1328start a block with a semicolon 1329or write two semicolons in sequence: 1330 1331<pre> 1332 stat ::= ‘<b>;</b>’ 1333</pre> 1334 1335<p> 1336Function calls and assignments 1337can start with an open parenthesis. 1338This possibility leads to an ambiguity in Lua's grammar. 1339Consider the following fragment: 1340 1341<pre> 1342 a = b + c 1343 (print or io.write)('done') 1344</pre><p> 1345The grammar could see it in two ways: 1346 1347<pre> 1348 a = b + c(print or io.write)('done') 1349 1350 a = b + c; (print or io.write)('done') 1351</pre><p> 1352The current parser always sees such constructions 1353in the first way, 1354interpreting the open parenthesis 1355as the start of the arguments to a call. 1356To avoid this ambiguity, 1357it is a good practice to always precede with a semicolon 1358statements that start with a parenthesis: 1359 1360<pre> 1361 ;(print or io.write)('done') 1362</pre> 1363 1364<p> 1365A block can be explicitly delimited to produce a single statement: 1366 1367<pre> 1368 stat ::= <b>do</b> block <b>end</b> 1369</pre><p> 1370Explicit blocks are useful 1371to control the scope of variable declarations. 1372Explicit blocks are also sometimes used to 1373add a <b>return</b> statement in the middle 1374of another block (see <a href="#3.3.4">§3.3.4</a>). 1375 1376 1377 1378 1379 1380<h3>3.3.2 – <a name="3.3.2">Chunks</a></h3> 1381 1382<p> 1383The unit of compilation of Lua is called a <em>chunk</em>. 1384Syntactically, 1385a chunk is simply a block: 1386 1387<pre> 1388 chunk ::= block 1389</pre> 1390 1391<p> 1392Lua handles a chunk as the body of an anonymous function 1393with a variable number of arguments 1394(see <a href="#3.4.11">§3.4.11</a>). 1395As such, chunks can define local variables, 1396receive arguments, and return values. 1397Moreover, such anonymous function is compiled as in the 1398scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>). 1399The resulting function always has <code>_ENV</code> as its only upvalue, 1400even if it does not use that variable. 1401 1402 1403<p> 1404A chunk can be stored in a file or in a string inside the host program. 1405To execute a chunk, 1406Lua first <em>loads</em> it, 1407precompiling the chunk's code into instructions for a virtual machine, 1408and then Lua executes the compiled code 1409with an interpreter for the virtual machine. 1410 1411 1412<p> 1413Chunks can also be precompiled into binary form; 1414see program <code>luac</code> and function <a href="#pdf-string.dump"><code>string.dump</code></a> for details. 1415Programs in source and compiled forms are interchangeable; 1416Lua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>). 1417 1418 1419 1420 1421 1422<h3>3.3.3 – <a name="3.3.3">Assignment</a></h3> 1423 1424<p> 1425Lua allows multiple assignments. 1426Therefore, the syntax for assignment 1427defines a list of variables on the left side 1428and a list of expressions on the right side. 1429The elements in both lists are separated by commas: 1430 1431<pre> 1432 stat ::= varlist ‘<b>=</b>’ explist 1433 varlist ::= var {‘<b>,</b>’ var} 1434 explist ::= exp {‘<b>,</b>’ exp} 1435</pre><p> 1436Expressions are discussed in <a href="#3.4">§3.4</a>. 1437 1438 1439<p> 1440Before the assignment, 1441the list of values is <em>adjusted</em> to the length of 1442the list of variables. 1443If there are more values than needed, 1444the excess values are thrown away. 1445If there are fewer values than needed, 1446the list is extended with as many <b>nil</b>'s as needed. 1447If the list of expressions ends with a function call, 1448then all values returned by that call enter the list of values, 1449before the adjustment 1450(except when the call is enclosed in parentheses; see <a href="#3.4">§3.4</a>). 1451 1452 1453<p> 1454The assignment statement first evaluates all its expressions 1455and only then the assignments are performed. 1456Thus the code 1457 1458<pre> 1459 i = 3 1460 i, a[i] = i+1, 20 1461</pre><p> 1462sets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 1463because the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 1464before it is assigned 4. 1465Similarly, the line 1466 1467<pre> 1468 x, y = y, x 1469</pre><p> 1470exchanges the values of <code>x</code> and <code>y</code>, 1471and 1472 1473<pre> 1474 x, y, z = y, z, x 1475</pre><p> 1476cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 1477 1478 1479<p> 1480The meaning of assignments to global variables 1481and table fields can be changed via metatables. 1482An assignment to an indexed variable <code>t[i] = val</code> is equivalent to 1483<code>settable_event(t,i,val)</code>. 1484(See <a href="#2.4">§2.4</a> for a complete description of the 1485<code>settable_event</code> function. 1486This function is not defined or callable in Lua. 1487We use it here only for explanatory purposes.) 1488 1489 1490<p> 1491An assignment to a global name <code>x = val</code> 1492is equivalent to the assignment 1493<code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>). 1494 1495 1496 1497 1498 1499<h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p> 1500The control structures 1501<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 1502familiar syntax: 1503 1504 1505 1506 1507<pre> 1508 stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 1509 stat ::= <b>repeat</b> block <b>until</b> exp 1510 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> 1511</pre><p> 1512Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>). 1513 1514 1515<p> 1516The condition expression of a 1517control structure can return any value. 1518Both <b>false</b> and <b>nil</b> are considered false. 1519All values different from <b>nil</b> and <b>false</b> are considered true 1520(in particular, the number 0 and the empty string are also true). 1521 1522 1523<p> 1524In the <b>repeat</b>–<b>until</b> loop, 1525the inner block does not end at the <b>until</b> keyword, 1526but only after the condition. 1527So, the condition can refer to local variables 1528declared inside the loop block. 1529 1530 1531<p> 1532The <b>goto</b> statement transfers the program control to a label. 1533For syntactical reasons, 1534labels in Lua are considered statements too: 1535 1536 1537 1538<pre> 1539 stat ::= <b>goto</b> Name 1540 stat ::= label 1541 label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 1542</pre> 1543 1544<p> 1545A label is visible in the entire block where it is defined, 1546except 1547inside nested blocks where a label with the same name is defined and 1548inside nested functions. 1549A goto may jump to any visible label as long as it does not 1550enter into the scope of a local variable. 1551 1552 1553<p> 1554Labels and empty statements are called <em>void statements</em>, 1555as they perform no actions. 1556 1557 1558<p> 1559The <b>break</b> statement terminates the execution of a 1560<b>while</b>, <b>repeat</b>, or <b>for</b> loop, 1561skipping to the next statement after the loop: 1562 1563 1564<pre> 1565 stat ::= <b>break</b> 1566</pre><p> 1567A <b>break</b> ends the innermost enclosing loop. 1568 1569 1570<p> 1571The <b>return</b> statement is used to return values 1572from a function or a chunk 1573(which is an anonymous function). 1574 1575Functions can return more than one value, 1576so the syntax for the <b>return</b> statement is 1577 1578<pre> 1579 stat ::= <b>return</b> [explist] [‘<b>;</b>’] 1580</pre> 1581 1582<p> 1583The <b>return</b> statement can only be written 1584as the last statement of a block. 1585If it is really necessary to <b>return</b> in the middle of a block, 1586then an explicit inner block can be used, 1587as in the idiom <code>do return end</code>, 1588because now <b>return</b> is the last statement in its (inner) block. 1589 1590 1591 1592 1593 1594<h3>3.3.5 – <a name="3.3.5">For Statement</a></h3> 1595 1596<p> 1597 1598The <b>for</b> statement has two forms: 1599one numerical and one generic. 1600 1601 1602<p> 1603The numerical <b>for</b> loop repeats a block of code while a 1604control variable runs through an arithmetic progression. 1605It has the following syntax: 1606 1607<pre> 1608 stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> 1609</pre><p> 1610The <em>block</em> is repeated for <em>name</em> starting at the value of 1611the first <em>exp</em>, until it passes the second <em>exp</em> by steps of the 1612third <em>exp</em>. 1613More precisely, a <b>for</b> statement like 1614 1615<pre> 1616 for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end 1617</pre><p> 1618is equivalent to the code: 1619 1620<pre> 1621 do 1622 local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>) 1623 if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end 1624 <em>var</em> = <em>var</em> - <em>step</em> 1625 while true do 1626 <em>var</em> = <em>var</em> + <em>step</em> 1627 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 1628 break 1629 end 1630 local v = <em>var</em> 1631 <em>block</em> 1632 end 1633 end 1634</pre> 1635 1636<p> 1637Note the following: 1638 1639<ul> 1640 1641<li> 1642All three control expressions are evaluated only once, 1643before the loop starts. 1644They must all result in numbers. 1645</li> 1646 1647<li> 1648<code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables. 1649The names shown here are for explanatory purposes only. 1650</li> 1651 1652<li> 1653If the third expression (the step) is absent, 1654then a step of 1 is used. 1655</li> 1656 1657<li> 1658You can use <b>break</b> and <b>goto</b> to exit a <b>for</b> loop. 1659</li> 1660 1661<li> 1662The loop variable <code>v</code> is local to the loop body. 1663If you need its value after the loop, 1664assign it to another variable before exiting the loop. 1665</li> 1666 1667</ul> 1668 1669<p> 1670The generic <b>for</b> statement works over functions, 1671called <em>iterators</em>. 1672On each iteration, the iterator function is called to produce a new value, 1673stopping when this new value is <b>nil</b>. 1674The generic <b>for</b> loop has the following syntax: 1675 1676<pre> 1677 stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> 1678 namelist ::= Name {‘<b>,</b>’ Name} 1679</pre><p> 1680A <b>for</b> statement like 1681 1682<pre> 1683 for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end 1684</pre><p> 1685is equivalent to the code: 1686 1687<pre> 1688 do 1689 local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em> 1690 while true do 1691 local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>) 1692 if <em>var_1</em> == nil then break end 1693 <em>var</em> = <em>var_1</em> 1694 <em>block</em> 1695 end 1696 end 1697</pre><p> 1698Note the following: 1699 1700<ul> 1701 1702<li> 1703<code><em>explist</em></code> is evaluated only once. 1704Its results are an <em>iterator</em> function, 1705a <em>state</em>, 1706and an initial value for the first <em>iterator variable</em>. 1707</li> 1708 1709<li> 1710<code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables. 1711The names are here for explanatory purposes only. 1712</li> 1713 1714<li> 1715You can use <b>break</b> to exit a <b>for</b> loop. 1716</li> 1717 1718<li> 1719The loop variables <code><em>var_i</em></code> are local to the loop; 1720you cannot use their values after the <b>for</b> ends. 1721If you need these values, 1722then assign them to other variables before breaking or exiting the loop. 1723</li> 1724 1725</ul> 1726 1727 1728 1729 1730<h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p> 1731To allow possible side-effects, 1732function calls can be executed as statements: 1733 1734<pre> 1735 stat ::= functioncall 1736</pre><p> 1737In this case, all returned values are thrown away. 1738Function calls are explained in <a href="#3.4.10">§3.4.10</a>. 1739 1740 1741 1742 1743 1744<h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p> 1745Local variables can be declared anywhere inside a block. 1746The declaration can include an initial assignment: 1747 1748<pre> 1749 stat ::= <b>local</b> namelist [‘<b>=</b>’ explist] 1750</pre><p> 1751If present, an initial assignment has the same semantics 1752of a multiple assignment (see <a href="#3.3.3">§3.3.3</a>). 1753Otherwise, all variables are initialized with <b>nil</b>. 1754 1755 1756<p> 1757A chunk is also a block (see <a href="#3.3.2">§3.3.2</a>), 1758and so local variables can be declared in a chunk outside any explicit block. 1759 1760 1761<p> 1762The visibility rules for local variables are explained in <a href="#3.5">§3.5</a>. 1763 1764 1765 1766 1767 1768 1769 1770<h2>3.4 – <a name="3.4">Expressions</a></h2> 1771 1772<p> 1773The basic expressions in Lua are the following: 1774 1775<pre> 1776 exp ::= prefixexp 1777 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 1778 exp ::= Numeral 1779 exp ::= LiteralString 1780 exp ::= functiondef 1781 exp ::= tableconstructor 1782 exp ::= ‘<b>...</b>’ 1783 exp ::= exp binop exp 1784 exp ::= unop exp 1785 prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 1786</pre> 1787 1788<p> 1789Numerals and literal strings are explained in <a href="#3.1">§3.1</a>; 1790variables are explained in <a href="#3.2">§3.2</a>; 1791function definitions are explained in <a href="#3.4.11">§3.4.11</a>; 1792function calls are explained in <a href="#3.4.10">§3.4.10</a>; 1793table constructors are explained in <a href="#3.4.9">§3.4.9</a>. 1794Vararg expressions, 1795denoted by three dots ('<code>...</code>'), can only be used when 1796directly inside a vararg function; 1797they are explained in <a href="#3.4.11">§3.4.11</a>. 1798 1799 1800<p> 1801Binary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), 1802bitwise operators (see <a href="#3.4.2">§3.4.2</a>), 1803relational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>), 1804and the concatenation operator (see <a href="#3.4.6">§3.4.6</a>). 1805Unary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), 1806the unary bitwise NOT (see <a href="#3.4.2">§3.4.2</a>), 1807the unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), 1808and the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). 1809 1810 1811<p> 1812Both function calls and vararg expressions can result in multiple values. 1813If a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>), 1814then its return list is adjusted to zero elements, 1815thus discarding all returned values. 1816If an expression is used as the last (or the only) element 1817of a list of expressions, 1818then no adjustment is made 1819(unless the expression is enclosed in parentheses). 1820In all other contexts, 1821Lua adjusts the result list to one element, 1822either discarding all values except the first one 1823or adding a single <b>nil</b> if there are no values. 1824 1825 1826<p> 1827Here are some examples: 1828 1829<pre> 1830 f() -- adjusted to 0 results 1831 g(f(), x) -- f() is adjusted to 1 result 1832 g(x, f()) -- g gets x plus all results from f() 1833 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) 1834 a,b = ... -- a gets the first vararg parameter, b gets 1835 -- the second (both a and b can get nil if there 1836 -- is no corresponding vararg parameter) 1837 1838 a,b,c = x, f() -- f() is adjusted to 2 results 1839 a,b,c = f() -- f() is adjusted to 3 results 1840 return f() -- returns all results from f() 1841 return ... -- returns all received vararg parameters 1842 return x,y,f() -- returns x, y, and all results from f() 1843 {f()} -- creates a list with all results from f() 1844 {...} -- creates a list with all vararg parameters 1845 {f(), nil} -- f() is adjusted to 1 result 1846</pre> 1847 1848<p> 1849Any expression enclosed in parentheses always results in only one value. 1850Thus, 1851<code>(f(x,y,z))</code> is always a single value, 1852even if <code>f</code> returns several values. 1853(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> 1854or <b>nil</b> if <code>f</code> does not return any values.) 1855 1856 1857 1858<h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p> 1859Lua supports the following arithmetic operators: 1860 1861<ul> 1862<li><b><code>+</code>: </b>addition</li> 1863<li><b><code>-</code>: </b>subtraction</li> 1864<li><b><code>*</code>: </b>multiplication</li> 1865<li><b><code>/</code>: </b>float division</li> 1866<li><b><code>//</code>: </b>floor division</li> 1867<li><b><code>%</code>: </b>modulo</li> 1868<li><b><code>^</code>: </b>exponentiation</li> 1869<li><b><code>-</code>: </b>unary minus</li> 1870</ul> 1871 1872<p> 1873With the exception of exponentiation and float division, 1874the arithmetic operators work as follows: 1875If both operands are integers, 1876the operation is performed over integers and the result is an integer. 1877Otherwise, if both operands are numbers 1878or strings that can be converted to 1879numbers (see <a href="#3.4.3">§3.4.3</a>), 1880then they are converted to floats, 1881the operation is performed following the usual rules 1882for floating-point arithmetic 1883(usually the IEEE 754 standard), 1884and the result is a float. 1885 1886 1887<p> 1888Exponentiation and float division (<code>/</code>) 1889always convert their operands to floats 1890and the result is always a float. 1891Exponentiation uses the ISO C function <code>pow</code>, 1892so that it works for non-integer exponents too. 1893 1894 1895<p> 1896Floor division (<code>//</code>) is a division 1897that rounds the quotient towards minus infinity, 1898that is, the floor of the division of its operands. 1899 1900 1901<p> 1902Modulo is defined as the remainder of a division 1903that rounds the quotient towards minus infinity (floor division). 1904 1905 1906<p> 1907In case of overflows in integer arithmetic, 1908all operations <em>wrap around</em>, 1909according to the usual rules of two-complement arithmetic. 1910(In other words, 1911they return the unique representable integer 1912that is equal modulo <em>2<sup>64</sup></em> to the mathematical result.) 1913 1914 1915 1916<h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p> 1917Lua supports the following bitwise operators: 1918 1919<ul> 1920<li><b><code>&</code>: </b>bitwise AND</li> 1921<li><b><code>|</code>: </b>bitwise OR</li> 1922<li><b><code>~</code>: </b>bitwise exclusive OR</li> 1923<li><b><code>>></code>: </b>right shift</li> 1924<li><b><code><<</code>: </b>left shift</li> 1925<li><b><code>~</code>: </b>unary bitwise NOT</li> 1926</ul> 1927 1928<p> 1929All bitwise operations convert its operands to integers 1930(see <a href="#3.4.3">§3.4.3</a>), 1931operate on all bits of those integers, 1932and result in an integer. 1933 1934 1935<p> 1936Both right and left shifts fill the vacant bits with zeros. 1937Negative displacements shift to the other direction; 1938displacements with absolute values equal to or higher than 1939the number of bits in an integer 1940result in zero (as all bits are shifted out). 1941 1942 1943 1944 1945 1946<h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p> 1947Lua provides some automatic conversions between some 1948types and representations at run time. 1949Bitwise operators always convert float operands to integers. 1950Exponentiation and float division 1951always convert integer operands to floats. 1952All other arithmetic operations applied to mixed numbers 1953(integers and floats) convert the integer operand to a float; 1954this is called the <em>usual rule</em>. 1955The C API also converts both integers to floats and 1956floats to integers, as needed. 1957Moreover, string concatenation accepts numbers as arguments, 1958besides strings. 1959 1960 1961<p> 1962Lua also converts strings to numbers, 1963whenever a number is expected. 1964 1965 1966<p> 1967In a conversion from integer to float, 1968if the integer value has an exact representation as a float, 1969that is the result. 1970Otherwise, 1971the conversion gets the nearest higher or 1972the nearest lower representable value. 1973This kind of conversion never fails. 1974 1975 1976<p> 1977The conversion from float to integer 1978checks whether the float has an exact representation as an integer 1979(that is, the float has an integral value and 1980it is in the range of integer representation). 1981If it does, that representation is the result. 1982Otherwise, the conversion fails. 1983 1984 1985<p> 1986The conversion from strings to numbers goes as follows: 1987First, the string is converted to an integer or a float, 1988following its syntax and the rules of the Lua lexer. 1989(The string may have also leading and trailing spaces and a sign.) 1990Then, the resulting number (float or integer) 1991is converted to the type (float or integer) required by the context 1992(e.g., the operation that forced the conversion). 1993 1994 1995<p> 1996All conversions from strings to numbers 1997accept both a dot and the current locale mark 1998as the radix character. 1999(The Lua lexer, however, accepts only a dot.) 2000 2001 2002<p> 2003The conversion from numbers to strings uses a 2004non-specified human-readable format. 2005For complete control over how numbers are converted to strings, 2006use the <code>format</code> function from the string library 2007(see <a href="#pdf-string.format"><code>string.format</code></a>). 2008 2009 2010 2011 2012 2013<h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p> 2014Lua supports the following relational operators: 2015 2016<ul> 2017<li><b><code>==</code>: </b>equality</li> 2018<li><b><code>~=</code>: </b>inequality</li> 2019<li><b><code><</code>: </b>less than</li> 2020<li><b><code>></code>: </b>greater than</li> 2021<li><b><code><=</code>: </b>less or equal</li> 2022<li><b><code>>=</code>: </b>greater or equal</li> 2023</ul><p> 2024These operators always result in <b>false</b> or <b>true</b>. 2025 2026 2027<p> 2028Equality (<code>==</code>) first compares the type of its operands. 2029If the types are different, then the result is <b>false</b>. 2030Otherwise, the values of the operands are compared. 2031Strings are compared in the obvious way. 2032Numbers are equal if they denote the same mathematical value. 2033 2034 2035<p> 2036Tables, userdata, and threads 2037are compared by reference: 2038two objects are considered equal only if they are the same object. 2039Every time you create a new object 2040(a table, userdata, or thread), 2041this new object is different from any previously existing object. 2042Closures with the same reference are always equal. 2043Closures with any detectable difference 2044(different behavior, different definition) are always different. 2045 2046 2047<p> 2048You can change the way that Lua compares tables and userdata 2049by using the "eq" metamethod (see <a href="#2.4">§2.4</a>). 2050 2051 2052<p> 2053Equality comparisons do not convert strings to numbers 2054or vice versa. 2055Thus, <code>"0"==0</code> evaluates to <b>false</b>, 2056and <code>t[0]</code> and <code>t["0"]</code> denote different 2057entries in a table. 2058 2059 2060<p> 2061The operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 2062 2063 2064<p> 2065The order operators work as follows. 2066If both arguments are numbers, 2067then they are compared according to their mathematical values 2068(regardless of their subtypes). 2069Otherwise, if both arguments are strings, 2070then their values are compared according to the current locale. 2071Otherwise, Lua tries to call the "lt" or the "le" 2072metamethod (see <a href="#2.4">§2.4</a>). 2073A comparison <code>a > b</code> is translated to <code>b < a</code> 2074and <code>a >= b</code> is translated to <code>b <= a</code>. 2075 2076 2077<p> 2078Following the IEEE 754 standard, 2079NaN is considered neither smaller than, 2080nor equal to, nor greater than any value (including itself). 2081 2082 2083 2084 2085 2086<h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p> 2087The logical operators in Lua are 2088<b>and</b>, <b>or</b>, and <b>not</b>. 2089Like the control structures (see <a href="#3.3.4">§3.3.4</a>), 2090all logical operators consider both <b>false</b> and <b>nil</b> as false 2091and anything else as true. 2092 2093 2094<p> 2095The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 2096The conjunction operator <b>and</b> returns its first argument 2097if this value is <b>false</b> or <b>nil</b>; 2098otherwise, <b>and</b> returns its second argument. 2099The disjunction operator <b>or</b> returns its first argument 2100if this value is different from <b>nil</b> and <b>false</b>; 2101otherwise, <b>or</b> returns its second argument. 2102Both <b>and</b> and <b>or</b> use short-circuit evaluation; 2103that is, 2104the second operand is evaluated only if necessary. 2105Here are some examples: 2106 2107<pre> 2108 10 or 20 --> 10 2109 10 or error() --> 10 2110 nil or "a" --> "a" 2111 nil and 10 --> nil 2112 false and error() --> false 2113 false and nil --> false 2114 false or nil --> nil 2115 10 and 20 --> 20 2116</pre><p> 2117(In this manual, 2118<code>--></code> indicates the result of the preceding expression.) 2119 2120 2121 2122 2123 2124<h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p> 2125The string concatenation operator in Lua is 2126denoted by two dots ('<code>..</code>'). 2127If both operands are strings or numbers, then they are converted to 2128strings according to the rules described in <a href="#3.4.3">§3.4.3</a>. 2129Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). 2130 2131 2132 2133 2134 2135<h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3> 2136 2137<p> 2138The length operator is denoted by the unary prefix operator <code>#</code>. 2139 2140 2141<p> 2142The length of a string is its number of bytes 2143(that is, the usual meaning of string length when each 2144character is one byte). 2145 2146 2147<p> 2148The length operator applied on a table 2149returns a border in that table. 2150A <em>border</em> in a table <code>t</code> is any natural number 2151that satisfies the following condition: 2152 2153<pre> 2154 (border == 0 or t[border] ~= nil) and t[border + 1] == nil 2155</pre><p> 2156In words, 2157a border is any (natural) index in a table 2158where a non-nil value is followed by a nil value 2159(or zero, when index 1 is nil). 2160 2161 2162<p> 2163A table with exactly one border is called a <em>sequence</em>. 2164For instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence, 2165as it has only one border (5). 2166The table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5), 2167and therefore it is not a sequence. 2168The table <code>{nil, 20, 30, nil, nil, 60, nil}</code> 2169has three borders (0, 3, and 6), 2170so it is not a sequence, too. 2171The table <code>{}</code> is a sequence with border 0. 2172Note that non-natural keys do not interfere 2173with whether a table is a sequence. 2174 2175 2176<p> 2177When <code>t</code> is a sequence, 2178<code>#t</code> returns its only border, 2179which corresponds to the intuitive notion of the length of the sequence. 2180When <code>t</code> is not a sequence, 2181<code>#t</code> can return any of its borders. 2182(The exact one depends on details of 2183the internal representation of the table, 2184which in turn can depend on how the table was populated and 2185the memory addresses of its non-numeric keys.) 2186 2187 2188<p> 2189The computation of the length of a table 2190has a guaranteed worst time of <em>O(log n)</em>, 2191where <em>n</em> is the largest natural key in the table. 2192 2193 2194<p> 2195A program can modify the behavior of the length operator for 2196any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>). 2197 2198 2199 2200 2201 2202<h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p> 2203Operator precedence in Lua follows the table below, 2204from lower to higher priority: 2205 2206<pre> 2207 or 2208 and 2209 < > <= >= ~= == 2210 | 2211 ~ 2212 & 2213 << >> 2214 .. 2215 + - 2216 * / // % 2217 unary operators (not # - ~) 2218 ^ 2219</pre><p> 2220As usual, 2221you can use parentheses to change the precedences of an expression. 2222The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 2223operators are right associative. 2224All other binary operators are left associative. 2225 2226 2227 2228 2229 2230<h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p> 2231Table constructors are expressions that create tables. 2232Every time a constructor is evaluated, a new table is created. 2233A constructor can be used to create an empty table 2234or to create a table and initialize some of its fields. 2235The general syntax for constructors is 2236 2237<pre> 2238 tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 2239 fieldlist ::= field {fieldsep field} [fieldsep] 2240 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 2241 fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 2242</pre> 2243 2244<p> 2245Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry 2246with key <code>exp1</code> and value <code>exp2</code>. 2247A field of the form <code>name = exp</code> is equivalent to 2248<code>["name"] = exp</code>. 2249Finally, fields of the form <code>exp</code> are equivalent to 2250<code>[i] = exp</code>, where <code>i</code> are consecutive integers 2251starting with 1. 2252Fields in the other formats do not affect this counting. 2253For example, 2254 2255<pre> 2256 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 2257</pre><p> 2258is equivalent to 2259 2260<pre> 2261 do 2262 local t = {} 2263 t[f(1)] = g 2264 t[1] = "x" -- 1st exp 2265 t[2] = "y" -- 2nd exp 2266 t.x = 1 -- t["x"] = 1 2267 t[3] = f(x) -- 3rd exp 2268 t[30] = 23 2269 t[4] = 45 -- 4th exp 2270 a = t 2271 end 2272</pre> 2273 2274<p> 2275The order of the assignments in a constructor is undefined. 2276(This order would be relevant only when there are repeated keys.) 2277 2278 2279<p> 2280If the last field in the list has the form <code>exp</code> 2281and the expression is a function call or a vararg expression, 2282then all values returned by this expression enter the list consecutively 2283(see <a href="#3.4.10">§3.4.10</a>). 2284 2285 2286<p> 2287The field list can have an optional trailing separator, 2288as a convenience for machine-generated code. 2289 2290 2291 2292 2293 2294<h3>3.4.10 – <a name="3.4.10">Function Calls</a></h3><p> 2295A function call in Lua has the following syntax: 2296 2297<pre> 2298 functioncall ::= prefixexp args 2299</pre><p> 2300In a function call, 2301first prefixexp and args are evaluated. 2302If the value of prefixexp has type <em>function</em>, 2303then this function is called 2304with the given arguments. 2305Otherwise, the prefixexp "call" metamethod is called, 2306having as first parameter the value of prefixexp, 2307followed by the original call arguments 2308(see <a href="#2.4">§2.4</a>). 2309 2310 2311<p> 2312The form 2313 2314<pre> 2315 functioncall ::= prefixexp ‘<b>:</b>’ Name args 2316</pre><p> 2317can be used to call "methods". 2318A call <code>v:name(<em>args</em>)</code> 2319is syntactic sugar for <code>v.name(v,<em>args</em>)</code>, 2320except that <code>v</code> is evaluated only once. 2321 2322 2323<p> 2324Arguments have the following syntax: 2325 2326<pre> 2327 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ 2328 args ::= tableconstructor 2329 args ::= LiteralString 2330</pre><p> 2331All argument expressions are evaluated before the call. 2332A call of the form <code>f{<em>fields</em>}</code> is 2333syntactic sugar for <code>f({<em>fields</em>})</code>; 2334that is, the argument list is a single new table. 2335A call of the form <code>f'<em>string</em>'</code> 2336(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 2337is syntactic sugar for <code>f('<em>string</em>')</code>; 2338that is, the argument list is a single literal string. 2339 2340 2341<p> 2342A call of the form <code>return <em>functioncall</em></code> is called 2343a <em>tail call</em>. 2344Lua implements <em>proper tail calls</em> 2345(or <em>proper tail recursion</em>): 2346in a tail call, 2347the called function reuses the stack entry of the calling function. 2348Therefore, there is no limit on the number of nested tail calls that 2349a program can execute. 2350However, a tail call erases any debug information about the 2351calling function. 2352Note that a tail call only happens with a particular syntax, 2353where the <b>return</b> has one single function call as argument; 2354this syntax makes the calling function return exactly 2355the returns of the called function. 2356So, none of the following examples are tail calls: 2357 2358<pre> 2359 return (f(x)) -- results adjusted to 1 2360 return 2 * f(x) 2361 return x, f(x) -- additional results 2362 f(x); return -- results discarded 2363 return x or f(x) -- results adjusted to 1 2364</pre> 2365 2366 2367 2368 2369<h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3> 2370 2371<p> 2372The syntax for function definition is 2373 2374<pre> 2375 functiondef ::= <b>function</b> funcbody 2376 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 2377</pre> 2378 2379<p> 2380The following syntactic sugar simplifies function definitions: 2381 2382<pre> 2383 stat ::= <b>function</b> funcname funcbody 2384 stat ::= <b>local</b> <b>function</b> Name funcbody 2385 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 2386</pre><p> 2387The statement 2388 2389<pre> 2390 function f () <em>body</em> end 2391</pre><p> 2392translates to 2393 2394<pre> 2395 f = function () <em>body</em> end 2396</pre><p> 2397The statement 2398 2399<pre> 2400 function t.a.b.c.f () <em>body</em> end 2401</pre><p> 2402translates to 2403 2404<pre> 2405 t.a.b.c.f = function () <em>body</em> end 2406</pre><p> 2407The statement 2408 2409<pre> 2410 local function f () <em>body</em> end 2411</pre><p> 2412translates to 2413 2414<pre> 2415 local f; f = function () <em>body</em> end 2416</pre><p> 2417not to 2418 2419<pre> 2420 local f = function () <em>body</em> end 2421</pre><p> 2422(This only makes a difference when the body of the function 2423contains references to <code>f</code>.) 2424 2425 2426<p> 2427A function definition is an executable expression, 2428whose value has type <em>function</em>. 2429When Lua precompiles a chunk, 2430all its function bodies are precompiled too. 2431Then, whenever Lua executes the function definition, 2432the function is <em>instantiated</em> (or <em>closed</em>). 2433This function instance (or <em>closure</em>) 2434is the final value of the expression. 2435 2436 2437<p> 2438Parameters act as local variables that are 2439initialized with the argument values: 2440 2441<pre> 2442 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 2443</pre><p> 2444When a function is called, 2445the list of arguments is adjusted to 2446the length of the list of parameters, 2447unless the function is a <em>vararg function</em>, 2448which is indicated by three dots ('<code>...</code>') 2449at the end of its parameter list. 2450A vararg function does not adjust its argument list; 2451instead, it collects all extra arguments and supplies them 2452to the function through a <em>vararg expression</em>, 2453which is also written as three dots. 2454The value of this expression is a list of all actual extra arguments, 2455similar to a function with multiple results. 2456If a vararg expression is used inside another expression 2457or in the middle of a list of expressions, 2458then its return list is adjusted to one element. 2459If the expression is used as the last element of a list of expressions, 2460then no adjustment is made 2461(unless that last expression is enclosed in parentheses). 2462 2463 2464<p> 2465As an example, consider the following definitions: 2466 2467<pre> 2468 function f(a, b) end 2469 function g(a, b, ...) end 2470 function r() return 1,2,3 end 2471</pre><p> 2472Then, we have the following mapping from arguments to parameters and 2473to the vararg expression: 2474 2475<pre> 2476 CALL PARAMETERS 2477 2478 f(3) a=3, b=nil 2479 f(3, 4) a=3, b=4 2480 f(3, 4, 5) a=3, b=4 2481 f(r(), 10) a=1, b=10 2482 f(r()) a=1, b=2 2483 2484 g(3) a=3, b=nil, ... --> (nothing) 2485 g(3, 4) a=3, b=4, ... --> (nothing) 2486 g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 2487 g(5, r()) a=5, b=1, ... --> 2 3 2488</pre> 2489 2490<p> 2491Results are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>). 2492If control reaches the end of a function 2493without encountering a <b>return</b> statement, 2494then the function returns with no results. 2495 2496 2497<p> 2498 2499There is a system-dependent limit on the number of values 2500that a function may return. 2501This limit is guaranteed to be larger than 1000. 2502 2503 2504<p> 2505The <em>colon</em> syntax 2506is used for defining <em>methods</em>, 2507that is, functions that have an implicit extra parameter <code>self</code>. 2508Thus, the statement 2509 2510<pre> 2511 function t.a.b.c:f (<em>params</em>) <em>body</em> end 2512</pre><p> 2513is syntactic sugar for 2514 2515<pre> 2516 t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end 2517</pre> 2518 2519 2520 2521 2522 2523 2524<h2>3.5 – <a name="3.5">Visibility Rules</a></h2> 2525 2526<p> 2527 2528Lua is a lexically scoped language. 2529The scope of a local variable begins at the first statement after 2530its declaration and lasts until the last non-void statement 2531of the innermost block that includes the declaration. 2532Consider the following example: 2533 2534<pre> 2535 x = 10 -- global variable 2536 do -- new block 2537 local x = x -- new 'x', with value 10 2538 print(x) --> 10 2539 x = x+1 2540 do -- another block 2541 local x = x+1 -- another 'x' 2542 print(x) --> 12 2543 end 2544 print(x) --> 11 2545 end 2546 print(x) --> 10 (the global one) 2547</pre> 2548 2549<p> 2550Notice that, in a declaration like <code>local x = x</code>, 2551the new <code>x</code> being declared is not in scope yet, 2552and so the second <code>x</code> refers to the outside variable. 2553 2554 2555<p> 2556Because of the lexical scoping rules, 2557local variables can be freely accessed by functions 2558defined inside their scope. 2559A local variable used by an inner function is called 2560an <em>upvalue</em>, or <em>external local variable</em>, 2561inside the inner function. 2562 2563 2564<p> 2565Notice that each execution of a <b>local</b> statement 2566defines new local variables. 2567Consider the following example: 2568 2569<pre> 2570 a = {} 2571 local x = 20 2572 for i=1,10 do 2573 local y = 0 2574 a[i] = function () y=y+1; return x+y end 2575 end 2576</pre><p> 2577The loop creates ten closures 2578(that is, ten instances of the anonymous function). 2579Each of these closures uses a different <code>y</code> variable, 2580while all of them share the same <code>x</code>. 2581 2582 2583 2584 2585 2586<h1>4 – <a name="4">The Application Program Interface</a></h1> 2587 2588<p> 2589 2590This section describes the C API for Lua, that is, 2591the set of C functions available to the host program to communicate 2592with Lua. 2593All API functions and related types and constants 2594are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. 2595 2596 2597<p> 2598Even when we use the term "function", 2599any facility in the API may be provided as a macro instead. 2600Except where stated otherwise, 2601all such macros use each of their arguments exactly once 2602(except for the first argument, which is always a Lua state), 2603and so do not generate any hidden side-effects. 2604 2605 2606<p> 2607As in most C libraries, 2608the Lua API functions do not check their arguments for validity or consistency. 2609However, you can change this behavior by compiling Lua 2610with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined. 2611 2612 2613<p> 2614The Lua library is fully reentrant: 2615it has no global variables. 2616It keeps all information it needs in a dynamic structure, 2617called the <em>Lua state</em>. 2618 2619 2620<p> 2621Each Lua state has one or more threads, 2622which correspond to independent, cooperative lines of execution. 2623The type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread. 2624(Indirectly, through the thread, it also refers to the 2625Lua state associated to the thread.) 2626 2627 2628<p> 2629A pointer to a thread must be passed as the first argument to 2630every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 2631which creates a Lua state from scratch and returns a pointer 2632to the <em>main thread</em> in the new state. 2633 2634 2635 2636<h2>4.1 – <a name="4.1">The Stack</a></h2> 2637 2638<p> 2639Lua uses a <em>virtual stack</em> to pass values to and from C. 2640Each element in this stack represents a Lua value 2641(<b>nil</b>, number, string, etc.). 2642Functions in the API can access this stack through the 2643Lua state parameter that they receive. 2644 2645 2646<p> 2647Whenever Lua calls C, the called function gets a new stack, 2648which is independent of previous stacks and of stacks of 2649C functions that are still active. 2650This stack initially contains any arguments to the C function 2651and it is where the C function can store temporary 2652Lua values and must push its results 2653to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 2654 2655 2656<p> 2657For convenience, 2658most query operations in the API do not follow a strict stack discipline. 2659Instead, they can refer to any element in the stack 2660by using an <em>index</em>: 2661A positive index represents an absolute stack position 2662(starting at 1); 2663a negative index represents an offset relative to the top of the stack. 2664More specifically, if the stack has <em>n</em> elements, 2665then index 1 represents the first element 2666(that is, the element that was pushed onto the stack first) 2667and 2668index <em>n</em> represents the last element; 2669index -1 also represents the last element 2670(that is, the element at the top) 2671and index <em>-n</em> represents the first element. 2672 2673 2674 2675 2676 2677<h2>4.2 – <a name="4.2">Stack Size</a></h2> 2678 2679<p> 2680When you interact with the Lua API, 2681you are responsible for ensuring consistency. 2682In particular, 2683<em>you are responsible for controlling stack overflow</em>. 2684You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> 2685to ensure that the stack has enough space for pushing new elements. 2686 2687 2688<p> 2689Whenever Lua calls C, 2690it ensures that the stack has space for 2691at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots. 2692<code>LUA_MINSTACK</code> is defined as 20, 2693so that usually you do not have to worry about stack space 2694unless your code has loops pushing elements onto the stack. 2695 2696 2697<p> 2698When you call a Lua function 2699without a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>), 2700Lua ensures that the stack has enough space for all results, 2701but it does not ensure any extra space. 2702So, before pushing anything in the stack after such a call 2703you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>. 2704 2705 2706 2707 2708 2709<h2>4.3 – <a name="4.3">Valid and Acceptable Indices</a></h2> 2710 2711<p> 2712Any function in the API that receives stack indices 2713works only with <em>valid indices</em> or <em>acceptable indices</em>. 2714 2715 2716<p> 2717A <em>valid index</em> is an index that refers to a 2718position that stores a modifiable Lua value. 2719It comprises stack indices between 1 and the stack top 2720(<code>1 ≤ abs(index) ≤ top</code>) 2721 2722plus <em>pseudo-indices</em>, 2723which represent some positions that are accessible to C code 2724but that are not in the stack. 2725Pseudo-indices are used to access the registry (see <a href="#4.5">§4.5</a>) 2726and the upvalues of a C function (see <a href="#4.4">§4.4</a>). 2727 2728 2729<p> 2730Functions that do not need a specific mutable position, 2731but only a value (e.g., query functions), 2732can be called with acceptable indices. 2733An <em>acceptable index</em> can be any valid index, 2734but it also can be any positive index after the stack top 2735within the space allocated for the stack, 2736that is, indices up to the stack size. 2737(Note that 0 is never an acceptable index.) 2738Except when noted otherwise, 2739functions in the API work with acceptable indices. 2740 2741 2742<p> 2743Acceptable indices serve to avoid extra tests 2744against the stack top when querying the stack. 2745For instance, a C function can query its third argument 2746without the need to first check whether there is a third argument, 2747that is, without the need to check whether 3 is a valid index. 2748 2749 2750<p> 2751For functions that can be called with acceptable indices, 2752any non-valid index is treated as if it 2753contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>, 2754which behaves like a nil value. 2755 2756 2757 2758 2759 2760<h2>4.4 – <a name="4.4">C Closures</a></h2> 2761 2762<p> 2763When a C function is created, 2764it is possible to associate some values with it, 2765thus creating a <em>C closure</em> 2766(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>); 2767these values are called <em>upvalues</em> and are 2768accessible to the function whenever it is called. 2769 2770 2771<p> 2772Whenever a C function is called, 2773its upvalues are located at specific pseudo-indices. 2774These pseudo-indices are produced by the macro 2775<a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>. 2776The first upvalue associated with a function is at index 2777<code>lua_upvalueindex(1)</code>, and so on. 2778Any access to <code>lua_upvalueindex(<em>n</em>)</code>, 2779where <em>n</em> is greater than the number of upvalues of the 2780current function 2781(but not greater than 256, 2782which is one plus the maximum number of upvalues in a closure), 2783produces an acceptable but invalid index. 2784 2785 2786 2787 2788 2789<h2>4.5 – <a name="4.5">Registry</a></h2> 2790 2791<p> 2792Lua provides a <em>registry</em>, 2793a predefined table that can be used by any C code to 2794store whatever Lua values it needs to store. 2795The registry table is always located at pseudo-index 2796<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. 2797Any C library can store data into this table, 2798but it must take care to choose keys 2799that are different from those used 2800by other libraries, to avoid collisions. 2801Typically, you should use as key a string containing your library name, 2802or a light userdata with the address of a C object in your code, 2803or any Lua object created by your code. 2804As with variable names, 2805string keys starting with an underscore followed by 2806uppercase letters are reserved for Lua. 2807 2808 2809<p> 2810The integer keys in the registry are used 2811by the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>) 2812and by some predefined values. 2813Therefore, integer keys must not be used for other purposes. 2814 2815 2816<p> 2817When you create a new Lua state, 2818its registry comes with some predefined values. 2819These predefined values are indexed with integer keys 2820defined as constants in <code>lua.h</code>. 2821The following constants are defined: 2822 2823<ul> 2824<li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has 2825the main thread of the state. 2826(The main thread is the one created together with the state.) 2827</li> 2828 2829<li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has 2830the global environment. 2831</li> 2832</ul> 2833 2834 2835 2836 2837<h2>4.6 – <a name="4.6">Error Handling in C</a></h2> 2838 2839<p> 2840Internally, Lua uses the C <code>longjmp</code> facility to handle errors. 2841(Lua will use exceptions if you compile it as C++; 2842search for <code>LUAI_THROW</code> in the source code for details.) 2843When Lua faces any error 2844(such as a memory allocation error or a type error) 2845it <em>raises</em> an error; 2846that is, it does a long jump. 2847A <em>protected environment</em> uses <code>setjmp</code> 2848to set a recovery point; 2849any error jumps to the most recent active recovery point. 2850 2851 2852<p> 2853Inside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>. 2854 2855 2856<p> 2857Most functions in the API can raise an error, 2858for instance due to a memory allocation error. 2859The documentation for each function indicates whether 2860it can raise errors. 2861 2862 2863<p> 2864If an error happens outside any protected environment, 2865Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) 2866and then calls <code>abort</code>, 2867thus exiting the host application. 2868Your panic function can avoid this exit by 2869never returning 2870(e.g., doing a long jump to your own recovery point outside Lua). 2871 2872 2873<p> 2874The panic function, 2875as its name implies, 2876is a mechanism of last resort. 2877Programs should avoid it. 2878As a general rule, 2879when a C function is called by Lua with a Lua state, 2880it can do whatever it wants on that Lua state, 2881as it should be already protected. 2882However, 2883when C code operates on other Lua states 2884(e.g., a Lua parameter to the function, 2885a Lua state stored in the registry, or 2886the result of <a href="#lua_newthread"><code>lua_newthread</code></a>), 2887it should use them only in API calls that cannot raise errors. 2888 2889 2890<p> 2891The panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>); 2892in particular, the error object is at the top of the stack. 2893However, there is no guarantee about stack space. 2894To push anything on the stack, 2895the panic function must first check the available space (see <a href="#4.2">§4.2</a>). 2896 2897 2898 2899 2900 2901<h2>4.7 – <a name="4.7">Handling Yields in C</a></h2> 2902 2903<p> 2904Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine. 2905Therefore, if a C function <code>foo</code> calls an API function 2906and this API function yields 2907(directly or indirectly by calling another function that yields), 2908Lua cannot return to <code>foo</code> any more, 2909because the <code>longjmp</code> removes its frame from the C stack. 2910 2911 2912<p> 2913To avoid this kind of problem, 2914Lua raises an error whenever it tries to yield across an API call, 2915except for three functions: 2916<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>. 2917All those functions receive a <em>continuation function</em> 2918(as a parameter named <code>k</code>) to continue execution after a yield. 2919 2920 2921<p> 2922We need to set some terminology to explain continuations. 2923We have a C function called from Lua which we will call 2924the <em>original function</em>. 2925This original function then calls one of those three functions in the C API, 2926which we will call the <em>callee function</em>, 2927that then yields the current thread. 2928(This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 2929or 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> 2930and the function called by them yields.) 2931 2932 2933<p> 2934Suppose the running thread yields while executing the callee function. 2935After the thread resumes, 2936it eventually will finish running the callee function. 2937However, 2938the callee function cannot return to the original function, 2939because its frame in the C stack was destroyed by the yield. 2940Instead, Lua calls a <em>continuation function</em>, 2941which was given as an argument to the callee function. 2942As the name implies, 2943the continuation function should continue the task 2944of the original function. 2945 2946 2947<p> 2948As an illustration, consider the following function: 2949 2950<pre> 2951 int original_function (lua_State *L) { 2952 ... /* code 1 */ 2953 status = lua_pcall(L, n, m, h); /* calls Lua */ 2954 ... /* code 2 */ 2955 } 2956</pre><p> 2957Now we want to allow 2958the Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield. 2959First, we can rewrite our function like here: 2960 2961<pre> 2962 int k (lua_State *L, int status, lua_KContext ctx) { 2963 ... /* code 2 */ 2964 } 2965 2966 int original_function (lua_State *L) { 2967 ... /* code 1 */ 2968 return k(L, lua_pcall(L, n, m, h), ctx); 2969 } 2970</pre><p> 2971In the above code, 2972the new function <code>k</code> is a 2973<em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>), 2974which should do all the work that the original function 2975was doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>. 2976Now, we must inform Lua that it must call <code>k</code> if the Lua code 2977being executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way 2978(errors or yielding), 2979so we rewrite the code as here, 2980replacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>: 2981 2982<pre> 2983 int original_function (lua_State *L) { 2984 ... /* code 1 */ 2985 return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1); 2986 } 2987</pre><p> 2988Note the external, explicit call to the continuation: 2989Lua will call the continuation only if needed, that is, 2990in case of errors or resuming after a yield. 2991If the called function returns normally without ever yielding, 2992<a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally. 2993(Of course, instead of calling the continuation in that case, 2994you can do the equivalent work directly inside the original function.) 2995 2996 2997<p> 2998Besides the Lua state, 2999the continuation function has two other parameters: 3000the final status of the call plus the context value (<code>ctx</code>) that 3001was passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>. 3002(Lua does not use this context value; 3003it only passes this value from the original function to the 3004continuation function.) 3005For <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 3006the status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 3007except that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield 3008(instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>). 3009For <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>, 3010the status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation. 3011(For these two functions, 3012Lua will not call the continuation in case of errors, 3013because they do not handle errors.) 3014Similarly, when using <a href="#lua_callk"><code>lua_callk</code></a>, 3015you should call the continuation function 3016with <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status. 3017(For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling 3018directly the continuation function, 3019because <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.) 3020 3021 3022<p> 3023Lua treats the continuation function as if it were the original function. 3024The continuation function receives the same Lua stack 3025from the original function, 3026in the same state it would be if the callee function had returned. 3027(For instance, 3028after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are 3029removed from the stack and replaced by the results from the call.) 3030It also has the same upvalues. 3031Whatever it returns is handled by Lua as if it were the return 3032of the original function. 3033 3034 3035 3036 3037 3038<h2>4.8 – <a name="4.8">Functions and Types</a></h2> 3039 3040<p> 3041Here we list all functions and types from the C API in 3042alphabetical order. 3043Each function has an indicator like this: 3044<span class="apii">[-o, +p, <em>x</em>]</span> 3045 3046 3047<p> 3048The first field, <code>o</code>, 3049is how many elements the function pops from the stack. 3050The second field, <code>p</code>, 3051is how many elements the function pushes onto the stack. 3052(Any function always pushes its results after popping its arguments.) 3053A field in the form <code>x|y</code> means the function can push (or pop) 3054<code>x</code> or <code>y</code> elements, 3055depending on the situation; 3056an interrogation mark '<code>?</code>' means that 3057we cannot know how many elements the function pops/pushes 3058by looking only at its arguments 3059(e.g., they may depend on what is on the stack). 3060The third field, <code>x</code>, 3061tells whether the function may raise errors: 3062'<code>-</code>' means the function never raises any error; 3063'<code>m</code>' means the function may raise out-of-memory errors 3064and errors running a <code>__gc</code> metamethod; 3065'<code>e</code>' means the function may raise any errors 3066(it can run arbitrary Lua code, 3067either directly or through metamethods); 3068'<code>v</code>' means the function may raise an error on purpose. 3069 3070 3071 3072<hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p> 3073<span class="apii">[-0, +0, –]</span> 3074<pre>int lua_absindex (lua_State *L, int idx);</pre> 3075 3076<p> 3077Converts the acceptable index <code>idx</code> 3078into an equivalent absolute index 3079(that is, one that does not depend on the stack top). 3080 3081 3082 3083 3084 3085<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> 3086<pre>typedef void * (*lua_Alloc) (void *ud, 3087 void *ptr, 3088 size_t osize, 3089 size_t nsize);</pre> 3090 3091<p> 3092The type of the memory-allocation function used by Lua states. 3093The allocator function must provide a 3094functionality similar to <code>realloc</code>, 3095but not exactly the same. 3096Its arguments are 3097<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; 3098<code>ptr</code>, a pointer to the block being allocated/reallocated/freed; 3099<code>osize</code>, the original size of the block or some code about what 3100is being allocated; 3101and <code>nsize</code>, the new size of the block. 3102 3103 3104<p> 3105When <code>ptr</code> is not <code>NULL</code>, 3106<code>osize</code> is the size of the block pointed by <code>ptr</code>, 3107that is, the size given when it was allocated or reallocated. 3108 3109 3110<p> 3111When <code>ptr</code> is <code>NULL</code>, 3112<code>osize</code> encodes the kind of object that Lua is allocating. 3113<code>osize</code> is any of 3114<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>, 3115<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) 3116Lua is creating a new object of that type. 3117When <code>osize</code> is some other value, 3118Lua is allocating memory for something else. 3119 3120 3121<p> 3122Lua assumes the following behavior from the allocator function: 3123 3124 3125<p> 3126When <code>nsize</code> is zero, 3127the allocator must behave like <code>free</code> 3128and return <code>NULL</code>. 3129 3130 3131<p> 3132When <code>nsize</code> is not zero, 3133the allocator must behave like <code>realloc</code>. 3134The allocator returns <code>NULL</code> 3135if and only if it cannot fulfill the request. 3136Lua assumes that the allocator never fails when 3137<code>osize >= nsize</code>. 3138 3139 3140<p> 3141Here is a simple implementation for the allocator function. 3142It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. 3143 3144<pre> 3145 static void *l_alloc (void *ud, void *ptr, size_t osize, 3146 size_t nsize) { 3147 (void)ud; (void)osize; /* not used */ 3148 if (nsize == 0) { 3149 free(ptr); 3150 return NULL; 3151 } 3152 else 3153 return realloc(ptr, nsize); 3154 } 3155</pre><p> 3156Note that Standard C ensures 3157that <code>free(NULL)</code> has no effect and that 3158<code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>. 3159This code assumes that <code>realloc</code> does not fail when shrinking a block. 3160(Although Standard C does not ensure this behavior, 3161it seems to be a safe assumption.) 3162 3163 3164 3165 3166 3167<hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p> 3168<span class="apii">[-(2|1), +1, <em>e</em>]</span> 3169<pre>void lua_arith (lua_State *L, int op);</pre> 3170 3171<p> 3172Performs an arithmetic or bitwise operation over the two values 3173(or one, in the case of negations) 3174at the top of the stack, 3175with the value at the top being the second operand, 3176pops these values, and pushes the result of the operation. 3177The function follows the semantics of the corresponding Lua operator 3178(that is, it may call metamethods). 3179 3180 3181<p> 3182The value of <code>op</code> must be one of the following constants: 3183 3184<ul> 3185 3186<li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li> 3187<li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li> 3188<li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li> 3189<li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li> 3190<li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li> 3191<li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li> 3192<li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li> 3193<li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li> 3194<li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li> 3195<li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&</code>)</li> 3196<li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li> 3197<li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li> 3198<li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li> 3199<li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li> 3200 3201</ul> 3202 3203 3204 3205 3206<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> 3207<span class="apii">[-0, +0, –]</span> 3208<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> 3209 3210<p> 3211Sets a new panic function and returns the old one (see <a href="#4.6">§4.6</a>). 3212 3213 3214 3215 3216 3217<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> 3218<span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span> 3219<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> 3220 3221<p> 3222Calls a function. 3223 3224 3225<p> 3226To call a function you must use the following protocol: 3227first, the function to be called is pushed onto the stack; 3228then, the arguments to the function are pushed 3229in direct order; 3230that is, the first argument is pushed first. 3231Finally you call <a href="#lua_call"><code>lua_call</code></a>; 3232<code>nargs</code> is the number of arguments that you pushed onto the stack. 3233All arguments and the function value are popped from the stack 3234when the function is called. 3235The function results are pushed onto the stack when the function returns. 3236The number of results is adjusted to <code>nresults</code>, 3237unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. 3238In this case, all results from the function are pushed; 3239Lua takes care that the returned values fit into the stack space, 3240but it does not ensure any extra space in the stack. 3241The function results are pushed onto the stack in direct order 3242(the first result is pushed first), 3243so that after the call the last result is on the top of the stack. 3244 3245 3246<p> 3247Any error inside the called function is propagated upwards 3248(with a <code>longjmp</code>). 3249 3250 3251<p> 3252The following example shows how the host program can do the 3253equivalent to this Lua code: 3254 3255<pre> 3256 a = f("how", t.x, 14) 3257</pre><p> 3258Here it is in C: 3259 3260<pre> 3261 lua_getglobal(L, "f"); /* function to be called */ 3262 lua_pushliteral(L, "how"); /* 1st argument */ 3263 lua_getglobal(L, "t"); /* table to be indexed */ 3264 lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 3265 lua_remove(L, -2); /* remove 't' from the stack */ 3266 lua_pushinteger(L, 14); /* 3rd argument */ 3267 lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ 3268 lua_setglobal(L, "a"); /* set global 'a' */ 3269</pre><p> 3270Note that the code above is <em>balanced</em>: 3271at its end, the stack is back to its original configuration. 3272This is considered good programming practice. 3273 3274 3275 3276 3277 3278<hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p> 3279<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> 3280<pre>void lua_callk (lua_State *L, 3281 int nargs, 3282 int nresults, 3283 lua_KContext ctx, 3284 lua_KFunction k);</pre> 3285 3286<p> 3287This function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>, 3288but allows the called function to yield (see <a href="#4.7">§4.7</a>). 3289 3290 3291 3292 3293 3294<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> 3295<pre>typedef int (*lua_CFunction) (lua_State *L);</pre> 3296 3297<p> 3298Type for C functions. 3299 3300 3301<p> 3302In order to communicate properly with Lua, 3303a C function must use the following protocol, 3304which defines the way parameters and results are passed: 3305a C function receives its arguments from Lua in its stack 3306in direct order (the first argument is pushed first). 3307So, when the function starts, 3308<code>lua_gettop(L)</code> returns the number of arguments received by the function. 3309The first argument (if any) is at index 1 3310and its last argument is at index <code>lua_gettop(L)</code>. 3311To return values to Lua, a C function just pushes them onto the stack, 3312in direct order (the first result is pushed first), 3313and returns the number of results. 3314Any other value in the stack below the results will be properly 3315discarded by Lua. 3316Like a Lua function, a C function called by Lua can also return 3317many results. 3318 3319 3320<p> 3321As an example, the following function receives a variable number 3322of numeric arguments and returns their average and their sum: 3323 3324<pre> 3325 static int foo (lua_State *L) { 3326 int n = lua_gettop(L); /* number of arguments */ 3327 lua_Number sum = 0.0; 3328 int i; 3329 for (i = 1; i <= n; i++) { 3330 if (!lua_isnumber(L, i)) { 3331 lua_pushliteral(L, "incorrect argument"); 3332 lua_error(L); 3333 } 3334 sum += lua_tonumber(L, i); 3335 } 3336 lua_pushnumber(L, sum/n); /* first result */ 3337 lua_pushnumber(L, sum); /* second result */ 3338 return 2; /* number of results */ 3339 } 3340</pre> 3341 3342 3343 3344 3345<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> 3346<span class="apii">[-0, +0, –]</span> 3347<pre>int lua_checkstack (lua_State *L, int n);</pre> 3348 3349<p> 3350Ensures that the stack has space for at least <code>n</code> extra slots 3351(that is, that you can safely push up to <code>n</code> values into it). 3352It returns false if it cannot fulfill the request, 3353either because it would cause the stack 3354to be larger than a fixed maximum size 3355(typically at least several thousand elements) or 3356because it cannot allocate memory for the extra space. 3357This function never shrinks the stack; 3358if the stack already has space for the extra slots, 3359it is left unchanged. 3360 3361 3362 3363 3364 3365<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> 3366<span class="apii">[-0, +0, –]</span> 3367<pre>void lua_close (lua_State *L);</pre> 3368 3369<p> 3370Destroys all objects in the given Lua state 3371(calling the corresponding garbage-collection metamethods, if any) 3372and frees all dynamic memory used by this state. 3373On several platforms, you may not need to call this function, 3374because all resources are naturally released when the host program ends. 3375On the other hand, long-running programs that create multiple states, 3376such as daemons or web servers, 3377will probably need to close states as soon as they are not needed. 3378 3379 3380 3381 3382 3383<hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p> 3384<span class="apii">[-0, +0, <em>e</em>]</span> 3385<pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre> 3386 3387<p> 3388Compares two Lua values. 3389Returns 1 if the value at index <code>index1</code> satisfies <code>op</code> 3390when compared with the value at index <code>index2</code>, 3391following the semantics of the corresponding Lua operator 3392(that is, it may call metamethods). 3393Otherwise returns 0. 3394Also returns 0 if any of the indices is not valid. 3395 3396 3397<p> 3398The value of <code>op</code> must be one of the following constants: 3399 3400<ul> 3401 3402<li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li> 3403<li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li> 3404<li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li> 3405 3406</ul> 3407 3408 3409 3410 3411<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> 3412<span class="apii">[-n, +1, <em>e</em>]</span> 3413<pre>void lua_concat (lua_State *L, int n);</pre> 3414 3415<p> 3416Concatenates the <code>n</code> values at the top of the stack, 3417pops them, and leaves the result at the top. 3418If <code>n</code> is 1, the result is the single value on the stack 3419(that is, the function does nothing); 3420if <code>n</code> is 0, the result is the empty string. 3421Concatenation is performed following the usual semantics of Lua 3422(see <a href="#3.4.6">§3.4.6</a>). 3423 3424 3425 3426 3427 3428<hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p> 3429<span class="apii">[-0, +0, –]</span> 3430<pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre> 3431 3432<p> 3433Copies the element at index <code>fromidx</code> 3434into the valid index <code>toidx</code>, 3435replacing the value at that position. 3436Values at other positions are not affected. 3437 3438 3439 3440 3441 3442<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> 3443<span class="apii">[-0, +1, <em>m</em>]</span> 3444<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> 3445 3446<p> 3447Creates a new empty table and pushes it onto the stack. 3448Parameter <code>narr</code> is a hint for how many elements the table 3449will have as a sequence; 3450parameter <code>nrec</code> is a hint for how many other elements 3451the table will have. 3452Lua may use these hints to preallocate memory for the new table. 3453This preallocation is useful for performance when you know in advance 3454how many elements the table will have. 3455Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. 3456 3457 3458 3459 3460 3461<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> 3462<span class="apii">[-0, +0, –]</span> 3463<pre>int lua_dump (lua_State *L, 3464 lua_Writer writer, 3465 void *data, 3466 int strip);</pre> 3467 3468<p> 3469Dumps a function as a binary chunk. 3470Receives a Lua function on the top of the stack 3471and produces a binary chunk that, 3472if loaded again, 3473results in a function equivalent to the one dumped. 3474As it produces parts of the chunk, 3475<a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>) 3476with the given <code>data</code> 3477to write them. 3478 3479 3480<p> 3481If <code>strip</code> is true, 3482the binary representation may not include all debug information 3483about the function, 3484to save space. 3485 3486 3487<p> 3488The value returned is the error code returned by the last 3489call to the writer; 34900 means no errors. 3491 3492 3493<p> 3494This function does not pop the Lua function from the stack. 3495 3496 3497 3498 3499 3500<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> 3501<span class="apii">[-1, +0, <em>v</em>]</span> 3502<pre>int lua_error (lua_State *L);</pre> 3503 3504<p> 3505Generates a Lua error, 3506using the value at the top of the stack as the error object. 3507This function does a long jump, 3508and therefore never returns 3509(see <a href="#luaL_error"><code>luaL_error</code></a>). 3510 3511 3512 3513 3514 3515<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> 3516<span class="apii">[-0, +0, <em>m</em>]</span> 3517<pre>int lua_gc (lua_State *L, int what, int data);</pre> 3518 3519<p> 3520Controls the garbage collector. 3521 3522 3523<p> 3524This function performs several tasks, 3525according to the value of the parameter <code>what</code>: 3526 3527<ul> 3528 3529<li><b><code>LUA_GCSTOP</code>: </b> 3530stops the garbage collector. 3531</li> 3532 3533<li><b><code>LUA_GCRESTART</code>: </b> 3534restarts the garbage collector. 3535</li> 3536 3537<li><b><code>LUA_GCCOLLECT</code>: </b> 3538performs a full garbage-collection cycle. 3539</li> 3540 3541<li><b><code>LUA_GCCOUNT</code>: </b> 3542returns the current amount of memory (in Kbytes) in use by Lua. 3543</li> 3544 3545<li><b><code>LUA_GCCOUNTB</code>: </b> 3546returns the remainder of dividing the current amount of bytes of 3547memory in use by Lua by 1024. 3548</li> 3549 3550<li><b><code>LUA_GCSTEP</code>: </b> 3551performs an incremental step of garbage collection. 3552</li> 3553 3554<li><b><code>LUA_GCSETPAUSE</code>: </b> 3555sets <code>data</code> as the new value 3556for the <em>pause</em> of the collector (see <a href="#2.5">§2.5</a>) 3557and returns the previous value of the pause. 3558</li> 3559 3560<li><b><code>LUA_GCSETSTEPMUL</code>: </b> 3561sets <code>data</code> as the new value for the <em>step multiplier</em> of 3562the collector (see <a href="#2.5">§2.5</a>) 3563and returns the previous value of the step multiplier. 3564</li> 3565 3566<li><b><code>LUA_GCISRUNNING</code>: </b> 3567returns a boolean that tells whether the collector is running 3568(i.e., not stopped). 3569</li> 3570 3571</ul> 3572 3573<p> 3574For more details about these options, 3575see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>. 3576 3577 3578 3579 3580 3581<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> 3582<span class="apii">[-0, +0, –]</span> 3583<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> 3584 3585<p> 3586Returns the memory-allocation function of a given state. 3587If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the 3588opaque pointer given when the memory-allocator function was set. 3589 3590 3591 3592 3593 3594<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> 3595<span class="apii">[-0, +1, <em>e</em>]</span> 3596<pre>int lua_getfield (lua_State *L, int index, const char *k);</pre> 3597 3598<p> 3599Pushes onto the stack the value <code>t[k]</code>, 3600where <code>t</code> is the value at the given index. 3601As in Lua, this function may trigger a metamethod 3602for the "index" event (see <a href="#2.4">§2.4</a>). 3603 3604 3605<p> 3606Returns the type of the pushed value. 3607 3608 3609 3610 3611 3612<hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p> 3613<span class="apii">[-0, +0, –]</span> 3614<pre>void *lua_getextraspace (lua_State *L);</pre> 3615 3616<p> 3617Returns a pointer to a raw memory area associated with the 3618given Lua state. 3619The application can use this area for any purpose; 3620Lua does not use it for anything. 3621 3622 3623<p> 3624Each new thread has this area initialized with a copy 3625of the area of the main thread. 3626 3627 3628<p> 3629By default, this area has the size of a pointer to void, 3630but you can recompile Lua with a different size for this area. 3631(See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.) 3632 3633 3634 3635 3636 3637<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> 3638<span class="apii">[-0, +1, <em>e</em>]</span> 3639<pre>int lua_getglobal (lua_State *L, const char *name);</pre> 3640 3641<p> 3642Pushes onto the stack the value of the global <code>name</code>. 3643Returns the type of that value. 3644 3645 3646 3647 3648 3649<hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p> 3650<span class="apii">[-0, +1, <em>e</em>]</span> 3651<pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre> 3652 3653<p> 3654Pushes onto the stack the value <code>t[i]</code>, 3655where <code>t</code> is the value at the given index. 3656As in Lua, this function may trigger a metamethod 3657for the "index" event (see <a href="#2.4">§2.4</a>). 3658 3659 3660<p> 3661Returns the type of the pushed value. 3662 3663 3664 3665 3666 3667<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> 3668<span class="apii">[-0, +(0|1), –]</span> 3669<pre>int lua_getmetatable (lua_State *L, int index);</pre> 3670 3671<p> 3672If the value at the given index has a metatable, 3673the function pushes that metatable onto the stack and returns 1. 3674Otherwise, 3675the function returns 0 and pushes nothing on the stack. 3676 3677 3678 3679 3680 3681<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> 3682<span class="apii">[-1, +1, <em>e</em>]</span> 3683<pre>int lua_gettable (lua_State *L, int index);</pre> 3684 3685<p> 3686Pushes onto the stack the value <code>t[k]</code>, 3687where <code>t</code> is the value at the given index 3688and <code>k</code> is the value at the top of the stack. 3689 3690 3691<p> 3692This function pops the key from the stack, 3693pushing the resulting value in its place. 3694As in Lua, this function may trigger a metamethod 3695for the "index" event (see <a href="#2.4">§2.4</a>). 3696 3697 3698<p> 3699Returns the type of the pushed value. 3700 3701 3702 3703 3704 3705<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> 3706<span class="apii">[-0, +0, –]</span> 3707<pre>int lua_gettop (lua_State *L);</pre> 3708 3709<p> 3710Returns the index of the top element in the stack. 3711Because indices start at 1, 3712this result is equal to the number of elements in the stack; 3713in particular, 0 means an empty stack. 3714 3715 3716 3717 3718 3719<hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p> 3720<span class="apii">[-0, +1, –]</span> 3721<pre>int lua_getuservalue (lua_State *L, int index);</pre> 3722 3723<p> 3724Pushes onto the stack the Lua value associated with the full userdata 3725at the given index. 3726 3727 3728<p> 3729Returns the type of the pushed value. 3730 3731 3732 3733 3734 3735<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> 3736<span class="apii">[-1, +1, –]</span> 3737<pre>void lua_insert (lua_State *L, int index);</pre> 3738 3739<p> 3740Moves the top element into the given valid index, 3741shifting up the elements above this index to open space. 3742This function cannot be called with a pseudo-index, 3743because a pseudo-index is not an actual stack position. 3744 3745 3746 3747 3748 3749<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> 3750<pre>typedef ... lua_Integer;</pre> 3751 3752<p> 3753The type of integers in Lua. 3754 3755 3756<p> 3757By default this type is <code>long long</code>, 3758(usually a 64-bit two-complement integer), 3759but that can be changed to <code>long</code> or <code>int</code> 3760(usually a 32-bit two-complement integer). 3761(See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.) 3762 3763 3764<p> 3765Lua also defines the constants 3766<a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>, 3767with the minimum and the maximum values that fit in this type. 3768 3769 3770 3771 3772 3773<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> 3774<span class="apii">[-0, +0, –]</span> 3775<pre>int lua_isboolean (lua_State *L, int index);</pre> 3776 3777<p> 3778Returns 1 if the value at the given index is a boolean, 3779and 0 otherwise. 3780 3781 3782 3783 3784 3785<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> 3786<span class="apii">[-0, +0, –]</span> 3787<pre>int lua_iscfunction (lua_State *L, int index);</pre> 3788 3789<p> 3790Returns 1 if the value at the given index is a C function, 3791and 0 otherwise. 3792 3793 3794 3795 3796 3797<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> 3798<span class="apii">[-0, +0, –]</span> 3799<pre>int lua_isfunction (lua_State *L, int index);</pre> 3800 3801<p> 3802Returns 1 if the value at the given index is a function 3803(either C or Lua), and 0 otherwise. 3804 3805 3806 3807 3808 3809<hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p> 3810<span class="apii">[-0, +0, –]</span> 3811<pre>int lua_isinteger (lua_State *L, int index);</pre> 3812 3813<p> 3814Returns 1 if the value at the given index is an integer 3815(that is, the value is a number and is represented as an integer), 3816and 0 otherwise. 3817 3818 3819 3820 3821 3822<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> 3823<span class="apii">[-0, +0, –]</span> 3824<pre>int lua_islightuserdata (lua_State *L, int index);</pre> 3825 3826<p> 3827Returns 1 if the value at the given index is a light userdata, 3828and 0 otherwise. 3829 3830 3831 3832 3833 3834<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> 3835<span class="apii">[-0, +0, –]</span> 3836<pre>int lua_isnil (lua_State *L, int index);</pre> 3837 3838<p> 3839Returns 1 if the value at the given index is <b>nil</b>, 3840and 0 otherwise. 3841 3842 3843 3844 3845 3846<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> 3847<span class="apii">[-0, +0, –]</span> 3848<pre>int lua_isnone (lua_State *L, int index);</pre> 3849 3850<p> 3851Returns 1 if the given index is not valid, 3852and 0 otherwise. 3853 3854 3855 3856 3857 3858<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> 3859<span class="apii">[-0, +0, –]</span> 3860<pre>int lua_isnoneornil (lua_State *L, int index);</pre> 3861 3862<p> 3863Returns 1 if the given index is not valid 3864or if the value at this index is <b>nil</b>, 3865and 0 otherwise. 3866 3867 3868 3869 3870 3871<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> 3872<span class="apii">[-0, +0, –]</span> 3873<pre>int lua_isnumber (lua_State *L, int index);</pre> 3874 3875<p> 3876Returns 1 if the value at the given index is a number 3877or a string convertible to a number, 3878and 0 otherwise. 3879 3880 3881 3882 3883 3884<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> 3885<span class="apii">[-0, +0, –]</span> 3886<pre>int lua_isstring (lua_State *L, int index);</pre> 3887 3888<p> 3889Returns 1 if the value at the given index is a string 3890or a number (which is always convertible to a string), 3891and 0 otherwise. 3892 3893 3894 3895 3896 3897<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> 3898<span class="apii">[-0, +0, –]</span> 3899<pre>int lua_istable (lua_State *L, int index);</pre> 3900 3901<p> 3902Returns 1 if the value at the given index is a table, 3903and 0 otherwise. 3904 3905 3906 3907 3908 3909<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> 3910<span class="apii">[-0, +0, –]</span> 3911<pre>int lua_isthread (lua_State *L, int index);</pre> 3912 3913<p> 3914Returns 1 if the value at the given index is a thread, 3915and 0 otherwise. 3916 3917 3918 3919 3920 3921<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> 3922<span class="apii">[-0, +0, –]</span> 3923<pre>int lua_isuserdata (lua_State *L, int index);</pre> 3924 3925<p> 3926Returns 1 if the value at the given index is a userdata 3927(either full or light), and 0 otherwise. 3928 3929 3930 3931 3932 3933<hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p> 3934<span class="apii">[-0, +0, –]</span> 3935<pre>int lua_isyieldable (lua_State *L);</pre> 3936 3937<p> 3938Returns 1 if the given coroutine can yield, 3939and 0 otherwise. 3940 3941 3942 3943 3944 3945<hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3> 3946<pre>typedef ... lua_KContext;</pre> 3947 3948<p> 3949The type for continuation-function contexts. 3950It must be a numeric type. 3951This type is defined as <code>intptr_t</code> 3952when <code>intptr_t</code> is available, 3953so that it can store pointers too. 3954Otherwise, it is defined as <code>ptrdiff_t</code>. 3955 3956 3957 3958 3959 3960<hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3> 3961<pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre> 3962 3963<p> 3964Type for continuation functions (see <a href="#4.7">§4.7</a>). 3965 3966 3967 3968 3969 3970<hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p> 3971<span class="apii">[-0, +1, <em>e</em>]</span> 3972<pre>void lua_len (lua_State *L, int index);</pre> 3973 3974<p> 3975Returns the length of the value at the given index. 3976It is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>) and 3977may trigger a metamethod for the "length" event (see <a href="#2.4">§2.4</a>). 3978The result is pushed on the stack. 3979 3980 3981 3982 3983 3984<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> 3985<span class="apii">[-0, +1, –]</span> 3986<pre>int lua_load (lua_State *L, 3987 lua_Reader reader, 3988 void *data, 3989 const char *chunkname, 3990 const char *mode);</pre> 3991 3992<p> 3993Loads a Lua chunk without running it. 3994If there are no errors, 3995<code>lua_load</code> pushes the compiled chunk as a Lua 3996function on top of the stack. 3997Otherwise, it pushes an error message. 3998 3999 4000<p> 4001The return values of <code>lua_load</code> are: 4002 4003<ul> 4004 4005<li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li> 4006 4007<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> 4008syntax error during precompilation;</li> 4009 4010<li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 4011memory allocation (out-of-memory) error;</li> 4012 4013<li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> 4014error while running a <code>__gc</code> metamethod. 4015(This error has no relation with the chunk being loaded. 4016It is generated by the garbage collector.) 4017</li> 4018 4019</ul> 4020 4021<p> 4022The <code>lua_load</code> function uses a user-supplied <code>reader</code> function 4023to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). 4024The <code>data</code> argument is an opaque value passed to the reader function. 4025 4026 4027<p> 4028The <code>chunkname</code> argument gives a name to the chunk, 4029which is used for error messages and in debug information (see <a href="#4.9">§4.9</a>). 4030 4031 4032<p> 4033<code>lua_load</code> automatically detects whether the chunk is text or binary 4034and loads it accordingly (see program <code>luac</code>). 4035The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>, 4036with the addition that 4037a <code>NULL</code> value is equivalent to the string "<code>bt</code>". 4038 4039 4040<p> 4041<code>lua_load</code> uses the stack internally, 4042so the reader function must always leave the stack 4043unmodified when returning. 4044 4045 4046<p> 4047If the resulting function has upvalues, 4048its first upvalue is set to the value of the global environment 4049stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">§4.5</a>). 4050When loading main chunks, 4051this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 4052Other upvalues are initialized with <b>nil</b>. 4053 4054 4055 4056 4057 4058<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> 4059<span class="apii">[-0, +0, –]</span> 4060<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> 4061 4062<p> 4063Creates a new thread running in a new, independent state. 4064Returns <code>NULL</code> if it cannot create the thread or the state 4065(due to lack of memory). 4066The argument <code>f</code> is the allocator function; 4067Lua does all memory allocation for this state 4068through this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>). 4069The second argument, <code>ud</code>, is an opaque pointer that Lua 4070passes to the allocator in every call. 4071 4072 4073 4074 4075 4076<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> 4077<span class="apii">[-0, +1, <em>m</em>]</span> 4078<pre>void lua_newtable (lua_State *L);</pre> 4079 4080<p> 4081Creates a new empty table and pushes it onto the stack. 4082It is equivalent to <code>lua_createtable(L, 0, 0)</code>. 4083 4084 4085 4086 4087 4088<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> 4089<span class="apii">[-0, +1, <em>m</em>]</span> 4090<pre>lua_State *lua_newthread (lua_State *L);</pre> 4091 4092<p> 4093Creates a new thread, pushes it on the stack, 4094and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. 4095The new thread returned by this function shares with the original thread 4096its global environment, 4097but has an independent execution stack. 4098 4099 4100<p> 4101There is no explicit function to close or to destroy a thread. 4102Threads are subject to garbage collection, 4103like any Lua object. 4104 4105 4106 4107 4108 4109<hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p> 4110<span class="apii">[-0, +1, <em>m</em>]</span> 4111<pre>void *lua_newuserdata (lua_State *L, size_t size);</pre> 4112 4113<p> 4114This function allocates a new block of memory with the given size, 4115pushes onto the stack a new full userdata with the block address, 4116and returns this address. 4117The host program can freely use this memory. 4118 4119 4120 4121 4122 4123<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> 4124<span class="apii">[-1, +(2|0), <em>e</em>]</span> 4125<pre>int lua_next (lua_State *L, int index);</pre> 4126 4127<p> 4128Pops a key from the stack, 4129and pushes a key–value pair from the table at the given index 4130(the "next" pair after the given key). 4131If there are no more elements in the table, 4132then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). 4133 4134 4135<p> 4136A typical traversal looks like this: 4137 4138<pre> 4139 /* table is in the stack at index 't' */ 4140 lua_pushnil(L); /* first key */ 4141 while (lua_next(L, t) != 0) { 4142 /* uses 'key' (at index -2) and 'value' (at index -1) */ 4143 printf("%s - %s\n", 4144 lua_typename(L, lua_type(L, -2)), 4145 lua_typename(L, lua_type(L, -1))); 4146 /* removes 'value'; keeps 'key' for next iteration */ 4147 lua_pop(L, 1); 4148 } 4149</pre> 4150 4151<p> 4152While traversing a table, 4153do not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, 4154unless you know that the key is actually a string. 4155Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change 4156the value at the given index; 4157this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. 4158 4159 4160<p> 4161See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 4162the table during its traversal. 4163 4164 4165 4166 4167 4168<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> 4169<pre>typedef ... lua_Number;</pre> 4170 4171<p> 4172The type of floats in Lua. 4173 4174 4175<p> 4176By default this type is double, 4177but that can be changed to a single float or a long double. 4178(See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.) 4179 4180 4181 4182 4183 4184<hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3> 4185<pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre> 4186 4187<p> 4188Converts a Lua float to a Lua integer. 4189This macro assumes that <code>n</code> has an integral value. 4190If that value is within the range of Lua integers, 4191it is converted to an integer and assigned to <code>*p</code>. 4192The macro results in a boolean indicating whether the 4193conversion was successful. 4194(Note that this range test can be tricky to do 4195correctly without this macro, 4196due to roundings.) 4197 4198 4199<p> 4200This macro may evaluate its arguments more than once. 4201 4202 4203 4204 4205 4206<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> 4207<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4208<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre> 4209 4210<p> 4211Calls a function in protected mode. 4212 4213 4214<p> 4215Both <code>nargs</code> and <code>nresults</code> have the same meaning as 4216in <a href="#lua_call"><code>lua_call</code></a>. 4217If there are no errors during the call, 4218<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. 4219However, if there is any error, 4220<a href="#lua_pcall"><code>lua_pcall</code></a> catches it, 4221pushes a single value on the stack (the error object), 4222and returns an error code. 4223Like <a href="#lua_call"><code>lua_call</code></a>, 4224<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function 4225and its arguments from the stack. 4226 4227 4228<p> 4229If <code>msgh</code> is 0, 4230then the error object returned on the stack 4231is exactly the original error object. 4232Otherwise, <code>msgh</code> is the stack index of a 4233<em>message handler</em>. 4234(This index cannot be a pseudo-index.) 4235In case of runtime errors, 4236this function will be called with the error object 4237and its return value will be the object 4238returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. 4239 4240 4241<p> 4242Typically, the message handler is used to add more debug 4243information to the error object, such as a stack traceback. 4244Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, 4245since by then the stack has unwound. 4246 4247 4248<p> 4249The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following constants 4250(defined in <code>lua.h</code>): 4251 4252<ul> 4253 4254<li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> 4255success.</li> 4256 4257<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b> 4258a runtime error. 4259</li> 4260 4261<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 4262memory allocation error. 4263For such errors, Lua does not call the message handler. 4264</li> 4265 4266<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b> 4267error while running the message handler. 4268</li> 4269 4270<li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> 4271error while running a <code>__gc</code> metamethod. 4272For such errors, Lua does not call the message handler 4273(as this kind of error typically has no relation 4274with the function being called). 4275</li> 4276 4277</ul> 4278 4279 4280 4281 4282<hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p> 4283<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4284<pre>int lua_pcallk (lua_State *L, 4285 int nargs, 4286 int nresults, 4287 int msgh, 4288 lua_KContext ctx, 4289 lua_KFunction k);</pre> 4290 4291<p> 4292This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>, 4293but allows the called function to yield (see <a href="#4.7">§4.7</a>). 4294 4295 4296 4297 4298 4299<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> 4300<span class="apii">[-n, +0, –]</span> 4301<pre>void lua_pop (lua_State *L, int n);</pre> 4302 4303<p> 4304Pops <code>n</code> elements from the stack. 4305 4306 4307 4308 4309 4310<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> 4311<span class="apii">[-0, +1, –]</span> 4312<pre>void lua_pushboolean (lua_State *L, int b);</pre> 4313 4314<p> 4315Pushes a boolean value with value <code>b</code> onto the stack. 4316 4317 4318 4319 4320 4321<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> 4322<span class="apii">[-n, +1, <em>m</em>]</span> 4323<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> 4324 4325<p> 4326Pushes a new C closure onto the stack. 4327 4328 4329<p> 4330When a C function is created, 4331it is possible to associate some values with it, 4332thus creating a C closure (see <a href="#4.4">§4.4</a>); 4333these values are then accessible to the function whenever it is called. 4334To associate values with a C function, 4335first these values must be pushed onto the stack 4336(when there are multiple values, the first value is pushed first). 4337Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 4338is called to create and push the C function onto the stack, 4339with the argument <code>n</code> telling how many values will be 4340associated with the function. 4341<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. 4342 4343 4344<p> 4345The maximum value for <code>n</code> is 255. 4346 4347 4348<p> 4349When <code>n</code> is zero, 4350this function creates a <em>light C function</em>, 4351which is just a pointer to the C function. 4352In that case, it never raises a memory error. 4353 4354 4355 4356 4357 4358<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> 4359<span class="apii">[-0, +1, –]</span> 4360<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> 4361 4362<p> 4363Pushes a C function onto the stack. 4364This function receives a pointer to a C function 4365and pushes onto the stack a Lua value of type <code>function</code> that, 4366when called, invokes the corresponding C function. 4367 4368 4369<p> 4370Any function to be callable by Lua must 4371follow the correct protocol to receive its parameters 4372and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 4373 4374 4375 4376 4377 4378<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> 4379<span class="apii">[-0, +1, <em>e</em>]</span> 4380<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> 4381 4382<p> 4383Pushes onto the stack a formatted string 4384and returns a pointer to this string. 4385It is similar to the ISO C function <code>sprintf</code>, 4386but has some important differences: 4387 4388<ul> 4389 4390<li> 4391You do not have to allocate space for the result: 4392the result is a Lua string and Lua takes care of memory allocation 4393(and deallocation, through garbage collection). 4394</li> 4395 4396<li> 4397The conversion specifiers are quite restricted. 4398There are no flags, widths, or precisions. 4399The conversion specifiers can only be 4400'<code>%%</code>' (inserts the character '<code>%</code>'), 4401'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), 4402'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), 4403'<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>), 4404'<code>%p</code>' (inserts a pointer as a hexadecimal numeral), 4405'<code>%d</code>' (inserts an <code>int</code>), 4406'<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and 4407'<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence). 4408</li> 4409 4410</ul> 4411 4412<p> 4413Unlike other push functions, 4414this function checks for the stack space it needs, 4415including the slot for its result. 4416 4417 4418 4419 4420 4421<hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p> 4422<span class="apii">[-0, +1, –]</span> 4423<pre>void lua_pushglobaltable (lua_State *L);</pre> 4424 4425<p> 4426Pushes the global environment onto the stack. 4427 4428 4429 4430 4431 4432<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> 4433<span class="apii">[-0, +1, –]</span> 4434<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> 4435 4436<p> 4437Pushes an integer with value <code>n</code> onto the stack. 4438 4439 4440 4441 4442 4443<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> 4444<span class="apii">[-0, +1, –]</span> 4445<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> 4446 4447<p> 4448Pushes a light userdata onto the stack. 4449 4450 4451<p> 4452Userdata represent C values in Lua. 4453A <em>light userdata</em> represents a pointer, a <code>void*</code>. 4454It is a value (like a number): 4455you do not create it, it has no individual metatable, 4456and it is not collected (as it was never created). 4457A light userdata is equal to "any" 4458light userdata with the same C address. 4459 4460 4461 4462 4463 4464<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> 4465<span class="apii">[-0, +1, <em>m</em>]</span> 4466<pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre> 4467 4468<p> 4469This macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>, 4470but should be used only when <code>s</code> is a literal string. 4471 4472 4473 4474 4475 4476<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> 4477<span class="apii">[-0, +1, <em>m</em>]</span> 4478<pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> 4479 4480<p> 4481Pushes the string pointed to by <code>s</code> with size <code>len</code> 4482onto the stack. 4483Lua makes (or reuses) an internal copy of the given string, 4484so the memory at <code>s</code> can be freed or reused immediately after 4485the function returns. 4486The string can contain any binary data, 4487including embedded zeros. 4488 4489 4490<p> 4491Returns a pointer to the internal copy of the string. 4492 4493 4494 4495 4496 4497<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> 4498<span class="apii">[-0, +1, –]</span> 4499<pre>void lua_pushnil (lua_State *L);</pre> 4500 4501<p> 4502Pushes a nil value onto the stack. 4503 4504 4505 4506 4507 4508<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> 4509<span class="apii">[-0, +1, –]</span> 4510<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> 4511 4512<p> 4513Pushes a float with value <code>n</code> onto the stack. 4514 4515 4516 4517 4518 4519<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> 4520<span class="apii">[-0, +1, <em>m</em>]</span> 4521<pre>const char *lua_pushstring (lua_State *L, const char *s);</pre> 4522 4523<p> 4524Pushes the zero-terminated string pointed to by <code>s</code> 4525onto the stack. 4526Lua makes (or reuses) an internal copy of the given string, 4527so the memory at <code>s</code> can be freed or reused immediately after 4528the function returns. 4529 4530 4531<p> 4532Returns a pointer to the internal copy of the string. 4533 4534 4535<p> 4536If <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>. 4537 4538 4539 4540 4541 4542<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> 4543<span class="apii">[-0, +1, –]</span> 4544<pre>int lua_pushthread (lua_State *L);</pre> 4545 4546<p> 4547Pushes the thread represented by <code>L</code> onto the stack. 4548Returns 1 if this thread is the main thread of its state. 4549 4550 4551 4552 4553 4554<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> 4555<span class="apii">[-0, +1, –]</span> 4556<pre>void lua_pushvalue (lua_State *L, int index);</pre> 4557 4558<p> 4559Pushes a copy of the element at the given index 4560onto the stack. 4561 4562 4563 4564 4565 4566<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> 4567<span class="apii">[-0, +1, <em>m</em>]</span> 4568<pre>const char *lua_pushvfstring (lua_State *L, 4569 const char *fmt, 4570 va_list argp);</pre> 4571 4572<p> 4573Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> 4574instead of a variable number of arguments. 4575 4576 4577 4578 4579 4580<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> 4581<span class="apii">[-0, +0, –]</span> 4582<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> 4583 4584<p> 4585Returns 1 if the two values in indices <code>index1</code> and 4586<code>index2</code> are primitively equal 4587(that is, without calling the <code>__eq</code> metamethod). 4588Otherwise returns 0. 4589Also returns 0 if any of the indices are not valid. 4590 4591 4592 4593 4594 4595<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> 4596<span class="apii">[-1, +1, –]</span> 4597<pre>int lua_rawget (lua_State *L, int index);</pre> 4598 4599<p> 4600Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access 4601(i.e., without metamethods). 4602 4603 4604 4605 4606 4607<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> 4608<span class="apii">[-0, +1, –]</span> 4609<pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre> 4610 4611<p> 4612Pushes onto the stack the value <code>t[n]</code>, 4613where <code>t</code> is the table at the given index. 4614The access is raw, 4615that is, it does not invoke the <code>__index</code> metamethod. 4616 4617 4618<p> 4619Returns the type of the pushed value. 4620 4621 4622 4623 4624 4625<hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p> 4626<span class="apii">[-0, +1, –]</span> 4627<pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre> 4628 4629<p> 4630Pushes onto the stack the value <code>t[k]</code>, 4631where <code>t</code> is the table at the given index and 4632<code>k</code> is the pointer <code>p</code> represented as a light userdata. 4633The access is raw; 4634that is, it does not invoke the <code>__index</code> metamethod. 4635 4636 4637<p> 4638Returns the type of the pushed value. 4639 4640 4641 4642 4643 4644<hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p> 4645<span class="apii">[-0, +0, –]</span> 4646<pre>size_t lua_rawlen (lua_State *L, int index);</pre> 4647 4648<p> 4649Returns the raw "length" of the value at the given index: 4650for strings, this is the string length; 4651for tables, this is the result of the length operator ('<code>#</code>') 4652with no metamethods; 4653for userdata, this is the size of the block of memory allocated 4654for the userdata; 4655for other values, it is 0. 4656 4657 4658 4659 4660 4661<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> 4662<span class="apii">[-2, +0, <em>m</em>]</span> 4663<pre>void lua_rawset (lua_State *L, int index);</pre> 4664 4665<p> 4666Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment 4667(i.e., without metamethods). 4668 4669 4670 4671 4672 4673<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> 4674<span class="apii">[-1, +0, <em>m</em>]</span> 4675<pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre> 4676 4677<p> 4678Does the equivalent of <code>t[i] = v</code>, 4679where <code>t</code> is the table at the given index 4680and <code>v</code> is the value at the top of the stack. 4681 4682 4683<p> 4684This function pops the value from the stack. 4685The assignment is raw, 4686that is, it does not invoke the <code>__newindex</code> metamethod. 4687 4688 4689 4690 4691 4692<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p> 4693<span class="apii">[-1, +0, <em>m</em>]</span> 4694<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre> 4695 4696<p> 4697Does the equivalent of <code>t[p] = v</code>, 4698where <code>t</code> is the table at the given index, 4699<code>p</code> is encoded as a light userdata, 4700and <code>v</code> is the value at the top of the stack. 4701 4702 4703<p> 4704This function pops the value from the stack. 4705The assignment is raw, 4706that is, it does not invoke <code>__newindex</code> metamethod. 4707 4708 4709 4710 4711 4712<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> 4713<pre>typedef const char * (*lua_Reader) (lua_State *L, 4714 void *data, 4715 size_t *size);</pre> 4716 4717<p> 4718The reader function used by <a href="#lua_load"><code>lua_load</code></a>. 4719Every time it needs another piece of the chunk, 4720<a href="#lua_load"><code>lua_load</code></a> calls the reader, 4721passing along its <code>data</code> parameter. 4722The reader must return a pointer to a block of memory 4723with a new piece of the chunk 4724and set <code>size</code> to the block size. 4725The block must exist until the reader function is called again. 4726To signal the end of the chunk, 4727the reader must return <code>NULL</code> or set <code>size</code> to zero. 4728The reader function may return pieces of any size greater than zero. 4729 4730 4731 4732 4733 4734<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> 4735<span class="apii">[-0, +0, <em>e</em>]</span> 4736<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre> 4737 4738<p> 4739Sets the C function <code>f</code> as the new value of global <code>name</code>. 4740It is defined as a macro: 4741 4742<pre> 4743 #define lua_register(L,n,f) \ 4744 (lua_pushcfunction(L, f), lua_setglobal(L, n)) 4745</pre> 4746 4747 4748 4749 4750<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> 4751<span class="apii">[-1, +0, –]</span> 4752<pre>void lua_remove (lua_State *L, int index);</pre> 4753 4754<p> 4755Removes the element at the given valid index, 4756shifting down the elements above this index to fill the gap. 4757This function cannot be called with a pseudo-index, 4758because a pseudo-index is not an actual stack position. 4759 4760 4761 4762 4763 4764<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> 4765<span class="apii">[-1, +0, –]</span> 4766<pre>void lua_replace (lua_State *L, int index);</pre> 4767 4768<p> 4769Moves the top element into the given valid index 4770without shifting any element 4771(therefore replacing the value at that given index), 4772and then pops the top element. 4773 4774 4775 4776 4777 4778<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> 4779<span class="apii">[-?, +?, –]</span> 4780<pre>int lua_resume (lua_State *L, lua_State *from, int nargs);</pre> 4781 4782<p> 4783Starts and resumes a coroutine in the given thread <code>L</code>. 4784 4785 4786<p> 4787To start a coroutine, 4788you push onto the thread stack the main function plus any arguments; 4789then you call <a href="#lua_resume"><code>lua_resume</code></a>, 4790with <code>nargs</code> being the number of arguments. 4791This call returns when the coroutine suspends or finishes its execution. 4792When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>, 4793or all values returned by the body function. 4794<a href="#lua_resume"><code>lua_resume</code></a> returns 4795<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, 4796<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution 4797without errors, 4798or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). 4799 4800 4801<p> 4802In case of errors, 4803the stack is not unwound, 4804so you can use the debug API over it. 4805The error object is on the top of the stack. 4806 4807 4808<p> 4809To resume a coroutine, 4810you remove any results from the last <a href="#lua_yield"><code>lua_yield</code></a>, 4811put on its stack only the values to 4812be passed as results from <code>yield</code>, 4813and then call <a href="#lua_resume"><code>lua_resume</code></a>. 4814 4815 4816<p> 4817The parameter <code>from</code> represents the coroutine that is resuming <code>L</code>. 4818If there is no such coroutine, 4819this parameter can be <code>NULL</code>. 4820 4821 4822 4823 4824 4825<hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p> 4826<span class="apii">[-0, +0, –]</span> 4827<pre>void lua_rotate (lua_State *L, int idx, int n);</pre> 4828 4829<p> 4830Rotates the stack elements between the valid index <code>idx</code> 4831and the top of the stack. 4832The elements are rotated <code>n</code> positions in the direction of the top, 4833for a positive <code>n</code>, 4834or <code>-n</code> positions in the direction of the bottom, 4835for a negative <code>n</code>. 4836The absolute value of <code>n</code> must not be greater than the size 4837of the slice being rotated. 4838This function cannot be called with a pseudo-index, 4839because a pseudo-index is not an actual stack position. 4840 4841 4842 4843 4844 4845<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> 4846<span class="apii">[-0, +0, –]</span> 4847<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> 4848 4849<p> 4850Changes the allocator function of a given state to <code>f</code> 4851with user data <code>ud</code>. 4852 4853 4854 4855 4856 4857<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> 4858<span class="apii">[-1, +0, <em>e</em>]</span> 4859<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> 4860 4861<p> 4862Does the equivalent to <code>t[k] = v</code>, 4863where <code>t</code> is the value at the given index 4864and <code>v</code> is the value at the top of the stack. 4865 4866 4867<p> 4868This function pops the value from the stack. 4869As in Lua, this function may trigger a metamethod 4870for the "newindex" event (see <a href="#2.4">§2.4</a>). 4871 4872 4873 4874 4875 4876<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> 4877<span class="apii">[-1, +0, <em>e</em>]</span> 4878<pre>void lua_setglobal (lua_State *L, const char *name);</pre> 4879 4880<p> 4881Pops a value from the stack and 4882sets it as the new value of global <code>name</code>. 4883 4884 4885 4886 4887 4888<hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p> 4889<span class="apii">[-1, +0, <em>e</em>]</span> 4890<pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre> 4891 4892<p> 4893Does the equivalent to <code>t[n] = v</code>, 4894where <code>t</code> is the value at the given index 4895and <code>v</code> is the value at the top of the stack. 4896 4897 4898<p> 4899This function pops the value from the stack. 4900As in Lua, this function may trigger a metamethod 4901for the "newindex" event (see <a href="#2.4">§2.4</a>). 4902 4903 4904 4905 4906 4907<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> 4908<span class="apii">[-1, +0, –]</span> 4909<pre>void lua_setmetatable (lua_State *L, int index);</pre> 4910 4911<p> 4912Pops a table from the stack and 4913sets it as the new metatable for the value at the given index. 4914 4915 4916 4917 4918 4919<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> 4920<span class="apii">[-2, +0, <em>e</em>]</span> 4921<pre>void lua_settable (lua_State *L, int index);</pre> 4922 4923<p> 4924Does the equivalent to <code>t[k] = v</code>, 4925where <code>t</code> is the value at the given index, 4926<code>v</code> is the value at the top of the stack, 4927and <code>k</code> is the value just below the top. 4928 4929 4930<p> 4931This function pops both the key and the value from the stack. 4932As in Lua, this function may trigger a metamethod 4933for the "newindex" event (see <a href="#2.4">§2.4</a>). 4934 4935 4936 4937 4938 4939<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> 4940<span class="apii">[-?, +?, –]</span> 4941<pre>void lua_settop (lua_State *L, int index);</pre> 4942 4943<p> 4944Accepts any index, or 0, 4945and sets the stack top to this index. 4946If the new top is larger than the old one, 4947then the new elements are filled with <b>nil</b>. 4948If <code>index</code> is 0, then all stack elements are removed. 4949 4950 4951 4952 4953 4954<hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p> 4955<span class="apii">[-1, +0, –]</span> 4956<pre>void lua_setuservalue (lua_State *L, int index);</pre> 4957 4958<p> 4959Pops a value from the stack and sets it as 4960the new value associated to the full userdata at the given index. 4961 4962 4963 4964 4965 4966<hr><h3><a name="lua_State"><code>lua_State</code></a></h3> 4967<pre>typedef struct lua_State lua_State;</pre> 4968 4969<p> 4970An opaque structure that points to a thread and indirectly 4971(through the thread) to the whole state of a Lua interpreter. 4972The Lua library is fully reentrant: 4973it has no global variables. 4974All information about a state is accessible through this structure. 4975 4976 4977<p> 4978A pointer to this structure must be passed as the first argument to 4979every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 4980which creates a Lua state from scratch. 4981 4982 4983 4984 4985 4986<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> 4987<span class="apii">[-0, +0, –]</span> 4988<pre>int lua_status (lua_State *L);</pre> 4989 4990<p> 4991Returns the status of the thread <code>L</code>. 4992 4993 4994<p> 4995The status can be 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) for a normal thread, 4996an error code if the thread finished the execution 4997of a <a href="#lua_resume"><code>lua_resume</code></a> with an error, 4998or <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. 4999 5000 5001<p> 5002You can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>. 5003You can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> 5004(to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> 5005(to resume a coroutine). 5006 5007 5008 5009 5010 5011<hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p> 5012<span class="apii">[-0, +1, –]</span> 5013<pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre> 5014 5015<p> 5016Converts the zero-terminated string <code>s</code> to a number, 5017pushes that number into the stack, 5018and returns the total size of the string, 5019that is, its length plus one. 5020The conversion can result in an integer or a float, 5021according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 5022The string may have leading and trailing spaces and a sign. 5023If the string is not a valid numeral, 5024returns 0 and pushes nothing. 5025(Note that the result can be used as a boolean, 5026true if the conversion succeeds.) 5027 5028 5029 5030 5031 5032<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> 5033<span class="apii">[-0, +0, –]</span> 5034<pre>int lua_toboolean (lua_State *L, int index);</pre> 5035 5036<p> 5037Converts the Lua value at the given index to a C boolean 5038value (0 or 1). 5039Like all tests in Lua, 5040<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value 5041different from <b>false</b> and <b>nil</b>; 5042otherwise it returns false. 5043(If you want to accept only actual boolean values, 5044use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) 5045 5046 5047 5048 5049 5050<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> 5051<span class="apii">[-0, +0, –]</span> 5052<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> 5053 5054<p> 5055Converts a value at the given index to a C function. 5056That value must be a C function; 5057otherwise, returns <code>NULL</code>. 5058 5059 5060 5061 5062 5063<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> 5064<span class="apii">[-0, +0, –]</span> 5065<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> 5066 5067<p> 5068Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5069 5070 5071 5072 5073 5074<hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p> 5075<span class="apii">[-0, +0, –]</span> 5076<pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre> 5077 5078<p> 5079Converts the Lua value at the given index 5080to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. 5081The Lua value must be an integer, 5082or a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>); 5083otherwise, <code>lua_tointegerx</code> returns 0. 5084 5085 5086<p> 5087If <code>isnum</code> is not <code>NULL</code>, 5088its referent is assigned a boolean value that 5089indicates whether the operation succeeded. 5090 5091 5092 5093 5094 5095<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> 5096<span class="apii">[-0, +0, <em>m</em>]</span> 5097<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> 5098 5099<p> 5100Converts the Lua value at the given index to a C string. 5101If <code>len</code> is not <code>NULL</code>, 5102it sets <code>*len</code> with the string length. 5103The Lua value must be a string or a number; 5104otherwise, the function returns <code>NULL</code>. 5105If the value is a number, 5106then <code>lua_tolstring</code> also 5107<em>changes the actual value in the stack to a string</em>. 5108(This change confuses <a href="#lua_next"><code>lua_next</code></a> 5109when <code>lua_tolstring</code> is applied to keys during a table traversal.) 5110 5111 5112<p> 5113<code>lua_tolstring</code> returns a pointer 5114to a string inside the Lua state. 5115This string always has a zero ('<code>\0</code>') 5116after its last character (as in C), 5117but can contain other zeros in its body. 5118 5119 5120<p> 5121Because Lua has garbage collection, 5122there is no guarantee that the pointer returned by <code>lua_tolstring</code> 5123will be valid after the corresponding Lua value is removed from the stack. 5124 5125 5126 5127 5128 5129<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> 5130<span class="apii">[-0, +0, –]</span> 5131<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> 5132 5133<p> 5134Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5135 5136 5137 5138 5139 5140<hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p> 5141<span class="apii">[-0, +0, –]</span> 5142<pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre> 5143 5144<p> 5145Converts the Lua value at the given index 5146to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). 5147The Lua value must be a number or a string convertible to a number 5148(see <a href="#3.4.3">§3.4.3</a>); 5149otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0. 5150 5151 5152<p> 5153If <code>isnum</code> is not <code>NULL</code>, 5154its referent is assigned a boolean value that 5155indicates whether the operation succeeded. 5156 5157 5158 5159 5160 5161<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> 5162<span class="apii">[-0, +0, –]</span> 5163<pre>const void *lua_topointer (lua_State *L, int index);</pre> 5164 5165<p> 5166Converts the value at the given index to a generic 5167C pointer (<code>void*</code>). 5168The value can be a userdata, a table, a thread, or a function; 5169otherwise, <code>lua_topointer</code> returns <code>NULL</code>. 5170Different objects will give different pointers. 5171There is no way to convert the pointer back to its original value. 5172 5173 5174<p> 5175Typically this function is used only for hashing and debug information. 5176 5177 5178 5179 5180 5181<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> 5182<span class="apii">[-0, +0, <em>m</em>]</span> 5183<pre>const char *lua_tostring (lua_State *L, int index);</pre> 5184 5185<p> 5186Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. 5187 5188 5189 5190 5191 5192<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> 5193<span class="apii">[-0, +0, –]</span> 5194<pre>lua_State *lua_tothread (lua_State *L, int index);</pre> 5195 5196<p> 5197Converts the value at the given index to a Lua thread 5198(represented as <code>lua_State*</code>). 5199This value must be a thread; 5200otherwise, the function returns <code>NULL</code>. 5201 5202 5203 5204 5205 5206<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> 5207<span class="apii">[-0, +0, –]</span> 5208<pre>void *lua_touserdata (lua_State *L, int index);</pre> 5209 5210<p> 5211If the value at the given index is a full userdata, 5212returns its block address. 5213If the value is a light userdata, 5214returns its pointer. 5215Otherwise, returns <code>NULL</code>. 5216 5217 5218 5219 5220 5221<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> 5222<span class="apii">[-0, +0, –]</span> 5223<pre>int lua_type (lua_State *L, int index);</pre> 5224 5225<p> 5226Returns the type of the value in the given valid index, 5227or <code>LUA_TNONE</code> for a non-valid (but acceptable) index. 5228The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants 5229defined in <code>lua.h</code>: 5230<a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a> (0), 5231<a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>, 5232<a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>, 5233<a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, 5234<a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, 5235<a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, 5236<a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, 5237<a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>, 5238and 5239<a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>. 5240 5241 5242 5243 5244 5245<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> 5246<span class="apii">[-0, +0, –]</span> 5247<pre>const char *lua_typename (lua_State *L, int tp);</pre> 5248 5249<p> 5250Returns the name of the type encoded by the value <code>tp</code>, 5251which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. 5252 5253 5254 5255 5256 5257<hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3> 5258<pre>typedef ... lua_Unsigned;</pre> 5259 5260<p> 5261The unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>. 5262 5263 5264 5265 5266 5267<hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p> 5268<span class="apii">[-0, +0, –]</span> 5269<pre>int lua_upvalueindex (int i);</pre> 5270 5271<p> 5272Returns the pseudo-index that represents the <code>i</code>-th upvalue of 5273the running function (see <a href="#4.4">§4.4</a>). 5274 5275 5276 5277 5278 5279<hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p> 5280<span class="apii">[-0, +0, –]</span> 5281<pre>const lua_Number *lua_version (lua_State *L);</pre> 5282 5283<p> 5284Returns the address of the version number 5285(a C static variable) 5286stored in the Lua core. 5287When called with a valid <a href="#lua_State"><code>lua_State</code></a>, 5288returns the address of the version used to create that state. 5289When called with <code>NULL</code>, 5290returns the address of the version running the call. 5291 5292 5293 5294 5295 5296<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> 5297<pre>typedef int (*lua_Writer) (lua_State *L, 5298 const void* p, 5299 size_t sz, 5300 void* ud);</pre> 5301 5302<p> 5303The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. 5304Every time it produces another piece of chunk, 5305<a href="#lua_dump"><code>lua_dump</code></a> calls the writer, 5306passing along the buffer to be written (<code>p</code>), 5307its size (<code>sz</code>), 5308and the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. 5309 5310 5311<p> 5312The writer returns an error code: 53130 means no errors; 5314any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from 5315calling the writer again. 5316 5317 5318 5319 5320 5321<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> 5322<span class="apii">[-?, +?, –]</span> 5323<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> 5324 5325<p> 5326Exchange values between different threads of the same state. 5327 5328 5329<p> 5330This function pops <code>n</code> values from the stack <code>from</code>, 5331and pushes them onto the stack <code>to</code>. 5332 5333 5334 5335 5336 5337<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> 5338<span class="apii">[-?, +?, <em>e</em>]</span> 5339<pre>int lua_yield (lua_State *L, int nresults);</pre> 5340 5341<p> 5342This function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5343but it has no continuation (see <a href="#4.7">§4.7</a>). 5344Therefore, when the thread resumes, 5345it continues the function that called 5346the function calling <code>lua_yield</code>. 5347 5348 5349 5350 5351 5352<hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p> 5353<span class="apii">[-?, +?, <em>e</em>]</span> 5354<pre>int lua_yieldk (lua_State *L, 5355 int nresults, 5356 lua_KContext ctx, 5357 lua_KFunction k);</pre> 5358 5359<p> 5360Yields a coroutine (thread). 5361 5362 5363<p> 5364When a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5365the running coroutine suspends its execution, 5366and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. 5367The parameter <code>nresults</code> is the number of values from the stack 5368that will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. 5369 5370 5371<p> 5372When the coroutine is resumed again, 5373Lua calls the given continuation function <code>k</code> to continue 5374the execution of the C function that yielded (see <a href="#4.7">§4.7</a>). 5375This continuation function receives the same stack 5376from the previous function, 5377with the <code>n</code> results removed and 5378replaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>. 5379Moreover, 5380the continuation function receives the value <code>ctx</code> 5381that was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>. 5382 5383 5384<p> 5385Usually, this function does not return; 5386when the coroutine eventually resumes, 5387it continues executing the continuation function. 5388However, there is one special case, 5389which is when this function is called 5390from inside a line or a count hook (see <a href="#4.9">§4.9</a>). 5391In that case, <code>lua_yieldk</code> should be called with no continuation 5392(probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results, 5393and the hook should return immediately after the call. 5394Lua will yield and, 5395when the coroutine resumes again, 5396it will continue the normal execution 5397of the (Lua) function that triggered the hook. 5398 5399 5400<p> 5401This function can raise an error if it is called from a thread 5402with a pending C call with no continuation function, 5403or it is called from a thread that is not running inside a resume 5404(e.g., the main thread). 5405 5406 5407 5408 5409 5410 5411 5412<h2>4.9 – <a name="4.9">The Debug Interface</a></h2> 5413 5414<p> 5415Lua has no built-in debugging facilities. 5416Instead, it offers a special interface 5417by means of functions and <em>hooks</em>. 5418This interface allows the construction of different 5419kinds of debuggers, profilers, and other tools 5420that need "inside information" from the interpreter. 5421 5422 5423 5424<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> 5425<pre>typedef struct lua_Debug { 5426 int event; 5427 const char *name; /* (n) */ 5428 const char *namewhat; /* (n) */ 5429 const char *what; /* (S) */ 5430 const char *source; /* (S) */ 5431 int currentline; /* (l) */ 5432 int linedefined; /* (S) */ 5433 int lastlinedefined; /* (S) */ 5434 unsigned char nups; /* (u) number of upvalues */ 5435 unsigned char nparams; /* (u) number of parameters */ 5436 char isvararg; /* (u) */ 5437 char istailcall; /* (t) */ 5438 char short_src[LUA_IDSIZE]; /* (S) */ 5439 /* private part */ 5440 <em>other fields</em> 5441} lua_Debug;</pre> 5442 5443<p> 5444A structure used to carry different pieces of 5445information about a function or an activation record. 5446<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part 5447of this structure, for later use. 5448To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, 5449call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 5450 5451 5452<p> 5453The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: 5454 5455<ul> 5456 5457<li><b><code>source</code>: </b> 5458the name of the chunk that created the function. 5459If <code>source</code> starts with a '<code>@</code>', 5460it means that the function was defined in a file where 5461the file name follows the '<code>@</code>'. 5462If <code>source</code> starts with a '<code>=</code>', 5463the remainder of its contents describe the source in a user-dependent manner. 5464Otherwise, 5465the function was defined in a string where 5466<code>source</code> is that string. 5467</li> 5468 5469<li><b><code>short_src</code>: </b> 5470a "printable" version of <code>source</code>, to be used in error messages. 5471</li> 5472 5473<li><b><code>linedefined</code>: </b> 5474the line number where the definition of the function starts. 5475</li> 5476 5477<li><b><code>lastlinedefined</code>: </b> 5478the line number where the definition of the function ends. 5479</li> 5480 5481<li><b><code>what</code>: </b> 5482the string <code>"Lua"</code> if the function is a Lua function, 5483<code>"C"</code> if it is a C function, 5484<code>"main"</code> if it is the main part of a chunk. 5485</li> 5486 5487<li><b><code>currentline</code>: </b> 5488the current line where the given function is executing. 5489When no line information is available, 5490<code>currentline</code> is set to -1. 5491</li> 5492 5493<li><b><code>name</code>: </b> 5494a reasonable name for the given function. 5495Because functions in Lua are first-class values, 5496they do not have a fixed name: 5497some functions can be the value of multiple global variables, 5498while others can be stored only in a table field. 5499The <code>lua_getinfo</code> function checks how the function was 5500called to find a suitable name. 5501If it cannot find a name, 5502then <code>name</code> is set to <code>NULL</code>. 5503</li> 5504 5505<li><b><code>namewhat</code>: </b> 5506explains the <code>name</code> field. 5507The value of <code>namewhat</code> can be 5508<code>"global"</code>, <code>"local"</code>, <code>"method"</code>, 5509<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), 5510according to how the function was called. 5511(Lua uses the empty string when no other option seems to apply.) 5512</li> 5513 5514<li><b><code>istailcall</code>: </b> 5515true if this function invocation was called by a tail call. 5516In this case, the caller of this level is not in the stack. 5517</li> 5518 5519<li><b><code>nups</code>: </b> 5520the number of upvalues of the function. 5521</li> 5522 5523<li><b><code>nparams</code>: </b> 5524the number of fixed parameters of the function 5525(always 0 for C functions). 5526</li> 5527 5528<li><b><code>isvararg</code>: </b> 5529true if the function is a vararg function 5530(always true for C functions). 5531</li> 5532 5533</ul> 5534 5535 5536 5537 5538<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> 5539<span class="apii">[-0, +0, –]</span> 5540<pre>lua_Hook lua_gethook (lua_State *L);</pre> 5541 5542<p> 5543Returns the current hook function. 5544 5545 5546 5547 5548 5549<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> 5550<span class="apii">[-0, +0, –]</span> 5551<pre>int lua_gethookcount (lua_State *L);</pre> 5552 5553<p> 5554Returns the current hook count. 5555 5556 5557 5558 5559 5560<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> 5561<span class="apii">[-0, +0, –]</span> 5562<pre>int lua_gethookmask (lua_State *L);</pre> 5563 5564<p> 5565Returns the current hook mask. 5566 5567 5568 5569 5570 5571<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> 5572<span class="apii">[-(0|1), +(0|1|2), <em>e</em>]</span> 5573<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> 5574 5575<p> 5576Gets information about a specific function or function invocation. 5577 5578 5579<p> 5580To get information about a function invocation, 5581the parameter <code>ar</code> must be a valid activation record that was 5582filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 5583given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 5584 5585 5586<p> 5587To get information about a function you push it onto the stack 5588and start the <code>what</code> string with the character '<code>></code>'. 5589(In that case, 5590<code>lua_getinfo</code> pops the function from the top of the stack.) 5591For instance, to know in which line a function <code>f</code> was defined, 5592you can write the following code: 5593 5594<pre> 5595 lua_Debug ar; 5596 lua_getglobal(L, "f"); /* get global 'f' */ 5597 lua_getinfo(L, ">S", &ar); 5598 printf("%d\n", ar.linedefined); 5599</pre> 5600 5601<p> 5602Each character in the string <code>what</code> 5603selects some fields of the structure <code>ar</code> to be filled or 5604a value to be pushed on the stack: 5605 5606<ul> 5607 5608<li><b>'<code>n</code>': </b> fills in the field <code>name</code> and <code>namewhat</code>; 5609</li> 5610 5611<li><b>'<code>S</code>': </b> 5612fills in the fields <code>source</code>, <code>short_src</code>, 5613<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; 5614</li> 5615 5616<li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>; 5617</li> 5618 5619<li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>; 5620</li> 5621 5622<li><b>'<code>u</code>': </b> fills in the fields 5623<code>nups</code>, <code>nparams</code>, and <code>isvararg</code>; 5624</li> 5625 5626<li><b>'<code>f</code>': </b> 5627pushes onto the stack the function that is 5628running at the given level; 5629</li> 5630 5631<li><b>'<code>L</code>': </b> 5632pushes onto the stack a table whose indices are the 5633numbers of the lines that are valid on the function. 5634(A <em>valid line</em> is a line with some associated code, 5635that is, a line where you can put a break point. 5636Non-valid lines include empty lines and comments.) 5637 5638 5639<p> 5640If this option is given together with option '<code>f</code>', 5641its table is pushed after the function. 5642</li> 5643 5644</ul> 5645 5646<p> 5647This function returns 0 on error 5648(for instance, an invalid option in <code>what</code>). 5649 5650 5651 5652 5653 5654<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> 5655<span class="apii">[-0, +(0|1), –]</span> 5656<pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 5657 5658<p> 5659Gets information about a local variable of 5660a given activation record or a given function. 5661 5662 5663<p> 5664In the first case, 5665the parameter <code>ar</code> must be a valid activation record that was 5666filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 5667given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 5668The index <code>n</code> selects which local variable to inspect; 5669see <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices 5670and names. 5671 5672 5673<p> 5674<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack 5675and returns its name. 5676 5677 5678<p> 5679In the second case, <code>ar</code> must be <code>NULL</code> and the function 5680to be inspected must be at the top of the stack. 5681In this case, only parameters of Lua functions are visible 5682(as there is no information about what variables are active) 5683and no values are pushed onto the stack. 5684 5685 5686<p> 5687Returns <code>NULL</code> (and pushes nothing) 5688when the index is greater than 5689the number of active local variables. 5690 5691 5692 5693 5694 5695<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> 5696<span class="apii">[-0, +0, –]</span> 5697<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> 5698 5699<p> 5700Gets information about the interpreter runtime stack. 5701 5702 5703<p> 5704This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with 5705an identification of the <em>activation record</em> 5706of the function executing at a given level. 5707Level 0 is the current running function, 5708whereas level <em>n+1</em> is the function that has called level <em>n</em> 5709(except for tail calls, which do not count on the stack). 5710When there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1; 5711when called with a level greater than the stack depth, 5712it returns 0. 5713 5714 5715 5716 5717 5718<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> 5719<span class="apii">[-0, +(0|1), –]</span> 5720<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> 5721 5722<p> 5723Gets information about the <code>n</code>-th upvalue 5724of the closure at index <code>funcindex</code>. 5725It pushes the upvalue's value onto the stack 5726and returns its name. 5727Returns <code>NULL</code> (and pushes nothing) 5728when the index <code>n</code> is greater than the number of upvalues. 5729 5730 5731<p> 5732For C functions, this function uses the empty string <code>""</code> 5733as a name for all upvalues. 5734(For Lua functions, 5735upvalues are the external local variables that the function uses, 5736and that are consequently included in its closure.) 5737 5738 5739<p> 5740Upvalues have no particular order, 5741as they are active through the whole function. 5742They are numbered in an arbitrary order. 5743 5744 5745 5746 5747 5748<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> 5749<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> 5750 5751<p> 5752Type for debugging hook functions. 5753 5754 5755<p> 5756Whenever a hook is called, its <code>ar</code> argument has its field 5757<code>event</code> set to the specific event that triggered the hook. 5758Lua identifies these events with the following constants: 5759<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, 5760<a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, 5761and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. 5762Moreover, for line events, the field <code>currentline</code> is also set. 5763To get the value of any other field in <code>ar</code>, 5764the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 5765 5766 5767<p> 5768For call events, <code>event</code> can be <code>LUA_HOOKCALL</code>, 5769the normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call; 5770in this case, there will be no corresponding return event. 5771 5772 5773<p> 5774While Lua is running a hook, it disables other calls to hooks. 5775Therefore, if a hook calls back Lua to execute a function or a chunk, 5776this execution occurs without any calls to hooks. 5777 5778 5779<p> 5780Hook functions cannot have continuations, 5781that is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5782<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>. 5783 5784 5785<p> 5786Hook functions can yield under the following conditions: 5787Only count and line events can yield; 5788to yield, a hook function must finish its execution 5789calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero 5790(that is, with no values). 5791 5792 5793 5794 5795 5796<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> 5797<span class="apii">[-0, +0, –]</span> 5798<pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> 5799 5800<p> 5801Sets the debugging hook function. 5802 5803 5804<p> 5805Argument <code>f</code> is the hook function. 5806<code>mask</code> specifies on which events the hook will be called: 5807it is formed by a bitwise OR of the constants 5808<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, 5809<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, 5810<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, 5811and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. 5812The <code>count</code> argument is only meaningful when the mask 5813includes <code>LUA_MASKCOUNT</code>. 5814For each event, the hook is called as explained below: 5815 5816<ul> 5817 5818<li><b>The call hook: </b> is called when the interpreter calls a function. 5819The hook is called just after Lua enters the new function, 5820before the function gets its arguments. 5821</li> 5822 5823<li><b>The return hook: </b> is called when the interpreter returns from a function. 5824The hook is called just before Lua leaves the function. 5825There is no standard way to access the values 5826to be returned by the function. 5827</li> 5828 5829<li><b>The line hook: </b> is called when the interpreter is about to 5830start the execution of a new line of code, 5831or when it jumps back in the code (even to the same line). 5832(This event only happens while Lua is executing a Lua function.) 5833</li> 5834 5835<li><b>The count hook: </b> is called after the interpreter executes every 5836<code>count</code> instructions. 5837(This event only happens while Lua is executing a Lua function.) 5838</li> 5839 5840</ul> 5841 5842<p> 5843A hook is disabled by setting <code>mask</code> to zero. 5844 5845 5846 5847 5848 5849<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> 5850<span class="apii">[-(0|1), +0, –]</span> 5851<pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 5852 5853<p> 5854Sets the value of a local variable of a given activation record. 5855It assigns the value at the top of the stack 5856to the variable and returns its name. 5857It also pops the value from the stack. 5858 5859 5860<p> 5861Returns <code>NULL</code> (and pops nothing) 5862when the index is greater than 5863the number of active local variables. 5864 5865 5866<p> 5867Parameters <code>ar</code> and <code>n</code> are as in function <a href="#lua_getlocal"><code>lua_getlocal</code></a>. 5868 5869 5870 5871 5872 5873<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> 5874<span class="apii">[-(0|1), +0, –]</span> 5875<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> 5876 5877<p> 5878Sets the value of a closure's upvalue. 5879It assigns the value at the top of the stack 5880to the upvalue and returns its name. 5881It also pops the value from the stack. 5882 5883 5884<p> 5885Returns <code>NULL</code> (and pops nothing) 5886when the index <code>n</code> is greater than the number of upvalues. 5887 5888 5889<p> 5890Parameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>. 5891 5892 5893 5894 5895 5896<hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p> 5897<span class="apii">[-0, +0, –]</span> 5898<pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre> 5899 5900<p> 5901Returns a unique identifier for the upvalue numbered <code>n</code> 5902from the closure at index <code>funcindex</code>. 5903 5904 5905<p> 5906These unique identifiers allow a program to check whether different 5907closures share upvalues. 5908Lua closures that share an upvalue 5909(that is, that access a same external local variable) 5910will return identical ids for those upvalue indices. 5911 5912 5913<p> 5914Parameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, 5915but <code>n</code> cannot be greater than the number of upvalues. 5916 5917 5918 5919 5920 5921<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p> 5922<span class="apii">[-0, +0, –]</span> 5923<pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1, 5924 int funcindex2, int n2);</pre> 5925 5926<p> 5927Make the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code> 5928refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>. 5929 5930 5931 5932 5933 5934 5935 5936<h1>5 – <a name="5">The Auxiliary Library</a></h1> 5937 5938<p> 5939 5940The <em>auxiliary library</em> provides several convenient functions 5941to interface C with Lua. 5942While the basic API provides the primitive functions for all 5943interactions between C and Lua, 5944the auxiliary library provides higher-level functions for some 5945common tasks. 5946 5947 5948<p> 5949All functions and types from the auxiliary library 5950are defined in header file <code>lauxlib.h</code> and 5951have a prefix <code>luaL_</code>. 5952 5953 5954<p> 5955All functions in the auxiliary library are built on 5956top of the basic API, 5957and so they provide nothing that cannot be done with that API. 5958Nevertheless, the use of the auxiliary library ensures 5959more consistency to your code. 5960 5961 5962<p> 5963Several functions in the auxiliary library use internally some 5964extra stack slots. 5965When a function in the auxiliary library uses less than five slots, 5966it does not check the stack size; 5967it simply assumes that there are enough slots. 5968 5969 5970<p> 5971Several functions in the auxiliary library are used to 5972check C function arguments. 5973Because the error message is formatted for arguments 5974(e.g., "<code>bad argument #1</code>"), 5975you should not use these functions for other stack values. 5976 5977 5978<p> 5979Functions called <code>luaL_check*</code> 5980always raise an error if the check is not satisfied. 5981 5982 5983 5984<h2>5.1 – <a name="5.1">Functions and Types</a></h2> 5985 5986<p> 5987Here we list all functions and types from the auxiliary library 5988in alphabetical order. 5989 5990 5991 5992<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> 5993<span class="apii">[-?, +?, <em>m</em>]</span> 5994<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> 5995 5996<p> 5997Adds the byte <code>c</code> to the buffer <code>B</code> 5998(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5999 6000 6001 6002 6003 6004<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> 6005<span class="apii">[-?, +?, <em>m</em>]</span> 6006<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> 6007 6008<p> 6009Adds the string pointed to by <code>s</code> with length <code>l</code> to 6010the buffer <code>B</code> 6011(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6012The string can contain embedded zeros. 6013 6014 6015 6016 6017 6018<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> 6019<span class="apii">[-?, +?, –]</span> 6020<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> 6021 6022<p> 6023Adds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>) 6024a string of length <code>n</code> previously copied to the 6025buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). 6026 6027 6028 6029 6030 6031<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> 6032<span class="apii">[-?, +?, <em>m</em>]</span> 6033<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> 6034 6035<p> 6036Adds the zero-terminated string pointed to by <code>s</code> 6037to the buffer <code>B</code> 6038(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6039 6040 6041 6042 6043 6044<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> 6045<span class="apii">[-1, +?, <em>m</em>]</span> 6046<pre>void luaL_addvalue (luaL_Buffer *B);</pre> 6047 6048<p> 6049Adds the value at the top of the stack 6050to the buffer <code>B</code> 6051(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6052Pops the value. 6053 6054 6055<p> 6056This is the only function on string buffers that can (and must) 6057be called with an extra element on the stack, 6058which is the value to be added to the buffer. 6059 6060 6061 6062 6063 6064<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> 6065<span class="apii">[-0, +0, <em>v</em>]</span> 6066<pre>void luaL_argcheck (lua_State *L, 6067 int cond, 6068 int arg, 6069 const char *extramsg);</pre> 6070 6071<p> 6072Checks whether <code>cond</code> is true. 6073If it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>). 6074 6075 6076 6077 6078 6079<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> 6080<span class="apii">[-0, +0, <em>v</em>]</span> 6081<pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre> 6082 6083<p> 6084Raises an error reporting a problem with argument <code>arg</code> 6085of the C function that called it, 6086using a standard message 6087that includes <code>extramsg</code> as a comment: 6088 6089<pre> 6090 bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>) 6091</pre><p> 6092This function never returns. 6093 6094 6095 6096 6097 6098<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> 6099<pre>typedef struct luaL_Buffer luaL_Buffer;</pre> 6100 6101<p> 6102Type for a <em>string buffer</em>. 6103 6104 6105<p> 6106A string buffer allows C code to build Lua strings piecemeal. 6107Its pattern of use is as follows: 6108 6109<ul> 6110 6111<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6112 6113<li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> 6114 6115<li> 6116Then add string pieces to the buffer calling any of 6117the <code>luaL_add*</code> functions. 6118</li> 6119 6120<li> 6121Finish by calling <code>luaL_pushresult(&b)</code>. 6122This call leaves the final string on the top of the stack. 6123</li> 6124 6125</ul> 6126 6127<p> 6128If you know beforehand the total size of the resulting string, 6129you can use the buffer like this: 6130 6131<ul> 6132 6133<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6134 6135<li>Then initialize it and preallocate a space of 6136size <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li> 6137 6138<li>Then copy the string into that space.</li> 6139 6140<li> 6141Finish by calling <code>luaL_pushresultsize(&b, sz)</code>, 6142where <code>sz</code> is the total size of the resulting string 6143copied into that space. 6144</li> 6145 6146</ul> 6147 6148<p> 6149During its normal operation, 6150a string buffer uses a variable number of stack slots. 6151So, while using a buffer, you cannot assume that you know where 6152the top of the stack is. 6153You can use the stack between successive calls to buffer operations 6154as long as that use is balanced; 6155that is, 6156when you call a buffer operation, 6157the stack is at the same level 6158it was immediately after the previous buffer operation. 6159(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) 6160After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its 6161level when the buffer was initialized, 6162plus the final string on its top. 6163 6164 6165 6166 6167 6168<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> 6169<span class="apii">[-0, +0, –]</span> 6170<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> 6171 6172<p> 6173Initializes a buffer <code>B</code>. 6174This function does not allocate any space; 6175the buffer must be declared as a variable 6176(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6177 6178 6179 6180 6181 6182<hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p> 6183<span class="apii">[-?, +?, <em>m</em>]</span> 6184<pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre> 6185 6186<p> 6187Equivalent to the sequence 6188<a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>. 6189 6190 6191 6192 6193 6194<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> 6195<span class="apii">[-0, +(0|1), <em>e</em>]</span> 6196<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> 6197 6198<p> 6199Calls a metamethod. 6200 6201 6202<p> 6203If the object at index <code>obj</code> has a metatable and this 6204metatable has a field <code>e</code>, 6205this function calls this field passing the object as its only argument. 6206In this case this function returns true and pushes onto the 6207stack the value returned by the call. 6208If there is no metatable or no metamethod, 6209this function returns false (without pushing any value on the stack). 6210 6211 6212 6213 6214 6215<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> 6216<span class="apii">[-0, +0, <em>v</em>]</span> 6217<pre>void luaL_checkany (lua_State *L, int arg);</pre> 6218 6219<p> 6220Checks whether the function has an argument 6221of any type (including <b>nil</b>) at position <code>arg</code>. 6222 6223 6224 6225 6226 6227<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> 6228<span class="apii">[-0, +0, <em>v</em>]</span> 6229<pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre> 6230 6231<p> 6232Checks whether the function argument <code>arg</code> is an integer 6233(or can be converted to an integer) 6234and returns this integer cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. 6235 6236 6237 6238 6239 6240<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> 6241<span class="apii">[-0, +0, <em>v</em>]</span> 6242<pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre> 6243 6244<p> 6245Checks whether the function argument <code>arg</code> is a string 6246and returns this string; 6247if <code>l</code> is not <code>NULL</code> fills <code>*l</code> 6248with the string's length. 6249 6250 6251<p> 6252This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6253so all conversions and caveats of that function apply here. 6254 6255 6256 6257 6258 6259<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> 6260<span class="apii">[-0, +0, <em>v</em>]</span> 6261<pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre> 6262 6263<p> 6264Checks whether the function argument <code>arg</code> is a number 6265and returns this number. 6266 6267 6268 6269 6270 6271<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> 6272<span class="apii">[-0, +0, <em>v</em>]</span> 6273<pre>int luaL_checkoption (lua_State *L, 6274 int arg, 6275 const char *def, 6276 const char *const lst[]);</pre> 6277 6278<p> 6279Checks whether the function argument <code>arg</code> is a string and 6280searches for this string in the array <code>lst</code> 6281(which must be NULL-terminated). 6282Returns the index in the array where the string was found. 6283Raises an error if the argument is not a string or 6284if the string cannot be found. 6285 6286 6287<p> 6288If <code>def</code> is not <code>NULL</code>, 6289the function uses <code>def</code> as a default value when 6290there is no argument <code>arg</code> or when this argument is <b>nil</b>. 6291 6292 6293<p> 6294This is a useful function for mapping strings to C enums. 6295(The usual convention in Lua libraries is 6296to use strings instead of numbers to select options.) 6297 6298 6299 6300 6301 6302<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> 6303<span class="apii">[-0, +0, <em>v</em>]</span> 6304<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> 6305 6306<p> 6307Grows the stack size to <code>top + sz</code> elements, 6308raising an error if the stack cannot grow to that size. 6309<code>msg</code> is an additional text to go into the error message 6310(or <code>NULL</code> for no additional text). 6311 6312 6313 6314 6315 6316<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> 6317<span class="apii">[-0, +0, <em>v</em>]</span> 6318<pre>const char *luaL_checkstring (lua_State *L, int arg);</pre> 6319 6320<p> 6321Checks whether the function argument <code>arg</code> is a string 6322and returns this string. 6323 6324 6325<p> 6326This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6327so all conversions and caveats of that function apply here. 6328 6329 6330 6331 6332 6333<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> 6334<span class="apii">[-0, +0, <em>v</em>]</span> 6335<pre>void luaL_checktype (lua_State *L, int arg, int t);</pre> 6336 6337<p> 6338Checks whether the function argument <code>arg</code> has type <code>t</code>. 6339See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. 6340 6341 6342 6343 6344 6345<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> 6346<span class="apii">[-0, +0, <em>v</em>]</span> 6347<pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre> 6348 6349<p> 6350Checks whether the function argument <code>arg</code> is a userdata 6351of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and 6352returns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>). 6353 6354 6355 6356 6357 6358<hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p> 6359<span class="apii">[-0, +0, <em>v</em>]</span> 6360<pre>void luaL_checkversion (lua_State *L);</pre> 6361 6362<p> 6363Checks whether the core running the call, 6364the core that created the Lua state, 6365and the code making the call are all using the same version of Lua. 6366Also checks whether the core running the call 6367and the core that created the Lua state 6368are using the same address space. 6369 6370 6371 6372 6373 6374<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> 6375<span class="apii">[-0, +?, <em>e</em>]</span> 6376<pre>int luaL_dofile (lua_State *L, const char *filename);</pre> 6377 6378<p> 6379Loads and runs the given file. 6380It is defined as the following macro: 6381 6382<pre> 6383 (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6384</pre><p> 6385It returns false if there are no errors 6386or true in case of errors. 6387 6388 6389 6390 6391 6392<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> 6393<span class="apii">[-0, +?, –]</span> 6394<pre>int luaL_dostring (lua_State *L, const char *str);</pre> 6395 6396<p> 6397Loads and runs the given string. 6398It is defined as the following macro: 6399 6400<pre> 6401 (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6402</pre><p> 6403It returns false if there are no errors 6404or true in case of errors. 6405 6406 6407 6408 6409 6410<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> 6411<span class="apii">[-0, +0, <em>v</em>]</span> 6412<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> 6413 6414<p> 6415Raises an error. 6416The error message format is given by <code>fmt</code> 6417plus any extra arguments, 6418following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. 6419It also adds at the beginning of the message the file name and 6420the line number where the error occurred, 6421if this information is available. 6422 6423 6424<p> 6425This function never returns, 6426but it is an idiom to use it in C functions 6427as <code>return luaL_error(<em>args</em>)</code>. 6428 6429 6430 6431 6432 6433<hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p> 6434<span class="apii">[-0, +3, <em>m</em>]</span> 6435<pre>int luaL_execresult (lua_State *L, int stat);</pre> 6436 6437<p> 6438This function produces the return values for 6439process-related functions in the standard library 6440(<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>). 6441 6442 6443 6444 6445 6446<hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p> 6447<span class="apii">[-0, +(1|3), <em>m</em>]</span> 6448<pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre> 6449 6450<p> 6451This function produces the return values for 6452file-related functions in the standard library 6453(<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.). 6454 6455 6456 6457 6458 6459<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> 6460<span class="apii">[-0, +(0|1), <em>m</em>]</span> 6461<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> 6462 6463<p> 6464Pushes onto the stack the field <code>e</code> from the metatable 6465of the object at index <code>obj</code> and returns the type of pushed value. 6466If the object does not have a metatable, 6467or if the metatable does not have this field, 6468pushes nothing and returns <code>LUA_TNIL</code>. 6469 6470 6471 6472 6473 6474<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> 6475<span class="apii">[-0, +1, <em>m</em>]</span> 6476<pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre> 6477 6478<p> 6479Pushes onto the stack the metatable associated with name <code>tname</code> 6480in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) 6481(<b>nil</b> if there is no metatable associated with that name). 6482Returns the type of the pushed value. 6483 6484 6485 6486 6487 6488<hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p> 6489<span class="apii">[-0, +1, <em>e</em>]</span> 6490<pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre> 6491 6492<p> 6493Ensures that the value <code>t[fname]</code>, 6494where <code>t</code> is the value at index <code>idx</code>, 6495is a table, 6496and pushes that table onto the stack. 6497Returns true if it finds a previous table there 6498and false if it creates a new table. 6499 6500 6501 6502 6503 6504<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> 6505<span class="apii">[-0, +1, <em>m</em>]</span> 6506<pre>const char *luaL_gsub (lua_State *L, 6507 const char *s, 6508 const char *p, 6509 const char *r);</pre> 6510 6511<p> 6512Creates a copy of string <code>s</code> by replacing 6513any occurrence of the string <code>p</code> 6514with the string <code>r</code>. 6515Pushes the resulting string on the stack and returns it. 6516 6517 6518 6519 6520 6521<hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p> 6522<span class="apii">[-0, +0, <em>e</em>]</span> 6523<pre>lua_Integer luaL_len (lua_State *L, int index);</pre> 6524 6525<p> 6526Returns the "length" of the value at the given index 6527as a number; 6528it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). 6529Raises an error if the result of the operation is not an integer. 6530(This case only can happen through metamethods.) 6531 6532 6533 6534 6535 6536<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> 6537<span class="apii">[-0, +1, –]</span> 6538<pre>int luaL_loadbuffer (lua_State *L, 6539 const char *buff, 6540 size_t sz, 6541 const char *name);</pre> 6542 6543<p> 6544Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>. 6545 6546 6547 6548 6549 6550<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p> 6551<span class="apii">[-0, +1, –]</span> 6552<pre>int luaL_loadbufferx (lua_State *L, 6553 const char *buff, 6554 size_t sz, 6555 const char *name, 6556 const char *mode);</pre> 6557 6558<p> 6559Loads a buffer as a Lua chunk. 6560This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the 6561buffer pointed to by <code>buff</code> with size <code>sz</code>. 6562 6563 6564<p> 6565This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 6566<code>name</code> is the chunk name, 6567used for debug information and error messages. 6568The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. 6569 6570 6571 6572 6573 6574<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> 6575<span class="apii">[-0, +1, <em>m</em>]</span> 6576<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> 6577 6578<p> 6579Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>. 6580 6581 6582 6583 6584 6585<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p> 6586<span class="apii">[-0, +1, <em>m</em>]</span> 6587<pre>int luaL_loadfilex (lua_State *L, const char *filename, 6588 const char *mode);</pre> 6589 6590<p> 6591Loads a file as a Lua chunk. 6592This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file 6593named <code>filename</code>. 6594If <code>filename</code> is <code>NULL</code>, 6595then it loads from the standard input. 6596The first line in the file is ignored if it starts with a <code>#</code>. 6597 6598 6599<p> 6600The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. 6601 6602 6603<p> 6604This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, 6605but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> 6606for file-related errors 6607(e.g., it cannot open or read the file). 6608 6609 6610<p> 6611As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 6612it does not run it. 6613 6614 6615 6616 6617 6618<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> 6619<span class="apii">[-0, +1, –]</span> 6620<pre>int luaL_loadstring (lua_State *L, const char *s);</pre> 6621 6622<p> 6623Loads a string as a Lua chunk. 6624This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in 6625the zero-terminated string <code>s</code>. 6626 6627 6628<p> 6629This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 6630 6631 6632<p> 6633Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 6634it does not run it. 6635 6636 6637 6638 6639 6640<hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p> 6641<span class="apii">[-0, +1, <em>m</em>]</span> 6642<pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre> 6643 6644<p> 6645Creates a new table and registers there 6646the functions in list <code>l</code>. 6647 6648 6649<p> 6650It is implemented as the following macro: 6651 6652<pre> 6653 (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0)) 6654</pre><p> 6655The array <code>l</code> must be the actual array, 6656not a pointer to it. 6657 6658 6659 6660 6661 6662<hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p> 6663<span class="apii">[-0, +1, <em>m</em>]</span> 6664<pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre> 6665 6666<p> 6667Creates a new table with a size optimized 6668to store all entries in the array <code>l</code> 6669(but does not actually store them). 6670It is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> 6671(see <a href="#luaL_newlib"><code>luaL_newlib</code></a>). 6672 6673 6674<p> 6675It is implemented as a macro. 6676The array <code>l</code> must be the actual array, 6677not a pointer to it. 6678 6679 6680 6681 6682 6683<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> 6684<span class="apii">[-0, +1, <em>m</em>]</span> 6685<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> 6686 6687<p> 6688If the registry already has the key <code>tname</code>, 6689returns 0. 6690Otherwise, 6691creates a new table to be used as a metatable for userdata, 6692adds to this new table the pair <code>__name = tname</code>, 6693adds to the registry the pair <code>[tname] = new table</code>, 6694and returns 1. 6695(The entry <code>__name</code> is used by some error-reporting functions.) 6696 6697 6698<p> 6699In both cases pushes onto the stack the final value associated 6700with <code>tname</code> in the registry. 6701 6702 6703 6704 6705 6706<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> 6707<span class="apii">[-0, +0, –]</span> 6708<pre>lua_State *luaL_newstate (void);</pre> 6709 6710<p> 6711Creates a new Lua state. 6712It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an 6713allocator based on the standard C <code>realloc</code> function 6714and then sets a panic function (see <a href="#4.6">§4.6</a>) that prints 6715an error message to the standard error output in case of fatal 6716errors. 6717 6718 6719<p> 6720Returns the new state, 6721or <code>NULL</code> if there is a memory allocation error. 6722 6723 6724 6725 6726 6727<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> 6728<span class="apii">[-0, +0, <em>e</em>]</span> 6729<pre>void luaL_openlibs (lua_State *L);</pre> 6730 6731<p> 6732Opens all standard Lua libraries into the given state. 6733 6734 6735 6736 6737 6738<hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p> 6739<span class="apii">[-0, +0, <em>e</em>]</span> 6740<pre>T luaL_opt (L, func, arg, dflt);</pre> 6741 6742<p> 6743This macro is defined as follows: 6744 6745<pre> 6746 (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg))) 6747</pre><p> 6748In words, if the argument <code>arg</code> is nil or absent, 6749the macro results in the default <code>dflt</code>. 6750Otherwise, it results in the result of calling <code>func</code> 6751with the state <code>L</code> and the argument index <code>arg</code> as 6752parameters. 6753Note that it evaluates the expression <code>dflt</code> only if needed. 6754 6755 6756 6757 6758 6759<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> 6760<span class="apii">[-0, +0, <em>v</em>]</span> 6761<pre>lua_Integer luaL_optinteger (lua_State *L, 6762 int arg, 6763 lua_Integer d);</pre> 6764 6765<p> 6766If the function argument <code>arg</code> is an integer 6767(or convertible to an integer), 6768returns this integer. 6769If this argument is absent or is <b>nil</b>, 6770returns <code>d</code>. 6771Otherwise, raises an error. 6772 6773 6774 6775 6776 6777<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> 6778<span class="apii">[-0, +0, <em>v</em>]</span> 6779<pre>const char *luaL_optlstring (lua_State *L, 6780 int arg, 6781 const char *d, 6782 size_t *l);</pre> 6783 6784<p> 6785If the function argument <code>arg</code> is a string, 6786returns this string. 6787If this argument is absent or is <b>nil</b>, 6788returns <code>d</code>. 6789Otherwise, raises an error. 6790 6791 6792<p> 6793If <code>l</code> is not <code>NULL</code>, 6794fills the position <code>*l</code> with the result's length. 6795If the result is <code>NULL</code> 6796(only possible when returning <code>d</code> and <code>d == NULL</code>), 6797its length is considered zero. 6798 6799 6800<p> 6801This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6802so all conversions and caveats of that function apply here. 6803 6804 6805 6806 6807 6808<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> 6809<span class="apii">[-0, +0, <em>v</em>]</span> 6810<pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre> 6811 6812<p> 6813If the function argument <code>arg</code> is a number, 6814returns this number. 6815If this argument is absent or is <b>nil</b>, 6816returns <code>d</code>. 6817Otherwise, raises an error. 6818 6819 6820 6821 6822 6823<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> 6824<span class="apii">[-0, +0, <em>v</em>]</span> 6825<pre>const char *luaL_optstring (lua_State *L, 6826 int arg, 6827 const char *d);</pre> 6828 6829<p> 6830If the function argument <code>arg</code> is a string, 6831returns this string. 6832If this argument is absent or is <b>nil</b>, 6833returns <code>d</code>. 6834Otherwise, raises an error. 6835 6836 6837 6838 6839 6840<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> 6841<span class="apii">[-?, +?, <em>m</em>]</span> 6842<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> 6843 6844<p> 6845Equivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a> 6846with the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>. 6847 6848 6849 6850 6851 6852<hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p> 6853<span class="apii">[-?, +?, <em>m</em>]</span> 6854<pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre> 6855 6856<p> 6857Returns an address to a space of size <code>sz</code> 6858where you can copy a string to be added to buffer <code>B</code> 6859(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6860After copying the string into this space you must call 6861<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add 6862it to the buffer. 6863 6864 6865 6866 6867 6868<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> 6869<span class="apii">[-?, +1, <em>m</em>]</span> 6870<pre>void luaL_pushresult (luaL_Buffer *B);</pre> 6871 6872<p> 6873Finishes the use of buffer <code>B</code> leaving the final string on 6874the top of the stack. 6875 6876 6877 6878 6879 6880<hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p> 6881<span class="apii">[-?, +1, <em>m</em>]</span> 6882<pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre> 6883 6884<p> 6885Equivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>. 6886 6887 6888 6889 6890 6891<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> 6892<span class="apii">[-1, +0, <em>m</em>]</span> 6893<pre>int luaL_ref (lua_State *L, int t);</pre> 6894 6895<p> 6896Creates and returns a <em>reference</em>, 6897in the table at index <code>t</code>, 6898for the object at the top of the stack (and pops the object). 6899 6900 6901<p> 6902A reference is a unique integer key. 6903As long as you do not manually add integer keys into table <code>t</code>, 6904<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. 6905You can retrieve an object referred by reference <code>r</code> 6906by calling <code>lua_rawgeti(L, t, r)</code>. 6907Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object. 6908 6909 6910<p> 6911If the object at the top of the stack is <b>nil</b>, 6912<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>. 6913The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different 6914from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. 6915 6916 6917 6918 6919 6920<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> 6921<pre>typedef struct luaL_Reg { 6922 const char *name; 6923 lua_CFunction func; 6924} luaL_Reg;</pre> 6925 6926<p> 6927Type for arrays of functions to be registered by 6928<a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>. 6929<code>name</code> is the function name and <code>func</code> is a pointer to 6930the function. 6931Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry 6932in which both <code>name</code> and <code>func</code> are <code>NULL</code>. 6933 6934 6935 6936 6937 6938<hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p> 6939<span class="apii">[-0, +1, <em>e</em>]</span> 6940<pre>void luaL_requiref (lua_State *L, const char *modname, 6941 lua_CFunction openf, int glb);</pre> 6942 6943<p> 6944If <code>modname</code> is not already present in <a href="#pdf-package.loaded"><code>package.loaded</code></a>, 6945calls function <code>openf</code> with string <code>modname</code> as an argument 6946and sets the call result in <code>package.loaded[modname]</code>, 6947as if that function has been called through <a href="#pdf-require"><code>require</code></a>. 6948 6949 6950<p> 6951If <code>glb</code> is true, 6952also stores the module into global <code>modname</code>. 6953 6954 6955<p> 6956Leaves a copy of the module on the stack. 6957 6958 6959 6960 6961 6962<hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p> 6963<span class="apii">[-nup, +0, <em>m</em>]</span> 6964<pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre> 6965 6966<p> 6967Registers all functions in the array <code>l</code> 6968(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack 6969(below optional upvalues, see next). 6970 6971 6972<p> 6973When <code>nup</code> is not zero, 6974all functions are created sharing <code>nup</code> upvalues, 6975which must be previously pushed on the stack 6976on top of the library table. 6977These values are popped from the stack after the registration. 6978 6979 6980 6981 6982 6983<hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p> 6984<span class="apii">[-0, +0, –]</span> 6985<pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre> 6986 6987<p> 6988Sets the metatable of the object at the top of the stack 6989as the metatable associated with name <code>tname</code> 6990in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 6991 6992 6993 6994 6995 6996<hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3> 6997<pre>typedef struct luaL_Stream { 6998 FILE *f; 6999 lua_CFunction closef; 7000} luaL_Stream;</pre> 7001 7002<p> 7003The standard representation for file handles, 7004which is used by the standard I/O library. 7005 7006 7007<p> 7008A file handle is implemented as a full userdata, 7009with a metatable called <code>LUA_FILEHANDLE</code> 7010(where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name). 7011The metatable is created by the I/O library 7012(see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 7013 7014 7015<p> 7016This userdata must start with the structure <code>luaL_Stream</code>; 7017it can contain other data after this initial structure. 7018Field <code>f</code> points to the corresponding C stream 7019(or it can be <code>NULL</code> to indicate an incompletely created handle). 7020Field <code>closef</code> points to a Lua function 7021that will be called to close the stream 7022when the handle is closed or collected; 7023this function receives the file handle as its sole argument and 7024must return either <b>true</b> (in case of success) 7025or <b>nil</b> plus an error message (in case of error). 7026Once Lua calls this field, 7027it changes the field value to <code>NULL</code> 7028to signal that the handle is closed. 7029 7030 7031 7032 7033 7034<hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p> 7035<span class="apii">[-0, +0, <em>m</em>]</span> 7036<pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre> 7037 7038<p> 7039This function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>, 7040except that, when the test fails, 7041it returns <code>NULL</code> instead of raising an error. 7042 7043 7044 7045 7046 7047<hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p> 7048<span class="apii">[-0, +1, <em>e</em>]</span> 7049<pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre> 7050 7051<p> 7052Converts any Lua value at the given index to a C string 7053in a reasonable format. 7054The resulting string is pushed onto the stack and also 7055returned by the function. 7056If <code>len</code> is not <code>NULL</code>, 7057the function also sets <code>*len</code> with the string length. 7058 7059 7060<p> 7061If the value has a metatable with a <code>__tostring</code> field, 7062then <code>luaL_tolstring</code> calls the corresponding metamethod 7063with the value as argument, 7064and uses the result of the call as its result. 7065 7066 7067 7068 7069 7070<hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p> 7071<span class="apii">[-0, +1, <em>m</em>]</span> 7072<pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, 7073 int level);</pre> 7074 7075<p> 7076Creates and pushes a traceback of the stack <code>L1</code>. 7077If <code>msg</code> is not <code>NULL</code> it is appended 7078at the beginning of the traceback. 7079The <code>level</code> parameter tells at which level 7080to start the traceback. 7081 7082 7083 7084 7085 7086<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> 7087<span class="apii">[-0, +0, –]</span> 7088<pre>const char *luaL_typename (lua_State *L, int index);</pre> 7089 7090<p> 7091Returns the name of the type of the value at the given index. 7092 7093 7094 7095 7096 7097<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> 7098<span class="apii">[-0, +0, –]</span> 7099<pre>void luaL_unref (lua_State *L, int t, int ref);</pre> 7100 7101<p> 7102Releases reference <code>ref</code> from the table at index <code>t</code> 7103(see <a href="#luaL_ref"><code>luaL_ref</code></a>). 7104The entry is removed from the table, 7105so that the referred object can be collected. 7106The reference <code>ref</code> is also freed to be used again. 7107 7108 7109<p> 7110If <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>, 7111<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. 7112 7113 7114 7115 7116 7117<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> 7118<span class="apii">[-0, +1, <em>m</em>]</span> 7119<pre>void luaL_where (lua_State *L, int lvl);</pre> 7120 7121<p> 7122Pushes onto the stack a string identifying the current position 7123of the control at level <code>lvl</code> in the call stack. 7124Typically this string has the following format: 7125 7126<pre> 7127 <em>chunkname</em>:<em>currentline</em>: 7128</pre><p> 7129Level 0 is the running function, 7130level 1 is the function that called the running function, 7131etc. 7132 7133 7134<p> 7135This function is used to build a prefix for error messages. 7136 7137 7138 7139 7140 7141 7142 7143<h1>6 – <a name="6">Standard Libraries</a></h1> 7144 7145<p> 7146The standard Lua libraries provide useful functions 7147that are implemented directly through the C API. 7148Some of these functions provide essential services to the language 7149(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); 7150others provide access to "outside" services (e.g., I/O); 7151and others could be implemented in Lua itself, 7152but are quite useful or have critical performance requirements that 7153deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). 7154 7155 7156<p> 7157All libraries are implemented through the official C API 7158and are provided as separate C modules. 7159Currently, Lua has the following standard libraries: 7160 7161<ul> 7162 7163<li>basic library (<a href="#6.1">§6.1</a>);</li> 7164 7165<li>coroutine library (<a href="#6.2">§6.2</a>);</li> 7166 7167<li>package library (<a href="#6.3">§6.3</a>);</li> 7168 7169<li>string manipulation (<a href="#6.4">§6.4</a>);</li> 7170 7171<li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li> 7172 7173<li>table manipulation (<a href="#6.6">§6.6</a>);</li> 7174 7175<li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li> 7176 7177<li>input and output (<a href="#6.8">§6.8</a>);</li> 7178 7179<li>operating system facilities (<a href="#6.9">§6.9</a>);</li> 7180 7181<li>debug facilities (<a href="#6.10">§6.10</a>).</li> 7182 7183</ul><p> 7184Except for the basic and the package libraries, 7185each library provides all its functions as fields of a global table 7186or as methods of its objects. 7187 7188 7189<p> 7190To have access to these libraries, 7191the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, 7192which opens all standard libraries. 7193Alternatively, 7194the host program can open them individually by using 7195<a href="#luaL_requiref"><code>luaL_requiref</code></a> to call 7196<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), 7197<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), 7198<a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library), 7199<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), 7200<a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF8 library), 7201<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), 7202<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), 7203<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), 7204<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library), 7205and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). 7206These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>. 7207 7208 7209 7210<h2>6.1 – <a name="6.1">Basic Functions</a></h2> 7211 7212<p> 7213The basic library provides core functions to Lua. 7214If you do not include this library in your application, 7215you should check carefully whether you need to provide 7216implementations for some of its facilities. 7217 7218 7219<p> 7220<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> 7221 7222 7223<p> 7224Calls <a href="#pdf-error"><code>error</code></a> if 7225the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); 7226otherwise, returns all its arguments. 7227In case of error, 7228<code>message</code> is the error object; 7229when absent, it defaults to "<code>assertion failed!</code>" 7230 7231 7232 7233 7234<p> 7235<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3> 7236 7237 7238<p> 7239This function is a generic interface to the garbage collector. 7240It performs different functions according to its first argument, <code>opt</code>: 7241 7242<ul> 7243 7244<li><b>"<code>collect</code>": </b> 7245performs a full garbage-collection cycle. 7246This is the default option. 7247</li> 7248 7249<li><b>"<code>stop</code>": </b> 7250stops automatic execution of the garbage collector. 7251The collector will run only when explicitly invoked, 7252until a call to restart it. 7253</li> 7254 7255<li><b>"<code>restart</code>": </b> 7256restarts automatic execution of the garbage collector. 7257</li> 7258 7259<li><b>"<code>count</code>": </b> 7260returns the total memory in use by Lua in Kbytes. 7261The value has a fractional part, 7262so that it multiplied by 1024 7263gives the exact number of bytes in use by Lua 7264(except for overflows). 7265</li> 7266 7267<li><b>"<code>step</code>": </b> 7268performs a garbage-collection step. 7269The step "size" is controlled by <code>arg</code>. 7270With a zero value, 7271the collector will perform one basic (indivisible) step. 7272For non-zero values, 7273the collector will perform as if that amount of memory 7274(in KBytes) had been allocated by Lua. 7275Returns <b>true</b> if the step finished a collection cycle. 7276</li> 7277 7278<li><b>"<code>setpause</code>": </b> 7279sets <code>arg</code> as the new value for the <em>pause</em> of 7280the collector (see <a href="#2.5">§2.5</a>). 7281Returns the previous value for <em>pause</em>. 7282</li> 7283 7284<li><b>"<code>setstepmul</code>": </b> 7285sets <code>arg</code> as the new value for the <em>step multiplier</em> of 7286the collector (see <a href="#2.5">§2.5</a>). 7287Returns the previous value for <em>step</em>. 7288</li> 7289 7290<li><b>"<code>isrunning</code>": </b> 7291returns a boolean that tells whether the collector is running 7292(i.e., not stopped). 7293</li> 7294 7295</ul> 7296 7297 7298 7299<p> 7300<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> 7301Opens the named file and executes its contents as a Lua chunk. 7302When called without arguments, 7303<code>dofile</code> executes the contents of the standard input (<code>stdin</code>). 7304Returns all values returned by the chunk. 7305In case of errors, <code>dofile</code> propagates the error 7306to its caller (that is, <code>dofile</code> does not run in protected mode). 7307 7308 7309 7310 7311<p> 7312<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> 7313Terminates the last protected function called 7314and returns <code>message</code> as the error object. 7315Function <code>error</code> never returns. 7316 7317 7318<p> 7319Usually, <code>error</code> adds some information about the error position 7320at the beginning of the message, if the message is a string. 7321The <code>level</code> argument specifies how to get the error position. 7322With level 1 (the default), the error position is where the 7323<code>error</code> function was called. 7324Level 2 points the error to where the function 7325that called <code>error</code> was called; and so on. 7326Passing a level 0 avoids the addition of error position information 7327to the message. 7328 7329 7330 7331 7332<p> 7333<hr><h3><a name="pdf-_G"><code>_G</code></a></h3> 7334A global variable (not a function) that 7335holds the global environment (see <a href="#2.2">§2.2</a>). 7336Lua itself does not use this variable; 7337changing its value does not affect any environment, 7338nor vice versa. 7339 7340 7341 7342 7343<p> 7344<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> 7345 7346 7347<p> 7348If <code>object</code> does not have a metatable, returns <b>nil</b>. 7349Otherwise, 7350if the object's metatable has a <code>__metatable</code> field, 7351returns the associated value. 7352Otherwise, returns the metatable of the given object. 7353 7354 7355 7356 7357<p> 7358<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> 7359 7360 7361<p> 7362Returns three values (an iterator function, the table <code>t</code>, and 0) 7363so that the construction 7364 7365<pre> 7366 for i,v in ipairs(t) do <em>body</em> end 7367</pre><p> 7368will iterate over the key–value pairs 7369(<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., 7370up to the first nil value. 7371 7372 7373 7374 7375<p> 7376<hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3> 7377 7378 7379<p> 7380Loads a chunk. 7381 7382 7383<p> 7384If <code>chunk</code> is a string, the chunk is this string. 7385If <code>chunk</code> is a function, 7386<code>load</code> calls it repeatedly to get the chunk pieces. 7387Each call to <code>chunk</code> must return a string that concatenates 7388with previous results. 7389A return of an empty string, <b>nil</b>, or no value signals the end of the chunk. 7390 7391 7392<p> 7393If there are no syntactic errors, 7394returns the compiled chunk as a function; 7395otherwise, returns <b>nil</b> plus the error message. 7396 7397 7398<p> 7399If the resulting function has upvalues, 7400the first upvalue is set to the value of <code>env</code>, 7401if that parameter is given, 7402or to the value of the global environment. 7403Other upvalues are initialized with <b>nil</b>. 7404(When you load a main chunk, 7405the resulting function will always have exactly one upvalue, 7406the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 7407However, 7408when you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>), 7409the resulting function can have an arbitrary number of upvalues.) 7410All upvalues are fresh, that is, 7411they are not shared with any other function. 7412 7413 7414<p> 7415<code>chunkname</code> is used as the name of the chunk for error messages 7416and debug information (see <a href="#4.9">§4.9</a>). 7417When absent, 7418it defaults to <code>chunk</code>, if <code>chunk</code> is a string, 7419or to "<code>=(load)</code>" otherwise. 7420 7421 7422<p> 7423The string <code>mode</code> controls whether the chunk can be text or binary 7424(that is, a precompiled chunk). 7425It may be the string "<code>b</code>" (only binary chunks), 7426"<code>t</code>" (only text chunks), 7427or "<code>bt</code>" (both binary and text). 7428The default is "<code>bt</code>". 7429 7430 7431<p> 7432Lua does not check the consistency of binary chunks. 7433Maliciously crafted binary chunks can crash 7434the interpreter. 7435 7436 7437 7438 7439<p> 7440<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3> 7441 7442 7443<p> 7444Similar to <a href="#pdf-load"><code>load</code></a>, 7445but gets the chunk from file <code>filename</code> 7446or from the standard input, 7447if no file name is given. 7448 7449 7450 7451 7452<p> 7453<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> 7454 7455 7456<p> 7457Allows a program to traverse all fields of a table. 7458Its first argument is a table and its second argument 7459is an index in this table. 7460<code>next</code> returns the next index of the table 7461and its associated value. 7462When called with <b>nil</b> as its second argument, 7463<code>next</code> returns an initial index 7464and its associated value. 7465When called with the last index, 7466or with <b>nil</b> in an empty table, 7467<code>next</code> returns <b>nil</b>. 7468If the second argument is absent, then it is interpreted as <b>nil</b>. 7469In particular, 7470you can use <code>next(t)</code> to check whether a table is empty. 7471 7472 7473<p> 7474The order in which the indices are enumerated is not specified, 7475<em>even for numeric indices</em>. 7476(To traverse a table in numerical order, 7477use a numerical <b>for</b>.) 7478 7479 7480<p> 7481The behavior of <code>next</code> is undefined if, 7482during the traversal, 7483you assign any value to a non-existent field in the table. 7484You may however modify existing fields. 7485In particular, you may clear existing fields. 7486 7487 7488 7489 7490<p> 7491<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> 7492 7493 7494<p> 7495If <code>t</code> has a metamethod <code>__pairs</code>, 7496calls it with <code>t</code> as argument and returns the first three 7497results from the call. 7498 7499 7500<p> 7501Otherwise, 7502returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, 7503so that the construction 7504 7505<pre> 7506 for k,v in pairs(t) do <em>body</em> end 7507</pre><p> 7508will iterate over all key–value pairs of table <code>t</code>. 7509 7510 7511<p> 7512See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 7513the table during its traversal. 7514 7515 7516 7517 7518<p> 7519<hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3> 7520 7521 7522<p> 7523Calls function <code>f</code> with 7524the given arguments in <em>protected mode</em>. 7525This means that any error inside <code>f</code> is not propagated; 7526instead, <code>pcall</code> catches the error 7527and returns a status code. 7528Its first result is the status code (a boolean), 7529which is true if the call succeeds without errors. 7530In such case, <code>pcall</code> also returns all results from the call, 7531after this first result. 7532In case of any error, <code>pcall</code> returns <b>false</b> plus the error message. 7533 7534 7535 7536 7537<p> 7538<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> 7539Receives any number of arguments 7540and prints their values to <code>stdout</code>, 7541using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string. 7542<code>print</code> is not intended for formatted output, 7543but only as a quick way to show a value, 7544for instance for debugging. 7545For complete control over the output, 7546use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. 7547 7548 7549 7550 7551<p> 7552<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> 7553Checks whether <code>v1</code> is equal to <code>v2</code>, 7554without invoking the <code>__eq</code> metamethod. 7555Returns a boolean. 7556 7557 7558 7559 7560<p> 7561<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> 7562Gets the real value of <code>table[index]</code>, 7563without invoking the <code>__index</code> metamethod. 7564<code>table</code> must be a table; 7565<code>index</code> may be any value. 7566 7567 7568 7569 7570<p> 7571<hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3> 7572Returns the length of the object <code>v</code>, 7573which must be a table or a string, 7574without invoking the <code>__len</code> metamethod. 7575Returns an integer. 7576 7577 7578 7579 7580<p> 7581<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> 7582Sets the real value of <code>table[index]</code> to <code>value</code>, 7583without invoking the <code>__newindex</code> metamethod. 7584<code>table</code> must be a table, 7585<code>index</code> any value different from <b>nil</b> and NaN, 7586and <code>value</code> any Lua value. 7587 7588 7589<p> 7590This function returns <code>table</code>. 7591 7592 7593 7594 7595<p> 7596<hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> 7597 7598 7599<p> 7600If <code>index</code> is a number, 7601returns all arguments after argument number <code>index</code>; 7602a negative number indexes from the end (-1 is the last argument). 7603Otherwise, <code>index</code> must be the string <code>"#"</code>, 7604and <code>select</code> returns the total number of extra arguments it received. 7605 7606 7607 7608 7609<p> 7610<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> 7611 7612 7613<p> 7614Sets the metatable for the given table. 7615(To change the metatable of other types from Lua code, 7616you must use the debug library (<a href="#6.10">§6.10</a>).) 7617If <code>metatable</code> is <b>nil</b>, 7618removes the metatable of the given table. 7619If the original metatable has a <code>__metatable</code> field, 7620raises an error. 7621 7622 7623<p> 7624This function returns <code>table</code>. 7625 7626 7627 7628 7629<p> 7630<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> 7631 7632 7633<p> 7634When called with no <code>base</code>, 7635<code>tonumber</code> tries to convert its argument to a number. 7636If the argument is already a number or 7637a string convertible to a number, 7638then <code>tonumber</code> returns this number; 7639otherwise, it returns <b>nil</b>. 7640 7641 7642<p> 7643The conversion of strings can result in integers or floats, 7644according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 7645(The string may have leading and trailing spaces and a sign.) 7646 7647 7648<p> 7649When called with <code>base</code>, 7650then <code>e</code> must be a string to be interpreted as 7651an integer numeral in that base. 7652The base may be any integer between 2 and 36, inclusive. 7653In bases above 10, the letter '<code>A</code>' (in either upper or lower case) 7654represents 10, '<code>B</code>' represents 11, and so forth, 7655with '<code>Z</code>' representing 35. 7656If the string <code>e</code> is not a valid numeral in the given base, 7657the function returns <b>nil</b>. 7658 7659 7660 7661 7662<p> 7663<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3> 7664Receives a value of any type and 7665converts it to a string in a human-readable format. 7666(For complete control of how numbers are converted, 7667use <a href="#pdf-string.format"><code>string.format</code></a>.) 7668 7669 7670<p> 7671If the metatable of <code>v</code> has a <code>__tostring</code> field, 7672then <code>tostring</code> calls the corresponding value 7673with <code>v</code> as argument, 7674and uses the result of the call as its result. 7675 7676 7677 7678 7679<p> 7680<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> 7681Returns the type of its only argument, coded as a string. 7682The possible results of this function are 7683"<code>nil</code>" (a string, not the value <b>nil</b>), 7684"<code>number</code>", 7685"<code>string</code>", 7686"<code>boolean</code>", 7687"<code>table</code>", 7688"<code>function</code>", 7689"<code>thread</code>", 7690and "<code>userdata</code>". 7691 7692 7693 7694 7695<p> 7696<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> 7697 7698 7699<p> 7700A global variable (not a function) that 7701holds a string containing the running Lua version. 7702The current value of this variable is "<code>Lua 5.3</code>". 7703 7704 7705 7706 7707<p> 7708<hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3> 7709 7710 7711<p> 7712This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, 7713except that it sets a new message handler <code>msgh</code>. 7714 7715 7716 7717 7718 7719 7720 7721<h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2> 7722 7723<p> 7724This library comprises the operations to manipulate coroutines, 7725which come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. 7726See <a href="#2.6">§2.6</a> for a general description of coroutines. 7727 7728 7729<p> 7730<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> 7731 7732 7733<p> 7734Creates a new coroutine, with body <code>f</code>. 7735<code>f</code> must be a function. 7736Returns this new coroutine, 7737an object with type <code>"thread"</code>. 7738 7739 7740 7741 7742<p> 7743<hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ()</code></a></h3> 7744 7745 7746<p> 7747Returns true when the running coroutine can yield. 7748 7749 7750<p> 7751A running coroutine is yieldable if it is not the main thread and 7752it is not inside a non-yieldable C function. 7753 7754 7755 7756 7757<p> 7758<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> 7759 7760 7761<p> 7762Starts or continues the execution of coroutine <code>co</code>. 7763The first time you resume a coroutine, 7764it starts running its body. 7765The values <code>val1</code>, ... are passed 7766as the arguments to the body function. 7767If the coroutine has yielded, 7768<code>resume</code> restarts it; 7769the values <code>val1</code>, ... are passed 7770as the results from the yield. 7771 7772 7773<p> 7774If the coroutine runs without any errors, 7775<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> 7776(when the coroutine yields) or any values returned by the body function 7777(when the coroutine terminates). 7778If there is any error, 7779<code>resume</code> returns <b>false</b> plus the error message. 7780 7781 7782 7783 7784<p> 7785<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> 7786 7787 7788<p> 7789Returns the running coroutine plus a boolean, 7790true when the running coroutine is the main one. 7791 7792 7793 7794 7795<p> 7796<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> 7797 7798 7799<p> 7800Returns the status of coroutine <code>co</code>, as a string: 7801<code>"running"</code>, 7802if the coroutine is running (that is, it called <code>status</code>); 7803<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, 7804or if it has not started running yet; 7805<code>"normal"</code> if the coroutine is active but not running 7806(that is, it has resumed another coroutine); 7807and <code>"dead"</code> if the coroutine has finished its body function, 7808or if it has stopped with an error. 7809 7810 7811 7812 7813<p> 7814<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> 7815 7816 7817<p> 7818Creates a new coroutine, with body <code>f</code>. 7819<code>f</code> must be a function. 7820Returns a function that resumes the coroutine each time it is called. 7821Any arguments passed to the function behave as the 7822extra arguments to <code>resume</code>. 7823Returns the same values returned by <code>resume</code>, 7824except the first boolean. 7825In case of error, propagates the error. 7826 7827 7828 7829 7830<p> 7831<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> 7832 7833 7834<p> 7835Suspends the execution of the calling coroutine. 7836Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>. 7837 7838 7839 7840 7841 7842 7843 7844<h2>6.3 – <a name="6.3">Modules</a></h2> 7845 7846<p> 7847The package library provides basic 7848facilities for loading modules in Lua. 7849It exports one function directly in the global environment: 7850<a href="#pdf-require"><code>require</code></a>. 7851Everything else is exported in a table <a name="pdf-package"><code>package</code></a>. 7852 7853 7854<p> 7855<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> 7856 7857 7858<p> 7859Loads the given module. 7860The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table 7861to determine whether <code>modname</code> is already loaded. 7862If it is, then <code>require</code> returns the value stored 7863at <code>package.loaded[modname]</code>. 7864Otherwise, it tries to find a <em>loader</em> for the module. 7865 7866 7867<p> 7868To find a loader, 7869<code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence. 7870By changing this sequence, 7871we can change how <code>require</code> looks for a module. 7872The following explanation is based on the default configuration 7873for <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 7874 7875 7876<p> 7877First <code>require</code> queries <code>package.preload[modname]</code>. 7878If it has a value, 7879this value (which must be a function) is the loader. 7880Otherwise <code>require</code> searches for a Lua loader using the 7881path stored in <a href="#pdf-package.path"><code>package.path</code></a>. 7882If that also fails, it searches for a C loader using the 7883path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 7884If that also fails, 7885it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>). 7886 7887 7888<p> 7889Once a loader is found, 7890<code>require</code> calls the loader with two arguments: 7891<code>modname</code> and an extra value dependent on how it got the loader. 7892(If the loader came from a file, 7893this extra value is the file name.) 7894If the loader returns any non-nil value, 7895<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. 7896If the loader does not return a non-nil value and 7897has not assigned any value to <code>package.loaded[modname]</code>, 7898then <code>require</code> assigns <b>true</b> to this entry. 7899In any case, <code>require</code> returns the 7900final value of <code>package.loaded[modname]</code>. 7901 7902 7903<p> 7904If there is any error loading or running the module, 7905or if it cannot find any loader for the module, 7906then <code>require</code> raises an error. 7907 7908 7909 7910 7911<p> 7912<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3> 7913 7914 7915<p> 7916A string describing some compile-time configurations for packages. 7917This string is a sequence of lines: 7918 7919<ul> 7920 7921<li>The first line is the directory separator string. 7922Default is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li> 7923 7924<li>The second line is the character that separates templates in a path. 7925Default is '<code>;</code>'.</li> 7926 7927<li>The third line is the string that marks the 7928substitution points in a template. 7929Default is '<code>?</code>'.</li> 7930 7931<li>The fourth line is a string that, in a path in Windows, 7932is replaced by the executable's directory. 7933Default is '<code>!</code>'.</li> 7934 7935<li>The fifth line is a mark to ignore all text after it 7936when building the <code>luaopen_</code> function name. 7937Default is '<code>-</code>'.</li> 7938 7939</ul> 7940 7941 7942 7943<p> 7944<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> 7945 7946 7947<p> 7948The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. 7949 7950 7951<p> 7952Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way 7953it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, 7954using the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>, 7955or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>, 7956or a default path defined in <code>luaconf.h</code>. 7957 7958 7959 7960 7961<p> 7962<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> 7963 7964 7965<p> 7966A table used by <a href="#pdf-require"><code>require</code></a> to control which 7967modules are already loaded. 7968When you require a module <code>modname</code> and 7969<code>package.loaded[modname]</code> is not false, 7970<a href="#pdf-require"><code>require</code></a> simply returns the value stored there. 7971 7972 7973<p> 7974This variable is only a reference to the real table; 7975assignments to this variable do not change the 7976table used by <a href="#pdf-require"><code>require</code></a>. 7977 7978 7979 7980 7981<p> 7982<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> 7983 7984 7985<p> 7986Dynamically links the host program with the C library <code>libname</code>. 7987 7988 7989<p> 7990If <code>funcname</code> is "<code>*</code>", 7991then it only links with the library, 7992making the symbols exported by the library 7993available to other dynamically linked libraries. 7994Otherwise, 7995it looks for a function <code>funcname</code> inside the library 7996and returns this function as a C function. 7997So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype 7998(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 7999 8000 8001<p> 8002This is a low-level function. 8003It completely bypasses the package and module system. 8004Unlike <a href="#pdf-require"><code>require</code></a>, 8005it does not perform any path searching and 8006does not automatically adds extensions. 8007<code>libname</code> must be the complete file name of the C library, 8008including if necessary a path and an extension. 8009<code>funcname</code> must be the exact name exported by the C library 8010(which may depend on the C compiler and linker used). 8011 8012 8013<p> 8014This function is not supported by Standard C. 8015As such, it is only available on some platforms 8016(Windows, Linux, Mac OS X, Solaris, BSD, 8017plus other Unix systems that support the <code>dlfcn</code> standard). 8018 8019 8020 8021 8022<p> 8023<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> 8024 8025 8026<p> 8027The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. 8028 8029 8030<p> 8031At start-up, Lua initializes this variable with 8032the value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or 8033the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or 8034with a default path defined in <code>luaconf.h</code>, 8035if those environment variables are not defined. 8036Any "<code>;;</code>" in the value of the environment variable 8037is replaced by the default path. 8038 8039 8040 8041 8042<p> 8043<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> 8044 8045 8046<p> 8047A table to store loaders for specific modules 8048(see <a href="#pdf-require"><code>require</code></a>). 8049 8050 8051<p> 8052This variable is only a reference to the real table; 8053assignments to this variable do not change the 8054table used by <a href="#pdf-require"><code>require</code></a>. 8055 8056 8057 8058 8059<p> 8060<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3> 8061 8062 8063<p> 8064A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules. 8065 8066 8067<p> 8068Each entry in this table is a <em>searcher function</em>. 8069When looking for a module, 8070<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, 8071with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its 8072sole parameter. 8073The function can return another function (the module <em>loader</em>) 8074plus an extra value that will be passed to that loader, 8075or a string explaining why it did not find that module 8076(or <b>nil</b> if it has nothing to say). 8077 8078 8079<p> 8080Lua initializes this table with four searcher functions. 8081 8082 8083<p> 8084The first searcher simply looks for a loader in the 8085<a href="#pdf-package.preload"><code>package.preload</code></a> table. 8086 8087 8088<p> 8089The second searcher looks for a loader as a Lua library, 8090using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. 8091The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8092 8093 8094<p> 8095The third searcher looks for a loader as a C library, 8096using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 8097Again, 8098the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8099For instance, 8100if the C path is the string 8101 8102<pre> 8103 "./?.so;./?.dll;/usr/local/?/init.so" 8104</pre><p> 8105the searcher for module <code>foo</code> 8106will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, 8107and <code>/usr/local/foo/init.so</code>, in that order. 8108Once it finds a C library, 8109this searcher first uses a dynamic link facility to link the 8110application with the library. 8111Then it tries to find a C function inside the library to 8112be used as the loader. 8113The name of this C function is the string "<code>luaopen_</code>" 8114concatenated with a copy of the module name where each dot 8115is replaced by an underscore. 8116Moreover, if the module name has a hyphen, 8117its suffix after (and including) the first hyphen is removed. 8118For instance, if the module name is <code>a.b.c-v2.1</code>, 8119the function name will be <code>luaopen_a_b_c</code>. 8120 8121 8122<p> 8123The fourth searcher tries an <em>all-in-one loader</em>. 8124It searches the C path for a library for 8125the root name of the given module. 8126For instance, when requiring <code>a.b.c</code>, 8127it will search for a C library for <code>a</code>. 8128If found, it looks into it for an open function for 8129the submodule; 8130in our example, that would be <code>luaopen_a_b_c</code>. 8131With this facility, a package can pack several C submodules 8132into one single library, 8133with each submodule keeping its original open function. 8134 8135 8136<p> 8137All searchers except the first one (preload) return as the extra value 8138the file name where the module was found, 8139as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8140The first searcher returns no extra value. 8141 8142 8143 8144 8145<p> 8146<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3> 8147 8148 8149<p> 8150Searches for the given <code>name</code> in the given <code>path</code>. 8151 8152 8153<p> 8154A path is a string containing a sequence of 8155<em>templates</em> separated by semicolons. 8156For each template, 8157the function replaces each interrogation mark (if any) 8158in the template with a copy of <code>name</code> 8159wherein all occurrences of <code>sep</code> 8160(a dot, by default) 8161were replaced by <code>rep</code> 8162(the system's directory separator, by default), 8163and then tries to open the resulting file name. 8164 8165 8166<p> 8167For instance, if the path is the string 8168 8169<pre> 8170 "./?.lua;./?.lc;/usr/local/?/init.lua" 8171</pre><p> 8172the search for the name <code>foo.a</code> 8173will try to open the files 8174<code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and 8175<code>/usr/local/foo/a/init.lua</code>, in that order. 8176 8177 8178<p> 8179Returns the resulting name of the first file that it can 8180open in read mode (after closing the file), 8181or <b>nil</b> plus an error message if none succeeds. 8182(This error message lists all file names it tried to open.) 8183 8184 8185 8186 8187 8188 8189 8190<h2>6.4 – <a name="6.4">String Manipulation</a></h2> 8191 8192<p> 8193This library provides generic functions for string manipulation, 8194such as finding and extracting substrings, and pattern matching. 8195When indexing a string in Lua, the first character is at position 1 8196(not at 0, as in C). 8197Indices are allowed to be negative and are interpreted as indexing backwards, 8198from the end of the string. 8199Thus, the last character is at position -1, and so on. 8200 8201 8202<p> 8203The string library provides all its functions inside the table 8204<a name="pdf-string"><code>string</code></a>. 8205It also sets a metatable for strings 8206where the <code>__index</code> field points to the <code>string</code> table. 8207Therefore, you can use the string functions in object-oriented style. 8208For instance, <code>string.byte(s,i)</code> 8209can be written as <code>s:byte(i)</code>. 8210 8211 8212<p> 8213The string library assumes one-byte character encodings. 8214 8215 8216<p> 8217<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> 8218Returns the internal numeric codes of the characters <code>s[i]</code>, 8219<code>s[i+1]</code>, ..., <code>s[j]</code>. 8220The default value for <code>i</code> is 1; 8221the default value for <code>j</code> is <code>i</code>. 8222These indices are corrected 8223following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>. 8224 8225 8226<p> 8227Numeric codes are not necessarily portable across platforms. 8228 8229 8230 8231 8232<p> 8233<hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> 8234Receives zero or more integers. 8235Returns a string with length equal to the number of arguments, 8236in which each character has the internal numeric code equal 8237to its corresponding argument. 8238 8239 8240<p> 8241Numeric codes are not necessarily portable across platforms. 8242 8243 8244 8245 8246<p> 8247<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3> 8248 8249 8250<p> 8251Returns a string containing a binary representation 8252(a <em>binary chunk</em>) 8253of the given function, 8254so that a later <a href="#pdf-load"><code>load</code></a> on this string returns 8255a copy of the function (but with new upvalues). 8256If <code>strip</code> is a true value, 8257the binary representation may not include all debug information 8258about the function, 8259to save space. 8260 8261 8262<p> 8263Functions with upvalues have only their number of upvalues saved. 8264When (re)loaded, 8265those upvalues receive fresh instances containing <b>nil</b>. 8266(You can use the debug library to serialize 8267and reload the upvalues of a function 8268in a way adequate to your needs.) 8269 8270 8271 8272 8273<p> 8274<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> 8275 8276 8277<p> 8278Looks for the first match of 8279<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 8280If it finds a match, then <code>find</code> returns the indices of <code>s</code> 8281where this occurrence starts and ends; 8282otherwise, it returns <b>nil</b>. 8283A third, optional numeric argument <code>init</code> specifies 8284where to start the search; 8285its default value is 1 and can be negative. 8286A value of <b>true</b> as a fourth, optional argument <code>plain</code> 8287turns off the pattern matching facilities, 8288so the function does a plain "find substring" operation, 8289with no characters in <code>pattern</code> being considered magic. 8290Note that if <code>plain</code> is given, then <code>init</code> must be given as well. 8291 8292 8293<p> 8294If the pattern has captures, 8295then in a successful match 8296the captured values are also returned, 8297after the two indices. 8298 8299 8300 8301 8302<p> 8303<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> 8304 8305 8306<p> 8307Returns a formatted version of its variable number of arguments 8308following the description given in its first argument (which must be a string). 8309The format string follows the same rules as the ISO C function <code>sprintf</code>. 8310The only differences are that the options/modifiers 8311<code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>, 8312and <code>p</code> are not supported 8313and that there is an extra option, <code>q</code>. 8314 8315 8316<p> 8317The <code>q</code> option formats a string between double quotes, 8318using escape sequences when necessary to ensure that 8319it can safely be read back by the Lua interpreter. 8320For instance, the call 8321 8322<pre> 8323 string.format('%q', 'a string with "quotes" and \n new line') 8324</pre><p> 8325may produce the string: 8326 8327<pre> 8328 "a string with \"quotes\" and \ 8329 new line" 8330</pre> 8331 8332<p> 8333Options 8334<code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>, 8335<code>G</code>, and <code>g</code> all expect a number as argument. 8336Options <code>c</code>, <code>d</code>, 8337<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> 8338expect an integer. 8339When Lua is compiled with a C89 compiler, 8340options <code>A</code> and <code>a</code> (hexadecimal floats) 8341do not support any modifier (flags, width, length). 8342 8343 8344<p> 8345Option <code>s</code> expects a string; 8346if its argument is not a string, 8347it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 8348If the option has any modifier (flags, width, length), 8349the string argument should not contain embedded zeros. 8350 8351 8352 8353 8354<p> 8355<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3> 8356Returns an iterator function that, 8357each time it is called, 8358returns the next captures from <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) 8359over the string <code>s</code>. 8360If <code>pattern</code> specifies no captures, 8361then the whole match is produced in each call. 8362 8363 8364<p> 8365As an example, the following loop 8366will iterate over all the words from string <code>s</code>, 8367printing one per line: 8368 8369<pre> 8370 s = "hello world from Lua" 8371 for w in string.gmatch(s, "%a+") do 8372 print(w) 8373 end 8374</pre><p> 8375The next example collects all pairs <code>key=value</code> from the 8376given string into a table: 8377 8378<pre> 8379 t = {} 8380 s = "from=world, to=Lua" 8381 for k, v in string.gmatch(s, "(%w+)=(%w+)") do 8382 t[k] = v 8383 end 8384</pre> 8385 8386<p> 8387For this function, a caret '<code>^</code>' at the start of a pattern does not 8388work as an anchor, as this would prevent the iteration. 8389 8390 8391 8392 8393<p> 8394<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> 8395Returns a copy of <code>s</code> 8396in which all (or the first <code>n</code>, if given) 8397occurrences of the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) have been 8398replaced by a replacement string specified by <code>repl</code>, 8399which can be a string, a table, or a function. 8400<code>gsub</code> also returns, as its second value, 8401the total number of matches that occurred. 8402The name <code>gsub</code> comes from <em>Global SUBstitution</em>. 8403 8404 8405<p> 8406If <code>repl</code> is a string, then its value is used for replacement. 8407The character <code>%</code> works as an escape character: 8408any sequence in <code>repl</code> of the form <code>%<em>d</em></code>, 8409with <em>d</em> between 1 and 9, 8410stands for the value of the <em>d</em>-th captured substring. 8411The sequence <code>%0</code> stands for the whole match. 8412The sequence <code>%%</code> stands for a single <code>%</code>. 8413 8414 8415<p> 8416If <code>repl</code> is a table, then the table is queried for every match, 8417using the first capture as the key. 8418 8419 8420<p> 8421If <code>repl</code> is a function, then this function is called every time a 8422match occurs, with all captured substrings passed as arguments, 8423in order. 8424 8425 8426<p> 8427In any case, 8428if the pattern specifies no captures, 8429then it behaves as if the whole pattern was inside a capture. 8430 8431 8432<p> 8433If the value returned by the table query or by the function call 8434is a string or a number, 8435then it is used as the replacement string; 8436otherwise, if it is <b>false</b> or <b>nil</b>, 8437then there is no replacement 8438(that is, the original match is kept in the string). 8439 8440 8441<p> 8442Here are some examples: 8443 8444<pre> 8445 x = string.gsub("hello world", "(%w+)", "%1 %1") 8446 --> x="hello hello world world" 8447 8448 x = string.gsub("hello world", "%w+", "%0 %0", 1) 8449 --> x="hello hello world" 8450 8451 x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 8452 --> x="world hello Lua from" 8453 8454 x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) 8455 --> x="home = /home/roberto, user = roberto" 8456 8457 x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 8458 return load(s)() 8459 end) 8460 --> x="4+5 = 9" 8461 8462 local t = {name="lua", version="5.3"} 8463 x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 8464 --> x="lua-5.3.tar.gz" 8465</pre> 8466 8467 8468 8469<p> 8470<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> 8471Receives a string and returns its length. 8472The empty string <code>""</code> has length 0. 8473Embedded zeros are counted, 8474so <code>"a\000bc\000"</code> has length 5. 8475 8476 8477 8478 8479<p> 8480<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> 8481Receives a string and returns a copy of this string with all 8482uppercase letters changed to lowercase. 8483All other characters are left unchanged. 8484The definition of what an uppercase letter is depends on the current locale. 8485 8486 8487 8488 8489<p> 8490<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> 8491Looks for the first <em>match</em> of 8492<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 8493If it finds one, then <code>match</code> returns 8494the captures from the pattern; 8495otherwise it returns <b>nil</b>. 8496If <code>pattern</code> specifies no captures, 8497then the whole match is returned. 8498A third, optional numeric argument <code>init</code> specifies 8499where to start the search; 8500its default value is 1 and can be negative. 8501 8502 8503 8504 8505<p> 8506<hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, ···)</code></a></h3> 8507 8508 8509<p> 8510Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc. 8511packed (that is, serialized in binary form) 8512according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 8513 8514 8515 8516 8517<p> 8518<hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3> 8519 8520 8521<p> 8522Returns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a> 8523with the given format. 8524The format string cannot have the variable-length options 8525'<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">§6.4.2</a>). 8526 8527 8528 8529 8530<p> 8531<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3> 8532Returns a string that is the concatenation of <code>n</code> copies of 8533the string <code>s</code> separated by the string <code>sep</code>. 8534The default value for <code>sep</code> is the empty string 8535(that is, no separator). 8536Returns the empty string if <code>n</code> is not positive. 8537 8538 8539<p> 8540(Note that it is very easy to exhaust the memory of your machine 8541with a single call to this function.) 8542 8543 8544 8545 8546<p> 8547<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> 8548Returns a string that is the string <code>s</code> reversed. 8549 8550 8551 8552 8553<p> 8554<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> 8555Returns the substring of <code>s</code> that 8556starts at <code>i</code> and continues until <code>j</code>; 8557<code>i</code> and <code>j</code> can be negative. 8558If <code>j</code> is absent, then it is assumed to be equal to -1 8559(which is the same as the string length). 8560In particular, 8561the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 8562with length <code>j</code>, 8563and <code>string.sub(s, -i)</code> (for a positive <code>i</code>) 8564returns a suffix of <code>s</code> 8565with length <code>i</code>. 8566 8567 8568<p> 8569If, after the translation of negative indices, 8570<code>i</code> is less than 1, 8571it is corrected to 1. 8572If <code>j</code> is greater than the string length, 8573it is corrected to that length. 8574If, after these corrections, 8575<code>i</code> is greater than <code>j</code>, 8576the function returns the empty string. 8577 8578 8579 8580 8581<p> 8582<hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3> 8583 8584 8585<p> 8586Returns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>) 8587according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 8588An optional <code>pos</code> marks where 8589to start reading in <code>s</code> (default is 1). 8590After the read values, 8591this function also returns the index of the first unread byte in <code>s</code>. 8592 8593 8594 8595 8596<p> 8597<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> 8598Receives a string and returns a copy of this string with all 8599lowercase letters changed to uppercase. 8600All other characters are left unchanged. 8601The definition of what a lowercase letter is depends on the current locale. 8602 8603 8604 8605 8606 8607<h3>6.4.1 – <a name="6.4.1">Patterns</a></h3> 8608 8609<p> 8610Patterns in Lua are described by regular strings, 8611which are interpreted as patterns by the pattern-matching functions 8612<a href="#pdf-string.find"><code>string.find</code></a>, 8613<a href="#pdf-string.gmatch"><code>string.gmatch</code></a>, 8614<a href="#pdf-string.gsub"><code>string.gsub</code></a>, 8615and <a href="#pdf-string.match"><code>string.match</code></a>. 8616This section describes the syntax and the meaning 8617(that is, what they match) of these strings. 8618 8619 8620 8621<h4>Character Class:</h4><p> 8622A <em>character class</em> is used to represent a set of characters. 8623The following combinations are allowed in describing a character class: 8624 8625<ul> 8626 8627<li><b><em>x</em>: </b> 8628(where <em>x</em> is not one of the <em>magic characters</em> 8629<code>^$()%.[]*+-?</code>) 8630represents the character <em>x</em> itself. 8631</li> 8632 8633<li><b><code>.</code>: </b> (a dot) represents all characters.</li> 8634 8635<li><b><code>%a</code>: </b> represents all letters.</li> 8636 8637<li><b><code>%c</code>: </b> represents all control characters.</li> 8638 8639<li><b><code>%d</code>: </b> represents all digits.</li> 8640 8641<li><b><code>%g</code>: </b> represents all printable characters except space.</li> 8642 8643<li><b><code>%l</code>: </b> represents all lowercase letters.</li> 8644 8645<li><b><code>%p</code>: </b> represents all punctuation characters.</li> 8646 8647<li><b><code>%s</code>: </b> represents all space characters.</li> 8648 8649<li><b><code>%u</code>: </b> represents all uppercase letters.</li> 8650 8651<li><b><code>%w</code>: </b> represents all alphanumeric characters.</li> 8652 8653<li><b><code>%x</code>: </b> represents all hexadecimal digits.</li> 8654 8655<li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character) 8656represents the character <em>x</em>. 8657This is the standard way to escape the magic characters. 8658Any non-alphanumeric character 8659(including all punctuation characters, even the non-magical) 8660can be preceded by a '<code>%</code>' 8661when used to represent itself in a pattern. 8662</li> 8663 8664<li><b><code>[<em>set</em>]</code>: </b> 8665represents the class which is the union of all 8666characters in <em>set</em>. 8667A range of characters can be specified by 8668separating the end characters of the range, 8669in ascending order, with a '<code>-</code>'. 8670All classes <code>%</code><em>x</em> described above can also be used as 8671components in <em>set</em>. 8672All other characters in <em>set</em> represent themselves. 8673For example, <code>[%w_]</code> (or <code>[_%w]</code>) 8674represents all alphanumeric characters plus the underscore, 8675<code>[0-7]</code> represents the octal digits, 8676and <code>[0-7%l%-]</code> represents the octal digits plus 8677the lowercase letters plus the '<code>-</code>' character. 8678 8679 8680<p> 8681You can put a closing square bracket in a set 8682by positioning it as the first character in the set. 8683You can put an hyphen in a set 8684by positioning it as the first or the last character in the set. 8685(You can also use an escape for both cases.) 8686 8687 8688<p> 8689The interaction between ranges and classes is not defined. 8690Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> 8691have no meaning. 8692</li> 8693 8694<li><b><code>[^<em>set</em>]</code>: </b> 8695represents the complement of <em>set</em>, 8696where <em>set</em> is interpreted as above. 8697</li> 8698 8699</ul><p> 8700For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), 8701the corresponding uppercase letter represents the complement of the class. 8702For instance, <code>%S</code> represents all non-space characters. 8703 8704 8705<p> 8706The definitions of letter, space, and other character groups 8707depend on the current locale. 8708In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. 8709 8710 8711 8712 8713 8714<h4>Pattern Item:</h4><p> 8715A <em>pattern item</em> can be 8716 8717<ul> 8718 8719<li> 8720a single character class, 8721which matches any single character in the class; 8722</li> 8723 8724<li> 8725a single character class followed by '<code>*</code>', 8726which matches zero or more repetitions of characters in the class. 8727These repetition items will always match the longest possible sequence; 8728</li> 8729 8730<li> 8731a single character class followed by '<code>+</code>', 8732which matches one or more repetitions of characters in the class. 8733These repetition items will always match the longest possible sequence; 8734</li> 8735 8736<li> 8737a single character class followed by '<code>-</code>', 8738which also matches zero or more repetitions of characters in the class. 8739Unlike '<code>*</code>', 8740these repetition items will always match the shortest possible sequence; 8741</li> 8742 8743<li> 8744a single character class followed by '<code>?</code>', 8745which matches zero or one occurrence of a character in the class. 8746It always matches one occurrence if possible; 8747</li> 8748 8749<li> 8750<code>%<em>n</em></code>, for <em>n</em> between 1 and 9; 8751such item matches a substring equal to the <em>n</em>-th captured string 8752(see below); 8753</li> 8754 8755<li> 8756<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; 8757such item matches strings that start with <em>x</em>, end with <em>y</em>, 8758and where the <em>x</em> and <em>y</em> are <em>balanced</em>. 8759This means that, if one reads the string from left to right, 8760counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, 8761the ending <em>y</em> is the first <em>y</em> where the count reaches 0. 8762For instance, the item <code>%b()</code> matches expressions with 8763balanced parentheses. 8764</li> 8765 8766<li> 8767<code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>; 8768such item matches an empty string at any position such that 8769the next character belongs to <em>set</em> 8770and the previous character does not belong to <em>set</em>. 8771The set <em>set</em> is interpreted as previously described. 8772The beginning and the end of the subject are handled as if 8773they were the character '<code>\0</code>'. 8774</li> 8775 8776</ul> 8777 8778 8779 8780 8781<h4>Pattern:</h4><p> 8782A <em>pattern</em> is a sequence of pattern items. 8783A caret '<code>^</code>' at the beginning of a pattern anchors the match at the 8784beginning of the subject string. 8785A '<code>$</code>' at the end of a pattern anchors the match at the 8786end of the subject string. 8787At other positions, 8788'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. 8789 8790 8791 8792 8793 8794<h4>Captures:</h4><p> 8795A pattern can contain sub-patterns enclosed in parentheses; 8796they describe <em>captures</em>. 8797When a match succeeds, the substrings of the subject string 8798that match captures are stored (<em>captured</em>) for future use. 8799Captures are numbered according to their left parentheses. 8800For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, 8801the part of the string matching <code>"a*(.)%w(%s*)"</code> is 8802stored as the first capture (and therefore has number 1); 8803the character matching "<code>.</code>" is captured with number 2, 8804and the part matching "<code>%s*</code>" has number 3. 8805 8806 8807<p> 8808As a special case, the empty capture <code>()</code> captures 8809the current string position (a number). 8810For instance, if we apply the pattern <code>"()aa()"</code> on the 8811string <code>"flaaap"</code>, there will be two captures: 3 and 5. 8812 8813 8814 8815 8816 8817 8818 8819<h3>6.4.2 – <a name="6.4.2">Format Strings for Pack and Unpack</a></h3> 8820 8821<p> 8822The first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>, 8823<a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a> 8824is a format string, 8825which describes the layout of the structure being created or read. 8826 8827 8828<p> 8829A format string is a sequence of conversion options. 8830The conversion options are as follows: 8831 8832<ul> 8833<li><b><code><</code>: </b>sets little endian</li> 8834<li><b><code>></code>: </b>sets big endian</li> 8835<li><b><code>=</code>: </b>sets native endian</li> 8836<li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code> 8837(default is native alignment)</li> 8838<li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li> 8839<li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li> 8840<li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li> 8841<li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li> 8842<li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li> 8843<li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li> 8844<li><b><code>j</code>: </b>a <code>lua_Integer</code></li> 8845<li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li> 8846<li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li> 8847<li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes 8848(default is native size)</li> 8849<li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes 8850(default is native size)</li> 8851<li><b><code>f</code>: </b>a <code>float</code> (native size)</li> 8852<li><b><code>d</code>: </b>a <code>double</code> (native size)</li> 8853<li><b><code>n</code>: </b>a <code>lua_Number</code></li> 8854<li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li> 8855<li><b><code>z</code>: </b>a zero-terminated string</li> 8856<li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length 8857coded as an unsigned integer with <code>n</code> bytes 8858(default is a <code>size_t</code>)</li> 8859<li><b><code>x</code>: </b>one byte of padding</li> 8860<li><b><code>X<em>op</em></code>: </b>an empty item that aligns 8861according to option <code>op</code> 8862(which is otherwise ignored)</li> 8863<li><b>'<code> </code>': </b>(empty space) ignored</li> 8864</ul><p> 8865(A "<code>[<em>n</em>]</code>" means an optional integral numeral.) 8866Except for padding, spaces, and configurations 8867(options "<code>xX <=>!</code>"), 8868each option corresponds to an argument (in <a href="#pdf-string.pack"><code>string.pack</code></a>) 8869or a result (in <a href="#pdf-string.unpack"><code>string.unpack</code></a>). 8870 8871 8872<p> 8873For 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>", 8874<code>n</code> can be any integer between 1 and 16. 8875All integral options check overflows; 8876<a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size; 8877<a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer. 8878 8879 8880<p> 8881Any format string starts as if prefixed by "<code>!1=</code>", 8882that is, 8883with maximum alignment of 1 (no alignment) 8884and native endianness. 8885 8886 8887<p> 8888Alignment works as follows: 8889For each option, 8890the format gets extra padding until the data starts 8891at an offset that is a multiple of the minimum between the 8892option size and the maximum alignment; 8893this minimum must be a power of 2. 8894Options "<code>c</code>" and "<code>z</code>" are not aligned; 8895option "<code>s</code>" follows the alignment of its starting integer. 8896 8897 8898<p> 8899All padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a> 8900(and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>). 8901 8902 8903 8904 8905 8906 8907 8908<h2>6.5 – <a name="6.5">UTF-8 Support</a></h2> 8909 8910<p> 8911This library provides basic support for UTF-8 encoding. 8912It provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>. 8913This library does not provide any support for Unicode other 8914than the handling of the encoding. 8915Any operation that needs the meaning of a character, 8916such as character classification, is outside its scope. 8917 8918 8919<p> 8920Unless stated otherwise, 8921all functions that expect a byte position as a parameter 8922assume that the given position is either the start of a byte sequence 8923or one plus the length of the subject string. 8924As in the string library, 8925negative indices count from the end of the string. 8926 8927 8928<p> 8929<hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3> 8930Receives zero or more integers, 8931converts each one to its corresponding UTF-8 byte sequence 8932and returns a string with the concatenation of all these sequences. 8933 8934 8935 8936 8937<p> 8938<hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3> 8939The pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>" 8940(see <a href="#6.4.1">§6.4.1</a>), 8941which matches exactly one UTF-8 byte sequence, 8942assuming that the subject is a valid UTF-8 string. 8943 8944 8945 8946 8947<p> 8948<hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3> 8949 8950 8951<p> 8952Returns values so that the construction 8953 8954<pre> 8955 for p, c in utf8.codes(s) do <em>body</em> end 8956</pre><p> 8957will iterate over all characters in string <code>s</code>, 8958with <code>p</code> being the position (in bytes) and <code>c</code> the code point 8959of each character. 8960It raises an error if it meets any invalid byte sequence. 8961 8962 8963 8964 8965<p> 8966<hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3> 8967Returns the codepoints (as integers) from all characters in <code>s</code> 8968that start between byte position <code>i</code> and <code>j</code> (both included). 8969The default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>. 8970It raises an error if it meets any invalid byte sequence. 8971 8972 8973 8974 8975<p> 8976<hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j]])</code></a></h3> 8977Returns the number of UTF-8 characters in string <code>s</code> 8978that start between positions <code>i</code> and <code>j</code> (both inclusive). 8979The default for <code>i</code> is 1 and for <code>j</code> is -1. 8980If it finds any invalid byte sequence, 8981returns a false value plus the position of the first invalid byte. 8982 8983 8984 8985 8986<p> 8987<hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3> 8988Returns the position (in bytes) where the encoding of the 8989<code>n</code>-th character of <code>s</code> 8990(counting from position <code>i</code>) starts. 8991A negative <code>n</code> gets characters before position <code>i</code>. 8992The default for <code>i</code> is 1 when <code>n</code> is non-negative 8993and <code>#s + 1</code> otherwise, 8994so that <code>utf8.offset(s, -n)</code> gets the offset of the 8995<code>n</code>-th character from the end of the string. 8996If the specified character is neither in the subject 8997nor right after its end, 8998the function returns <b>nil</b>. 8999 9000 9001<p> 9002As a special case, 9003when <code>n</code> is 0 the function returns the start of the encoding 9004of the character that contains the <code>i</code>-th byte of <code>s</code>. 9005 9006 9007<p> 9008This function assumes that <code>s</code> is a valid UTF-8 string. 9009 9010 9011 9012 9013 9014 9015 9016<h2>6.6 – <a name="6.6">Table Manipulation</a></h2> 9017 9018<p> 9019This library provides generic functions for table manipulation. 9020It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. 9021 9022 9023<p> 9024Remember that, whenever an operation needs the length of a table, 9025all caveats about the length operator apply (see <a href="#3.4.7">§3.4.7</a>). 9026All functions ignore non-numeric keys 9027in the tables given as arguments. 9028 9029 9030<p> 9031<hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3> 9032 9033 9034<p> 9035Given a list where all elements are strings or numbers, 9036returns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>. 9037The default value for <code>sep</code> is the empty string, 9038the default for <code>i</code> is 1, 9039and the default for <code>j</code> is <code>#list</code>. 9040If <code>i</code> is greater than <code>j</code>, returns the empty string. 9041 9042 9043 9044 9045<p> 9046<hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3> 9047 9048 9049<p> 9050Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>, 9051shifting up the elements 9052<code>list[pos], list[pos+1], ···, list[#list]</code>. 9053The default value for <code>pos</code> is <code>#list+1</code>, 9054so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end 9055of list <code>t</code>. 9056 9057 9058 9059 9060<p> 9061<hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3> 9062 9063 9064<p> 9065Moves elements from table <code>a1</code> to table <code>a2</code>, 9066performing the equivalent to the following 9067multiple assignment: 9068<code>a2[t],··· = a1[f],···,a1[e]</code>. 9069The default for <code>a2</code> is <code>a1</code>. 9070The destination range can overlap with the source range. 9071The number of elements to be moved must fit in a Lua integer. 9072 9073 9074<p> 9075Returns the destination table <code>a2</code>. 9076 9077 9078 9079 9080<p> 9081<hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3> 9082 9083 9084<p> 9085Returns a new table with all parameters stored into keys 1, 2, etc. 9086and with a field "<code>n</code>" with the total number of parameters. 9087Note that the resulting table may not be a sequence. 9088 9089 9090 9091 9092<p> 9093<hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3> 9094 9095 9096<p> 9097Removes from <code>list</code> the element at position <code>pos</code>, 9098returning the value of the removed element. 9099When <code>pos</code> is an integer between 1 and <code>#list</code>, 9100it shifts down the elements 9101<code>list[pos+1], list[pos+2], ···, list[#list]</code> 9102and erases element <code>list[#list]</code>; 9103The index <code>pos</code> can also be 0 when <code>#list</code> is 0, 9104or <code>#list + 1</code>; 9105in those cases, the function erases the element <code>list[pos]</code>. 9106 9107 9108<p> 9109The default value for <code>pos</code> is <code>#list</code>, 9110so that a call <code>table.remove(l)</code> removes the last element 9111of list <code>l</code>. 9112 9113 9114 9115 9116<p> 9117<hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3> 9118 9119 9120<p> 9121Sorts list elements in a given order, <em>in-place</em>, 9122from <code>list[1]</code> to <code>list[#list]</code>. 9123If <code>comp</code> is given, 9124then it must be a function that receives two list elements 9125and returns true when the first element must come 9126before the second in the final order 9127(so that, after the sort, 9128<code>i < j</code> implies <code>not comp(list[j],list[i])</code>). 9129If <code>comp</code> is not given, 9130then the standard Lua operator <code><</code> is used instead. 9131 9132 9133<p> 9134Note that the <code>comp</code> function must define 9135a strict partial order over the elements in the list; 9136that is, it must be asymmetric and transitive. 9137Otherwise, no valid sort may be possible. 9138 9139 9140<p> 9141The sort algorithm is not stable: 9142elements considered equal by the given order 9143may have their relative positions changed by the sort. 9144 9145 9146 9147 9148<p> 9149<hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3> 9150 9151 9152<p> 9153Returns the elements from the given list. 9154This function is equivalent to 9155 9156<pre> 9157 return list[i], list[i+1], ···, list[j] 9158</pre><p> 9159By default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>. 9160 9161 9162 9163 9164 9165 9166 9167<h2>6.7 – <a name="6.7">Mathematical Functions</a></h2> 9168 9169<p> 9170This library provides basic mathematical functions. 9171It provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>. 9172Functions with the annotation "<code>integer/float</code>" give 9173integer results for integer arguments 9174and float results for float (or mixed) arguments. 9175Rounding functions 9176(<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>) 9177return an integer when the result fits in the range of an integer, 9178or a float otherwise. 9179 9180 9181<p> 9182<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> 9183 9184 9185<p> 9186Returns the absolute value of <code>x</code>. (integer/float) 9187 9188 9189 9190 9191<p> 9192<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> 9193 9194 9195<p> 9196Returns the arc cosine of <code>x</code> (in radians). 9197 9198 9199 9200 9201<p> 9202<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> 9203 9204 9205<p> 9206Returns the arc sine of <code>x</code> (in radians). 9207 9208 9209 9210 9211<p> 9212<hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3> 9213 9214 9215<p> 9216 9217Returns the arc tangent of <code>y/x</code> (in radians), 9218but uses the signs of both parameters to find the 9219quadrant of the result. 9220(It also handles correctly the case of <code>x</code> being zero.) 9221 9222 9223<p> 9224The default value for <code>x</code> is 1, 9225so that the call <code>math.atan(y)</code> 9226returns the arc tangent of <code>y</code>. 9227 9228 9229 9230 9231<p> 9232<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> 9233 9234 9235<p> 9236Returns the smallest integral value larger than or equal to <code>x</code>. 9237 9238 9239 9240 9241<p> 9242<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> 9243 9244 9245<p> 9246Returns the cosine of <code>x</code> (assumed to be in radians). 9247 9248 9249 9250 9251<p> 9252<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> 9253 9254 9255<p> 9256Converts the angle <code>x</code> from radians to degrees. 9257 9258 9259 9260 9261<p> 9262<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> 9263 9264 9265<p> 9266Returns the value <em>e<sup>x</sup></em> 9267(where <code>e</code> is the base of natural logarithms). 9268 9269 9270 9271 9272<p> 9273<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> 9274 9275 9276<p> 9277Returns the largest integral value smaller than or equal to <code>x</code>. 9278 9279 9280 9281 9282<p> 9283<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> 9284 9285 9286<p> 9287Returns the remainder of the division of <code>x</code> by <code>y</code> 9288that rounds the quotient towards zero. (integer/float) 9289 9290 9291 9292 9293<p> 9294<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> 9295 9296 9297<p> 9298The float value <code>HUGE_VAL</code>, 9299a value larger than any other numeric value. 9300 9301 9302 9303 9304<p> 9305<hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3> 9306 9307 9308<p> 9309Returns the logarithm of <code>x</code> in the given base. 9310The default for <code>base</code> is <em>e</em> 9311(so that the function returns the natural logarithm of <code>x</code>). 9312 9313 9314 9315 9316<p> 9317<hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> 9318 9319 9320<p> 9321Returns the argument with the maximum value, 9322according to the Lua operator <code><</code>. (integer/float) 9323 9324 9325 9326 9327<p> 9328<hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3> 9329An integer with the maximum value for an integer. 9330 9331 9332 9333 9334<p> 9335<hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> 9336 9337 9338<p> 9339Returns the argument with the minimum value, 9340according to the Lua operator <code><</code>. (integer/float) 9341 9342 9343 9344 9345<p> 9346<hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3> 9347An integer with the minimum value for an integer. 9348 9349 9350 9351 9352<p> 9353<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> 9354 9355 9356<p> 9357Returns the integral part of <code>x</code> and the fractional part of <code>x</code>. 9358Its second result is always a float. 9359 9360 9361 9362 9363<p> 9364<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> 9365 9366 9367<p> 9368The value of <em>π</em>. 9369 9370 9371 9372 9373<p> 9374<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> 9375 9376 9377<p> 9378Converts the angle <code>x</code> from degrees to radians. 9379 9380 9381 9382 9383<p> 9384<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> 9385 9386 9387<p> 9388When called without arguments, 9389returns a pseudo-random float with uniform distribution 9390in the range <em>[0,1)</em>. 9391When called with two integers <code>m</code> and <code>n</code>, 9392<code>math.random</code> returns a pseudo-random integer 9393with uniform distribution in the range <em>[m, n]</em>. 9394(The value <em>n-m</em> cannot be negative and must fit in a Lua integer.) 9395The call <code>math.random(n)</code> is equivalent to <code>math.random(1,n)</code>. 9396 9397 9398<p> 9399This function is an interface to the underling 9400pseudo-random generator function provided by C. 9401 9402 9403 9404 9405<p> 9406<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3> 9407 9408 9409<p> 9410Sets <code>x</code> as the "seed" 9411for the pseudo-random generator: 9412equal seeds produce equal sequences of numbers. 9413 9414 9415 9416 9417<p> 9418<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> 9419 9420 9421<p> 9422Returns the sine of <code>x</code> (assumed to be in radians). 9423 9424 9425 9426 9427<p> 9428<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> 9429 9430 9431<p> 9432Returns the square root of <code>x</code>. 9433(You can also use the expression <code>x^0.5</code> to compute this value.) 9434 9435 9436 9437 9438<p> 9439<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> 9440 9441 9442<p> 9443Returns the tangent of <code>x</code> (assumed to be in radians). 9444 9445 9446 9447 9448<p> 9449<hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3> 9450 9451 9452<p> 9453If the value <code>x</code> is convertible to an integer, 9454returns that integer. 9455Otherwise, returns <b>nil</b>. 9456 9457 9458 9459 9460<p> 9461<hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3> 9462 9463 9464<p> 9465Returns "<code>integer</code>" if <code>x</code> is an integer, 9466"<code>float</code>" if it is a float, 9467or <b>nil</b> if <code>x</code> is not a number. 9468 9469 9470 9471 9472<p> 9473<hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3> 9474 9475 9476<p> 9477Returns a boolean, 9478true if and only if integer <code>m</code> is below integer <code>n</code> when 9479they are compared as unsigned integers. 9480 9481 9482 9483 9484 9485 9486 9487<h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2> 9488 9489<p> 9490The I/O library provides two different styles for file manipulation. 9491The first one uses implicit file handles; 9492that is, there are operations to set a default input file and a 9493default output file, 9494and all input/output operations are over these default files. 9495The second style uses explicit file handles. 9496 9497 9498<p> 9499When using implicit file handles, 9500all operations are supplied by table <a name="pdf-io"><code>io</code></a>. 9501When using explicit file handles, 9502the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle 9503and then all operations are supplied as methods of the file handle. 9504 9505 9506<p> 9507The table <code>io</code> also provides 9508three predefined file handles with their usual meanings from C: 9509<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>. 9510The I/O library never closes these files. 9511 9512 9513<p> 9514Unless otherwise stated, 9515all I/O functions return <b>nil</b> on failure 9516(plus an error message as a second result and 9517a system-dependent error code as a third result) 9518and some value different from <b>nil</b> on success. 9519On non-POSIX systems, 9520the computation of the error message and error code 9521in case of errors 9522may be not thread safe, 9523because they rely on the global C variable <code>errno</code>. 9524 9525 9526<p> 9527<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> 9528 9529 9530<p> 9531Equivalent to <code>file:close()</code>. 9532Without a <code>file</code>, closes the default output file. 9533 9534 9535 9536 9537<p> 9538<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> 9539 9540 9541<p> 9542Equivalent to <code>io.output():flush()</code>. 9543 9544 9545 9546 9547<p> 9548<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> 9549 9550 9551<p> 9552When called with a file name, it opens the named file (in text mode), 9553and sets its handle as the default input file. 9554When called with a file handle, 9555it simply sets this file handle as the default input file. 9556When called without parameters, 9557it returns the current default input file. 9558 9559 9560<p> 9561In case of errors this function raises the error, 9562instead of returning an error code. 9563 9564 9565 9566 9567<p> 9568<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, ···])</code></a></h3> 9569 9570 9571<p> 9572Opens the given file name in read mode 9573and returns an iterator function that 9574works like <code>file:lines(···)</code> over the opened file. 9575When the iterator function detects the end of file, 9576it returns no values (to finish the loop) and automatically closes the file. 9577 9578 9579<p> 9580The call <code>io.lines()</code> (with no file name) is equivalent 9581to <code>io.input():lines("*l")</code>; 9582that is, it iterates over the lines of the default input file. 9583In this case it does not close the file when the loop ends. 9584 9585 9586<p> 9587In case of errors this function raises the error, 9588instead of returning an error code. 9589 9590 9591 9592 9593<p> 9594<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> 9595 9596 9597<p> 9598This function opens a file, 9599in the mode specified in the string <code>mode</code>. 9600In case of success, 9601it returns a new file handle. 9602 9603 9604<p> 9605The <code>mode</code> string can be any of the following: 9606 9607<ul> 9608<li><b>"<code>r</code>": </b> read mode (the default);</li> 9609<li><b>"<code>w</code>": </b> write mode;</li> 9610<li><b>"<code>a</code>": </b> append mode;</li> 9611<li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li> 9612<li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li> 9613<li><b>"<code>a+</code>": </b> append update mode, previous data is preserved, 9614 writing is only allowed at the end of file.</li> 9615</ul><p> 9616The <code>mode</code> string can also have a '<code>b</code>' at the end, 9617which is needed in some systems to open the file in binary mode. 9618 9619 9620 9621 9622<p> 9623<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> 9624 9625 9626<p> 9627Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. 9628 9629 9630 9631 9632<p> 9633<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> 9634 9635 9636<p> 9637This function is system dependent and is not available 9638on all platforms. 9639 9640 9641<p> 9642Starts program <code>prog</code> in a separated process and returns 9643a file handle that you can use to read data from this program 9644(if <code>mode</code> is <code>"r"</code>, the default) 9645or to write data to this program 9646(if <code>mode</code> is <code>"w"</code>). 9647 9648 9649 9650 9651<p> 9652<hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> 9653 9654 9655<p> 9656Equivalent to <code>io.input():read(···)</code>. 9657 9658 9659 9660 9661<p> 9662<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> 9663 9664 9665<p> 9666In case of success, 9667returns a handle for a temporary file. 9668This file is opened in update mode 9669and it is automatically removed when the program ends. 9670 9671 9672 9673 9674<p> 9675<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> 9676 9677 9678<p> 9679Checks whether <code>obj</code> is a valid file handle. 9680Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, 9681<code>"closed file"</code> if <code>obj</code> is a closed file handle, 9682or <b>nil</b> if <code>obj</code> is not a file handle. 9683 9684 9685 9686 9687<p> 9688<hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> 9689 9690 9691<p> 9692Equivalent to <code>io.output():write(···)</code>. 9693 9694 9695 9696 9697<p> 9698<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> 9699 9700 9701<p> 9702Closes <code>file</code>. 9703Note that files are automatically closed when 9704their handles are garbage collected, 9705but that takes an unpredictable amount of time to happen. 9706 9707 9708<p> 9709When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>, 9710<a href="#pdf-file:close"><code>file:close</code></a> returns the same values 9711returned by <a href="#pdf-os.execute"><code>os.execute</code></a>. 9712 9713 9714 9715 9716<p> 9717<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> 9718 9719 9720<p> 9721Saves any written data to <code>file</code>. 9722 9723 9724 9725 9726<p> 9727<hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3> 9728 9729 9730<p> 9731Returns an iterator function that, 9732each time it is called, 9733reads the file according to the given formats. 9734When no format is given, 9735uses "<code>l</code>" as a default. 9736As an example, the construction 9737 9738<pre> 9739 for c in file:lines(1) do <em>body</em> end 9740</pre><p> 9741will iterate over all characters of the file, 9742starting at the current position. 9743Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file 9744when the loop ends. 9745 9746 9747<p> 9748In case of errors this function raises the error, 9749instead of returning an error code. 9750 9751 9752 9753 9754<p> 9755<hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> 9756 9757 9758<p> 9759Reads the file <code>file</code>, 9760according to the given formats, which specify what to read. 9761For each format, 9762the function returns a string or a number with the characters read, 9763or <b>nil</b> if it cannot read data with the specified format. 9764(In this latter case, 9765the function does not read subsequent formats.) 9766When called without formats, 9767it uses a default format that reads the next line 9768(see below). 9769 9770 9771<p> 9772The available formats are 9773 9774<ul> 9775 9776<li><b>"<code>n</code>": </b> 9777reads a numeral and returns it as a float or an integer, 9778following the lexical conventions of Lua. 9779(The numeral may have leading spaces and a sign.) 9780This format always reads the longest input sequence that 9781is a valid prefix for a numeral; 9782if that prefix does not form a valid numeral 9783(e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"), 9784it is discarded and the function returns <b>nil</b>. 9785</li> 9786 9787<li><b>"<code>a</code>": </b> 9788reads the whole file, starting at the current position. 9789On end of file, it returns the empty string. 9790</li> 9791 9792<li><b>"<code>l</code>": </b> 9793reads the next line skipping the end of line, 9794returning <b>nil</b> on end of file. 9795This is the default format. 9796</li> 9797 9798<li><b>"<code>L</code>": </b> 9799reads the next line keeping the end-of-line character (if present), 9800returning <b>nil</b> on end of file. 9801</li> 9802 9803<li><b><em>number</em>: </b> 9804reads a string with up to this number of bytes, 9805returning <b>nil</b> on end of file. 9806If <code>number</code> is zero, 9807it reads nothing and returns an empty string, 9808or <b>nil</b> on end of file. 9809</li> 9810 9811</ul><p> 9812The formats "<code>l</code>" and "<code>L</code>" should be used only for text files. 9813 9814 9815 9816 9817<p> 9818<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3> 9819 9820 9821<p> 9822Sets and gets the file position, 9823measured from the beginning of the file, 9824to the position given by <code>offset</code> plus a base 9825specified by the string <code>whence</code>, as follows: 9826 9827<ul> 9828<li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li> 9829<li><b>"<code>cur</code>": </b> base is current position;</li> 9830<li><b>"<code>end</code>": </b> base is end of file;</li> 9831</ul><p> 9832In case of success, <code>seek</code> returns the final file position, 9833measured in bytes from the beginning of the file. 9834If <code>seek</code> fails, it returns <b>nil</b>, 9835plus a string describing the error. 9836 9837 9838<p> 9839The default value for <code>whence</code> is <code>"cur"</code>, 9840and for <code>offset</code> is 0. 9841Therefore, the call <code>file:seek()</code> returns the current 9842file position, without changing it; 9843the call <code>file:seek("set")</code> sets the position to the 9844beginning of the file (and returns 0); 9845and the call <code>file:seek("end")</code> sets the position to the 9846end of the file, and returns its size. 9847 9848 9849 9850 9851<p> 9852<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> 9853 9854 9855<p> 9856Sets the buffering mode for an output file. 9857There are three available modes: 9858 9859<ul> 9860 9861<li><b>"<code>no</code>": </b> 9862no buffering; the result of any output operation appears immediately. 9863</li> 9864 9865<li><b>"<code>full</code>": </b> 9866full buffering; output operation is performed only 9867when the buffer is full or when 9868you explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>). 9869</li> 9870 9871<li><b>"<code>line</code>": </b> 9872line buffering; output is buffered until a newline is output 9873or there is any input from some special files 9874(such as a terminal device). 9875</li> 9876 9877</ul><p> 9878For the last two cases, <code>size</code> 9879specifies the size of the buffer, in bytes. 9880The default is an appropriate size. 9881 9882 9883 9884 9885<p> 9886<hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> 9887 9888 9889<p> 9890Writes the value of each of its arguments to <code>file</code>. 9891The arguments must be strings or numbers. 9892 9893 9894<p> 9895In case of success, this function returns <code>file</code>. 9896Otherwise it returns <b>nil</b> plus a string describing the error. 9897 9898 9899 9900 9901 9902 9903 9904<h2>6.9 – <a name="6.9">Operating System Facilities</a></h2> 9905 9906<p> 9907This library is implemented through table <a name="pdf-os"><code>os</code></a>. 9908 9909 9910<p> 9911<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> 9912 9913 9914<p> 9915Returns an approximation of the amount in seconds of CPU time 9916used by the program. 9917 9918 9919 9920 9921<p> 9922<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> 9923 9924 9925<p> 9926Returns a string or a table containing date and time, 9927formatted according to the given string <code>format</code>. 9928 9929 9930<p> 9931If the <code>time</code> argument is present, 9932this is the time to be formatted 9933(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). 9934Otherwise, <code>date</code> formats the current time. 9935 9936 9937<p> 9938If <code>format</code> starts with '<code>!</code>', 9939then the date is formatted in Coordinated Universal Time. 9940After this optional character, 9941if <code>format</code> is the string "<code>*t</code>", 9942then <code>date</code> returns a table with the following fields: 9943<code>year</code>, <code>month</code> (1–12), <code>day</code> (1–31), 9944<code>hour</code> (0–23), <code>min</code> (0–59), <code>sec</code> (0–61), 9945<code>wday</code> (weekday, 1–7, Sunday is 1), 9946<code>yday</code> (day of the year, 1–366), 9947and <code>isdst</code> (daylight saving flag, a boolean). 9948This last field may be absent 9949if the information is not available. 9950 9951 9952<p> 9953If <code>format</code> is not "<code>*t</code>", 9954then <code>date</code> returns the date as a string, 9955formatted according to the same rules as the ISO C function <code>strftime</code>. 9956 9957 9958<p> 9959When called without arguments, 9960<code>date</code> returns a reasonable date and time representation that depends on 9961the host system and on the current locale. 9962(More specifically, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>.) 9963 9964 9965<p> 9966On non-POSIX systems, 9967this function may be not thread safe 9968because of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>. 9969 9970 9971 9972 9973<p> 9974<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> 9975 9976 9977<p> 9978Returns the difference, in seconds, 9979from time <code>t1</code> to time <code>t2</code> 9980(where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>). 9981In POSIX, Windows, and some other systems, 9982this value is exactly <code>t2</code><em>-</em><code>t1</code>. 9983 9984 9985 9986 9987<p> 9988<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> 9989 9990 9991<p> 9992This function is equivalent to the ISO C function <code>system</code>. 9993It passes <code>command</code> to be executed by an operating system shell. 9994Its first result is <b>true</b> 9995if the command terminated successfully, 9996or <b>nil</b> otherwise. 9997After this first result 9998the function returns a string plus a number, 9999as follows: 10000 10001<ul> 10002 10003<li><b>"<code>exit</code>": </b> 10004the command terminated normally; 10005the following number is the exit status of the command. 10006</li> 10007 10008<li><b>"<code>signal</code>": </b> 10009the command was terminated by a signal; 10010the following number is the signal that terminated the command. 10011</li> 10012 10013</ul> 10014 10015<p> 10016When called without a <code>command</code>, 10017<code>os.execute</code> returns a boolean that is true if a shell is available. 10018 10019 10020 10021 10022<p> 10023<hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3> 10024 10025 10026<p> 10027Calls the ISO C function <code>exit</code> to terminate the host program. 10028If <code>code</code> is <b>true</b>, 10029the returned status is <code>EXIT_SUCCESS</code>; 10030if <code>code</code> is <b>false</b>, 10031the returned status is <code>EXIT_FAILURE</code>; 10032if <code>code</code> is a number, 10033the returned status is this number. 10034The default value for <code>code</code> is <b>true</b>. 10035 10036 10037<p> 10038If the optional second argument <code>close</code> is true, 10039closes the Lua state before exiting. 10040 10041 10042 10043 10044<p> 10045<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> 10046 10047 10048<p> 10049Returns the value of the process environment variable <code>varname</code>, 10050or <b>nil</b> if the variable is not defined. 10051 10052 10053 10054 10055<p> 10056<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> 10057 10058 10059<p> 10060Deletes the file (or empty directory, on POSIX systems) 10061with the given name. 10062If this function fails, it returns <b>nil</b>, 10063plus a string describing the error and the error code. 10064Otherwise, it returns true. 10065 10066 10067 10068 10069<p> 10070<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> 10071 10072 10073<p> 10074Renames the file or directory named <code>oldname</code> to <code>newname</code>. 10075If this function fails, it returns <b>nil</b>, 10076plus a string describing the error and the error code. 10077Otherwise, it returns true. 10078 10079 10080 10081 10082<p> 10083<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> 10084 10085 10086<p> 10087Sets the current locale of the program. 10088<code>locale</code> is a system-dependent string specifying a locale; 10089<code>category</code> is an optional string describing which category to change: 10090<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, 10091<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; 10092the default category is <code>"all"</code>. 10093The function returns the name of the new locale, 10094or <b>nil</b> if the request cannot be honored. 10095 10096 10097<p> 10098If <code>locale</code> is the empty string, 10099the current locale is set to an implementation-defined native locale. 10100If <code>locale</code> is the string "<code>C</code>", 10101the current locale is set to the standard C locale. 10102 10103 10104<p> 10105When called with <b>nil</b> as the first argument, 10106this function only returns the name of the current locale 10107for the given category. 10108 10109 10110<p> 10111This function may be not thread safe 10112because of its reliance on C function <code>setlocale</code>. 10113 10114 10115 10116 10117<p> 10118<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> 10119 10120 10121<p> 10122Returns the current time when called without arguments, 10123or a time representing the local date and time specified by the given table. 10124This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, 10125and may have fields 10126<code>hour</code> (default is 12), 10127<code>min</code> (default is 0), 10128<code>sec</code> (default is 0), 10129and <code>isdst</code> (default is <b>nil</b>). 10130Other fields are ignored. 10131For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function. 10132 10133 10134<p> 10135The values in these fields do not need to be inside their valid ranges. 10136For instance, if <code>sec</code> is -10, 10137it means -10 seconds from the time specified by the other fields; 10138if <code>hour</code> is 1000, 10139it means +1000 hours from the time specified by the other fields. 10140 10141 10142<p> 10143The returned value is a number, whose meaning depends on your system. 10144In POSIX, Windows, and some other systems, 10145this number counts the number 10146of seconds since some given start time (the "epoch"). 10147In other systems, the meaning is not specified, 10148and the number returned by <code>time</code> can be used only as an argument to 10149<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. 10150 10151 10152 10153 10154<p> 10155<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> 10156 10157 10158<p> 10159Returns a string with a file name that can 10160be used for a temporary file. 10161The file must be explicitly opened before its use 10162and explicitly removed when no longer needed. 10163 10164 10165<p> 10166On POSIX systems, 10167this function also creates a file with that name, 10168to avoid security risks. 10169(Someone else might create the file with wrong permissions 10170in the time between getting the name and creating the file.) 10171You still have to open the file to use it 10172and to remove it (even if you do not use it). 10173 10174 10175<p> 10176When possible, 10177you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, 10178which automatically removes the file when the program ends. 10179 10180 10181 10182 10183 10184 10185 10186<h2>6.10 – <a name="6.10">The Debug Library</a></h2> 10187 10188<p> 10189This library provides 10190the functionality of the debug interface (<a href="#4.9">§4.9</a>) to Lua programs. 10191You should exert care when using this library. 10192Several of its functions 10193violate basic assumptions about Lua code 10194(e.g., that variables local to a function 10195cannot be accessed from outside; 10196that userdata metatables cannot be changed by Lua code; 10197that Lua programs do not crash) 10198and therefore can compromise otherwise secure code. 10199Moreover, some functions in this library may be slow. 10200 10201 10202<p> 10203All functions in this library are provided 10204inside the <a name="pdf-debug"><code>debug</code></a> table. 10205All functions that operate over a thread 10206have an optional first argument which is the 10207thread to operate over. 10208The default is always the current thread. 10209 10210 10211<p> 10212<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> 10213 10214 10215<p> 10216Enters an interactive mode with the user, 10217running each string that the user enters. 10218Using simple commands and other debug facilities, 10219the user can inspect global and local variables, 10220change their values, evaluate expressions, and so on. 10221A line containing only the word <code>cont</code> finishes this function, 10222so that the caller continues its execution. 10223 10224 10225<p> 10226Note that commands for <code>debug.debug</code> are not lexically nested 10227within any function and so have no direct access to local variables. 10228 10229 10230 10231 10232<p> 10233<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> 10234 10235 10236<p> 10237Returns the current hook settings of the thread, as three values: 10238the current hook function, the current hook mask, 10239and the current hook count 10240(as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). 10241 10242 10243 10244 10245<p> 10246<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> 10247 10248 10249<p> 10250Returns a table with information about a function. 10251You can give the function directly 10252or you can give a number as the value of <code>f</code>, 10253which means the function running at level <code>f</code> of the call stack 10254of the given thread: 10255level 0 is the current function (<code>getinfo</code> itself); 10256level 1 is the function that called <code>getinfo</code> 10257(except for tail calls, which do not count on the stack); 10258and so on. 10259If <code>f</code> is a number larger than the number of active functions, 10260then <code>getinfo</code> returns <b>nil</b>. 10261 10262 10263<p> 10264The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, 10265with the string <code>what</code> describing which fields to fill in. 10266The default for <code>what</code> is to get all information available, 10267except the table of valid lines. 10268If present, 10269the option '<code>f</code>' 10270adds a field named <code>func</code> with the function itself. 10271If present, 10272the option '<code>L</code>' 10273adds a field named <code>activelines</code> with the table of 10274valid lines. 10275 10276 10277<p> 10278For instance, the expression <code>debug.getinfo(1,"n").name</code> returns 10279a name for the current function, 10280if a reasonable name can be found, 10281and the expression <code>debug.getinfo(print)</code> 10282returns a table with all available information 10283about the <a href="#pdf-print"><code>print</code></a> function. 10284 10285 10286 10287 10288<p> 10289<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3> 10290 10291 10292<p> 10293This function returns the name and the value of the local variable 10294with index <code>local</code> of the function at level <code>f</code> of the stack. 10295This function accesses not only explicit local variables, 10296but also parameters, temporaries, etc. 10297 10298 10299<p> 10300The first parameter or local variable has index 1, and so on, 10301following the order that they are declared in the code, 10302counting only the variables that are active 10303in the current scope of the function. 10304Negative indices refer to vararg parameters; 10305-1 is the first vararg parameter. 10306The function returns <b>nil</b> if there is no variable with the given index, 10307and raises an error when called with a level out of range. 10308(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) 10309 10310 10311<p> 10312Variable names starting with '<code>(</code>' (open parenthesis) 10313represent variables with no known names 10314(internal variables such as loop control variables, 10315and variables from chunks saved without debug information). 10316 10317 10318<p> 10319The parameter <code>f</code> may also be a function. 10320In that case, <code>getlocal</code> returns only the name of function parameters. 10321 10322 10323 10324 10325<p> 10326<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3> 10327 10328 10329<p> 10330Returns the metatable of the given <code>value</code> 10331or <b>nil</b> if it does not have a metatable. 10332 10333 10334 10335 10336<p> 10337<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> 10338 10339 10340<p> 10341Returns the registry table (see <a href="#4.5">§4.5</a>). 10342 10343 10344 10345 10346<p> 10347<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3> 10348 10349 10350<p> 10351This function returns the name and the value of the upvalue 10352with index <code>up</code> of the function <code>f</code>. 10353The function returns <b>nil</b> if there is no upvalue with the given index. 10354 10355 10356<p> 10357Variable names starting with '<code>(</code>' (open parenthesis) 10358represent variables with no known names 10359(variables from chunks saved without debug information). 10360 10361 10362 10363 10364<p> 10365<hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3> 10366 10367 10368<p> 10369Returns the Lua value associated to <code>u</code>. 10370If <code>u</code> is not a full userdata, 10371returns <b>nil</b>. 10372 10373 10374 10375 10376<p> 10377<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> 10378 10379 10380<p> 10381Sets the given function as a hook. 10382The string <code>mask</code> and the number <code>count</code> describe 10383when the hook will be called. 10384The string mask may have any combination of the following characters, 10385with the given meaning: 10386 10387<ul> 10388<li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li> 10389<li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li> 10390<li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li> 10391</ul><p> 10392Moreover, 10393with a <code>count</code> different from zero, 10394the hook is called also after every <code>count</code> instructions. 10395 10396 10397<p> 10398When called without arguments, 10399<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. 10400 10401 10402<p> 10403When the hook is called, its first parameter is a string 10404describing the event that has triggered its call: 10405<code>"call"</code> (or <code>"tail call"</code>), 10406<code>"return"</code>, 10407<code>"line"</code>, and <code>"count"</code>. 10408For line events, 10409the hook also gets the new line number as its second parameter. 10410Inside a hook, 10411you can call <code>getinfo</code> with level 2 to get more information about 10412the running function 10413(level 0 is the <code>getinfo</code> function, 10414and level 1 is the hook function). 10415 10416 10417 10418 10419<p> 10420<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> 10421 10422 10423<p> 10424This function assigns the value <code>value</code> to the local variable 10425with index <code>local</code> of the function at level <code>level</code> of the stack. 10426The function returns <b>nil</b> if there is no local 10427variable with the given index, 10428and raises an error when called with a <code>level</code> out of range. 10429(You can call <code>getinfo</code> to check whether the level is valid.) 10430Otherwise, it returns the name of the local variable. 10431 10432 10433<p> 10434See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about 10435variable indices and names. 10436 10437 10438 10439 10440<p> 10441<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> 10442 10443 10444<p> 10445Sets the metatable for the given <code>value</code> to the given <code>table</code> 10446(which can be <b>nil</b>). 10447Returns <code>value</code>. 10448 10449 10450 10451 10452<p> 10453<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> 10454 10455 10456<p> 10457This function assigns the value <code>value</code> to the upvalue 10458with index <code>up</code> of the function <code>f</code>. 10459The function returns <b>nil</b> if there is no upvalue 10460with the given index. 10461Otherwise, it returns the name of the upvalue. 10462 10463 10464 10465 10466<p> 10467<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3> 10468 10469 10470<p> 10471Sets the given <code>value</code> as 10472the Lua value associated to the given <code>udata</code>. 10473<code>udata</code> must be a full userdata. 10474 10475 10476<p> 10477Returns <code>udata</code>. 10478 10479 10480 10481 10482<p> 10483<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> 10484 10485 10486<p> 10487If <code>message</code> is present but is neither a string nor <b>nil</b>, 10488this function returns <code>message</code> without further processing. 10489Otherwise, 10490it returns a string with a traceback of the call stack. 10491The optional <code>message</code> string is appended 10492at the beginning of the traceback. 10493An optional <code>level</code> number tells at which level 10494to start the traceback 10495(default is 1, the function calling <code>traceback</code>). 10496 10497 10498 10499 10500<p> 10501<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3> 10502 10503 10504<p> 10505Returns a unique identifier (as a light userdata) 10506for the upvalue numbered <code>n</code> 10507from the given function. 10508 10509 10510<p> 10511These unique identifiers allow a program to check whether different 10512closures share upvalues. 10513Lua closures that share an upvalue 10514(that is, that access a same external local variable) 10515will return identical ids for those upvalue indices. 10516 10517 10518 10519 10520<p> 10521<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3> 10522 10523 10524<p> 10525Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code> 10526refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>. 10527 10528 10529 10530 10531 10532 10533 10534<h1>7 – <a name="7">Lua Standalone</a></h1> 10535 10536<p> 10537Although Lua has been designed as an extension language, 10538to be embedded in a host C program, 10539it is also frequently used as a standalone language. 10540An interpreter for Lua as a standalone language, 10541called simply <code>lua</code>, 10542is provided with the standard distribution. 10543The standalone interpreter includes 10544all standard libraries, including the debug library. 10545Its usage is: 10546 10547<pre> 10548 lua [options] [script [args]] 10549</pre><p> 10550The options are: 10551 10552<ul> 10553<li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li> 10554<li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li> 10555<li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li> 10556<li><b><code>-v</code>: </b> prints version information;</li> 10557<li><b><code>-E</code>: </b> ignores environment variables;</li> 10558<li><b><code>--</code>: </b> stops handling options;</li> 10559<li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li> 10560</ul><p> 10561After handling its options, <code>lua</code> runs the given <em>script</em>. 10562When called without arguments, 10563<code>lua</code> behaves as <code>lua -v -i</code> 10564when the standard input (<code>stdin</code>) is a terminal, 10565and as <code>lua -</code> otherwise. 10566 10567 10568<p> 10569When called without option <code>-E</code>, 10570the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a> 10571(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined) 10572before running any argument. 10573If the variable content has the format <code>@<em>filename</em></code>, 10574then <code>lua</code> executes the file. 10575Otherwise, <code>lua</code> executes the string itself. 10576 10577 10578<p> 10579When called with option <code>-E</code>, 10580besides ignoring <code>LUA_INIT</code>, 10581Lua also ignores 10582the values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>, 10583setting the values of 10584<a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a> 10585with the default paths defined in <code>luaconf.h</code>. 10586 10587 10588<p> 10589All options are handled in order, except <code>-i</code> and <code>-E</code>. 10590For instance, an invocation like 10591 10592<pre> 10593 $ lua -e'a=1' -e 'print(a)' script.lua 10594</pre><p> 10595will first set <code>a</code> to 1, then print the value of <code>a</code>, 10596and finally run the file <code>script.lua</code> with no arguments. 10597(Here <code>$</code> is the shell prompt. Your prompt may be different.) 10598 10599 10600<p> 10601Before running any code, 10602<code>lua</code> collects all command-line arguments 10603in a global table called <code>arg</code>. 10604The script name goes to index 0, 10605the first argument after the script name goes to index 1, 10606and so on. 10607Any arguments before the script name 10608(that is, the interpreter name plus its options) 10609go to negative indices. 10610For instance, in the call 10611 10612<pre> 10613 $ lua -la b.lua t1 t2 10614</pre><p> 10615the table is like this: 10616 10617<pre> 10618 arg = { [-2] = "lua", [-1] = "-la", 10619 [0] = "b.lua", 10620 [1] = "t1", [2] = "t2" } 10621</pre><p> 10622If there is no script in the call, 10623the interpreter name goes to index 0, 10624followed by the other arguments. 10625For instance, the call 10626 10627<pre> 10628 $ lua -e "print(arg[1])" 10629</pre><p> 10630will print "<code>-e</code>". 10631If there is a script, 10632the script is called with parameters 10633<code>arg[1]</code>, ···, <code>arg[#arg]</code>. 10634(Like all chunks in Lua, 10635the script is compiled as a vararg function.) 10636 10637 10638<p> 10639In interactive mode, 10640Lua repeatedly prompts and waits for a line. 10641After reading a line, 10642Lua first try to interpret the line as an expression. 10643If it succeeds, it prints its value. 10644Otherwise, it interprets the line as a statement. 10645If you write an incomplete statement, 10646the interpreter waits for its completion 10647by issuing a different prompt. 10648 10649 10650<p> 10651If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, 10652then its value is used as the prompt. 10653Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, 10654its value is used as the secondary prompt 10655(issued during incomplete statements). 10656 10657 10658<p> 10659In case of unprotected errors in the script, 10660the interpreter reports the error to the standard error stream. 10661If the error object is not a string but 10662has a metamethod <code>__tostring</code>, 10663the interpreter calls this metamethod to produce the final message. 10664Otherwise, the interpreter converts the error object to a string 10665and adds a stack traceback to it. 10666 10667 10668<p> 10669When finishing normally, 10670the interpreter closes its main Lua state 10671(see <a href="#lua_close"><code>lua_close</code></a>). 10672The script can avoid this step by 10673calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate. 10674 10675 10676<p> 10677To allow the use of Lua as a 10678script interpreter in Unix systems, 10679the standalone interpreter skips 10680the first line of a chunk if it starts with <code>#</code>. 10681Therefore, Lua scripts can be made into executable programs 10682by using <code>chmod +x</code> and the <code>#!</code> form, 10683as in 10684 10685<pre> 10686 #!/usr/local/bin/lua 10687</pre><p> 10688(Of course, 10689the location of the Lua interpreter may be different in your machine. 10690If <code>lua</code> is in your <code>PATH</code>, 10691then 10692 10693<pre> 10694 #!/usr/bin/env lua 10695</pre><p> 10696is a more portable solution.) 10697 10698 10699 10700<h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> 10701 10702<p> 10703Here we list the incompatibilities that you may find when moving a program 10704from Lua 5.2 to Lua 5.3. 10705You can avoid some incompatibilities by compiling Lua with 10706appropriate options (see file <code>luaconf.h</code>). 10707However, 10708all these compatibility options will be removed in the future. 10709 10710 10711<p> 10712Lua versions can always change the C API in ways that 10713do not imply source-code changes in a program, 10714such as the numeric values for constants 10715or the implementation of functions as macros. 10716Therefore, 10717you should not assume that binaries are compatible between 10718different Lua versions. 10719Always recompile clients of the Lua API when 10720using a new version. 10721 10722 10723<p> 10724Similarly, Lua versions can always change the internal representation 10725of precompiled chunks; 10726precompiled chunks are not compatible between different Lua versions. 10727 10728 10729<p> 10730The standard paths in the official distribution may 10731change between versions. 10732 10733 10734 10735<h2>8.1 – <a name="8.1">Changes in the Language</a></h2> 10736<ul> 10737 10738<li> 10739The main difference between Lua 5.2 and Lua 5.3 is the 10740introduction of an integer subtype for numbers. 10741Although this change should not affect "normal" computations, 10742some computations 10743(mainly those that involve some kind of overflow) 10744can give different results. 10745 10746 10747<p> 10748You can fix these differences by forcing a number to be a float 10749(in Lua 5.2 all numbers were float), 10750in particular writing constants with an ending <code>.0</code> 10751or using <code>x = x + 0.0</code> to convert a variable. 10752(This recommendation is only for a quick fix 10753for an occasional incompatibility; 10754it is not a general guideline for good programming. 10755For good programming, 10756use floats where you need floats 10757and integers where you need integers.) 10758</li> 10759 10760<li> 10761The conversion of a float to a string now adds a <code>.0</code> suffix 10762to the result if it looks like an integer. 10763(For instance, the float 2.0 will be printed as <code>2.0</code>, 10764not as <code>2</code>.) 10765You should always use an explicit format 10766when you need a specific format for numbers. 10767 10768 10769<p> 10770(Formally this is not an incompatibility, 10771because Lua does not specify how numbers are formatted as strings, 10772but some programs assumed a specific format.) 10773</li> 10774 10775<li> 10776The generational mode for the garbage collector was removed. 10777(It was an experimental feature in Lua 5.2.) 10778</li> 10779 10780</ul> 10781 10782 10783 10784 10785<h2>8.2 – <a name="8.2">Changes in the Libraries</a></h2> 10786<ul> 10787 10788<li> 10789The <code>bit32</code> library has been deprecated. 10790It is easy to require a compatible external library or, 10791better yet, to replace its functions with appropriate bitwise operations. 10792(Keep in mind that <code>bit32</code> operates on 32-bit integers, 10793while the bitwise operators in Lua 5.3 operate on Lua integers, 10794which by default have 64 bits.) 10795</li> 10796 10797<li> 10798The Table library now respects metamethods 10799for setting and getting elements. 10800</li> 10801 10802<li> 10803The <a href="#pdf-ipairs"><code>ipairs</code></a> iterator now respects metamethods and 10804its <code>__ipairs</code> metamethod has been deprecated. 10805</li> 10806 10807<li> 10808Option names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore. 10809For compatibility, Lua will continue to accept (and ignore) this character. 10810</li> 10811 10812<li> 10813The following functions were deprecated in the mathematical library: 10814<code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>, 10815<code>frexp</code>, and <code>ldexp</code>. 10816You can replace <code>math.pow(x,y)</code> with <code>x^y</code>; 10817you can replace <code>math.atan2</code> with <code>math.atan</code>, 10818which now accepts one or two parameters; 10819you can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>. 10820For the other operations, 10821you can either use an external library or 10822implement them in Lua. 10823</li> 10824 10825<li> 10826The searcher for C loaders used by <a href="#pdf-require"><code>require</code></a> 10827changed the way it handles versioned names. 10828Now, the version should come after the module name 10829(as is usual in most other tools). 10830For compatibility, that searcher still tries the old format 10831if it cannot find an open function according to the new style. 10832(Lua 5.2 already worked that way, 10833but it did not document the change.) 10834</li> 10835 10836<li> 10837The call <code>collectgarbage("count")</code> now returns only one result. 10838(You can compute that second result from the fractional part 10839of the first result.) 10840</li> 10841 10842</ul> 10843 10844 10845 10846 10847<h2>8.3 – <a name="8.3">Changes in the API</a></h2> 10848 10849 10850<ul> 10851 10852<li> 10853Continuation functions now receive as parameters what they needed 10854to get through <code>lua_getctx</code>, 10855so <code>lua_getctx</code> has been removed. 10856Adapt your code accordingly. 10857</li> 10858 10859<li> 10860Function <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>. 10861Use 0 as the value of this parameter to get the old behavior. 10862</li> 10863 10864<li> 10865Functions to inject/project unsigned integers 10866(<code>lua_pushunsigned</code>, <code>lua_tounsigned</code>, <code>lua_tounsignedx</code>, 10867<code>luaL_checkunsigned</code>, <code>luaL_optunsigned</code>) 10868were deprecated. 10869Use their signed equivalents with a type cast. 10870</li> 10871 10872<li> 10873Macros to project non-default integer types 10874(<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>) 10875were deprecated. 10876Use their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast 10877(or, when possible, use <a href="#lua_Integer"><code>lua_Integer</code></a> in your code). 10878</li> 10879 10880</ul> 10881 10882 10883 10884 10885<h1>9 – <a name="9">The Complete Syntax of Lua</a></h1> 10886 10887<p> 10888Here is the complete syntax of Lua in extended BNF. 10889As usual in extended BNF, 10890{A} means 0 or more As, 10891and [A] means an optional A. 10892(For operator precedences, see <a href="#3.4.8">§3.4.8</a>; 10893for a description of the terminals 10894Name, Numeral, 10895and LiteralString, see <a href="#3.1">§3.1</a>.) 10896 10897 10898 10899 10900<pre> 10901 10902 chunk ::= block 10903 10904 block ::= {stat} [retstat] 10905 10906 stat ::= ‘<b>;</b>’ | 10907 varlist ‘<b>=</b>’ explist | 10908 functioncall | 10909 label | 10910 <b>break</b> | 10911 <b>goto</b> Name | 10912 <b>do</b> block <b>end</b> | 10913 <b>while</b> exp <b>do</b> block <b>end</b> | 10914 <b>repeat</b> block <b>until</b> exp | 10915 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 10916 <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> | 10917 <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 10918 <b>function</b> funcname funcbody | 10919 <b>local</b> <b>function</b> Name funcbody | 10920 <b>local</b> namelist [‘<b>=</b>’ explist] 10921 10922 retstat ::= <b>return</b> [explist] [‘<b>;</b>’] 10923 10924 label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 10925 10926 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 10927 10928 varlist ::= var {‘<b>,</b>’ var} 10929 10930 var ::= Name | prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | prefixexp ‘<b>.</b>’ Name 10931 10932 namelist ::= Name {‘<b>,</b>’ Name} 10933 10934 explist ::= exp {‘<b>,</b>’ exp} 10935 10936 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | ‘<b>...</b>’ | functiondef | 10937 prefixexp | tableconstructor | exp binop exp | unop exp 10938 10939 prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 10940 10941 functioncall ::= prefixexp args | prefixexp ‘<b>:</b>’ Name args 10942 10943 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | tableconstructor | LiteralString 10944 10945 functiondef ::= <b>function</b> funcbody 10946 10947 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 10948 10949 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 10950 10951 tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 10952 10953 fieldlist ::= field {fieldsep field} [fieldsep] 10954 10955 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 10956 10957 fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 10958 10959 binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</b>’ | ‘<b>//</b>’ | ‘<b>^</b>’ | ‘<b>%</b>’ | 10960 ‘<b>&</b>’ | ‘<b>~</b>’ | ‘<b>|</b>’ | ‘<b>>></b>’ | ‘<b><<</b>’ | ‘<b>..</b>’ | 10961 ‘<b><</b>’ | ‘<b><=</b>’ | ‘<b>></b>’ | ‘<b>>=</b>’ | ‘<b>==</b>’ | ‘<b>~=</b>’ | 10962 <b>and</b> | <b>or</b> 10963 10964 unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’ | ‘<b>~</b>’ 10965 10966</pre> 10967 10968<p> 10969 10970 10971 10972 10973 10974 10975 10976<P CLASS="footer"> 10977Last update: 10978Mon Jan 9 13:30:53 BRST 2017 10979</P> 10980<!-- 10981Last change: revised for Lua 5.3.4 10982--> 10983 10984</body></html> 10985 10986
