1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<TITLE>Lua 5.4 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.4 Reference Manual 15</H1> 16 17<P> 18by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes 19 20<P> 21<SMALL> 22Copyright © 2020–2022 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 $ --> 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 59a generational 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 110 111<p> 112This section describes the basic concepts of the language. 113 114 115 116 117 118<h2>2.1 – <a name="2.1">Values and Types</a></h2> 119 120<p> 121Lua is a dynamically typed language. 122This means that 123variables do not have types; only values do. 124There are no type definitions in the language. 125All values carry their own type. 126 127 128<p> 129All values in Lua are first-class values. 130This means that all values can be stored in variables, 131passed as arguments to other functions, and returned as results. 132 133 134<p> 135There are eight basic types in Lua: 136<em>nil</em>, <em>boolean</em>, <em>number</em>, 137<em>string</em>, <em>function</em>, <em>userdata</em>, 138<em>thread</em>, and <em>table</em>. 139The type <em>nil</em> has one single value, <b>nil</b>, 140whose main property is to be different from any other value; 141it often represents the absence of a useful value. 142The type <em>boolean</em> has two values, <b>false</b> and <b>true</b>. 143Both <b>nil</b> and <b>false</b> make a condition false; 144they are collectively called <em>false values</em>. 145Any other value makes a condition true. 146Despite its name, 147<b>false</b> is frequently used as an alternative to <b>nil</b>, 148with the key difference that <b>false</b> behaves 149like a regular value in a table, 150while a <b>nil</b> in a table represents an absent key. 151 152 153<p> 154The type <em>number</em> represents both 155integer numbers and real (floating-point) numbers, 156using two subtypes: <em>integer</em> and <em>float</em>. 157Standard Lua uses 64-bit integers and double-precision (64-bit) floats, 158but you can also compile Lua so that it 159uses 32-bit integers and/or single-precision (32-bit) floats. 160The option with 32 bits for both integers and floats 161is particularly attractive 162for small machines and embedded systems. 163(See macro <code>LUA_32BITS</code> in file <code>luaconf.h</code>.) 164 165 166<p> 167Unless stated otherwise, 168any overflow when manipulating integer values <em>wrap around</em>, 169according to the usual rules of two-complement arithmetic. 170(In other words, 171the actual result is the unique representable integer 172that is equal modulo <em>2<sup>n</sup></em> to the mathematical result, 173where <em>n</em> is the number of bits of the integer type.) 174 175 176<p> 177Lua has explicit rules about when each subtype is used, 178but it also converts between them automatically as needed (see <a href="#3.4.3">§3.4.3</a>). 179Therefore, 180the programmer may choose to mostly ignore the difference 181between integers and floats 182or to assume complete control over the representation of each number. 183 184 185<p> 186The type <em>string</em> represents immutable sequences of bytes. 187 188Lua is 8-bit clean: 189strings can contain any 8-bit value, 190including embedded zeros ('<code>\0</code>'). 191Lua is also encoding-agnostic; 192it makes no assumptions about the contents of a string. 193The length of any string in Lua must fit in a Lua integer. 194 195 196<p> 197Lua can call (and manipulate) functions written in Lua and 198functions written in C (see <a href="#3.4.10">§3.4.10</a>). 199Both are represented by the type <em>function</em>. 200 201 202<p> 203The type <em>userdata</em> is provided to allow arbitrary C data to 204be stored in Lua variables. 205A userdata value represents a block of raw memory. 206There are two kinds of userdata: 207<em>full userdata</em>, 208which is an object with a block of memory managed by Lua, 209and <em>light userdata</em>, 210which is simply a C pointer value. 211Userdata has no predefined operations in Lua, 212except assignment and identity test. 213By using <em>metatables</em>, 214the programmer can define operations for full userdata values 215(see <a href="#2.4">§2.4</a>). 216Userdata values cannot be created or modified in Lua, 217only through the C API. 218This guarantees the integrity of data owned by 219the host program and C libraries. 220 221 222<p> 223The type <em>thread</em> represents independent threads of execution 224and it is used to implement coroutines (see <a href="#2.6">§2.6</a>). 225Lua threads are not related to operating-system threads. 226Lua supports coroutines on all systems, 227even those that do not support threads natively. 228 229 230<p> 231The type <em>table</em> implements associative arrays, 232that is, arrays that can have as indices not only numbers, 233but any Lua value except <b>nil</b> and NaN. 234(<em>Not a Number</em> is a special floating-point value 235used by the IEEE 754 standard to represent 236undefined numerical results, such as <code>0/0</code>.) 237Tables can be <em>heterogeneous</em>; 238that is, they can contain values of all types (except <b>nil</b>). 239Any key associated to the value <b>nil</b> is not considered part of the table. 240Conversely, any key that is not part of a table has 241an associated value <b>nil</b>. 242 243 244<p> 245Tables are the sole data-structuring mechanism in Lua; 246they can be used to represent ordinary arrays, lists, 247symbol tables, sets, records, graphs, trees, etc. 248To represent records, Lua uses the field name as an index. 249The language supports this representation by 250providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. 251There are several convenient ways to create tables in Lua 252(see <a href="#3.4.9">§3.4.9</a>). 253 254 255<p> 256Like indices, 257the values of table fields can be of any type. 258In particular, 259because functions are first-class values, 260table fields can contain functions. 261Thus tables can also carry <em>methods</em> (see <a href="#3.4.11">§3.4.11</a>). 262 263 264<p> 265The indexing of tables follows 266the definition of raw equality in the language. 267The expressions <code>a[i]</code> and <code>a[j]</code> 268denote the same table element 269if and only if <code>i</code> and <code>j</code> are raw equal 270(that is, equal without metamethods). 271In particular, floats with integral values 272are equal to their respective integers 273(e.g., <code>1.0 == 1</code>). 274To avoid ambiguities, 275any float used as a key that is equal to an integer 276is converted to that integer. 277For instance, if you write <code>a[2.0] = true</code>, 278the actual key inserted into the table will be the integer <code>2</code>. 279 280 281<p> 282Tables, functions, threads, and (full) userdata values are <em>objects</em>: 283variables do not actually <em>contain</em> these values, 284only <em>references</em> to them. 285Assignment, parameter passing, and function returns 286always manipulate references to such values; 287these operations do not imply any kind of copy. 288 289 290<p> 291The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type 292of a given value (see <a href="#pdf-type"><code>type</code></a>). 293 294 295 296 297 298<h2>2.2 – <a name="2.2">Environments and the Global Environment</a></h2> 299 300<p> 301As we will discuss further in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>, 302any reference to a free name 303(that is, a name not bound to any declaration) <code>var</code> 304is syntactically translated to <code>_ENV.var</code>. 305Moreover, every chunk is compiled in the scope of 306an external local variable named <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>), 307so <code>_ENV</code> itself is never a free name in a chunk. 308 309 310<p> 311Despite the existence of this external <code>_ENV</code> variable and 312the translation of free names, 313<code>_ENV</code> is a completely regular name. 314In particular, 315you can define new variables and parameters with that name. 316Each reference to a free name uses the <code>_ENV</code> that is 317visible at that point in the program, 318following the usual visibility rules of Lua (see <a href="#3.5">§3.5</a>). 319 320 321<p> 322Any table used as the value of <code>_ENV</code> is called an <em>environment</em>. 323 324 325<p> 326Lua keeps a distinguished environment called the <em>global environment</em>. 327This value is kept at a special index in the C registry (see <a href="#4.3">§4.3</a>). 328In Lua, the global variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value. 329(<a href="#pdf-_G"><code>_G</code></a> is never used internally, 330so changing its value will affect only your own code.) 331 332 333<p> 334When Lua loads a chunk, 335the default value for its <code>_ENV</code> variable 336is the global environment (see <a href="#pdf-load"><code>load</code></a>). 337Therefore, by default, 338free names in Lua code refer to entries in the global environment 339and, therefore, they are also called <em>global variables</em>. 340Moreover, all standard libraries are loaded in the global environment 341and some functions there operate on that environment. 342You can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>) 343to load a chunk with a different environment. 344(In C, you have to load the chunk and then change the value 345of its first upvalue; see <a href="#lua_setupvalue"><code>lua_setupvalue</code></a>.) 346 347 348 349 350 351<h2>2.3 – <a name="2.3">Error Handling</a></h2> 352 353<p> 354Several operations in Lua can <em>raise</em> an error. 355An error interrupts the normal flow of the program, 356which can continue by <em>catching</em> the error. 357 358 359<p> 360Lua code can explicitly raise an error by calling the 361<a href="#pdf-error"><code>error</code></a> function. 362(This function never returns.) 363 364 365<p> 366To catch errors in Lua, 367you can do a <em>protected call</em>, 368using <a href="#pdf-pcall"><code>pcall</code></a> (or <a href="#pdf-xpcall"><code>xpcall</code></a>). 369The function <a href="#pdf-pcall"><code>pcall</code></a> calls a given function in <em>protected mode</em>. 370Any error while running the function stops its execution, 371and control returns immediately to <code>pcall</code>, 372which returns a status code. 373 374 375<p> 376Because Lua is an embedded extension language, 377Lua code starts running by a call 378from C code in the host program. 379(When you use Lua standalone, 380the <code>lua</code> application is the host program.) 381Usually, this call is protected; 382so, when an otherwise unprotected error occurs during 383the compilation or execution of a Lua chunk, 384control returns to the host, 385which can take appropriate measures, 386such as printing an error message. 387 388 389<p> 390Whenever there is an error, 391an <em>error object</em> 392is propagated with information about the error. 393Lua itself only generates errors whose error object is a string, 394but programs may generate errors with 395any value as the error object. 396It is up to the Lua program or its host to handle such error objects. 397For historical reasons, 398an error object is often called an <em>error message</em>, 399even though it does not have to be a string. 400 401 402<p> 403When you use <a href="#pdf-xpcall"><code>xpcall</code></a> (or <a href="#lua_pcall"><code>lua_pcall</code></a>, in C) 404you may give a <em>message handler</em> 405to be called in case of errors. 406This function is called with the original error object 407and returns a new error object. 408It is called before the error unwinds the stack, 409so that it can gather more information about the error, 410for instance by inspecting the stack and creating a stack traceback. 411This message handler is still protected by the protected call; 412so, an error inside the message handler 413will call the message handler again. 414If this loop goes on for too long, 415Lua breaks it and returns an appropriate message. 416The message handler is called only for regular runtime errors. 417It is not called for memory-allocation errors 418nor for errors while running finalizers or other message handlers. 419 420 421<p> 422Lua also offers a system of <em>warnings</em> (see <a href="#pdf-warn"><code>warn</code></a>). 423Unlike errors, warnings do not interfere 424in any way with program execution. 425They typically only generate a message to the user, 426although this behavior can be adapted from C (see <a href="#lua_setwarnf"><code>lua_setwarnf</code></a>). 427 428 429 430 431 432<h2>2.4 – <a name="2.4">Metatables and Metamethods</a></h2> 433 434<p> 435Every value in Lua can have a <em>metatable</em>. 436This <em>metatable</em> is an ordinary Lua table 437that defines the behavior of the original value 438under certain events. 439You can change several aspects of the behavior 440of a value by setting specific fields in its metatable. 441For instance, when a non-numeric value is the operand of an addition, 442Lua checks for a function in the field <code>__add</code> of the value's metatable. 443If it finds one, 444Lua calls this function to perform the addition. 445 446 447<p> 448The key for each event in a metatable is a string 449with the event name prefixed by two underscores; 450the corresponding value is called a <em>metavalue</em>. 451For most events, the metavalue must be a function, 452which is then called a <em>metamethod</em>. 453In the previous example, the key is the string "<code>__add</code>" 454and the metamethod is the function that performs the addition. 455Unless stated otherwise, 456a metamethod may in fact be any callable value, 457which is either a function or a value with a <code>__call</code> metamethod. 458 459 460<p> 461You can query the metatable of any value 462using the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function. 463Lua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>). 464 465 466<p> 467You can replace the metatable of tables 468using the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function. 469You cannot change the metatable of other types from Lua code, 470except by using the debug library (<a href="#6.10">§6.10</a>). 471 472 473<p> 474Tables and full userdata have individual metatables, 475although multiple tables and userdata can share their metatables. 476Values of all other types share one single metatable per type; 477that is, there is one single metatable for all numbers, 478one for all strings, etc. 479By default, a value has no metatable, 480but the string library sets a metatable for the string type (see <a href="#6.4">§6.4</a>). 481 482 483<p> 484A detailed list of operations controlled by metatables is given next. 485Each event is identified by its corresponding key. 486By convention, all metatable keys used by Lua are composed by 487two underscores followed by lowercase Latin letters. 488 489 490 491<ul> 492 493<li><b><code>__add</code>: </b> 494the addition (<code>+</code>) operation. 495If any operand for an addition is not a number, 496Lua will try to call a metamethod. 497It starts by checking the first operand (even if it is a number); 498if that operand does not define a metamethod for <code>__add</code>, 499then Lua will check the second operand. 500If Lua can find a metamethod, 501it calls the metamethod with the two operands as arguments, 502and the result of the call 503(adjusted to one value) 504is the result of the operation. 505Otherwise, if no metamethod is found, 506Lua raises an error. 507</li> 508 509<li><b><code>__sub</code>: </b> 510the subtraction (<code>-</code>) operation. 511Behavior similar to the addition operation. 512</li> 513 514<li><b><code>__mul</code>: </b> 515the multiplication (<code>*</code>) operation. 516Behavior similar to the addition operation. 517</li> 518 519<li><b><code>__div</code>: </b> 520the division (<code>/</code>) operation. 521Behavior similar to the addition operation. 522</li> 523 524<li><b><code>__mod</code>: </b> 525the modulo (<code>%</code>) operation. 526Behavior similar to the addition operation. 527</li> 528 529<li><b><code>__pow</code>: </b> 530the exponentiation (<code>^</code>) operation. 531Behavior similar to the addition operation. 532</li> 533 534<li><b><code>__unm</code>: </b> 535the negation (unary <code>-</code>) operation. 536Behavior similar to the addition operation. 537</li> 538 539<li><b><code>__idiv</code>: </b> 540the floor division (<code>//</code>) operation. 541Behavior similar to the addition operation. 542</li> 543 544<li><b><code>__band</code>: </b> 545the bitwise AND (<code>&</code>) operation. 546Behavior similar to the addition operation, 547except that Lua will try a metamethod 548if any operand is neither an integer 549nor a float coercible to an integer (see <a href="#3.4.3">§3.4.3</a>). 550</li> 551 552<li><b><code>__bor</code>: </b> 553the bitwise OR (<code>|</code>) operation. 554Behavior similar to the bitwise AND operation. 555</li> 556 557<li><b><code>__bxor</code>: </b> 558the bitwise exclusive OR (binary <code>~</code>) operation. 559Behavior similar to the bitwise AND operation. 560</li> 561 562<li><b><code>__bnot</code>: </b> 563the bitwise NOT (unary <code>~</code>) operation. 564Behavior similar to the bitwise AND operation. 565</li> 566 567<li><b><code>__shl</code>: </b> 568the bitwise left shift (<code><<</code>) operation. 569Behavior similar to the bitwise AND operation. 570</li> 571 572<li><b><code>__shr</code>: </b> 573the bitwise right shift (<code>>></code>) operation. 574Behavior similar to the bitwise AND operation. 575</li> 576 577<li><b><code>__concat</code>: </b> 578the concatenation (<code>..</code>) operation. 579Behavior similar to the addition operation, 580except that Lua will try a metamethod 581if any operand is neither a string nor a number 582(which is always coercible to a string). 583</li> 584 585<li><b><code>__len</code>: </b> 586the length (<code>#</code>) operation. 587If the object is not a string, 588Lua will try its metamethod. 589If there is a metamethod, 590Lua calls it with the object as argument, 591and the result of the call 592(always adjusted to one value) 593is the result of the operation. 594If there is no metamethod but the object is a table, 595then Lua uses the table length operation (see <a href="#3.4.7">§3.4.7</a>). 596Otherwise, Lua raises an error. 597</li> 598 599<li><b><code>__eq</code>: </b> 600the equal (<code>==</code>) operation. 601Behavior similar to the addition operation, 602except that Lua will try a metamethod only when the values 603being compared are either both tables or both full userdata 604and they are not primitively equal. 605The result of the call is always converted to a boolean. 606</li> 607 608<li><b><code>__lt</code>: </b> 609the less than (<code><</code>) operation. 610Behavior similar to the addition operation, 611except that Lua will try a metamethod only when the values 612being compared are neither both numbers nor both strings. 613Moreover, the result of the call is always converted to a boolean. 614</li> 615 616<li><b><code>__le</code>: </b> 617the less equal (<code><=</code>) operation. 618Behavior similar to the less than operation. 619</li> 620 621<li><b><code>__index</code>: </b> 622The indexing access operation <code>table[key]</code>. 623This event happens when <code>table</code> is not a table or 624when <code>key</code> is not present in <code>table</code>. 625The metavalue is looked up in the metatable of <code>table</code>. 626 627 628<p> 629The metavalue for this event can be either a function, a table, 630or any value with an <code>__index</code> metavalue. 631If it is a function, 632it is called with <code>table</code> and <code>key</code> as arguments, 633and the result of the call 634(adjusted to one value) 635is the result of the operation. 636Otherwise, 637the final result is the result of indexing this metavalue with <code>key</code>. 638This indexing is regular, not raw, 639and therefore can trigger another <code>__index</code> metavalue. 640</li> 641 642<li><b><code>__newindex</code>: </b> 643The indexing assignment <code>table[key] = value</code>. 644Like the index event, 645this event happens when <code>table</code> is not a table or 646when <code>key</code> is not present in <code>table</code>. 647The metavalue is looked up in the metatable of <code>table</code>. 648 649 650<p> 651Like with indexing, 652the metavalue for this event can be either a function, a table, 653or any value with an <code>__newindex</code> metavalue. 654If it is a function, 655it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments. 656Otherwise, 657Lua repeats the indexing assignment over this metavalue 658with the same key and value. 659This assignment is regular, not raw, 660and therefore can trigger another <code>__newindex</code> metavalue. 661 662 663<p> 664Whenever a <code>__newindex</code> metavalue is invoked, 665Lua does not perform the primitive assignment. 666If needed, 667the metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a> 668to do the assignment. 669</li> 670 671<li><b><code>__call</code>: </b> 672The call operation <code>func(args)</code>. 673This event happens when Lua tries to call a non-function value 674(that is, <code>func</code> is not a function). 675The metamethod is looked up in <code>func</code>. 676If present, 677the metamethod is called with <code>func</code> as its first argument, 678followed by the arguments of the original call (<code>args</code>). 679All results of the call 680are the results of the operation. 681This is the only metamethod that allows multiple results. 682</li> 683 684</ul> 685 686<p> 687In addition to the previous list, 688the interpreter also respects the following keys in metatables: 689<code>__gc</code> (see <a href="#2.5.3">§2.5.3</a>), 690<code>__close</code> (see <a href="#3.3.8">§3.3.8</a>), 691<code>__mode</code> (see <a href="#2.5.4">§2.5.4</a>), 692and <code>__name</code>. 693(The entry <code>__name</code>, 694when it contains a string, 695may be used by <a href="#pdf-tostring"><code>tostring</code></a> and in error messages.) 696 697 698<p> 699For the unary operators (negation, length, and bitwise NOT), 700the metamethod is computed and called with a dummy second operand, 701equal to the first one. 702This extra operand is only to simplify Lua's internals 703(by making these operators behave like a binary operation) 704and may be removed in future versions. 705For most uses this extra operand is irrelevant. 706 707 708<p> 709Because metatables are regular tables, 710they can contain arbitrary fields, 711not only the event names defined above. 712Some functions in the standard library 713(e.g., <a href="#pdf-tostring"><code>tostring</code></a>) 714use other fields in metatables for their own purposes. 715 716 717<p> 718It is a good practice to add all needed metamethods to a table 719before setting it as a metatable of some object. 720In particular, the <code>__gc</code> metamethod works only when this order 721is followed (see <a href="#2.5.3">§2.5.3</a>). 722It is also a good practice to set the metatable of an object 723right after its creation. 724 725 726 727 728 729<h2>2.5 – <a name="2.5">Garbage Collection</a></h2> 730 731 732 733<p> 734Lua performs automatic memory management. 735This means that 736you do not have to worry about allocating memory for new objects 737or freeing it when the objects are no longer needed. 738Lua manages memory automatically by running 739a <em>garbage collector</em> to collect all <em>dead</em> objects. 740All memory used by Lua is subject to automatic management: 741strings, tables, userdata, functions, threads, internal structures, etc. 742 743 744<p> 745An object is considered <em>dead</em> 746as soon as the collector can be sure the object 747will not be accessed again in the normal execution of the program. 748("Normal execution" here excludes finalizers, 749which can resurrect dead objects (see <a href="#2.5.3">§2.5.3</a>), 750and excludes also operations using the debug library.) 751Note that the time when the collector can be sure that an object 752is dead may not coincide with the programmer's expectations. 753The only guarantees are that Lua will not collect an object 754that may still be accessed in the normal execution of the program, 755and it will eventually collect an object 756that is inaccessible from Lua. 757(Here, 758<em>inaccessible from Lua</em> means that neither a variable nor 759another live object refer to the object.) 760Because Lua has no knowledge about C code, 761it never collects objects accessible through the registry (see <a href="#4.3">§4.3</a>), 762which includes the global environment (see <a href="#2.2">§2.2</a>). 763 764 765<p> 766The garbage collector (GC) in Lua can work in two modes: 767incremental and generational. 768 769 770<p> 771The default GC mode with the default parameters 772are adequate for most uses. 773However, programs that waste a large proportion of their time 774allocating and freeing memory can benefit from other settings. 775Keep in mind that the GC behavior is non-portable 776both across platforms and across different Lua releases; 777therefore, optimal settings are also non-portable. 778 779 780<p> 781You can change the GC mode and parameters by calling 782<a href="#lua_gc"><code>lua_gc</code></a> in C 783or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. 784You can also use these functions to control 785the collector directly (e.g., to stop and restart it). 786 787 788 789 790 791<h3>2.5.1 – <a name="2.5.1">Incremental Garbage Collection</a></h3> 792 793<p> 794In incremental mode, 795each GC cycle performs a mark-and-sweep collection in small steps 796interleaved with the program's execution. 797In this mode, 798the collector uses three numbers to control its garbage-collection cycles: 799the <em>garbage-collector pause</em>, 800the <em>garbage-collector step multiplier</em>, 801and the <em>garbage-collector step size</em>. 802 803 804<p> 805The garbage-collector pause 806controls how long the collector waits before starting a new cycle. 807The collector starts a new cycle when the use of memory 808hits <em>n%</em> of the use after the previous collection. 809Larger values make the collector less aggressive. 810Values equal to or less than 100 mean the collector will not wait to 811start a new cycle. 812A value of 200 means that the collector waits for the total memory in use 813to double before starting a new cycle. 814The default value is 200; the maximum value is 1000. 815 816 817<p> 818The garbage-collector step multiplier 819controls the speed of the collector relative to 820memory allocation, 821that is, 822how many elements it marks or sweeps for each 823kilobyte of memory allocated. 824Larger values make the collector more aggressive but also increase 825the size of each incremental step. 826You should not use values less than 100, 827because they make the collector too slow and 828can result in the collector never finishing a cycle. 829The default value is 100; the maximum value is 1000. 830 831 832<p> 833The garbage-collector step size controls the 834size of each incremental step, 835specifically how many bytes the interpreter allocates 836before performing a step. 837This parameter is logarithmic: 838A value of <em>n</em> means the interpreter will allocate <em>2<sup>n</sup></em> 839bytes between steps and perform equivalent work during the step. 840A large value (e.g., 60) makes the collector a stop-the-world 841(non-incremental) collector. 842The default value is 13, 843which means steps of approximately 8 Kbytes. 844 845 846 847 848 849<h3>2.5.2 – <a name="2.5.2">Generational Garbage Collection</a></h3> 850 851<p> 852In generational mode, 853the collector does frequent <em>minor</em> collections, 854which traverses only objects recently created. 855If after a minor collection the use of memory is still above a limit, 856the collector does a stop-the-world <em>major</em> collection, 857which traverses all objects. 858The generational mode uses two parameters: 859the <em>minor multiplier</em> and the <em>the major multiplier</em>. 860 861 862<p> 863The minor multiplier controls the frequency of minor collections. 864For a minor multiplier <em>x</em>, 865a new minor collection will be done when memory 866grows <em>x%</em> larger than the memory in use after the previous major 867collection. 868For instance, for a multiplier of 20, 869the collector will do a minor collection when the use of memory 870gets 20% larger than the use after the previous major collection. 871The default value is 20; the maximum value is 200. 872 873 874<p> 875The major multiplier controls the frequency of major collections. 876For a major multiplier <em>x</em>, 877a new major collection will be done when memory 878grows <em>x%</em> larger than the memory in use after the previous major 879collection. 880For instance, for a multiplier of 100, 881the collector will do a major collection when the use of memory 882gets larger than twice the use after the previous collection. 883The default value is 100; the maximum value is 1000. 884 885 886 887 888 889<h3>2.5.3 – <a name="2.5.3">Garbage-Collection Metamethods</a></h3> 890 891<p> 892You can set garbage-collector metamethods for tables 893and, using the C API, 894for full userdata (see <a href="#2.4">§2.4</a>). 895These metamethods, called <em>finalizers</em>, 896are called when the garbage collector detects that the 897corresponding table or userdata is dead. 898Finalizers allow you to coordinate Lua's garbage collection 899with external resource management such as closing files, 900network or database connections, 901or freeing your own memory. 902 903 904<p> 905For an object (table or userdata) to be finalized when collected, 906you must <em>mark</em> it for finalization. 907 908You mark an object for finalization when you set its metatable 909and the metatable has a <code>__gc</code> metamethod. 910Note that if you set a metatable without a <code>__gc</code> field 911and later create that field in the metatable, 912the object will not be marked for finalization. 913 914 915<p> 916When a marked object becomes dead, 917it is not collected immediately by the garbage collector. 918Instead, Lua puts it in a list. 919After the collection, 920Lua goes through that list. 921For each object in the list, 922it checks the object's <code>__gc</code> metamethod: 923If it is present, 924Lua calls it with the object as its single argument. 925 926 927<p> 928At the end of each garbage-collection cycle, 929the finalizers are called in 930the reverse order that the objects were marked for finalization, 931among those collected in that cycle; 932that is, the first finalizer to be called is the one associated 933with the object marked last in the program. 934The execution of each finalizer may occur at any point during 935the execution of the regular code. 936 937 938<p> 939Because the object being collected must still be used by the finalizer, 940that object (and other objects accessible only through it) 941must be <em>resurrected</em> by Lua. 942Usually, this resurrection is transient, 943and the object memory is freed in the next garbage-collection cycle. 944However, if the finalizer stores the object in some global place 945(e.g., a global variable), 946then the resurrection is permanent. 947Moreover, if the finalizer marks a finalizing object for finalization again, 948its finalizer will be called again in the next cycle where the 949object is dead. 950In any case, 951the object memory is freed only in a GC cycle where 952the object is dead and not marked for finalization. 953 954 955<p> 956When you close a state (see <a href="#lua_close"><code>lua_close</code></a>), 957Lua calls the finalizers of all objects marked for finalization, 958following the reverse order that they were marked. 959If any finalizer marks objects for collection during that phase, 960these marks have no effect. 961 962 963<p> 964Finalizers cannot yield nor run the garbage collector. 965Because they can run in unpredictable times, 966it is good practice to restrict each finalizer 967to the minimum necessary to properly release 968its associated resource. 969 970 971<p> 972Any error while running a finalizer generates a warning; 973the error is not propagated. 974 975 976 977 978 979<h3>2.5.4 – <a name="2.5.4">Weak Tables</a></h3> 980 981<p> 982A <em>weak table</em> is a table whose elements are 983<em>weak references</em>. 984A weak reference is ignored by the garbage collector. 985In other words, 986if the only references to an object are weak references, 987then the garbage collector will collect that object. 988 989 990<p> 991A weak table can have weak keys, weak values, or both. 992A table with weak values allows the collection of its values, 993but prevents the collection of its keys. 994A table with both weak keys and weak values allows the collection of 995both keys and values. 996In any case, if either the key or the value is collected, 997the whole pair is removed from the table. 998The weakness of a table is controlled by the 999<code>__mode</code> field of its metatable. 1000This metavalue, if present, must be one of the following strings: 1001"<code>k</code>", for a table with weak keys; 1002"<code>v</code>", for a table with weak values; 1003or "<code>kv</code>", for a table with both weak keys and values. 1004 1005 1006<p> 1007A table with weak keys and strong values 1008is also called an <em>ephemeron table</em>. 1009In an ephemeron table, 1010a value is considered reachable only if its key is reachable. 1011In particular, 1012if the only reference to a key comes through its value, 1013the pair is removed. 1014 1015 1016<p> 1017Any change in the weakness of a table may take effect only 1018at the next collect cycle. 1019In particular, if you change the weakness to a stronger mode, 1020Lua may still collect some items from that table 1021before the change takes effect. 1022 1023 1024<p> 1025Only objects that have an explicit construction 1026are removed from weak tables. 1027Values, such as numbers and light C functions, 1028are not subject to garbage collection, 1029and therefore are not removed from weak tables 1030(unless their associated values are collected). 1031Although strings are subject to garbage collection, 1032they do not have an explicit construction and 1033their equality is by value; 1034they behave more like values than like objects. 1035Therefore, they are not removed from weak tables. 1036 1037 1038<p> 1039Resurrected objects 1040(that is, objects being finalized 1041and objects accessible only through objects being finalized) 1042have a special behavior in weak tables. 1043They are removed from weak values before running their finalizers, 1044but are removed from weak keys only in the next collection 1045after running their finalizers, when such objects are actually freed. 1046This behavior allows the finalizer to access properties 1047associated with the object through weak tables. 1048 1049 1050<p> 1051If a weak table is among the resurrected objects in a collection cycle, 1052it may not be properly cleared until the next cycle. 1053 1054 1055 1056 1057 1058 1059 1060<h2>2.6 – <a name="2.6">Coroutines</a></h2> 1061 1062<p> 1063Lua supports coroutines, 1064also called <em>collaborative multithreading</em>. 1065A coroutine in Lua represents an independent thread of execution. 1066Unlike threads in multithread systems, however, 1067a coroutine only suspends its execution by explicitly calling 1068a yield function. 1069 1070 1071<p> 1072You create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>. 1073Its sole argument is a function 1074that is the main function of the coroutine. 1075The <code>create</code> function only creates a new coroutine and 1076returns a handle to it (an object of type <em>thread</em>); 1077it does not start the coroutine. 1078 1079 1080<p> 1081You execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 1082When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 1083passing as its first argument 1084a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 1085the coroutine starts its execution by 1086calling its main function. 1087Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed 1088as arguments to that function. 1089After the coroutine starts running, 1090it runs until it terminates or <em>yields</em>. 1091 1092 1093<p> 1094A coroutine can terminate its execution in two ways: 1095normally, when its main function returns 1096(explicitly or implicitly, after the last instruction); 1097and abnormally, if there is an unprotected error. 1098In case of normal termination, 1099<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>, 1100plus any values returned by the coroutine main function. 1101In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b> 1102plus the error object. 1103In this case, the coroutine does not unwind its stack, 1104so that it is possible to inspect it after the error 1105with the debug API. 1106 1107 1108<p> 1109A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 1110When a coroutine yields, 1111the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately, 1112even if the yield happens inside nested function calls 1113(that is, not in the main function, 1114but in a function directly or indirectly called by the main function). 1115In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>, 1116plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 1117The next time you resume the same coroutine, 1118it continues its execution from the point where it yielded, 1119with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra 1120arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 1121 1122 1123<p> 1124Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 1125the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine, 1126but instead of returning the coroutine itself, 1127it returns a function that, when called, resumes the coroutine. 1128Any arguments passed to this function 1129go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 1130<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>, 1131except the first one (the boolean error code). 1132Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 1133the function created by <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> 1134propagates any error to the caller. 1135In this case, 1136the function also closes the coroutine (see <a href="#pdf-coroutine.close"><code>coroutine.close</code></a>). 1137 1138 1139<p> 1140As an example of how coroutines work, 1141consider the following code: 1142 1143<pre> 1144 function foo (a) 1145 print("foo", a) 1146 return coroutine.yield(2*a) 1147 end 1148 1149 co = coroutine.create(function (a,b) 1150 print("co-body", a, b) 1151 local r = foo(a+1) 1152 print("co-body", r) 1153 local r, s = coroutine.yield(a+b, a-b) 1154 print("co-body", r, s) 1155 return b, "end" 1156 end) 1157 1158 print("main", coroutine.resume(co, 1, 10)) 1159 print("main", coroutine.resume(co, "r")) 1160 print("main", coroutine.resume(co, "x", "y")) 1161 print("main", coroutine.resume(co, "x", "y")) 1162</pre><p> 1163When you run it, it produces the following output: 1164 1165<pre> 1166 co-body 1 10 1167 foo 2 1168 main true 4 1169 co-body r 1170 main true 11 -9 1171 co-body x y 1172 main true 10 end 1173 main false cannot resume dead coroutine 1174</pre> 1175 1176<p> 1177You can also create and manipulate coroutines through the C API: 1178see functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>, 1179and <a href="#lua_yield"><code>lua_yield</code></a>. 1180 1181 1182 1183 1184 1185<h1>3 – <a name="3">The Language</a></h1> 1186 1187 1188 1189<p> 1190This section describes the lexis, the syntax, and the semantics of Lua. 1191In other words, 1192this section describes 1193which tokens are valid, 1194how they can be combined, 1195and what their combinations mean. 1196 1197 1198<p> 1199Language constructs will be explained using the usual extended BNF notation, 1200in which 1201{<em>a</em>} means 0 or more <em>a</em>'s, and 1202[<em>a</em>] means an optional <em>a</em>. 1203Non-terminals are shown like non-terminal, 1204keywords are shown like <b>kword</b>, 1205and other terminal symbols are shown like ‘<b>=</b>’. 1206The complete syntax of Lua can be found in <a href="#9">§9</a> 1207at the end of this manual. 1208 1209 1210 1211 1212 1213<h2>3.1 – <a name="3.1">Lexical Conventions</a></h2> 1214 1215<p> 1216Lua is a free-form language. 1217It ignores spaces and comments between lexical elements (tokens), 1218except as delimiters between two tokens. 1219In source code, 1220Lua recognizes as spaces the standard ASCII whitespace 1221characters space, form feed, newline, 1222carriage return, horizontal tab, and vertical tab. 1223 1224 1225<p> 1226<em>Names</em> 1227(also called <em>identifiers</em>) 1228in Lua can be any string of Latin letters, 1229Arabic-Indic digits, and underscores, 1230not beginning with a digit and 1231not being a reserved word. 1232Identifiers are used to name variables, table fields, and labels. 1233 1234 1235<p> 1236The following <em>keywords</em> are reserved 1237and cannot be used as names: 1238 1239 1240<pre> 1241 and break do else elseif end 1242 false for function goto if in 1243 local nil not or repeat return 1244 then true until while 1245</pre> 1246 1247<p> 1248Lua is a case-sensitive language: 1249<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> 1250are two different, valid names. 1251As a convention, 1252programs should avoid creating 1253names that start with an underscore followed by 1254one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>). 1255 1256 1257<p> 1258The following strings denote other tokens: 1259 1260<pre> 1261 + - * / % ^ # 1262 & ~ | << >> // 1263 == ~= <= >= < > = 1264 ( ) { } [ ] :: 1265 ; : , . .. ... 1266</pre> 1267 1268<p> 1269A <em>short literal string</em> 1270can be delimited by matching single or double quotes, 1271and can contain the following C-like escape sequences: 1272'<code>\a</code>' (bell), 1273'<code>\b</code>' (backspace), 1274'<code>\f</code>' (form feed), 1275'<code>\n</code>' (newline), 1276'<code>\r</code>' (carriage return), 1277'<code>\t</code>' (horizontal tab), 1278'<code>\v</code>' (vertical tab), 1279'<code>\\</code>' (backslash), 1280'<code>\"</code>' (quotation mark [double quote]), 1281and '<code>\'</code>' (apostrophe [single quote]). 1282A backslash followed by a line break 1283results in a newline in the string. 1284The escape sequence '<code>\z</code>' skips the following span 1285of whitespace characters, 1286including line breaks; 1287it is particularly useful to break and indent a long literal string 1288into multiple lines without adding the newlines and spaces 1289into the string contents. 1290A short literal string cannot contain unescaped line breaks 1291nor escapes not forming a valid escape sequence. 1292 1293 1294<p> 1295We can specify any byte in a short literal string, 1296including embedded zeros, 1297by its numeric value. 1298This can be done 1299with the escape sequence <code>\x<em>XX</em></code>, 1300where <em>XX</em> is a sequence of exactly two hexadecimal digits, 1301or with the escape sequence <code>\<em>ddd</em></code>, 1302where <em>ddd</em> is a sequence of up to three decimal digits. 1303(Note that if a decimal escape sequence is to be followed by a digit, 1304it must be expressed using exactly three digits.) 1305 1306 1307<p> 1308The UTF-8 encoding of a Unicode character 1309can be inserted in a literal string with 1310the escape sequence <code>\u{<em>XXX</em>}</code> 1311(with mandatory enclosing braces), 1312where <em>XXX</em> is a sequence of one or more hexadecimal digits 1313representing the character code point. 1314This code point can be any value less than <em>2<sup>31</sup></em>. 1315(Lua uses the original UTF-8 specification here, 1316which is not restricted to valid Unicode code points.) 1317 1318 1319<p> 1320Literal strings can also be defined using a long format 1321enclosed by <em>long brackets</em>. 1322We define an <em>opening long bracket of level <em>n</em></em> as an opening 1323square bracket followed by <em>n</em> equal signs followed by another 1324opening square bracket. 1325So, an opening long bracket of level 0 is written as <code>[[</code>, 1326an opening long bracket of level 1 is written as <code>[=[</code>, 1327and so on. 1328A <em>closing long bracket</em> is defined similarly; 1329for instance, 1330a closing long bracket of level 4 is written as <code>]====]</code>. 1331A <em>long literal</em> starts with an opening long bracket of any level and 1332ends at the first closing long bracket of the same level. 1333It can contain any text except a closing bracket of the same level. 1334Literals in this bracketed form can run for several lines, 1335do not interpret any escape sequences, 1336and ignore long brackets of any other level. 1337Any kind of end-of-line sequence 1338(carriage return, newline, carriage return followed by newline, 1339or newline followed by carriage return) 1340is converted to a simple newline. 1341When the opening long bracket is immediately followed by a newline, 1342the newline is not included in the string. 1343 1344 1345<p> 1346As an example, in a system using ASCII 1347(in which '<code>a</code>' is coded as 97, 1348newline is coded as 10, and '<code>1</code>' is coded as 49), 1349the five literal strings below denote the same string: 1350 1351<pre> 1352 a = 'alo\n123"' 1353 a = "alo\n123\"" 1354 a = '\97lo\10\04923"' 1355 a = [[alo 1356 123"]] 1357 a = [==[ 1358 alo 1359 123"]==] 1360</pre> 1361 1362<p> 1363Any byte in a literal string not 1364explicitly affected by the previous rules represents itself. 1365However, Lua opens files for parsing in text mode, 1366and the system's file functions may have problems with 1367some control characters. 1368So, it is safer to represent 1369binary data as a quoted literal with 1370explicit escape sequences for the non-text characters. 1371 1372 1373<p> 1374A <em>numeric constant</em> (or <em>numeral</em>) 1375can be written with an optional fractional part 1376and an optional decimal exponent, 1377marked by a letter '<code>e</code>' or '<code>E</code>'. 1378Lua also accepts hexadecimal constants, 1379which start with <code>0x</code> or <code>0X</code>. 1380Hexadecimal constants also accept an optional fractional part 1381plus an optional binary exponent, 1382marked by a letter '<code>p</code>' or '<code>P</code>'. 1383 1384 1385<p> 1386A numeric constant with a radix point or an exponent 1387denotes a float; 1388otherwise, 1389if its value fits in an integer or it is a hexadecimal constant, 1390it denotes an integer; 1391otherwise (that is, a decimal integer numeral that overflows), 1392it denotes a float. 1393Hexadecimal numerals with neither a radix point nor an exponent 1394always denote an integer value; 1395if the value overflows, it <em>wraps around</em> 1396to fit into a valid integer. 1397 1398 1399<p> 1400Examples of valid integer constants are 1401 1402<pre> 1403 3 345 0xff 0xBEBADA 1404</pre><p> 1405Examples of valid float constants are 1406 1407<pre> 1408 3.0 3.1416 314.16e-2 0.31416E1 34e1 1409 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 1410</pre> 1411 1412<p> 1413A <em>comment</em> starts with a double hyphen (<code>--</code>) 1414anywhere outside a string. 1415If the text immediately after <code>--</code> is not an opening long bracket, 1416the comment is a <em>short comment</em>, 1417which runs until the end of the line. 1418Otherwise, it is a <em>long comment</em>, 1419which runs until the corresponding closing long bracket. 1420 1421 1422 1423 1424 1425<h2>3.2 – <a name="3.2">Variables</a></h2> 1426 1427<p> 1428Variables are places that store values. 1429There are three kinds of variables in Lua: 1430global variables, local variables, and table fields. 1431 1432 1433<p> 1434A single name can denote a global variable or a local variable 1435(or a function's formal parameter, 1436which is a particular kind of local variable): 1437 1438<pre> 1439 var ::= Name 1440</pre><p> 1441Name denotes identifiers (see <a href="#3.1">§3.1</a>). 1442 1443 1444<p> 1445Any variable name is assumed to be global unless explicitly declared 1446as a local (see <a href="#3.3.7">§3.3.7</a>). 1447Local variables are <em>lexically scoped</em>: 1448local variables can be freely accessed by functions 1449defined inside their scope (see <a href="#3.5">§3.5</a>). 1450 1451 1452<p> 1453Before the first assignment to a variable, its value is <b>nil</b>. 1454 1455 1456<p> 1457Square brackets are used to index a table: 1458 1459<pre> 1460 var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ 1461</pre><p> 1462The meaning of accesses to table fields can be changed via metatables 1463(see <a href="#2.4">§2.4</a>). 1464 1465 1466<p> 1467The syntax <code>var.Name</code> is just syntactic sugar for 1468<code>var["Name"]</code>: 1469 1470<pre> 1471 var ::= prefixexp ‘<b>.</b>’ Name 1472</pre> 1473 1474<p> 1475An access to a global variable <code>x</code> 1476is equivalent to <code>_ENV.x</code>. 1477Due to the way that chunks are compiled, 1478the variable <code>_ENV</code> itself is never global (see <a href="#2.2">§2.2</a>). 1479 1480 1481 1482 1483 1484<h2>3.3 – <a name="3.3">Statements</a></h2> 1485 1486 1487 1488<p> 1489Lua supports an almost conventional set of statements, 1490similar to those in other conventional languages. 1491This set includes 1492blocks, assignments, control structures, function calls, 1493and variable declarations. 1494 1495 1496 1497 1498 1499<h3>3.3.1 – <a name="3.3.1">Blocks</a></h3> 1500 1501<p> 1502A block is a list of statements, 1503which are executed sequentially: 1504 1505<pre> 1506 block ::= {stat} 1507</pre><p> 1508Lua has <em>empty statements</em> 1509that allow you to separate statements with semicolons, 1510start a block with a semicolon 1511or write two semicolons in sequence: 1512 1513<pre> 1514 stat ::= ‘<b>;</b>’ 1515</pre> 1516 1517<p> 1518Both function calls and assignments 1519can start with an open parenthesis. 1520This possibility leads to an ambiguity in Lua's grammar. 1521Consider the following fragment: 1522 1523<pre> 1524 a = b + c 1525 (print or io.write)('done') 1526</pre><p> 1527The grammar could see this fragment in two ways: 1528 1529<pre> 1530 a = b + c(print or io.write)('done') 1531 1532 a = b + c; (print or io.write)('done') 1533</pre><p> 1534The current parser always sees such constructions 1535in the first way, 1536interpreting the open parenthesis 1537as the start of the arguments to a call. 1538To avoid this ambiguity, 1539it is a good practice to always precede with a semicolon 1540statements that start with a parenthesis: 1541 1542<pre> 1543 ;(print or io.write)('done') 1544</pre> 1545 1546<p> 1547A block can be explicitly delimited to produce a single statement: 1548 1549<pre> 1550 stat ::= <b>do</b> block <b>end</b> 1551</pre><p> 1552Explicit blocks are useful 1553to control the scope of variable declarations. 1554Explicit blocks are also sometimes used to 1555add a <b>return</b> statement in the middle 1556of another block (see <a href="#3.3.4">§3.3.4</a>). 1557 1558 1559 1560 1561 1562<h3>3.3.2 – <a name="3.3.2">Chunks</a></h3> 1563 1564<p> 1565The unit of compilation of Lua is called a <em>chunk</em>. 1566Syntactically, 1567a chunk is simply a block: 1568 1569<pre> 1570 chunk ::= block 1571</pre> 1572 1573<p> 1574Lua handles a chunk as the body of an anonymous function 1575with a variable number of arguments 1576(see <a href="#3.4.11">§3.4.11</a>). 1577As such, chunks can define local variables, 1578receive arguments, and return values. 1579Moreover, such anonymous function is compiled as in the 1580scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>). 1581The resulting function always has <code>_ENV</code> as its only external variable, 1582even if it does not use that variable. 1583 1584 1585<p> 1586A chunk can be stored in a file or in a string inside the host program. 1587To execute a chunk, 1588Lua first <em>loads</em> it, 1589precompiling the chunk's code into instructions for a virtual machine, 1590and then Lua executes the compiled code 1591with an interpreter for the virtual machine. 1592 1593 1594<p> 1595Chunks can also be precompiled into binary form; 1596see the program <code>luac</code> and the function <a href="#pdf-string.dump"><code>string.dump</code></a> for details. 1597Programs in source and compiled forms are interchangeable; 1598Lua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>). 1599 1600 1601 1602 1603 1604<h3>3.3.3 – <a name="3.3.3">Assignment</a></h3> 1605 1606<p> 1607Lua allows multiple assignments. 1608Therefore, the syntax for assignment 1609defines a list of variables on the left side 1610and a list of expressions on the right side. 1611The elements in both lists are separated by commas: 1612 1613<pre> 1614 stat ::= varlist ‘<b>=</b>’ explist 1615 varlist ::= var {‘<b>,</b>’ var} 1616 explist ::= exp {‘<b>,</b>’ exp} 1617</pre><p> 1618Expressions are discussed in <a href="#3.4">§3.4</a>. 1619 1620 1621<p> 1622Before the assignment, 1623the list of values is <em>adjusted</em> to the length of 1624the list of variables. 1625If there are more values than needed, 1626the excess values are thrown away. 1627If there are fewer values than needed, 1628the list is extended with <b>nil</b>'s. 1629If the list of expressions ends with a function call, 1630then all values returned by that call enter the list of values, 1631before the adjustment 1632(except when the call is enclosed in parentheses; see <a href="#3.4">§3.4</a>). 1633 1634 1635<p> 1636If a variable is both assigned and read 1637inside a multiple assignment, 1638Lua ensures all reads get the value of the variable 1639before the assignment. 1640Thus the code 1641 1642<pre> 1643 i = 3 1644 i, a[i] = i+1, 20 1645</pre><p> 1646sets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 1647because the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 1648before it is assigned 4. 1649Similarly, the line 1650 1651<pre> 1652 x, y = y, x 1653</pre><p> 1654exchanges the values of <code>x</code> and <code>y</code>, 1655and 1656 1657<pre> 1658 x, y, z = y, z, x 1659</pre><p> 1660cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 1661 1662 1663<p> 1664Note that this guarantee covers only accesses 1665syntactically inside the assignment statement. 1666If a function or a metamethod called during the assignment 1667changes the value of a variable, 1668Lua gives no guarantees about the order of that access. 1669 1670 1671<p> 1672An assignment to a global name <code>x = val</code> 1673is equivalent to the assignment 1674<code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>). 1675 1676 1677<p> 1678The meaning of assignments to table fields and 1679global variables (which are actually table fields, too) 1680can be changed via metatables (see <a href="#2.4">§2.4</a>). 1681 1682 1683 1684 1685 1686<h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p> 1687The control structures 1688<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 1689familiar syntax: 1690 1691 1692 1693 1694<pre> 1695 stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 1696 stat ::= <b>repeat</b> block <b>until</b> exp 1697 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> 1698</pre><p> 1699Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>). 1700 1701 1702<p> 1703The condition expression of a 1704control structure can return any value. 1705Both <b>false</b> and <b>nil</b> test false. 1706All values different from <b>nil</b> and <b>false</b> test true. 1707In particular, the number 0 and the empty string also test true. 1708 1709 1710<p> 1711In the <b>repeat</b>–<b>until</b> loop, 1712the inner block does not end at the <b>until</b> keyword, 1713but only after the condition. 1714So, the condition can refer to local variables 1715declared inside the loop block. 1716 1717 1718<p> 1719The <b>goto</b> statement transfers the program control to a label. 1720For syntactical reasons, 1721labels in Lua are considered statements too: 1722 1723 1724 1725<pre> 1726 stat ::= <b>goto</b> Name 1727 stat ::= label 1728 label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 1729</pre> 1730 1731<p> 1732A label is visible in the entire block where it is defined, 1733except inside nested functions. 1734A goto may jump to any visible label as long as it does not 1735enter into the scope of a local variable. 1736A label should not be declared 1737where a label with the same name is visible, 1738even if this other label has been declared in an enclosing block. 1739 1740 1741<p> 1742Labels and empty statements are called <em>void statements</em>, 1743as they perform no actions. 1744 1745 1746<p> 1747The <b>break</b> statement terminates the execution of a 1748<b>while</b>, <b>repeat</b>, or <b>for</b> loop, 1749skipping to the next statement after the loop: 1750 1751 1752<pre> 1753 stat ::= <b>break</b> 1754</pre><p> 1755A <b>break</b> ends the innermost enclosing loop. 1756 1757 1758<p> 1759The <b>return</b> statement is used to return values 1760from a function or a chunk 1761(which is handled as an anonymous function). 1762 1763Functions can return more than one value, 1764so the syntax for the <b>return</b> statement is 1765 1766<pre> 1767 stat ::= <b>return</b> [explist] [‘<b>;</b>’] 1768</pre> 1769 1770<p> 1771The <b>return</b> statement can only be written 1772as the last statement of a block. 1773If it is necessary to <b>return</b> in the middle of a block, 1774then an explicit inner block can be used, 1775as in the idiom <code>do return end</code>, 1776because now <b>return</b> is the last statement in its (inner) block. 1777 1778 1779 1780 1781 1782<h3>3.3.5 – <a name="3.3.5">For Statement</a></h3> 1783 1784<p> 1785 1786The <b>for</b> statement has two forms: 1787one numerical and one generic. 1788 1789 1790 1791<h4>The numerical <b>for</b> loop</h4> 1792 1793<p> 1794The numerical <b>for</b> loop repeats a block of code while a 1795control variable goes through an arithmetic progression. 1796It has the following syntax: 1797 1798<pre> 1799 stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> 1800</pre><p> 1801The given identifier (Name) defines the control variable, 1802which is a new variable local to the loop body (<em>block</em>). 1803 1804 1805<p> 1806The loop starts by evaluating once the three control expressions. 1807Their values are called respectively 1808the <em>initial value</em>, the <em>limit</em>, and the <em>step</em>. 1809If the step is absent, it defaults to 1. 1810 1811 1812<p> 1813If both the initial value and the step are integers, 1814the loop is done with integers; 1815note that the limit may not be an integer. 1816Otherwise, the three values are converted to 1817floats and the loop is done with floats. 1818Beware of floating-point accuracy in this case. 1819 1820 1821<p> 1822After that initialization, 1823the loop body is repeated with the value of the control variable 1824going through an arithmetic progression, 1825starting at the initial value, 1826with a common difference given by the step. 1827A negative step makes a decreasing sequence; 1828a step equal to zero raises an error. 1829The loop continues while the value is less than 1830or equal to the limit 1831(greater than or equal to for a negative step). 1832If the initial value is already greater than the limit 1833(or less than, if the step is negative), 1834the body is not executed. 1835 1836 1837<p> 1838For integer loops, 1839the control variable never wraps around; 1840instead, the loop ends in case of an overflow. 1841 1842 1843<p> 1844You should not change the value of the control variable 1845during the loop. 1846If you need its value after the loop, 1847assign it to another variable before exiting the loop. 1848 1849 1850 1851 1852 1853<h4>The generic <b>for</b> loop</h4> 1854 1855<p> 1856The generic <b>for</b> statement works over functions, 1857called <em>iterators</em>. 1858On each iteration, the iterator function is called to produce a new value, 1859stopping when this new value is <b>nil</b>. 1860The generic <b>for</b> loop has the following syntax: 1861 1862<pre> 1863 stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> 1864 namelist ::= Name {‘<b>,</b>’ Name} 1865</pre><p> 1866A <b>for</b> statement like 1867 1868<pre> 1869 for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>body</em> end 1870</pre><p> 1871works as follows. 1872 1873 1874<p> 1875The names <em>var_i</em> declare loop variables local to the loop body. 1876The first of these variables is the <em>control variable</em>. 1877 1878 1879<p> 1880The loop starts by evaluating <em>explist</em> 1881to produce four values: 1882an <em>iterator function</em>, 1883a <em>state</em>, 1884an initial value for the control variable, 1885and a <em>closing value</em>. 1886 1887 1888<p> 1889Then, at each iteration, 1890Lua calls the iterator function with two arguments: 1891the state and the control variable. 1892The results from this call are then assigned to the loop variables, 1893following the rules of multiple assignments (see <a href="#3.3.3">§3.3.3</a>). 1894If the control variable becomes <b>nil</b>, 1895the loop terminates. 1896Otherwise, the body is executed and the loop goes 1897to the next iteration. 1898 1899 1900<p> 1901The closing value behaves like a 1902to-be-closed variable (see <a href="#3.3.8">§3.3.8</a>), 1903which can be used to release resources when the loop ends. 1904Otherwise, it does not interfere with the loop. 1905 1906 1907<p> 1908You should not change the value of the control variable 1909during the loop. 1910 1911 1912 1913 1914 1915 1916 1917<h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p> 1918To allow possible side-effects, 1919function calls can be executed as statements: 1920 1921<pre> 1922 stat ::= functioncall 1923</pre><p> 1924In this case, all returned values are thrown away. 1925Function calls are explained in <a href="#3.4.10">§3.4.10</a>. 1926 1927 1928 1929 1930 1931<h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p> 1932Local variables can be declared anywhere inside a block. 1933The declaration can include an initialization: 1934 1935<pre> 1936 stat ::= <b>local</b> attnamelist [‘<b>=</b>’ explist] 1937 attnamelist ::= Name attrib {‘<b>,</b>’ Name attrib} 1938</pre><p> 1939If present, an initial assignment has the same semantics 1940of a multiple assignment (see <a href="#3.3.3">§3.3.3</a>). 1941Otherwise, all variables are initialized with <b>nil</b>. 1942 1943 1944<p> 1945Each variable name may be postfixed by an attribute 1946(a name between angle brackets): 1947 1948<pre> 1949 attrib ::= [‘<b><</b>’ Name ‘<b>></b>’] 1950</pre><p> 1951There are two possible attributes: 1952<code>const</code>, which declares a constant variable, 1953that is, a variable that cannot be assigned to 1954after its initialization; 1955and <code>close</code>, which declares a to-be-closed variable (see <a href="#3.3.8">§3.3.8</a>). 1956A list of variables can contain at most one to-be-closed variable. 1957 1958 1959<p> 1960A chunk is also a block (see <a href="#3.3.2">§3.3.2</a>), 1961and so local variables can be declared in a chunk outside any explicit block. 1962 1963 1964<p> 1965The visibility rules for local variables are explained in <a href="#3.5">§3.5</a>. 1966 1967 1968 1969 1970 1971<h3>3.3.8 – <a name="3.3.8">To-be-closed Variables</a></h3> 1972 1973<p> 1974A to-be-closed variable behaves like a constant local variable, 1975except that its value is <em>closed</em> whenever the variable 1976goes out of scope, including normal block termination, 1977exiting its block by <b>break</b>/<b>goto</b>/<b>return</b>, 1978or exiting by an error. 1979 1980 1981<p> 1982Here, to <em>close</em> a value means 1983to call its <code>__close</code> metamethod. 1984When calling the metamethod, 1985the value itself is passed as the first argument 1986and the error object that caused the exit (if any) 1987is passed as a second argument; 1988if there was no error, the second argument is <b>nil</b>. 1989 1990 1991<p> 1992The value assigned to a to-be-closed variable 1993must have a <code>__close</code> metamethod 1994or be a false value. 1995(<b>nil</b> and <b>false</b> are ignored as to-be-closed values.) 1996 1997 1998<p> 1999If several to-be-closed variables go out of scope at the same event, 2000they are closed in the reverse order that they were declared. 2001 2002 2003<p> 2004If there is any error while running a closing method, 2005that error is handled like an error in the regular code 2006where the variable was defined. 2007After an error, 2008the other pending closing methods will still be called. 2009 2010 2011<p> 2012If a coroutine yields and is never resumed again, 2013some variables may never go out of scope, 2014and therefore they will never be closed. 2015(These variables are the ones created inside the coroutine 2016and in scope at the point where the coroutine yielded.) 2017Similarly, if a coroutine ends with an error, 2018it does not unwind its stack, 2019so it does not close any variable. 2020In both cases, 2021you can either use finalizers 2022or call <a href="#pdf-coroutine.close"><code>coroutine.close</code></a> to close the variables. 2023However, if the coroutine was created 2024through <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a>, 2025then its corresponding function will close the coroutine 2026in case of errors. 2027 2028 2029 2030 2031 2032 2033 2034<h2>3.4 – <a name="3.4">Expressions</a></h2> 2035 2036 2037 2038<p> 2039The basic expressions in Lua are the following: 2040 2041<pre> 2042 exp ::= prefixexp 2043 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 2044 exp ::= Numeral 2045 exp ::= LiteralString 2046 exp ::= functiondef 2047 exp ::= tableconstructor 2048 exp ::= ‘<b>...</b>’ 2049 exp ::= exp binop exp 2050 exp ::= unop exp 2051 prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 2052</pre> 2053 2054<p> 2055Numerals and literal strings are explained in <a href="#3.1">§3.1</a>; 2056variables are explained in <a href="#3.2">§3.2</a>; 2057function definitions are explained in <a href="#3.4.11">§3.4.11</a>; 2058function calls are explained in <a href="#3.4.10">§3.4.10</a>; 2059table constructors are explained in <a href="#3.4.9">§3.4.9</a>. 2060Vararg expressions, 2061denoted by three dots ('<code>...</code>'), can only be used when 2062directly inside a vararg function; 2063they are explained in <a href="#3.4.11">§3.4.11</a>. 2064 2065 2066<p> 2067Binary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), 2068bitwise operators (see <a href="#3.4.2">§3.4.2</a>), 2069relational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>), 2070and the concatenation operator (see <a href="#3.4.6">§3.4.6</a>). 2071Unary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), 2072the unary bitwise NOT (see <a href="#3.4.2">§3.4.2</a>), 2073the unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), 2074and the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). 2075 2076 2077<p> 2078Both function calls and vararg expressions can result in multiple values. 2079If a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>), 2080then its return list is adjusted to zero elements, 2081thus discarding all returned values. 2082If an expression is used as the last (or the only) element 2083of a list of expressions, 2084then no adjustment is made 2085(unless the expression is enclosed in parentheses). 2086In all other contexts, 2087Lua adjusts the result list to one element, 2088either discarding all values except the first one 2089or adding a single <b>nil</b> if there are no values. 2090 2091 2092<p> 2093Here are some examples: 2094 2095<pre> 2096 f() -- adjusted to 0 results 2097 g(f(), x) -- f() is adjusted to 1 result 2098 g(x, f()) -- g gets x plus all results from f() 2099 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) 2100 a,b = ... -- a gets the first vararg argument, b gets 2101 -- the second (both a and b can get nil if there 2102 -- is no corresponding vararg argument) 2103 2104 a,b,c = x, f() -- f() is adjusted to 2 results 2105 a,b,c = f() -- f() is adjusted to 3 results 2106 return f() -- returns all results from f() 2107 return ... -- returns all received vararg arguments 2108 return x,y,f() -- returns x, y, and all results from f() 2109 {f()} -- creates a list with all results from f() 2110 {...} -- creates a list with all vararg arguments 2111 {f(), nil} -- f() is adjusted to 1 result 2112</pre> 2113 2114<p> 2115Any expression enclosed in parentheses always results in only one value. 2116Thus, 2117<code>(f(x,y,z))</code> is always a single value, 2118even if <code>f</code> returns several values. 2119(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> 2120or <b>nil</b> if <code>f</code> does not return any values.) 2121 2122 2123 2124 2125 2126<h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p> 2127Lua supports the following arithmetic operators: 2128 2129<ul> 2130<li><b><code>+</code>: </b>addition</li> 2131<li><b><code>-</code>: </b>subtraction</li> 2132<li><b><code>*</code>: </b>multiplication</li> 2133<li><b><code>/</code>: </b>float division</li> 2134<li><b><code>//</code>: </b>floor division</li> 2135<li><b><code>%</code>: </b>modulo</li> 2136<li><b><code>^</code>: </b>exponentiation</li> 2137<li><b><code>-</code>: </b>unary minus</li> 2138</ul> 2139 2140<p> 2141With the exception of exponentiation and float division, 2142the arithmetic operators work as follows: 2143If both operands are integers, 2144the operation is performed over integers and the result is an integer. 2145Otherwise, if both operands are numbers, 2146then they are converted to floats, 2147the operation is performed following the machine's rules 2148for floating-point arithmetic 2149(usually the IEEE 754 standard), 2150and the result is a float. 2151(The string library coerces strings to numbers in 2152arithmetic operations; see <a href="#3.4.3">§3.4.3</a> for details.) 2153 2154 2155<p> 2156Exponentiation and float division (<code>/</code>) 2157always convert their operands to floats 2158and the result is always a float. 2159Exponentiation uses the ISO C function <code>pow</code>, 2160so that it works for non-integer exponents too. 2161 2162 2163<p> 2164Floor division (<code>//</code>) is a division 2165that rounds the quotient towards minus infinity, 2166resulting in the floor of the division of its operands. 2167 2168 2169<p> 2170Modulo is defined as the remainder of a division 2171that rounds the quotient towards minus infinity (floor division). 2172 2173 2174<p> 2175In case of overflows in integer arithmetic, 2176all operations <em>wrap around</em>. 2177 2178 2179 2180<h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p> 2181Lua supports the following bitwise operators: 2182 2183<ul> 2184<li><b><code>&</code>: </b>bitwise AND</li> 2185<li><b><code>|</code>: </b>bitwise OR</li> 2186<li><b><code>~</code>: </b>bitwise exclusive OR</li> 2187<li><b><code>>></code>: </b>right shift</li> 2188<li><b><code><<</code>: </b>left shift</li> 2189<li><b><code>~</code>: </b>unary bitwise NOT</li> 2190</ul> 2191 2192<p> 2193All bitwise operations convert its operands to integers 2194(see <a href="#3.4.3">§3.4.3</a>), 2195operate on all bits of those integers, 2196and result in an integer. 2197 2198 2199<p> 2200Both right and left shifts fill the vacant bits with zeros. 2201Negative displacements shift to the other direction; 2202displacements with absolute values equal to or higher than 2203the number of bits in an integer 2204result in zero (as all bits are shifted out). 2205 2206 2207 2208 2209 2210<h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p> 2211Lua provides some automatic conversions between some 2212types and representations at run time. 2213Bitwise operators always convert float operands to integers. 2214Exponentiation and float division 2215always convert integer operands to floats. 2216All other arithmetic operations applied to mixed numbers 2217(integers and floats) convert the integer operand to a float. 2218The C API also converts both integers to floats and 2219floats to integers, as needed. 2220Moreover, string concatenation accepts numbers as arguments, 2221besides strings. 2222 2223 2224<p> 2225In a conversion from integer to float, 2226if the integer value has an exact representation as a float, 2227that is the result. 2228Otherwise, 2229the conversion gets the nearest higher or 2230the nearest lower representable value. 2231This kind of conversion never fails. 2232 2233 2234<p> 2235The conversion from float to integer 2236checks whether the float has an exact representation as an integer 2237(that is, the float has an integral value and 2238it is in the range of integer representation). 2239If it does, that representation is the result. 2240Otherwise, the conversion fails. 2241 2242 2243<p> 2244Several places in Lua coerce strings to numbers when necessary. 2245In particular, 2246the string library sets metamethods that try to coerce 2247strings to numbers in all arithmetic operations. 2248If the conversion fails, 2249the library calls the metamethod of the other operand 2250(if present) or it raises an error. 2251Note that bitwise operators do not do this coercion. 2252 2253 2254<p> 2255Nonetheless, it is always a good practice not to rely on these 2256implicit coercions, as they are not always applied; 2257in particular, <code>"1"==1</code> is false and <code>"1"<1</code> raises an error 2258(see <a href="#3.4.4">§3.4.4</a>). 2259These coercions exist mainly for compatibility and may be removed 2260in future versions of the language. 2261 2262 2263<p> 2264A string is converted to an integer or a float 2265following its syntax and the rules of the Lua lexer. 2266The string may have also leading and trailing whitespaces and a sign. 2267All conversions from strings to numbers 2268accept both a dot and the current locale mark 2269as the radix character. 2270(The Lua lexer, however, accepts only a dot.) 2271If the string is not a valid numeral, 2272the conversion fails. 2273If necessary, the result of this first step is then converted 2274to a specific number subtype following the previous rules 2275for conversions between floats and integers. 2276 2277 2278<p> 2279The conversion from numbers to strings uses a 2280non-specified human-readable format. 2281To convert numbers to strings in any specific way, 2282use the function <a href="#pdf-string.format"><code>string.format</code></a>. 2283 2284 2285 2286 2287 2288<h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p> 2289Lua supports the following relational operators: 2290 2291<ul> 2292<li><b><code>==</code>: </b>equality</li> 2293<li><b><code>~=</code>: </b>inequality</li> 2294<li><b><code><</code>: </b>less than</li> 2295<li><b><code>></code>: </b>greater than</li> 2296<li><b><code><=</code>: </b>less or equal</li> 2297<li><b><code>>=</code>: </b>greater or equal</li> 2298</ul><p> 2299These operators always result in <b>false</b> or <b>true</b>. 2300 2301 2302<p> 2303Equality (<code>==</code>) first compares the type of its operands. 2304If the types are different, then the result is <b>false</b>. 2305Otherwise, the values of the operands are compared. 2306Strings are equal if they have the same byte content. 2307Numbers are equal if they denote the same mathematical value. 2308 2309 2310<p> 2311Tables, userdata, and threads 2312are compared by reference: 2313two objects are considered equal only if they are the same object. 2314Every time you create a new object 2315(a table, a userdata, or a thread), 2316this new object is different from any previously existing object. 2317A function is always equal to itself. 2318Functions with any detectable difference 2319(different behavior, different definition) are always different. 2320Functions created at different times but with no detectable differences 2321may be classified as equal or not 2322(depending on internal caching details). 2323 2324 2325<p> 2326You can change the way that Lua compares tables and userdata 2327by using the <code>__eq</code> metamethod (see <a href="#2.4">§2.4</a>). 2328 2329 2330<p> 2331Equality comparisons do not convert strings to numbers 2332or vice versa. 2333Thus, <code>"0"==0</code> evaluates to <b>false</b>, 2334and <code>t[0]</code> and <code>t["0"]</code> denote different 2335entries in a table. 2336 2337 2338<p> 2339The operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 2340 2341 2342<p> 2343The order operators work as follows. 2344If both arguments are numbers, 2345then they are compared according to their mathematical values, 2346regardless of their subtypes. 2347Otherwise, if both arguments are strings, 2348then their values are compared according to the current locale. 2349Otherwise, Lua tries to call the <code>__lt</code> or the <code>__le</code> 2350metamethod (see <a href="#2.4">§2.4</a>). 2351A comparison <code>a > b</code> is translated to <code>b < a</code> 2352and <code>a >= b</code> is translated to <code>b <= a</code>. 2353 2354 2355<p> 2356Following the IEEE 754 standard, 2357the special value NaN is considered neither less than, 2358nor equal to, nor greater than any value, including itself. 2359 2360 2361 2362 2363 2364<h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p> 2365The logical operators in Lua are 2366<b>and</b>, <b>or</b>, and <b>not</b>. 2367Like the control structures (see <a href="#3.3.4">§3.3.4</a>), 2368all logical operators consider both <b>false</b> and <b>nil</b> as false 2369and anything else as true. 2370 2371 2372<p> 2373The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 2374The conjunction operator <b>and</b> returns its first argument 2375if this value is <b>false</b> or <b>nil</b>; 2376otherwise, <b>and</b> returns its second argument. 2377The disjunction operator <b>or</b> returns its first argument 2378if this value is different from <b>nil</b> and <b>false</b>; 2379otherwise, <b>or</b> returns its second argument. 2380Both <b>and</b> and <b>or</b> use short-circuit evaluation; 2381that is, 2382the second operand is evaluated only if necessary. 2383Here are some examples: 2384 2385<pre> 2386 10 or 20 --> 10 2387 10 or error() --> 10 2388 nil or "a" --> "a" 2389 nil and 10 --> nil 2390 false and error() --> false 2391 false and nil --> false 2392 false or nil --> nil 2393 10 and 20 --> 20 2394</pre> 2395 2396 2397 2398 2399<h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p> 2400The string concatenation operator in Lua is 2401denoted by two dots ('<code>..</code>'). 2402If both operands are strings or numbers, 2403then the numbers are converted to strings 2404in a non-specified format (see <a href="#3.4.3">§3.4.3</a>). 2405Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). 2406 2407 2408 2409 2410 2411<h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3> 2412 2413<p> 2414The length operator is denoted by the unary prefix operator <code>#</code>. 2415 2416 2417<p> 2418The length of a string is its number of bytes. 2419(That is the usual meaning of string length when each 2420character is one byte.) 2421 2422 2423<p> 2424The length operator applied on a table 2425returns a border in that table. 2426A <em>border</em> in a table <code>t</code> is any non-negative integer 2427that satisfies the following condition: 2428 2429<pre> 2430 (border == 0 or t[border] ~= nil) and 2431 (t[border + 1] == nil or border == math.maxinteger) 2432</pre><p> 2433In words, 2434a border is any positive integer index present in the table 2435that is followed by an absent index, 2436plus two limit cases: 2437zero, when index 1 is absent; 2438and the maximum value for an integer, when that index is present. 2439Note that keys that are not positive integers 2440do not interfere with borders. 2441 2442 2443<p> 2444A table with exactly one border is called a <em>sequence</em>. 2445For instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence, 2446as it has only one border (5). 2447The table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5), 2448and therefore it is not a sequence. 2449(The <b>nil</b> at index 4 is called a <em>hole</em>.) 2450The table <code>{nil, 20, 30, nil, nil, 60, nil}</code> 2451has three borders (0, 3, and 6), 2452so it is not a sequence, too. 2453The table <code>{}</code> is a sequence with border 0. 2454 2455 2456<p> 2457When <code>t</code> is a sequence, 2458<code>#t</code> returns its only border, 2459which corresponds to the intuitive notion of the length of the sequence. 2460When <code>t</code> is not a sequence, 2461<code>#t</code> can return any of its borders. 2462(The exact one depends on details of 2463the internal representation of the table, 2464which in turn can depend on how the table was populated and 2465the memory addresses of its non-numeric keys.) 2466 2467 2468<p> 2469The computation of the length of a table 2470has a guaranteed worst time of <em>O(log n)</em>, 2471where <em>n</em> is the largest integer key in the table. 2472 2473 2474<p> 2475A program can modify the behavior of the length operator for 2476any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>). 2477 2478 2479 2480 2481 2482<h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p> 2483Operator precedence in Lua follows the table below, 2484from lower to higher priority: 2485 2486<pre> 2487 or 2488 and 2489 < > <= >= ~= == 2490 | 2491 ~ 2492 & 2493 << >> 2494 .. 2495 + - 2496 * / // % 2497 unary operators (not # - ~) 2498 ^ 2499</pre><p> 2500As usual, 2501you can use parentheses to change the precedences of an expression. 2502The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 2503operators are right associative. 2504All other binary operators are left associative. 2505 2506 2507 2508 2509 2510<h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p> 2511Table constructors are expressions that create tables. 2512Every time a constructor is evaluated, a new table is created. 2513A constructor can be used to create an empty table 2514or to create a table and initialize some of its fields. 2515The general syntax for constructors is 2516 2517<pre> 2518 tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 2519 fieldlist ::= field {fieldsep field} [fieldsep] 2520 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 2521 fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 2522</pre> 2523 2524<p> 2525Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry 2526with key <code>exp1</code> and value <code>exp2</code>. 2527A field of the form <code>name = exp</code> is equivalent to 2528<code>["name"] = exp</code>. 2529Fields of the form <code>exp</code> are equivalent to 2530<code>[i] = exp</code>, where <code>i</code> are consecutive integers 2531starting with 1; 2532fields in the other formats do not affect this counting. 2533For example, 2534 2535<pre> 2536 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 2537</pre><p> 2538is equivalent to 2539 2540<pre> 2541 do 2542 local t = {} 2543 t[f(1)] = g 2544 t[1] = "x" -- 1st exp 2545 t[2] = "y" -- 2nd exp 2546 t.x = 1 -- t["x"] = 1 2547 t[3] = f(x) -- 3rd exp 2548 t[30] = 23 2549 t[4] = 45 -- 4th exp 2550 a = t 2551 end 2552</pre> 2553 2554<p> 2555The order of the assignments in a constructor is undefined. 2556(This order would be relevant only when there are repeated keys.) 2557 2558 2559<p> 2560If the last field in the list has the form <code>exp</code> 2561and the expression is a function call or a vararg expression, 2562then all values returned by this expression enter the list consecutively 2563(see <a href="#3.4.10">§3.4.10</a>). 2564 2565 2566<p> 2567The field list can have an optional trailing separator, 2568as a convenience for machine-generated code. 2569 2570 2571 2572 2573 2574<h3>3.4.10 – <a name="3.4.10">Function Calls</a></h3><p> 2575A function call in Lua has the following syntax: 2576 2577<pre> 2578 functioncall ::= prefixexp args 2579</pre><p> 2580In a function call, 2581first prefixexp and args are evaluated. 2582If the value of prefixexp has type <em>function</em>, 2583then this function is called 2584with the given arguments. 2585Otherwise, if present, 2586the prefixexp <code>__call</code> metamethod is called: 2587its first argument is the value of prefixexp, 2588followed by the original call arguments 2589(see <a href="#2.4">§2.4</a>). 2590 2591 2592<p> 2593The form 2594 2595<pre> 2596 functioncall ::= prefixexp ‘<b>:</b>’ Name args 2597</pre><p> 2598can be used to emulate methods. 2599A call <code>v:name(<em>args</em>)</code> 2600is syntactic sugar for <code>v.name(v,<em>args</em>)</code>, 2601except that <code>v</code> is evaluated only once. 2602 2603 2604<p> 2605Arguments have the following syntax: 2606 2607<pre> 2608 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ 2609 args ::= tableconstructor 2610 args ::= LiteralString 2611</pre><p> 2612All argument expressions are evaluated before the call. 2613A call of the form <code>f{<em>fields</em>}</code> is 2614syntactic sugar for <code>f({<em>fields</em>})</code>; 2615that is, the argument list is a single new table. 2616A call of the form <code>f'<em>string</em>'</code> 2617(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 2618is syntactic sugar for <code>f('<em>string</em>')</code>; 2619that is, the argument list is a single literal string. 2620 2621 2622<p> 2623A call of the form <code>return <em>functioncall</em></code> not in the 2624scope of a to-be-closed variable is called a <em>tail call</em>. 2625Lua implements <em>proper tail calls</em> 2626(or <em>proper tail recursion</em>): 2627in a tail call, 2628the called function reuses the stack entry of the calling function. 2629Therefore, there is no limit on the number of nested tail calls that 2630a program can execute. 2631However, a tail call erases any debug information about the 2632calling function. 2633Note that a tail call only happens with a particular syntax, 2634where the <b>return</b> has one single function call as argument, 2635and it is outside the scope of any to-be-closed variable. 2636This syntax makes the calling function return exactly 2637the returns of the called function, 2638without any intervening action. 2639So, none of the following examples are tail calls: 2640 2641<pre> 2642 return (f(x)) -- results adjusted to 1 2643 return 2 * f(x) -- result multiplied by 2 2644 return x, f(x) -- additional results 2645 f(x); return -- results discarded 2646 return x or f(x) -- results adjusted to 1 2647</pre> 2648 2649 2650 2651 2652<h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3> 2653 2654<p> 2655The syntax for function definition is 2656 2657<pre> 2658 functiondef ::= <b>function</b> funcbody 2659 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 2660</pre> 2661 2662<p> 2663The following syntactic sugar simplifies function definitions: 2664 2665<pre> 2666 stat ::= <b>function</b> funcname funcbody 2667 stat ::= <b>local</b> <b>function</b> Name funcbody 2668 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 2669</pre><p> 2670The statement 2671 2672<pre> 2673 function f () <em>body</em> end 2674</pre><p> 2675translates to 2676 2677<pre> 2678 f = function () <em>body</em> end 2679</pre><p> 2680The statement 2681 2682<pre> 2683 function t.a.b.c.f () <em>body</em> end 2684</pre><p> 2685translates to 2686 2687<pre> 2688 t.a.b.c.f = function () <em>body</em> end 2689</pre><p> 2690The statement 2691 2692<pre> 2693 local function f () <em>body</em> end 2694</pre><p> 2695translates to 2696 2697<pre> 2698 local f; f = function () <em>body</em> end 2699</pre><p> 2700not to 2701 2702<pre> 2703 local f = function () <em>body</em> end 2704</pre><p> 2705(This only makes a difference when the body of the function 2706contains references to <code>f</code>.) 2707 2708 2709<p> 2710A function definition is an executable expression, 2711whose value has type <em>function</em>. 2712When Lua precompiles a chunk, 2713all its function bodies are precompiled too, 2714but they are not created yet. 2715Then, whenever Lua executes the function definition, 2716the function is <em>instantiated</em> (or <em>closed</em>). 2717This function instance, or <em>closure</em>, 2718is the final value of the expression. 2719 2720 2721<p> 2722Parameters act as local variables that are 2723initialized with the argument values: 2724 2725<pre> 2726 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 2727</pre><p> 2728When a Lua function is called, 2729it adjusts its list of arguments to 2730the length of its list of parameters, 2731unless the function is a <em>vararg function</em>, 2732which is indicated by three dots ('<code>...</code>') 2733at the end of its parameter list. 2734A vararg function does not adjust its argument list; 2735instead, it collects all extra arguments and supplies them 2736to the function through a <em>vararg expression</em>, 2737which is also written as three dots. 2738The value of this expression is a list of all actual extra arguments, 2739similar to a function with multiple results. 2740If a vararg expression is used inside another expression 2741or in the middle of a list of expressions, 2742then its return list is adjusted to one element. 2743If the expression is used as the last element of a list of expressions, 2744then no adjustment is made 2745(unless that last expression is enclosed in parentheses). 2746 2747 2748<p> 2749As an example, consider the following definitions: 2750 2751<pre> 2752 function f(a, b) end 2753 function g(a, b, ...) end 2754 function r() return 1,2,3 end 2755</pre><p> 2756Then, we have the following mapping from arguments to parameters and 2757to the vararg expression: 2758 2759<pre> 2760 CALL PARAMETERS 2761 2762 f(3) a=3, b=nil 2763 f(3, 4) a=3, b=4 2764 f(3, 4, 5) a=3, b=4 2765 f(r(), 10) a=1, b=10 2766 f(r()) a=1, b=2 2767 2768 g(3) a=3, b=nil, ... --> (nothing) 2769 g(3, 4) a=3, b=4, ... --> (nothing) 2770 g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 2771 g(5, r()) a=5, b=1, ... --> 2 3 2772</pre> 2773 2774<p> 2775Results are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>). 2776If control reaches the end of a function 2777without encountering a <b>return</b> statement, 2778then the function returns with no results. 2779 2780 2781<p> 2782 2783There is a system-dependent limit on the number of values 2784that a function may return. 2785This limit is guaranteed to be greater than 1000. 2786 2787 2788<p> 2789The <em>colon</em> syntax 2790is used to emulate <em>methods</em>, 2791adding an implicit extra parameter <code>self</code> to the function. 2792Thus, the statement 2793 2794<pre> 2795 function t.a.b.c:f (<em>params</em>) <em>body</em> end 2796</pre><p> 2797is syntactic sugar for 2798 2799<pre> 2800 t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end 2801</pre> 2802 2803 2804 2805 2806 2807 2808<h2>3.5 – <a name="3.5">Visibility Rules</a></h2> 2809 2810<p> 2811 2812Lua is a lexically scoped language. 2813The scope of a local variable begins at the first statement after 2814its declaration and lasts until the last non-void statement 2815of the innermost block that includes the declaration. 2816Consider the following example: 2817 2818<pre> 2819 x = 10 -- global variable 2820 do -- new block 2821 local x = x -- new 'x', with value 10 2822 print(x) --> 10 2823 x = x+1 2824 do -- another block 2825 local x = x+1 -- another 'x' 2826 print(x) --> 12 2827 end 2828 print(x) --> 11 2829 end 2830 print(x) --> 10 (the global one) 2831</pre> 2832 2833<p> 2834Notice that, in a declaration like <code>local x = x</code>, 2835the new <code>x</code> being declared is not in scope yet, 2836and so the second <code>x</code> refers to the outside variable. 2837 2838 2839<p> 2840Because of the lexical scoping rules, 2841local variables can be freely accessed by functions 2842defined inside their scope. 2843A local variable used by an inner function is called an <em>upvalue</em> 2844(or <em>external local variable</em>, or simply <em>external variable</em>) 2845inside the inner function. 2846 2847 2848<p> 2849Notice that each execution of a <b>local</b> statement 2850defines new local variables. 2851Consider the following example: 2852 2853<pre> 2854 a = {} 2855 local x = 20 2856 for i = 1, 10 do 2857 local y = 0 2858 a[i] = function () y = y + 1; return x + y end 2859 end 2860</pre><p> 2861The loop creates ten closures 2862(that is, ten instances of the anonymous function). 2863Each of these closures uses a different <code>y</code> variable, 2864while all of them share the same <code>x</code>. 2865 2866 2867 2868 2869 2870<h1>4 – <a name="4">The Application Program Interface</a></h1> 2871 2872 2873 2874<p> 2875 2876This section describes the C API for Lua, that is, 2877the set of C functions available to the host program to communicate 2878with Lua. 2879All API functions and related types and constants 2880are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. 2881 2882 2883<p> 2884Even when we use the term "function", 2885any facility in the API may be provided as a macro instead. 2886Except where stated otherwise, 2887all such macros use each of their arguments exactly once 2888(except for the first argument, which is always a Lua state), 2889and so do not generate any hidden side-effects. 2890 2891 2892<p> 2893As in most C libraries, 2894the Lua API functions do not check their arguments 2895for validity or consistency. 2896However, you can change this behavior by compiling Lua 2897with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined. 2898 2899 2900<p> 2901The Lua library is fully reentrant: 2902it has no global variables. 2903It keeps all information it needs in a dynamic structure, 2904called the <em>Lua state</em>. 2905 2906 2907<p> 2908Each Lua state has one or more threads, 2909which correspond to independent, cooperative lines of execution. 2910The type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread. 2911(Indirectly, through the thread, it also refers to the 2912Lua state associated to the thread.) 2913 2914 2915<p> 2916A pointer to a thread must be passed as the first argument to 2917every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 2918which creates a Lua state from scratch and returns a pointer 2919to the <em>main thread</em> in the new state. 2920 2921 2922 2923 2924 2925<h2>4.1 – <a name="4.1">The Stack</a></h2> 2926 2927 2928 2929<p> 2930Lua uses a <em>virtual stack</em> to pass values to and from C. 2931Each element in this stack represents a Lua value 2932(<b>nil</b>, number, string, etc.). 2933Functions in the API can access this stack through the 2934Lua state parameter that they receive. 2935 2936 2937<p> 2938Whenever Lua calls C, the called function gets a new stack, 2939which is independent of previous stacks and of stacks of 2940C functions that are still active. 2941This stack initially contains any arguments to the C function 2942and it is where the C function can store temporary 2943Lua values and must push its results 2944to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 2945 2946 2947<p> 2948For convenience, 2949most query operations in the API do not follow a strict stack discipline. 2950Instead, they can refer to any element in the stack 2951by using an <em>index</em>: 2952A positive index represents an absolute stack position, 2953starting at 1 as the bottom of the stack; 2954a negative index represents an offset relative to the top of the stack. 2955More specifically, if the stack has <em>n</em> elements, 2956then index 1 represents the first element 2957(that is, the element that was pushed onto the stack first) 2958and 2959index <em>n</em> represents the last element; 2960index -1 also represents the last element 2961(that is, the element at the top) 2962and index <em>-n</em> represents the first element. 2963 2964 2965 2966 2967 2968<h3>4.1.1 – <a name="4.1.1">Stack Size</a></h3> 2969 2970<p> 2971When you interact with the Lua API, 2972you are responsible for ensuring consistency. 2973In particular, 2974<em>you are responsible for controlling stack overflow</em>. 2975When you call any API function, 2976you must ensure the stack has enough room to accommodate the results. 2977 2978 2979<p> 2980There is one exception to the above rule: 2981When you call a Lua function 2982without a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>), 2983Lua ensures that the stack has enough space for all results. 2984However, it does not ensure any extra space. 2985So, before pushing anything on the stack after such a call 2986you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>. 2987 2988 2989<p> 2990Whenever Lua calls C, 2991it ensures that the stack has space for 2992at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra elements; 2993that is, you can safely push up to <code>LUA_MINSTACK</code> values into it. 2994<code>LUA_MINSTACK</code> is defined as 20, 2995so that usually you do not have to worry about stack space 2996unless your code has loops pushing elements onto the stack. 2997Whenever necessary, 2998you can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> 2999to ensure that the stack has enough space for pushing new elements. 3000 3001 3002 3003 3004 3005<h3>4.1.2 – <a name="4.1.2">Valid and Acceptable Indices</a></h3> 3006 3007<p> 3008Any function in the API that receives stack indices 3009works only with <em>valid indices</em> or <em>acceptable indices</em>. 3010 3011 3012<p> 3013A <em>valid index</em> is an index that refers to a 3014position that stores a modifiable Lua value. 3015It comprises stack indices between 1 and the stack top 3016(<code>1 ≤ abs(index) ≤ top</code>) 3017 3018plus <em>pseudo-indices</em>, 3019which represent some positions that are accessible to C code 3020but that are not in the stack. 3021Pseudo-indices are used to access the registry (see <a href="#4.3">§4.3</a>) 3022and the upvalues of a C function (see <a href="#4.2">§4.2</a>). 3023 3024 3025<p> 3026Functions that do not need a specific mutable position, 3027but only a value (e.g., query functions), 3028can be called with acceptable indices. 3029An <em>acceptable index</em> can be any valid index, 3030but it also can be any positive index after the stack top 3031within the space allocated for the stack, 3032that is, indices up to the stack size. 3033(Note that 0 is never an acceptable index.) 3034Indices to upvalues (see <a href="#4.2">§4.2</a>) greater than the real number 3035of upvalues in the current C function are also acceptable (but invalid). 3036Except when noted otherwise, 3037functions in the API work with acceptable indices. 3038 3039 3040<p> 3041Acceptable indices serve to avoid extra tests 3042against the stack top when querying the stack. 3043For instance, a C function can query its third argument 3044without the need to check whether there is a third argument, 3045that is, without the need to check whether 3 is a valid index. 3046 3047 3048<p> 3049For functions that can be called with acceptable indices, 3050any non-valid index is treated as if it 3051contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>, 3052which behaves like a nil value. 3053 3054 3055 3056 3057 3058<h3>4.1.3 – <a name="4.1.3">Pointers to strings</a></h3> 3059 3060<p> 3061Several functions in the API return pointers (<code>const char*</code>) 3062to Lua strings in the stack. 3063(See <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>, 3064<a href="#lua_pushstring"><code>lua_pushstring</code></a>, and <a href="#lua_tolstring"><code>lua_tolstring</code></a>. 3065See also <a href="#luaL_checklstring"><code>luaL_checklstring</code></a>, <a href="#luaL_checkstring"><code>luaL_checkstring</code></a>, 3066and <a href="#luaL_tolstring"><code>luaL_tolstring</code></a> in the auxiliary library.) 3067 3068 3069<p> 3070In general, 3071Lua's garbage collection can free or move internal memory 3072and then invalidate pointers to internal strings. 3073To allow a safe use of these pointers, 3074The API guarantees that any pointer to a string in a stack index 3075is valid while the string value at that index is not removed from the stack. 3076(It can be moved to another index, though.) 3077When the index is a pseudo-index (referring to an upvalue), 3078the pointer is valid while the corresponding call is active and 3079the corresponding upvalue is not modified. 3080 3081 3082<p> 3083Some functions in the debug interface 3084also return pointers to strings, 3085namely <a href="#lua_getlocal"><code>lua_getlocal</code></a>, <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, 3086<a href="#lua_setlocal"><code>lua_setlocal</code></a>, and <a href="#lua_setupvalue"><code>lua_setupvalue</code></a>. 3087For these functions, the pointer is guaranteed to 3088be valid while the caller function is active and 3089the given closure (if one was given) is in the stack. 3090 3091 3092<p> 3093Except for these guarantees, 3094the garbage collector is free to invalidate 3095any pointer to internal strings. 3096 3097 3098 3099 3100 3101 3102 3103<h2>4.2 – <a name="4.2">C Closures</a></h2> 3104 3105<p> 3106When a C function is created, 3107it is possible to associate some values with it, 3108thus creating a <em>C closure</em> 3109(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>); 3110these values are called <em>upvalues</em> and are 3111accessible to the function whenever it is called. 3112 3113 3114<p> 3115Whenever a C function is called, 3116its upvalues are located at specific pseudo-indices. 3117These pseudo-indices are produced by the macro 3118<a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>. 3119The first upvalue associated with a function is at index 3120<code>lua_upvalueindex(1)</code>, and so on. 3121Any access to <code>lua_upvalueindex(<em>n</em>)</code>, 3122where <em>n</em> is greater than the number of upvalues of the 3123current function 3124(but not greater than 256, 3125which is one plus the maximum number of upvalues in a closure), 3126produces an acceptable but invalid index. 3127 3128 3129<p> 3130A C closure can also change the values 3131of its corresponding upvalues. 3132 3133 3134 3135 3136 3137<h2>4.3 – <a name="4.3">Registry</a></h2> 3138 3139<p> 3140Lua provides a <em>registry</em>, 3141a predefined table that can be used by any C code to 3142store whatever Lua values it needs to store. 3143The registry table is always accessible at pseudo-index 3144<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. 3145Any C library can store data into this table, 3146but it must take care to choose keys 3147that are different from those used 3148by other libraries, to avoid collisions. 3149Typically, you should use as key a string containing your library name, 3150or a light userdata with the address of a C object in your code, 3151or any Lua object created by your code. 3152As with variable names, 3153string keys starting with an underscore followed by 3154uppercase letters are reserved for Lua. 3155 3156 3157<p> 3158The integer keys in the registry are used 3159by the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>) 3160and by some predefined values. 3161Therefore, integer keys in the registry 3162must not be used for other purposes. 3163 3164 3165<p> 3166When you create a new Lua state, 3167its registry comes with some predefined values. 3168These predefined values are indexed with integer keys 3169defined as constants in <code>lua.h</code>. 3170The following constants are defined: 3171 3172<ul> 3173<li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has 3174the main thread of the state. 3175(The main thread is the one created together with the state.) 3176</li> 3177 3178<li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has 3179the global environment. 3180</li> 3181</ul> 3182 3183 3184 3185 3186<h2>4.4 – <a name="4.4">Error Handling in C</a></h2> 3187 3188 3189 3190<p> 3191Internally, Lua uses the C <code>longjmp</code> facility to handle errors. 3192(Lua will use exceptions if you compile it as C++; 3193search for <code>LUAI_THROW</code> in the source code for details.) 3194When Lua faces any error, 3195such as a memory allocation error or a type error, 3196it <em>raises</em> an error; 3197that is, it does a long jump. 3198A <em>protected environment</em> uses <code>setjmp</code> 3199to set a recovery point; 3200any error jumps to the most recent active recovery point. 3201 3202 3203<p> 3204Inside a C function you can raise an error explicitly 3205by calling <a href="#lua_error"><code>lua_error</code></a>. 3206 3207 3208<p> 3209Most functions in the API can raise an error, 3210for instance due to a memory allocation error. 3211The documentation for each function indicates whether 3212it can raise errors. 3213 3214 3215<p> 3216If an error happens outside any protected environment, 3217Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) 3218and then calls <code>abort</code>, 3219thus exiting the host application. 3220Your panic function can avoid this exit by 3221never returning 3222(e.g., doing a long jump to your own recovery point outside Lua). 3223 3224 3225<p> 3226The panic function, 3227as its name implies, 3228is a mechanism of last resort. 3229Programs should avoid it. 3230As a general rule, 3231when a C function is called by Lua with a Lua state, 3232it can do whatever it wants on that Lua state, 3233as it should be already protected. 3234However, 3235when C code operates on other Lua states 3236(e.g., a Lua-state argument to the function, 3237a Lua state stored in the registry, or 3238the result of <a href="#lua_newthread"><code>lua_newthread</code></a>), 3239it should use them only in API calls that cannot raise errors. 3240 3241 3242<p> 3243The panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>); 3244in particular, the error object is on the top of the stack. 3245However, there is no guarantee about stack space. 3246To push anything on the stack, 3247the panic function must first check the available space (see <a href="#4.1.1">§4.1.1</a>). 3248 3249 3250 3251 3252 3253<h3>4.4.1 – <a name="4.4.1">Status Codes</a></h3> 3254 3255<p> 3256Several functions that report errors in the API use the following 3257status codes to indicate different kinds of errors or other conditions: 3258 3259<ul> 3260 3261<li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> no errors.</li> 3262 3263<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b> a runtime error.</li> 3264 3265<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 3266memory allocation error. 3267For such errors, Lua does not call the message handler. 3268</li> 3269 3270<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b> error while running the message handler.</li> 3271 3272<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> syntax error during precompilation.</li> 3273 3274<li><b><a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a>: </b> the thread (coroutine) yields.</li> 3275 3276<li><b><a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>: </b> a file-related error; 3277e.g., it cannot open or read the file.</li> 3278 3279</ul><p> 3280These constants are defined in the header file <code>lua.h</code>. 3281 3282 3283 3284 3285 3286 3287 3288<h2>4.5 – <a name="4.5">Handling Yields in C</a></h2> 3289 3290<p> 3291Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine. 3292Therefore, if a C function <code>foo</code> calls an API function 3293and this API function yields 3294(directly or indirectly by calling another function that yields), 3295Lua cannot return to <code>foo</code> any more, 3296because the <code>longjmp</code> removes its frame from the C stack. 3297 3298 3299<p> 3300To avoid this kind of problem, 3301Lua raises an error whenever it tries to yield across an API call, 3302except for three functions: 3303<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>. 3304All those functions receive a <em>continuation function</em> 3305(as a parameter named <code>k</code>) to continue execution after a yield. 3306 3307 3308<p> 3309We need to set some terminology to explain continuations. 3310We have a C function called from Lua which we will call 3311the <em>original function</em>. 3312This original function then calls one of those three functions in the C API, 3313which we will call the <em>callee function</em>, 3314that then yields the current thread. 3315This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 3316or 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> 3317and the function called by them yields. 3318 3319 3320<p> 3321Suppose the running thread yields while executing the callee function. 3322After the thread resumes, 3323it eventually will finish running the callee function. 3324However, 3325the callee function cannot return to the original function, 3326because its frame in the C stack was destroyed by the yield. 3327Instead, Lua calls a <em>continuation function</em>, 3328which was given as an argument to the callee function. 3329As the name implies, 3330the continuation function should continue the task 3331of the original function. 3332 3333 3334<p> 3335As an illustration, consider the following function: 3336 3337<pre> 3338 int original_function (lua_State *L) { 3339 ... /* code 1 */ 3340 status = lua_pcall(L, n, m, h); /* calls Lua */ 3341 ... /* code 2 */ 3342 } 3343</pre><p> 3344Now we want to allow 3345the Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield. 3346First, we can rewrite our function like here: 3347 3348<pre> 3349 int k (lua_State *L, int status, lua_KContext ctx) { 3350 ... /* code 2 */ 3351 } 3352 3353 int original_function (lua_State *L) { 3354 ... /* code 1 */ 3355 return k(L, lua_pcall(L, n, m, h), ctx); 3356 } 3357</pre><p> 3358In the above code, 3359the new function <code>k</code> is a 3360<em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>), 3361which should do all the work that the original function 3362was doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>. 3363Now, we must inform Lua that it must call <code>k</code> if the Lua code 3364being executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way 3365(errors or yielding), 3366so we rewrite the code as here, 3367replacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>: 3368 3369<pre> 3370 int original_function (lua_State *L) { 3371 ... /* code 1 */ 3372 return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1); 3373 } 3374</pre><p> 3375Note the external, explicit call to the continuation: 3376Lua will call the continuation only if needed, that is, 3377in case of errors or resuming after a yield. 3378If the called function returns normally without ever yielding, 3379<a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally. 3380(Of course, instead of calling the continuation in that case, 3381you can do the equivalent work directly inside the original function.) 3382 3383 3384<p> 3385Besides the Lua state, 3386the continuation function has two other parameters: 3387the final status of the call and the context value (<code>ctx</code>) that 3388was passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>. 3389Lua does not use this context value; 3390it only passes this value from the original function to the 3391continuation function. 3392For <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 3393the status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 3394except that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield 3395(instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>). 3396For <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>, 3397the status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation. 3398(For these two functions, 3399Lua will not call the continuation in case of errors, 3400because they do not handle errors.) 3401Similarly, when using <a href="#lua_callk"><code>lua_callk</code></a>, 3402you should call the continuation function 3403with <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status. 3404(For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling 3405directly the continuation function, 3406because <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.) 3407 3408 3409<p> 3410Lua treats the continuation function as if it were the original function. 3411The continuation function receives the same Lua stack 3412from the original function, 3413in the same state it would be if the callee function had returned. 3414(For instance, 3415after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are 3416removed from the stack and replaced by the results from the call.) 3417It also has the same upvalues. 3418Whatever it returns is handled by Lua as if it were the return 3419of the original function. 3420 3421 3422 3423 3424 3425<h2>4.6 – <a name="4.6">Functions and Types</a></h2> 3426 3427<p> 3428Here we list all functions and types from the C API in 3429alphabetical order. 3430Each function has an indicator like this: 3431<span class="apii">[-o, +p, <em>x</em>]</span> 3432 3433 3434<p> 3435The first field, <code>o</code>, 3436is how many elements the function pops from the stack. 3437The second field, <code>p</code>, 3438is how many elements the function pushes onto the stack. 3439(Any function always pushes its results after popping its arguments.) 3440A field in the form <code>x|y</code> means the function can push (or pop) 3441<code>x</code> or <code>y</code> elements, 3442depending on the situation; 3443an interrogation mark '<code>?</code>' means that 3444we cannot know how many elements the function pops/pushes 3445by looking only at its arguments. 3446(For instance, they may depend on what is in the stack.) 3447The third field, <code>x</code>, 3448tells whether the function may raise errors: 3449'<code>-</code>' means the function never raises any error; 3450'<code>m</code>' means the function may raise only out-of-memory errors; 3451'<code>v</code>' means the function may raise the errors explained in the text; 3452'<code>e</code>' means the function can run arbitrary Lua code, 3453either directly or through metamethods, 3454and therefore may raise any errors. 3455 3456 3457 3458<hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p> 3459<span class="apii">[-0, +0, –]</span> 3460<pre>int lua_absindex (lua_State *L, int idx);</pre> 3461 3462<p> 3463Converts the acceptable index <code>idx</code> 3464into an equivalent absolute index 3465(that is, one that does not depend on the stack size). 3466 3467 3468 3469 3470 3471<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> 3472<pre>typedef void * (*lua_Alloc) (void *ud, 3473 void *ptr, 3474 size_t osize, 3475 size_t nsize);</pre> 3476 3477<p> 3478The type of the memory-allocation function used by Lua states. 3479The allocator function must provide a 3480functionality similar to <code>realloc</code>, 3481but not exactly the same. 3482Its arguments are 3483<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; 3484<code>ptr</code>, a pointer to the block being allocated/reallocated/freed; 3485<code>osize</code>, the original size of the block or some code about what 3486is being allocated; 3487and <code>nsize</code>, the new size of the block. 3488 3489 3490<p> 3491When <code>ptr</code> is not <code>NULL</code>, 3492<code>osize</code> is the size of the block pointed by <code>ptr</code>, 3493that is, the size given when it was allocated or reallocated. 3494 3495 3496<p> 3497When <code>ptr</code> is <code>NULL</code>, 3498<code>osize</code> encodes the kind of object that Lua is allocating. 3499<code>osize</code> is any of 3500<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>, 3501<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) 3502Lua is creating a new object of that type. 3503When <code>osize</code> is some other value, 3504Lua is allocating memory for something else. 3505 3506 3507<p> 3508Lua assumes the following behavior from the allocator function: 3509 3510 3511<p> 3512When <code>nsize</code> is zero, 3513the allocator must behave like <code>free</code> 3514and then return <code>NULL</code>. 3515 3516 3517<p> 3518When <code>nsize</code> is not zero, 3519the allocator must behave like <code>realloc</code>. 3520In particular, the allocator returns <code>NULL</code> 3521if and only if it cannot fulfill the request. 3522 3523 3524<p> 3525Here is a simple implementation for the allocator function. 3526It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. 3527 3528<pre> 3529 static void *l_alloc (void *ud, void *ptr, size_t osize, 3530 size_t nsize) { 3531 (void)ud; (void)osize; /* not used */ 3532 if (nsize == 0) { 3533 free(ptr); 3534 return NULL; 3535 } 3536 else 3537 return realloc(ptr, nsize); 3538 } 3539</pre><p> 3540Note that Standard C ensures 3541that <code>free(NULL)</code> has no effect and that 3542<code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>. 3543 3544 3545 3546 3547 3548<hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p> 3549<span class="apii">[-(2|1), +1, <em>e</em>]</span> 3550<pre>void lua_arith (lua_State *L, int op);</pre> 3551 3552<p> 3553Performs an arithmetic or bitwise operation over the two values 3554(or one, in the case of negations) 3555at the top of the stack, 3556with the value on the top being the second operand, 3557pops these values, and pushes the result of the operation. 3558The function follows the semantics of the corresponding Lua operator 3559(that is, it may call metamethods). 3560 3561 3562<p> 3563The value of <code>op</code> must be one of the following constants: 3564 3565<ul> 3566 3567<li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li> 3568<li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li> 3569<li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li> 3570<li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li> 3571<li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li> 3572<li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li> 3573<li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li> 3574<li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li> 3575<li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li> 3576<li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&</code>)</li> 3577<li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li> 3578<li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li> 3579<li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li> 3580<li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li> 3581 3582</ul> 3583 3584 3585 3586 3587<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> 3588<span class="apii">[-0, +0, –]</span> 3589<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> 3590 3591<p> 3592Sets a new panic function and returns the old one (see <a href="#4.4">§4.4</a>). 3593 3594 3595 3596 3597 3598<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> 3599<span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span> 3600<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> 3601 3602<p> 3603Calls a function. 3604Like regular Lua calls, 3605<code>lua_call</code> respects the <code>__call</code> metamethod. 3606So, here the word "function" 3607means any callable value. 3608 3609 3610<p> 3611To do a call you must use the following protocol: 3612first, the function to be called is pushed onto the stack; 3613then, the arguments to the call are pushed 3614in direct order; 3615that is, the first argument is pushed first. 3616Finally you call <a href="#lua_call"><code>lua_call</code></a>; 3617<code>nargs</code> is the number of arguments that you pushed onto the stack. 3618When the function returns, 3619all arguments and the function value are popped 3620and the call results are pushed onto the stack. 3621The number of results is adjusted to <code>nresults</code>, 3622unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. 3623In this case, all results from the function are pushed; 3624Lua takes care that the returned values fit into the stack space, 3625but it does not ensure any extra space in the stack. 3626The function results are pushed onto the stack in direct order 3627(the first result is pushed first), 3628so that after the call the last result is on the top of the stack. 3629 3630 3631<p> 3632Any error while calling and running the function is propagated upwards 3633(with a <code>longjmp</code>). 3634 3635 3636<p> 3637The following example shows how the host program can do the 3638equivalent to this Lua code: 3639 3640<pre> 3641 a = f("how", t.x, 14) 3642</pre><p> 3643Here it is in C: 3644 3645<pre> 3646 lua_getglobal(L, "f"); /* function to be called */ 3647 lua_pushliteral(L, "how"); /* 1st argument */ 3648 lua_getglobal(L, "t"); /* table to be indexed */ 3649 lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 3650 lua_remove(L, -2); /* remove 't' from the stack */ 3651 lua_pushinteger(L, 14); /* 3rd argument */ 3652 lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ 3653 lua_setglobal(L, "a"); /* set global 'a' */ 3654</pre><p> 3655Note that the code above is <em>balanced</em>: 3656at its end, the stack is back to its original configuration. 3657This is considered good programming practice. 3658 3659 3660 3661 3662 3663<hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p> 3664<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> 3665<pre>void lua_callk (lua_State *L, 3666 int nargs, 3667 int nresults, 3668 lua_KContext ctx, 3669 lua_KFunction k);</pre> 3670 3671<p> 3672This function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>, 3673but allows the called function to yield (see <a href="#4.5">§4.5</a>). 3674 3675 3676 3677 3678 3679<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> 3680<pre>typedef int (*lua_CFunction) (lua_State *L);</pre> 3681 3682<p> 3683Type for C functions. 3684 3685 3686<p> 3687In order to communicate properly with Lua, 3688a C function must use the following protocol, 3689which defines the way parameters and results are passed: 3690a C function receives its arguments from Lua in its stack 3691in direct order (the first argument is pushed first). 3692So, when the function starts, 3693<code>lua_gettop(L)</code> returns the number of arguments received by the function. 3694The first argument (if any) is at index 1 3695and its last argument is at index <code>lua_gettop(L)</code>. 3696To return values to Lua, a C function just pushes them onto the stack, 3697in direct order (the first result is pushed first), 3698and returns in C the number of results. 3699Any other value in the stack below the results will be properly 3700discarded by Lua. 3701Like a Lua function, a C function called by Lua can also return 3702many results. 3703 3704 3705<p> 3706As an example, the following function receives a variable number 3707of numeric arguments and returns their average and their sum: 3708 3709<pre> 3710 static int foo (lua_State *L) { 3711 int n = lua_gettop(L); /* number of arguments */ 3712 lua_Number sum = 0.0; 3713 int i; 3714 for (i = 1; i <= n; i++) { 3715 if (!lua_isnumber(L, i)) { 3716 lua_pushliteral(L, "incorrect argument"); 3717 lua_error(L); 3718 } 3719 sum += lua_tonumber(L, i); 3720 } 3721 lua_pushnumber(L, sum/n); /* first result */ 3722 lua_pushnumber(L, sum); /* second result */ 3723 return 2; /* number of results */ 3724 } 3725</pre> 3726 3727 3728 3729 3730<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> 3731<span class="apii">[-0, +0, –]</span> 3732<pre>int lua_checkstack (lua_State *L, int n);</pre> 3733 3734<p> 3735Ensures that the stack has space for at least <code>n</code> extra elements, 3736that is, that you can safely push up to <code>n</code> values into it. 3737It returns false if it cannot fulfill the request, 3738either because it would cause the stack 3739to be greater than a fixed maximum size 3740(typically at least several thousand elements) or 3741because it cannot allocate memory for the extra space. 3742This function never shrinks the stack; 3743if the stack already has space for the extra elements, 3744it is left unchanged. 3745 3746 3747 3748 3749 3750<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> 3751<span class="apii">[-0, +0, –]</span> 3752<pre>void lua_close (lua_State *L);</pre> 3753 3754<p> 3755Close all active to-be-closed variables in the main thread, 3756release all objects in the given Lua state 3757(calling the corresponding garbage-collection metamethods, if any), 3758and frees all dynamic memory used by this state. 3759 3760 3761<p> 3762On several platforms, you may not need to call this function, 3763because all resources are naturally released when the host program ends. 3764On the other hand, long-running programs that create multiple states, 3765such as daemons or web servers, 3766will probably need to close states as soon as they are not needed. 3767 3768 3769 3770 3771 3772<hr><h3><a name="lua_closeslot"><code>lua_closeslot</code></a></h3><p> 3773<span class="apii">[-0, +0, <em>e</em>]</span> 3774<pre>void lua_closeslot (lua_State *L, int index);</pre> 3775 3776<p> 3777Close the to-be-closed slot at the given index and set its value to <b>nil</b>. 3778The index must be the last index previously marked to be closed 3779(see <a href="#lua_toclose"><code>lua_toclose</code></a>) that is still active (that is, not closed yet). 3780 3781 3782<p> 3783A <code>__close</code> metamethod cannot yield 3784when called through this function. 3785 3786 3787<p> 3788(Exceptionally, this function was introduced in release 5.4.3. 3789It is not present in previous 5.4 releases.) 3790 3791 3792 3793 3794 3795<hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p> 3796<span class="apii">[-0, +0, <em>e</em>]</span> 3797<pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre> 3798 3799<p> 3800Compares two Lua values. 3801Returns 1 if the value at index <code>index1</code> satisfies <code>op</code> 3802when compared with the value at index <code>index2</code>, 3803following the semantics of the corresponding Lua operator 3804(that is, it may call metamethods). 3805Otherwise returns 0. 3806Also returns 0 if any of the indices is not valid. 3807 3808 3809<p> 3810The value of <code>op</code> must be one of the following constants: 3811 3812<ul> 3813 3814<li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li> 3815<li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li> 3816<li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li> 3817 3818</ul> 3819 3820 3821 3822 3823<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> 3824<span class="apii">[-n, +1, <em>e</em>]</span> 3825<pre>void lua_concat (lua_State *L, int n);</pre> 3826 3827<p> 3828Concatenates the <code>n</code> values at the top of the stack, 3829pops them, and leaves the result on the top. 3830If <code>n</code> is 1, the result is the single value on the stack 3831(that is, the function does nothing); 3832if <code>n</code> is 0, the result is the empty string. 3833Concatenation is performed following the usual semantics of Lua 3834(see <a href="#3.4.6">§3.4.6</a>). 3835 3836 3837 3838 3839 3840<hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p> 3841<span class="apii">[-0, +0, –]</span> 3842<pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre> 3843 3844<p> 3845Copies the element at index <code>fromidx</code> 3846into the valid index <code>toidx</code>, 3847replacing the value at that position. 3848Values at other positions are not affected. 3849 3850 3851 3852 3853 3854<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> 3855<span class="apii">[-0, +1, <em>m</em>]</span> 3856<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> 3857 3858<p> 3859Creates a new empty table and pushes it onto the stack. 3860Parameter <code>narr</code> is a hint for how many elements the table 3861will have as a sequence; 3862parameter <code>nrec</code> is a hint for how many other elements 3863the table will have. 3864Lua may use these hints to preallocate memory for the new table. 3865This preallocation may help performance when you know in advance 3866how many elements the table will have. 3867Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. 3868 3869 3870 3871 3872 3873<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> 3874<span class="apii">[-0, +0, –]</span> 3875<pre>int lua_dump (lua_State *L, 3876 lua_Writer writer, 3877 void *data, 3878 int strip);</pre> 3879 3880<p> 3881Dumps a function as a binary chunk. 3882Receives a Lua function on the top of the stack 3883and produces a binary chunk that, 3884if loaded again, 3885results in a function equivalent to the one dumped. 3886As it produces parts of the chunk, 3887<a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>) 3888with the given <code>data</code> 3889to write them. 3890 3891 3892<p> 3893If <code>strip</code> is true, 3894the binary representation may not include all debug information 3895about the function, 3896to save space. 3897 3898 3899<p> 3900The value returned is the error code returned by the last 3901call to the writer; 39020 means no errors. 3903 3904 3905<p> 3906This function does not pop the Lua function from the stack. 3907 3908 3909 3910 3911 3912<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> 3913<span class="apii">[-1, +0, <em>v</em>]</span> 3914<pre>int lua_error (lua_State *L);</pre> 3915 3916<p> 3917Raises a Lua error, 3918using the value on the top of the stack as the error object. 3919This function does a long jump, 3920and therefore never returns 3921(see <a href="#luaL_error"><code>luaL_error</code></a>). 3922 3923 3924 3925 3926 3927<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> 3928<span class="apii">[-0, +0, –]</span> 3929<pre>int lua_gc (lua_State *L, int what, ...);</pre> 3930 3931<p> 3932Controls the garbage collector. 3933 3934 3935<p> 3936This function performs several tasks, 3937according to the value of the parameter <code>what</code>. 3938For options that need extra arguments, 3939they are listed after the option. 3940 3941<ul> 3942 3943<li><b><code>LUA_GCCOLLECT</code>: </b> 3944Performs a full garbage-collection cycle. 3945</li> 3946 3947<li><b><code>LUA_GCSTOP</code>: </b> 3948Stops the garbage collector. 3949</li> 3950 3951<li><b><code>LUA_GCRESTART</code>: </b> 3952Restarts the garbage collector. 3953</li> 3954 3955<li><b><code>LUA_GCCOUNT</code>: </b> 3956Returns the current amount of memory (in Kbytes) in use by Lua. 3957</li> 3958 3959<li><b><code>LUA_GCCOUNTB</code>: </b> 3960Returns the remainder of dividing the current amount of bytes of 3961memory in use by Lua by 1024. 3962</li> 3963 3964<li><b><code>LUA_GCSTEP</code> <code>(int stepsize)</code>: </b> 3965Performs an incremental step of garbage collection, 3966corresponding to the allocation of <code>stepsize</code> Kbytes. 3967</li> 3968 3969<li><b><code>LUA_GCISRUNNING</code>: </b> 3970Returns a boolean that tells whether the collector is running 3971(i.e., not stopped). 3972</li> 3973 3974<li><b><code>LUA_GCINC</code> (int pause, int stepmul, stepsize): </b> 3975Changes the collector to incremental mode 3976with the given parameters (see <a href="#2.5.1">§2.5.1</a>). 3977Returns the previous mode (<code>LUA_GCGEN</code> or <code>LUA_GCINC</code>). 3978</li> 3979 3980<li><b><code>LUA_GCGEN</code> (int minormul, int majormul): </b> 3981Changes the collector to generational mode 3982with the given parameters (see <a href="#2.5.2">§2.5.2</a>). 3983Returns the previous mode (<code>LUA_GCGEN</code> or <code>LUA_GCINC</code>). 3984</li> 3985 3986</ul><p> 3987For more details about these options, 3988see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>. 3989 3990 3991<p> 3992This function should not be called by a finalizer. 3993 3994 3995 3996 3997 3998<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> 3999<span class="apii">[-0, +0, –]</span> 4000<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> 4001 4002<p> 4003Returns the memory-allocation function of a given state. 4004If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the 4005opaque pointer given when the memory-allocator function was set. 4006 4007 4008 4009 4010 4011<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> 4012<span class="apii">[-0, +1, <em>e</em>]</span> 4013<pre>int lua_getfield (lua_State *L, int index, const char *k);</pre> 4014 4015<p> 4016Pushes onto the stack the value <code>t[k]</code>, 4017where <code>t</code> is the value at the given index. 4018As in Lua, this function may trigger a metamethod 4019for the "index" event (see <a href="#2.4">§2.4</a>). 4020 4021 4022<p> 4023Returns the type of the pushed value. 4024 4025 4026 4027 4028 4029<hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p> 4030<span class="apii">[-0, +0, –]</span> 4031<pre>void *lua_getextraspace (lua_State *L);</pre> 4032 4033<p> 4034Returns a pointer to a raw memory area associated with the 4035given Lua state. 4036The application can use this area for any purpose; 4037Lua does not use it for anything. 4038 4039 4040<p> 4041Each new thread has this area initialized with a copy 4042of the area of the main thread. 4043 4044 4045<p> 4046By default, this area has the size of a pointer to void, 4047but you can recompile Lua with a different size for this area. 4048(See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.) 4049 4050 4051 4052 4053 4054<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> 4055<span class="apii">[-0, +1, <em>e</em>]</span> 4056<pre>int lua_getglobal (lua_State *L, const char *name);</pre> 4057 4058<p> 4059Pushes onto the stack the value of the global <code>name</code>. 4060Returns the type of that value. 4061 4062 4063 4064 4065 4066<hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p> 4067<span class="apii">[-0, +1, <em>e</em>]</span> 4068<pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre> 4069 4070<p> 4071Pushes onto the stack the value <code>t[i]</code>, 4072where <code>t</code> is the value at the given index. 4073As in Lua, this function may trigger a metamethod 4074for the "index" event (see <a href="#2.4">§2.4</a>). 4075 4076 4077<p> 4078Returns the type of the pushed value. 4079 4080 4081 4082 4083 4084<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> 4085<span class="apii">[-0, +(0|1), –]</span> 4086<pre>int lua_getmetatable (lua_State *L, int index);</pre> 4087 4088<p> 4089If the value at the given index has a metatable, 4090the function pushes that metatable onto the stack and returns 1. 4091Otherwise, 4092the function returns 0 and pushes nothing on the stack. 4093 4094 4095 4096 4097 4098<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> 4099<span class="apii">[-1, +1, <em>e</em>]</span> 4100<pre>int lua_gettable (lua_State *L, int index);</pre> 4101 4102<p> 4103Pushes onto the stack the value <code>t[k]</code>, 4104where <code>t</code> is the value at the given index 4105and <code>k</code> is the value on the top of the stack. 4106 4107 4108<p> 4109This function pops the key from the stack, 4110pushing the resulting value in its place. 4111As in Lua, this function may trigger a metamethod 4112for the "index" event (see <a href="#2.4">§2.4</a>). 4113 4114 4115<p> 4116Returns the type of the pushed value. 4117 4118 4119 4120 4121 4122<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> 4123<span class="apii">[-0, +0, –]</span> 4124<pre>int lua_gettop (lua_State *L);</pre> 4125 4126<p> 4127Returns the index of the top element in the stack. 4128Because indices start at 1, 4129this result is equal to the number of elements in the stack; 4130in particular, 0 means an empty stack. 4131 4132 4133 4134 4135 4136<hr><h3><a name="lua_getiuservalue"><code>lua_getiuservalue</code></a></h3><p> 4137<span class="apii">[-0, +1, –]</span> 4138<pre>int lua_getiuservalue (lua_State *L, int index, int n);</pre> 4139 4140<p> 4141Pushes onto the stack the <code>n</code>-th user value associated with the 4142full userdata at the given index and 4143returns the type of the pushed value. 4144 4145 4146<p> 4147If the userdata does not have that value, 4148pushes <b>nil</b> and returns <a href="#pdf-LUA_TNONE"><code>LUA_TNONE</code></a>. 4149 4150 4151 4152 4153 4154<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> 4155<span class="apii">[-1, +1, –]</span> 4156<pre>void lua_insert (lua_State *L, int index);</pre> 4157 4158<p> 4159Moves the top element into the given valid index, 4160shifting up the elements above this index to open space. 4161This function cannot be called with a pseudo-index, 4162because a pseudo-index is not an actual stack position. 4163 4164 4165 4166 4167 4168<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> 4169<pre>typedef ... lua_Integer;</pre> 4170 4171<p> 4172The type of integers in Lua. 4173 4174 4175<p> 4176By default this type is <code>long long</code>, 4177(usually a 64-bit two-complement integer), 4178but that can be changed to <code>long</code> or <code>int</code> 4179(usually a 32-bit two-complement integer). 4180(See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.) 4181 4182 4183<p> 4184Lua also defines the constants 4185<a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>, 4186with the minimum and the maximum values that fit in this type. 4187 4188 4189 4190 4191 4192<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> 4193<span class="apii">[-0, +0, –]</span> 4194<pre>int lua_isboolean (lua_State *L, int index);</pre> 4195 4196<p> 4197Returns 1 if the value at the given index is a boolean, 4198and 0 otherwise. 4199 4200 4201 4202 4203 4204<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> 4205<span class="apii">[-0, +0, –]</span> 4206<pre>int lua_iscfunction (lua_State *L, int index);</pre> 4207 4208<p> 4209Returns 1 if the value at the given index is a C function, 4210and 0 otherwise. 4211 4212 4213 4214 4215 4216<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> 4217<span class="apii">[-0, +0, –]</span> 4218<pre>int lua_isfunction (lua_State *L, int index);</pre> 4219 4220<p> 4221Returns 1 if the value at the given index is a function 4222(either C or Lua), and 0 otherwise. 4223 4224 4225 4226 4227 4228<hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p> 4229<span class="apii">[-0, +0, –]</span> 4230<pre>int lua_isinteger (lua_State *L, int index);</pre> 4231 4232<p> 4233Returns 1 if the value at the given index is an integer 4234(that is, the value is a number and is represented as an integer), 4235and 0 otherwise. 4236 4237 4238 4239 4240 4241<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> 4242<span class="apii">[-0, +0, –]</span> 4243<pre>int lua_islightuserdata (lua_State *L, int index);</pre> 4244 4245<p> 4246Returns 1 if the value at the given index is a light userdata, 4247and 0 otherwise. 4248 4249 4250 4251 4252 4253<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> 4254<span class="apii">[-0, +0, –]</span> 4255<pre>int lua_isnil (lua_State *L, int index);</pre> 4256 4257<p> 4258Returns 1 if the value at the given index is <b>nil</b>, 4259and 0 otherwise. 4260 4261 4262 4263 4264 4265<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> 4266<span class="apii">[-0, +0, –]</span> 4267<pre>int lua_isnone (lua_State *L, int index);</pre> 4268 4269<p> 4270Returns 1 if the given index is not valid, 4271and 0 otherwise. 4272 4273 4274 4275 4276 4277<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> 4278<span class="apii">[-0, +0, –]</span> 4279<pre>int lua_isnoneornil (lua_State *L, int index);</pre> 4280 4281<p> 4282Returns 1 if the given index is not valid 4283or if the value at this index is <b>nil</b>, 4284and 0 otherwise. 4285 4286 4287 4288 4289 4290<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> 4291<span class="apii">[-0, +0, –]</span> 4292<pre>int lua_isnumber (lua_State *L, int index);</pre> 4293 4294<p> 4295Returns 1 if the value at the given index is a number 4296or a string convertible to a number, 4297and 0 otherwise. 4298 4299 4300 4301 4302 4303<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> 4304<span class="apii">[-0, +0, –]</span> 4305<pre>int lua_isstring (lua_State *L, int index);</pre> 4306 4307<p> 4308Returns 1 if the value at the given index is a string 4309or a number (which is always convertible to a string), 4310and 0 otherwise. 4311 4312 4313 4314 4315 4316<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> 4317<span class="apii">[-0, +0, –]</span> 4318<pre>int lua_istable (lua_State *L, int index);</pre> 4319 4320<p> 4321Returns 1 if the value at the given index is a table, 4322and 0 otherwise. 4323 4324 4325 4326 4327 4328<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> 4329<span class="apii">[-0, +0, –]</span> 4330<pre>int lua_isthread (lua_State *L, int index);</pre> 4331 4332<p> 4333Returns 1 if the value at the given index is a thread, 4334and 0 otherwise. 4335 4336 4337 4338 4339 4340<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> 4341<span class="apii">[-0, +0, –]</span> 4342<pre>int lua_isuserdata (lua_State *L, int index);</pre> 4343 4344<p> 4345Returns 1 if the value at the given index is a userdata 4346(either full or light), and 0 otherwise. 4347 4348 4349 4350 4351 4352<hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p> 4353<span class="apii">[-0, +0, –]</span> 4354<pre>int lua_isyieldable (lua_State *L);</pre> 4355 4356<p> 4357Returns 1 if the given coroutine can yield, 4358and 0 otherwise. 4359 4360 4361 4362 4363 4364<hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3> 4365<pre>typedef ... lua_KContext;</pre> 4366 4367<p> 4368The type for continuation-function contexts. 4369It must be a numeric type. 4370This type is defined as <code>intptr_t</code> 4371when <code>intptr_t</code> is available, 4372so that it can store pointers too. 4373Otherwise, it is defined as <code>ptrdiff_t</code>. 4374 4375 4376 4377 4378 4379<hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3> 4380<pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre> 4381 4382<p> 4383Type for continuation functions (see <a href="#4.5">§4.5</a>). 4384 4385 4386 4387 4388 4389<hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p> 4390<span class="apii">[-0, +1, <em>e</em>]</span> 4391<pre>void lua_len (lua_State *L, int index);</pre> 4392 4393<p> 4394Returns the length of the value at the given index. 4395It is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>) and 4396may trigger a metamethod for the "length" event (see <a href="#2.4">§2.4</a>). 4397The result is pushed on the stack. 4398 4399 4400 4401 4402 4403<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> 4404<span class="apii">[-0, +1, –]</span> 4405<pre>int lua_load (lua_State *L, 4406 lua_Reader reader, 4407 void *data, 4408 const char *chunkname, 4409 const char *mode);</pre> 4410 4411<p> 4412Loads a Lua chunk without running it. 4413If there are no errors, 4414<code>lua_load</code> pushes the compiled chunk as a Lua 4415function on top of the stack. 4416Otherwise, it pushes an error message. 4417 4418 4419<p> 4420The <code>lua_load</code> function uses a user-supplied <code>reader</code> function 4421to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). 4422The <code>data</code> argument is an opaque value passed to the reader function. 4423 4424 4425<p> 4426The <code>chunkname</code> argument gives a name to the chunk, 4427which is used for error messages and in debug information (see <a href="#4.7">§4.7</a>). 4428 4429 4430<p> 4431<code>lua_load</code> automatically detects whether the chunk is text or binary 4432and loads it accordingly (see program <code>luac</code>). 4433The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>, 4434with the addition that 4435a <code>NULL</code> value is equivalent to the string "<code>bt</code>". 4436 4437 4438<p> 4439<code>lua_load</code> uses the stack internally, 4440so the reader function must always leave the stack 4441unmodified when returning. 4442 4443 4444<p> 4445<code>lua_load</code> can return 4446<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>, <a href="#pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>, or <a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>. 4447The function may also return other values corresponding to 4448errors raised by the read function (see <a href="#4.4.1">§4.4.1</a>). 4449 4450 4451<p> 4452If the resulting function has upvalues, 4453its first upvalue is set to the value of the global environment 4454stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.3">§4.3</a>). 4455When loading main chunks, 4456this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 4457Other upvalues are initialized with <b>nil</b>. 4458 4459 4460 4461 4462 4463<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> 4464<span class="apii">[-0, +0, –]</span> 4465<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> 4466 4467<p> 4468Creates a new independent state and returns its main thread. 4469Returns <code>NULL</code> if it cannot create the state 4470(due to lack of memory). 4471The argument <code>f</code> is the allocator function; 4472Lua will do all memory allocation for this state 4473through this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>). 4474The second argument, <code>ud</code>, is an opaque pointer that Lua 4475passes to the allocator in every call. 4476 4477 4478 4479 4480 4481<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> 4482<span class="apii">[-0, +1, <em>m</em>]</span> 4483<pre>void lua_newtable (lua_State *L);</pre> 4484 4485<p> 4486Creates a new empty table and pushes it onto the stack. 4487It is equivalent to <code>lua_createtable(L, 0, 0)</code>. 4488 4489 4490 4491 4492 4493<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> 4494<span class="apii">[-0, +1, <em>m</em>]</span> 4495<pre>lua_State *lua_newthread (lua_State *L);</pre> 4496 4497<p> 4498Creates a new thread, pushes it on the stack, 4499and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. 4500The new thread returned by this function shares with the original thread 4501its global environment, 4502but has an independent execution stack. 4503 4504 4505<p> 4506Threads are subject to garbage collection, 4507like any Lua object. 4508 4509 4510 4511 4512 4513<hr><h3><a name="lua_newuserdatauv"><code>lua_newuserdatauv</code></a></h3><p> 4514<span class="apii">[-0, +1, <em>m</em>]</span> 4515<pre>void *lua_newuserdatauv (lua_State *L, size_t size, int nuvalue);</pre> 4516 4517<p> 4518This function creates and pushes on the stack a new full userdata, 4519with <code>nuvalue</code> associated Lua values, called <code>user values</code>, 4520plus an associated block of raw memory with <code>size</code> bytes. 4521(The user values can be set and read with the functions 4522<a href="#lua_setiuservalue"><code>lua_setiuservalue</code></a> and <a href="#lua_getiuservalue"><code>lua_getiuservalue</code></a>.) 4523 4524 4525<p> 4526The function returns the address of the block of memory. 4527Lua ensures that this address is valid as long as 4528the corresponding userdata is alive (see <a href="#2.5">§2.5</a>). 4529Moreover, if the userdata is marked for finalization (see <a href="#2.5.3">§2.5.3</a>), 4530its address is valid at least until the call to its finalizer. 4531 4532 4533 4534 4535 4536<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> 4537<span class="apii">[-1, +(2|0), <em>v</em>]</span> 4538<pre>int lua_next (lua_State *L, int index);</pre> 4539 4540<p> 4541Pops a key from the stack, 4542and pushes a key–value pair from the table at the given index, 4543the "next" pair after the given key. 4544If there are no more elements in the table, 4545then <a href="#lua_next"><code>lua_next</code></a> returns 0 and pushes nothing. 4546 4547 4548<p> 4549A typical table traversal looks like this: 4550 4551<pre> 4552 /* table is in the stack at index 't' */ 4553 lua_pushnil(L); /* first key */ 4554 while (lua_next(L, t) != 0) { 4555 /* uses 'key' (at index -2) and 'value' (at index -1) */ 4556 printf("%s - %s\n", 4557 lua_typename(L, lua_type(L, -2)), 4558 lua_typename(L, lua_type(L, -1))); 4559 /* removes 'value'; keeps 'key' for next iteration */ 4560 lua_pop(L, 1); 4561 } 4562</pre> 4563 4564<p> 4565While traversing a table, 4566avoid calling <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, 4567unless you know that the key is actually a string. 4568Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change 4569the value at the given index; 4570this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. 4571 4572 4573<p> 4574This function may raise an error if the given key 4575is neither <b>nil</b> nor present in the table. 4576See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 4577the table during its traversal. 4578 4579 4580 4581 4582 4583<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> 4584<pre>typedef ... lua_Number;</pre> 4585 4586<p> 4587The type of floats in Lua. 4588 4589 4590<p> 4591By default this type is double, 4592but that can be changed to a single float or a long double. 4593(See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.) 4594 4595 4596 4597 4598 4599<hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3> 4600<pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre> 4601 4602<p> 4603Tries to convert a Lua float to a Lua integer; 4604the float <code>n</code> must have an integral value. 4605If that value is within the range of Lua integers, 4606it is converted to an integer and assigned to <code>*p</code>. 4607The macro results in a boolean indicating whether the 4608conversion was successful. 4609(Note that this range test can be tricky to do 4610correctly without this macro, due to rounding.) 4611 4612 4613<p> 4614This macro may evaluate its arguments more than once. 4615 4616 4617 4618 4619 4620<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> 4621<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4622<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre> 4623 4624<p> 4625Calls a function (or a callable object) in protected mode. 4626 4627 4628<p> 4629Both <code>nargs</code> and <code>nresults</code> have the same meaning as 4630in <a href="#lua_call"><code>lua_call</code></a>. 4631If there are no errors during the call, 4632<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. 4633However, if there is any error, 4634<a href="#lua_pcall"><code>lua_pcall</code></a> catches it, 4635pushes a single value on the stack (the error object), 4636and returns an error code. 4637Like <a href="#lua_call"><code>lua_call</code></a>, 4638<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function 4639and its arguments from the stack. 4640 4641 4642<p> 4643If <code>msgh</code> is 0, 4644then the error object returned on the stack 4645is exactly the original error object. 4646Otherwise, <code>msgh</code> is the stack index of a 4647<em>message handler</em>. 4648(This index cannot be a pseudo-index.) 4649In case of runtime errors, 4650this handler will be called with the error object 4651and its return value will be the object 4652returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. 4653 4654 4655<p> 4656Typically, the message handler is used to add more debug 4657information to the error object, such as a stack traceback. 4658Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, 4659since by then the stack has unwound. 4660 4661 4662<p> 4663The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following status codes: 4664<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>, <a href="#pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>, <a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>, or <a href="#pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>. 4665 4666 4667 4668 4669 4670<hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p> 4671<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4672<pre>int lua_pcallk (lua_State *L, 4673 int nargs, 4674 int nresults, 4675 int msgh, 4676 lua_KContext ctx, 4677 lua_KFunction k);</pre> 4678 4679<p> 4680This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>, 4681except that it allows the called function to yield (see <a href="#4.5">§4.5</a>). 4682 4683 4684 4685 4686 4687<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> 4688<span class="apii">[-n, +0, <em>e</em>]</span> 4689<pre>void lua_pop (lua_State *L, int n);</pre> 4690 4691<p> 4692Pops <code>n</code> elements from the stack. 4693It is implemented as a macro over <a href="#lua_settop"><code>lua_settop</code></a>. 4694 4695 4696 4697 4698 4699<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> 4700<span class="apii">[-0, +1, –]</span> 4701<pre>void lua_pushboolean (lua_State *L, int b);</pre> 4702 4703<p> 4704Pushes a boolean value with value <code>b</code> onto the stack. 4705 4706 4707 4708 4709 4710<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> 4711<span class="apii">[-n, +1, <em>m</em>]</span> 4712<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> 4713 4714<p> 4715Pushes a new C closure onto the stack. 4716This function receives a pointer to a C function 4717and pushes onto the stack a Lua value of type <code>function</code> that, 4718when called, invokes the corresponding C function. 4719The parameter <code>n</code> tells how many upvalues this function will have 4720(see <a href="#4.2">§4.2</a>). 4721 4722 4723<p> 4724Any function to be callable by Lua must 4725follow the correct protocol to receive its parameters 4726and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 4727 4728 4729<p> 4730When a C function is created, 4731it is possible to associate some values with it, 4732the so called upvalues; 4733these upvalues are then accessible to the function whenever it is called. 4734This association is called a C closure (see <a href="#4.2">§4.2</a>). 4735To create a C closure, 4736first the initial values for its upvalues must be pushed onto the stack. 4737(When there are multiple upvalues, the first value is pushed first.) 4738Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 4739is called to create and push the C function onto the stack, 4740with the argument <code>n</code> telling how many values will be 4741associated with the function. 4742<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. 4743 4744 4745<p> 4746The maximum value for <code>n</code> is 255. 4747 4748 4749<p> 4750When <code>n</code> is zero, 4751this function creates a <em>light C function</em>, 4752which is just a pointer to the C function. 4753In that case, it never raises a memory error. 4754 4755 4756 4757 4758 4759<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> 4760<span class="apii">[-0, +1, –]</span> 4761<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> 4762 4763<p> 4764Pushes a C function onto the stack. 4765This function is equivalent to <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> with no upvalues. 4766 4767 4768 4769 4770 4771<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> 4772<span class="apii">[-0, +1, <em>v</em>]</span> 4773<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> 4774 4775<p> 4776Pushes onto the stack a formatted string 4777and returns a pointer to this string (see <a href="#4.1.3">§4.1.3</a>). 4778It is similar to the ISO C function <code>sprintf</code>, 4779but has two important differences. 4780First, 4781you do not have to allocate space for the result; 4782the result is a Lua string and Lua takes care of memory allocation 4783(and deallocation, through garbage collection). 4784Second, 4785the conversion specifiers are quite restricted. 4786There are no flags, widths, or precisions. 4787The conversion specifiers can only be 4788'<code>%%</code>' (inserts the character '<code>%</code>'), 4789'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), 4790'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), 4791'<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>), 4792'<code>%p</code>' (inserts a pointer), 4793'<code>%d</code>' (inserts an <code>int</code>), 4794'<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and 4795'<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence). 4796 4797 4798<p> 4799This function may raise errors due to memory overflow 4800or an invalid conversion specifier. 4801 4802 4803 4804 4805 4806<hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p> 4807<span class="apii">[-0, +1, –]</span> 4808<pre>void lua_pushglobaltable (lua_State *L);</pre> 4809 4810<p> 4811Pushes the global environment onto the stack. 4812 4813 4814 4815 4816 4817<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> 4818<span class="apii">[-0, +1, –]</span> 4819<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> 4820 4821<p> 4822Pushes an integer with value <code>n</code> onto the stack. 4823 4824 4825 4826 4827 4828<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> 4829<span class="apii">[-0, +1, –]</span> 4830<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> 4831 4832<p> 4833Pushes a light userdata onto the stack. 4834 4835 4836<p> 4837Userdata represent C values in Lua. 4838A <em>light userdata</em> represents a pointer, a <code>void*</code>. 4839It is a value (like a number): 4840you do not create it, it has no individual metatable, 4841and it is not collected (as it was never created). 4842A light userdata is equal to "any" 4843light userdata with the same C address. 4844 4845 4846 4847 4848 4849<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> 4850<span class="apii">[-0, +1, <em>m</em>]</span> 4851<pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre> 4852 4853<p> 4854This macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>, 4855but should be used only when <code>s</code> is a literal string. 4856(Lua may optimize this case.) 4857 4858 4859 4860 4861 4862<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> 4863<span class="apii">[-0, +1, <em>m</em>]</span> 4864<pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> 4865 4866<p> 4867Pushes the string pointed to by <code>s</code> with size <code>len</code> 4868onto the stack. 4869Lua will make or reuse an internal copy of the given string, 4870so the memory at <code>s</code> can be freed or reused immediately after 4871the function returns. 4872The string can contain any binary data, 4873including embedded zeros. 4874 4875 4876<p> 4877Returns a pointer to the internal copy of the string (see <a href="#4.1.3">§4.1.3</a>). 4878 4879 4880 4881 4882 4883<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> 4884<span class="apii">[-0, +1, –]</span> 4885<pre>void lua_pushnil (lua_State *L);</pre> 4886 4887<p> 4888Pushes a nil value onto the stack. 4889 4890 4891 4892 4893 4894<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> 4895<span class="apii">[-0, +1, –]</span> 4896<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> 4897 4898<p> 4899Pushes a float with value <code>n</code> onto the stack. 4900 4901 4902 4903 4904 4905<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> 4906<span class="apii">[-0, +1, <em>m</em>]</span> 4907<pre>const char *lua_pushstring (lua_State *L, const char *s);</pre> 4908 4909<p> 4910Pushes the zero-terminated string pointed to by <code>s</code> 4911onto the stack. 4912Lua will make or reuse an internal copy of the given string, 4913so the memory at <code>s</code> can be freed or reused immediately after 4914the function returns. 4915 4916 4917<p> 4918Returns a pointer to the internal copy of the string (see <a href="#4.1.3">§4.1.3</a>). 4919 4920 4921<p> 4922If <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>. 4923 4924 4925 4926 4927 4928<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> 4929<span class="apii">[-0, +1, –]</span> 4930<pre>int lua_pushthread (lua_State *L);</pre> 4931 4932<p> 4933Pushes the thread represented by <code>L</code> onto the stack. 4934Returns 1 if this thread is the main thread of its state. 4935 4936 4937 4938 4939 4940<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> 4941<span class="apii">[-0, +1, –]</span> 4942<pre>void lua_pushvalue (lua_State *L, int index);</pre> 4943 4944<p> 4945Pushes a copy of the element at the given index 4946onto the stack. 4947 4948 4949 4950 4951 4952<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> 4953<span class="apii">[-0, +1, <em>v</em>]</span> 4954<pre>const char *lua_pushvfstring (lua_State *L, 4955 const char *fmt, 4956 va_list argp);</pre> 4957 4958<p> 4959Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> 4960instead of a variable number of arguments. 4961 4962 4963 4964 4965 4966<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> 4967<span class="apii">[-0, +0, –]</span> 4968<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> 4969 4970<p> 4971Returns 1 if the two values in indices <code>index1</code> and 4972<code>index2</code> are primitively equal 4973(that is, equal without calling the <code>__eq</code> metamethod). 4974Otherwise returns 0. 4975Also returns 0 if any of the indices are not valid. 4976 4977 4978 4979 4980 4981<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> 4982<span class="apii">[-1, +1, –]</span> 4983<pre>int lua_rawget (lua_State *L, int index);</pre> 4984 4985<p> 4986Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access 4987(i.e., without metamethods). 4988 4989 4990 4991 4992 4993<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> 4994<span class="apii">[-0, +1, –]</span> 4995<pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre> 4996 4997<p> 4998Pushes onto the stack the value <code>t[n]</code>, 4999where <code>t</code> is the table at the given index. 5000The access is raw, 5001that is, it does not use the <code>__index</code> metavalue. 5002 5003 5004<p> 5005Returns the type of the pushed value. 5006 5007 5008 5009 5010 5011<hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p> 5012<span class="apii">[-0, +1, –]</span> 5013<pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre> 5014 5015<p> 5016Pushes onto the stack the value <code>t[k]</code>, 5017where <code>t</code> is the table at the given index and 5018<code>k</code> is the pointer <code>p</code> represented as a light userdata. 5019The access is raw; 5020that is, it does not use the <code>__index</code> metavalue. 5021 5022 5023<p> 5024Returns the type of the pushed value. 5025 5026 5027 5028 5029 5030<hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p> 5031<span class="apii">[-0, +0, –]</span> 5032<pre>lua_Unsigned lua_rawlen (lua_State *L, int index);</pre> 5033 5034<p> 5035Returns the raw "length" of the value at the given index: 5036for strings, this is the string length; 5037for tables, this is the result of the length operator ('<code>#</code>') 5038with no metamethods; 5039for userdata, this is the size of the block of memory allocated 5040for the userdata. 5041For other values, this call returns 0. 5042 5043 5044 5045 5046 5047<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> 5048<span class="apii">[-2, +0, <em>m</em>]</span> 5049<pre>void lua_rawset (lua_State *L, int index);</pre> 5050 5051<p> 5052Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment 5053(i.e., without metamethods). 5054 5055 5056 5057 5058 5059<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> 5060<span class="apii">[-1, +0, <em>m</em>]</span> 5061<pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre> 5062 5063<p> 5064Does the equivalent of <code>t[i] = v</code>, 5065where <code>t</code> is the table at the given index 5066and <code>v</code> is the value on the top of the stack. 5067 5068 5069<p> 5070This function pops the value from the stack. 5071The assignment is raw, 5072that is, it does not use the <code>__newindex</code> metavalue. 5073 5074 5075 5076 5077 5078<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p> 5079<span class="apii">[-1, +0, <em>m</em>]</span> 5080<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre> 5081 5082<p> 5083Does the equivalent of <code>t[p] = v</code>, 5084where <code>t</code> is the table at the given index, 5085<code>p</code> is encoded as a light userdata, 5086and <code>v</code> is the value on the top of the stack. 5087 5088 5089<p> 5090This function pops the value from the stack. 5091The assignment is raw, 5092that is, it does not use the <code>__newindex</code> metavalue. 5093 5094 5095 5096 5097 5098<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> 5099<pre>typedef const char * (*lua_Reader) (lua_State *L, 5100 void *data, 5101 size_t *size);</pre> 5102 5103<p> 5104The reader function used by <a href="#lua_load"><code>lua_load</code></a>. 5105Every time <a href="#lua_load"><code>lua_load</code></a> needs another piece of the chunk, 5106it calls the reader, 5107passing along its <code>data</code> parameter. 5108The reader must return a pointer to a block of memory 5109with a new piece of the chunk 5110and set <code>size</code> to the block size. 5111The block must exist until the reader function is called again. 5112To signal the end of the chunk, 5113the reader must return <code>NULL</code> or set <code>size</code> to zero. 5114The reader function may return pieces of any size greater than zero. 5115 5116 5117 5118 5119 5120<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> 5121<span class="apii">[-0, +0, <em>e</em>]</span> 5122<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre> 5123 5124<p> 5125Sets the C function <code>f</code> as the new value of global <code>name</code>. 5126It is defined as a macro: 5127 5128<pre> 5129 #define lua_register(L,n,f) \ 5130 (lua_pushcfunction(L, f), lua_setglobal(L, n)) 5131</pre> 5132 5133 5134 5135 5136<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> 5137<span class="apii">[-1, +0, –]</span> 5138<pre>void lua_remove (lua_State *L, int index);</pre> 5139 5140<p> 5141Removes the element at the given valid index, 5142shifting down the elements above this index to fill the gap. 5143This function cannot be called with a pseudo-index, 5144because a pseudo-index is not an actual stack position. 5145 5146 5147 5148 5149 5150<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> 5151<span class="apii">[-1, +0, –]</span> 5152<pre>void lua_replace (lua_State *L, int index);</pre> 5153 5154<p> 5155Moves the top element into the given valid index 5156without shifting any element 5157(therefore replacing the value at that given index), 5158and then pops the top element. 5159 5160 5161 5162 5163 5164<hr><h3><a name="lua_resetthread"><code>lua_resetthread</code></a></h3><p> 5165<span class="apii">[-0, +?, –]</span> 5166<pre>int lua_resetthread (lua_State *L);</pre> 5167 5168<p> 5169Resets a thread, cleaning its call stack and closing all pending 5170to-be-closed variables. 5171Returns a status code: 5172<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for no errors in the thread 5173(either the original error that stopped the thread or 5174errors in closing methods), 5175or an error status otherwise. 5176In case of error, 5177leaves the error object on the top of the stack. 5178 5179 5180 5181 5182 5183<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> 5184<span class="apii">[-?, +?, –]</span> 5185<pre>int lua_resume (lua_State *L, lua_State *from, int nargs, 5186 int *nresults);</pre> 5187 5188<p> 5189Starts and resumes a coroutine in the given thread <code>L</code>. 5190 5191 5192<p> 5193To start a coroutine, 5194you push the main function plus any arguments 5195onto the empty stack of the thread. 5196then you call <a href="#lua_resume"><code>lua_resume</code></a>, 5197with <code>nargs</code> being the number of arguments. 5198This call returns when the coroutine suspends or finishes its execution. 5199When it returns, 5200<code>*nresults</code> is updated and 5201the top of the stack contains 5202the <code>*nresults</code> values passed to <a href="#lua_yield"><code>lua_yield</code></a> 5203or returned by the body function. 5204<a href="#lua_resume"><code>lua_resume</code></a> returns 5205<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, 5206<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution 5207without errors, 5208or an error code in case of errors (see <a href="#4.4.1">§4.4.1</a>). 5209In case of errors, 5210the error object is on the top of the stack. 5211 5212 5213<p> 5214To resume a coroutine, 5215you remove the <code>*nresults</code> yielded values from its stack, 5216push the values to be passed as results from <code>yield</code>, 5217and then call <a href="#lua_resume"><code>lua_resume</code></a>. 5218 5219 5220<p> 5221The parameter <code>from</code> represents the coroutine that is resuming <code>L</code>. 5222If there is no such coroutine, 5223this parameter can be <code>NULL</code>. 5224 5225 5226 5227 5228 5229<hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p> 5230<span class="apii">[-0, +0, –]</span> 5231<pre>void lua_rotate (lua_State *L, int idx, int n);</pre> 5232 5233<p> 5234Rotates the stack elements between the valid index <code>idx</code> 5235and the top of the stack. 5236The elements are rotated <code>n</code> positions in the direction of the top, 5237for a positive <code>n</code>, 5238or <code>-n</code> positions in the direction of the bottom, 5239for a negative <code>n</code>. 5240The absolute value of <code>n</code> must not be greater than the size 5241of the slice being rotated. 5242This function cannot be called with a pseudo-index, 5243because a pseudo-index is not an actual stack position. 5244 5245 5246 5247 5248 5249<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> 5250<span class="apii">[-0, +0, –]</span> 5251<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> 5252 5253<p> 5254Changes the allocator function of a given state to <code>f</code> 5255with user data <code>ud</code>. 5256 5257 5258 5259 5260 5261<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> 5262<span class="apii">[-1, +0, <em>e</em>]</span> 5263<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> 5264 5265<p> 5266Does the equivalent to <code>t[k] = v</code>, 5267where <code>t</code> is the value at the given index 5268and <code>v</code> is the value on the top of the stack. 5269 5270 5271<p> 5272This function pops the value from the stack. 5273As in Lua, this function may trigger a metamethod 5274for the "newindex" event (see <a href="#2.4">§2.4</a>). 5275 5276 5277 5278 5279 5280<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> 5281<span class="apii">[-1, +0, <em>e</em>]</span> 5282<pre>void lua_setglobal (lua_State *L, const char *name);</pre> 5283 5284<p> 5285Pops a value from the stack and 5286sets it as the new value of global <code>name</code>. 5287 5288 5289 5290 5291 5292<hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p> 5293<span class="apii">[-1, +0, <em>e</em>]</span> 5294<pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre> 5295 5296<p> 5297Does the equivalent to <code>t[n] = v</code>, 5298where <code>t</code> is the value at the given index 5299and <code>v</code> is the value on the top of the stack. 5300 5301 5302<p> 5303This function pops the value from the stack. 5304As in Lua, this function may trigger a metamethod 5305for the "newindex" event (see <a href="#2.4">§2.4</a>). 5306 5307 5308 5309 5310 5311<hr><h3><a name="lua_setiuservalue"><code>lua_setiuservalue</code></a></h3><p> 5312<span class="apii">[-1, +0, –]</span> 5313<pre>int lua_setiuservalue (lua_State *L, int index, int n);</pre> 5314 5315<p> 5316Pops a value from the stack and sets it as 5317the new <code>n</code>-th user value associated to the 5318full userdata at the given index. 5319Returns 0 if the userdata does not have that value. 5320 5321 5322 5323 5324 5325<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> 5326<span class="apii">[-1, +0, –]</span> 5327<pre>int lua_setmetatable (lua_State *L, int index);</pre> 5328 5329<p> 5330Pops a table or <b>nil</b> from the stack and 5331sets that value as the new metatable for the value at the given index. 5332(<b>nil</b> means no metatable.) 5333 5334 5335<p> 5336(For historical reasons, this function returns an <code>int</code>, 5337which now is always 1.) 5338 5339 5340 5341 5342 5343<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> 5344<span class="apii">[-2, +0, <em>e</em>]</span> 5345<pre>void lua_settable (lua_State *L, int index);</pre> 5346 5347<p> 5348Does the equivalent to <code>t[k] = v</code>, 5349where <code>t</code> is the value at the given index, 5350<code>v</code> is the value on the top of the stack, 5351and <code>k</code> is the value just below the top. 5352 5353 5354<p> 5355This function pops both the key and the value from the stack. 5356As in Lua, this function may trigger a metamethod 5357for the "newindex" event (see <a href="#2.4">§2.4</a>). 5358 5359 5360 5361 5362 5363<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> 5364<span class="apii">[-?, +?, <em>e</em>]</span> 5365<pre>void lua_settop (lua_State *L, int index);</pre> 5366 5367<p> 5368Accepts any index, or 0, 5369and sets the stack top to this index. 5370If the new top is greater than the old one, 5371then the new elements are filled with <b>nil</b>. 5372If <code>index</code> is 0, then all stack elements are removed. 5373 5374 5375<p> 5376This function can run arbitrary code when removing an index 5377marked as to-be-closed from the stack. 5378 5379 5380 5381 5382 5383<hr><h3><a name="lua_setwarnf"><code>lua_setwarnf</code></a></h3><p> 5384<span class="apii">[-0, +0, –]</span> 5385<pre>void lua_setwarnf (lua_State *L, lua_WarnFunction f, void *ud);</pre> 5386 5387<p> 5388Sets the warning function to be used by Lua to emit warnings 5389(see <a href="#lua_WarnFunction"><code>lua_WarnFunction</code></a>). 5390The <code>ud</code> parameter sets the value <code>ud</code> passed to 5391the warning function. 5392 5393 5394 5395 5396 5397<hr><h3><a name="lua_State"><code>lua_State</code></a></h3> 5398<pre>typedef struct lua_State lua_State;</pre> 5399 5400<p> 5401An opaque structure that points to a thread and indirectly 5402(through the thread) to the whole state of a Lua interpreter. 5403The Lua library is fully reentrant: 5404it has no global variables. 5405All information about a state is accessible through this structure. 5406 5407 5408<p> 5409A pointer to this structure must be passed as the first argument to 5410every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 5411which creates a Lua state from scratch. 5412 5413 5414 5415 5416 5417<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> 5418<span class="apii">[-0, +0, –]</span> 5419<pre>int lua_status (lua_State *L);</pre> 5420 5421<p> 5422Returns the status of the thread <code>L</code>. 5423 5424 5425<p> 5426The status can be <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for a normal thread, 5427an error code if the thread finished the execution 5428of a <a href="#lua_resume"><code>lua_resume</code></a> with an error, 5429or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. 5430 5431 5432<p> 5433You can call functions only in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>. 5434You can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> 5435(to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> 5436(to resume a coroutine). 5437 5438 5439 5440 5441 5442<hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p> 5443<span class="apii">[-0, +1, –]</span> 5444<pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre> 5445 5446<p> 5447Converts the zero-terminated string <code>s</code> to a number, 5448pushes that number into the stack, 5449and returns the total size of the string, 5450that is, its length plus one. 5451The conversion can result in an integer or a float, 5452according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 5453The string may have leading and trailing whitespaces and a sign. 5454If the string is not a valid numeral, 5455returns 0 and pushes nothing. 5456(Note that the result can be used as a boolean, 5457true if the conversion succeeds.) 5458 5459 5460 5461 5462 5463<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> 5464<span class="apii">[-0, +0, –]</span> 5465<pre>int lua_toboolean (lua_State *L, int index);</pre> 5466 5467<p> 5468Converts the Lua value at the given index to a C boolean 5469value (0 or 1). 5470Like all tests in Lua, 5471<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value 5472different from <b>false</b> and <b>nil</b>; 5473otherwise it returns false. 5474(If you want to accept only actual boolean values, 5475use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) 5476 5477 5478 5479 5480 5481<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> 5482<span class="apii">[-0, +0, –]</span> 5483<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> 5484 5485<p> 5486Converts a value at the given index to a C function. 5487That value must be a C function; 5488otherwise, returns <code>NULL</code>. 5489 5490 5491 5492 5493 5494<hr><h3><a name="lua_toclose"><code>lua_toclose</code></a></h3><p> 5495<span class="apii">[-0, +0, <em>m</em>]</span> 5496<pre>void lua_toclose (lua_State *L, int index);</pre> 5497 5498<p> 5499Marks the given index in the stack as a 5500to-be-closed slot (see <a href="#3.3.8">§3.3.8</a>). 5501Like a to-be-closed variable in Lua, 5502the value at that slot in the stack will be closed 5503when it goes out of scope. 5504Here, in the context of a C function, 5505to go out of scope means that the running function returns to Lua, 5506or there is an error, 5507or the slot is removed from the stack through 5508<a href="#lua_settop"><code>lua_settop</code></a> or <a href="#lua_pop"><code>lua_pop</code></a>, 5509or there is a call to <a href="#lua_closeslot"><code>lua_closeslot</code></a>. 5510A slot marked as to-be-closed should not be removed from the stack 5511by any other function in the API except <a href="#lua_settop"><code>lua_settop</code></a> or <a href="#lua_pop"><code>lua_pop</code></a>, 5512unless previously deactivated by <a href="#lua_closeslot"><code>lua_closeslot</code></a>. 5513 5514 5515<p> 5516This function should not be called for an index 5517that is equal to or below an active to-be-closed slot. 5518 5519 5520<p> 5521Note that, both in case of errors and of a regular return, 5522by the time the <code>__close</code> metamethod runs, 5523the C stack was already unwound, 5524so that any automatic C variable declared in the calling function 5525(e.g., a buffer) will be out of scope. 5526 5527 5528 5529 5530 5531<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> 5532<span class="apii">[-0, +0, –]</span> 5533<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> 5534 5535<p> 5536Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5537 5538 5539 5540 5541 5542<hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p> 5543<span class="apii">[-0, +0, –]</span> 5544<pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre> 5545 5546<p> 5547Converts the Lua value at the given index 5548to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. 5549The Lua value must be an integer, 5550or a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>); 5551otherwise, <code>lua_tointegerx</code> returns 0. 5552 5553 5554<p> 5555If <code>isnum</code> is not <code>NULL</code>, 5556its referent is assigned a boolean value that 5557indicates whether the operation succeeded. 5558 5559 5560 5561 5562 5563<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> 5564<span class="apii">[-0, +0, <em>m</em>]</span> 5565<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> 5566 5567<p> 5568Converts the Lua value at the given index to a C string. 5569If <code>len</code> is not <code>NULL</code>, 5570it sets <code>*len</code> with the string length. 5571The Lua value must be a string or a number; 5572otherwise, the function returns <code>NULL</code>. 5573If the value is a number, 5574then <code>lua_tolstring</code> also 5575<em>changes the actual value in the stack to a string</em>. 5576(This change confuses <a href="#lua_next"><code>lua_next</code></a> 5577when <code>lua_tolstring</code> is applied to keys during a table traversal.) 5578 5579 5580<p> 5581<code>lua_tolstring</code> returns a pointer 5582to a string inside the Lua state (see <a href="#4.1.3">§4.1.3</a>). 5583This string always has a zero ('<code>\0</code>') 5584after its last character (as in C), 5585but can contain other zeros in its body. 5586 5587 5588 5589 5590 5591<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> 5592<span class="apii">[-0, +0, –]</span> 5593<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> 5594 5595<p> 5596Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5597 5598 5599 5600 5601 5602<hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p> 5603<span class="apii">[-0, +0, –]</span> 5604<pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre> 5605 5606<p> 5607Converts the Lua value at the given index 5608to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). 5609The Lua value must be a number or a string convertible to a number 5610(see <a href="#3.4.3">§3.4.3</a>); 5611otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0. 5612 5613 5614<p> 5615If <code>isnum</code> is not <code>NULL</code>, 5616its referent is assigned a boolean value that 5617indicates whether the operation succeeded. 5618 5619 5620 5621 5622 5623<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> 5624<span class="apii">[-0, +0, –]</span> 5625<pre>const void *lua_topointer (lua_State *L, int index);</pre> 5626 5627<p> 5628Converts the value at the given index to a generic 5629C pointer (<code>void*</code>). 5630The value can be a userdata, a table, a thread, a string, or a function; 5631otherwise, <code>lua_topointer</code> returns <code>NULL</code>. 5632Different objects will give different pointers. 5633There is no way to convert the pointer back to its original value. 5634 5635 5636<p> 5637Typically this function is used only for hashing and debug information. 5638 5639 5640 5641 5642 5643<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> 5644<span class="apii">[-0, +0, <em>m</em>]</span> 5645<pre>const char *lua_tostring (lua_State *L, int index);</pre> 5646 5647<p> 5648Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. 5649 5650 5651 5652 5653 5654<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> 5655<span class="apii">[-0, +0, –]</span> 5656<pre>lua_State *lua_tothread (lua_State *L, int index);</pre> 5657 5658<p> 5659Converts the value at the given index to a Lua thread 5660(represented as <code>lua_State*</code>). 5661This value must be a thread; 5662otherwise, the function returns <code>NULL</code>. 5663 5664 5665 5666 5667 5668<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> 5669<span class="apii">[-0, +0, –]</span> 5670<pre>void *lua_touserdata (lua_State *L, int index);</pre> 5671 5672<p> 5673If the value at the given index is a full userdata, 5674returns its memory-block address. 5675If the value is a light userdata, 5676returns its value (a pointer). 5677Otherwise, returns <code>NULL</code>. 5678 5679 5680 5681 5682 5683<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> 5684<span class="apii">[-0, +0, –]</span> 5685<pre>int lua_type (lua_State *L, int index);</pre> 5686 5687<p> 5688Returns the type of the value in the given valid index, 5689or <code>LUA_TNONE</code> for a non-valid but acceptable index. 5690The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants 5691defined in <code>lua.h</code>: 5692<a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a>, 5693<a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>, 5694<a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>, 5695<a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, 5696<a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, 5697<a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, 5698<a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, 5699<a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>, 5700and 5701<a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>. 5702 5703 5704 5705 5706 5707<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> 5708<span class="apii">[-0, +0, –]</span> 5709<pre>const char *lua_typename (lua_State *L, int tp);</pre> 5710 5711<p> 5712Returns the name of the type encoded by the value <code>tp</code>, 5713which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. 5714 5715 5716 5717 5718 5719<hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3> 5720<pre>typedef ... lua_Unsigned;</pre> 5721 5722<p> 5723The unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>. 5724 5725 5726 5727 5728 5729<hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p> 5730<span class="apii">[-0, +0, –]</span> 5731<pre>int lua_upvalueindex (int i);</pre> 5732 5733<p> 5734Returns the pseudo-index that represents the <code>i</code>-th upvalue of 5735the running function (see <a href="#4.2">§4.2</a>). 5736<code>i</code> must be in the range <em>[1,256]</em>. 5737 5738 5739 5740 5741 5742<hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p> 5743<span class="apii">[-0, +0, –]</span> 5744<pre>lua_Number lua_version (lua_State *L);</pre> 5745 5746<p> 5747Returns the version number of this core. 5748 5749 5750 5751 5752 5753<hr><h3><a name="lua_WarnFunction"><code>lua_WarnFunction</code></a></h3> 5754<pre>typedef void (*lua_WarnFunction) (void *ud, const char *msg, int tocont);</pre> 5755 5756<p> 5757The type of warning functions, called by Lua to emit warnings. 5758The first parameter is an opaque pointer 5759set by <a href="#lua_setwarnf"><code>lua_setwarnf</code></a>. 5760The second parameter is the warning message. 5761The third parameter is a boolean that 5762indicates whether the message is 5763to be continued by the message in the next call. 5764 5765 5766<p> 5767See <a href="#pdf-warn"><code>warn</code></a> for more details about warnings. 5768 5769 5770 5771 5772 5773<hr><h3><a name="lua_warning"><code>lua_warning</code></a></h3><p> 5774<span class="apii">[-0, +0, –]</span> 5775<pre>void lua_warning (lua_State *L, const char *msg, int tocont);</pre> 5776 5777<p> 5778Emits a warning with the given message. 5779A message in a call with <code>tocont</code> true should be 5780continued in another call to this function. 5781 5782 5783<p> 5784See <a href="#pdf-warn"><code>warn</code></a> for more details about warnings. 5785 5786 5787 5788 5789 5790<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> 5791<pre>typedef int (*lua_Writer) (lua_State *L, 5792 const void* p, 5793 size_t sz, 5794 void* ud);</pre> 5795 5796<p> 5797The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. 5798Every time <a href="#lua_dump"><code>lua_dump</code></a> produces another piece of chunk, 5799it calls the writer, 5800passing along the buffer to be written (<code>p</code>), 5801its size (<code>sz</code>), 5802and the <code>ud</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. 5803 5804 5805<p> 5806The writer returns an error code: 58070 means no errors; 5808any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from 5809calling the writer again. 5810 5811 5812 5813 5814 5815<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> 5816<span class="apii">[-?, +?, –]</span> 5817<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> 5818 5819<p> 5820Exchange values between different threads of the same state. 5821 5822 5823<p> 5824This function pops <code>n</code> values from the stack <code>from</code>, 5825and pushes them onto the stack <code>to</code>. 5826 5827 5828 5829 5830 5831<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> 5832<span class="apii">[-?, +?, <em>v</em>]</span> 5833<pre>int lua_yield (lua_State *L, int nresults);</pre> 5834 5835<p> 5836This function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5837but it has no continuation (see <a href="#4.5">§4.5</a>). 5838Therefore, when the thread resumes, 5839it continues the function that called 5840the function calling <code>lua_yield</code>. 5841To avoid surprises, 5842this function should be called only in a tail call. 5843 5844 5845 5846 5847 5848<hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p> 5849<span class="apii">[-?, +?, <em>v</em>]</span> 5850<pre>int lua_yieldk (lua_State *L, 5851 int nresults, 5852 lua_KContext ctx, 5853 lua_KFunction k);</pre> 5854 5855<p> 5856Yields a coroutine (thread). 5857 5858 5859<p> 5860When a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5861the running coroutine suspends its execution, 5862and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. 5863The parameter <code>nresults</code> is the number of values from the stack 5864that will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. 5865 5866 5867<p> 5868When the coroutine is resumed again, 5869Lua calls the given continuation function <code>k</code> to continue 5870the execution of the C function that yielded (see <a href="#4.5">§4.5</a>). 5871This continuation function receives the same stack 5872from the previous function, 5873with the <code>n</code> results removed and 5874replaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>. 5875Moreover, 5876the continuation function receives the value <code>ctx</code> 5877that was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>. 5878 5879 5880<p> 5881Usually, this function does not return; 5882when the coroutine eventually resumes, 5883it continues executing the continuation function. 5884However, there is one special case, 5885which is when this function is called 5886from inside a line or a count hook (see <a href="#4.7">§4.7</a>). 5887In that case, <code>lua_yieldk</code> should be called with no continuation 5888(probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results, 5889and the hook should return immediately after the call. 5890Lua will yield and, 5891when the coroutine resumes again, 5892it will continue the normal execution 5893of the (Lua) function that triggered the hook. 5894 5895 5896<p> 5897This function can raise an error if it is called from a thread 5898with a pending C call with no continuation function 5899(what is called a <em>C-call boundary</em>), 5900or it is called from a thread that is not running inside a resume 5901(typically the main thread). 5902 5903 5904 5905 5906 5907 5908 5909<h2>4.7 – <a name="4.7">The Debug Interface</a></h2> 5910 5911<p> 5912Lua has no built-in debugging facilities. 5913Instead, it offers a special interface 5914by means of functions and <em>hooks</em>. 5915This interface allows the construction of different 5916kinds of debuggers, profilers, and other tools 5917that need "inside information" from the interpreter. 5918 5919 5920 5921<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> 5922<pre>typedef struct lua_Debug { 5923 int event; 5924 const char *name; /* (n) */ 5925 const char *namewhat; /* (n) */ 5926 const char *what; /* (S) */ 5927 const char *source; /* (S) */ 5928 size_t srclen; /* (S) */ 5929 int currentline; /* (l) */ 5930 int linedefined; /* (S) */ 5931 int lastlinedefined; /* (S) */ 5932 unsigned char nups; /* (u) number of upvalues */ 5933 unsigned char nparams; /* (u) number of parameters */ 5934 char isvararg; /* (u) */ 5935 char istailcall; /* (t) */ 5936 unsigned short ftransfer; /* (r) index of first value transferred */ 5937 unsigned short ntransfer; /* (r) number of transferred values */ 5938 char short_src[LUA_IDSIZE]; /* (S) */ 5939 /* private part */ 5940 <em>other fields</em> 5941} lua_Debug;</pre> 5942 5943<p> 5944A structure used to carry different pieces of 5945information about a function or an activation record. 5946<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part 5947of this structure, for later use. 5948To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, 5949you must call <a href="#lua_getinfo"><code>lua_getinfo</code></a> with an appropriate parameter. 5950(Specifically, to get a field, 5951you must add the letter between parentheses in the field's comment 5952to the parameter <code>what</code> of <a href="#lua_getinfo"><code>lua_getinfo</code></a>.) 5953 5954 5955<p> 5956The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: 5957 5958<ul> 5959 5960<li><b><code>source</code>: </b> 5961the source of the chunk that created the function. 5962If <code>source</code> starts with a '<code>@</code>', 5963it means that the function was defined in a file where 5964the file name follows the '<code>@</code>'. 5965If <code>source</code> starts with a '<code>=</code>', 5966the remainder of its contents describes the source in a user-dependent manner. 5967Otherwise, 5968the function was defined in a string where 5969<code>source</code> is that string. 5970</li> 5971 5972<li><b><code>srclen</code>: </b> 5973The length of the string <code>source</code>. 5974</li> 5975 5976<li><b><code>short_src</code>: </b> 5977a "printable" version of <code>source</code>, to be used in error messages. 5978</li> 5979 5980<li><b><code>linedefined</code>: </b> 5981the line number where the definition of the function starts. 5982</li> 5983 5984<li><b><code>lastlinedefined</code>: </b> 5985the line number where the definition of the function ends. 5986</li> 5987 5988<li><b><code>what</code>: </b> 5989the string <code>"Lua"</code> if the function is a Lua function, 5990<code>"C"</code> if it is a C function, 5991<code>"main"</code> if it is the main part of a chunk. 5992</li> 5993 5994<li><b><code>currentline</code>: </b> 5995the current line where the given function is executing. 5996When no line information is available, 5997<code>currentline</code> is set to -1. 5998</li> 5999 6000<li><b><code>name</code>: </b> 6001a reasonable name for the given function. 6002Because functions in Lua are first-class values, 6003they do not have a fixed name: 6004some functions can be the value of multiple global variables, 6005while others can be stored only in a table field. 6006The <code>lua_getinfo</code> function checks how the function was 6007called to find a suitable name. 6008If it cannot find a name, 6009then <code>name</code> is set to <code>NULL</code>. 6010</li> 6011 6012<li><b><code>namewhat</code>: </b> 6013explains the <code>name</code> field. 6014The value of <code>namewhat</code> can be 6015<code>"global"</code>, <code>"local"</code>, <code>"method"</code>, 6016<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), 6017according to how the function was called. 6018(Lua uses the empty string when no other option seems to apply.) 6019</li> 6020 6021<li><b><code>istailcall</code>: </b> 6022true if this function invocation was called by a tail call. 6023In this case, the caller of this level is not in the stack. 6024</li> 6025 6026<li><b><code>nups</code>: </b> 6027the number of upvalues of the function. 6028</li> 6029 6030<li><b><code>nparams</code>: </b> 6031the number of parameters of the function 6032(always 0 for C functions). 6033</li> 6034 6035<li><b><code>isvararg</code>: </b> 6036true if the function is a vararg function 6037(always true for C functions). 6038</li> 6039 6040<li><b><code>ftransfer</code>: </b> 6041the index in the stack of the first value being "transferred", 6042that is, parameters in a call or return values in a return. 6043(The other values are in consecutive indices.) 6044Using this index, you can access and modify these values 6045through <a href="#lua_getlocal"><code>lua_getlocal</code></a> and <a href="#lua_setlocal"><code>lua_setlocal</code></a>. 6046This field is only meaningful during a 6047call hook, denoting the first parameter, 6048or a return hook, denoting the first value being returned. 6049(For call hooks, this value is always 1.) 6050</li> 6051 6052<li><b><code>ntransfer</code>: </b> 6053The number of values being transferred (see previous item). 6054(For calls of Lua functions, 6055this value is always equal to <code>nparams</code>.) 6056</li> 6057 6058</ul> 6059 6060 6061 6062 6063<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> 6064<span class="apii">[-0, +0, –]</span> 6065<pre>lua_Hook lua_gethook (lua_State *L);</pre> 6066 6067<p> 6068Returns the current hook function. 6069 6070 6071 6072 6073 6074<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> 6075<span class="apii">[-0, +0, –]</span> 6076<pre>int lua_gethookcount (lua_State *L);</pre> 6077 6078<p> 6079Returns the current hook count. 6080 6081 6082 6083 6084 6085<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> 6086<span class="apii">[-0, +0, –]</span> 6087<pre>int lua_gethookmask (lua_State *L);</pre> 6088 6089<p> 6090Returns the current hook mask. 6091 6092 6093 6094 6095 6096<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> 6097<span class="apii">[-(0|1), +(0|1|2), <em>m</em>]</span> 6098<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> 6099 6100<p> 6101Gets information about a specific function or function invocation. 6102 6103 6104<p> 6105To get information about a function invocation, 6106the parameter <code>ar</code> must be a valid activation record that was 6107filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 6108given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 6109 6110 6111<p> 6112To get information about a function, you push it onto the stack 6113and start the <code>what</code> string with the character '<code>></code>'. 6114(In that case, 6115<code>lua_getinfo</code> pops the function from the top of the stack.) 6116For instance, to know in which line a function <code>f</code> was defined, 6117you can write the following code: 6118 6119<pre> 6120 lua_Debug ar; 6121 lua_getglobal(L, "f"); /* get global 'f' */ 6122 lua_getinfo(L, ">S", &ar); 6123 printf("%d\n", ar.linedefined); 6124</pre> 6125 6126<p> 6127Each character in the string <code>what</code> 6128selects some fields of the structure <code>ar</code> to be filled or 6129a value to be pushed on the stack. 6130(These characters are also documented in the declaration of 6131the structure <a href="#lua_Debug"><code>lua_Debug</code></a>, 6132between parentheses in the comments following each field.) 6133 6134<ul> 6135 6136<li><b>'<code>f</code>': </b> 6137pushes onto the stack the function that is 6138running at the given level; 6139</li> 6140 6141<li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>; 6142</li> 6143 6144<li><b>'<code>n</code>': </b> fills in the fields <code>name</code> and <code>namewhat</code>; 6145</li> 6146 6147<li><b>'<code>r</code>': </b> fills in the fields <code>ftransfer</code> and <code>ntransfer</code>; 6148</li> 6149 6150<li><b>'<code>S</code>': </b> 6151fills in the fields <code>source</code>, <code>short_src</code>, 6152<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; 6153</li> 6154 6155<li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>; 6156</li> 6157 6158<li><b>'<code>u</code>': </b> fills in the fields 6159<code>nups</code>, <code>nparams</code>, and <code>isvararg</code>; 6160</li> 6161 6162<li><b>'<code>L</code>': </b> 6163pushes onto the stack a table whose indices are 6164the lines on the function with some associated code, 6165that is, the lines where you can put a break point. 6166(Lines with no code include empty lines and comments.) 6167If this option is given together with option '<code>f</code>', 6168its table is pushed after the function. 6169This is the only option that can raise a memory error. 6170</li> 6171 6172</ul> 6173 6174<p> 6175This function returns 0 to signal an invalid option in <code>what</code>; 6176even then the valid options are handled correctly. 6177 6178 6179 6180 6181 6182<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> 6183<span class="apii">[-0, +(0|1), –]</span> 6184<pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 6185 6186<p> 6187Gets information about a local variable or a temporary value 6188of a given activation record or a given function. 6189 6190 6191<p> 6192In the first case, 6193the parameter <code>ar</code> must be a valid activation record that was 6194filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 6195given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 6196The index <code>n</code> selects which local variable to inspect; 6197see <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices 6198and names. 6199 6200 6201<p> 6202<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack 6203and returns its name. 6204 6205 6206<p> 6207In the second case, <code>ar</code> must be <code>NULL</code> and the function 6208to be inspected must be on the top of the stack. 6209In this case, only parameters of Lua functions are visible 6210(as there is no information about what variables are active) 6211and no values are pushed onto the stack. 6212 6213 6214<p> 6215Returns <code>NULL</code> (and pushes nothing) 6216when the index is greater than 6217the number of active local variables. 6218 6219 6220 6221 6222 6223<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> 6224<span class="apii">[-0, +0, –]</span> 6225<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> 6226 6227<p> 6228Gets information about the interpreter runtime stack. 6229 6230 6231<p> 6232This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with 6233an identification of the <em>activation record</em> 6234of the function executing at a given level. 6235Level 0 is the current running function, 6236whereas level <em>n+1</em> is the function that has called level <em>n</em> 6237(except for tail calls, which do not count in the stack). 6238When called with a level greater than the stack depth, 6239<a href="#lua_getstack"><code>lua_getstack</code></a> returns 0; 6240otherwise it returns 1. 6241 6242 6243 6244 6245 6246<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> 6247<span class="apii">[-0, +(0|1), –]</span> 6248<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> 6249 6250<p> 6251Gets information about the <code>n</code>-th upvalue 6252of the closure at index <code>funcindex</code>. 6253It pushes the upvalue's value onto the stack 6254and returns its name. 6255Returns <code>NULL</code> (and pushes nothing) 6256when the index <code>n</code> is greater than the number of upvalues. 6257 6258 6259<p> 6260See <a href="#pdf-debug.getupvalue"><code>debug.getupvalue</code></a> for more information about upvalues. 6261 6262 6263 6264 6265 6266<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> 6267<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> 6268 6269<p> 6270Type for debugging hook functions. 6271 6272 6273<p> 6274Whenever a hook is called, its <code>ar</code> argument has its field 6275<code>event</code> set to the specific event that triggered the hook. 6276Lua identifies these events with the following constants: 6277<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, 6278<a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, 6279and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. 6280Moreover, for line events, the field <code>currentline</code> is also set. 6281To get the value of any other field in <code>ar</code>, 6282the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 6283 6284 6285<p> 6286For call events, <code>event</code> can be <code>LUA_HOOKCALL</code>, 6287the normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call; 6288in this case, there will be no corresponding return event. 6289 6290 6291<p> 6292While Lua is running a hook, it disables other calls to hooks. 6293Therefore, if a hook calls back Lua to execute a function or a chunk, 6294this execution occurs without any calls to hooks. 6295 6296 6297<p> 6298Hook functions cannot have continuations, 6299that is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 6300<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>. 6301 6302 6303<p> 6304Hook functions can yield under the following conditions: 6305Only count and line events can yield; 6306to yield, a hook function must finish its execution 6307calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero 6308(that is, with no values). 6309 6310 6311 6312 6313 6314<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> 6315<span class="apii">[-0, +0, –]</span> 6316<pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> 6317 6318<p> 6319Sets the debugging hook function. 6320 6321 6322<p> 6323Argument <code>f</code> is the hook function. 6324<code>mask</code> specifies on which events the hook will be called: 6325it is formed by a bitwise OR of the constants 6326<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, 6327<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, 6328<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, 6329and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. 6330The <code>count</code> argument is only meaningful when the mask 6331includes <code>LUA_MASKCOUNT</code>. 6332For each event, the hook is called as explained below: 6333 6334<ul> 6335 6336<li><b>The call hook: </b> is called when the interpreter calls a function. 6337The hook is called just after Lua enters the new function. 6338</li> 6339 6340<li><b>The return hook: </b> is called when the interpreter returns from a function. 6341The hook is called just before Lua leaves the function. 6342</li> 6343 6344<li><b>The line hook: </b> is called when the interpreter is about to 6345start the execution of a new line of code, 6346or when it jumps back in the code (even to the same line). 6347This event only happens while Lua is executing a Lua function. 6348</li> 6349 6350<li><b>The count hook: </b> is called after the interpreter executes every 6351<code>count</code> instructions. 6352This event only happens while Lua is executing a Lua function. 6353</li> 6354 6355</ul> 6356 6357<p> 6358Hooks are disabled by setting <code>mask</code> to zero. 6359 6360 6361 6362 6363 6364<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> 6365<span class="apii">[-(0|1), +0, –]</span> 6366<pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 6367 6368<p> 6369Sets the value of a local variable of a given activation record. 6370It assigns the value on the top of the stack 6371to the variable and returns its name. 6372It also pops the value from the stack. 6373 6374 6375<p> 6376Returns <code>NULL</code> (and pops nothing) 6377when the index is greater than 6378the number of active local variables. 6379 6380 6381<p> 6382Parameters <code>ar</code> and <code>n</code> are as in the function <a href="#lua_getlocal"><code>lua_getlocal</code></a>. 6383 6384 6385 6386 6387 6388<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> 6389<span class="apii">[-(0|1), +0, –]</span> 6390<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> 6391 6392<p> 6393Sets the value of a closure's upvalue. 6394It assigns the value on the top of the stack 6395to the upvalue and returns its name. 6396It also pops the value from the stack. 6397 6398 6399<p> 6400Returns <code>NULL</code> (and pops nothing) 6401when the index <code>n</code> is greater than the number of upvalues. 6402 6403 6404<p> 6405Parameters <code>funcindex</code> and <code>n</code> are as in 6406the function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>. 6407 6408 6409 6410 6411 6412<hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p> 6413<span class="apii">[-0, +0, –]</span> 6414<pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre> 6415 6416<p> 6417Returns a unique identifier for the upvalue numbered <code>n</code> 6418from the closure at index <code>funcindex</code>. 6419 6420 6421<p> 6422These unique identifiers allow a program to check whether different 6423closures share upvalues. 6424Lua closures that share an upvalue 6425(that is, that access a same external local variable) 6426will return identical ids for those upvalue indices. 6427 6428 6429<p> 6430Parameters <code>funcindex</code> and <code>n</code> are as in 6431the function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, 6432but <code>n</code> cannot be greater than the number of upvalues. 6433 6434 6435 6436 6437 6438<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p> 6439<span class="apii">[-0, +0, –]</span> 6440<pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1, 6441 int funcindex2, int n2);</pre> 6442 6443<p> 6444Make the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code> 6445refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>. 6446 6447 6448 6449 6450 6451 6452 6453<h1>5 – <a name="5">The Auxiliary Library</a></h1> 6454 6455 6456 6457<p> 6458 6459The <em>auxiliary library</em> provides several convenient functions 6460to interface C with Lua. 6461While the basic API provides the primitive functions for all 6462interactions between C and Lua, 6463the auxiliary library provides higher-level functions for some 6464common tasks. 6465 6466 6467<p> 6468All functions and types from the auxiliary library 6469are defined in header file <code>lauxlib.h</code> and 6470have a prefix <code>luaL_</code>. 6471 6472 6473<p> 6474All functions in the auxiliary library are built on 6475top of the basic API, 6476and so they provide nothing that cannot be done with that API. 6477Nevertheless, the use of the auxiliary library ensures 6478more consistency to your code. 6479 6480 6481<p> 6482Several functions in the auxiliary library use internally some 6483extra stack slots. 6484When a function in the auxiliary library uses less than five slots, 6485it does not check the stack size; 6486it simply assumes that there are enough slots. 6487 6488 6489<p> 6490Several functions in the auxiliary library are used to 6491check C function arguments. 6492Because the error message is formatted for arguments 6493(e.g., "<code>bad argument #1</code>"), 6494you should not use these functions for other stack values. 6495 6496 6497<p> 6498Functions called <code>luaL_check*</code> 6499always raise an error if the check is not satisfied. 6500 6501 6502 6503 6504 6505<h2>5.1 – <a name="5.1">Functions and Types</a></h2> 6506 6507<p> 6508Here we list all functions and types from the auxiliary library 6509in alphabetical order. 6510 6511 6512 6513<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> 6514<span class="apii">[-?, +?, <em>m</em>]</span> 6515<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> 6516 6517<p> 6518Adds the byte <code>c</code> to the buffer <code>B</code> 6519(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6520 6521 6522 6523 6524 6525<hr><h3><a name="luaL_addgsub"><code>luaL_addgsub</code></a></h3><p> 6526<span class="apii">[-?, +?, <em>m</em>]</span> 6527<pre>const void luaL_addgsub (luaL_Buffer *B, const char *s, 6528 const char *p, const char *r);</pre> 6529 6530<p> 6531Adds a copy of the string <code>s</code> to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>), 6532replacing any occurrence of the string <code>p</code> 6533with the string <code>r</code>. 6534 6535 6536 6537 6538 6539<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> 6540<span class="apii">[-?, +?, <em>m</em>]</span> 6541<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> 6542 6543<p> 6544Adds the string pointed to by <code>s</code> with length <code>l</code> to 6545the buffer <code>B</code> 6546(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6547The string can contain embedded zeros. 6548 6549 6550 6551 6552 6553<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> 6554<span class="apii">[-?, +?, –]</span> 6555<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> 6556 6557<p> 6558Adds to the buffer <code>B</code> 6559a string of length <code>n</code> previously copied to the 6560buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). 6561 6562 6563 6564 6565 6566<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> 6567<span class="apii">[-?, +?, <em>m</em>]</span> 6568<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> 6569 6570<p> 6571Adds the zero-terminated string pointed to by <code>s</code> 6572to the buffer <code>B</code> 6573(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6574 6575 6576 6577 6578 6579<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> 6580<span class="apii">[-?, +?, <em>m</em>]</span> 6581<pre>void luaL_addvalue (luaL_Buffer *B);</pre> 6582 6583<p> 6584Adds the value on the top of the stack 6585to the buffer <code>B</code> 6586(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6587Pops the value. 6588 6589 6590<p> 6591This is the only function on string buffers that can (and must) 6592be called with an extra element on the stack, 6593which is the value to be added to the buffer. 6594 6595 6596 6597 6598 6599<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> 6600<span class="apii">[-0, +0, <em>v</em>]</span> 6601<pre>void luaL_argcheck (lua_State *L, 6602 int cond, 6603 int arg, 6604 const char *extramsg);</pre> 6605 6606<p> 6607Checks whether <code>cond</code> is true. 6608If it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>). 6609 6610 6611 6612 6613 6614<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> 6615<span class="apii">[-0, +0, <em>v</em>]</span> 6616<pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre> 6617 6618<p> 6619Raises an error reporting a problem with argument <code>arg</code> 6620of the C function that called it, 6621using a standard message 6622that includes <code>extramsg</code> as a comment: 6623 6624<pre> 6625 bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>) 6626</pre><p> 6627This function never returns. 6628 6629 6630 6631 6632 6633<hr><h3><a name="luaL_argexpected"><code>luaL_argexpected</code></a></h3><p> 6634<span class="apii">[-0, +0, <em>v</em>]</span> 6635<pre>void luaL_argexpected (lua_State *L, 6636 int cond, 6637 int arg, 6638 const char *tname);</pre> 6639 6640<p> 6641Checks whether <code>cond</code> is true. 6642If it is not, raises an error about the type of the argument <code>arg</code> 6643with a standard message (see <a href="#luaL_typeerror"><code>luaL_typeerror</code></a>). 6644 6645 6646 6647 6648 6649<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> 6650<pre>typedef struct luaL_Buffer luaL_Buffer;</pre> 6651 6652<p> 6653Type for a <em>string buffer</em>. 6654 6655 6656<p> 6657A string buffer allows C code to build Lua strings piecemeal. 6658Its pattern of use is as follows: 6659 6660<ul> 6661 6662<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6663 6664<li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> 6665 6666<li> 6667Then add string pieces to the buffer calling any of 6668the <code>luaL_add*</code> functions. 6669</li> 6670 6671<li> 6672Finish by calling <code>luaL_pushresult(&b)</code>. 6673This call leaves the final string on the top of the stack. 6674</li> 6675 6676</ul> 6677 6678<p> 6679If you know beforehand the maximum size of the resulting string, 6680you can use the buffer like this: 6681 6682<ul> 6683 6684<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6685 6686<li>Then initialize it and preallocate a space of 6687size <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li> 6688 6689<li>Then produce the string into that space.</li> 6690 6691<li> 6692Finish by calling <code>luaL_pushresultsize(&b, sz)</code>, 6693where <code>sz</code> is the total size of the resulting string 6694copied into that space (which may be less than or 6695equal to the preallocated size). 6696</li> 6697 6698</ul> 6699 6700<p> 6701During its normal operation, 6702a string buffer uses a variable number of stack slots. 6703So, while using a buffer, you cannot assume that you know where 6704the top of the stack is. 6705You can use the stack between successive calls to buffer operations 6706as long as that use is balanced; 6707that is, 6708when you call a buffer operation, 6709the stack is at the same level 6710it was immediately after the previous buffer operation. 6711(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) 6712After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>, 6713the stack is back to its level when the buffer was initialized, 6714plus the final string on its top. 6715 6716 6717 6718 6719 6720<hr><h3><a name="luaL_buffaddr"><code>luaL_buffaddr</code></a></h3><p> 6721<span class="apii">[-0, +0, –]</span> 6722<pre>char *luaL_buffaddr (luaL_Buffer *B);</pre> 6723 6724<p> 6725Returns the address of the current content of buffer <code>B</code> 6726(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6727Note that any addition to the buffer may invalidate this address. 6728 6729 6730 6731 6732 6733<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> 6734<span class="apii">[-0, +?, –]</span> 6735<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> 6736 6737<p> 6738Initializes a buffer <code>B</code> 6739(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6740This function does not allocate any space; 6741the buffer must be declared as a variable. 6742 6743 6744 6745 6746 6747<hr><h3><a name="luaL_bufflen"><code>luaL_bufflen</code></a></h3><p> 6748<span class="apii">[-0, +0, –]</span> 6749<pre>size_t luaL_bufflen (luaL_Buffer *B);</pre> 6750 6751<p> 6752Returns the length of the current content of buffer <code>B</code> 6753(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6754 6755 6756 6757 6758 6759<hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p> 6760<span class="apii">[-?, +?, <em>m</em>]</span> 6761<pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre> 6762 6763<p> 6764Equivalent to the sequence 6765<a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>. 6766 6767 6768 6769 6770 6771<hr><h3><a name="luaL_buffsub"><code>luaL_buffsub</code></a></h3><p> 6772<span class="apii">[-?, +?, –]</span> 6773<pre>void luaL_buffsub (luaL_Buffer *B, int n);</pre> 6774 6775<p> 6776Removes <code>n</code> bytes from the the buffer <code>B</code> 6777(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6778The buffer must have at least that many bytes. 6779 6780 6781 6782 6783 6784<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> 6785<span class="apii">[-0, +(0|1), <em>e</em>]</span> 6786<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> 6787 6788<p> 6789Calls a metamethod. 6790 6791 6792<p> 6793If the object at index <code>obj</code> has a metatable and this 6794metatable has a field <code>e</code>, 6795this function calls this field passing the object as its only argument. 6796In this case this function returns true and pushes onto the 6797stack the value returned by the call. 6798If there is no metatable or no metamethod, 6799this function returns false without pushing any value on the stack. 6800 6801 6802 6803 6804 6805<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> 6806<span class="apii">[-0, +0, <em>v</em>]</span> 6807<pre>void luaL_checkany (lua_State *L, int arg);</pre> 6808 6809<p> 6810Checks whether the function has an argument 6811of any type (including <b>nil</b>) at position <code>arg</code>. 6812 6813 6814 6815 6816 6817<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> 6818<span class="apii">[-0, +0, <em>v</em>]</span> 6819<pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre> 6820 6821<p> 6822Checks whether the function argument <code>arg</code> is an integer 6823(or can be converted to an integer) 6824and returns this integer. 6825 6826 6827 6828 6829 6830<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> 6831<span class="apii">[-0, +0, <em>v</em>]</span> 6832<pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre> 6833 6834<p> 6835Checks whether the function argument <code>arg</code> is a string 6836and returns this string; 6837if <code>l</code> is not <code>NULL</code> fills its referent 6838with the string's length. 6839 6840 6841<p> 6842This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6843so all conversions and caveats of that function apply here. 6844 6845 6846 6847 6848 6849<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> 6850<span class="apii">[-0, +0, <em>v</em>]</span> 6851<pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre> 6852 6853<p> 6854Checks whether the function argument <code>arg</code> is a number 6855and returns this number converted to a <code>lua_Number</code>. 6856 6857 6858 6859 6860 6861<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> 6862<span class="apii">[-0, +0, <em>v</em>]</span> 6863<pre>int luaL_checkoption (lua_State *L, 6864 int arg, 6865 const char *def, 6866 const char *const lst[]);</pre> 6867 6868<p> 6869Checks whether the function argument <code>arg</code> is a string and 6870searches for this string in the array <code>lst</code> 6871(which must be NULL-terminated). 6872Returns the index in the array where the string was found. 6873Raises an error if the argument is not a string or 6874if the string cannot be found. 6875 6876 6877<p> 6878If <code>def</code> is not <code>NULL</code>, 6879the function uses <code>def</code> as a default value when 6880there is no argument <code>arg</code> or when this argument is <b>nil</b>. 6881 6882 6883<p> 6884This is a useful function for mapping strings to C enums. 6885(The usual convention in Lua libraries is 6886to use strings instead of numbers to select options.) 6887 6888 6889 6890 6891 6892<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> 6893<span class="apii">[-0, +0, <em>v</em>]</span> 6894<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> 6895 6896<p> 6897Grows the stack size to <code>top + sz</code> elements, 6898raising an error if the stack cannot grow to that size. 6899<code>msg</code> is an additional text to go into the error message 6900(or <code>NULL</code> for no additional text). 6901 6902 6903 6904 6905 6906<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> 6907<span class="apii">[-0, +0, <em>v</em>]</span> 6908<pre>const char *luaL_checkstring (lua_State *L, int arg);</pre> 6909 6910<p> 6911Checks whether the function argument <code>arg</code> is a string 6912and returns this string. 6913 6914 6915<p> 6916This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6917so all conversions and caveats of that function apply here. 6918 6919 6920 6921 6922 6923<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> 6924<span class="apii">[-0, +0, <em>v</em>]</span> 6925<pre>void luaL_checktype (lua_State *L, int arg, int t);</pre> 6926 6927<p> 6928Checks whether the function argument <code>arg</code> has type <code>t</code>. 6929See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. 6930 6931 6932 6933 6934 6935<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> 6936<span class="apii">[-0, +0, <em>v</em>]</span> 6937<pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre> 6938 6939<p> 6940Checks whether the function argument <code>arg</code> is a userdata 6941of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and 6942returns the userdata's memory-block address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>). 6943 6944 6945 6946 6947 6948<hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p> 6949<span class="apii">[-0, +0, <em>v</em>]</span> 6950<pre>void luaL_checkversion (lua_State *L);</pre> 6951 6952<p> 6953Checks whether the code making the call and the Lua library being called 6954are using the same version of Lua and the same numeric types. 6955 6956 6957 6958 6959 6960<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> 6961<span class="apii">[-0, +?, <em>m</em>]</span> 6962<pre>int luaL_dofile (lua_State *L, const char *filename);</pre> 6963 6964<p> 6965Loads and runs the given file. 6966It is defined as the following macro: 6967 6968<pre> 6969 (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6970</pre><p> 6971It returns <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if there are no errors, 6972or an error code in case of errors (see <a href="#4.4.1">§4.4.1</a>). 6973 6974 6975 6976 6977 6978<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> 6979<span class="apii">[-0, +?, –]</span> 6980<pre>int luaL_dostring (lua_State *L, const char *str);</pre> 6981 6982<p> 6983Loads and runs the given string. 6984It is defined as the following macro: 6985 6986<pre> 6987 (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6988</pre><p> 6989It returns <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if there are no errors, 6990or an error code in case of errors (see <a href="#4.4.1">§4.4.1</a>). 6991 6992 6993 6994 6995 6996<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> 6997<span class="apii">[-0, +0, <em>v</em>]</span> 6998<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> 6999 7000<p> 7001Raises an error. 7002The error message format is given by <code>fmt</code> 7003plus any extra arguments, 7004following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. 7005It also adds at the beginning of the message the file name and 7006the line number where the error occurred, 7007if this information is available. 7008 7009 7010<p> 7011This function never returns, 7012but it is an idiom to use it in C functions 7013as <code>return luaL_error(<em>args</em>)</code>. 7014 7015 7016 7017 7018 7019<hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p> 7020<span class="apii">[-0, +3, <em>m</em>]</span> 7021<pre>int luaL_execresult (lua_State *L, int stat);</pre> 7022 7023<p> 7024This function produces the return values for 7025process-related functions in the standard library 7026(<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>). 7027 7028 7029 7030 7031 7032<hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p> 7033<span class="apii">[-0, +(1|3), <em>m</em>]</span> 7034<pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre> 7035 7036<p> 7037This function produces the return values for 7038file-related functions in the standard library 7039(<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.). 7040 7041 7042 7043 7044 7045<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> 7046<span class="apii">[-0, +(0|1), <em>m</em>]</span> 7047<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> 7048 7049<p> 7050Pushes onto the stack the field <code>e</code> from the metatable 7051of the object at index <code>obj</code> and returns the type of the pushed value. 7052If the object does not have a metatable, 7053or if the metatable does not have this field, 7054pushes nothing and returns <code>LUA_TNIL</code>. 7055 7056 7057 7058 7059 7060<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> 7061<span class="apii">[-0, +1, <em>m</em>]</span> 7062<pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre> 7063 7064<p> 7065Pushes onto the stack the metatable associated with the name <code>tname</code> 7066in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>), 7067or <b>nil</b> if there is no metatable associated with that name. 7068Returns the type of the pushed value. 7069 7070 7071 7072 7073 7074<hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p> 7075<span class="apii">[-0, +1, <em>e</em>]</span> 7076<pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre> 7077 7078<p> 7079Ensures that the value <code>t[fname]</code>, 7080where <code>t</code> is the value at index <code>idx</code>, 7081is a table, 7082and pushes that table onto the stack. 7083Returns true if it finds a previous table there 7084and false if it creates a new table. 7085 7086 7087 7088 7089 7090<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> 7091<span class="apii">[-0, +1, <em>m</em>]</span> 7092<pre>const char *luaL_gsub (lua_State *L, 7093 const char *s, 7094 const char *p, 7095 const char *r);</pre> 7096 7097<p> 7098Creates a copy of string <code>s</code>, 7099replacing any occurrence of the string <code>p</code> 7100with the string <code>r</code>. 7101Pushes the resulting string on the stack and returns it. 7102 7103 7104 7105 7106 7107<hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p> 7108<span class="apii">[-0, +0, <em>e</em>]</span> 7109<pre>lua_Integer luaL_len (lua_State *L, int index);</pre> 7110 7111<p> 7112Returns the "length" of the value at the given index 7113as a number; 7114it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). 7115Raises an error if the result of the operation is not an integer. 7116(This case can only happen through metamethods.) 7117 7118 7119 7120 7121 7122<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> 7123<span class="apii">[-0, +1, –]</span> 7124<pre>int luaL_loadbuffer (lua_State *L, 7125 const char *buff, 7126 size_t sz, 7127 const char *name);</pre> 7128 7129<p> 7130Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>. 7131 7132 7133 7134 7135 7136<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p> 7137<span class="apii">[-0, +1, –]</span> 7138<pre>int luaL_loadbufferx (lua_State *L, 7139 const char *buff, 7140 size_t sz, 7141 const char *name, 7142 const char *mode);</pre> 7143 7144<p> 7145Loads a buffer as a Lua chunk. 7146This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the 7147buffer pointed to by <code>buff</code> with size <code>sz</code>. 7148 7149 7150<p> 7151This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 7152<code>name</code> is the chunk name, 7153used for debug information and error messages. 7154The string <code>mode</code> works as in the function <a href="#lua_load"><code>lua_load</code></a>. 7155 7156 7157 7158 7159 7160<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> 7161<span class="apii">[-0, +1, <em>m</em>]</span> 7162<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> 7163 7164<p> 7165Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>. 7166 7167 7168 7169 7170 7171<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p> 7172<span class="apii">[-0, +1, <em>m</em>]</span> 7173<pre>int luaL_loadfilex (lua_State *L, const char *filename, 7174 const char *mode);</pre> 7175 7176<p> 7177Loads a file as a Lua chunk. 7178This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file 7179named <code>filename</code>. 7180If <code>filename</code> is <code>NULL</code>, 7181then it loads from the standard input. 7182The first line in the file is ignored if it starts with a <code>#</code>. 7183 7184 7185<p> 7186The string <code>mode</code> works as in the function <a href="#lua_load"><code>lua_load</code></a>. 7187 7188 7189<p> 7190This function returns the same results as <a href="#lua_load"><code>lua_load</code></a> 7191or <a href="#pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> for file-related errors. 7192 7193 7194<p> 7195As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 7196it does not run it. 7197 7198 7199 7200 7201 7202<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> 7203<span class="apii">[-0, +1, –]</span> 7204<pre>int luaL_loadstring (lua_State *L, const char *s);</pre> 7205 7206<p> 7207Loads a string as a Lua chunk. 7208This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in 7209the zero-terminated string <code>s</code>. 7210 7211 7212<p> 7213This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 7214 7215 7216<p> 7217Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 7218it does not run it. 7219 7220 7221 7222 7223 7224<hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p> 7225<span class="apii">[-0, +1, <em>m</em>]</span> 7226<pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre> 7227 7228<p> 7229Creates a new table and registers there 7230the functions in the list <code>l</code>. 7231 7232 7233<p> 7234It is implemented as the following macro: 7235 7236<pre> 7237 (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0)) 7238</pre><p> 7239The array <code>l</code> must be the actual array, 7240not a pointer to it. 7241 7242 7243 7244 7245 7246<hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p> 7247<span class="apii">[-0, +1, <em>m</em>]</span> 7248<pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre> 7249 7250<p> 7251Creates a new table with a size optimized 7252to store all entries in the array <code>l</code> 7253(but does not actually store them). 7254It is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> 7255(see <a href="#luaL_newlib"><code>luaL_newlib</code></a>). 7256 7257 7258<p> 7259It is implemented as a macro. 7260The array <code>l</code> must be the actual array, 7261not a pointer to it. 7262 7263 7264 7265 7266 7267<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> 7268<span class="apii">[-0, +1, <em>m</em>]</span> 7269<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> 7270 7271<p> 7272If the registry already has the key <code>tname</code>, 7273returns 0. 7274Otherwise, 7275creates a new table to be used as a metatable for userdata, 7276adds to this new table the pair <code>__name = tname</code>, 7277adds to the registry the pair <code>[tname] = new table</code>, 7278and returns 1. 7279 7280 7281<p> 7282In both cases, 7283the function pushes onto the stack the final value associated 7284with <code>tname</code> in the registry. 7285 7286 7287 7288 7289 7290<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> 7291<span class="apii">[-0, +0, –]</span> 7292<pre>lua_State *luaL_newstate (void);</pre> 7293 7294<p> 7295Creates a new Lua state. 7296It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an 7297allocator based on the standard C allocation functions 7298and then sets a warning function and a panic function (see <a href="#4.4">§4.4</a>) 7299that print messages to the standard error output. 7300 7301 7302<p> 7303Returns the new state, 7304or <code>NULL</code> if there is a memory allocation error. 7305 7306 7307 7308 7309 7310<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> 7311<span class="apii">[-0, +0, <em>e</em>]</span> 7312<pre>void luaL_openlibs (lua_State *L);</pre> 7313 7314<p> 7315Opens all standard Lua libraries into the given state. 7316 7317 7318 7319 7320 7321<hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p> 7322<span class="apii">[-0, +0, –]</span> 7323<pre>T luaL_opt (L, func, arg, dflt);</pre> 7324 7325<p> 7326This macro is defined as follows: 7327 7328<pre> 7329 (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg))) 7330</pre><p> 7331In words, if the argument <code>arg</code> is nil or absent, 7332the macro results in the default <code>dflt</code>. 7333Otherwise, it results in the result of calling <code>func</code> 7334with the state <code>L</code> and the argument index <code>arg</code> as 7335arguments. 7336Note that it evaluates the expression <code>dflt</code> only if needed. 7337 7338 7339 7340 7341 7342<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> 7343<span class="apii">[-0, +0, <em>v</em>]</span> 7344<pre>lua_Integer luaL_optinteger (lua_State *L, 7345 int arg, 7346 lua_Integer d);</pre> 7347 7348<p> 7349If the function argument <code>arg</code> is an integer 7350(or it is convertible to an integer), 7351returns this integer. 7352If this argument is absent or is <b>nil</b>, 7353returns <code>d</code>. 7354Otherwise, raises an error. 7355 7356 7357 7358 7359 7360<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> 7361<span class="apii">[-0, +0, <em>v</em>]</span> 7362<pre>const char *luaL_optlstring (lua_State *L, 7363 int arg, 7364 const char *d, 7365 size_t *l);</pre> 7366 7367<p> 7368If the function argument <code>arg</code> is a string, 7369returns this string. 7370If this argument is absent or is <b>nil</b>, 7371returns <code>d</code>. 7372Otherwise, raises an error. 7373 7374 7375<p> 7376If <code>l</code> is not <code>NULL</code>, 7377fills its referent with the result's length. 7378If the result is <code>NULL</code> 7379(only possible when returning <code>d</code> and <code>d == NULL</code>), 7380its length is considered zero. 7381 7382 7383<p> 7384This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 7385so all conversions and caveats of that function apply here. 7386 7387 7388 7389 7390 7391<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> 7392<span class="apii">[-0, +0, <em>v</em>]</span> 7393<pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre> 7394 7395<p> 7396If the function argument <code>arg</code> is a number, 7397returns this number as a <code>lua_Number</code>. 7398If this argument is absent or is <b>nil</b>, 7399returns <code>d</code>. 7400Otherwise, raises an error. 7401 7402 7403 7404 7405 7406<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> 7407<span class="apii">[-0, +0, <em>v</em>]</span> 7408<pre>const char *luaL_optstring (lua_State *L, 7409 int arg, 7410 const char *d);</pre> 7411 7412<p> 7413If the function argument <code>arg</code> is a string, 7414returns this string. 7415If this argument is absent or is <b>nil</b>, 7416returns <code>d</code>. 7417Otherwise, raises an error. 7418 7419 7420 7421 7422 7423<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> 7424<span class="apii">[-?, +?, <em>m</em>]</span> 7425<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> 7426 7427<p> 7428Equivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a> 7429with the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>. 7430 7431 7432 7433 7434 7435<hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p> 7436<span class="apii">[-?, +?, <em>m</em>]</span> 7437<pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre> 7438 7439<p> 7440Returns an address to a space of size <code>sz</code> 7441where you can copy a string to be added to buffer <code>B</code> 7442(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 7443After copying the string into this space you must call 7444<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add 7445it to the buffer. 7446 7447 7448 7449 7450 7451<hr><h3><a name="luaL_pushfail"><code>luaL_pushfail</code></a></h3><p> 7452<span class="apii">[-0, +1, –]</span> 7453<pre>void luaL_pushfail (lua_State *L);</pre> 7454 7455<p> 7456Pushes the <b>fail</b> value onto the stack (see <a href="#6">§6</a>). 7457 7458 7459 7460 7461 7462<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> 7463<span class="apii">[-?, +1, <em>m</em>]</span> 7464<pre>void luaL_pushresult (luaL_Buffer *B);</pre> 7465 7466<p> 7467Finishes the use of buffer <code>B</code> leaving the final string on 7468the top of the stack. 7469 7470 7471 7472 7473 7474<hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p> 7475<span class="apii">[-?, +1, <em>m</em>]</span> 7476<pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre> 7477 7478<p> 7479Equivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>. 7480 7481 7482 7483 7484 7485<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> 7486<span class="apii">[-1, +0, <em>m</em>]</span> 7487<pre>int luaL_ref (lua_State *L, int t);</pre> 7488 7489<p> 7490Creates and returns a <em>reference</em>, 7491in the table at index <code>t</code>, 7492for the object on the top of the stack (and pops the object). 7493 7494 7495<p> 7496A reference is a unique integer key. 7497As long as you do not manually add integer keys into the table <code>t</code>, 7498<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. 7499You can retrieve an object referred by the reference <code>r</code> 7500by calling <code>lua_rawgeti(L, t, r)</code>. 7501The function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference. 7502 7503 7504<p> 7505If the object on the top of the stack is <b>nil</b>, 7506<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>. 7507The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different 7508from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. 7509 7510 7511 7512 7513 7514<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> 7515<pre>typedef struct luaL_Reg { 7516 const char *name; 7517 lua_CFunction func; 7518} luaL_Reg;</pre> 7519 7520<p> 7521Type for arrays of functions to be registered by 7522<a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>. 7523<code>name</code> is the function name and <code>func</code> is a pointer to 7524the function. 7525Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry 7526in which both <code>name</code> and <code>func</code> are <code>NULL</code>. 7527 7528 7529 7530 7531 7532<hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p> 7533<span class="apii">[-0, +1, <em>e</em>]</span> 7534<pre>void luaL_requiref (lua_State *L, const char *modname, 7535 lua_CFunction openf, int glb);</pre> 7536 7537<p> 7538If <code>package.loaded[modname]</code> is not true, 7539calls the function <code>openf</code> with the string <code>modname</code> as an argument 7540and sets the call result to <code>package.loaded[modname]</code>, 7541as if that function has been called through <a href="#pdf-require"><code>require</code></a>. 7542 7543 7544<p> 7545If <code>glb</code> is true, 7546also stores the module into the global <code>modname</code>. 7547 7548 7549<p> 7550Leaves a copy of the module on the stack. 7551 7552 7553 7554 7555 7556<hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p> 7557<span class="apii">[-nup, +0, <em>m</em>]</span> 7558<pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre> 7559 7560<p> 7561Registers all functions in the array <code>l</code> 7562(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack 7563(below optional upvalues, see next). 7564 7565 7566<p> 7567When <code>nup</code> is not zero, 7568all functions are created with <code>nup</code> upvalues, 7569initialized with copies of the <code>nup</code> values 7570previously pushed on the stack 7571on top of the library table. 7572These values are popped from the stack after the registration. 7573 7574 7575<p> 7576A function with a <code>NULL</code> value represents a placeholder, 7577which is filled with <b>false</b>. 7578 7579 7580 7581 7582 7583<hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p> 7584<span class="apii">[-0, +0, –]</span> 7585<pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre> 7586 7587<p> 7588Sets the metatable of the object on the top of the stack 7589as the metatable associated with name <code>tname</code> 7590in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 7591 7592 7593 7594 7595 7596<hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3> 7597<pre>typedef struct luaL_Stream { 7598 FILE *f; 7599 lua_CFunction closef; 7600} luaL_Stream;</pre> 7601 7602<p> 7603The standard representation for file handles 7604used by the standard I/O library. 7605 7606 7607<p> 7608A file handle is implemented as a full userdata, 7609with a metatable called <code>LUA_FILEHANDLE</code> 7610(where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name). 7611The metatable is created by the I/O library 7612(see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 7613 7614 7615<p> 7616This userdata must start with the structure <code>luaL_Stream</code>; 7617it can contain other data after this initial structure. 7618The field <code>f</code> points to the corresponding C stream 7619(or it can be <code>NULL</code> to indicate an incompletely created handle). 7620The field <code>closef</code> points to a Lua function 7621that will be called to close the stream 7622when the handle is closed or collected; 7623this function receives the file handle as its sole argument and 7624must return either a true value, in case of success, 7625or a false value plus an error message, in case of error. 7626Once Lua calls this field, 7627it changes the field value to <code>NULL</code> 7628to signal that the handle is closed. 7629 7630 7631 7632 7633 7634<hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p> 7635<span class="apii">[-0, +0, <em>m</em>]</span> 7636<pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre> 7637 7638<p> 7639This function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>, 7640except that, when the test fails, 7641it returns <code>NULL</code> instead of raising an error. 7642 7643 7644 7645 7646 7647<hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p> 7648<span class="apii">[-0, +1, <em>e</em>]</span> 7649<pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre> 7650 7651<p> 7652Converts any Lua value at the given index to a C string 7653in a reasonable format. 7654The resulting string is pushed onto the stack and also 7655returned by the function (see <a href="#4.1.3">§4.1.3</a>). 7656If <code>len</code> is not <code>NULL</code>, 7657the function also sets <code>*len</code> with the string length. 7658 7659 7660<p> 7661If the value has a metatable with a <code>__tostring</code> field, 7662then <code>luaL_tolstring</code> calls the corresponding metamethod 7663with the value as argument, 7664and uses the result of the call as its result. 7665 7666 7667 7668 7669 7670<hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p> 7671<span class="apii">[-0, +1, <em>m</em>]</span> 7672<pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, 7673 int level);</pre> 7674 7675<p> 7676Creates and pushes a traceback of the stack <code>L1</code>. 7677If <code>msg</code> is not <code>NULL</code>, it is appended 7678at the beginning of the traceback. 7679The <code>level</code> parameter tells at which level 7680to start the traceback. 7681 7682 7683 7684 7685 7686<hr><h3><a name="luaL_typeerror"><code>luaL_typeerror</code></a></h3><p> 7687<span class="apii">[-0, +0, <em>v</em>]</span> 7688<pre>const char *luaL_typeerror (lua_State *L, 7689 int arg, 7690 const char *tname);</pre> 7691 7692<p> 7693Raises a type error for the argument <code>arg</code> 7694of the C function that called it, 7695using a standard message; 7696<code>tname</code> is a "name" for the expected type. 7697This function never returns. 7698 7699 7700 7701 7702 7703<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> 7704<span class="apii">[-0, +0, –]</span> 7705<pre>const char *luaL_typename (lua_State *L, int index);</pre> 7706 7707<p> 7708Returns the name of the type of the value at the given index. 7709 7710 7711 7712 7713 7714<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> 7715<span class="apii">[-0, +0, –]</span> 7716<pre>void luaL_unref (lua_State *L, int t, int ref);</pre> 7717 7718<p> 7719Releases the reference <code>ref</code> from the table at index <code>t</code> 7720(see <a href="#luaL_ref"><code>luaL_ref</code></a>). 7721The entry is removed from the table, 7722so that the referred object can be collected. 7723The reference <code>ref</code> is also freed to be used again. 7724 7725 7726<p> 7727If <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>, 7728<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. 7729 7730 7731 7732 7733 7734<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> 7735<span class="apii">[-0, +1, <em>m</em>]</span> 7736<pre>void luaL_where (lua_State *L, int lvl);</pre> 7737 7738<p> 7739Pushes onto the stack a string identifying the current position 7740of the control at level <code>lvl</code> in the call stack. 7741Typically this string has the following format: 7742 7743<pre> 7744 <em>chunkname</em>:<em>currentline</em>: 7745</pre><p> 7746Level 0 is the running function, 7747level 1 is the function that called the running function, 7748etc. 7749 7750 7751<p> 7752This function is used to build a prefix for error messages. 7753 7754 7755 7756 7757 7758 7759 7760<h1>6 – <a name="6">The Standard Libraries</a></h1> 7761 7762 7763 7764<p> 7765The standard Lua libraries provide useful functions 7766that are implemented in C through the C API. 7767Some of these functions provide essential services to the language 7768(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); 7769others provide access to outside services (e.g., I/O); 7770and others could be implemented in Lua itself, 7771but that for different reasons 7772deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). 7773 7774 7775<p> 7776All libraries are implemented through the official C API 7777and are provided as separate C modules. 7778Unless otherwise noted, 7779these library functions do not adjust its number of arguments 7780to its expected parameters. 7781For instance, a function documented as <code>foo(arg)</code> 7782should not be called without an argument. 7783 7784 7785<p> 7786The notation <b>fail</b> means a false value representing 7787some kind of failure. 7788(Currently, <b>fail</b> is equal to <b>nil</b>, 7789but that may change in future versions. 7790The recommendation is to always test the success of these functions 7791with <code>(not status)</code>, instead of <code>(status == nil)</code>.) 7792 7793 7794<p> 7795Currently, Lua has the following standard libraries: 7796 7797<ul> 7798 7799<li>basic library (<a href="#6.1">§6.1</a>);</li> 7800 7801<li>coroutine library (<a href="#6.2">§6.2</a>);</li> 7802 7803<li>package library (<a href="#6.3">§6.3</a>);</li> 7804 7805<li>string manipulation (<a href="#6.4">§6.4</a>);</li> 7806 7807<li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li> 7808 7809<li>table manipulation (<a href="#6.6">§6.6</a>);</li> 7810 7811<li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li> 7812 7813<li>input and output (<a href="#6.8">§6.8</a>);</li> 7814 7815<li>operating system facilities (<a href="#6.9">§6.9</a>);</li> 7816 7817<li>debug facilities (<a href="#6.10">§6.10</a>).</li> 7818 7819</ul><p> 7820Except for the basic and the package libraries, 7821each library provides all its functions as fields of a global table 7822or as methods of its objects. 7823 7824 7825<p> 7826To have access to these libraries, 7827the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, 7828which opens all standard libraries. 7829Alternatively, 7830the host program can open them individually by using 7831<a href="#luaL_requiref"><code>luaL_requiref</code></a> to call 7832<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), 7833<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), 7834<a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library), 7835<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), 7836<a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF-8 library), 7837<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), 7838<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), 7839<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), 7840<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library), 7841and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). 7842These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>. 7843 7844 7845 7846 7847 7848<h2>6.1 – <a name="6.1">Basic Functions</a></h2> 7849 7850<p> 7851The basic library provides core functions to Lua. 7852If you do not include this library in your application, 7853you should check carefully whether you need to provide 7854implementations for some of its facilities. 7855 7856 7857<p> 7858<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> 7859 7860 7861<p> 7862Raises an error if 7863the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); 7864otherwise, returns all its arguments. 7865In case of error, 7866<code>message</code> is the error object; 7867when absent, it defaults to "<code>assertion failed!</code>" 7868 7869 7870 7871 7872<p> 7873<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3> 7874 7875 7876<p> 7877This function is a generic interface to the garbage collector. 7878It performs different functions according to its first argument, <code>opt</code>: 7879 7880<ul> 7881 7882<li><b>"<code>collect</code>": </b> 7883Performs a full garbage-collection cycle. 7884This is the default option. 7885</li> 7886 7887<li><b>"<code>stop</code>": </b> 7888Stops automatic execution of the garbage collector. 7889The collector will run only when explicitly invoked, 7890until a call to restart it. 7891</li> 7892 7893<li><b>"<code>restart</code>": </b> 7894Restarts automatic execution of the garbage collector. 7895</li> 7896 7897<li><b>"<code>count</code>": </b> 7898Returns the total memory in use by Lua in Kbytes. 7899The value has a fractional part, 7900so that it multiplied by 1024 7901gives the exact number of bytes in use by Lua. 7902</li> 7903 7904<li><b>"<code>step</code>": </b> 7905Performs a garbage-collection step. 7906The step "size" is controlled by <code>arg</code>. 7907With a zero value, 7908the collector will perform one basic (indivisible) step. 7909For non-zero values, 7910the collector will perform as if that amount of memory 7911(in Kbytes) had been allocated by Lua. 7912Returns <b>true</b> if the step finished a collection cycle. 7913</li> 7914 7915<li><b>"<code>isrunning</code>": </b> 7916Returns a boolean that tells whether the collector is running 7917(i.e., not stopped). 7918</li> 7919 7920<li><b>"<code>incremental</code>": </b> 7921Change the collector mode to incremental. 7922This option can be followed by three numbers: 7923the garbage-collector pause, 7924the step multiplier, 7925and the step size (see <a href="#2.5.1">§2.5.1</a>). 7926A zero means to not change that value. 7927</li> 7928 7929<li><b>"<code>generational</code>": </b> 7930Change the collector mode to generational. 7931This option can be followed by two numbers: 7932the garbage-collector minor multiplier 7933and the major multiplier (see <a href="#2.5.2">§2.5.2</a>). 7934A zero means to not change that value. 7935</li> 7936 7937</ul><p> 7938See <a href="#2.5">§2.5</a> for more details about garbage collection 7939and some of these options. 7940 7941 7942<p> 7943This function should not be called by a finalizer. 7944 7945 7946 7947 7948<p> 7949<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> 7950Opens the named file and executes its content as a Lua chunk. 7951When called without arguments, 7952<code>dofile</code> executes the content of the standard input (<code>stdin</code>). 7953Returns all values returned by the chunk. 7954In case of errors, <code>dofile</code> propagates the error 7955to its caller. 7956(That is, <code>dofile</code> does not run in protected mode.) 7957 7958 7959 7960 7961<p> 7962<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> 7963Raises an error (see <a href="#2.3">§2.3</a>) with <code>message</code> as the error object. 7964This function never returns. 7965 7966 7967<p> 7968Usually, <code>error</code> adds some information about the error position 7969at the beginning of the message, if the message is a string. 7970The <code>level</code> argument specifies how to get the error position. 7971With level 1 (the default), the error position is where the 7972<code>error</code> function was called. 7973Level 2 points the error to where the function 7974that called <code>error</code> was called; and so on. 7975Passing a level 0 avoids the addition of error position information 7976to the message. 7977 7978 7979 7980 7981<p> 7982<hr><h3><a name="pdf-_G"><code>_G</code></a></h3> 7983A global variable (not a function) that 7984holds the global environment (see <a href="#2.2">§2.2</a>). 7985Lua itself does not use this variable; 7986changing its value does not affect any environment, 7987nor vice versa. 7988 7989 7990 7991 7992<p> 7993<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> 7994 7995 7996<p> 7997If <code>object</code> does not have a metatable, returns <b>nil</b>. 7998Otherwise, 7999if the object's metatable has a <code>__metatable</code> field, 8000returns the associated value. 8001Otherwise, returns the metatable of the given object. 8002 8003 8004 8005 8006<p> 8007<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> 8008 8009 8010<p> 8011Returns three values (an iterator function, the table <code>t</code>, and 0) 8012so that the construction 8013 8014<pre> 8015 for i,v in ipairs(t) do <em>body</em> end 8016</pre><p> 8017will iterate over the key–value pairs 8018(<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., 8019up to the first absent index. 8020 8021 8022 8023 8024<p> 8025<hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3> 8026 8027 8028<p> 8029Loads a chunk. 8030 8031 8032<p> 8033If <code>chunk</code> is a string, the chunk is this string. 8034If <code>chunk</code> is a function, 8035<code>load</code> calls it repeatedly to get the chunk pieces. 8036Each call to <code>chunk</code> must return a string that concatenates 8037with previous results. 8038A return of an empty string, <b>nil</b>, or no value signals the end of the chunk. 8039 8040 8041<p> 8042If there are no syntactic errors, 8043<code>load</code> returns the compiled chunk as a function; 8044otherwise, it returns <b>fail</b> plus the error message. 8045 8046 8047<p> 8048When you load a main chunk, 8049the resulting function will always have exactly one upvalue, 8050the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 8051However, 8052when you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>), 8053the resulting function can have an arbitrary number of upvalues, 8054and there is no guarantee that its first upvalue will be 8055the <code>_ENV</code> variable. 8056(A non-main function may not even have an <code>_ENV</code> upvalue.) 8057 8058 8059<p> 8060Regardless, if the resulting function has any upvalues, 8061its first upvalue is set to the value of <code>env</code>, 8062if that parameter is given, 8063or to the value of the global environment. 8064Other upvalues are initialized with <b>nil</b>. 8065All upvalues are fresh, that is, 8066they are not shared with any other function. 8067 8068 8069<p> 8070<code>chunkname</code> is used as the name of the chunk for error messages 8071and debug information (see <a href="#4.7">§4.7</a>). 8072When absent, 8073it defaults to <code>chunk</code>, if <code>chunk</code> is a string, 8074or to "<code>=(load)</code>" otherwise. 8075 8076 8077<p> 8078The string <code>mode</code> controls whether the chunk can be text or binary 8079(that is, a precompiled chunk). 8080It may be the string "<code>b</code>" (only binary chunks), 8081"<code>t</code>" (only text chunks), 8082or "<code>bt</code>" (both binary and text). 8083The default is "<code>bt</code>". 8084 8085 8086<p> 8087It is safe to load malformed binary chunks; 8088<code>load</code> signals an appropriate error. 8089However, 8090Lua does not check the consistency of the code inside binary chunks; 8091running maliciously crafted bytecode can crash the interpreter. 8092 8093 8094 8095 8096<p> 8097<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3> 8098 8099 8100<p> 8101Similar to <a href="#pdf-load"><code>load</code></a>, 8102but gets the chunk from file <code>filename</code> 8103or from the standard input, 8104if no file name is given. 8105 8106 8107 8108 8109<p> 8110<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> 8111 8112 8113<p> 8114Allows a program to traverse all fields of a table. 8115Its first argument is a table and its second argument 8116is an index in this table. 8117A call to <code>next</code> returns the next index of the table 8118and its associated value. 8119When called with <b>nil</b> as its second argument, 8120<code>next</code> returns an initial index 8121and its associated value. 8122When called with the last index, 8123or with <b>nil</b> in an empty table, 8124<code>next</code> returns <b>nil</b>. 8125If the second argument is absent, then it is interpreted as <b>nil</b>. 8126In particular, 8127you can use <code>next(t)</code> to check whether a table is empty. 8128 8129 8130<p> 8131The order in which the indices are enumerated is not specified, 8132<em>even for numeric indices</em>. 8133(To traverse a table in numerical order, 8134use a numerical <b>for</b>.) 8135 8136 8137<p> 8138You should not assign any value to a non-existent field in a table 8139during its traversal. 8140You may however modify existing fields. 8141In particular, you may set existing fields to nil. 8142 8143 8144 8145 8146<p> 8147<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> 8148 8149 8150<p> 8151If <code>t</code> has a metamethod <code>__pairs</code>, 8152calls it with <code>t</code> as argument and returns the first three 8153results from the call. 8154 8155 8156<p> 8157Otherwise, 8158returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, 8159so that the construction 8160 8161<pre> 8162 for k,v in pairs(t) do <em>body</em> end 8163</pre><p> 8164will iterate over all key–value pairs of table <code>t</code>. 8165 8166 8167<p> 8168See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 8169the table during its traversal. 8170 8171 8172 8173 8174<p> 8175<hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3> 8176 8177 8178<p> 8179Calls the function <code>f</code> with 8180the given arguments in <em>protected mode</em>. 8181This means that any error inside <code>f</code> is not propagated; 8182instead, <code>pcall</code> catches the error 8183and returns a status code. 8184Its first result is the status code (a boolean), 8185which is <b>true</b> if the call succeeds without errors. 8186In such case, <code>pcall</code> also returns all results from the call, 8187after this first result. 8188In case of any error, <code>pcall</code> returns <b>false</b> plus the error object. 8189Note that errors caught by <code>pcall</code> do not call a message handler. 8190 8191 8192 8193 8194<p> 8195<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> 8196Receives any number of arguments 8197and prints their values to <code>stdout</code>, 8198converting each argument to a string 8199following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 8200 8201 8202<p> 8203The function <code>print</code> is not intended for formatted output, 8204but only as a quick way to show a value, 8205for instance for debugging. 8206For complete control over the output, 8207use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. 8208 8209 8210 8211 8212<p> 8213<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> 8214Checks whether <code>v1</code> is equal to <code>v2</code>, 8215without invoking the <code>__eq</code> metamethod. 8216Returns a boolean. 8217 8218 8219 8220 8221<p> 8222<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> 8223Gets the real value of <code>table[index]</code>, 8224without using the <code>__index</code> metavalue. 8225<code>table</code> must be a table; 8226<code>index</code> may be any value. 8227 8228 8229 8230 8231<p> 8232<hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3> 8233Returns the length of the object <code>v</code>, 8234which must be a table or a string, 8235without invoking the <code>__len</code> metamethod. 8236Returns an integer. 8237 8238 8239 8240 8241<p> 8242<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> 8243Sets the real value of <code>table[index]</code> to <code>value</code>, 8244without using the <code>__newindex</code> metavalue. 8245<code>table</code> must be a table, 8246<code>index</code> any value different from <b>nil</b> and NaN, 8247and <code>value</code> any Lua value. 8248 8249 8250<p> 8251This function returns <code>table</code>. 8252 8253 8254 8255 8256<p> 8257<hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> 8258 8259 8260<p> 8261If <code>index</code> is a number, 8262returns all arguments after argument number <code>index</code>; 8263a negative number indexes from the end (-1 is the last argument). 8264Otherwise, <code>index</code> must be the string <code>"#"</code>, 8265and <code>select</code> returns the total number of extra arguments it received. 8266 8267 8268 8269 8270<p> 8271<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> 8272 8273 8274<p> 8275Sets the metatable for the given table. 8276If <code>metatable</code> is <b>nil</b>, 8277removes the metatable of the given table. 8278If the original metatable has a <code>__metatable</code> field, 8279raises an error. 8280 8281 8282<p> 8283This function returns <code>table</code>. 8284 8285 8286<p> 8287To change the metatable of other types from Lua code, 8288you must use the debug library (<a href="#6.10">§6.10</a>). 8289 8290 8291 8292 8293<p> 8294<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> 8295 8296 8297<p> 8298When called with no <code>base</code>, 8299<code>tonumber</code> tries to convert its argument to a number. 8300If the argument is already a number or 8301a string convertible to a number, 8302then <code>tonumber</code> returns this number; 8303otherwise, it returns <b>fail</b>. 8304 8305 8306<p> 8307The conversion of strings can result in integers or floats, 8308according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 8309The string may have leading and trailing spaces and a sign. 8310 8311 8312<p> 8313When called with <code>base</code>, 8314then <code>e</code> must be a string to be interpreted as 8315an integer numeral in that base. 8316The base may be any integer between 2 and 36, inclusive. 8317In bases above 10, the letter '<code>A</code>' (in either upper or lower case) 8318represents 10, '<code>B</code>' represents 11, and so forth, 8319with '<code>Z</code>' representing 35. 8320If the string <code>e</code> is not a valid numeral in the given base, 8321the function returns <b>fail</b>. 8322 8323 8324 8325 8326<p> 8327<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3> 8328 8329 8330<p> 8331Receives a value of any type and 8332converts it to a string in a human-readable format. 8333 8334 8335<p> 8336If the metatable of <code>v</code> has a <code>__tostring</code> field, 8337then <code>tostring</code> calls the corresponding value 8338with <code>v</code> as argument, 8339and uses the result of the call as its result. 8340Otherwise, if the metatable of <code>v</code> has a <code>__name</code> field 8341with a string value, 8342<code>tostring</code> may use that string in its final result. 8343 8344 8345<p> 8346For complete control of how numbers are converted, 8347use <a href="#pdf-string.format"><code>string.format</code></a>. 8348 8349 8350 8351 8352<p> 8353<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> 8354 8355 8356<p> 8357Returns the type of its only argument, coded as a string. 8358The possible results of this function are 8359"<code>nil</code>" (a string, not the value <b>nil</b>), 8360"<code>number</code>", 8361"<code>string</code>", 8362"<code>boolean</code>", 8363"<code>table</code>", 8364"<code>function</code>", 8365"<code>thread</code>", 8366and "<code>userdata</code>". 8367 8368 8369 8370 8371<p> 8372<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> 8373 8374 8375<p> 8376A global variable (not a function) that 8377holds a string containing the running Lua version. 8378The current value of this variable is "<code>Lua 5.4</code>". 8379 8380 8381 8382 8383<p> 8384<hr><h3><a name="pdf-warn"><code>warn (msg1, ···)</code></a></h3> 8385 8386 8387<p> 8388Emits a warning with a message composed by the concatenation 8389of all its arguments (which should be strings). 8390 8391 8392<p> 8393By convention, 8394a one-piece message starting with '<code>@</code>' 8395is intended to be a <em>control message</em>, 8396which is a message to the warning system itself. 8397In particular, the standard warning function in Lua 8398recognizes the control messages "<code>@off</code>", 8399to stop the emission of warnings, 8400and "<code>@on</code>", to (re)start the emission; 8401it ignores unknown control messages. 8402 8403 8404 8405 8406<p> 8407<hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3> 8408 8409 8410<p> 8411This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, 8412except that it sets a new message handler <code>msgh</code>. 8413 8414 8415 8416 8417 8418 8419 8420<h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2> 8421 8422<p> 8423This library comprises the operations to manipulate coroutines, 8424which come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. 8425See <a href="#2.6">§2.6</a> for a general description of coroutines. 8426 8427 8428<p> 8429<hr><h3><a name="pdf-coroutine.close"><code>coroutine.close (co)</code></a></h3> 8430 8431 8432<p> 8433Closes coroutine <code>co</code>, 8434that is, 8435closes all its pending to-be-closed variables 8436and puts the coroutine in a dead state. 8437The given coroutine must be dead or suspended. 8438In case of error 8439(either the original error that stopped the coroutine or 8440errors in closing methods), 8441returns <b>false</b> plus the error object; 8442otherwise returns <b>true</b>. 8443 8444 8445 8446 8447<p> 8448<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> 8449 8450 8451<p> 8452Creates a new coroutine, with body <code>f</code>. 8453<code>f</code> must be a function. 8454Returns this new coroutine, 8455an object with type <code>"thread"</code>. 8456 8457 8458 8459 8460<p> 8461<hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ([co])</code></a></h3> 8462 8463 8464<p> 8465Returns <b>true</b> when the coroutine <code>co</code> can yield. 8466The default for <code>co</code> is the running coroutine. 8467 8468 8469<p> 8470A coroutine is yieldable if it is not the main thread and 8471it is not inside a non-yieldable C function. 8472 8473 8474 8475 8476<p> 8477<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> 8478 8479 8480<p> 8481Starts or continues the execution of coroutine <code>co</code>. 8482The first time you resume a coroutine, 8483it starts running its body. 8484The values <code>val1</code>, ... are passed 8485as the arguments to the body function. 8486If the coroutine has yielded, 8487<code>resume</code> restarts it; 8488the values <code>val1</code>, ... are passed 8489as the results from the yield. 8490 8491 8492<p> 8493If the coroutine runs without any errors, 8494<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> 8495(when the coroutine yields) or any values returned by the body function 8496(when the coroutine terminates). 8497If there is any error, 8498<code>resume</code> returns <b>false</b> plus the error message. 8499 8500 8501 8502 8503<p> 8504<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> 8505 8506 8507<p> 8508Returns the running coroutine plus a boolean, 8509<b>true</b> when the running coroutine is the main one. 8510 8511 8512 8513 8514<p> 8515<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> 8516 8517 8518<p> 8519Returns the status of the coroutine <code>co</code>, as a string: 8520<code>"running"</code>, 8521if the coroutine is running 8522(that is, it is the one that called <code>status</code>); 8523<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, 8524or if it has not started running yet; 8525<code>"normal"</code> if the coroutine is active but not running 8526(that is, it has resumed another coroutine); 8527and <code>"dead"</code> if the coroutine has finished its body function, 8528or if it has stopped with an error. 8529 8530 8531 8532 8533<p> 8534<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> 8535 8536 8537<p> 8538Creates a new coroutine, with body <code>f</code>; 8539<code>f</code> must be a function. 8540Returns a function that resumes the coroutine each time it is called. 8541Any arguments passed to this function behave as the 8542extra arguments to <code>resume</code>. 8543The function returns the same values returned by <code>resume</code>, 8544except the first boolean. 8545In case of error, 8546the function closes the coroutine and propagates the error. 8547 8548 8549 8550 8551<p> 8552<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> 8553 8554 8555<p> 8556Suspends the execution of the calling coroutine. 8557Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>. 8558 8559 8560 8561 8562 8563 8564 8565<h2>6.3 – <a name="6.3">Modules</a></h2> 8566 8567<p> 8568The package library provides basic 8569facilities for loading modules in Lua. 8570It exports one function directly in the global environment: 8571<a href="#pdf-require"><code>require</code></a>. 8572Everything else is exported in the table <a name="pdf-package"><code>package</code></a>. 8573 8574 8575<p> 8576<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> 8577 8578 8579<p> 8580Loads the given module. 8581The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table 8582to determine whether <code>modname</code> is already loaded. 8583If it is, then <code>require</code> returns the value stored 8584at <code>package.loaded[modname]</code>. 8585(The absence of a second result in this case 8586signals that this call did not have to load the module.) 8587Otherwise, it tries to find a <em>loader</em> for the module. 8588 8589 8590<p> 8591To find a loader, 8592<code>require</code> is guided by the table <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 8593Each item in this table is a search function, 8594that searches for the module in a particular way. 8595By changing this table, 8596we can change how <code>require</code> looks for a module. 8597The following explanation is based on the default configuration 8598for <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 8599 8600 8601<p> 8602First <code>require</code> queries <code>package.preload[modname]</code>. 8603If it has a value, 8604this value (which must be a function) is the loader. 8605Otherwise <code>require</code> searches for a Lua loader using the 8606path stored in <a href="#pdf-package.path"><code>package.path</code></a>. 8607If that also fails, it searches for a C loader using the 8608path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 8609If that also fails, 8610it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>). 8611 8612 8613<p> 8614Once a loader is found, 8615<code>require</code> calls the loader with two arguments: 8616<code>modname</code> and an extra value, 8617a <em>loader data</em>, 8618also returned by the searcher. 8619The loader data can be any value useful to the module; 8620for the default searchers, 8621it indicates where the loader was found. 8622(For instance, if the loader came from a file, 8623this extra value is the file path.) 8624If the loader returns any non-nil value, 8625<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. 8626If the loader does not return a non-nil value and 8627has not assigned any value to <code>package.loaded[modname]</code>, 8628then <code>require</code> assigns <b>true</b> to this entry. 8629In any case, <code>require</code> returns the 8630final value of <code>package.loaded[modname]</code>. 8631Besides that value, <code>require</code> also returns as a second result 8632the loader data returned by the searcher, 8633which indicates how <code>require</code> found the module. 8634 8635 8636<p> 8637If there is any error loading or running the module, 8638or if it cannot find any loader for the module, 8639then <code>require</code> raises an error. 8640 8641 8642 8643 8644<p> 8645<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3> 8646 8647 8648<p> 8649A string describing some compile-time configurations for packages. 8650This string is a sequence of lines: 8651 8652<ul> 8653 8654<li>The first line is the directory separator string. 8655Default is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li> 8656 8657<li>The second line is the character that separates templates in a path. 8658Default is '<code>;</code>'.</li> 8659 8660<li>The third line is the string that marks the 8661substitution points in a template. 8662Default is '<code>?</code>'.</li> 8663 8664<li>The fourth line is a string that, in a path in Windows, 8665is replaced by the executable's directory. 8666Default is '<code>!</code>'.</li> 8667 8668<li>The fifth line is a mark to ignore all text after it 8669when building the <code>luaopen_</code> function name. 8670Default is '<code>-</code>'.</li> 8671 8672</ul> 8673 8674 8675 8676<p> 8677<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> 8678 8679 8680<p> 8681A string with the path used by <a href="#pdf-require"><code>require</code></a> 8682to search for a C loader. 8683 8684 8685<p> 8686Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way 8687it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, 8688using the environment variable <a name="pdf-LUA_CPATH_5_4"><code>LUA_CPATH_5_4</code></a>, 8689or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>, 8690or a default path defined in <code>luaconf.h</code>. 8691 8692 8693 8694 8695<p> 8696<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> 8697 8698 8699<p> 8700A table used by <a href="#pdf-require"><code>require</code></a> to control which 8701modules are already loaded. 8702When you require a module <code>modname</code> and 8703<code>package.loaded[modname]</code> is not false, 8704<a href="#pdf-require"><code>require</code></a> simply returns the value stored there. 8705 8706 8707<p> 8708This variable is only a reference to the real table; 8709assignments to this variable do not change the 8710table used by <a href="#pdf-require"><code>require</code></a>. 8711 8712 8713 8714 8715<p> 8716<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> 8717 8718 8719<p> 8720Dynamically links the host program with the C library <code>libname</code>. 8721 8722 8723<p> 8724If <code>funcname</code> is "<code>*</code>", 8725then it only links with the library, 8726making the symbols exported by the library 8727available to other dynamically linked libraries. 8728Otherwise, 8729it looks for a function <code>funcname</code> inside the library 8730and returns this function as a C function. 8731So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype 8732(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 8733 8734 8735<p> 8736This is a low-level function. 8737It completely bypasses the package and module system. 8738Unlike <a href="#pdf-require"><code>require</code></a>, 8739it does not perform any path searching and 8740does not automatically adds extensions. 8741<code>libname</code> must be the complete file name of the C library, 8742including if necessary a path and an extension. 8743<code>funcname</code> must be the exact name exported by the C library 8744(which may depend on the C compiler and linker used). 8745 8746 8747<p> 8748This function is not supported by Standard C. 8749As such, it is only available on some platforms 8750(Windows, Linux, Mac OS X, Solaris, BSD, 8751plus other Unix systems that support the <code>dlfcn</code> standard). 8752 8753 8754<p> 8755This function is inherently insecure, 8756as it allows Lua to call any function in any readable dynamic 8757library in the system. 8758(Lua calls any function assuming the function 8759has a proper prototype and respects a proper protocol 8760(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 8761Therefore, 8762calling an arbitrary function in an arbitrary dynamic library 8763more often than not results in an access violation.) 8764 8765 8766 8767 8768<p> 8769<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> 8770 8771 8772<p> 8773A string with the path used by <a href="#pdf-require"><code>require</code></a> 8774to search for a Lua loader. 8775 8776 8777<p> 8778At start-up, Lua initializes this variable with 8779the value of the environment variable <a name="pdf-LUA_PATH_5_4"><code>LUA_PATH_5_4</code></a> or 8780the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or 8781with a default path defined in <code>luaconf.h</code>, 8782if those environment variables are not defined. 8783A "<code>;;</code>" in the value of the environment variable 8784is replaced by the default path. 8785 8786 8787 8788 8789<p> 8790<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> 8791 8792 8793<p> 8794A table to store loaders for specific modules 8795(see <a href="#pdf-require"><code>require</code></a>). 8796 8797 8798<p> 8799This variable is only a reference to the real table; 8800assignments to this variable do not change the 8801table used by <a href="#pdf-require"><code>require</code></a>. 8802 8803 8804 8805 8806<p> 8807<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3> 8808 8809 8810<p> 8811A table used by <a href="#pdf-require"><code>require</code></a> to control how to find modules. 8812 8813 8814<p> 8815Each entry in this table is a <em>searcher function</em>. 8816When looking for a module, 8817<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, 8818with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its 8819sole argument. 8820If the searcher finds the module, 8821it returns another function, the module <em>loader</em>, 8822plus an extra value, a <em>loader data</em>, 8823that will be passed to that loader and 8824returned as a second result by <a href="#pdf-require"><code>require</code></a>. 8825If it cannot find the module, 8826it returns a string explaining why 8827(or <b>nil</b> if it has nothing to say). 8828 8829 8830<p> 8831Lua initializes this table with four searcher functions. 8832 8833 8834<p> 8835The first searcher simply looks for a loader in the 8836<a href="#pdf-package.preload"><code>package.preload</code></a> table. 8837 8838 8839<p> 8840The second searcher looks for a loader as a Lua library, 8841using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. 8842The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8843 8844 8845<p> 8846The third searcher looks for a loader as a C library, 8847using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 8848Again, 8849the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8850For instance, 8851if the C path is the string 8852 8853<pre> 8854 "./?.so;./?.dll;/usr/local/?/init.so" 8855</pre><p> 8856the searcher for module <code>foo</code> 8857will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, 8858and <code>/usr/local/foo/init.so</code>, in that order. 8859Once it finds a C library, 8860this searcher first uses a dynamic link facility to link the 8861application with the library. 8862Then it tries to find a C function inside the library to 8863be used as the loader. 8864The name of this C function is the string "<code>luaopen_</code>" 8865concatenated with a copy of the module name where each dot 8866is replaced by an underscore. 8867Moreover, if the module name has a hyphen, 8868its suffix after (and including) the first hyphen is removed. 8869For instance, if the module name is <code>a.b.c-v2.1</code>, 8870the function name will be <code>luaopen_a_b_c</code>. 8871 8872 8873<p> 8874The fourth searcher tries an <em>all-in-one loader</em>. 8875It searches the C path for a library for 8876the root name of the given module. 8877For instance, when requiring <code>a.b.c</code>, 8878it will search for a C library for <code>a</code>. 8879If found, it looks into it for an open function for 8880the submodule; 8881in our example, that would be <code>luaopen_a_b_c</code>. 8882With this facility, a package can pack several C submodules 8883into one single library, 8884with each submodule keeping its original open function. 8885 8886 8887<p> 8888All searchers except the first one (preload) return as the extra value 8889the file path where the module was found, 8890as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8891The first searcher always returns the string "<code>:preload:</code>". 8892 8893 8894<p> 8895Searchers should raise no errors and have no side effects in Lua. 8896(They may have side effects in C, 8897for instance by linking the application with a library.) 8898 8899 8900 8901 8902<p> 8903<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3> 8904 8905 8906<p> 8907Searches for the given <code>name</code> in the given <code>path</code>. 8908 8909 8910<p> 8911A path is a string containing a sequence of 8912<em>templates</em> separated by semicolons. 8913For each template, 8914the function replaces each interrogation mark (if any) 8915in the template with a copy of <code>name</code> 8916wherein all occurrences of <code>sep</code> 8917(a dot, by default) 8918were replaced by <code>rep</code> 8919(the system's directory separator, by default), 8920and then tries to open the resulting file name. 8921 8922 8923<p> 8924For instance, if the path is the string 8925 8926<pre> 8927 "./?.lua;./?.lc;/usr/local/?/init.lua" 8928</pre><p> 8929the search for the name <code>foo.a</code> 8930will try to open the files 8931<code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and 8932<code>/usr/local/foo/a/init.lua</code>, in that order. 8933 8934 8935<p> 8936Returns the resulting name of the first file that it can 8937open in read mode (after closing the file), 8938or <b>fail</b> plus an error message if none succeeds. 8939(This error message lists all file names it tried to open.) 8940 8941 8942 8943 8944 8945 8946 8947<h2>6.4 – <a name="6.4">String Manipulation</a></h2> 8948 8949 8950 8951<p> 8952This library provides generic functions for string manipulation, 8953such as finding and extracting substrings, and pattern matching. 8954When indexing a string in Lua, the first character is at position 1 8955(not at 0, as in C). 8956Indices are allowed to be negative and are interpreted as indexing backwards, 8957from the end of the string. 8958Thus, the last character is at position -1, and so on. 8959 8960 8961<p> 8962The string library provides all its functions inside the table 8963<a name="pdf-string"><code>string</code></a>. 8964It also sets a metatable for strings 8965where the <code>__index</code> field points to the <code>string</code> table. 8966Therefore, you can use the string functions in object-oriented style. 8967For instance, <code>string.byte(s,i)</code> 8968can be written as <code>s:byte(i)</code>. 8969 8970 8971<p> 8972The string library assumes one-byte character encodings. 8973 8974 8975<p> 8976<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> 8977Returns the internal numeric codes of the characters <code>s[i]</code>, 8978<code>s[i+1]</code>, ..., <code>s[j]</code>. 8979The default value for <code>i</code> is 1; 8980the default value for <code>j</code> is <code>i</code>. 8981These indices are corrected 8982following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>. 8983 8984 8985<p> 8986Numeric codes are not necessarily portable across platforms. 8987 8988 8989 8990 8991<p> 8992<hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> 8993Receives zero or more integers. 8994Returns a string with length equal to the number of arguments, 8995in which each character has the internal numeric code equal 8996to its corresponding argument. 8997 8998 8999<p> 9000Numeric codes are not necessarily portable across platforms. 9001 9002 9003 9004 9005<p> 9006<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3> 9007 9008 9009<p> 9010Returns a string containing a binary representation 9011(a <em>binary chunk</em>) 9012of the given function, 9013so that a later <a href="#pdf-load"><code>load</code></a> on this string returns 9014a copy of the function (but with new upvalues). 9015If <code>strip</code> is a true value, 9016the binary representation may not include all debug information 9017about the function, 9018to save space. 9019 9020 9021<p> 9022Functions with upvalues have only their number of upvalues saved. 9023When (re)loaded, 9024those upvalues receive fresh instances. 9025(See the <a href="#pdf-load"><code>load</code></a> function for details about 9026how these upvalues are initialized. 9027You can use the debug library to serialize 9028and reload the upvalues of a function 9029in a way adequate to your needs.) 9030 9031 9032 9033 9034<p> 9035<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> 9036 9037 9038<p> 9039Looks for the first match of 9040<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 9041If it finds a match, then <code>find</code> returns the indices of <code>s</code> 9042where this occurrence starts and ends; 9043otherwise, it returns <b>fail</b>. 9044A third, optional numeric argument <code>init</code> specifies 9045where to start the search; 9046its default value is 1 and can be negative. 9047A <b>true</b> as a fourth, optional argument <code>plain</code> 9048turns off the pattern matching facilities, 9049so the function does a plain "find substring" operation, 9050with no characters in <code>pattern</code> being considered magic. 9051 9052 9053<p> 9054If the pattern has captures, 9055then in a successful match 9056the captured values are also returned, 9057after the two indices. 9058 9059 9060 9061 9062<p> 9063<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> 9064 9065 9066<p> 9067Returns a formatted version of its variable number of arguments 9068following the description given in its first argument, 9069which must be a string. 9070The format string follows the same rules as the ISO C function <code>sprintf</code>. 9071The only differences are that the conversion specifiers and modifiers 9072<code>F</code>, <code>n</code>, <code>*</code>, <code>h</code>, <code>L</code>, and <code>l</code> are not supported 9073and that there is an extra specifier, <code>q</code>. 9074Both width and precision, when present, 9075are limited to two digits. 9076 9077 9078<p> 9079The specifier <code>q</code> formats booleans, nil, numbers, and strings 9080in a way that the result is a valid constant in Lua source code. 9081Booleans and nil are written in the obvious way 9082(<code>true</code>, <code>false</code>, <code>nil</code>). 9083Floats are written in hexadecimal, 9084to preserve full precision. 9085A string is written between double quotes, 9086using escape sequences when necessary to ensure that 9087it can safely be read back by the Lua interpreter. 9088For instance, the call 9089 9090<pre> 9091 string.format('%q', 'a string with "quotes" and \n new line') 9092</pre><p> 9093may produce the string: 9094 9095<pre> 9096 "a string with \"quotes\" and \ 9097 new line" 9098</pre><p> 9099This specifier does not support modifiers (flags, width, precision). 9100 9101 9102<p> 9103The conversion specifiers 9104<code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>, 9105<code>G</code>, and <code>g</code> all expect a number as argument. 9106The specifiers <code>c</code>, <code>d</code>, 9107<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> 9108expect an integer. 9109When Lua is compiled with a C89 compiler, 9110the specifiers <code>A</code> and <code>a</code> (hexadecimal floats) 9111do not support modifiers. 9112 9113 9114<p> 9115The specifier <code>s</code> expects a string; 9116if its argument is not a string, 9117it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 9118If the specifier has any modifier, 9119the corresponding string argument should not contain embedded zeros. 9120 9121 9122<p> 9123The specifier <code>p</code> formats the pointer 9124returned by <a href="#lua_topointer"><code>lua_topointer</code></a>. 9125That gives a unique string identifier for tables, userdata, 9126threads, strings, and functions. 9127For other values (numbers, nil, booleans), 9128this specifier results in a string representing 9129the pointer <code>NULL</code>. 9130 9131 9132 9133 9134<p> 9135<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern [, init])</code></a></h3> 9136Returns an iterator function that, 9137each time it is called, 9138returns the next captures from <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) 9139over the string <code>s</code>. 9140If <code>pattern</code> specifies no captures, 9141then the whole match is produced in each call. 9142A third, optional numeric argument <code>init</code> specifies 9143where to start the search; 9144its default value is 1 and can be negative. 9145 9146 9147<p> 9148As an example, the following loop 9149will iterate over all the words from string <code>s</code>, 9150printing one per line: 9151 9152<pre> 9153 s = "hello world from Lua" 9154 for w in string.gmatch(s, "%a+") do 9155 print(w) 9156 end 9157</pre><p> 9158The next example collects all pairs <code>key=value</code> from the 9159given string into a table: 9160 9161<pre> 9162 t = {} 9163 s = "from=world, to=Lua" 9164 for k, v in string.gmatch(s, "(%w+)=(%w+)") do 9165 t[k] = v 9166 end 9167</pre> 9168 9169<p> 9170For this function, a caret '<code>^</code>' at the start of a pattern does not 9171work as an anchor, as this would prevent the iteration. 9172 9173 9174 9175 9176<p> 9177<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> 9178Returns a copy of <code>s</code> 9179in which all (or the first <code>n</code>, if given) 9180occurrences of the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) have been 9181replaced by a replacement string specified by <code>repl</code>, 9182which can be a string, a table, or a function. 9183<code>gsub</code> also returns, as its second value, 9184the total number of matches that occurred. 9185The name <code>gsub</code> comes from <em>Global SUBstitution</em>. 9186 9187 9188<p> 9189If <code>repl</code> is a string, then its value is used for replacement. 9190The character <code>%</code> works as an escape character: 9191any sequence in <code>repl</code> of the form <code>%<em>d</em></code>, 9192with <em>d</em> between 1 and 9, 9193stands for the value of the <em>d</em>-th captured substring; 9194the sequence <code>%0</code> stands for the whole match; 9195the sequence <code>%%</code> stands for a single <code>%</code>. 9196 9197 9198<p> 9199If <code>repl</code> is a table, then the table is queried for every match, 9200using the first capture as the key. 9201 9202 9203<p> 9204If <code>repl</code> is a function, then this function is called every time a 9205match occurs, with all captured substrings passed as arguments, 9206in order. 9207 9208 9209<p> 9210In any case, 9211if the pattern specifies no captures, 9212then it behaves as if the whole pattern was inside a capture. 9213 9214 9215<p> 9216If the value returned by the table query or by the function call 9217is a string or a number, 9218then it is used as the replacement string; 9219otherwise, if it is <b>false</b> or <b>nil</b>, 9220then there is no replacement 9221(that is, the original match is kept in the string). 9222 9223 9224<p> 9225Here are some examples: 9226 9227<pre> 9228 x = string.gsub("hello world", "(%w+)", "%1 %1") 9229 --> x="hello hello world world" 9230 9231 x = string.gsub("hello world", "%w+", "%0 %0", 1) 9232 --> x="hello hello world" 9233 9234 x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 9235 --> x="world hello Lua from" 9236 9237 x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) 9238 --> x="home = /home/roberto, user = roberto" 9239 9240 x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 9241 return load(s)() 9242 end) 9243 --> x="4+5 = 9" 9244 9245 local t = {name="lua", version="5.4"} 9246 x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 9247 --> x="lua-5.4.tar.gz" 9248</pre> 9249 9250 9251 9252<p> 9253<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> 9254 9255 9256<p> 9257Receives a string and returns its length. 9258The empty string <code>""</code> has length 0. 9259Embedded zeros are counted, 9260so <code>"a\000bc\000"</code> has length 5. 9261 9262 9263 9264 9265<p> 9266<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> 9267 9268 9269<p> 9270Receives a string and returns a copy of this string with all 9271uppercase letters changed to lowercase. 9272All other characters are left unchanged. 9273The definition of what an uppercase letter is depends on the current locale. 9274 9275 9276 9277 9278<p> 9279<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> 9280 9281 9282<p> 9283Looks for the first <em>match</em> of 9284the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 9285If it finds one, then <code>match</code> returns 9286the captures from the pattern; 9287otherwise it returns <b>fail</b>. 9288If <code>pattern</code> specifies no captures, 9289then the whole match is returned. 9290A third, optional numeric argument <code>init</code> specifies 9291where to start the search; 9292its default value is 1 and can be negative. 9293 9294 9295 9296 9297<p> 9298<hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, ···)</code></a></h3> 9299 9300 9301<p> 9302Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc. 9303serialized in binary form (packed) 9304according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 9305 9306 9307 9308 9309<p> 9310<hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3> 9311 9312 9313<p> 9314Returns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a> 9315with the given format. 9316The format string cannot have the variable-length options 9317'<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">§6.4.2</a>). 9318 9319 9320 9321 9322<p> 9323<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3> 9324 9325 9326<p> 9327Returns a string that is the concatenation of <code>n</code> copies of 9328the string <code>s</code> separated by the string <code>sep</code>. 9329The default value for <code>sep</code> is the empty string 9330(that is, no separator). 9331Returns the empty string if <code>n</code> is not positive. 9332 9333 9334<p> 9335(Note that it is very easy to exhaust the memory of your machine 9336with a single call to this function.) 9337 9338 9339 9340 9341<p> 9342<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> 9343 9344 9345<p> 9346Returns a string that is the string <code>s</code> reversed. 9347 9348 9349 9350 9351<p> 9352<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> 9353 9354 9355<p> 9356Returns the substring of <code>s</code> that 9357starts at <code>i</code> and continues until <code>j</code>; 9358<code>i</code> and <code>j</code> can be negative. 9359If <code>j</code> is absent, then it is assumed to be equal to -1 9360(which is the same as the string length). 9361In particular, 9362the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 9363with length <code>j</code>, 9364and <code>string.sub(s, -i)</code> (for a positive <code>i</code>) 9365returns a suffix of <code>s</code> 9366with length <code>i</code>. 9367 9368 9369<p> 9370If, after the translation of negative indices, 9371<code>i</code> is less than 1, 9372it is corrected to 1. 9373If <code>j</code> is greater than the string length, 9374it is corrected to that length. 9375If, after these corrections, 9376<code>i</code> is greater than <code>j</code>, 9377the function returns the empty string. 9378 9379 9380 9381 9382<p> 9383<hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3> 9384 9385 9386<p> 9387Returns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>) 9388according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 9389An optional <code>pos</code> marks where 9390to start reading in <code>s</code> (default is 1). 9391After the read values, 9392this function also returns the index of the first unread byte in <code>s</code>. 9393 9394 9395 9396 9397<p> 9398<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> 9399 9400 9401<p> 9402Receives a string and returns a copy of this string with all 9403lowercase letters changed to uppercase. 9404All other characters are left unchanged. 9405The definition of what a lowercase letter is depends on the current locale. 9406 9407 9408 9409 9410 9411 9412 9413<h3>6.4.1 – <a name="6.4.1">Patterns</a></h3> 9414 9415 9416 9417<p> 9418Patterns in Lua are described by regular strings, 9419which are interpreted as patterns by the pattern-matching functions 9420<a href="#pdf-string.find"><code>string.find</code></a>, 9421<a href="#pdf-string.gmatch"><code>string.gmatch</code></a>, 9422<a href="#pdf-string.gsub"><code>string.gsub</code></a>, 9423and <a href="#pdf-string.match"><code>string.match</code></a>. 9424This section describes the syntax and the meaning 9425(that is, what they match) of these strings. 9426 9427 9428 9429 9430 9431<h4>Character Class:</h4><p> 9432A <em>character class</em> is used to represent a set of characters. 9433The following combinations are allowed in describing a character class: 9434 9435<ul> 9436 9437<li><b><em>x</em>: </b> 9438(where <em>x</em> is not one of the <em>magic characters</em> 9439<code>^$()%.[]*+-?</code>) 9440represents the character <em>x</em> itself. 9441</li> 9442 9443<li><b><code>.</code>: </b> (a dot) represents all characters.</li> 9444 9445<li><b><code>%a</code>: </b> represents all letters.</li> 9446 9447<li><b><code>%c</code>: </b> represents all control characters.</li> 9448 9449<li><b><code>%d</code>: </b> represents all digits.</li> 9450 9451<li><b><code>%g</code>: </b> represents all printable characters except space.</li> 9452 9453<li><b><code>%l</code>: </b> represents all lowercase letters.</li> 9454 9455<li><b><code>%p</code>: </b> represents all punctuation characters.</li> 9456 9457<li><b><code>%s</code>: </b> represents all space characters.</li> 9458 9459<li><b><code>%u</code>: </b> represents all uppercase letters.</li> 9460 9461<li><b><code>%w</code>: </b> represents all alphanumeric characters.</li> 9462 9463<li><b><code>%x</code>: </b> represents all hexadecimal digits.</li> 9464 9465<li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character) 9466represents the character <em>x</em>. 9467This is the standard way to escape the magic characters. 9468Any non-alphanumeric character 9469(including all punctuation characters, even the non-magical) 9470can be preceded by a '<code>%</code>' to represent itself in a pattern. 9471</li> 9472 9473<li><b><code>[<em>set</em>]</code>: </b> 9474represents the class which is the union of all 9475characters in <em>set</em>. 9476A range of characters can be specified by 9477separating the end characters of the range, 9478in ascending order, with a '<code>-</code>'. 9479All classes <code>%</code><em>x</em> described above can also be used as 9480components in <em>set</em>. 9481All other characters in <em>set</em> represent themselves. 9482For example, <code>[%w_]</code> (or <code>[_%w]</code>) 9483represents all alphanumeric characters plus the underscore, 9484<code>[0-7]</code> represents the octal digits, 9485and <code>[0-7%l%-]</code> represents the octal digits plus 9486the lowercase letters plus the '<code>-</code>' character. 9487 9488 9489<p> 9490You can put a closing square bracket in a set 9491by positioning it as the first character in the set. 9492You can put a hyphen in a set 9493by positioning it as the first or the last character in the set. 9494(You can also use an escape for both cases.) 9495 9496 9497<p> 9498The interaction between ranges and classes is not defined. 9499Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> 9500have no meaning. 9501</li> 9502 9503<li><b><code>[^<em>set</em>]</code>: </b> 9504represents the complement of <em>set</em>, 9505where <em>set</em> is interpreted as above. 9506</li> 9507 9508</ul><p> 9509For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), 9510the corresponding uppercase letter represents the complement of the class. 9511For instance, <code>%S</code> represents all non-space characters. 9512 9513 9514<p> 9515The definitions of letter, space, and other character groups 9516depend on the current locale. 9517In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. 9518 9519 9520 9521 9522 9523<h4>Pattern Item:</h4><p> 9524A <em>pattern item</em> can be 9525 9526<ul> 9527 9528<li> 9529a single character class, 9530which matches any single character in the class; 9531</li> 9532 9533<li> 9534a single character class followed by '<code>*</code>', 9535which matches sequences of zero or more characters in the class. 9536These repetition items will always match the longest possible sequence; 9537</li> 9538 9539<li> 9540a single character class followed by '<code>+</code>', 9541which matches sequences of one or more characters in the class. 9542These repetition items will always match the longest possible sequence; 9543</li> 9544 9545<li> 9546a single character class followed by '<code>-</code>', 9547which also matches sequences of zero or more characters in the class. 9548Unlike '<code>*</code>', 9549these repetition items will always match the shortest possible sequence; 9550</li> 9551 9552<li> 9553a single character class followed by '<code>?</code>', 9554which matches zero or one occurrence of a character in the class. 9555It always matches one occurrence if possible; 9556</li> 9557 9558<li> 9559<code>%<em>n</em></code>, for <em>n</em> between 1 and 9; 9560such item matches a substring equal to the <em>n</em>-th captured string 9561(see below); 9562</li> 9563 9564<li> 9565<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; 9566such item matches strings that start with <em>x</em>, end with <em>y</em>, 9567and where the <em>x</em> and <em>y</em> are <em>balanced</em>. 9568This means that, if one reads the string from left to right, 9569counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, 9570the ending <em>y</em> is the first <em>y</em> where the count reaches 0. 9571For instance, the item <code>%b()</code> matches expressions with 9572balanced parentheses. 9573</li> 9574 9575<li> 9576<code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>; 9577such item matches an empty string at any position such that 9578the next character belongs to <em>set</em> 9579and the previous character does not belong to <em>set</em>. 9580The set <em>set</em> is interpreted as previously described. 9581The beginning and the end of the subject are handled as if 9582they were the character '<code>\0</code>'. 9583</li> 9584 9585</ul> 9586 9587 9588 9589 9590<h4>Pattern:</h4><p> 9591A <em>pattern</em> is a sequence of pattern items. 9592A caret '<code>^</code>' at the beginning of a pattern anchors the match at the 9593beginning of the subject string. 9594A '<code>$</code>' at the end of a pattern anchors the match at the 9595end of the subject string. 9596At other positions, 9597'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. 9598 9599 9600 9601 9602 9603<h4>Captures:</h4><p> 9604A pattern can contain sub-patterns enclosed in parentheses; 9605they describe <em>captures</em>. 9606When a match succeeds, the substrings of the subject string 9607that match captures are stored (<em>captured</em>) for future use. 9608Captures are numbered according to their left parentheses. 9609For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, 9610the part of the string matching <code>"a*(.)%w(%s*)"</code> is 9611stored as the first capture, and therefore has number 1; 9612the character matching "<code>.</code>" is captured with number 2, 9613and the part matching "<code>%s*</code>" has number 3. 9614 9615 9616<p> 9617As a special case, the capture <code>()</code> captures 9618the current string position (a number). 9619For instance, if we apply the pattern <code>"()aa()"</code> on the 9620string <code>"flaaap"</code>, there will be two captures: 3 and 5. 9621 9622 9623 9624 9625 9626<h4>Multiple matches:</h4><p> 9627The function <a href="#pdf-string.gsub"><code>string.gsub</code></a> and the iterator <a href="#pdf-string.gmatch"><code>string.gmatch</code></a> 9628match multiple occurrences of the given pattern in the subject. 9629For these functions, 9630a new match is considered valid only 9631if it ends at least one byte after the end of the previous match. 9632In other words, the pattern machine never accepts the 9633empty string as a match immediately after another match. 9634As an example, 9635consider the results of the following code: 9636 9637<pre> 9638 > string.gsub("abc", "()a*()", print); 9639 --> 1 2 9640 --> 3 3 9641 --> 4 4 9642</pre><p> 9643The second and third results come from Lua matching an empty 9644string after '<code>b</code>' and another one after '<code>c</code>'. 9645Lua does not match an empty string after '<code>a</code>', 9646because it would end at the same position of the previous match. 9647 9648 9649 9650 9651 9652 9653 9654<h3>6.4.2 – <a name="6.4.2">Format Strings for Pack and Unpack</a></h3> 9655 9656<p> 9657The first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>, 9658<a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a> 9659is a format string, 9660which describes the layout of the structure being created or read. 9661 9662 9663<p> 9664A format string is a sequence of conversion options. 9665The conversion options are as follows: 9666 9667<ul> 9668<li><b><code><</code>: </b>sets little endian</li> 9669<li><b><code>></code>: </b>sets big endian</li> 9670<li><b><code>=</code>: </b>sets native endian</li> 9671<li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code> 9672(default is native alignment)</li> 9673<li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li> 9674<li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li> 9675<li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li> 9676<li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li> 9677<li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li> 9678<li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li> 9679<li><b><code>j</code>: </b>a <code>lua_Integer</code></li> 9680<li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li> 9681<li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li> 9682<li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes 9683(default is native size)</li> 9684<li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes 9685(default is native size)</li> 9686<li><b><code>f</code>: </b>a <code>float</code> (native size)</li> 9687<li><b><code>d</code>: </b>a <code>double</code> (native size)</li> 9688<li><b><code>n</code>: </b>a <code>lua_Number</code></li> 9689<li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li> 9690<li><b><code>z</code>: </b>a zero-terminated string</li> 9691<li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length 9692coded as an unsigned integer with <code>n</code> bytes 9693(default is a <code>size_t</code>)</li> 9694<li><b><code>x</code>: </b>one byte of padding</li> 9695<li><b><code>X<em>op</em></code>: </b>an empty item that aligns 9696according to option <code>op</code> 9697(which is otherwise ignored)</li> 9698<li><b>'<code> </code>': </b>(space) ignored</li> 9699</ul><p> 9700(A "<code>[<em>n</em>]</code>" means an optional integral numeral.) 9701Except for padding, spaces, and configurations 9702(options "<code>xX <=>!</code>"), 9703each option corresponds to an argument in <a href="#pdf-string.pack"><code>string.pack</code></a> 9704or a result in <a href="#pdf-string.unpack"><code>string.unpack</code></a>. 9705 9706 9707<p> 9708For 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>", 9709<code>n</code> can be any integer between 1 and 16. 9710All integral options check overflows; 9711<a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size; 9712<a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer. 9713For the unsigned options, 9714Lua integers are treated as unsigned values too. 9715 9716 9717<p> 9718Any format string starts as if prefixed by "<code>!1=</code>", 9719that is, 9720with maximum alignment of 1 (no alignment) 9721and native endianness. 9722 9723 9724<p> 9725Native endianness assumes that the whole system is 9726either big or little endian. 9727The packing functions will not emulate correctly the behavior 9728of mixed-endian formats. 9729 9730 9731<p> 9732Alignment works as follows: 9733For each option, 9734the format gets extra padding until the data starts 9735at an offset that is a multiple of the minimum between the 9736option size and the maximum alignment; 9737this minimum must be a power of 2. 9738Options "<code>c</code>" and "<code>z</code>" are not aligned; 9739option "<code>s</code>" follows the alignment of its starting integer. 9740 9741 9742<p> 9743All padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a> 9744and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>. 9745 9746 9747 9748 9749 9750 9751 9752<h2>6.5 – <a name="6.5">UTF-8 Support</a></h2> 9753 9754<p> 9755This library provides basic support for UTF-8 encoding. 9756It provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>. 9757This library does not provide any support for Unicode other 9758than the handling of the encoding. 9759Any operation that needs the meaning of a character, 9760such as character classification, is outside its scope. 9761 9762 9763<p> 9764Unless stated otherwise, 9765all functions that expect a byte position as a parameter 9766assume that the given position is either the start of a byte sequence 9767or one plus the length of the subject string. 9768As in the string library, 9769negative indices count from the end of the string. 9770 9771 9772<p> 9773Functions that create byte sequences 9774accept all values up to <code>0x7FFFFFFF</code>, 9775as defined in the original UTF-8 specification; 9776that implies byte sequences of up to six bytes. 9777 9778 9779<p> 9780Functions that interpret byte sequences only accept 9781valid sequences (well formed and not overlong). 9782By default, they only accept byte sequences 9783that result in valid Unicode code points, 9784rejecting values greater than <code>10FFFF</code> and surrogates. 9785A boolean argument <code>lax</code>, when available, 9786lifts these checks, 9787so that all values up to <code>0x7FFFFFFF</code> are accepted. 9788(Not well formed and overlong sequences are still rejected.) 9789 9790 9791<p> 9792<hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3> 9793 9794 9795<p> 9796Receives zero or more integers, 9797converts each one to its corresponding UTF-8 byte sequence 9798and returns a string with the concatenation of all these sequences. 9799 9800 9801 9802 9803<p> 9804<hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3> 9805 9806 9807<p> 9808The pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xFD][\x80-\xBF]*</code>" 9809(see <a href="#6.4.1">§6.4.1</a>), 9810which matches exactly one UTF-8 byte sequence, 9811assuming that the subject is a valid UTF-8 string. 9812 9813 9814 9815 9816<p> 9817<hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s [, lax])</code></a></h3> 9818 9819 9820<p> 9821Returns values so that the construction 9822 9823<pre> 9824 for p, c in utf8.codes(s) do <em>body</em> end 9825</pre><p> 9826will iterate over all UTF-8 characters in string <code>s</code>, 9827with <code>p</code> being the position (in bytes) and <code>c</code> the code point 9828of each character. 9829It raises an error if it meets any invalid byte sequence. 9830 9831 9832 9833 9834<p> 9835<hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j [, lax]]])</code></a></h3> 9836 9837 9838<p> 9839Returns the code points (as integers) from all characters in <code>s</code> 9840that start between byte position <code>i</code> and <code>j</code> (both included). 9841The default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>. 9842It raises an error if it meets any invalid byte sequence. 9843 9844 9845 9846 9847<p> 9848<hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j [, lax]]])</code></a></h3> 9849 9850 9851<p> 9852Returns the number of UTF-8 characters in string <code>s</code> 9853that start between positions <code>i</code> and <code>j</code> (both inclusive). 9854The default for <code>i</code> is 1 and for <code>j</code> is -1. 9855If it finds any invalid byte sequence, 9856returns <b>fail</b> plus the position of the first invalid byte. 9857 9858 9859 9860 9861<p> 9862<hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3> 9863 9864 9865<p> 9866Returns the position (in bytes) where the encoding of the 9867<code>n</code>-th character of <code>s</code> 9868(counting from position <code>i</code>) starts. 9869A negative <code>n</code> gets characters before position <code>i</code>. 9870The default for <code>i</code> is 1 when <code>n</code> is non-negative 9871and <code>#s + 1</code> otherwise, 9872so that <code>utf8.offset(s, -n)</code> gets the offset of the 9873<code>n</code>-th character from the end of the string. 9874If the specified character is neither in the subject 9875nor right after its end, 9876the function returns <b>fail</b>. 9877 9878 9879<p> 9880As a special case, 9881when <code>n</code> is 0 the function returns the start of the encoding 9882of the character that contains the <code>i</code>-th byte of <code>s</code>. 9883 9884 9885<p> 9886This function assumes that <code>s</code> is a valid UTF-8 string. 9887 9888 9889 9890 9891 9892 9893 9894<h2>6.6 – <a name="6.6">Table Manipulation</a></h2> 9895 9896<p> 9897This library provides generic functions for table manipulation. 9898It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. 9899 9900 9901<p> 9902Remember that, whenever an operation needs the length of a table, 9903all caveats about the length operator apply (see <a href="#3.4.7">§3.4.7</a>). 9904All functions ignore non-numeric keys 9905in the tables given as arguments. 9906 9907 9908<p> 9909<hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3> 9910 9911 9912<p> 9913Given a list where all elements are strings or numbers, 9914returns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>. 9915The default value for <code>sep</code> is the empty string, 9916the default for <code>i</code> is 1, 9917and the default for <code>j</code> is <code>#list</code>. 9918If <code>i</code> is greater than <code>j</code>, returns the empty string. 9919 9920 9921 9922 9923<p> 9924<hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3> 9925 9926 9927<p> 9928Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>, 9929shifting up the elements 9930<code>list[pos], list[pos+1], ···, list[#list]</code>. 9931The default value for <code>pos</code> is <code>#list+1</code>, 9932so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end 9933of the list <code>t</code>. 9934 9935 9936 9937 9938<p> 9939<hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3> 9940 9941 9942<p> 9943Moves elements from the table <code>a1</code> to the table <code>a2</code>, 9944performing the equivalent to the following 9945multiple assignment: 9946<code>a2[t],··· = a1[f],···,a1[e]</code>. 9947The default for <code>a2</code> is <code>a1</code>. 9948The destination range can overlap with the source range. 9949The number of elements to be moved must fit in a Lua integer. 9950 9951 9952<p> 9953Returns the destination table <code>a2</code>. 9954 9955 9956 9957 9958<p> 9959<hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3> 9960 9961 9962<p> 9963Returns a new table with all arguments stored into keys 1, 2, etc. 9964and with a field "<code>n</code>" with the total number of arguments. 9965Note that the resulting table may not be a sequence, 9966if some arguments are <b>nil</b>. 9967 9968 9969 9970 9971<p> 9972<hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3> 9973 9974 9975<p> 9976Removes from <code>list</code> the element at position <code>pos</code>, 9977returning the value of the removed element. 9978When <code>pos</code> is an integer between 1 and <code>#list</code>, 9979it shifts down the elements 9980<code>list[pos+1], list[pos+2], ···, list[#list]</code> 9981and erases element <code>list[#list]</code>; 9982The index <code>pos</code> can also be 0 when <code>#list</code> is 0, 9983or <code>#list + 1</code>. 9984 9985 9986<p> 9987The default value for <code>pos</code> is <code>#list</code>, 9988so that a call <code>table.remove(l)</code> removes the last element 9989of the list <code>l</code>. 9990 9991 9992 9993 9994<p> 9995<hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3> 9996 9997 9998<p> 9999Sorts the list elements in a given order, <em>in-place</em>, 10000from <code>list[1]</code> to <code>list[#list]</code>. 10001If <code>comp</code> is given, 10002then it must be a function that receives two list elements 10003and returns true when the first element must come 10004before the second in the final order, 10005so that, after the sort, 10006<code>i <= j</code> implies <code>not comp(list[j],list[i])</code>. 10007If <code>comp</code> is not given, 10008then the standard Lua operator <code><</code> is used instead. 10009 10010 10011<p> 10012The <code>comp</code> function must define a consistent order; 10013more formally, the function must define a strict weak order. 10014(A weak order is similar to a total order, 10015but it can equate different elements for comparison purposes.) 10016 10017 10018<p> 10019The sort algorithm is not stable: 10020Different elements considered equal by the given order 10021may have their relative positions changed by the sort. 10022 10023 10024 10025 10026<p> 10027<hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3> 10028 10029 10030<p> 10031Returns the elements from the given list. 10032This function is equivalent to 10033 10034<pre> 10035 return list[i], list[i+1], ···, list[j] 10036</pre><p> 10037By default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>. 10038 10039 10040 10041 10042 10043 10044 10045<h2>6.7 – <a name="6.7">Mathematical Functions</a></h2> 10046 10047<p> 10048This library provides basic mathematical functions. 10049It provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>. 10050Functions with the annotation "<code>integer/float</code>" give 10051integer results for integer arguments 10052and float results for non-integer arguments. 10053The rounding functions 10054<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> 10055return an integer when the result fits in the range of an integer, 10056or a float otherwise. 10057 10058 10059<p> 10060<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> 10061 10062 10063<p> 10064Returns the maximum value between <code>x</code> and <code>-x</code>. (integer/float) 10065 10066 10067 10068 10069<p> 10070<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> 10071 10072 10073<p> 10074Returns the arc cosine of <code>x</code> (in radians). 10075 10076 10077 10078 10079<p> 10080<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> 10081 10082 10083<p> 10084Returns the arc sine of <code>x</code> (in radians). 10085 10086 10087 10088 10089<p> 10090<hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3> 10091 10092 10093<p> 10094 10095Returns the arc tangent of <code>y/x</code> (in radians), 10096but uses the signs of both arguments to find the 10097quadrant of the result. 10098It also handles correctly the case of <code>x</code> being zero. 10099 10100 10101<p> 10102The default value for <code>x</code> is 1, 10103so that the call <code>math.atan(y)</code> 10104returns the arc tangent of <code>y</code>. 10105 10106 10107 10108 10109<p> 10110<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> 10111 10112 10113<p> 10114Returns the smallest integral value greater than or equal to <code>x</code>. 10115 10116 10117 10118 10119<p> 10120<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> 10121 10122 10123<p> 10124Returns the cosine of <code>x</code> (assumed to be in radians). 10125 10126 10127 10128 10129<p> 10130<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> 10131 10132 10133<p> 10134Converts the angle <code>x</code> from radians to degrees. 10135 10136 10137 10138 10139<p> 10140<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> 10141 10142 10143<p> 10144Returns the value <em>e<sup>x</sup></em> 10145(where <code>e</code> is the base of natural logarithms). 10146 10147 10148 10149 10150<p> 10151<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> 10152 10153 10154<p> 10155Returns the largest integral value less than or equal to <code>x</code>. 10156 10157 10158 10159 10160<p> 10161<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> 10162 10163 10164<p> 10165Returns the remainder of the division of <code>x</code> by <code>y</code> 10166that rounds the quotient towards zero. (integer/float) 10167 10168 10169 10170 10171<p> 10172<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> 10173 10174 10175<p> 10176The float value <code>HUGE_VAL</code>, 10177a value greater than any other numeric value. 10178 10179 10180 10181 10182<p> 10183<hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3> 10184 10185 10186<p> 10187Returns the logarithm of <code>x</code> in the given base. 10188The default for <code>base</code> is <em>e</em> 10189(so that the function returns the natural logarithm of <code>x</code>). 10190 10191 10192 10193 10194<p> 10195<hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> 10196 10197 10198<p> 10199Returns the argument with the maximum value, 10200according to the Lua operator <code><</code>. 10201 10202 10203 10204 10205<p> 10206<hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3> 10207An integer with the maximum value for an integer. 10208 10209 10210 10211 10212<p> 10213<hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> 10214 10215 10216<p> 10217Returns the argument with the minimum value, 10218according to the Lua operator <code><</code>. 10219 10220 10221 10222 10223<p> 10224<hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3> 10225An integer with the minimum value for an integer. 10226 10227 10228 10229 10230<p> 10231<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> 10232 10233 10234<p> 10235Returns the integral part of <code>x</code> and the fractional part of <code>x</code>. 10236Its second result is always a float. 10237 10238 10239 10240 10241<p> 10242<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> 10243 10244 10245<p> 10246The value of <em>π</em>. 10247 10248 10249 10250 10251<p> 10252<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> 10253 10254 10255<p> 10256Converts the angle <code>x</code> from degrees to radians. 10257 10258 10259 10260 10261<p> 10262<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> 10263 10264 10265<p> 10266When called without arguments, 10267returns a pseudo-random float with uniform distribution 10268in the range <em>[0,1)</em>. 10269When called with two integers <code>m</code> and <code>n</code>, 10270<code>math.random</code> returns a pseudo-random integer 10271with uniform distribution in the range <em>[m, n]</em>. 10272The call <code>math.random(n)</code>, for a positive <code>n</code>, 10273is equivalent to <code>math.random(1,n)</code>. 10274The call <code>math.random(0)</code> produces an integer with 10275all bits (pseudo)random. 10276 10277 10278<p> 10279This function uses the <code>xoshiro256**</code> algorithm to produce 10280pseudo-random 64-bit integers, 10281which are the results of calls with argument 0. 10282Other results (ranges and floats) 10283are unbiased extracted from these integers. 10284 10285 10286<p> 10287Lua initializes its pseudo-random generator with the equivalent of 10288a call to <a href="#pdf-math.randomseed"><code>math.randomseed</code></a> with no arguments, 10289so that <code>math.random</code> should generate 10290different sequences of results each time the program runs. 10291 10292 10293 10294 10295<p> 10296<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed ([x [, y]])</code></a></h3> 10297 10298 10299<p> 10300When called with at least one argument, 10301the integer parameters <code>x</code> and <code>y</code> are 10302joined into a 128-bit <em>seed</em> that 10303is used to reinitialize the pseudo-random generator; 10304equal seeds produce equal sequences of numbers. 10305The default for <code>y</code> is zero. 10306 10307 10308<p> 10309When called with no arguments, 10310Lua generates a seed with 10311a weak attempt for randomness. 10312 10313 10314<p> 10315This function returns the two seed components 10316that were effectively used, 10317so that setting them again repeats the sequence. 10318 10319 10320<p> 10321To ensure a required level of randomness to the initial state 10322(or contrarily, to have a deterministic sequence, 10323for instance when debugging a program), 10324you should call <a href="#pdf-math.randomseed"><code>math.randomseed</code></a> with explicit arguments. 10325 10326 10327 10328 10329<p> 10330<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> 10331 10332 10333<p> 10334Returns the sine of <code>x</code> (assumed to be in radians). 10335 10336 10337 10338 10339<p> 10340<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> 10341 10342 10343<p> 10344Returns the square root of <code>x</code>. 10345(You can also use the expression <code>x^0.5</code> to compute this value.) 10346 10347 10348 10349 10350<p> 10351<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> 10352 10353 10354<p> 10355Returns the tangent of <code>x</code> (assumed to be in radians). 10356 10357 10358 10359 10360<p> 10361<hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3> 10362 10363 10364<p> 10365If the value <code>x</code> is convertible to an integer, 10366returns that integer. 10367Otherwise, returns <b>fail</b>. 10368 10369 10370 10371 10372<p> 10373<hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3> 10374 10375 10376<p> 10377Returns "<code>integer</code>" if <code>x</code> is an integer, 10378"<code>float</code>" if it is a float, 10379or <b>fail</b> if <code>x</code> is not a number. 10380 10381 10382 10383 10384<p> 10385<hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3> 10386 10387 10388<p> 10389Returns a boolean, 10390<b>true</b> if and only if integer <code>m</code> is below integer <code>n</code> when 10391they are compared as unsigned integers. 10392 10393 10394 10395 10396 10397 10398 10399<h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2> 10400 10401<p> 10402The I/O library provides two different styles for file manipulation. 10403The first one uses implicit file handles; 10404that is, there are operations to set a default input file and a 10405default output file, 10406and all input/output operations are done over these default files. 10407The second style uses explicit file handles. 10408 10409 10410<p> 10411When using implicit file handles, 10412all operations are supplied by table <a name="pdf-io"><code>io</code></a>. 10413When using explicit file handles, 10414the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle 10415and then all operations are supplied as methods of the file handle. 10416 10417 10418<p> 10419The metatable for file handles provides metamethods 10420for <code>__gc</code> and <code>__close</code> that try 10421to close the file when called. 10422 10423 10424<p> 10425The table <code>io</code> also provides 10426three predefined file handles with their usual meanings from C: 10427<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>. 10428The I/O library never closes these files. 10429 10430 10431<p> 10432Unless otherwise stated, 10433all I/O functions return <b>fail</b> on failure, 10434plus an error message as a second result and 10435a system-dependent error code as a third result, 10436and some non-false value on success. 10437On non-POSIX systems, 10438the computation of the error message and error code 10439in case of errors 10440may be not thread safe, 10441because they rely on the global C variable <code>errno</code>. 10442 10443 10444<p> 10445<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> 10446 10447 10448<p> 10449Equivalent to <code>file:close()</code>. 10450Without a <code>file</code>, closes the default output file. 10451 10452 10453 10454 10455<p> 10456<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> 10457 10458 10459<p> 10460Equivalent to <code>io.output():flush()</code>. 10461 10462 10463 10464 10465<p> 10466<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> 10467 10468 10469<p> 10470When called with a file name, it opens the named file (in text mode), 10471and sets its handle as the default input file. 10472When called with a file handle, 10473it simply sets this file handle as the default input file. 10474When called without arguments, 10475it returns the current default input file. 10476 10477 10478<p> 10479In case of errors this function raises the error, 10480instead of returning an error code. 10481 10482 10483 10484 10485<p> 10486<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, ···])</code></a></h3> 10487 10488 10489<p> 10490Opens the given file name in read mode 10491and returns an iterator function that 10492works like <code>file:lines(···)</code> over the opened file. 10493When the iterator function fails to read any value, 10494it automatically closes the file. 10495Besides the iterator function, 10496<code>io.lines</code> returns three other values: 10497two <b>nil</b> values as placeholders, 10498plus the created file handle. 10499Therefore, when used in a generic <b>for</b> loop, 10500the file is closed also if the loop is interrupted by an 10501error or a <b>break</b>. 10502 10503 10504<p> 10505The call <code>io.lines()</code> (with no file name) is equivalent 10506to <code>io.input():lines("l")</code>; 10507that is, it iterates over the lines of the default input file. 10508In this case, the iterator does not close the file when the loop ends. 10509 10510 10511<p> 10512In case of errors opening the file, 10513this function raises the error, 10514instead of returning an error code. 10515 10516 10517 10518 10519<p> 10520<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> 10521 10522 10523<p> 10524This function opens a file, 10525in the mode specified in the string <code>mode</code>. 10526In case of success, 10527it returns a new file handle. 10528 10529 10530<p> 10531The <code>mode</code> string can be any of the following: 10532 10533<ul> 10534<li><b>"<code>r</code>": </b> read mode (the default);</li> 10535<li><b>"<code>w</code>": </b> write mode;</li> 10536<li><b>"<code>a</code>": </b> append mode;</li> 10537<li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li> 10538<li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li> 10539<li><b>"<code>a+</code>": </b> append update mode, previous data is preserved, 10540 writing is only allowed at the end of file.</li> 10541</ul><p> 10542The <code>mode</code> string can also have a '<code>b</code>' at the end, 10543which is needed in some systems to open the file in binary mode. 10544 10545 10546 10547 10548<p> 10549<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> 10550 10551 10552<p> 10553Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. 10554 10555 10556 10557 10558<p> 10559<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> 10560 10561 10562<p> 10563This function is system dependent and is not available 10564on all platforms. 10565 10566 10567<p> 10568Starts the program <code>prog</code> in a separated process and returns 10569a file handle that you can use to read data from this program 10570(if <code>mode</code> is <code>"r"</code>, the default) 10571or to write data to this program 10572(if <code>mode</code> is <code>"w"</code>). 10573 10574 10575 10576 10577<p> 10578<hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> 10579 10580 10581<p> 10582Equivalent to <code>io.input():read(···)</code>. 10583 10584 10585 10586 10587<p> 10588<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> 10589 10590 10591<p> 10592In case of success, 10593returns a handle for a temporary file. 10594This file is opened in update mode 10595and it is automatically removed when the program ends. 10596 10597 10598 10599 10600<p> 10601<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> 10602 10603 10604<p> 10605Checks whether <code>obj</code> is a valid file handle. 10606Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, 10607<code>"closed file"</code> if <code>obj</code> is a closed file handle, 10608or <b>fail</b> if <code>obj</code> is not a file handle. 10609 10610 10611 10612 10613<p> 10614<hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> 10615 10616 10617<p> 10618Equivalent to <code>io.output():write(···)</code>. 10619 10620 10621 10622 10623<p> 10624<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> 10625 10626 10627<p> 10628Closes <code>file</code>. 10629Note that files are automatically closed when 10630their handles are garbage collected, 10631but that takes an unpredictable amount of time to happen. 10632 10633 10634<p> 10635When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>, 10636<a href="#pdf-file:close"><code>file:close</code></a> returns the same values 10637returned by <a href="#pdf-os.execute"><code>os.execute</code></a>. 10638 10639 10640 10641 10642<p> 10643<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> 10644 10645 10646<p> 10647Saves any written data to <code>file</code>. 10648 10649 10650 10651 10652<p> 10653<hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3> 10654 10655 10656<p> 10657Returns an iterator function that, 10658each time it is called, 10659reads the file according to the given formats. 10660When no format is given, 10661uses "<code>l</code>" as a default. 10662As an example, the construction 10663 10664<pre> 10665 for c in file:lines(1) do <em>body</em> end 10666</pre><p> 10667will iterate over all characters of the file, 10668starting at the current position. 10669Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file 10670when the loop ends. 10671 10672 10673 10674 10675<p> 10676<hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> 10677 10678 10679<p> 10680Reads the file <code>file</code>, 10681according to the given formats, which specify what to read. 10682For each format, 10683the function returns a string or a number with the characters read, 10684or <b>fail</b> if it cannot read data with the specified format. 10685(In this latter case, 10686the function does not read subsequent formats.) 10687When called without arguments, 10688it uses a default format that reads the next line 10689(see below). 10690 10691 10692<p> 10693The available formats are 10694 10695<ul> 10696 10697<li><b>"<code>n</code>": </b> 10698reads a numeral and returns it as a float or an integer, 10699following the lexical conventions of Lua. 10700(The numeral may have leading whitespaces and a sign.) 10701This format always reads the longest input sequence that 10702is a valid prefix for a numeral; 10703if that prefix does not form a valid numeral 10704(e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>") 10705or it is too long (more than 200 characters), 10706it is discarded and the format returns <b>fail</b>. 10707</li> 10708 10709<li><b>"<code>a</code>": </b> 10710reads the whole file, starting at the current position. 10711On end of file, it returns the empty string; 10712this format never fails. 10713</li> 10714 10715<li><b>"<code>l</code>": </b> 10716reads the next line skipping the end of line, 10717returning <b>fail</b> on end of file. 10718This is the default format. 10719</li> 10720 10721<li><b>"<code>L</code>": </b> 10722reads the next line keeping the end-of-line character (if present), 10723returning <b>fail</b> on end of file. 10724</li> 10725 10726<li><b><em>number</em>: </b> 10727reads a string with up to this number of bytes, 10728returning <b>fail</b> on end of file. 10729If <code>number</code> is zero, 10730it reads nothing and returns an empty string, 10731or <b>fail</b> on end of file. 10732</li> 10733 10734</ul><p> 10735The formats "<code>l</code>" and "<code>L</code>" should be used only for text files. 10736 10737 10738 10739 10740<p> 10741<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3> 10742 10743 10744<p> 10745Sets and gets the file position, 10746measured from the beginning of the file, 10747to the position given by <code>offset</code> plus a base 10748specified by the string <code>whence</code>, as follows: 10749 10750<ul> 10751<li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li> 10752<li><b>"<code>cur</code>": </b> base is current position;</li> 10753<li><b>"<code>end</code>": </b> base is end of file;</li> 10754</ul><p> 10755In case of success, <code>seek</code> returns the final file position, 10756measured in bytes from the beginning of the file. 10757If <code>seek</code> fails, it returns <b>fail</b>, 10758plus a string describing the error. 10759 10760 10761<p> 10762The default value for <code>whence</code> is <code>"cur"</code>, 10763and for <code>offset</code> is 0. 10764Therefore, the call <code>file:seek()</code> returns the current 10765file position, without changing it; 10766the call <code>file:seek("set")</code> sets the position to the 10767beginning of the file (and returns 0); 10768and the call <code>file:seek("end")</code> sets the position to the 10769end of the file, and returns its size. 10770 10771 10772 10773 10774<p> 10775<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> 10776 10777 10778<p> 10779Sets the buffering mode for a file. 10780There are three available modes: 10781 10782<ul> 10783<li><b>"<code>no</code>": </b> no buffering.</li> 10784<li><b>"<code>full</code>": </b> full buffering.</li> 10785<li><b>"<code>line</code>": </b> line buffering.</li> 10786</ul> 10787 10788<p> 10789For the last two cases, 10790<code>size</code> is a hint for the size of the buffer, in bytes. 10791The default is an appropriate size. 10792 10793 10794<p> 10795The specific behavior of each mode is non portable; 10796check the underlying ISO C function <code>setvbuf</code> in your platform for 10797more details. 10798 10799 10800 10801 10802<p> 10803<hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> 10804 10805 10806<p> 10807Writes the value of each of its arguments to <code>file</code>. 10808The arguments must be strings or numbers. 10809 10810 10811<p> 10812In case of success, this function returns <code>file</code>. 10813 10814 10815 10816 10817 10818 10819 10820<h2>6.9 – <a name="6.9">Operating System Facilities</a></h2> 10821 10822<p> 10823This library is implemented through table <a name="pdf-os"><code>os</code></a>. 10824 10825 10826<p> 10827<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> 10828 10829 10830<p> 10831Returns an approximation of the amount in seconds of CPU time 10832used by the program, 10833as returned by the underlying ISO C function <code>clock</code>. 10834 10835 10836 10837 10838<p> 10839<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> 10840 10841 10842<p> 10843Returns a string or a table containing date and time, 10844formatted according to the given string <code>format</code>. 10845 10846 10847<p> 10848If the <code>time</code> argument is present, 10849this is the time to be formatted 10850(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). 10851Otherwise, <code>date</code> formats the current time. 10852 10853 10854<p> 10855If <code>format</code> starts with '<code>!</code>', 10856then the date is formatted in Coordinated Universal Time. 10857After this optional character, 10858if <code>format</code> is the string "<code>*t</code>", 10859then <code>date</code> returns a table with the following fields: 10860<code>year</code>, <code>month</code> (1–12), <code>day</code> (1–31), 10861<code>hour</code> (0–23), <code>min</code> (0–59), 10862<code>sec</code> (0–61, due to leap seconds), 10863<code>wday</code> (weekday, 1–7, Sunday is 1), 10864<code>yday</code> (day of the year, 1–366), 10865and <code>isdst</code> (daylight saving flag, a boolean). 10866This last field may be absent 10867if the information is not available. 10868 10869 10870<p> 10871If <code>format</code> is not "<code>*t</code>", 10872then <code>date</code> returns the date as a string, 10873formatted according to the same rules as the ISO C function <code>strftime</code>. 10874 10875 10876<p> 10877If <code>format</code> is absent, it defaults to "<code>%c</code>", 10878which gives a human-readable date and time representation 10879using the current locale. 10880 10881 10882<p> 10883On non-POSIX systems, 10884this function may be not thread safe 10885because of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>. 10886 10887 10888 10889 10890<p> 10891<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> 10892 10893 10894<p> 10895Returns the difference, in seconds, 10896from time <code>t1</code> to time <code>t2</code> 10897(where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>). 10898In POSIX, Windows, and some other systems, 10899this value is exactly <code>t2</code><em>-</em><code>t1</code>. 10900 10901 10902 10903 10904<p> 10905<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> 10906 10907 10908<p> 10909This function is equivalent to the ISO C function <code>system</code>. 10910It passes <code>command</code> to be executed by an operating system shell. 10911Its first result is <b>true</b> 10912if the command terminated successfully, 10913or <b>fail</b> otherwise. 10914After this first result 10915the function returns a string plus a number, 10916as follows: 10917 10918<ul> 10919 10920<li><b>"<code>exit</code>": </b> 10921the command terminated normally; 10922the following number is the exit status of the command. 10923</li> 10924 10925<li><b>"<code>signal</code>": </b> 10926the command was terminated by a signal; 10927the following number is the signal that terminated the command. 10928</li> 10929 10930</ul> 10931 10932<p> 10933When called without a <code>command</code>, 10934<code>os.execute</code> returns a boolean that is true if a shell is available. 10935 10936 10937 10938 10939<p> 10940<hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3> 10941 10942 10943<p> 10944Calls the ISO C function <code>exit</code> to terminate the host program. 10945If <code>code</code> is <b>true</b>, 10946the returned status is <code>EXIT_SUCCESS</code>; 10947if <code>code</code> is <b>false</b>, 10948the returned status is <code>EXIT_FAILURE</code>; 10949if <code>code</code> is a number, 10950the returned status is this number. 10951The default value for <code>code</code> is <b>true</b>. 10952 10953 10954<p> 10955If the optional second argument <code>close</code> is true, 10956closes the Lua state before exiting. 10957 10958 10959 10960 10961<p> 10962<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> 10963 10964 10965<p> 10966Returns the value of the process environment variable <code>varname</code> 10967or <b>fail</b> if the variable is not defined. 10968 10969 10970 10971 10972<p> 10973<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> 10974 10975 10976<p> 10977Deletes the file (or empty directory, on POSIX systems) 10978with the given name. 10979If this function fails, it returns <b>fail</b> 10980plus a string describing the error and the error code. 10981Otherwise, it returns true. 10982 10983 10984 10985 10986<p> 10987<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> 10988 10989 10990<p> 10991Renames the file or directory named <code>oldname</code> to <code>newname</code>. 10992If this function fails, it returns <b>fail</b>, 10993plus a string describing the error and the error code. 10994Otherwise, it returns true. 10995 10996 10997 10998 10999<p> 11000<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> 11001 11002 11003<p> 11004Sets the current locale of the program. 11005<code>locale</code> is a system-dependent string specifying a locale; 11006<code>category</code> is an optional string describing which category to change: 11007<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, 11008<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; 11009the default category is <code>"all"</code>. 11010The function returns the name of the new locale, 11011or <b>fail</b> if the request cannot be honored. 11012 11013 11014<p> 11015If <code>locale</code> is the empty string, 11016the current locale is set to an implementation-defined native locale. 11017If <code>locale</code> is the string "<code>C</code>", 11018the current locale is set to the standard C locale. 11019 11020 11021<p> 11022When called with <b>nil</b> as the first argument, 11023this function only returns the name of the current locale 11024for the given category. 11025 11026 11027<p> 11028This function may be not thread safe 11029because of its reliance on C function <code>setlocale</code>. 11030 11031 11032 11033 11034<p> 11035<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> 11036 11037 11038<p> 11039Returns the current time when called without arguments, 11040or a time representing the local date and time specified by the given table. 11041This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, 11042and may have fields 11043<code>hour</code> (default is 12), 11044<code>min</code> (default is 0), 11045<code>sec</code> (default is 0), 11046and <code>isdst</code> (default is <b>nil</b>). 11047Other fields are ignored. 11048For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function. 11049 11050 11051<p> 11052When the function is called, 11053the values in these fields do not need to be inside their valid ranges. 11054For instance, if <code>sec</code> is -10, 11055it means 10 seconds before the time specified by the other fields; 11056if <code>hour</code> is 1000, 11057it means 1000 hours after the time specified by the other fields. 11058 11059 11060<p> 11061The returned value is a number, whose meaning depends on your system. 11062In POSIX, Windows, and some other systems, 11063this number counts the number 11064of seconds since some given start time (the "epoch"). 11065In other systems, the meaning is not specified, 11066and the number returned by <code>time</code> can be used only as an argument to 11067<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. 11068 11069 11070<p> 11071When called with a table, 11072<code>os.time</code> also normalizes all the fields 11073documented in the <a href="#pdf-os.date"><code>os.date</code></a> function, 11074so that they represent the same time as before the call 11075but with values inside their valid ranges. 11076 11077 11078 11079 11080<p> 11081<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> 11082 11083 11084<p> 11085Returns a string with a file name that can 11086be used for a temporary file. 11087The file must be explicitly opened before its use 11088and explicitly removed when no longer needed. 11089 11090 11091<p> 11092In POSIX systems, 11093this function also creates a file with that name, 11094to avoid security risks. 11095(Someone else might create the file with wrong permissions 11096in the time between getting the name and creating the file.) 11097You still have to open the file to use it 11098and to remove it (even if you do not use it). 11099 11100 11101<p> 11102When possible, 11103you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, 11104which automatically removes the file when the program ends. 11105 11106 11107 11108 11109 11110 11111 11112<h2>6.10 – <a name="6.10">The Debug Library</a></h2> 11113 11114<p> 11115This library provides 11116the functionality of the debug interface (<a href="#4.7">§4.7</a>) to Lua programs. 11117You should exert care when using this library. 11118Several of its functions 11119violate basic assumptions about Lua code 11120(e.g., that variables local to a function 11121cannot be accessed from outside; 11122that userdata metatables cannot be changed by Lua code; 11123that Lua programs do not crash) 11124and therefore can compromise otherwise secure code. 11125Moreover, some functions in this library may be slow. 11126 11127 11128<p> 11129All functions in this library are provided 11130inside the <a name="pdf-debug"><code>debug</code></a> table. 11131All functions that operate over a thread 11132have an optional first argument which is the 11133thread to operate over. 11134The default is always the current thread. 11135 11136 11137<p> 11138<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> 11139 11140 11141<p> 11142Enters an interactive mode with the user, 11143running each string that the user enters. 11144Using simple commands and other debug facilities, 11145the user can inspect global and local variables, 11146change their values, evaluate expressions, and so on. 11147A line containing only the word <code>cont</code> finishes this function, 11148so that the caller continues its execution. 11149 11150 11151<p> 11152Note that commands for <code>debug.debug</code> are not lexically nested 11153within any function and so have no direct access to local variables. 11154 11155 11156 11157 11158<p> 11159<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> 11160 11161 11162<p> 11163Returns the current hook settings of the thread, as three values: 11164the current hook function, the current hook mask, 11165and the current hook count, 11166as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function. 11167 11168 11169<p> 11170Returns <b>fail</b> if there is no active hook. 11171 11172 11173 11174 11175<p> 11176<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> 11177 11178 11179<p> 11180Returns a table with information about a function. 11181You can give the function directly 11182or you can give a number as the value of <code>f</code>, 11183which means the function running at level <code>f</code> of the call stack 11184of the given thread: 11185level 0 is the current function (<code>getinfo</code> itself); 11186level 1 is the function that called <code>getinfo</code> 11187(except for tail calls, which do not count in the stack); 11188and so on. 11189If <code>f</code> is a number greater than the number of active functions, 11190then <code>getinfo</code> returns <b>fail</b>. 11191 11192 11193<p> 11194The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, 11195with the string <code>what</code> describing which fields to fill in. 11196The default for <code>what</code> is to get all information available, 11197except the table of valid lines. 11198If present, 11199the option '<code>f</code>' 11200adds a field named <code>func</code> with the function itself. 11201If present, 11202the option '<code>L</code>' 11203adds a field named <code>activelines</code> with the table of 11204valid lines. 11205 11206 11207<p> 11208For instance, the expression <code>debug.getinfo(1,"n").name</code> returns 11209a name for the current function, 11210if a reasonable name can be found, 11211and the expression <code>debug.getinfo(print)</code> 11212returns a table with all available information 11213about the <a href="#pdf-print"><code>print</code></a> function. 11214 11215 11216 11217 11218<p> 11219<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3> 11220 11221 11222<p> 11223This function returns the name and the value of the local variable 11224with index <code>local</code> of the function at level <code>f</code> of the stack. 11225This function accesses not only explicit local variables, 11226but also parameters and temporary values. 11227 11228 11229<p> 11230The first parameter or local variable has index 1, and so on, 11231following the order that they are declared in the code, 11232counting only the variables that are active 11233in the current scope of the function. 11234Compile-time constants may not appear in this listing, 11235if they were optimized away by the compiler. 11236Negative indices refer to vararg arguments; 11237-1 is the first vararg argument. 11238The function returns <b>fail</b> 11239if there is no variable with the given index, 11240and raises an error when called with a level out of range. 11241(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) 11242 11243 11244<p> 11245Variable names starting with '<code>(</code>' (open parenthesis) 11246represent variables with no known names 11247(internal variables such as loop control variables, 11248and variables from chunks saved without debug information). 11249 11250 11251<p> 11252The parameter <code>f</code> may also be a function. 11253In that case, <code>getlocal</code> returns only the name of function parameters. 11254 11255 11256 11257 11258<p> 11259<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3> 11260 11261 11262<p> 11263Returns the metatable of the given <code>value</code> 11264or <b>nil</b> if it does not have a metatable. 11265 11266 11267 11268 11269<p> 11270<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> 11271 11272 11273<p> 11274Returns the registry table (see <a href="#4.3">§4.3</a>). 11275 11276 11277 11278 11279<p> 11280<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3> 11281 11282 11283<p> 11284This function returns the name and the value of the upvalue 11285with index <code>up</code> of the function <code>f</code>. 11286The function returns <b>fail</b> 11287if there is no upvalue with the given index. 11288 11289 11290<p> 11291(For Lua functions, 11292upvalues are the external local variables that the function uses, 11293and that are consequently included in its closure.) 11294 11295 11296<p> 11297For C functions, this function uses the empty string <code>""</code> 11298as a name for all upvalues. 11299 11300 11301<p> 11302Variable name '<code>?</code>' (interrogation mark) 11303represents variables with no known names 11304(variables from chunks saved without debug information). 11305 11306 11307 11308 11309<p> 11310<hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u, n)</code></a></h3> 11311 11312 11313<p> 11314Returns the <code>n</code>-th user value associated 11315to the userdata <code>u</code> plus a boolean, 11316<b>false</b> if the userdata does not have that value. 11317 11318 11319 11320 11321<p> 11322<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> 11323 11324 11325<p> 11326Sets the given function as the debug hook. 11327The string <code>mask</code> and the number <code>count</code> describe 11328when the hook will be called. 11329The string mask may have any combination of the following characters, 11330with the given meaning: 11331 11332<ul> 11333<li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li> 11334<li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li> 11335<li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li> 11336</ul><p> 11337Moreover, 11338with a <code>count</code> different from zero, 11339the hook is called also after every <code>count</code> instructions. 11340 11341 11342<p> 11343When called without arguments, 11344<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. 11345 11346 11347<p> 11348When the hook is called, its first parameter is a string 11349describing the event that has triggered its call: 11350<code>"call"</code>, <code>"tail call"</code>, <code>"return"</code>, 11351<code>"line"</code>, and <code>"count"</code>. 11352For line events, 11353the hook also gets the new line number as its second parameter. 11354Inside a hook, 11355you can call <code>getinfo</code> with level 2 to get more information about 11356the running function. 11357(Level 0 is the <code>getinfo</code> function, 11358and level 1 is the hook function.) 11359 11360 11361 11362 11363<p> 11364<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> 11365 11366 11367<p> 11368This function assigns the value <code>value</code> to the local variable 11369with index <code>local</code> of the function at level <code>level</code> of the stack. 11370The function returns <b>fail</b> if there is no local 11371variable with the given index, 11372and raises an error when called with a <code>level</code> out of range. 11373(You can call <code>getinfo</code> to check whether the level is valid.) 11374Otherwise, it returns the name of the local variable. 11375 11376 11377<p> 11378See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about 11379variable indices and names. 11380 11381 11382 11383 11384<p> 11385<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> 11386 11387 11388<p> 11389Sets the metatable for the given <code>value</code> to the given <code>table</code> 11390(which can be <b>nil</b>). 11391Returns <code>value</code>. 11392 11393 11394 11395 11396<p> 11397<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> 11398 11399 11400<p> 11401This function assigns the value <code>value</code> to the upvalue 11402with index <code>up</code> of the function <code>f</code>. 11403The function returns <b>fail</b> if there is no upvalue 11404with the given index. 11405Otherwise, it returns the name of the upvalue. 11406 11407 11408<p> 11409See <a href="#pdf-debug.getupvalue"><code>debug.getupvalue</code></a> for more information about upvalues. 11410 11411 11412 11413 11414<p> 11415<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value, n)</code></a></h3> 11416 11417 11418<p> 11419Sets the given <code>value</code> as 11420the <code>n</code>-th user value associated to the given <code>udata</code>. 11421<code>udata</code> must be a full userdata. 11422 11423 11424<p> 11425Returns <code>udata</code>, 11426or <b>fail</b> if the userdata does not have that value. 11427 11428 11429 11430 11431<p> 11432<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> 11433 11434 11435<p> 11436If <code>message</code> is present but is neither a string nor <b>nil</b>, 11437this function returns <code>message</code> without further processing. 11438Otherwise, 11439it returns a string with a traceback of the call stack. 11440The optional <code>message</code> string is appended 11441at the beginning of the traceback. 11442An optional <code>level</code> number tells at which level 11443to start the traceback 11444(default is 1, the function calling <code>traceback</code>). 11445 11446 11447 11448 11449<p> 11450<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3> 11451 11452 11453<p> 11454Returns a unique identifier (as a light userdata) 11455for the upvalue numbered <code>n</code> 11456from the given function. 11457 11458 11459<p> 11460These unique identifiers allow a program to check whether different 11461closures share upvalues. 11462Lua closures that share an upvalue 11463(that is, that access a same external local variable) 11464will return identical ids for those upvalue indices. 11465 11466 11467 11468 11469<p> 11470<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3> 11471 11472 11473<p> 11474Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code> 11475refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>. 11476 11477 11478 11479 11480 11481 11482 11483<h1>7 – <a name="7">Lua Standalone</a></h1> 11484 11485<p> 11486Although Lua has been designed as an extension language, 11487to be embedded in a host C program, 11488it is also frequently used as a standalone language. 11489An interpreter for Lua as a standalone language, 11490called simply <code>lua</code>, 11491is provided with the standard distribution. 11492The standalone interpreter includes 11493all standard libraries. 11494Its usage is: 11495 11496<pre> 11497 lua [options] [script [args]] 11498</pre><p> 11499The options are: 11500 11501<ul> 11502<li><b><code>-e <em>stat</em></code>: </b> execute string <em>stat</em>;</li> 11503<li><b><code>-i</code>: </b> enter interactive mode after running <em>script</em>;</li> 11504<li><b><code>-l <em>mod</em></code>: </b> "require" <em>mod</em> and assign the 11505 result to global <em>mod</em>;</li> 11506<li><b><code>-v</code>: </b> print version information;</li> 11507<li><b><code>-E</code>: </b> ignore environment variables;</li> 11508<li><b><code>-W</code>: </b> turn warnings on;</li> 11509<li><b><code>--</code>: </b> stop handling options;</li> 11510<li><b><code>-</code>: </b> execute <code>stdin</code> as a file and stop handling options.</li> 11511</ul><p> 11512After handling its options, <code>lua</code> runs the given <em>script</em>. 11513When called without arguments, 11514<code>lua</code> behaves as <code>lua -v -i</code> 11515when the standard input (<code>stdin</code>) is a terminal, 11516and as <code>lua -</code> otherwise. 11517 11518 11519<p> 11520When called without the option <code>-E</code>, 11521the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_4"><code>LUA_INIT_5_4</code></a> 11522(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined) 11523before running any argument. 11524If the variable content has the format <code>@<em>filename</em></code>, 11525then <code>lua</code> executes the file. 11526Otherwise, <code>lua</code> executes the string itself. 11527 11528 11529<p> 11530When called with the option <code>-E</code>, 11531Lua does not consult any environment variables. 11532In particular, 11533the values of <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a> 11534are set with the default paths defined in <code>luaconf.h</code>. 11535 11536 11537<p> 11538The options <code>-e</code>, <code>-l</code>, and <code>-W</code> are handled in 11539the order they appear. 11540For instance, an invocation like 11541 11542<pre> 11543 $ lua -e 'a=1' -llib1 script.lua 11544</pre><p> 11545will first set <code>a</code> to 1, then require the library <code>lib1</code>, 11546and finally run the file <code>script.lua</code> with no arguments. 11547(Here <code>$</code> is the shell prompt. Your prompt may be different.) 11548 11549 11550<p> 11551Before running any code, 11552<code>lua</code> collects all command-line arguments 11553in a global table called <code>arg</code>. 11554The script name goes to index 0, 11555the first argument after the script name goes to index 1, 11556and so on. 11557Any arguments before the script name 11558(that is, the interpreter name plus its options) 11559go to negative indices. 11560For instance, in the call 11561 11562<pre> 11563 $ lua -la b.lua t1 t2 11564</pre><p> 11565the table is like this: 11566 11567<pre> 11568 arg = { [-2] = "lua", [-1] = "-la", 11569 [0] = "b.lua", 11570 [1] = "t1", [2] = "t2" } 11571</pre><p> 11572If there is no script in the call, 11573the interpreter name goes to index 0, 11574followed by the other arguments. 11575For instance, the call 11576 11577<pre> 11578 $ lua -e "print(arg[1])" 11579</pre><p> 11580will print "<code>-e</code>". 11581If there is a script, 11582the script is called with arguments 11583<code>arg[1]</code>, ···, <code>arg[#arg]</code>. 11584Like all chunks in Lua, 11585the script is compiled as a vararg function. 11586 11587 11588<p> 11589In interactive mode, 11590Lua repeatedly prompts and waits for a line. 11591After reading a line, 11592Lua first try to interpret the line as an expression. 11593If it succeeds, it prints its value. 11594Otherwise, it interprets the line as a statement. 11595If you write an incomplete statement, 11596the interpreter waits for its completion 11597by issuing a different prompt. 11598 11599 11600<p> 11601If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, 11602then its value is used as the prompt. 11603Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, 11604its value is used as the secondary prompt 11605(issued during incomplete statements). 11606 11607 11608<p> 11609In case of unprotected errors in the script, 11610the interpreter reports the error to the standard error stream. 11611If the error object is not a string but 11612has a metamethod <code>__tostring</code>, 11613the interpreter calls this metamethod to produce the final message. 11614Otherwise, the interpreter converts the error object to a string 11615and adds a stack traceback to it. 11616When warnings are on, 11617they are simply printed in the standard error output. 11618 11619 11620<p> 11621When finishing normally, 11622the interpreter closes its main Lua state 11623(see <a href="#lua_close"><code>lua_close</code></a>). 11624The script can avoid this step by 11625calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate. 11626 11627 11628<p> 11629To allow the use of Lua as a 11630script interpreter in Unix systems, 11631Lua skips the first line of a file chunk if it starts with <code>#</code>. 11632Therefore, Lua scripts can be made into executable programs 11633by using <code>chmod +x</code> and the <code>#!</code> form, 11634as in 11635 11636<pre> 11637 #!/usr/local/bin/lua 11638</pre><p> 11639Of course, 11640the location of the Lua interpreter may be different in your machine. 11641If <code>lua</code> is in your <code>PATH</code>, 11642then 11643 11644<pre> 11645 #!/usr/bin/env lua 11646</pre><p> 11647is a more portable solution. 11648 11649 11650 11651<h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> 11652 11653 11654 11655<p> 11656Here we list the incompatibilities that you may find when moving a program 11657from Lua 5.3 to Lua 5.4. 11658 11659 11660<p> 11661You can avoid some incompatibilities by compiling Lua with 11662appropriate options (see file <code>luaconf.h</code>). 11663However, 11664all these compatibility options will be removed in the future. 11665More often than not, 11666compatibility issues arise when these compatibility options 11667are removed. 11668So, whenever you have the chance, 11669you should try to test your code with a version of Lua compiled 11670with all compatibility options turned off. 11671That will ease transitions to newer versions of Lua. 11672 11673 11674<p> 11675Lua versions can always change the C API in ways that 11676do not imply source-code changes in a program, 11677such as the numeric values for constants 11678or the implementation of functions as macros. 11679Therefore, 11680you should never assume that binaries are compatible between 11681different Lua versions. 11682Always recompile clients of the Lua API when 11683using a new version. 11684 11685 11686<p> 11687Similarly, Lua versions can always change the internal representation 11688of precompiled chunks; 11689precompiled chunks are not compatible between different Lua versions. 11690 11691 11692<p> 11693The standard paths in the official distribution may 11694change between versions. 11695 11696 11697 11698 11699 11700<h2>8.1 – <a name="8.1">Incompatibilities in the Language</a></h2> 11701<ul> 11702 11703<li> 11704The coercion of strings to numbers in 11705arithmetic and bitwise operations 11706has been removed from the core language. 11707The string library does a similar job 11708for arithmetic (but not for bitwise) operations 11709using the string metamethods. 11710However, unlike in previous versions, 11711the new implementation preserves the implicit type of the numeral 11712in the string. 11713For instance, the result of <code>"1" + "2"</code> now is an integer, 11714not a float. 11715</li> 11716 11717<li> 11718Literal decimal integer constants that overflow are read as floats, 11719instead of wrapping around. 11720You can use hexadecimal notation for such constants if you 11721want the old behavior 11722(reading them as integers with wrap around). 11723</li> 11724 11725<li> 11726The use of the <code>__lt</code> metamethod to emulate <code>__le</code> 11727has been removed. 11728When needed, this metamethod must be explicitly defined. 11729</li> 11730 11731<li> 11732The semantics of the numerical <b>for</b> loop 11733over integers changed in some details. 11734In particular, the control variable never wraps around. 11735</li> 11736 11737<li> 11738A label for a <b>goto</b> cannot be declared where a label with the same 11739name is visible, even if this other label is declared in an enclosing 11740block. 11741</li> 11742 11743<li> 11744When finalizing an object, 11745Lua does not ignore <code>__gc</code> metamethods that are not functions. 11746Any value will be called, if present. 11747(Non-callable values will generate a warning, 11748like any other error when calling a finalizer.) 11749</li> 11750 11751</ul> 11752 11753 11754 11755 11756<h2>8.2 – <a name="8.2">Incompatibilities in the Libraries</a></h2> 11757<ul> 11758 11759<li> 11760The function <a href="#pdf-print"><code>print</code></a> does not call <a href="#pdf-tostring"><code>tostring</code></a> 11761to format its arguments; 11762instead, it has this functionality hardwired. 11763You should use <code>__tostring</code> to modify how values are printed. 11764</li> 11765 11766<li> 11767The pseudo-random number generator used by the function <a href="#pdf-math.random"><code>math.random</code></a> 11768now starts with a somewhat random seed. 11769Moreover, it uses a different algorithm. 11770</li> 11771 11772<li> 11773By default, the decoding functions in the <a href="#pdf-utf8"><code>utf8</code></a> library 11774do not accept surrogates as valid code points. 11775An extra parameter in these functions makes them more permissive. 11776</li> 11777 11778<li> 11779The options "<code>setpause</code>" and "<code>setstepmul</code>" 11780of the function <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> are deprecated. 11781You should use the new option "<code>incremental</code>" to set them. 11782</li> 11783 11784<li> 11785The function <a href="#pdf-io.lines"><code>io.lines</code></a> now returns four values, 11786instead of just one. 11787That can be a problem when it is used as the sole 11788argument to another function that has optional parameters, 11789such as in <code>load(io.lines(filename, "L"))</code>. 11790To fix that issue, 11791you can wrap the call into parentheses, 11792to adjust its number of results to one. 11793</li> 11794 11795</ul> 11796 11797 11798 11799 11800<h2>8.3 – <a name="8.3">Incompatibilities in the API</a></h2> 11801 11802 11803<ul> 11804 11805<li> 11806Full userdata now has an arbitrary number of associated user values. 11807Therefore, the functions <code>lua_newuserdata</code>, 11808<code>lua_setuservalue</code>, and <code>lua_getuservalue</code> were 11809replaced by <a href="#lua_newuserdatauv"><code>lua_newuserdatauv</code></a>, 11810<a href="#lua_setiuservalue"><code>lua_setiuservalue</code></a>, and <a href="#lua_getiuservalue"><code>lua_getiuservalue</code></a>, 11811which have an extra argument. 11812 11813 11814<p> 11815For compatibility, the old names still work as macros assuming 11816one single user value. 11817Note, however, that userdata with zero user values 11818are more efficient memory-wise. 11819</li> 11820 11821<li> 11822The function <a href="#lua_resume"><code>lua_resume</code></a> has an extra parameter. 11823This out parameter returns the number of values on 11824the top of the stack that were yielded or returned by the coroutine. 11825(In previous versions, 11826those values were the entire stack.) 11827</li> 11828 11829<li> 11830The function <a href="#lua_version"><code>lua_version</code></a> returns the version number, 11831instead of an address of the version number. 11832The Lua core should work correctly with libraries using their 11833own static copies of the same core, 11834so there is no need to check whether they are using the same 11835address space. 11836</li> 11837 11838<li> 11839The constant <code>LUA_ERRGCMM</code> was removed. 11840Errors in finalizers are never propagated; 11841instead, they generate a warning. 11842</li> 11843 11844<li> 11845The options <code>LUA_GCSETPAUSE</code> and <code>LUA_GCSETSTEPMUL</code> 11846of the function <a href="#lua_gc"><code>lua_gc</code></a> are deprecated. 11847You should use the new option <code>LUA_GCINC</code> to set them. 11848</li> 11849 11850</ul> 11851 11852 11853 11854 11855<h1>9 – <a name="9">The Complete Syntax of Lua</a></h1> 11856 11857<p> 11858Here is the complete syntax of Lua in extended BNF. 11859As usual in extended BNF, 11860{A} means 0 or more As, 11861and [A] means an optional A. 11862(For operator precedences, see <a href="#3.4.8">§3.4.8</a>; 11863for a description of the terminals 11864Name, Numeral, 11865and LiteralString, see <a href="#3.1">§3.1</a>.) 11866 11867 11868 11869 11870<pre> 11871 11872 chunk ::= block 11873 11874 block ::= {stat} [retstat] 11875 11876 stat ::= ‘<b>;</b>’ | 11877 varlist ‘<b>=</b>’ explist | 11878 functioncall | 11879 label | 11880 <b>break</b> | 11881 <b>goto</b> Name | 11882 <b>do</b> block <b>end</b> | 11883 <b>while</b> exp <b>do</b> block <b>end</b> | 11884 <b>repeat</b> block <b>until</b> exp | 11885 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 11886 <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> | 11887 <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 11888 <b>function</b> funcname funcbody | 11889 <b>local</b> <b>function</b> Name funcbody | 11890 <b>local</b> attnamelist [‘<b>=</b>’ explist] 11891 11892 attnamelist ::= Name attrib {‘<b>,</b>’ Name attrib} 11893 11894 attrib ::= [‘<b><</b>’ Name ‘<b>></b>’] 11895 11896 retstat ::= <b>return</b> [explist] [‘<b>;</b>’] 11897 11898 label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 11899 11900 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 11901 11902 varlist ::= var {‘<b>,</b>’ var} 11903 11904 var ::= Name | prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | prefixexp ‘<b>.</b>’ Name 11905 11906 namelist ::= Name {‘<b>,</b>’ Name} 11907 11908 explist ::= exp {‘<b>,</b>’ exp} 11909 11910 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | ‘<b>...</b>’ | functiondef | 11911 prefixexp | tableconstructor | exp binop exp | unop exp 11912 11913 prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 11914 11915 functioncall ::= prefixexp args | prefixexp ‘<b>:</b>’ Name args 11916 11917 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | tableconstructor | LiteralString 11918 11919 functiondef ::= <b>function</b> funcbody 11920 11921 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 11922 11923 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 11924 11925 tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 11926 11927 fieldlist ::= field {fieldsep field} [fieldsep] 11928 11929 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 11930 11931 fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 11932 11933 binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</b>’ | ‘<b>//</b>’ | ‘<b>^</b>’ | ‘<b>%</b>’ | 11934 ‘<b>&</b>’ | ‘<b>~</b>’ | ‘<b>|</b>’ | ‘<b>>></b>’ | ‘<b><<</b>’ | ‘<b>..</b>’ | 11935 ‘<b><</b>’ | ‘<b><=</b>’ | ‘<b>></b>’ | ‘<b>>=</b>’ | ‘<b>==</b>’ | ‘<b>~=</b>’ | 11936 <b>and</b> | <b>or</b> 11937 11938 unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’ | ‘<b>~</b>’ 11939 11940</pre> 11941 11942<p> 11943 11944 11945 11946 11947 11948 11949 11950<P CLASS="footer"> 11951Last update: 11952Thu Jan 13 11:33:16 UTC 2022 11953</P> 11954<!-- 11955Last change: revised for Lua 5.4.4 11956--> 11957 11958</body></html> 11959 11960
