1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<TITLE>Lua 5.3 Reference Manual</TITLE> 5<LINK REL="stylesheet" TYPE="text/css" HREF="lua.css"> 6<LINK REL="stylesheet" TYPE="text/css" HREF="manual.css"> 7<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> 8</HEAD> 9 10<BODY> 11 12<H1> 13<A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A> 14Lua 5.3 Reference Manual 15</H1> 16 17<P> 18by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes 19 20<P> 21<SMALL> 22Copyright © 2015–2016 Lua.org, PUC-Rio. 23Freely available under the terms of the 24<a href="http://www.lua.org/license.html">Lua license</a>. 25</SMALL> 26 27<DIV CLASS="menubar"> 28<A HREF="contents.html#contents">contents</A> 29· 30<A HREF="contents.html#index">index</A> 31· 32<A HREF="http://www.lua.org/manual/">other versions</A> 33</DIV> 34 35<!-- ====================================================================== --> 36<p> 37 38<!-- Id: manual.of,v 1.162 2016/05/30 15:57:03 roberto Exp --> 39 40 41 42 43<h1>1 – <a name="1">Introduction</a></h1> 44 45<p> 46Lua is a powerful, efficient, lightweight, embeddable scripting language. 47It supports procedural programming, 48object-oriented programming, functional programming, 49data-driven programming, and data description. 50 51 52<p> 53Lua combines simple procedural syntax with powerful data description 54constructs based on associative arrays and extensible semantics. 55Lua is dynamically typed, 56runs by interpreting bytecode with a register-based 57virtual machine, 58and has automatic memory management with 59incremental garbage collection, 60making it ideal for configuration, scripting, 61and rapid prototyping. 62 63 64<p> 65Lua is implemented as a library, written in <em>clean C</em>, 66the common subset of Standard C and C++. 67The Lua distribution includes a host program called <code>lua</code>, 68which uses the Lua library to offer a complete, 69standalone Lua interpreter, 70for interactive or batch use. 71Lua is intended to be used both as a powerful, lightweight, 72embeddable scripting language for any program that needs one, 73and as a powerful but lightweight and efficient stand-alone language. 74 75 76<p> 77As an extension language, Lua has no notion of a "main" program: 78it works <em>embedded</em> in a host client, 79called the <em>embedding program</em> or simply the <em>host</em>. 80(Frequently, this host is the stand-alone <code>lua</code> program.) 81The host program can invoke functions to execute a piece of Lua code, 82can write and read Lua variables, 83and can register C functions to be called by Lua code. 84Through the use of C functions, Lua can be augmented to cope with 85a wide range of different domains, 86thus creating customized programming languages sharing a syntactical framework. 87 88 89<p> 90Lua is free software, 91and is provided as usual with no guarantees, 92as stated in its license. 93The implementation described in this manual is available 94at Lua's official web site, <code>www.lua.org</code>. 95 96 97<p> 98Like any other reference manual, 99this document is dry in places. 100For a discussion of the decisions behind the design of Lua, 101see the technical papers available at Lua's web site. 102For a detailed introduction to programming in Lua, 103see Roberto's book, <em>Programming in Lua</em>. 104 105 106 107<h1>2 – <a name="2">Basic Concepts</a></h1> 108 109<p> 110This section describes the basic concepts of the language. 111 112 113 114<h2>2.1 – <a name="2.1">Values and Types</a></h2> 115 116<p> 117Lua is a <em>dynamically typed language</em>. 118This means that 119variables do not have types; only values do. 120There are no type definitions in the language. 121All values carry their own type. 122 123 124<p> 125All values in Lua are <em>first-class values</em>. 126This means that all values can be stored in variables, 127passed as arguments to other functions, and returned as results. 128 129 130<p> 131There are eight basic types in Lua: 132<em>nil</em>, <em>boolean</em>, <em>number</em>, 133<em>string</em>, <em>function</em>, <em>userdata</em>, 134<em>thread</em>, and <em>table</em>. 135The type <em>nil</em> has one single value, <b>nil</b>, 136whose main property is to be different from any other value; 137it usually represents the absence of a useful value. 138The type <em>boolean</em> has two values, <b>false</b> and <b>true</b>. 139Both <b>nil</b> and <b>false</b> make a condition false; 140any other value makes it true. 141The type <em>number</em> represents both 142integer numbers and real (floating-point) numbers. 143The type <em>string</em> represents immutable sequences of bytes. 144 145Lua is 8-bit clean: 146strings can contain any 8-bit value, 147including embedded zeros ('<code>\0</code>'). 148Lua is also encoding-agnostic; 149it makes no assumptions about the contents of a string. 150 151 152<p> 153The type <em>number</em> uses two internal representations, 154or two subtypes, 155one called <em>integer</em> and the other called <em>float</em>. 156Lua has explicit rules about when each representation is used, 157but it also converts between them automatically as needed (see <a href="#3.4.3">§3.4.3</a>). 158Therefore, 159the programmer may choose to mostly ignore the difference 160between integers and floats 161or to assume complete control over the representation of each number. 162Standard Lua uses 64-bit integers and double-precision (64-bit) floats, 163but you can also compile Lua so that it 164uses 32-bit integers and/or single-precision (32-bit) floats. 165The option with 32 bits for both integers and floats 166is particularly attractive 167for small machines and embedded systems. 168(See macro <code>LUA_32BITS</code> in file <code>luaconf.h</code>.) 169 170 171<p> 172Lua can call (and manipulate) functions written in Lua and 173functions written in C (see <a href="#3.4.10">§3.4.10</a>). 174Both are represented by the type <em>function</em>. 175 176 177<p> 178The type <em>userdata</em> is provided to allow arbitrary C data to 179be stored in Lua variables. 180A userdata value represents a block of raw memory. 181There are two kinds of userdata: 182<em>full userdata</em>, 183which is an object with a block of memory managed by Lua, 184and <em>light userdata</em>, 185which is simply a C pointer value. 186Userdata has no predefined operations in Lua, 187except assignment and identity test. 188By using <em>metatables</em>, 189the programmer can define operations for full userdata values 190(see <a href="#2.4">§2.4</a>). 191Userdata values cannot be created or modified in Lua, 192only through the C API. 193This guarantees the integrity of data owned by the host program. 194 195 196<p> 197The type <em>thread</em> represents independent threads of execution 198and it is used to implement coroutines (see <a href="#2.6">§2.6</a>). 199Lua threads are not related to operating-system threads. 200Lua supports coroutines on all systems, 201even those that do not support threads natively. 202 203 204<p> 205The type <em>table</em> implements associative arrays, 206that is, arrays that can be indexed not only with numbers, 207but with any Lua value except <b>nil</b> and NaN. 208(<em>Not a Number</em> is a special value used to represent 209undefined or unrepresentable numerical results, such as <code>0/0</code>.) 210Tables can be <em>heterogeneous</em>; 211that is, they can contain values of all types (except <b>nil</b>). 212Any key with value <b>nil</b> is not considered part of the table. 213Conversely, any key that is not part of a table has 214an associated value <b>nil</b>. 215 216 217<p> 218Tables are the sole data-structuring mechanism in Lua; 219they can be used to represent ordinary arrays, sequences, 220symbol tables, sets, records, graphs, trees, etc. 221To represent records, Lua uses the field name as an index. 222The language supports this representation by 223providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. 224There are several convenient ways to create tables in Lua 225(see <a href="#3.4.9">§3.4.9</a>). 226 227 228<p> 229We use the term <em>sequence</em> to denote a table where 230the set of all positive numeric keys is equal to {1..<em>n</em>} 231for some non-negative integer <em>n</em>, 232which is called the length of the sequence (see <a href="#3.4.7">§3.4.7</a>). 233 234 235<p> 236Like indices, 237the values of table fields can be of any type. 238In particular, 239because functions are first-class values, 240table fields can contain functions. 241Thus tables can also carry <em>methods</em> (see <a href="#3.4.11">§3.4.11</a>). 242 243 244<p> 245The indexing of tables follows 246the definition of raw equality in the language. 247The expressions <code>a[i]</code> and <code>a[j]</code> 248denote the same table element 249if and only if <code>i</code> and <code>j</code> are raw equal 250(that is, equal without metamethods). 251In particular, floats with integral values 252are equal to their respective integers 253(e.g., <code>1.0 == 1</code>). 254To avoid ambiguities, 255any float with integral value used as a key 256is converted to its respective integer. 257For instance, if you write <code>a[2.0] = true</code>, 258the actual key inserted into the table will be the 259integer <code>2</code>. 260(On the other hand, 2612 and "<code>2</code>" are different Lua values and therefore 262denote different table entries.) 263 264 265<p> 266Tables, functions, threads, and (full) userdata values are <em>objects</em>: 267variables do not actually <em>contain</em> these values, 268only <em>references</em> to them. 269Assignment, parameter passing, and function returns 270always manipulate references to such values; 271these operations do not imply any kind of copy. 272 273 274<p> 275The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type 276of a given value (see <a href="#6.1">§6.1</a>). 277 278 279 280 281 282<h2>2.2 – <a name="2.2">Environments and the Global Environment</a></h2> 283 284<p> 285As will be discussed in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>, 286any reference to a free name 287(that is, a name not bound to any declaration) <code>var</code> 288is syntactically translated to <code>_ENV.var</code>. 289Moreover, every chunk is compiled in the scope of 290an external local variable named <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>), 291so <code>_ENV</code> itself is never a free name in a chunk. 292 293 294<p> 295Despite the existence of this external <code>_ENV</code> variable and 296the translation of free names, 297<code>_ENV</code> is a completely regular name. 298In particular, 299you can define new variables and parameters with that name. 300Each reference to a free name uses the <code>_ENV</code> that is 301visible at that point in the program, 302following the usual visibility rules of Lua (see <a href="#3.5">§3.5</a>). 303 304 305<p> 306Any table used as the value of <code>_ENV</code> is called an <em>environment</em>. 307 308 309<p> 310Lua keeps a distinguished environment called the <em>global environment</em>. 311This value is kept at a special index in the C registry (see <a href="#4.5">§4.5</a>). 312In Lua, the global variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value. 313(<a href="#pdf-_G"><code>_G</code></a> is never used internally.) 314 315 316<p> 317When Lua loads a chunk, 318the default value for its <code>_ENV</code> upvalue 319is the global environment (see <a href="#pdf-load"><code>load</code></a>). 320Therefore, by default, 321free names in Lua code refer to entries in the global environment 322(and, therefore, they are also called <em>global variables</em>). 323Moreover, all standard libraries are loaded in the global environment 324and some functions there operate on that environment. 325You can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>) 326to load a chunk with a different environment. 327(In C, you have to load the chunk and then change the value 328of its first upvalue.) 329 330 331 332 333 334<h2>2.3 – <a name="2.3">Error Handling</a></h2> 335 336<p> 337Because Lua is an embedded extension language, 338all Lua actions start from C code in the host program 339calling a function from the Lua library. 340(When you use Lua standalone, 341the <code>lua</code> application is the host program.) 342Whenever an error occurs during 343the compilation or execution of a Lua chunk, 344control returns to the host, 345which can take appropriate measures 346(such as printing an error message). 347 348 349<p> 350Lua code can explicitly generate an error by calling the 351<a href="#pdf-error"><code>error</code></a> function. 352If you need to catch errors in Lua, 353you can use <a href="#pdf-pcall"><code>pcall</code></a> or <a href="#pdf-xpcall"><code>xpcall</code></a> 354to call a given function in <em>protected mode</em>. 355 356 357<p> 358Whenever there is an error, 359an <em>error object</em> (also called an <em>error message</em>) 360is propagated with information about the error. 361Lua itself only generates errors whose error object is a string, 362but programs may generate errors with 363any value as the error object. 364It is up to the Lua program or its host to handle such error objects. 365 366 367<p> 368When you use <a href="#pdf-xpcall"><code>xpcall</code></a> or <a href="#lua_pcall"><code>lua_pcall</code></a>, 369you may give a <em>message handler</em> 370to be called in case of errors. 371This function is called with the original error object 372and returns a new error object. 373It is called before the error unwinds the stack, 374so that it can gather more information about the error, 375for instance by inspecting the stack and creating a stack traceback. 376This message handler is still protected by the protected call; 377so, an error inside the message handler 378will call the message handler again. 379If this loop goes on for too long, 380Lua breaks it and returns an appropriate message. 381 382 383 384 385 386<h2>2.4 – <a name="2.4">Metatables and Metamethods</a></h2> 387 388<p> 389Every value in Lua can have a <em>metatable</em>. 390This <em>metatable</em> is an ordinary Lua table 391that defines the behavior of the original value 392under certain special operations. 393You can change several aspects of the behavior 394of operations over a value by setting specific fields in its metatable. 395For instance, when a non-numeric value is the operand of an addition, 396Lua checks for a function in the field "<code>__add</code>" of the value's metatable. 397If it finds one, 398Lua calls this function to perform the addition. 399 400 401<p> 402The key for each event in a metatable is a string 403with the event name prefixed by two underscores; 404the corresponding values are called <em>metamethods</em>. 405In the previous example, the key is "<code>__add</code>" 406and the metamethod is the function that performs the addition. 407 408 409<p> 410You can query the metatable of any value 411using the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function. 412Lua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>). 413So, to retrieve the metamethod for event <code>ev</code> in object <code>o</code>, 414Lua does the equivalent to the following code: 415 416<pre> 417 rawget(getmetatable(<em>o</em>) or {}, "__<em>ev</em>") 418</pre> 419 420<p> 421You can replace the metatable of tables 422using the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function. 423You cannot change the metatable of other types from Lua code 424(except by using the debug library (<a href="#6.10">§6.10</a>)); 425you should use the C API for that. 426 427 428<p> 429Tables and full userdata have individual metatables 430(although multiple tables and userdata can share their metatables). 431Values of all other types share one single metatable per type; 432that is, there is one single metatable for all numbers, 433one for all strings, etc. 434By default, a value has no metatable, 435but the string library sets a metatable for the string type (see <a href="#6.4">§6.4</a>). 436 437 438<p> 439A metatable controls how an object behaves in 440arithmetic operations, bitwise operations, 441order comparisons, concatenation, length operation, calls, and indexing. 442A metatable also can define a function to be called 443when a userdata or a table is garbage collected (<a href="#2.5">§2.5</a>). 444 445 446<p> 447For the unary operators (negation, length, and bitwise NOT), 448the metamethod is computed and called with a dummy second operand, 449equal to the first one. 450This extra operand is only to simplify Lua's internals 451(by making these operators behave like a binary operation) 452and may be removed in future versions. 453(For most uses this extra operand is irrelevant.) 454 455 456<p> 457A detailed list of events controlled by metatables is given next. 458Each operation is identified by its corresponding key. 459 460 461 462<ul> 463 464<li><b><code>__add</code>: </b> 465the addition (<code>+</code>) operation. 466If any operand for an addition is not a number 467(nor a string coercible to a number), 468Lua will try to call a metamethod. 469First, Lua will check the first operand (even if it is valid). 470If that operand does not define a metamethod for <code>__add</code>, 471then Lua will check the second operand. 472If Lua can find a metamethod, 473it calls the metamethod with the two operands as arguments, 474and the result of the call 475(adjusted to one value) 476is the result of the operation. 477Otherwise, 478it raises an error. 479</li> 480 481<li><b><code>__sub</code>: </b> 482the subtraction (<code>-</code>) operation. 483Behavior similar to the addition operation. 484</li> 485 486<li><b><code>__mul</code>: </b> 487the multiplication (<code>*</code>) operation. 488Behavior similar to the addition operation. 489</li> 490 491<li><b><code>__div</code>: </b> 492the division (<code>/</code>) operation. 493Behavior similar to the addition operation. 494</li> 495 496<li><b><code>__mod</code>: </b> 497the modulo (<code>%</code>) operation. 498Behavior similar to the addition operation. 499</li> 500 501<li><b><code>__pow</code>: </b> 502the exponentiation (<code>^</code>) operation. 503Behavior similar to the addition operation. 504</li> 505 506<li><b><code>__unm</code>: </b> 507the negation (unary <code>-</code>) operation. 508Behavior similar to the addition operation. 509</li> 510 511<li><b><code>__idiv</code>: </b> 512the floor division (<code>//</code>) operation. 513Behavior similar to the addition operation. 514</li> 515 516<li><b><code>__band</code>: </b> 517the bitwise AND (<code>&</code>) operation. 518Behavior similar to the addition operation, 519except that Lua will try a metamethod 520if any operand is neither an integer 521nor a value coercible to an integer (see <a href="#3.4.3">§3.4.3</a>). 522</li> 523 524<li><b><code>__bor</code>: </b> 525the bitwise OR (<code>|</code>) operation. 526Behavior similar to the bitwise AND operation. 527</li> 528 529<li><b><code>__bxor</code>: </b> 530the bitwise exclusive OR (binary <code>~</code>) operation. 531Behavior similar to the bitwise AND operation. 532</li> 533 534<li><b><code>__bnot</code>: </b> 535the bitwise NOT (unary <code>~</code>) operation. 536Behavior similar to the bitwise AND operation. 537</li> 538 539<li><b><code>__shl</code>: </b> 540the bitwise left shift (<code><<</code>) operation. 541Behavior similar to the bitwise AND operation. 542</li> 543 544<li><b><code>__shr</code>: </b> 545the bitwise right shift (<code>>></code>) operation. 546Behavior similar to the bitwise AND operation. 547</li> 548 549<li><b><code>__concat</code>: </b> 550the concatenation (<code>..</code>) operation. 551Behavior similar to the addition operation, 552except that Lua will try a metamethod 553if any operand is neither a string nor a number 554(which is always coercible to a string). 555</li> 556 557<li><b><code>__len</code>: </b> 558the length (<code>#</code>) operation. 559If the object is not a string, 560Lua will try its metamethod. 561If there is a metamethod, 562Lua calls it with the object as argument, 563and the result of the call 564(always adjusted to one value) 565is the result of the operation. 566If there is no metamethod but the object is a table, 567then Lua uses the table length operation (see <a href="#3.4.7">§3.4.7</a>). 568Otherwise, Lua raises an error. 569</li> 570 571<li><b><code>__eq</code>: </b> 572the equal (<code>==</code>) operation. 573Behavior similar to the addition operation, 574except that Lua will try a metamethod only when the values 575being compared are either both tables or both full userdata 576and they are not primitively equal. 577The result of the call is always converted to a boolean. 578</li> 579 580<li><b><code>__lt</code>: </b> 581the less than (<code><</code>) operation. 582Behavior similar to the addition operation, 583except that Lua will try a metamethod only when the values 584being compared are neither both numbers nor both strings. 585The result of the call is always converted to a boolean. 586</li> 587 588<li><b><code>__le</code>: </b> 589the less equal (<code><=</code>) operation. 590Unlike other operations, 591the less-equal operation can use two different events. 592First, Lua looks for the <code>__le</code> metamethod in both operands, 593like in the less than operation. 594If it cannot find such a metamethod, 595then it will try the <code>__lt</code> metamethod, 596assuming that <code>a <= b</code> is equivalent to <code>not (b < a)</code>. 597As with the other comparison operators, 598the result is always a boolean. 599(This use of the <code>__lt</code> event can be removed in future versions; 600it is also slower than a real <code>__le</code> metamethod.) 601</li> 602 603<li><b><code>__index</code>: </b> 604The indexing access <code>table[key]</code>. 605This event happens when <code>table</code> is not a table or 606when <code>key</code> is not present in <code>table</code>. 607The metamethod is looked up in <code>table</code>. 608 609 610<p> 611Despite the name, 612the metamethod for this event can be either a function or a table. 613If it is a function, 614it is called with <code>table</code> and <code>key</code> as arguments, 615and the result of the call 616(adjusted to one value) 617is the result of the operation. 618If it is a table, 619the final result is the result of indexing this table with <code>key</code>. 620(This indexing is regular, not raw, 621and therefore can trigger another metamethod.) 622</li> 623 624<li><b><code>__newindex</code>: </b> 625The indexing assignment <code>table[key] = value</code>. 626Like the index event, 627this event happens when <code>table</code> is not a table or 628when <code>key</code> is not present in <code>table</code>. 629The metamethod is looked up in <code>table</code>. 630 631 632<p> 633Like with indexing, 634the metamethod for this event can be either a function or a table. 635If it is a function, 636it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments. 637If it is a table, 638Lua does an indexing assignment to this table with the same key and value. 639(This assignment is regular, not raw, 640and therefore can trigger another metamethod.) 641 642 643<p> 644Whenever there is a <code>__newindex</code> metamethod, 645Lua does not perform the primitive assignment. 646(If necessary, 647the metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a> 648to do the assignment.) 649</li> 650 651<li><b><code>__call</code>: </b> 652The call operation <code>func(args)</code>. 653This event happens when Lua tries to call a non-function value 654(that is, <code>func</code> is not a function). 655The metamethod is looked up in <code>func</code>. 656If present, 657the metamethod is called with <code>func</code> as its first argument, 658followed by the arguments of the original call (<code>args</code>). 659All results of the call 660are the result of the operation. 661(This is the only metamethod that allows multiple results.) 662</li> 663 664</ul> 665 666<p> 667It is a good practice to add all needed metamethods to a table 668before setting it as a metatable of some object. 669In particular, the <code>__gc</code> metamethod works only when this order 670is followed (see <a href="#2.5.1">§2.5.1</a>). 671 672 673<p> 674Because metatables are regular tables, 675they can contain arbitrary fields, 676not only the event names defined above. 677Some functions in the standard library 678(e.g., <a href="#pdf-tostring"><code>tostring</code></a>) 679use other fields in metatables for their own purposes. 680 681 682 683 684 685<h2>2.5 – <a name="2.5">Garbage Collection</a></h2> 686 687<p> 688Lua performs automatic memory management. 689This means that 690you do not have to worry about allocating memory for new objects 691or freeing it when the objects are no longer needed. 692Lua manages memory automatically by running 693a <em>garbage collector</em> to collect all <em>dead objects</em> 694(that is, objects that are no longer accessible from Lua). 695All memory used by Lua is subject to automatic management: 696strings, tables, userdata, functions, threads, internal structures, etc. 697 698 699<p> 700Lua implements an incremental mark-and-sweep collector. 701It uses two numbers to control its garbage-collection cycles: 702the <em>garbage-collector pause</em> and 703the <em>garbage-collector step multiplier</em>. 704Both use percentage points as units 705(e.g., a value of 100 means an internal value of 1). 706 707 708<p> 709The garbage-collector pause 710controls how long the collector waits before starting a new cycle. 711Larger values make the collector less aggressive. 712Values smaller than 100 mean the collector will not wait to 713start a new cycle. 714A value of 200 means that the collector waits for the total memory in use 715to double before starting a new cycle. 716 717 718<p> 719The garbage-collector step multiplier 720controls the relative speed of the collector relative to 721memory allocation. 722Larger values make the collector more aggressive but also increase 723the size of each incremental step. 724You should not use values smaller than 100, 725because they make the collector too slow and 726can result in the collector never finishing a cycle. 727The default is 200, 728which means that the collector runs at "twice" 729the speed of memory allocation. 730 731 732<p> 733If you set the step multiplier to a very large number 734(larger than 10% of the maximum number of 735bytes that the program may use), 736the collector behaves like a stop-the-world collector. 737If you then set the pause to 200, 738the collector behaves as in old Lua versions, 739doing a complete collection every time Lua doubles its 740memory usage. 741 742 743<p> 744You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C 745or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. 746You can also use these functions to control 747the collector directly (e.g., stop and restart it). 748 749 750 751<h3>2.5.1 – <a name="2.5.1">Garbage-Collection Metamethods</a></h3> 752 753<p> 754You can set garbage-collector metamethods for tables 755and, using the C API, 756for full userdata (see <a href="#2.4">§2.4</a>). 757These metamethods are also called <em>finalizers</em>. 758Finalizers allow you to coordinate Lua's garbage collection 759with external resource management 760(such as closing files, network or database connections, 761or freeing your own memory). 762 763 764<p> 765For an object (table or userdata) to be finalized when collected, 766you must <em>mark</em> it for finalization. 767 768You mark an object for finalization when you set its metatable 769and the metatable has a field indexed by the string "<code>__gc</code>". 770Note that if you set a metatable without a <code>__gc</code> field 771and later create that field in the metatable, 772the object will not be marked for finalization. 773 774 775<p> 776When a marked object becomes garbage, 777it is not collected immediately by the garbage collector. 778Instead, Lua puts it in a list. 779After the collection, 780Lua goes through that list. 781For each object in the list, 782it checks the object's <code>__gc</code> metamethod: 783If it is a function, 784Lua calls it with the object as its single argument; 785if the metamethod is not a function, 786Lua simply ignores it. 787 788 789<p> 790At the end of each garbage-collection cycle, 791the finalizers for objects are called in 792the reverse order that the objects were marked for finalization, 793among those collected in that cycle; 794that is, the first finalizer to be called is the one associated 795with the object marked last in the program. 796The execution of each finalizer may occur at any point during 797the execution of the regular code. 798 799 800<p> 801Because the object being collected must still be used by the finalizer, 802that object (and other objects accessible only through it) 803must be <em>resurrected</em> by Lua. 804Usually, this resurrection is transient, 805and the object memory is freed in the next garbage-collection cycle. 806However, if the finalizer stores the object in some global place 807(e.g., a global variable), 808then the resurrection is permanent. 809Moreover, if the finalizer marks a finalizing object for finalization again, 810its finalizer will be called again in the next cycle where the 811object is unreachable. 812In any case, 813the object memory is freed only in a GC cycle where 814the object is unreachable and not marked for finalization. 815 816 817<p> 818When you close a state (see <a href="#lua_close"><code>lua_close</code></a>), 819Lua calls the finalizers of all objects marked for finalization, 820following the reverse order that they were marked. 821If any finalizer marks objects for collection during that phase, 822these marks have no effect. 823 824 825 826 827 828<h3>2.5.2 – <a name="2.5.2">Weak Tables</a></h3> 829 830<p> 831A <em>weak table</em> is a table whose elements are 832<em>weak references</em>. 833A weak reference is ignored by the garbage collector. 834In other words, 835if the only references to an object are weak references, 836then the garbage collector will collect that object. 837 838 839<p> 840A weak table can have weak keys, weak values, or both. 841A table with weak values allows the collection of its values, 842but prevents the collection of its keys. 843A table with both weak keys and weak values allows the collection of 844both keys and values. 845In any case, if either the key or the value is collected, 846the whole pair is removed from the table. 847The weakness of a table is controlled by the 848<code>__mode</code> field of its metatable. 849If the <code>__mode</code> field is a string containing the character '<code>k</code>', 850the keys in the table are weak. 851If <code>__mode</code> contains '<code>v</code>', 852the values in the table are weak. 853 854 855<p> 856A table with weak keys and strong values 857is also called an <em>ephemeron table</em>. 858In an ephemeron table, 859a value is considered reachable only if its key is reachable. 860In particular, 861if the only reference to a key comes through its value, 862the pair is removed. 863 864 865<p> 866Any change in the weakness of a table may take effect only 867at the next collect cycle. 868In particular, if you change the weakness to a stronger mode, 869Lua may still collect some items from that table 870before the change takes effect. 871 872 873<p> 874Only objects that have an explicit construction 875are removed from weak tables. 876Values, such as numbers and light C functions, 877are not subject to garbage collection, 878and therefore are not removed from weak tables 879(unless their associated values are collected). 880Although strings are subject to garbage collection, 881they do not have an explicit construction, 882and therefore are not removed from weak tables. 883 884 885<p> 886Resurrected objects 887(that is, objects being finalized 888and objects accessible only through objects being finalized) 889have a special behavior in weak tables. 890They are removed from weak values before running their finalizers, 891but are removed from weak keys only in the next collection 892after running their finalizers, when such objects are actually freed. 893This behavior allows the finalizer to access properties 894associated with the object through weak tables. 895 896 897<p> 898If a weak table is among the resurrected objects in a collection cycle, 899it may not be properly cleared until the next cycle. 900 901 902 903 904 905 906 907<h2>2.6 – <a name="2.6">Coroutines</a></h2> 908 909<p> 910Lua supports coroutines, 911also called <em>collaborative multithreading</em>. 912A coroutine in Lua represents an independent thread of execution. 913Unlike threads in multithread systems, however, 914a coroutine only suspends its execution by explicitly calling 915a yield function. 916 917 918<p> 919You create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>. 920Its sole argument is a function 921that is the main function of the coroutine. 922The <code>create</code> function only creates a new coroutine and 923returns a handle to it (an object of type <em>thread</em>); 924it does not start the coroutine. 925 926 927<p> 928You execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 929When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 930passing as its first argument 931a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 932the coroutine starts its execution by 933calling its main function. 934Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed 935as arguments to that function. 936After the coroutine starts running, 937it runs until it terminates or <em>yields</em>. 938 939 940<p> 941A coroutine can terminate its execution in two ways: 942normally, when its main function returns 943(explicitly or implicitly, after the last instruction); 944and abnormally, if there is an unprotected error. 945In case of normal termination, 946<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>, 947plus any values returned by the coroutine main function. 948In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b> 949plus an error object. 950 951 952<p> 953A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 954When a coroutine yields, 955the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately, 956even if the yield happens inside nested function calls 957(that is, not in the main function, 958but in a function directly or indirectly called by the main function). 959In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>, 960plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 961The next time you resume the same coroutine, 962it continues its execution from the point where it yielded, 963with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra 964arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 965 966 967<p> 968Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 969the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine, 970but instead of returning the coroutine itself, 971it returns a function that, when called, resumes the coroutine. 972Any arguments passed to this function 973go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 974<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>, 975except the first one (the boolean error code). 976Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 977<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors; 978any error is propagated to the caller. 979 980 981<p> 982As an example of how coroutines work, 983consider the following code: 984 985<pre> 986 function foo (a) 987 print("foo", a) 988 return coroutine.yield(2*a) 989 end 990 991 co = coroutine.create(function (a,b) 992 print("co-body", a, b) 993 local r = foo(a+1) 994 print("co-body", r) 995 local r, s = coroutine.yield(a+b, a-b) 996 print("co-body", r, s) 997 return b, "end" 998 end) 999 1000 print("main", coroutine.resume(co, 1, 10)) 1001 print("main", coroutine.resume(co, "r")) 1002 print("main", coroutine.resume(co, "x", "y")) 1003 print("main", coroutine.resume(co, "x", "y")) 1004</pre><p> 1005When you run it, it produces the following output: 1006 1007<pre> 1008 co-body 1 10 1009 foo 2 1010 main true 4 1011 co-body r 1012 main true 11 -9 1013 co-body x y 1014 main true 10 end 1015 main false cannot resume dead coroutine 1016</pre> 1017 1018<p> 1019You can also create and manipulate coroutines through the C API: 1020see functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>, 1021and <a href="#lua_yield"><code>lua_yield</code></a>. 1022 1023 1024 1025 1026 1027<h1>3 – <a name="3">The Language</a></h1> 1028 1029<p> 1030This section describes the lexis, the syntax, and the semantics of Lua. 1031In other words, 1032this section describes 1033which tokens are valid, 1034how they can be combined, 1035and what their combinations mean. 1036 1037 1038<p> 1039Language constructs will be explained using the usual extended BNF notation, 1040in which 1041{<em>a</em>} means 0 or more <em>a</em>'s, and 1042[<em>a</em>] means an optional <em>a</em>. 1043Non-terminals are shown like non-terminal, 1044keywords are shown like <b>kword</b>, 1045and other terminal symbols are shown like ‘<b>=</b>’. 1046The complete syntax of Lua can be found in <a href="#9">§9</a> 1047at the end of this manual. 1048 1049 1050 1051<h2>3.1 – <a name="3.1">Lexical Conventions</a></h2> 1052 1053<p> 1054Lua is a free-form language. 1055It ignores spaces (including new lines) and comments 1056between lexical elements (tokens), 1057except as delimiters between names and keywords. 1058 1059 1060<p> 1061<em>Names</em> 1062(also called <em>identifiers</em>) 1063in Lua can be any string of letters, 1064digits, and underscores, 1065not beginning with a digit and 1066not being a reserved word. 1067Identifiers are used to name variables, table fields, and labels. 1068 1069 1070<p> 1071The following <em>keywords</em> are reserved 1072and cannot be used as names: 1073 1074 1075<pre> 1076 and break do else elseif end 1077 false for function goto if in 1078 local nil not or repeat return 1079 then true until while 1080</pre> 1081 1082<p> 1083Lua is a case-sensitive language: 1084<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> 1085are two different, valid names. 1086As a convention, 1087programs should avoid creating 1088names that start with an underscore followed by 1089one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>). 1090 1091 1092<p> 1093The following strings denote other tokens: 1094 1095<pre> 1096 + - * / % ^ # 1097 & ~ | << >> // 1098 == ~= <= >= < > = 1099 ( ) { } [ ] :: 1100 ; : , . .. ... 1101</pre> 1102 1103<p> 1104<em>Literal strings</em> 1105can be delimited by matching single or double quotes, 1106and can contain the following C-like escape sequences: 1107'<code>\a</code>' (bell), 1108'<code>\b</code>' (backspace), 1109'<code>\f</code>' (form feed), 1110'<code>\n</code>' (newline), 1111'<code>\r</code>' (carriage return), 1112'<code>\t</code>' (horizontal tab), 1113'<code>\v</code>' (vertical tab), 1114'<code>\\</code>' (backslash), 1115'<code>\"</code>' (quotation mark [double quote]), 1116and '<code>\'</code>' (apostrophe [single quote]). 1117A backslash followed by a real newline 1118results in a newline in the string. 1119The escape sequence '<code>\z</code>' skips the following span 1120of white-space characters, 1121including line breaks; 1122it is particularly useful to break and indent a long literal string 1123into multiple lines without adding the newlines and spaces 1124into the string contents. 1125 1126 1127<p> 1128Strings in Lua can contain any 8-bit value, including embedded zeros, 1129which can be specified as '<code>\0</code>'. 1130More generally, 1131we can specify any byte in a literal string by its numeric value. 1132This can be done 1133with the escape sequence <code>\x<em>XX</em></code>, 1134where <em>XX</em> is a sequence of exactly two hexadecimal digits, 1135or with the escape sequence <code>\<em>ddd</em></code>, 1136where <em>ddd</em> is a sequence of up to three decimal digits. 1137(Note that if a decimal escape sequence is to be followed by a digit, 1138it must be expressed using exactly three digits.) 1139 1140 1141<p> 1142The UTF-8 encoding of a Unicode character 1143can be inserted in a literal string with 1144the escape sequence <code>\u{<em>XXX</em>}</code> 1145(note the mandatory enclosing brackets), 1146where <em>XXX</em> is a sequence of one or more hexadecimal digits 1147representing the character code point. 1148 1149 1150<p> 1151Literal strings can also be defined using a long format 1152enclosed by <em>long brackets</em>. 1153We define an <em>opening long bracket of level <em>n</em></em> as an opening 1154square bracket followed by <em>n</em> equal signs followed by another 1155opening square bracket. 1156So, an opening long bracket of level 0 is written as <code>[[</code>, 1157an opening long bracket of level 1 is written as <code>[=[</code>, 1158and so on. 1159A <em>closing long bracket</em> is defined similarly; 1160for instance, 1161a closing long bracket of level 4 is written as <code>]====]</code>. 1162A <em>long literal</em> starts with an opening long bracket of any level and 1163ends at the first closing long bracket of the same level. 1164It can contain any text except a closing bracket of the same level. 1165Literals in this bracketed form can run for several lines, 1166do not interpret any escape sequences, 1167and ignore long brackets of any other level. 1168Any kind of end-of-line sequence 1169(carriage return, newline, carriage return followed by newline, 1170or newline followed by carriage return) 1171is converted to a simple newline. 1172 1173 1174<p> 1175Any byte in a literal string not 1176explicitly affected by the previous rules represents itself. 1177However, Lua opens files for parsing in text mode, 1178and the system file functions may have problems with 1179some control characters. 1180So, it is safer to represent 1181non-text data as a quoted literal with 1182explicit escape sequences for the non-text characters. 1183 1184 1185<p> 1186For convenience, 1187when the opening long bracket is immediately followed by a newline, 1188the newline is not included in the string. 1189As an example, in a system using ASCII 1190(in which '<code>a</code>' is coded as 97, 1191newline is coded as 10, and '<code>1</code>' is coded as 49), 1192the five literal strings below denote the same string: 1193 1194<pre> 1195 a = 'alo\n123"' 1196 a = "alo\n123\"" 1197 a = '\97lo\10\04923"' 1198 a = [[alo 1199 123"]] 1200 a = [==[ 1201 alo 1202 123"]==] 1203</pre> 1204 1205<p> 1206A <em>numeric constant</em> (or <em>numeral</em>) 1207can be written with an optional fractional part 1208and an optional decimal exponent, 1209marked by a letter '<code>e</code>' or '<code>E</code>'. 1210Lua also accepts hexadecimal constants, 1211which start with <code>0x</code> or <code>0X</code>. 1212Hexadecimal constants also accept an optional fractional part 1213plus an optional binary exponent, 1214marked by a letter '<code>p</code>' or '<code>P</code>'. 1215A numeric constant with a radix point or an exponent 1216denotes a float; 1217otherwise, 1218if its value fits in an integer, 1219it denotes an integer. 1220Examples of valid integer constants are 1221 1222<pre> 1223 3 345 0xff 0xBEBADA 1224</pre><p> 1225Examples of valid float constants are 1226 1227<pre> 1228 3.0 3.1416 314.16e-2 0.31416E1 34e1 1229 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 1230</pre> 1231 1232<p> 1233A <em>comment</em> starts with a double hyphen (<code>--</code>) 1234anywhere outside a string. 1235If the text immediately after <code>--</code> is not an opening long bracket, 1236the comment is a <em>short comment</em>, 1237which runs until the end of the line. 1238Otherwise, it is a <em>long comment</em>, 1239which runs until the corresponding closing long bracket. 1240Long comments are frequently used to disable code temporarily. 1241 1242 1243 1244 1245 1246<h2>3.2 – <a name="3.2">Variables</a></h2> 1247 1248<p> 1249Variables are places that store values. 1250There are three kinds of variables in Lua: 1251global variables, local variables, and table fields. 1252 1253 1254<p> 1255A single name can denote a global variable or a local variable 1256(or a function's formal parameter, 1257which is a particular kind of local variable): 1258 1259<pre> 1260 var ::= Name 1261</pre><p> 1262Name denotes identifiers, as defined in <a href="#3.1">§3.1</a>. 1263 1264 1265<p> 1266Any variable name is assumed to be global unless explicitly declared 1267as a local (see <a href="#3.3.7">§3.3.7</a>). 1268Local variables are <em>lexically scoped</em>: 1269local variables can be freely accessed by functions 1270defined inside their scope (see <a href="#3.5">§3.5</a>). 1271 1272 1273<p> 1274Before the first assignment to a variable, its value is <b>nil</b>. 1275 1276 1277<p> 1278Square brackets are used to index a table: 1279 1280<pre> 1281 var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ 1282</pre><p> 1283The meaning of accesses to table fields can be changed via metatables. 1284An access to an indexed variable <code>t[i]</code> is equivalent to 1285a call <code>gettable_event(t,i)</code>. 1286(See <a href="#2.4">§2.4</a> for a complete description of the 1287<code>gettable_event</code> function. 1288This function is not defined or callable in Lua. 1289We use it here only for explanatory purposes.) 1290 1291 1292<p> 1293The syntax <code>var.Name</code> is just syntactic sugar for 1294<code>var["Name"]</code>: 1295 1296<pre> 1297 var ::= prefixexp ‘<b>.</b>’ Name 1298</pre> 1299 1300<p> 1301An access to a global variable <code>x</code> 1302is equivalent to <code>_ENV.x</code>. 1303Due to the way that chunks are compiled, 1304<code>_ENV</code> is never a global name (see <a href="#2.2">§2.2</a>). 1305 1306 1307 1308 1309 1310<h2>3.3 – <a name="3.3">Statements</a></h2> 1311 1312<p> 1313Lua supports an almost conventional set of statements, 1314similar to those in Pascal or C. 1315This set includes 1316assignments, control structures, function calls, 1317and variable declarations. 1318 1319 1320 1321<h3>3.3.1 – <a name="3.3.1">Blocks</a></h3> 1322 1323<p> 1324A block is a list of statements, 1325which are executed sequentially: 1326 1327<pre> 1328 block ::= {stat} 1329</pre><p> 1330Lua has <em>empty statements</em> 1331that allow you to separate statements with semicolons, 1332start a block with a semicolon 1333or write two semicolons in sequence: 1334 1335<pre> 1336 stat ::= ‘<b>;</b>’ 1337</pre> 1338 1339<p> 1340Function calls and assignments 1341can start with an open parenthesis. 1342This possibility leads to an ambiguity in Lua's grammar. 1343Consider the following fragment: 1344 1345<pre> 1346 a = b + c 1347 (print or io.write)('done') 1348</pre><p> 1349The grammar could see it in two ways: 1350 1351<pre> 1352 a = b + c(print or io.write)('done') 1353 1354 a = b + c; (print or io.write)('done') 1355</pre><p> 1356The current parser always sees such constructions 1357in the first way, 1358interpreting the open parenthesis 1359as the start of the arguments to a call. 1360To avoid this ambiguity, 1361it is a good practice to always precede with a semicolon 1362statements that start with a parenthesis: 1363 1364<pre> 1365 ;(print or io.write)('done') 1366</pre> 1367 1368<p> 1369A block can be explicitly delimited to produce a single statement: 1370 1371<pre> 1372 stat ::= <b>do</b> block <b>end</b> 1373</pre><p> 1374Explicit blocks are useful 1375to control the scope of variable declarations. 1376Explicit blocks are also sometimes used to 1377add a <b>return</b> statement in the middle 1378of another block (see <a href="#3.3.4">§3.3.4</a>). 1379 1380 1381 1382 1383 1384<h3>3.3.2 – <a name="3.3.2">Chunks</a></h3> 1385 1386<p> 1387The unit of compilation of Lua is called a <em>chunk</em>. 1388Syntactically, 1389a chunk is simply a block: 1390 1391<pre> 1392 chunk ::= block 1393</pre> 1394 1395<p> 1396Lua handles a chunk as the body of an anonymous function 1397with a variable number of arguments 1398(see <a href="#3.4.11">§3.4.11</a>). 1399As such, chunks can define local variables, 1400receive arguments, and return values. 1401Moreover, such anonymous function is compiled as in the 1402scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>). 1403The resulting function always has <code>_ENV</code> as its only upvalue, 1404even if it does not use that variable. 1405 1406 1407<p> 1408A chunk can be stored in a file or in a string inside the host program. 1409To execute a chunk, 1410Lua first <em>loads</em> it, 1411precompiling the chunk's code into instructions for a virtual machine, 1412and then Lua executes the compiled code 1413with an interpreter for the virtual machine. 1414 1415 1416<p> 1417Chunks can also be precompiled into binary form; 1418see program <code>luac</code> and function <a href="#pdf-string.dump"><code>string.dump</code></a> for details. 1419Programs in source and compiled forms are interchangeable; 1420Lua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>). 1421 1422 1423 1424 1425 1426<h3>3.3.3 – <a name="3.3.3">Assignment</a></h3> 1427 1428<p> 1429Lua allows multiple assignments. 1430Therefore, the syntax for assignment 1431defines a list of variables on the left side 1432and a list of expressions on the right side. 1433The elements in both lists are separated by commas: 1434 1435<pre> 1436 stat ::= varlist ‘<b>=</b>’ explist 1437 varlist ::= var {‘<b>,</b>’ var} 1438 explist ::= exp {‘<b>,</b>’ exp} 1439</pre><p> 1440Expressions are discussed in <a href="#3.4">§3.4</a>. 1441 1442 1443<p> 1444Before the assignment, 1445the list of values is <em>adjusted</em> to the length of 1446the list of variables. 1447If there are more values than needed, 1448the excess values are thrown away. 1449If there are fewer values than needed, 1450the list is extended with as many <b>nil</b>'s as needed. 1451If the list of expressions ends with a function call, 1452then all values returned by that call enter the list of values, 1453before the adjustment 1454(except when the call is enclosed in parentheses; see <a href="#3.4">§3.4</a>). 1455 1456 1457<p> 1458The assignment statement first evaluates all its expressions 1459and only then the assignments are performed. 1460Thus the code 1461 1462<pre> 1463 i = 3 1464 i, a[i] = i+1, 20 1465</pre><p> 1466sets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 1467because the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 1468before it is assigned 4. 1469Similarly, the line 1470 1471<pre> 1472 x, y = y, x 1473</pre><p> 1474exchanges the values of <code>x</code> and <code>y</code>, 1475and 1476 1477<pre> 1478 x, y, z = y, z, x 1479</pre><p> 1480cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 1481 1482 1483<p> 1484The meaning of assignments to global variables 1485and table fields can be changed via metatables. 1486An assignment to an indexed variable <code>t[i] = val</code> is equivalent to 1487<code>settable_event(t,i,val)</code>. 1488(See <a href="#2.4">§2.4</a> for a complete description of the 1489<code>settable_event</code> function. 1490This function is not defined or callable in Lua. 1491We use it here only for explanatory purposes.) 1492 1493 1494<p> 1495An assignment to a global name <code>x = val</code> 1496is equivalent to the assignment 1497<code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>). 1498 1499 1500 1501 1502 1503<h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p> 1504The control structures 1505<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 1506familiar syntax: 1507 1508 1509 1510 1511<pre> 1512 stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 1513 stat ::= <b>repeat</b> block <b>until</b> exp 1514 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> 1515</pre><p> 1516Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>). 1517 1518 1519<p> 1520The condition expression of a 1521control structure can return any value. 1522Both <b>false</b> and <b>nil</b> are considered false. 1523All values different from <b>nil</b> and <b>false</b> are considered true 1524(in particular, the number 0 and the empty string are also true). 1525 1526 1527<p> 1528In the <b>repeat</b>–<b>until</b> loop, 1529the inner block does not end at the <b>until</b> keyword, 1530but only after the condition. 1531So, the condition can refer to local variables 1532declared inside the loop block. 1533 1534 1535<p> 1536The <b>goto</b> statement transfers the program control to a label. 1537For syntactical reasons, 1538labels in Lua are considered statements too: 1539 1540 1541 1542<pre> 1543 stat ::= <b>goto</b> Name 1544 stat ::= label 1545 label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 1546</pre> 1547 1548<p> 1549A label is visible in the entire block where it is defined, 1550except 1551inside nested blocks where a label with the same name is defined and 1552inside nested functions. 1553A goto may jump to any visible label as long as it does not 1554enter into the scope of a local variable. 1555 1556 1557<p> 1558Labels and empty statements are called <em>void statements</em>, 1559as they perform no actions. 1560 1561 1562<p> 1563The <b>break</b> statement terminates the execution of a 1564<b>while</b>, <b>repeat</b>, or <b>for</b> loop, 1565skipping to the next statement after the loop: 1566 1567 1568<pre> 1569 stat ::= <b>break</b> 1570</pre><p> 1571A <b>break</b> ends the innermost enclosing loop. 1572 1573 1574<p> 1575The <b>return</b> statement is used to return values 1576from a function or a chunk 1577(which is an anonymous function). 1578 1579Functions can return more than one value, 1580so the syntax for the <b>return</b> statement is 1581 1582<pre> 1583 stat ::= <b>return</b> [explist] [‘<b>;</b>’] 1584</pre> 1585 1586<p> 1587The <b>return</b> statement can only be written 1588as the last statement of a block. 1589If it is really necessary to <b>return</b> in the middle of a block, 1590then an explicit inner block can be used, 1591as in the idiom <code>do return end</code>, 1592because now <b>return</b> is the last statement in its (inner) block. 1593 1594 1595 1596 1597 1598<h3>3.3.5 – <a name="3.3.5">For Statement</a></h3> 1599 1600<p> 1601 1602The <b>for</b> statement has two forms: 1603one numerical and one generic. 1604 1605 1606<p> 1607The numerical <b>for</b> loop repeats a block of code while a 1608control variable runs through an arithmetic progression. 1609It has the following syntax: 1610 1611<pre> 1612 stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> 1613</pre><p> 1614The <em>block</em> is repeated for <em>name</em> starting at the value of 1615the first <em>exp</em>, until it passes the second <em>exp</em> by steps of the 1616third <em>exp</em>. 1617More precisely, a <b>for</b> statement like 1618 1619<pre> 1620 for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end 1621</pre><p> 1622is equivalent to the code: 1623 1624<pre> 1625 do 1626 local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>) 1627 if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end 1628 <em>var</em> = <em>var</em> - <em>step</em> 1629 while true do 1630 <em>var</em> = <em>var</em> + <em>step</em> 1631 if (<em>step</em> >= 0 and <em>var</em> > <em>limit</em>) or (<em>step</em> < 0 and <em>var</em> < <em>limit</em>) then 1632 break 1633 end 1634 local v = <em>var</em> 1635 <em>block</em> 1636 end 1637 end 1638</pre> 1639 1640<p> 1641Note the following: 1642 1643<ul> 1644 1645<li> 1646All three control expressions are evaluated only once, 1647before the loop starts. 1648They must all result in numbers. 1649</li> 1650 1651<li> 1652<code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables. 1653The names shown here are for explanatory purposes only. 1654</li> 1655 1656<li> 1657If the third expression (the step) is absent, 1658then a step of 1 is used. 1659</li> 1660 1661<li> 1662You can use <b>break</b> and <b>goto</b> to exit a <b>for</b> loop. 1663</li> 1664 1665<li> 1666The loop variable <code>v</code> is local to the loop body. 1667If you need its value after the loop, 1668assign it to another variable before exiting the loop. 1669</li> 1670 1671</ul> 1672 1673<p> 1674The generic <b>for</b> statement works over functions, 1675called <em>iterators</em>. 1676On each iteration, the iterator function is called to produce a new value, 1677stopping when this new value is <b>nil</b>. 1678The generic <b>for</b> loop has the following syntax: 1679 1680<pre> 1681 stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> 1682 namelist ::= Name {‘<b>,</b>’ Name} 1683</pre><p> 1684A <b>for</b> statement like 1685 1686<pre> 1687 for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end 1688</pre><p> 1689is equivalent to the code: 1690 1691<pre> 1692 do 1693 local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em> 1694 while true do 1695 local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>) 1696 if <em>var_1</em> == nil then break end 1697 <em>var</em> = <em>var_1</em> 1698 <em>block</em> 1699 end 1700 end 1701</pre><p> 1702Note the following: 1703 1704<ul> 1705 1706<li> 1707<code><em>explist</em></code> is evaluated only once. 1708Its results are an <em>iterator</em> function, 1709a <em>state</em>, 1710and an initial value for the first <em>iterator variable</em>. 1711</li> 1712 1713<li> 1714<code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables. 1715The names are here for explanatory purposes only. 1716</li> 1717 1718<li> 1719You can use <b>break</b> to exit a <b>for</b> loop. 1720</li> 1721 1722<li> 1723The loop variables <code><em>var_i</em></code> are local to the loop; 1724you cannot use their values after the <b>for</b> ends. 1725If you need these values, 1726then assign them to other variables before breaking or exiting the loop. 1727</li> 1728 1729</ul> 1730 1731 1732 1733 1734<h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p> 1735To allow possible side-effects, 1736function calls can be executed as statements: 1737 1738<pre> 1739 stat ::= functioncall 1740</pre><p> 1741In this case, all returned values are thrown away. 1742Function calls are explained in <a href="#3.4.10">§3.4.10</a>. 1743 1744 1745 1746 1747 1748<h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p> 1749Local variables can be declared anywhere inside a block. 1750The declaration can include an initial assignment: 1751 1752<pre> 1753 stat ::= <b>local</b> namelist [‘<b>=</b>’ explist] 1754</pre><p> 1755If present, an initial assignment has the same semantics 1756of a multiple assignment (see <a href="#3.3.3">§3.3.3</a>). 1757Otherwise, all variables are initialized with <b>nil</b>. 1758 1759 1760<p> 1761A chunk is also a block (see <a href="#3.3.2">§3.3.2</a>), 1762and so local variables can be declared in a chunk outside any explicit block. 1763 1764 1765<p> 1766The visibility rules for local variables are explained in <a href="#3.5">§3.5</a>. 1767 1768 1769 1770 1771 1772 1773 1774<h2>3.4 – <a name="3.4">Expressions</a></h2> 1775 1776<p> 1777The basic expressions in Lua are the following: 1778 1779<pre> 1780 exp ::= prefixexp 1781 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 1782 exp ::= Numeral 1783 exp ::= LiteralString 1784 exp ::= functiondef 1785 exp ::= tableconstructor 1786 exp ::= ‘<b>...</b>’ 1787 exp ::= exp binop exp 1788 exp ::= unop exp 1789 prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 1790</pre> 1791 1792<p> 1793Numerals and literal strings are explained in <a href="#3.1">§3.1</a>; 1794variables are explained in <a href="#3.2">§3.2</a>; 1795function definitions are explained in <a href="#3.4.11">§3.4.11</a>; 1796function calls are explained in <a href="#3.4.10">§3.4.10</a>; 1797table constructors are explained in <a href="#3.4.9">§3.4.9</a>. 1798Vararg expressions, 1799denoted by three dots ('<code>...</code>'), can only be used when 1800directly inside a vararg function; 1801they are explained in <a href="#3.4.11">§3.4.11</a>. 1802 1803 1804<p> 1805Binary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), 1806bitwise operators (see <a href="#3.4.2">§3.4.2</a>), 1807relational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>), 1808and the concatenation operator (see <a href="#3.4.6">§3.4.6</a>). 1809Unary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), 1810the unary bitwise NOT (see <a href="#3.4.2">§3.4.2</a>), 1811the unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), 1812and the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). 1813 1814 1815<p> 1816Both function calls and vararg expressions can result in multiple values. 1817If a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>), 1818then its return list is adjusted to zero elements, 1819thus discarding all returned values. 1820If an expression is used as the last (or the only) element 1821of a list of expressions, 1822then no adjustment is made 1823(unless the expression is enclosed in parentheses). 1824In all other contexts, 1825Lua adjusts the result list to one element, 1826either discarding all values except the first one 1827or adding a single <b>nil</b> if there are no values. 1828 1829 1830<p> 1831Here are some examples: 1832 1833<pre> 1834 f() -- adjusted to 0 results 1835 g(f(), x) -- f() is adjusted to 1 result 1836 g(x, f()) -- g gets x plus all results from f() 1837 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) 1838 a,b = ... -- a gets the first vararg parameter, b gets 1839 -- the second (both a and b can get nil if there 1840 -- is no corresponding vararg parameter) 1841 1842 a,b,c = x, f() -- f() is adjusted to 2 results 1843 a,b,c = f() -- f() is adjusted to 3 results 1844 return f() -- returns all results from f() 1845 return ... -- returns all received vararg parameters 1846 return x,y,f() -- returns x, y, and all results from f() 1847 {f()} -- creates a list with all results from f() 1848 {...} -- creates a list with all vararg parameters 1849 {f(), nil} -- f() is adjusted to 1 result 1850</pre> 1851 1852<p> 1853Any expression enclosed in parentheses always results in only one value. 1854Thus, 1855<code>(f(x,y,z))</code> is always a single value, 1856even if <code>f</code> returns several values. 1857(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> 1858or <b>nil</b> if <code>f</code> does not return any values.) 1859 1860 1861 1862<h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p> 1863Lua supports the following arithmetic operators: 1864 1865<ul> 1866<li><b><code>+</code>: </b>addition</li> 1867<li><b><code>-</code>: </b>subtraction</li> 1868<li><b><code>*</code>: </b>multiplication</li> 1869<li><b><code>/</code>: </b>float division</li> 1870<li><b><code>//</code>: </b>floor division</li> 1871<li><b><code>%</code>: </b>modulo</li> 1872<li><b><code>^</code>: </b>exponentiation</li> 1873<li><b><code>-</code>: </b>unary minus</li> 1874</ul> 1875 1876<p> 1877With the exception of exponentiation and float division, 1878the arithmetic operators work as follows: 1879If both operands are integers, 1880the operation is performed over integers and the result is an integer. 1881Otherwise, if both operands are numbers 1882or strings that can be converted to 1883numbers (see <a href="#3.4.3">§3.4.3</a>), 1884then they are converted to floats, 1885the operation is performed following the usual rules 1886for floating-point arithmetic 1887(usually the IEEE 754 standard), 1888and the result is a float. 1889 1890 1891<p> 1892Exponentiation and float division (<code>/</code>) 1893always convert their operands to floats 1894and the result is always a float. 1895Exponentiation uses the ISO C function <code>pow</code>, 1896so that it works for non-integer exponents too. 1897 1898 1899<p> 1900Floor division (<code>//</code>) is a division 1901that rounds the quotient towards minus infinity, 1902that is, the floor of the division of its operands. 1903 1904 1905<p> 1906Modulo is defined as the remainder of a division 1907that rounds the quotient towards minus infinity (floor division). 1908 1909 1910<p> 1911In case of overflows in integer arithmetic, 1912all operations <em>wrap around</em>, 1913according to the usual rules of two-complement arithmetic. 1914(In other words, 1915they return the unique representable integer 1916that is equal modulo <em>2<sup>64</sup></em> to the mathematical result.) 1917 1918 1919 1920<h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p> 1921Lua supports the following bitwise operators: 1922 1923<ul> 1924<li><b><code>&</code>: </b>bitwise AND</li> 1925<li><b><code>|</code>: </b>bitwise OR</li> 1926<li><b><code>~</code>: </b>bitwise exclusive OR</li> 1927<li><b><code>>></code>: </b>right shift</li> 1928<li><b><code><<</code>: </b>left shift</li> 1929<li><b><code>~</code>: </b>unary bitwise NOT</li> 1930</ul> 1931 1932<p> 1933All bitwise operations convert its operands to integers 1934(see <a href="#3.4.3">§3.4.3</a>), 1935operate on all bits of those integers, 1936and result in an integer. 1937 1938 1939<p> 1940Both right and left shifts fill the vacant bits with zeros. 1941Negative displacements shift to the other direction; 1942displacements with absolute values equal to or higher than 1943the number of bits in an integer 1944result in zero (as all bits are shifted out). 1945 1946 1947 1948 1949 1950<h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p> 1951Lua provides some automatic conversions between some 1952types and representations at run time. 1953Bitwise operators always convert float operands to integers. 1954Exponentiation and float division 1955always convert integer operands to floats. 1956All other arithmetic operations applied to mixed numbers 1957(integers and floats) convert the integer operand to a float; 1958this is called the <em>usual rule</em>. 1959The C API also converts both integers to floats and 1960floats to integers, as needed. 1961Moreover, string concatenation accepts numbers as arguments, 1962besides strings. 1963 1964 1965<p> 1966Lua also converts strings to numbers, 1967whenever a number is expected. 1968 1969 1970<p> 1971In a conversion from integer to float, 1972if the integer value has an exact representation as a float, 1973that is the result. 1974Otherwise, 1975the conversion gets the nearest higher or 1976the nearest lower representable value. 1977This kind of conversion never fails. 1978 1979 1980<p> 1981The conversion from float to integer 1982checks whether the float has an exact representation as an integer 1983(that is, the float has an integral value and 1984it is in the range of integer representation). 1985If it does, that representation is the result. 1986Otherwise, the conversion fails. 1987 1988 1989<p> 1990The conversion from strings to numbers goes as follows: 1991First, the string is converted to an integer or a float, 1992following its syntax and the rules of the Lua lexer. 1993(The string may have also leading and trailing spaces and a sign.) 1994Then, the resulting number (float or integer) 1995is converted to the type (float or integer) required by the context 1996(e.g., the operation that forced the conversion). 1997 1998 1999<p> 2000All conversions from strings to numbers 2001accept both a dot and the current locale mark 2002as the radix character. 2003(The Lua lexer, however, accepts only a dot.) 2004 2005 2006<p> 2007The conversion from numbers to strings uses a 2008non-specified human-readable format. 2009For complete control over how numbers are converted to strings, 2010use the <code>format</code> function from the string library 2011(see <a href="#pdf-string.format"><code>string.format</code></a>). 2012 2013 2014 2015 2016 2017<h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p> 2018Lua supports the following relational operators: 2019 2020<ul> 2021<li><b><code>==</code>: </b>equality</li> 2022<li><b><code>~=</code>: </b>inequality</li> 2023<li><b><code><</code>: </b>less than</li> 2024<li><b><code>></code>: </b>greater than</li> 2025<li><b><code><=</code>: </b>less or equal</li> 2026<li><b><code>>=</code>: </b>greater or equal</li> 2027</ul><p> 2028These operators always result in <b>false</b> or <b>true</b>. 2029 2030 2031<p> 2032Equality (<code>==</code>) first compares the type of its operands. 2033If the types are different, then the result is <b>false</b>. 2034Otherwise, the values of the operands are compared. 2035Strings are compared in the obvious way. 2036Numbers are equal if they denote the same mathematical value. 2037 2038 2039<p> 2040Tables, userdata, and threads 2041are compared by reference: 2042two objects are considered equal only if they are the same object. 2043Every time you create a new object 2044(a table, userdata, or thread), 2045this new object is different from any previously existing object. 2046Closures with the same reference are always equal. 2047Closures with any detectable difference 2048(different behavior, different definition) are always different. 2049 2050 2051<p> 2052You can change the way that Lua compares tables and userdata 2053by using the "eq" metamethod (see <a href="#2.4">§2.4</a>). 2054 2055 2056<p> 2057Equality comparisons do not convert strings to numbers 2058or vice versa. 2059Thus, <code>"0"==0</code> evaluates to <b>false</b>, 2060and <code>t[0]</code> and <code>t["0"]</code> denote different 2061entries in a table. 2062 2063 2064<p> 2065The operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 2066 2067 2068<p> 2069The order operators work as follows. 2070If both arguments are numbers, 2071then they are compared according to their mathematical values 2072(regardless of their subtypes). 2073Otherwise, if both arguments are strings, 2074then their values are compared according to the current locale. 2075Otherwise, Lua tries to call the "lt" or the "le" 2076metamethod (see <a href="#2.4">§2.4</a>). 2077A comparison <code>a > b</code> is translated to <code>b < a</code> 2078and <code>a >= b</code> is translated to <code>b <= a</code>. 2079 2080 2081<p> 2082Following the IEEE 754 standard, 2083NaN is considered neither smaller than, 2084nor equal to, nor greater than any value (including itself). 2085 2086 2087 2088 2089 2090<h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p> 2091The logical operators in Lua are 2092<b>and</b>, <b>or</b>, and <b>not</b>. 2093Like the control structures (see <a href="#3.3.4">§3.3.4</a>), 2094all logical operators consider both <b>false</b> and <b>nil</b> as false 2095and anything else as true. 2096 2097 2098<p> 2099The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 2100The conjunction operator <b>and</b> returns its first argument 2101if this value is <b>false</b> or <b>nil</b>; 2102otherwise, <b>and</b> returns its second argument. 2103The disjunction operator <b>or</b> returns its first argument 2104if this value is different from <b>nil</b> and <b>false</b>; 2105otherwise, <b>or</b> returns its second argument. 2106Both <b>and</b> and <b>or</b> use short-circuit evaluation; 2107that is, 2108the second operand is evaluated only if necessary. 2109Here are some examples: 2110 2111<pre> 2112 10 or 20 --> 10 2113 10 or error() --> 10 2114 nil or "a" --> "a" 2115 nil and 10 --> nil 2116 false and error() --> false 2117 false and nil --> false 2118 false or nil --> nil 2119 10 and 20 --> 20 2120</pre><p> 2121(In this manual, 2122<code>--></code> indicates the result of the preceding expression.) 2123 2124 2125 2126 2127 2128<h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p> 2129The string concatenation operator in Lua is 2130denoted by two dots ('<code>..</code>'). 2131If both operands are strings or numbers, then they are converted to 2132strings according to the rules described in <a href="#3.4.3">§3.4.3</a>. 2133Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). 2134 2135 2136 2137 2138 2139<h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3> 2140 2141<p> 2142The length operator is denoted by the unary prefix operator <code>#</code>. 2143The length of a string is its number of bytes 2144(that is, the usual meaning of string length when each 2145character is one byte). 2146 2147 2148<p> 2149A program can modify the behavior of the length operator for 2150any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>). 2151 2152 2153<p> 2154Unless a <code>__len</code> metamethod is given, 2155the length of a table <code>t</code> is only defined if the 2156table is a <em>sequence</em>, 2157that is, 2158the set of its positive numeric keys is equal to <em>{1..n}</em> 2159for some non-negative integer <em>n</em>. 2160In that case, <em>n</em> is its length. 2161Note that a table like 2162 2163<pre> 2164 {10, 20, nil, 40} 2165</pre><p> 2166is not a sequence, because it has the key <code>4</code> 2167but does not have the key <code>3</code>. 2168(So, there is no <em>n</em> such that the set <em>{1..n}</em> is equal 2169to the set of positive numeric keys of that table.) 2170Note, however, that non-numeric keys do not interfere 2171with whether a table is a sequence. 2172 2173 2174 2175 2176 2177<h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p> 2178Operator precedence in Lua follows the table below, 2179from lower to higher priority: 2180 2181<pre> 2182 or 2183 and 2184 < > <= >= ~= == 2185 | 2186 ~ 2187 & 2188 << >> 2189 .. 2190 + - 2191 * / // % 2192 unary operators (not # - ~) 2193 ^ 2194</pre><p> 2195As usual, 2196you can use parentheses to change the precedences of an expression. 2197The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 2198operators are right associative. 2199All other binary operators are left associative. 2200 2201 2202 2203 2204 2205<h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p> 2206Table constructors are expressions that create tables. 2207Every time a constructor is evaluated, a new table is created. 2208A constructor can be used to create an empty table 2209or to create a table and initialize some of its fields. 2210The general syntax for constructors is 2211 2212<pre> 2213 tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 2214 fieldlist ::= field {fieldsep field} [fieldsep] 2215 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 2216 fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 2217</pre> 2218 2219<p> 2220Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry 2221with key <code>exp1</code> and value <code>exp2</code>. 2222A field of the form <code>name = exp</code> is equivalent to 2223<code>["name"] = exp</code>. 2224Finally, fields of the form <code>exp</code> are equivalent to 2225<code>[i] = exp</code>, where <code>i</code> are consecutive integers 2226starting with 1. 2227Fields in the other formats do not affect this counting. 2228For example, 2229 2230<pre> 2231 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 2232</pre><p> 2233is equivalent to 2234 2235<pre> 2236 do 2237 local t = {} 2238 t[f(1)] = g 2239 t[1] = "x" -- 1st exp 2240 t[2] = "y" -- 2nd exp 2241 t.x = 1 -- t["x"] = 1 2242 t[3] = f(x) -- 3rd exp 2243 t[30] = 23 2244 t[4] = 45 -- 4th exp 2245 a = t 2246 end 2247</pre> 2248 2249<p> 2250The order of the assignments in a constructor is undefined. 2251(This order would be relevant only when there are repeated keys.) 2252 2253 2254<p> 2255If the last field in the list has the form <code>exp</code> 2256and the expression is a function call or a vararg expression, 2257then all values returned by this expression enter the list consecutively 2258(see <a href="#3.4.10">§3.4.10</a>). 2259 2260 2261<p> 2262The field list can have an optional trailing separator, 2263as a convenience for machine-generated code. 2264 2265 2266 2267 2268 2269<h3>3.4.10 – <a name="3.4.10">Function Calls</a></h3><p> 2270A function call in Lua has the following syntax: 2271 2272<pre> 2273 functioncall ::= prefixexp args 2274</pre><p> 2275In a function call, 2276first prefixexp and args are evaluated. 2277If the value of prefixexp has type <em>function</em>, 2278then this function is called 2279with the given arguments. 2280Otherwise, the prefixexp "call" metamethod is called, 2281having as first parameter the value of prefixexp, 2282followed by the original call arguments 2283(see <a href="#2.4">§2.4</a>). 2284 2285 2286<p> 2287The form 2288 2289<pre> 2290 functioncall ::= prefixexp ‘<b>:</b>’ Name args 2291</pre><p> 2292can be used to call "methods". 2293A call <code>v:name(<em>args</em>)</code> 2294is syntactic sugar for <code>v.name(v,<em>args</em>)</code>, 2295except that <code>v</code> is evaluated only once. 2296 2297 2298<p> 2299Arguments have the following syntax: 2300 2301<pre> 2302 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ 2303 args ::= tableconstructor 2304 args ::= LiteralString 2305</pre><p> 2306All argument expressions are evaluated before the call. 2307A call of the form <code>f{<em>fields</em>}</code> is 2308syntactic sugar for <code>f({<em>fields</em>})</code>; 2309that is, the argument list is a single new table. 2310A call of the form <code>f'<em>string</em>'</code> 2311(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 2312is syntactic sugar for <code>f('<em>string</em>')</code>; 2313that is, the argument list is a single literal string. 2314 2315 2316<p> 2317A call of the form <code>return <em>functioncall</em></code> is called 2318a <em>tail call</em>. 2319Lua implements <em>proper tail calls</em> 2320(or <em>proper tail recursion</em>): 2321in a tail call, 2322the called function reuses the stack entry of the calling function. 2323Therefore, there is no limit on the number of nested tail calls that 2324a program can execute. 2325However, a tail call erases any debug information about the 2326calling function. 2327Note that a tail call only happens with a particular syntax, 2328where the <b>return</b> has one single function call as argument; 2329this syntax makes the calling function return exactly 2330the returns of the called function. 2331So, none of the following examples are tail calls: 2332 2333<pre> 2334 return (f(x)) -- results adjusted to 1 2335 return 2 * f(x) 2336 return x, f(x) -- additional results 2337 f(x); return -- results discarded 2338 return x or f(x) -- results adjusted to 1 2339</pre> 2340 2341 2342 2343 2344<h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3> 2345 2346<p> 2347The syntax for function definition is 2348 2349<pre> 2350 functiondef ::= <b>function</b> funcbody 2351 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 2352</pre> 2353 2354<p> 2355The following syntactic sugar simplifies function definitions: 2356 2357<pre> 2358 stat ::= <b>function</b> funcname funcbody 2359 stat ::= <b>local</b> <b>function</b> Name funcbody 2360 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 2361</pre><p> 2362The statement 2363 2364<pre> 2365 function f () <em>body</em> end 2366</pre><p> 2367translates to 2368 2369<pre> 2370 f = function () <em>body</em> end 2371</pre><p> 2372The statement 2373 2374<pre> 2375 function t.a.b.c.f () <em>body</em> end 2376</pre><p> 2377translates to 2378 2379<pre> 2380 t.a.b.c.f = function () <em>body</em> end 2381</pre><p> 2382The statement 2383 2384<pre> 2385 local function f () <em>body</em> end 2386</pre><p> 2387translates to 2388 2389<pre> 2390 local f; f = function () <em>body</em> end 2391</pre><p> 2392not to 2393 2394<pre> 2395 local f = function () <em>body</em> end 2396</pre><p> 2397(This only makes a difference when the body of the function 2398contains references to <code>f</code>.) 2399 2400 2401<p> 2402A function definition is an executable expression, 2403whose value has type <em>function</em>. 2404When Lua precompiles a chunk, 2405all its function bodies are precompiled too. 2406Then, whenever Lua executes the function definition, 2407the function is <em>instantiated</em> (or <em>closed</em>). 2408This function instance (or <em>closure</em>) 2409is the final value of the expression. 2410 2411 2412<p> 2413Parameters act as local variables that are 2414initialized with the argument values: 2415 2416<pre> 2417 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 2418</pre><p> 2419When a function is called, 2420the list of arguments is adjusted to 2421the length of the list of parameters, 2422unless the function is a <em>vararg function</em>, 2423which is indicated by three dots ('<code>...</code>') 2424at the end of its parameter list. 2425A vararg function does not adjust its argument list; 2426instead, it collects all extra arguments and supplies them 2427to the function through a <em>vararg expression</em>, 2428which is also written as three dots. 2429The value of this expression is a list of all actual extra arguments, 2430similar to a function with multiple results. 2431If a vararg expression is used inside another expression 2432or in the middle of a list of expressions, 2433then its return list is adjusted to one element. 2434If the expression is used as the last element of a list of expressions, 2435then no adjustment is made 2436(unless that last expression is enclosed in parentheses). 2437 2438 2439<p> 2440As an example, consider the following definitions: 2441 2442<pre> 2443 function f(a, b) end 2444 function g(a, b, ...) end 2445 function r() return 1,2,3 end 2446</pre><p> 2447Then, we have the following mapping from arguments to parameters and 2448to the vararg expression: 2449 2450<pre> 2451 CALL PARAMETERS 2452 2453 f(3) a=3, b=nil 2454 f(3, 4) a=3, b=4 2455 f(3, 4, 5) a=3, b=4 2456 f(r(), 10) a=1, b=10 2457 f(r()) a=1, b=2 2458 2459 g(3) a=3, b=nil, ... --> (nothing) 2460 g(3, 4) a=3, b=4, ... --> (nothing) 2461 g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 2462 g(5, r()) a=5, b=1, ... --> 2 3 2463</pre> 2464 2465<p> 2466Results are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>). 2467If control reaches the end of a function 2468without encountering a <b>return</b> statement, 2469then the function returns with no results. 2470 2471 2472<p> 2473 2474There is a system-dependent limit on the number of values 2475that a function may return. 2476This limit is guaranteed to be larger than 1000. 2477 2478 2479<p> 2480The <em>colon</em> syntax 2481is used for defining <em>methods</em>, 2482that is, functions that have an implicit extra parameter <code>self</code>. 2483Thus, the statement 2484 2485<pre> 2486 function t.a.b.c:f (<em>params</em>) <em>body</em> end 2487</pre><p> 2488is syntactic sugar for 2489 2490<pre> 2491 t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end 2492</pre> 2493 2494 2495 2496 2497 2498 2499<h2>3.5 – <a name="3.5">Visibility Rules</a></h2> 2500 2501<p> 2502 2503Lua is a lexically scoped language. 2504The scope of a local variable begins at the first statement after 2505its declaration and lasts until the last non-void statement 2506of the innermost block that includes the declaration. 2507Consider the following example: 2508 2509<pre> 2510 x = 10 -- global variable 2511 do -- new block 2512 local x = x -- new 'x', with value 10 2513 print(x) --> 10 2514 x = x+1 2515 do -- another block 2516 local x = x+1 -- another 'x' 2517 print(x) --> 12 2518 end 2519 print(x) --> 11 2520 end 2521 print(x) --> 10 (the global one) 2522</pre> 2523 2524<p> 2525Notice that, in a declaration like <code>local x = x</code>, 2526the new <code>x</code> being declared is not in scope yet, 2527and so the second <code>x</code> refers to the outside variable. 2528 2529 2530<p> 2531Because of the lexical scoping rules, 2532local variables can be freely accessed by functions 2533defined inside their scope. 2534A local variable used by an inner function is called 2535an <em>upvalue</em>, or <em>external local variable</em>, 2536inside the inner function. 2537 2538 2539<p> 2540Notice that each execution of a <b>local</b> statement 2541defines new local variables. 2542Consider the following example: 2543 2544<pre> 2545 a = {} 2546 local x = 20 2547 for i=1,10 do 2548 local y = 0 2549 a[i] = function () y=y+1; return x+y end 2550 end 2551</pre><p> 2552The loop creates ten closures 2553(that is, ten instances of the anonymous function). 2554Each of these closures uses a different <code>y</code> variable, 2555while all of them share the same <code>x</code>. 2556 2557 2558 2559 2560 2561<h1>4 – <a name="4">The Application Program Interface</a></h1> 2562 2563<p> 2564 2565This section describes the C API for Lua, that is, 2566the set of C functions available to the host program to communicate 2567with Lua. 2568All API functions and related types and constants 2569are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. 2570 2571 2572<p> 2573Even when we use the term "function", 2574any facility in the API may be provided as a macro instead. 2575Except where stated otherwise, 2576all such macros use each of their arguments exactly once 2577(except for the first argument, which is always a Lua state), 2578and so do not generate any hidden side-effects. 2579 2580 2581<p> 2582As in most C libraries, 2583the Lua API functions do not check their arguments for validity or consistency. 2584However, you can change this behavior by compiling Lua 2585with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined. 2586 2587 2588 2589<h2>4.1 – <a name="4.1">The Stack</a></h2> 2590 2591<p> 2592Lua uses a <em>virtual stack</em> to pass values to and from C. 2593Each element in this stack represents a Lua value 2594(<b>nil</b>, number, string, etc.). 2595 2596 2597<p> 2598Whenever Lua calls C, the called function gets a new stack, 2599which is independent of previous stacks and of stacks of 2600C functions that are still active. 2601This stack initially contains any arguments to the C function 2602and it is where the C function pushes its results 2603to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 2604 2605 2606<p> 2607For convenience, 2608most query operations in the API do not follow a strict stack discipline. 2609Instead, they can refer to any element in the stack 2610by using an <em>index</em>: 2611A positive index represents an absolute stack position 2612(starting at 1); 2613a negative index represents an offset relative to the top of the stack. 2614More specifically, if the stack has <em>n</em> elements, 2615then index 1 represents the first element 2616(that is, the element that was pushed onto the stack first) 2617and 2618index <em>n</em> represents the last element; 2619index -1 also represents the last element 2620(that is, the element at the top) 2621and index <em>-n</em> represents the first element. 2622 2623 2624 2625 2626 2627<h2>4.2 – <a name="4.2">Stack Size</a></h2> 2628 2629<p> 2630When you interact with the Lua API, 2631you are responsible for ensuring consistency. 2632In particular, 2633<em>you are responsible for controlling stack overflow</em>. 2634You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> 2635to ensure that the stack has enough space for pushing new elements. 2636 2637 2638<p> 2639Whenever Lua calls C, 2640it ensures that the stack has space for 2641at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots. 2642<code>LUA_MINSTACK</code> is defined as 20, 2643so that usually you do not have to worry about stack space 2644unless your code has loops pushing elements onto the stack. 2645 2646 2647<p> 2648When you call a Lua function 2649without a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>), 2650Lua ensures that the stack has enough space for all results, 2651but it does not ensure any extra space. 2652So, before pushing anything in the stack after such a call 2653you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>. 2654 2655 2656 2657 2658 2659<h2>4.3 – <a name="4.3">Valid and Acceptable Indices</a></h2> 2660 2661<p> 2662Any function in the API that receives stack indices 2663works only with <em>valid indices</em> or <em>acceptable indices</em>. 2664 2665 2666<p> 2667A <em>valid index</em> is an index that refers to a 2668position that stores a modifiable Lua value. 2669It comprises stack indices between 1 and the stack top 2670(<code>1 ≤ abs(index) ≤ top</code>) 2671 2672plus <em>pseudo-indices</em>, 2673which represent some positions that are accessible to C code 2674but that are not in the stack. 2675Pseudo-indices are used to access the registry (see <a href="#4.5">§4.5</a>) 2676and the upvalues of a C function (see <a href="#4.4">§4.4</a>). 2677 2678 2679<p> 2680Functions that do not need a specific mutable position, 2681but only a value (e.g., query functions), 2682can be called with acceptable indices. 2683An <em>acceptable index</em> can be any valid index, 2684but it also can be any positive index after the stack top 2685within the space allocated for the stack, 2686that is, indices up to the stack size. 2687(Note that 0 is never an acceptable index.) 2688Except when noted otherwise, 2689functions in the API work with acceptable indices. 2690 2691 2692<p> 2693Acceptable indices serve to avoid extra tests 2694against the stack top when querying the stack. 2695For instance, a C function can query its third argument 2696without the need to first check whether there is a third argument, 2697that is, without the need to check whether 3 is a valid index. 2698 2699 2700<p> 2701For functions that can be called with acceptable indices, 2702any non-valid index is treated as if it 2703contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>, 2704which behaves like a nil value. 2705 2706 2707 2708 2709 2710<h2>4.4 – <a name="4.4">C Closures</a></h2> 2711 2712<p> 2713When a C function is created, 2714it is possible to associate some values with it, 2715thus creating a <em>C closure</em> 2716(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>); 2717these values are called <em>upvalues</em> and are 2718accessible to the function whenever it is called. 2719 2720 2721<p> 2722Whenever a C function is called, 2723its upvalues are located at specific pseudo-indices. 2724These pseudo-indices are produced by the macro 2725<a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>. 2726The first upvalue associated with a function is at index 2727<code>lua_upvalueindex(1)</code>, and so on. 2728Any access to <code>lua_upvalueindex(<em>n</em>)</code>, 2729where <em>n</em> is greater than the number of upvalues of the 2730current function 2731(but not greater than 256, 2732which is one plus the maximum number of upvalues in a closure), 2733produces an acceptable but invalid index. 2734 2735 2736 2737 2738 2739<h2>4.5 – <a name="4.5">Registry</a></h2> 2740 2741<p> 2742Lua provides a <em>registry</em>, 2743a predefined table that can be used by any C code to 2744store whatever Lua values it needs to store. 2745The registry table is always located at pseudo-index 2746<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. 2747Any C library can store data into this table, 2748but it must take care to choose keys 2749that are different from those used 2750by other libraries, to avoid collisions. 2751Typically, you should use as key a string containing your library name, 2752or a light userdata with the address of a C object in your code, 2753or any Lua object created by your code. 2754As with variable names, 2755string keys starting with an underscore followed by 2756uppercase letters are reserved for Lua. 2757 2758 2759<p> 2760The integer keys in the registry are used 2761by the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>) 2762and by some predefined values. 2763Therefore, integer keys must not be used for other purposes. 2764 2765 2766<p> 2767When you create a new Lua state, 2768its registry comes with some predefined values. 2769These predefined values are indexed with integer keys 2770defined as constants in <code>lua.h</code>. 2771The following constants are defined: 2772 2773<ul> 2774<li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has 2775the main thread of the state. 2776(The main thread is the one created together with the state.) 2777</li> 2778 2779<li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has 2780the global environment. 2781</li> 2782</ul> 2783 2784 2785 2786 2787<h2>4.6 – <a name="4.6">Error Handling in C</a></h2> 2788 2789<p> 2790Internally, Lua uses the C <code>longjmp</code> facility to handle errors. 2791(Lua will use exceptions if you compile it as C++; 2792search for <code>LUAI_THROW</code> in the source code for details.) 2793When Lua faces any error 2794(such as a memory allocation error, type errors, syntax errors, 2795and runtime errors) 2796it <em>raises</em> an error; 2797that is, it does a long jump. 2798A <em>protected environment</em> uses <code>setjmp</code> 2799to set a recovery point; 2800any error jumps to the most recent active recovery point. 2801 2802 2803<p> 2804If an error happens outside any protected environment, 2805Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) 2806and then calls <code>abort</code>, 2807thus exiting the host application. 2808Your panic function can avoid this exit by 2809never returning 2810(e.g., doing a long jump to your own recovery point outside Lua). 2811 2812 2813<p> 2814The panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>); 2815in particular, the error object is at the top of the stack. 2816However, there is no guarantee about stack space. 2817To push anything on the stack, 2818the panic function must first check the available space (see <a href="#4.2">§4.2</a>). 2819 2820 2821<p> 2822Most functions in the API can raise an error, 2823for instance due to a memory allocation error. 2824The documentation for each function indicates whether 2825it can raise errors. 2826 2827 2828<p> 2829Inside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>. 2830 2831 2832 2833 2834 2835<h2>4.7 – <a name="4.7">Handling Yields in C</a></h2> 2836 2837<p> 2838Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine. 2839Therefore, if a C function <code>foo</code> calls an API function 2840and this API function yields 2841(directly or indirectly by calling another function that yields), 2842Lua cannot return to <code>foo</code> any more, 2843because the <code>longjmp</code> removes its frame from the C stack. 2844 2845 2846<p> 2847To avoid this kind of problem, 2848Lua raises an error whenever it tries to yield across an API call, 2849except for three functions: 2850<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>. 2851All those functions receive a <em>continuation function</em> 2852(as a parameter named <code>k</code>) to continue execution after a yield. 2853 2854 2855<p> 2856We need to set some terminology to explain continuations. 2857We have a C function called from Lua which we will call 2858the <em>original function</em>. 2859This original function then calls one of those three functions in the C API, 2860which we will call the <em>callee function</em>, 2861that then yields the current thread. 2862(This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 2863or 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> 2864and the function called by them yields.) 2865 2866 2867<p> 2868Suppose the running thread yields while executing the callee function. 2869After the thread resumes, 2870it eventually will finish running the callee function. 2871However, 2872the callee function cannot return to the original function, 2873because its frame in the C stack was destroyed by the yield. 2874Instead, Lua calls a <em>continuation function</em>, 2875which was given as an argument to the callee function. 2876As the name implies, 2877the continuation function should continue the task 2878of the original function. 2879 2880 2881<p> 2882As an illustration, consider the following function: 2883 2884<pre> 2885 int original_function (lua_State *L) { 2886 ... /* code 1 */ 2887 status = lua_pcall(L, n, m, h); /* calls Lua */ 2888 ... /* code 2 */ 2889 } 2890</pre><p> 2891Now we want to allow 2892the Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield. 2893First, we can rewrite our function like here: 2894 2895<pre> 2896 int k (lua_State *L, int status, lua_KContext ctx) { 2897 ... /* code 2 */ 2898 } 2899 2900 int original_function (lua_State *L) { 2901 ... /* code 1 */ 2902 return k(L, lua_pcall(L, n, m, h), ctx); 2903 } 2904</pre><p> 2905In the above code, 2906the new function <code>k</code> is a 2907<em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>), 2908which should do all the work that the original function 2909was doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>. 2910Now, we must inform Lua that it must call <code>k</code> if the Lua code 2911being executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way 2912(errors or yielding), 2913so we rewrite the code as here, 2914replacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>: 2915 2916<pre> 2917 int original_function (lua_State *L) { 2918 ... /* code 1 */ 2919 return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1); 2920 } 2921</pre><p> 2922Note the external, explicit call to the continuation: 2923Lua will call the continuation only if needed, that is, 2924in case of errors or resuming after a yield. 2925If the called function returns normally without ever yielding, 2926<a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally. 2927(Of course, instead of calling the continuation in that case, 2928you can do the equivalent work directly inside the original function.) 2929 2930 2931<p> 2932Besides the Lua state, 2933the continuation function has two other parameters: 2934the final status of the call plus the context value (<code>ctx</code>) that 2935was passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>. 2936(Lua does not use this context value; 2937it only passes this value from the original function to the 2938continuation function.) 2939For <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 2940the status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 2941except that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield 2942(instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>). 2943For <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>, 2944the status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation. 2945(For these two functions, 2946Lua will not call the continuation in case of errors, 2947because they do not handle errors.) 2948Similarly, when using <a href="#lua_callk"><code>lua_callk</code></a>, 2949you should call the continuation function 2950with <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status. 2951(For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling 2952directly the continuation function, 2953because <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.) 2954 2955 2956<p> 2957Lua treats the continuation function as if it were the original function. 2958The continuation function receives the same Lua stack 2959from the original function, 2960in the same state it would be if the callee function had returned. 2961(For instance, 2962after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are 2963removed from the stack and replaced by the results from the call.) 2964It also has the same upvalues. 2965Whatever it returns is handled by Lua as if it were the return 2966of the original function. 2967 2968 2969 2970 2971 2972<h2>4.8 – <a name="4.8">Functions and Types</a></h2> 2973 2974<p> 2975Here we list all functions and types from the C API in 2976alphabetical order. 2977Each function has an indicator like this: 2978<span class="apii">[-o, +p, <em>x</em>]</span> 2979 2980 2981<p> 2982The first field, <code>o</code>, 2983is how many elements the function pops from the stack. 2984The second field, <code>p</code>, 2985is how many elements the function pushes onto the stack. 2986(Any function always pushes its results after popping its arguments.) 2987A field in the form <code>x|y</code> means the function can push (or pop) 2988<code>x</code> or <code>y</code> elements, 2989depending on the situation; 2990an interrogation mark '<code>?</code>' means that 2991we cannot know how many elements the function pops/pushes 2992by looking only at its arguments 2993(e.g., they may depend on what is on the stack). 2994The third field, <code>x</code>, 2995tells whether the function may raise errors: 2996'<code>-</code>' means the function never raises any error; 2997'<code>m</code>' means the function may raise out-of-memory errors 2998and errors running a <code>__gc</code> metamethod; 2999'<code>e</code>' means the function may raise any errors 3000(it can run arbitrary Lua code, 3001either directly or through metamethods); 3002'<code>v</code>' means the function may raise an error on purpose. 3003 3004 3005 3006<hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p> 3007<span class="apii">[-0, +0, –]</span> 3008<pre>int lua_absindex (lua_State *L, int idx);</pre> 3009 3010<p> 3011Converts the acceptable index <code>idx</code> 3012into an equivalent absolute index 3013(that is, one that does not depend on the stack top). 3014 3015 3016 3017 3018 3019<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> 3020<pre>typedef void * (*lua_Alloc) (void *ud, 3021 void *ptr, 3022 size_t osize, 3023 size_t nsize);</pre> 3024 3025<p> 3026The type of the memory-allocation function used by Lua states. 3027The allocator function must provide a 3028functionality similar to <code>realloc</code>, 3029but not exactly the same. 3030Its arguments are 3031<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; 3032<code>ptr</code>, a pointer to the block being allocated/reallocated/freed; 3033<code>osize</code>, the original size of the block or some code about what 3034is being allocated; 3035and <code>nsize</code>, the new size of the block. 3036 3037 3038<p> 3039When <code>ptr</code> is not <code>NULL</code>, 3040<code>osize</code> is the size of the block pointed by <code>ptr</code>, 3041that is, the size given when it was allocated or reallocated. 3042 3043 3044<p> 3045When <code>ptr</code> is <code>NULL</code>, 3046<code>osize</code> encodes the kind of object that Lua is allocating. 3047<code>osize</code> is any of 3048<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>, 3049<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) 3050Lua is creating a new object of that type. 3051When <code>osize</code> is some other value, 3052Lua is allocating memory for something else. 3053 3054 3055<p> 3056Lua assumes the following behavior from the allocator function: 3057 3058 3059<p> 3060When <code>nsize</code> is zero, 3061the allocator must behave like <code>free</code> 3062and return <code>NULL</code>. 3063 3064 3065<p> 3066When <code>nsize</code> is not zero, 3067the allocator must behave like <code>realloc</code>. 3068The allocator returns <code>NULL</code> 3069if and only if it cannot fulfill the request. 3070Lua assumes that the allocator never fails when 3071<code>osize >= nsize</code>. 3072 3073 3074<p> 3075Here is a simple implementation for the allocator function. 3076It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. 3077 3078<pre> 3079 static void *l_alloc (void *ud, void *ptr, size_t osize, 3080 size_t nsize) { 3081 (void)ud; (void)osize; /* not used */ 3082 if (nsize == 0) { 3083 free(ptr); 3084 return NULL; 3085 } 3086 else 3087 return realloc(ptr, nsize); 3088 } 3089</pre><p> 3090Note that Standard C ensures 3091that <code>free(NULL)</code> has no effect and that 3092<code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>. 3093This code assumes that <code>realloc</code> does not fail when shrinking a block. 3094(Although Standard C does not ensure this behavior, 3095it seems to be a safe assumption.) 3096 3097 3098 3099 3100 3101<hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p> 3102<span class="apii">[-(2|1), +1, <em>e</em>]</span> 3103<pre>void lua_arith (lua_State *L, int op);</pre> 3104 3105<p> 3106Performs an arithmetic or bitwise operation over the two values 3107(or one, in the case of negations) 3108at the top of the stack, 3109with the value at the top being the second operand, 3110pops these values, and pushes the result of the operation. 3111The function follows the semantics of the corresponding Lua operator 3112(that is, it may call metamethods). 3113 3114 3115<p> 3116The value of <code>op</code> must be one of the following constants: 3117 3118<ul> 3119 3120<li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li> 3121<li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li> 3122<li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li> 3123<li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li> 3124<li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li> 3125<li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li> 3126<li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li> 3127<li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li> 3128<li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li> 3129<li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&</code>)</li> 3130<li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li> 3131<li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li> 3132<li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li> 3133<li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li> 3134 3135</ul> 3136 3137 3138 3139 3140<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> 3141<span class="apii">[-0, +0, –]</span> 3142<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> 3143 3144<p> 3145Sets a new panic function and returns the old one (see <a href="#4.6">§4.6</a>). 3146 3147 3148 3149 3150 3151<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> 3152<span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span> 3153<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> 3154 3155<p> 3156Calls a function. 3157 3158 3159<p> 3160To call a function you must use the following protocol: 3161first, the function to be called is pushed onto the stack; 3162then, the arguments to the function are pushed 3163in direct order; 3164that is, the first argument is pushed first. 3165Finally you call <a href="#lua_call"><code>lua_call</code></a>; 3166<code>nargs</code> is the number of arguments that you pushed onto the stack. 3167All arguments and the function value are popped from the stack 3168when the function is called. 3169The function results are pushed onto the stack when the function returns. 3170The number of results is adjusted to <code>nresults</code>, 3171unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. 3172In this case, all results from the function are pushed. 3173Lua takes care that the returned values fit into the stack space, 3174but it does not ensure any extra space in the stack. 3175The function results are pushed onto the stack in direct order 3176(the first result is pushed first), 3177so that after the call the last result is on the top of the stack. 3178 3179 3180<p> 3181Any error inside the called function is propagated upwards 3182(with a <code>longjmp</code>). 3183 3184 3185<p> 3186The following example shows how the host program can do the 3187equivalent to this Lua code: 3188 3189<pre> 3190 a = f("how", t.x, 14) 3191</pre><p> 3192Here it is in C: 3193 3194<pre> 3195 lua_getglobal(L, "f"); /* function to be called */ 3196 lua_pushliteral(L, "how"); /* 1st argument */ 3197 lua_getglobal(L, "t"); /* table to be indexed */ 3198 lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 3199 lua_remove(L, -2); /* remove 't' from the stack */ 3200 lua_pushinteger(L, 14); /* 3rd argument */ 3201 lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ 3202 lua_setglobal(L, "a"); /* set global 'a' */ 3203</pre><p> 3204Note that the code above is <em>balanced</em>: 3205at its end, the stack is back to its original configuration. 3206This is considered good programming practice. 3207 3208 3209 3210 3211 3212<hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p> 3213<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> 3214<pre>void lua_callk (lua_State *L, 3215 int nargs, 3216 int nresults, 3217 lua_KContext ctx, 3218 lua_KFunction k);</pre> 3219 3220<p> 3221This function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>, 3222but allows the called function to yield (see <a href="#4.7">§4.7</a>). 3223 3224 3225 3226 3227 3228<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> 3229<pre>typedef int (*lua_CFunction) (lua_State *L);</pre> 3230 3231<p> 3232Type for C functions. 3233 3234 3235<p> 3236In order to communicate properly with Lua, 3237a C function must use the following protocol, 3238which defines the way parameters and results are passed: 3239a C function receives its arguments from Lua in its stack 3240in direct order (the first argument is pushed first). 3241So, when the function starts, 3242<code>lua_gettop(L)</code> returns the number of arguments received by the function. 3243The first argument (if any) is at index 1 3244and its last argument is at index <code>lua_gettop(L)</code>. 3245To return values to Lua, a C function just pushes them onto the stack, 3246in direct order (the first result is pushed first), 3247and returns the number of results. 3248Any other value in the stack below the results will be properly 3249discarded by Lua. 3250Like a Lua function, a C function called by Lua can also return 3251many results. 3252 3253 3254<p> 3255As an example, the following function receives a variable number 3256of numeric arguments and returns their average and their sum: 3257 3258<pre> 3259 static int foo (lua_State *L) { 3260 int n = lua_gettop(L); /* number of arguments */ 3261 lua_Number sum = 0.0; 3262 int i; 3263 for (i = 1; i <= n; i++) { 3264 if (!lua_isnumber(L, i)) { 3265 lua_pushliteral(L, "incorrect argument"); 3266 lua_error(L); 3267 } 3268 sum += lua_tonumber(L, i); 3269 } 3270 lua_pushnumber(L, sum/n); /* first result */ 3271 lua_pushnumber(L, sum); /* second result */ 3272 return 2; /* number of results */ 3273 } 3274</pre> 3275 3276 3277 3278 3279<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> 3280<span class="apii">[-0, +0, –]</span> 3281<pre>int lua_checkstack (lua_State *L, int n);</pre> 3282 3283<p> 3284Ensures that the stack has space for at least <code>n</code> extra slots 3285(that is, that you can safely push up to <code>n</code> values into it). 3286It returns false if it cannot fulfill the request, 3287either because it would cause the stack 3288to be larger than a fixed maximum size 3289(typically at least several thousand elements) or 3290because it cannot allocate memory for the extra space. 3291This function never shrinks the stack; 3292if the stack already has space for the extra slots, 3293it is left unchanged. 3294 3295 3296 3297 3298 3299<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> 3300<span class="apii">[-0, +0, –]</span> 3301<pre>void lua_close (lua_State *L);</pre> 3302 3303<p> 3304Destroys all objects in the given Lua state 3305(calling the corresponding garbage-collection metamethods, if any) 3306and frees all dynamic memory used by this state. 3307On several platforms, you may not need to call this function, 3308because all resources are naturally released when the host program ends. 3309On the other hand, long-running programs that create multiple states, 3310such as daemons or web servers, 3311will probably need to close states as soon as they are not needed. 3312 3313 3314 3315 3316 3317<hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p> 3318<span class="apii">[-0, +0, <em>e</em>]</span> 3319<pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre> 3320 3321<p> 3322Compares two Lua values. 3323Returns 1 if the value at index <code>index1</code> satisfies <code>op</code> 3324when compared with the value at index <code>index2</code>, 3325following the semantics of the corresponding Lua operator 3326(that is, it may call metamethods). 3327Otherwise returns 0. 3328Also returns 0 if any of the indices is not valid. 3329 3330 3331<p> 3332The value of <code>op</code> must be one of the following constants: 3333 3334<ul> 3335 3336<li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li> 3337<li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li> 3338<li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li> 3339 3340</ul> 3341 3342 3343 3344 3345<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> 3346<span class="apii">[-n, +1, <em>e</em>]</span> 3347<pre>void lua_concat (lua_State *L, int n);</pre> 3348 3349<p> 3350Concatenates the <code>n</code> values at the top of the stack, 3351pops them, and leaves the result at the top. 3352If <code>n</code> is 1, the result is the single value on the stack 3353(that is, the function does nothing); 3354if <code>n</code> is 0, the result is the empty string. 3355Concatenation is performed following the usual semantics of Lua 3356(see <a href="#3.4.6">§3.4.6</a>). 3357 3358 3359 3360 3361 3362<hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p> 3363<span class="apii">[-0, +0, –]</span> 3364<pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre> 3365 3366<p> 3367Copies the element at index <code>fromidx</code> 3368into the valid index <code>toidx</code>, 3369replacing the value at that position. 3370Values at other positions are not affected. 3371 3372 3373 3374 3375 3376<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> 3377<span class="apii">[-0, +1, <em>m</em>]</span> 3378<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> 3379 3380<p> 3381Creates a new empty table and pushes it onto the stack. 3382Parameter <code>narr</code> is a hint for how many elements the table 3383will have as a sequence; 3384parameter <code>nrec</code> is a hint for how many other elements 3385the table will have. 3386Lua may use these hints to preallocate memory for the new table. 3387This preallocation is useful for performance when you know in advance 3388how many elements the table will have. 3389Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. 3390 3391 3392 3393 3394 3395<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> 3396<span class="apii">[-0, +0, –]</span> 3397<pre>int lua_dump (lua_State *L, 3398 lua_Writer writer, 3399 void *data, 3400 int strip);</pre> 3401 3402<p> 3403Dumps a function as a binary chunk. 3404Receives a Lua function on the top of the stack 3405and produces a binary chunk that, 3406if loaded again, 3407results in a function equivalent to the one dumped. 3408As it produces parts of the chunk, 3409<a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>) 3410with the given <code>data</code> 3411to write them. 3412 3413 3414<p> 3415If <code>strip</code> is true, 3416the binary representation may not include all debug information 3417about the function, 3418to save space. 3419 3420 3421<p> 3422The value returned is the error code returned by the last 3423call to the writer; 34240 means no errors. 3425 3426 3427<p> 3428This function does not pop the Lua function from the stack. 3429 3430 3431 3432 3433 3434<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> 3435<span class="apii">[-1, +0, <em>v</em>]</span> 3436<pre>int lua_error (lua_State *L);</pre> 3437 3438<p> 3439Generates a Lua error, 3440using the value at the top of the stack as the error object. 3441This function does a long jump, 3442and therefore never returns 3443(see <a href="#luaL_error"><code>luaL_error</code></a>). 3444 3445 3446 3447 3448 3449<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> 3450<span class="apii">[-0, +0, <em>m</em>]</span> 3451<pre>int lua_gc (lua_State *L, int what, int data);</pre> 3452 3453<p> 3454Controls the garbage collector. 3455 3456 3457<p> 3458This function performs several tasks, 3459according to the value of the parameter <code>what</code>: 3460 3461<ul> 3462 3463<li><b><code>LUA_GCSTOP</code>: </b> 3464stops the garbage collector. 3465</li> 3466 3467<li><b><code>LUA_GCRESTART</code>: </b> 3468restarts the garbage collector. 3469</li> 3470 3471<li><b><code>LUA_GCCOLLECT</code>: </b> 3472performs a full garbage-collection cycle. 3473</li> 3474 3475<li><b><code>LUA_GCCOUNT</code>: </b> 3476returns the current amount of memory (in Kbytes) in use by Lua. 3477</li> 3478 3479<li><b><code>LUA_GCCOUNTB</code>: </b> 3480returns the remainder of dividing the current amount of bytes of 3481memory in use by Lua by 1024. 3482</li> 3483 3484<li><b><code>LUA_GCSTEP</code>: </b> 3485performs an incremental step of garbage collection. 3486</li> 3487 3488<li><b><code>LUA_GCSETPAUSE</code>: </b> 3489sets <code>data</code> as the new value 3490for the <em>pause</em> of the collector (see <a href="#2.5">§2.5</a>) 3491and returns the previous value of the pause. 3492</li> 3493 3494<li><b><code>LUA_GCSETSTEPMUL</code>: </b> 3495sets <code>data</code> as the new value for the <em>step multiplier</em> of 3496the collector (see <a href="#2.5">§2.5</a>) 3497and returns the previous value of the step multiplier. 3498</li> 3499 3500<li><b><code>LUA_GCISRUNNING</code>: </b> 3501returns a boolean that tells whether the collector is running 3502(i.e., not stopped). 3503</li> 3504 3505</ul> 3506 3507<p> 3508For more details about these options, 3509see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>. 3510 3511 3512 3513 3514 3515<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> 3516<span class="apii">[-0, +0, –]</span> 3517<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> 3518 3519<p> 3520Returns the memory-allocation function of a given state. 3521If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the 3522opaque pointer given when the memory-allocator function was set. 3523 3524 3525 3526 3527 3528<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> 3529<span class="apii">[-0, +1, <em>e</em>]</span> 3530<pre>int lua_getfield (lua_State *L, int index, const char *k);</pre> 3531 3532<p> 3533Pushes onto the stack the value <code>t[k]</code>, 3534where <code>t</code> is the value at the given index. 3535As in Lua, this function may trigger a metamethod 3536for the "index" event (see <a href="#2.4">§2.4</a>). 3537 3538 3539<p> 3540Returns the type of the pushed value. 3541 3542 3543 3544 3545 3546<hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p> 3547<span class="apii">[-0, +0, –]</span> 3548<pre>void *lua_getextraspace (lua_State *L);</pre> 3549 3550<p> 3551Returns a pointer to a raw memory area associated with the 3552given Lua state. 3553The application can use this area for any purpose; 3554Lua does not use it for anything. 3555 3556 3557<p> 3558Each new thread has this area initialized with a copy 3559of the area of the main thread. 3560 3561 3562<p> 3563By default, this area has the size of a pointer to void, 3564but you can recompile Lua with a different size for this area. 3565(See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.) 3566 3567 3568 3569 3570 3571<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> 3572<span class="apii">[-0, +1, <em>e</em>]</span> 3573<pre>int lua_getglobal (lua_State *L, const char *name);</pre> 3574 3575<p> 3576Pushes onto the stack the value of the global <code>name</code>. 3577Returns the type of that value. 3578 3579 3580 3581 3582 3583<hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p> 3584<span class="apii">[-0, +1, <em>e</em>]</span> 3585<pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre> 3586 3587<p> 3588Pushes onto the stack the value <code>t[i]</code>, 3589where <code>t</code> is the value at the given index. 3590As in Lua, this function may trigger a metamethod 3591for the "index" event (see <a href="#2.4">§2.4</a>). 3592 3593 3594<p> 3595Returns the type of the pushed value. 3596 3597 3598 3599 3600 3601<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> 3602<span class="apii">[-0, +(0|1), –]</span> 3603<pre>int lua_getmetatable (lua_State *L, int index);</pre> 3604 3605<p> 3606If the value at the given index has a metatable, 3607the function pushes that metatable onto the stack and returns 1. 3608Otherwise, 3609the function returns 0 and pushes nothing on the stack. 3610 3611 3612 3613 3614 3615<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> 3616<span class="apii">[-1, +1, <em>e</em>]</span> 3617<pre>int lua_gettable (lua_State *L, int index);</pre> 3618 3619<p> 3620Pushes onto the stack the value <code>t[k]</code>, 3621where <code>t</code> is the value at the given index 3622and <code>k</code> is the value at the top of the stack. 3623 3624 3625<p> 3626This function pops the key from the stack, 3627pushing the resulting value in its place. 3628As in Lua, this function may trigger a metamethod 3629for the "index" event (see <a href="#2.4">§2.4</a>). 3630 3631 3632<p> 3633Returns the type of the pushed value. 3634 3635 3636 3637 3638 3639<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> 3640<span class="apii">[-0, +0, –]</span> 3641<pre>int lua_gettop (lua_State *L);</pre> 3642 3643<p> 3644Returns the index of the top element in the stack. 3645Because indices start at 1, 3646this result is equal to the number of elements in the stack; 3647in particular, 0 means an empty stack. 3648 3649 3650 3651 3652 3653<hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p> 3654<span class="apii">[-0, +1, –]</span> 3655<pre>int lua_getuservalue (lua_State *L, int index);</pre> 3656 3657<p> 3658Pushes onto the stack the Lua value associated with the userdata 3659at the given index. 3660 3661 3662<p> 3663Returns the type of the pushed value. 3664 3665 3666 3667 3668 3669<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> 3670<span class="apii">[-1, +1, –]</span> 3671<pre>void lua_insert (lua_State *L, int index);</pre> 3672 3673<p> 3674Moves the top element into the given valid index, 3675shifting up the elements above this index to open space. 3676This function cannot be called with a pseudo-index, 3677because a pseudo-index is not an actual stack position. 3678 3679 3680 3681 3682 3683<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> 3684<pre>typedef ... lua_Integer;</pre> 3685 3686<p> 3687The type of integers in Lua. 3688 3689 3690<p> 3691By default this type is <code>long long</code>, 3692(usually a 64-bit two-complement integer), 3693but that can be changed to <code>long</code> or <code>int</code> 3694(usually a 32-bit two-complement integer). 3695(See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.) 3696 3697 3698<p> 3699Lua also defines the constants 3700<a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>, 3701with the minimum and the maximum values that fit in this type. 3702 3703 3704 3705 3706 3707<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> 3708<span class="apii">[-0, +0, –]</span> 3709<pre>int lua_isboolean (lua_State *L, int index);</pre> 3710 3711<p> 3712Returns 1 if the value at the given index is a boolean, 3713and 0 otherwise. 3714 3715 3716 3717 3718 3719<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> 3720<span class="apii">[-0, +0, –]</span> 3721<pre>int lua_iscfunction (lua_State *L, int index);</pre> 3722 3723<p> 3724Returns 1 if the value at the given index is a C function, 3725and 0 otherwise. 3726 3727 3728 3729 3730 3731<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> 3732<span class="apii">[-0, +0, –]</span> 3733<pre>int lua_isfunction (lua_State *L, int index);</pre> 3734 3735<p> 3736Returns 1 if the value at the given index is a function 3737(either C or Lua), and 0 otherwise. 3738 3739 3740 3741 3742 3743<hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p> 3744<span class="apii">[-0, +0, –]</span> 3745<pre>int lua_isinteger (lua_State *L, int index);</pre> 3746 3747<p> 3748Returns 1 if the value at the given index is an integer 3749(that is, the value is a number and is represented as an integer), 3750and 0 otherwise. 3751 3752 3753 3754 3755 3756<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> 3757<span class="apii">[-0, +0, –]</span> 3758<pre>int lua_islightuserdata (lua_State *L, int index);</pre> 3759 3760<p> 3761Returns 1 if the value at the given index is a light userdata, 3762and 0 otherwise. 3763 3764 3765 3766 3767 3768<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> 3769<span class="apii">[-0, +0, –]</span> 3770<pre>int lua_isnil (lua_State *L, int index);</pre> 3771 3772<p> 3773Returns 1 if the value at the given index is <b>nil</b>, 3774and 0 otherwise. 3775 3776 3777 3778 3779 3780<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> 3781<span class="apii">[-0, +0, –]</span> 3782<pre>int lua_isnone (lua_State *L, int index);</pre> 3783 3784<p> 3785Returns 1 if the given index is not valid, 3786and 0 otherwise. 3787 3788 3789 3790 3791 3792<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> 3793<span class="apii">[-0, +0, –]</span> 3794<pre>int lua_isnoneornil (lua_State *L, int index);</pre> 3795 3796<p> 3797Returns 1 if the given index is not valid 3798or if the value at this index is <b>nil</b>, 3799and 0 otherwise. 3800 3801 3802 3803 3804 3805<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> 3806<span class="apii">[-0, +0, –]</span> 3807<pre>int lua_isnumber (lua_State *L, int index);</pre> 3808 3809<p> 3810Returns 1 if the value at the given index is a number 3811or a string convertible to a number, 3812and 0 otherwise. 3813 3814 3815 3816 3817 3818<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> 3819<span class="apii">[-0, +0, –]</span> 3820<pre>int lua_isstring (lua_State *L, int index);</pre> 3821 3822<p> 3823Returns 1 if the value at the given index is a string 3824or a number (which is always convertible to a string), 3825and 0 otherwise. 3826 3827 3828 3829 3830 3831<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> 3832<span class="apii">[-0, +0, –]</span> 3833<pre>int lua_istable (lua_State *L, int index);</pre> 3834 3835<p> 3836Returns 1 if the value at the given index is a table, 3837and 0 otherwise. 3838 3839 3840 3841 3842 3843<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> 3844<span class="apii">[-0, +0, –]</span> 3845<pre>int lua_isthread (lua_State *L, int index);</pre> 3846 3847<p> 3848Returns 1 if the value at the given index is a thread, 3849and 0 otherwise. 3850 3851 3852 3853 3854 3855<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> 3856<span class="apii">[-0, +0, –]</span> 3857<pre>int lua_isuserdata (lua_State *L, int index);</pre> 3858 3859<p> 3860Returns 1 if the value at the given index is a userdata 3861(either full or light), and 0 otherwise. 3862 3863 3864 3865 3866 3867<hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p> 3868<span class="apii">[-0, +0, –]</span> 3869<pre>int lua_isyieldable (lua_State *L);</pre> 3870 3871<p> 3872Returns 1 if the given coroutine can yield, 3873and 0 otherwise. 3874 3875 3876 3877 3878 3879<hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3> 3880<pre>typedef ... lua_KContext;</pre> 3881 3882<p> 3883The type for continuation-function contexts. 3884It must be a numeric type. 3885This type is defined as <code>intptr_t</code> 3886when <code>intptr_t</code> is available, 3887so that it can store pointers too. 3888Otherwise, it is defined as <code>ptrdiff_t</code>. 3889 3890 3891 3892 3893 3894<hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3> 3895<pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre> 3896 3897<p> 3898Type for continuation functions (see <a href="#4.7">§4.7</a>). 3899 3900 3901 3902 3903 3904<hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p> 3905<span class="apii">[-0, +1, <em>e</em>]</span> 3906<pre>void lua_len (lua_State *L, int index);</pre> 3907 3908<p> 3909Returns the length of the value at the given index. 3910It is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>) and 3911may trigger a metamethod for the "length" event (see <a href="#2.4">§2.4</a>). 3912The result is pushed on the stack. 3913 3914 3915 3916 3917 3918<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> 3919<span class="apii">[-0, +1, –]</span> 3920<pre>int lua_load (lua_State *L, 3921 lua_Reader reader, 3922 void *data, 3923 const char *chunkname, 3924 const char *mode);</pre> 3925 3926<p> 3927Loads a Lua chunk without running it. 3928If there are no errors, 3929<code>lua_load</code> pushes the compiled chunk as a Lua 3930function on top of the stack. 3931Otherwise, it pushes an error message. 3932 3933 3934<p> 3935The return values of <code>lua_load</code> are: 3936 3937<ul> 3938 3939<li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li> 3940 3941<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> 3942syntax error during precompilation;</li> 3943 3944<li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 3945memory allocation (out-of-memory) error;</li> 3946 3947<li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> 3948error while running a <code>__gc</code> metamethod. 3949(This error has no relation with the chunk being loaded. 3950It is generated by the garbage collector.) 3951</li> 3952 3953</ul> 3954 3955<p> 3956The <code>lua_load</code> function uses a user-supplied <code>reader</code> function 3957to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). 3958The <code>data</code> argument is an opaque value passed to the reader function. 3959 3960 3961<p> 3962The <code>chunkname</code> argument gives a name to the chunk, 3963which is used for error messages and in debug information (see <a href="#4.9">§4.9</a>). 3964 3965 3966<p> 3967<code>lua_load</code> automatically detects whether the chunk is text or binary 3968and loads it accordingly (see program <code>luac</code>). 3969The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>, 3970with the addition that 3971a <code>NULL</code> value is equivalent to the string "<code>bt</code>". 3972 3973 3974<p> 3975<code>lua_load</code> uses the stack internally, 3976so the reader function must always leave the stack 3977unmodified when returning. 3978 3979 3980<p> 3981If the resulting function has upvalues, 3982its first upvalue is set to the value of the global environment 3983stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">§4.5</a>). 3984When loading main chunks, 3985this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 3986Other upvalues are initialized with <b>nil</b>. 3987 3988 3989 3990 3991 3992<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> 3993<span class="apii">[-0, +0, –]</span> 3994<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> 3995 3996<p> 3997Creates a new thread running in a new, independent state. 3998Returns <code>NULL</code> if it cannot create the thread or the state 3999(due to lack of memory). 4000The argument <code>f</code> is the allocator function; 4001Lua does all memory allocation for this state through this function. 4002The second argument, <code>ud</code>, is an opaque pointer that Lua 4003passes to the allocator in every call. 4004 4005 4006 4007 4008 4009<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> 4010<span class="apii">[-0, +1, <em>m</em>]</span> 4011<pre>void lua_newtable (lua_State *L);</pre> 4012 4013<p> 4014Creates a new empty table and pushes it onto the stack. 4015It is equivalent to <code>lua_createtable(L, 0, 0)</code>. 4016 4017 4018 4019 4020 4021<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> 4022<span class="apii">[-0, +1, <em>m</em>]</span> 4023<pre>lua_State *lua_newthread (lua_State *L);</pre> 4024 4025<p> 4026Creates a new thread, pushes it on the stack, 4027and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. 4028The new thread returned by this function shares with the original thread 4029its global environment, 4030but has an independent execution stack. 4031 4032 4033<p> 4034There is no explicit function to close or to destroy a thread. 4035Threads are subject to garbage collection, 4036like any Lua object. 4037 4038 4039 4040 4041 4042<hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p> 4043<span class="apii">[-0, +1, <em>m</em>]</span> 4044<pre>void *lua_newuserdata (lua_State *L, size_t size);</pre> 4045 4046<p> 4047This function allocates a new block of memory with the given size, 4048pushes onto the stack a new full userdata with the block address, 4049and returns this address. 4050The host program can freely use this memory. 4051 4052 4053 4054 4055 4056<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> 4057<span class="apii">[-1, +(2|0), <em>e</em>]</span> 4058<pre>int lua_next (lua_State *L, int index);</pre> 4059 4060<p> 4061Pops a key from the stack, 4062and pushes a key–value pair from the table at the given index 4063(the "next" pair after the given key). 4064If there are no more elements in the table, 4065then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). 4066 4067 4068<p> 4069A typical traversal looks like this: 4070 4071<pre> 4072 /* table is in the stack at index 't' */ 4073 lua_pushnil(L); /* first key */ 4074 while (lua_next(L, t) != 0) { 4075 /* uses 'key' (at index -2) and 'value' (at index -1) */ 4076 printf("%s - %s\n", 4077 lua_typename(L, lua_type(L, -2)), 4078 lua_typename(L, lua_type(L, -1))); 4079 /* removes 'value'; keeps 'key' for next iteration */ 4080 lua_pop(L, 1); 4081 } 4082</pre> 4083 4084<p> 4085While traversing a table, 4086do not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, 4087unless you know that the key is actually a string. 4088Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change 4089the value at the given index; 4090this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. 4091 4092 4093<p> 4094See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 4095the table during its traversal. 4096 4097 4098 4099 4100 4101<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> 4102<pre>typedef ... lua_Number;</pre> 4103 4104<p> 4105The type of floats in Lua. 4106 4107 4108<p> 4109By default this type is double, 4110but that can be changed to a single float or a long double. 4111(See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.) 4112 4113 4114 4115 4116 4117<hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3> 4118<pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre> 4119 4120<p> 4121Converts a Lua float to a Lua integer. 4122This macro assumes that <code>n</code> has an integral value. 4123If that value is within the range of Lua integers, 4124it is converted to an integer and assigned to <code>*p</code>. 4125The macro results in a boolean indicating whether the 4126conversion was successful. 4127(Note that this range test can be tricky to do 4128correctly without this macro, 4129due to roundings.) 4130 4131 4132<p> 4133This macro may evaluate its arguments more than once. 4134 4135 4136 4137 4138 4139<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> 4140<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4141<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre> 4142 4143<p> 4144Calls a function in protected mode. 4145 4146 4147<p> 4148Both <code>nargs</code> and <code>nresults</code> have the same meaning as 4149in <a href="#lua_call"><code>lua_call</code></a>. 4150If there are no errors during the call, 4151<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. 4152However, if there is any error, 4153<a href="#lua_pcall"><code>lua_pcall</code></a> catches it, 4154pushes a single value on the stack (the error object), 4155and returns an error code. 4156Like <a href="#lua_call"><code>lua_call</code></a>, 4157<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function 4158and its arguments from the stack. 4159 4160 4161<p> 4162If <code>msgh</code> is 0, 4163then the error object returned on the stack 4164is exactly the original error object. 4165Otherwise, <code>msgh</code> is the stack index of a 4166<em>message handler</em>. 4167(This index cannot be a pseudo-index.) 4168In case of runtime errors, 4169this function will be called with the error object 4170and its return value will be the object 4171returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. 4172 4173 4174<p> 4175Typically, the message handler is used to add more debug 4176information to the error object, such as a stack traceback. 4177Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, 4178since by then the stack has unwound. 4179 4180 4181<p> 4182The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following constants 4183(defined in <code>lua.h</code>): 4184 4185<ul> 4186 4187<li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> 4188success.</li> 4189 4190<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b> 4191a runtime error. 4192</li> 4193 4194<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 4195memory allocation error. 4196For such errors, Lua does not call the message handler. 4197</li> 4198 4199<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b> 4200error while running the message handler. 4201</li> 4202 4203<li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> 4204error while running a <code>__gc</code> metamethod. 4205(This error typically has no relation with the function being called.) 4206</li> 4207 4208</ul> 4209 4210 4211 4212 4213<hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p> 4214<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4215<pre>int lua_pcallk (lua_State *L, 4216 int nargs, 4217 int nresults, 4218 int msgh, 4219 lua_KContext ctx, 4220 lua_KFunction k);</pre> 4221 4222<p> 4223This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>, 4224but allows the called function to yield (see <a href="#4.7">§4.7</a>). 4225 4226 4227 4228 4229 4230<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> 4231<span class="apii">[-n, +0, –]</span> 4232<pre>void lua_pop (lua_State *L, int n);</pre> 4233 4234<p> 4235Pops <code>n</code> elements from the stack. 4236 4237 4238 4239 4240 4241<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> 4242<span class="apii">[-0, +1, –]</span> 4243<pre>void lua_pushboolean (lua_State *L, int b);</pre> 4244 4245<p> 4246Pushes a boolean value with value <code>b</code> onto the stack. 4247 4248 4249 4250 4251 4252<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> 4253<span class="apii">[-n, +1, <em>m</em>]</span> 4254<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> 4255 4256<p> 4257Pushes a new C closure onto the stack. 4258 4259 4260<p> 4261When a C function is created, 4262it is possible to associate some values with it, 4263thus creating a C closure (see <a href="#4.4">§4.4</a>); 4264these values are then accessible to the function whenever it is called. 4265To associate values with a C function, 4266first these values must be pushed onto the stack 4267(when there are multiple values, the first value is pushed first). 4268Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 4269is called to create and push the C function onto the stack, 4270with the argument <code>n</code> telling how many values will be 4271associated with the function. 4272<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. 4273 4274 4275<p> 4276The maximum value for <code>n</code> is 255. 4277 4278 4279<p> 4280When <code>n</code> is zero, 4281this function creates a <em>light C function</em>, 4282which is just a pointer to the C function. 4283In that case, it never raises a memory error. 4284 4285 4286 4287 4288 4289<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> 4290<span class="apii">[-0, +1, –]</span> 4291<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> 4292 4293<p> 4294Pushes a C function onto the stack. 4295This function receives a pointer to a C function 4296and pushes onto the stack a Lua value of type <code>function</code> that, 4297when called, invokes the corresponding C function. 4298 4299 4300<p> 4301Any function to be callable by Lua must 4302follow the correct protocol to receive its parameters 4303and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 4304 4305 4306 4307 4308 4309<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> 4310<span class="apii">[-0, +1, <em>e</em>]</span> 4311<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> 4312 4313<p> 4314Pushes onto the stack a formatted string 4315and returns a pointer to this string. 4316It is similar to the ISO C function <code>sprintf</code>, 4317but has some important differences: 4318 4319<ul> 4320 4321<li> 4322You do not have to allocate space for the result: 4323the result is a Lua string and Lua takes care of memory allocation 4324(and deallocation, through garbage collection). 4325</li> 4326 4327<li> 4328The conversion specifiers are quite restricted. 4329There are no flags, widths, or precisions. 4330The conversion specifiers can only be 4331'<code>%%</code>' (inserts the character '<code>%</code>'), 4332'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), 4333'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), 4334'<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>), 4335'<code>%p</code>' (inserts a pointer as a hexadecimal numeral), 4336'<code>%d</code>' (inserts an <code>int</code>), 4337'<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and 4338'<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence). 4339</li> 4340 4341</ul> 4342 4343<p> 4344Unlike other push functions, 4345this function checks for the stack space it needs, 4346including the slot for its result. 4347 4348 4349 4350 4351 4352<hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p> 4353<span class="apii">[-0, +1, –]</span> 4354<pre>void lua_pushglobaltable (lua_State *L);</pre> 4355 4356<p> 4357Pushes the global environment onto the stack. 4358 4359 4360 4361 4362 4363<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> 4364<span class="apii">[-0, +1, –]</span> 4365<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> 4366 4367<p> 4368Pushes an integer with value <code>n</code> onto the stack. 4369 4370 4371 4372 4373 4374<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> 4375<span class="apii">[-0, +1, –]</span> 4376<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> 4377 4378<p> 4379Pushes a light userdata onto the stack. 4380 4381 4382<p> 4383Userdata represent C values in Lua. 4384A <em>light userdata</em> represents a pointer, a <code>void*</code>. 4385It is a value (like a number): 4386you do not create it, it has no individual metatable, 4387and it is not collected (as it was never created). 4388A light userdata is equal to "any" 4389light userdata with the same C address. 4390 4391 4392 4393 4394 4395<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> 4396<span class="apii">[-0, +1, <em>m</em>]</span> 4397<pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre> 4398 4399<p> 4400This macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>, 4401but should be used only when <code>s</code> is a literal string. 4402 4403 4404 4405 4406 4407<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> 4408<span class="apii">[-0, +1, <em>m</em>]</span> 4409<pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> 4410 4411<p> 4412Pushes the string pointed to by <code>s</code> with size <code>len</code> 4413onto the stack. 4414Lua makes (or reuses) an internal copy of the given string, 4415so the memory at <code>s</code> can be freed or reused immediately after 4416the function returns. 4417The string can contain any binary data, 4418including embedded zeros. 4419 4420 4421<p> 4422Returns a pointer to the internal copy of the string. 4423 4424 4425 4426 4427 4428<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> 4429<span class="apii">[-0, +1, –]</span> 4430<pre>void lua_pushnil (lua_State *L);</pre> 4431 4432<p> 4433Pushes a nil value onto the stack. 4434 4435 4436 4437 4438 4439<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> 4440<span class="apii">[-0, +1, –]</span> 4441<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> 4442 4443<p> 4444Pushes a float with value <code>n</code> onto the stack. 4445 4446 4447 4448 4449 4450<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> 4451<span class="apii">[-0, +1, <em>m</em>]</span> 4452<pre>const char *lua_pushstring (lua_State *L, const char *s);</pre> 4453 4454<p> 4455Pushes the zero-terminated string pointed to by <code>s</code> 4456onto the stack. 4457Lua makes (or reuses) an internal copy of the given string, 4458so the memory at <code>s</code> can be freed or reused immediately after 4459the function returns. 4460 4461 4462<p> 4463Returns a pointer to the internal copy of the string. 4464 4465 4466<p> 4467If <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>. 4468 4469 4470 4471 4472 4473<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> 4474<span class="apii">[-0, +1, –]</span> 4475<pre>int lua_pushthread (lua_State *L);</pre> 4476 4477<p> 4478Pushes the thread represented by <code>L</code> onto the stack. 4479Returns 1 if this thread is the main thread of its state. 4480 4481 4482 4483 4484 4485<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> 4486<span class="apii">[-0, +1, –]</span> 4487<pre>void lua_pushvalue (lua_State *L, int index);</pre> 4488 4489<p> 4490Pushes a copy of the element at the given index 4491onto the stack. 4492 4493 4494 4495 4496 4497<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> 4498<span class="apii">[-0, +1, <em>m</em>]</span> 4499<pre>const char *lua_pushvfstring (lua_State *L, 4500 const char *fmt, 4501 va_list argp);</pre> 4502 4503<p> 4504Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> 4505instead of a variable number of arguments. 4506 4507 4508 4509 4510 4511<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> 4512<span class="apii">[-0, +0, –]</span> 4513<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> 4514 4515<p> 4516Returns 1 if the two values in indices <code>index1</code> and 4517<code>index2</code> are primitively equal 4518(that is, without calling the <code>__eq</code> metamethod). 4519Otherwise returns 0. 4520Also returns 0 if any of the indices are not valid. 4521 4522 4523 4524 4525 4526<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> 4527<span class="apii">[-1, +1, –]</span> 4528<pre>int lua_rawget (lua_State *L, int index);</pre> 4529 4530<p> 4531Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access 4532(i.e., without metamethods). 4533 4534 4535 4536 4537 4538<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> 4539<span class="apii">[-0, +1, –]</span> 4540<pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre> 4541 4542<p> 4543Pushes onto the stack the value <code>t[n]</code>, 4544where <code>t</code> is the table at the given index. 4545The access is raw, 4546that is, it does not invoke the <code>__index</code> metamethod. 4547 4548 4549<p> 4550Returns the type of the pushed value. 4551 4552 4553 4554 4555 4556<hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p> 4557<span class="apii">[-0, +1, –]</span> 4558<pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre> 4559 4560<p> 4561Pushes onto the stack the value <code>t[k]</code>, 4562where <code>t</code> is the table at the given index and 4563<code>k</code> is the pointer <code>p</code> represented as a light userdata. 4564The access is raw; 4565that is, it does not invoke the <code>__index</code> metamethod. 4566 4567 4568<p> 4569Returns the type of the pushed value. 4570 4571 4572 4573 4574 4575<hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p> 4576<span class="apii">[-0, +0, –]</span> 4577<pre>size_t lua_rawlen (lua_State *L, int index);</pre> 4578 4579<p> 4580Returns the raw "length" of the value at the given index: 4581for strings, this is the string length; 4582for tables, this is the result of the length operator ('<code>#</code>') 4583with no metamethods; 4584for userdata, this is the size of the block of memory allocated 4585for the userdata; 4586for other values, it is 0. 4587 4588 4589 4590 4591 4592<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> 4593<span class="apii">[-2, +0, <em>m</em>]</span> 4594<pre>void lua_rawset (lua_State *L, int index);</pre> 4595 4596<p> 4597Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment 4598(i.e., without metamethods). 4599 4600 4601 4602 4603 4604<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> 4605<span class="apii">[-1, +0, <em>m</em>]</span> 4606<pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre> 4607 4608<p> 4609Does the equivalent of <code>t[i] = v</code>, 4610where <code>t</code> is the table at the given index 4611and <code>v</code> is the value at the top of the stack. 4612 4613 4614<p> 4615This function pops the value from the stack. 4616The assignment is raw, 4617that is, it does not invoke the <code>__newindex</code> metamethod. 4618 4619 4620 4621 4622 4623<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p> 4624<span class="apii">[-1, +0, <em>m</em>]</span> 4625<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre> 4626 4627<p> 4628Does the equivalent of <code>t[p] = v</code>, 4629where <code>t</code> is the table at the given index, 4630<code>p</code> is encoded as a light userdata, 4631and <code>v</code> is the value at the top of the stack. 4632 4633 4634<p> 4635This function pops the value from the stack. 4636The assignment is raw, 4637that is, it does not invoke <code>__newindex</code> metamethod. 4638 4639 4640 4641 4642 4643<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> 4644<pre>typedef const char * (*lua_Reader) (lua_State *L, 4645 void *data, 4646 size_t *size);</pre> 4647 4648<p> 4649The reader function used by <a href="#lua_load"><code>lua_load</code></a>. 4650Every time it needs another piece of the chunk, 4651<a href="#lua_load"><code>lua_load</code></a> calls the reader, 4652passing along its <code>data</code> parameter. 4653The reader must return a pointer to a block of memory 4654with a new piece of the chunk 4655and set <code>size</code> to the block size. 4656The block must exist until the reader function is called again. 4657To signal the end of the chunk, 4658the reader must return <code>NULL</code> or set <code>size</code> to zero. 4659The reader function may return pieces of any size greater than zero. 4660 4661 4662 4663 4664 4665<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> 4666<span class="apii">[-0, +0, <em>e</em>]</span> 4667<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre> 4668 4669<p> 4670Sets the C function <code>f</code> as the new value of global <code>name</code>. 4671It is defined as a macro: 4672 4673<pre> 4674 #define lua_register(L,n,f) \ 4675 (lua_pushcfunction(L, f), lua_setglobal(L, n)) 4676</pre> 4677 4678 4679 4680 4681<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> 4682<span class="apii">[-1, +0, –]</span> 4683<pre>void lua_remove (lua_State *L, int index);</pre> 4684 4685<p> 4686Removes the element at the given valid index, 4687shifting down the elements above this index to fill the gap. 4688This function cannot be called with a pseudo-index, 4689because a pseudo-index is not an actual stack position. 4690 4691 4692 4693 4694 4695<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> 4696<span class="apii">[-1, +0, –]</span> 4697<pre>void lua_replace (lua_State *L, int index);</pre> 4698 4699<p> 4700Moves the top element into the given valid index 4701without shifting any element 4702(therefore replacing the value at that given index), 4703and then pops the top element. 4704 4705 4706 4707 4708 4709<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> 4710<span class="apii">[-?, +?, –]</span> 4711<pre>int lua_resume (lua_State *L, lua_State *from, int nargs);</pre> 4712 4713<p> 4714Starts and resumes a coroutine in the given thread <code>L</code>. 4715 4716 4717<p> 4718To start a coroutine, 4719you push onto the thread stack the main function plus any arguments; 4720then you call <a href="#lua_resume"><code>lua_resume</code></a>, 4721with <code>nargs</code> being the number of arguments. 4722This call returns when the coroutine suspends or finishes its execution. 4723When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>, 4724or all values returned by the body function. 4725<a href="#lua_resume"><code>lua_resume</code></a> returns 4726<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, 4727<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution 4728without errors, 4729or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). 4730 4731 4732<p> 4733In case of errors, 4734the stack is not unwound, 4735so you can use the debug API over it. 4736The error object is on the top of the stack. 4737 4738 4739<p> 4740To resume a coroutine, 4741you remove any results from the last <a href="#lua_yield"><code>lua_yield</code></a>, 4742put on its stack only the values to 4743be passed as results from <code>yield</code>, 4744and then call <a href="#lua_resume"><code>lua_resume</code></a>. 4745 4746 4747<p> 4748The parameter <code>from</code> represents the coroutine that is resuming <code>L</code>. 4749If there is no such coroutine, 4750this parameter can be <code>NULL</code>. 4751 4752 4753 4754 4755 4756<hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p> 4757<span class="apii">[-0, +0, –]</span> 4758<pre>void lua_rotate (lua_State *L, int idx, int n);</pre> 4759 4760<p> 4761Rotates the stack elements between the valid index <code>idx</code> 4762and the top of the stack. 4763The elements are rotated <code>n</code> positions in the direction of the top, 4764for a positive <code>n</code>, 4765or <code>-n</code> positions in the direction of the bottom, 4766for a negative <code>n</code>. 4767The absolute value of <code>n</code> must not be greater than the size 4768of the slice being rotated. 4769This function cannot be called with a pseudo-index, 4770because a pseudo-index is not an actual stack position. 4771 4772 4773 4774 4775 4776<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> 4777<span class="apii">[-0, +0, –]</span> 4778<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> 4779 4780<p> 4781Changes the allocator function of a given state to <code>f</code> 4782with user data <code>ud</code>. 4783 4784 4785 4786 4787 4788<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> 4789<span class="apii">[-1, +0, <em>e</em>]</span> 4790<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> 4791 4792<p> 4793Does the equivalent to <code>t[k] = v</code>, 4794where <code>t</code> is the value at the given index 4795and <code>v</code> is the value at the top of the stack. 4796 4797 4798<p> 4799This function pops the value from the stack. 4800As in Lua, this function may trigger a metamethod 4801for the "newindex" event (see <a href="#2.4">§2.4</a>). 4802 4803 4804 4805 4806 4807<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> 4808<span class="apii">[-1, +0, <em>e</em>]</span> 4809<pre>void lua_setglobal (lua_State *L, const char *name);</pre> 4810 4811<p> 4812Pops a value from the stack and 4813sets it as the new value of global <code>name</code>. 4814 4815 4816 4817 4818 4819<hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p> 4820<span class="apii">[-1, +0, <em>e</em>]</span> 4821<pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre> 4822 4823<p> 4824Does the equivalent to <code>t[n] = v</code>, 4825where <code>t</code> is the value at the given index 4826and <code>v</code> is the value at the top of the stack. 4827 4828 4829<p> 4830This function pops the value from the stack. 4831As in Lua, this function may trigger a metamethod 4832for the "newindex" event (see <a href="#2.4">§2.4</a>). 4833 4834 4835 4836 4837 4838<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> 4839<span class="apii">[-1, +0, –]</span> 4840<pre>void lua_setmetatable (lua_State *L, int index);</pre> 4841 4842<p> 4843Pops a table from the stack and 4844sets it as the new metatable for the value at the given index. 4845 4846 4847 4848 4849 4850<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> 4851<span class="apii">[-2, +0, <em>e</em>]</span> 4852<pre>void lua_settable (lua_State *L, int index);</pre> 4853 4854<p> 4855Does the equivalent to <code>t[k] = v</code>, 4856where <code>t</code> is the value at the given index, 4857<code>v</code> is the value at the top of the stack, 4858and <code>k</code> is the value just below the top. 4859 4860 4861<p> 4862This function pops both the key and the value from the stack. 4863As in Lua, this function may trigger a metamethod 4864for the "newindex" event (see <a href="#2.4">§2.4</a>). 4865 4866 4867 4868 4869 4870<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> 4871<span class="apii">[-?, +?, –]</span> 4872<pre>void lua_settop (lua_State *L, int index);</pre> 4873 4874<p> 4875Accepts any index, or 0, 4876and sets the stack top to this index. 4877If the new top is larger than the old one, 4878then the new elements are filled with <b>nil</b>. 4879If <code>index</code> is 0, then all stack elements are removed. 4880 4881 4882 4883 4884 4885<hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p> 4886<span class="apii">[-1, +0, –]</span> 4887<pre>void lua_setuservalue (lua_State *L, int index);</pre> 4888 4889<p> 4890Pops a value from the stack and sets it as 4891the new value associated to the userdata at the given index. 4892 4893 4894 4895 4896 4897<hr><h3><a name="lua_State"><code>lua_State</code></a></h3> 4898<pre>typedef struct lua_State lua_State;</pre> 4899 4900<p> 4901An opaque structure that points to a thread and indirectly 4902(through the thread) to the whole state of a Lua interpreter. 4903The Lua library is fully reentrant: 4904it has no global variables. 4905All information about a state is accessible through this structure. 4906 4907 4908<p> 4909A pointer to this structure must be passed as the first argument to 4910every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 4911which creates a Lua state from scratch. 4912 4913 4914 4915 4916 4917<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> 4918<span class="apii">[-0, +0, –]</span> 4919<pre>int lua_status (lua_State *L);</pre> 4920 4921<p> 4922Returns the status of the thread <code>L</code>. 4923 4924 4925<p> 4926The status can be 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) for a normal thread, 4927an error code if the thread finished the execution 4928of a <a href="#lua_resume"><code>lua_resume</code></a> with an error, 4929or <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. 4930 4931 4932<p> 4933You can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>. 4934You can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> 4935(to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> 4936(to resume a coroutine). 4937 4938 4939 4940 4941 4942<hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p> 4943<span class="apii">[-0, +1, –]</span> 4944<pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre> 4945 4946<p> 4947Converts the zero-terminated string <code>s</code> to a number, 4948pushes that number into the stack, 4949and returns the total size of the string, 4950that is, its length plus one. 4951The conversion can result in an integer or a float, 4952according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 4953The string may have leading and trailing spaces and a sign. 4954If the string is not a valid numeral, 4955returns 0 and pushes nothing. 4956(Note that the result can be used as a boolean, 4957true if the conversion succeeds.) 4958 4959 4960 4961 4962 4963<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> 4964<span class="apii">[-0, +0, –]</span> 4965<pre>int lua_toboolean (lua_State *L, int index);</pre> 4966 4967<p> 4968Converts the Lua value at the given index to a C boolean 4969value (0 or 1). 4970Like all tests in Lua, 4971<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value 4972different from <b>false</b> and <b>nil</b>; 4973otherwise it returns false. 4974(If you want to accept only actual boolean values, 4975use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) 4976 4977 4978 4979 4980 4981<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> 4982<span class="apii">[-0, +0, –]</span> 4983<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> 4984 4985<p> 4986Converts a value at the given index to a C function. 4987That value must be a C function; 4988otherwise, returns <code>NULL</code>. 4989 4990 4991 4992 4993 4994<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> 4995<span class="apii">[-0, +0, –]</span> 4996<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> 4997 4998<p> 4999Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5000 5001 5002 5003 5004 5005<hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p> 5006<span class="apii">[-0, +0, –]</span> 5007<pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre> 5008 5009<p> 5010Converts the Lua value at the given index 5011to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. 5012The Lua value must be an integer, 5013or a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>); 5014otherwise, <code>lua_tointegerx</code> returns 0. 5015 5016 5017<p> 5018If <code>isnum</code> is not <code>NULL</code>, 5019its referent is assigned a boolean value that 5020indicates whether the operation succeeded. 5021 5022 5023 5024 5025 5026<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> 5027<span class="apii">[-0, +0, <em>m</em>]</span> 5028<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> 5029 5030<p> 5031Converts the Lua value at the given index to a C string. 5032If <code>len</code> is not <code>NULL</code>, 5033it sets <code>*len</code> with the string length. 5034The Lua value must be a string or a number; 5035otherwise, the function returns <code>NULL</code>. 5036If the value is a number, 5037then <code>lua_tolstring</code> also 5038<em>changes the actual value in the stack to a string</em>. 5039(This change confuses <a href="#lua_next"><code>lua_next</code></a> 5040when <code>lua_tolstring</code> is applied to keys during a table traversal.) 5041 5042 5043<p> 5044<code>lua_tolstring</code> returns a pointer 5045to a string inside the Lua state. 5046This string always has a zero ('<code>\0</code>') 5047after its last character (as in C), 5048but can contain other zeros in its body. 5049 5050 5051<p> 5052Because Lua has garbage collection, 5053there is no guarantee that the pointer returned by <code>lua_tolstring</code> 5054will be valid after the corresponding Lua value is removed from the stack. 5055 5056 5057 5058 5059 5060<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> 5061<span class="apii">[-0, +0, –]</span> 5062<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> 5063 5064<p> 5065Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5066 5067 5068 5069 5070 5071<hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p> 5072<span class="apii">[-0, +0, –]</span> 5073<pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre> 5074 5075<p> 5076Converts the Lua value at the given index 5077to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). 5078The Lua value must be a number or a string convertible to a number 5079(see <a href="#3.4.3">§3.4.3</a>); 5080otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0. 5081 5082 5083<p> 5084If <code>isnum</code> is not <code>NULL</code>, 5085its referent is assigned a boolean value that 5086indicates whether the operation succeeded. 5087 5088 5089 5090 5091 5092<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> 5093<span class="apii">[-0, +0, –]</span> 5094<pre>const void *lua_topointer (lua_State *L, int index);</pre> 5095 5096<p> 5097Converts the value at the given index to a generic 5098C pointer (<code>void*</code>). 5099The value can be a userdata, a table, a thread, or a function; 5100otherwise, <code>lua_topointer</code> returns <code>NULL</code>. 5101Different objects will give different pointers. 5102There is no way to convert the pointer back to its original value. 5103 5104 5105<p> 5106Typically this function is used only for hashing and debug information. 5107 5108 5109 5110 5111 5112<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> 5113<span class="apii">[-0, +0, <em>m</em>]</span> 5114<pre>const char *lua_tostring (lua_State *L, int index);</pre> 5115 5116<p> 5117Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. 5118 5119 5120 5121 5122 5123<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> 5124<span class="apii">[-0, +0, –]</span> 5125<pre>lua_State *lua_tothread (lua_State *L, int index);</pre> 5126 5127<p> 5128Converts the value at the given index to a Lua thread 5129(represented as <code>lua_State*</code>). 5130This value must be a thread; 5131otherwise, the function returns <code>NULL</code>. 5132 5133 5134 5135 5136 5137<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> 5138<span class="apii">[-0, +0, –]</span> 5139<pre>void *lua_touserdata (lua_State *L, int index);</pre> 5140 5141<p> 5142If the value at the given index is a full userdata, 5143returns its block address. 5144If the value is a light userdata, 5145returns its pointer. 5146Otherwise, returns <code>NULL</code>. 5147 5148 5149 5150 5151 5152<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> 5153<span class="apii">[-0, +0, –]</span> 5154<pre>int lua_type (lua_State *L, int index);</pre> 5155 5156<p> 5157Returns the type of the value in the given valid index, 5158or <code>LUA_TNONE</code> for a non-valid (but acceptable) index. 5159The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants 5160defined in <code>lua.h</code>: 5161<a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a> (0), 5162<a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>, 5163<a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>, 5164<a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, 5165<a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, 5166<a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, 5167<a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, 5168<a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>, 5169and 5170<a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>. 5171 5172 5173 5174 5175 5176<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> 5177<span class="apii">[-0, +0, –]</span> 5178<pre>const char *lua_typename (lua_State *L, int tp);</pre> 5179 5180<p> 5181Returns the name of the type encoded by the value <code>tp</code>, 5182which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. 5183 5184 5185 5186 5187 5188<hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3> 5189<pre>typedef ... lua_Unsigned;</pre> 5190 5191<p> 5192The unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>. 5193 5194 5195 5196 5197 5198<hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p> 5199<span class="apii">[-0, +0, –]</span> 5200<pre>int lua_upvalueindex (int i);</pre> 5201 5202<p> 5203Returns the pseudo-index that represents the <code>i</code>-th upvalue of 5204the running function (see <a href="#4.4">§4.4</a>). 5205 5206 5207 5208 5209 5210<hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p> 5211<span class="apii">[-0, +0, –]</span> 5212<pre>const lua_Number *lua_version (lua_State *L);</pre> 5213 5214<p> 5215Returns the address of the version number 5216(a C static variable) 5217stored in the Lua core. 5218When called with a valid <a href="#lua_State"><code>lua_State</code></a>, 5219returns the address of the version used to create that state. 5220When called with <code>NULL</code>, 5221returns the address of the version running the call. 5222 5223 5224 5225 5226 5227<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> 5228<pre>typedef int (*lua_Writer) (lua_State *L, 5229 const void* p, 5230 size_t sz, 5231 void* ud);</pre> 5232 5233<p> 5234The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. 5235Every time it produces another piece of chunk, 5236<a href="#lua_dump"><code>lua_dump</code></a> calls the writer, 5237passing along the buffer to be written (<code>p</code>), 5238its size (<code>sz</code>), 5239and the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. 5240 5241 5242<p> 5243The writer returns an error code: 52440 means no errors; 5245any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from 5246calling the writer again. 5247 5248 5249 5250 5251 5252<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> 5253<span class="apii">[-?, +?, –]</span> 5254<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> 5255 5256<p> 5257Exchange values between different threads of the same state. 5258 5259 5260<p> 5261This function pops <code>n</code> values from the stack <code>from</code>, 5262and pushes them onto the stack <code>to</code>. 5263 5264 5265 5266 5267 5268<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> 5269<span class="apii">[-?, +?, <em>e</em>]</span> 5270<pre>int lua_yield (lua_State *L, int nresults);</pre> 5271 5272<p> 5273This function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5274but it has no continuation (see <a href="#4.7">§4.7</a>). 5275Therefore, when the thread resumes, 5276it continues the function that called 5277the function calling <code>lua_yield</code>. 5278 5279 5280 5281 5282 5283<hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p> 5284<span class="apii">[-?, +?, <em>e</em>]</span> 5285<pre>int lua_yieldk (lua_State *L, 5286 int nresults, 5287 lua_KContext ctx, 5288 lua_KFunction k);</pre> 5289 5290<p> 5291Yields a coroutine (thread). 5292 5293 5294<p> 5295When a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5296the running coroutine suspends its execution, 5297and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. 5298The parameter <code>nresults</code> is the number of values from the stack 5299that will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. 5300 5301 5302<p> 5303When the coroutine is resumed again, 5304Lua calls the given continuation function <code>k</code> to continue 5305the execution of the C function that yielded (see <a href="#4.7">§4.7</a>). 5306This continuation function receives the same stack 5307from the previous function, 5308with the <code>n</code> results removed and 5309replaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>. 5310Moreover, 5311the continuation function receives the value <code>ctx</code> 5312that was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>. 5313 5314 5315<p> 5316Usually, this function does not return; 5317when the coroutine eventually resumes, 5318it continues executing the continuation function. 5319However, there is one special case, 5320which is when this function is called 5321from inside a line or a count hook (see <a href="#4.9">§4.9</a>). 5322In that case, <code>lua_yieldk</code> should be called with no continuation 5323(probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results, 5324and the hook should return immediately after the call. 5325Lua will yield and, 5326when the coroutine resumes again, 5327it will continue the normal execution 5328of the (Lua) function that triggered the hook. 5329 5330 5331<p> 5332This function can raise an error if it is called from a thread 5333with a pending C call with no continuation function, 5334or it is called from a thread that is not running inside a resume 5335(e.g., the main thread). 5336 5337 5338 5339 5340 5341 5342 5343<h2>4.9 – <a name="4.9">The Debug Interface</a></h2> 5344 5345<p> 5346Lua has no built-in debugging facilities. 5347Instead, it offers a special interface 5348by means of functions and <em>hooks</em>. 5349This interface allows the construction of different 5350kinds of debuggers, profilers, and other tools 5351that need "inside information" from the interpreter. 5352 5353 5354 5355<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> 5356<pre>typedef struct lua_Debug { 5357 int event; 5358 const char *name; /* (n) */ 5359 const char *namewhat; /* (n) */ 5360 const char *what; /* (S) */ 5361 const char *source; /* (S) */ 5362 int currentline; /* (l) */ 5363 int linedefined; /* (S) */ 5364 int lastlinedefined; /* (S) */ 5365 unsigned char nups; /* (u) number of upvalues */ 5366 unsigned char nparams; /* (u) number of parameters */ 5367 char isvararg; /* (u) */ 5368 char istailcall; /* (t) */ 5369 char short_src[LUA_IDSIZE]; /* (S) */ 5370 /* private part */ 5371 <em>other fields</em> 5372} lua_Debug;</pre> 5373 5374<p> 5375A structure used to carry different pieces of 5376information about a function or an activation record. 5377<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part 5378of this structure, for later use. 5379To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, 5380call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 5381 5382 5383<p> 5384The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: 5385 5386<ul> 5387 5388<li><b><code>source</code>: </b> 5389the name of the chunk that created the function. 5390If <code>source</code> starts with a '<code>@</code>', 5391it means that the function was defined in a file where 5392the file name follows the '<code>@</code>'. 5393If <code>source</code> starts with a '<code>=</code>', 5394the remainder of its contents describe the source in a user-dependent manner. 5395Otherwise, 5396the function was defined in a string where 5397<code>source</code> is that string. 5398</li> 5399 5400<li><b><code>short_src</code>: </b> 5401a "printable" version of <code>source</code>, to be used in error messages. 5402</li> 5403 5404<li><b><code>linedefined</code>: </b> 5405the line number where the definition of the function starts. 5406</li> 5407 5408<li><b><code>lastlinedefined</code>: </b> 5409the line number where the definition of the function ends. 5410</li> 5411 5412<li><b><code>what</code>: </b> 5413the string <code>"Lua"</code> if the function is a Lua function, 5414<code>"C"</code> if it is a C function, 5415<code>"main"</code> if it is the main part of a chunk. 5416</li> 5417 5418<li><b><code>currentline</code>: </b> 5419the current line where the given function is executing. 5420When no line information is available, 5421<code>currentline</code> is set to -1. 5422</li> 5423 5424<li><b><code>name</code>: </b> 5425a reasonable name for the given function. 5426Because functions in Lua are first-class values, 5427they do not have a fixed name: 5428some functions can be the value of multiple global variables, 5429while others can be stored only in a table field. 5430The <code>lua_getinfo</code> function checks how the function was 5431called to find a suitable name. 5432If it cannot find a name, 5433then <code>name</code> is set to <code>NULL</code>. 5434</li> 5435 5436<li><b><code>namewhat</code>: </b> 5437explains the <code>name</code> field. 5438The value of <code>namewhat</code> can be 5439<code>"global"</code>, <code>"local"</code>, <code>"method"</code>, 5440<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), 5441according to how the function was called. 5442(Lua uses the empty string when no other option seems to apply.) 5443</li> 5444 5445<li><b><code>istailcall</code>: </b> 5446true if this function invocation was called by a tail call. 5447In this case, the caller of this level is not in the stack. 5448</li> 5449 5450<li><b><code>nups</code>: </b> 5451the number of upvalues of the function. 5452</li> 5453 5454<li><b><code>nparams</code>: </b> 5455the number of fixed parameters of the function 5456(always 0 for C functions). 5457</li> 5458 5459<li><b><code>isvararg</code>: </b> 5460true if the function is a vararg function 5461(always true for C functions). 5462</li> 5463 5464</ul> 5465 5466 5467 5468 5469<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> 5470<span class="apii">[-0, +0, –]</span> 5471<pre>lua_Hook lua_gethook (lua_State *L);</pre> 5472 5473<p> 5474Returns the current hook function. 5475 5476 5477 5478 5479 5480<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> 5481<span class="apii">[-0, +0, –]</span> 5482<pre>int lua_gethookcount (lua_State *L);</pre> 5483 5484<p> 5485Returns the current hook count. 5486 5487 5488 5489 5490 5491<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> 5492<span class="apii">[-0, +0, –]</span> 5493<pre>int lua_gethookmask (lua_State *L);</pre> 5494 5495<p> 5496Returns the current hook mask. 5497 5498 5499 5500 5501 5502<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> 5503<span class="apii">[-(0|1), +(0|1|2), <em>e</em>]</span> 5504<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> 5505 5506<p> 5507Gets information about a specific function or function invocation. 5508 5509 5510<p> 5511To get information about a function invocation, 5512the parameter <code>ar</code> must be a valid activation record that was 5513filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 5514given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 5515 5516 5517<p> 5518To get information about a function you push it onto the stack 5519and start the <code>what</code> string with the character '<code>></code>'. 5520(In that case, 5521<code>lua_getinfo</code> pops the function from the top of the stack.) 5522For instance, to know in which line a function <code>f</code> was defined, 5523you can write the following code: 5524 5525<pre> 5526 lua_Debug ar; 5527 lua_getglobal(L, "f"); /* get global 'f' */ 5528 lua_getinfo(L, ">S", &ar); 5529 printf("%d\n", ar.linedefined); 5530</pre> 5531 5532<p> 5533Each character in the string <code>what</code> 5534selects some fields of the structure <code>ar</code> to be filled or 5535a value to be pushed on the stack: 5536 5537<ul> 5538 5539<li><b>'<code>n</code>': </b> fills in the field <code>name</code> and <code>namewhat</code>; 5540</li> 5541 5542<li><b>'<code>S</code>': </b> 5543fills in the fields <code>source</code>, <code>short_src</code>, 5544<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; 5545</li> 5546 5547<li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>; 5548</li> 5549 5550<li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>; 5551</li> 5552 5553<li><b>'<code>u</code>': </b> fills in the fields 5554<code>nups</code>, <code>nparams</code>, and <code>isvararg</code>; 5555</li> 5556 5557<li><b>'<code>f</code>': </b> 5558pushes onto the stack the function that is 5559running at the given level; 5560</li> 5561 5562<li><b>'<code>L</code>': </b> 5563pushes onto the stack a table whose indices are the 5564numbers of the lines that are valid on the function. 5565(A <em>valid line</em> is a line with some associated code, 5566that is, a line where you can put a break point. 5567Non-valid lines include empty lines and comments.) 5568 5569 5570<p> 5571If this option is given together with option '<code>f</code>', 5572its table is pushed after the function. 5573</li> 5574 5575</ul> 5576 5577<p> 5578This function returns 0 on error 5579(for instance, an invalid option in <code>what</code>). 5580 5581 5582 5583 5584 5585<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> 5586<span class="apii">[-0, +(0|1), –]</span> 5587<pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 5588 5589<p> 5590Gets information about a local variable of 5591a given activation record or a given function. 5592 5593 5594<p> 5595In the first case, 5596the parameter <code>ar</code> must be a valid activation record that was 5597filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 5598given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 5599The index <code>n</code> selects which local variable to inspect; 5600see <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices 5601and names. 5602 5603 5604<p> 5605<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack 5606and returns its name. 5607 5608 5609<p> 5610In the second case, <code>ar</code> must be <code>NULL</code> and the function 5611to be inspected must be at the top of the stack. 5612In this case, only parameters of Lua functions are visible 5613(as there is no information about what variables are active) 5614and no values are pushed onto the stack. 5615 5616 5617<p> 5618Returns <code>NULL</code> (and pushes nothing) 5619when the index is greater than 5620the number of active local variables. 5621 5622 5623 5624 5625 5626<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> 5627<span class="apii">[-0, +0, –]</span> 5628<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> 5629 5630<p> 5631Gets information about the interpreter runtime stack. 5632 5633 5634<p> 5635This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with 5636an identification of the <em>activation record</em> 5637of the function executing at a given level. 5638Level 0 is the current running function, 5639whereas level <em>n+1</em> is the function that has called level <em>n</em> 5640(except for tail calls, which do not count on the stack). 5641When there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1; 5642when called with a level greater than the stack depth, 5643it returns 0. 5644 5645 5646 5647 5648 5649<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> 5650<span class="apii">[-0, +(0|1), –]</span> 5651<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> 5652 5653<p> 5654Gets information about the <code>n</code>-th upvalue 5655of the closure at index <code>funcindex</code>. 5656It pushes the upvalue's value onto the stack 5657and returns its name. 5658Returns <code>NULL</code> (and pushes nothing) 5659when the index <code>n</code> is greater than the number of upvalues. 5660 5661 5662<p> 5663For C functions, this function uses the empty string <code>""</code> 5664as a name for all upvalues. 5665(For Lua functions, 5666upvalues are the external local variables that the function uses, 5667and that are consequently included in its closure.) 5668 5669 5670<p> 5671Upvalues have no particular order, 5672as they are active through the whole function. 5673They are numbered in an arbitrary order. 5674 5675 5676 5677 5678 5679<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> 5680<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> 5681 5682<p> 5683Type for debugging hook functions. 5684 5685 5686<p> 5687Whenever a hook is called, its <code>ar</code> argument has its field 5688<code>event</code> set to the specific event that triggered the hook. 5689Lua identifies these events with the following constants: 5690<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, 5691<a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, 5692and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. 5693Moreover, for line events, the field <code>currentline</code> is also set. 5694To get the value of any other field in <code>ar</code>, 5695the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 5696 5697 5698<p> 5699For call events, <code>event</code> can be <code>LUA_HOOKCALL</code>, 5700the normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call; 5701in this case, there will be no corresponding return event. 5702 5703 5704<p> 5705While Lua is running a hook, it disables other calls to hooks. 5706Therefore, if a hook calls back Lua to execute a function or a chunk, 5707this execution occurs without any calls to hooks. 5708 5709 5710<p> 5711Hook functions cannot have continuations, 5712that is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5713<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>. 5714 5715 5716<p> 5717Hook functions can yield under the following conditions: 5718Only count and line events can yield; 5719to yield, a hook function must finish its execution 5720calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero 5721(that is, with no values). 5722 5723 5724 5725 5726 5727<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> 5728<span class="apii">[-0, +0, –]</span> 5729<pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> 5730 5731<p> 5732Sets the debugging hook function. 5733 5734 5735<p> 5736Argument <code>f</code> is the hook function. 5737<code>mask</code> specifies on which events the hook will be called: 5738it is formed by a bitwise OR of the constants 5739<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, 5740<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, 5741<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, 5742and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. 5743The <code>count</code> argument is only meaningful when the mask 5744includes <code>LUA_MASKCOUNT</code>. 5745For each event, the hook is called as explained below: 5746 5747<ul> 5748 5749<li><b>The call hook: </b> is called when the interpreter calls a function. 5750The hook is called just after Lua enters the new function, 5751before the function gets its arguments. 5752</li> 5753 5754<li><b>The return hook: </b> is called when the interpreter returns from a function. 5755The hook is called just before Lua leaves the function. 5756There is no standard way to access the values 5757to be returned by the function. 5758</li> 5759 5760<li><b>The line hook: </b> is called when the interpreter is about to 5761start the execution of a new line of code, 5762or when it jumps back in the code (even to the same line). 5763(This event only happens while Lua is executing a Lua function.) 5764</li> 5765 5766<li><b>The count hook: </b> is called after the interpreter executes every 5767<code>count</code> instructions. 5768(This event only happens while Lua is executing a Lua function.) 5769</li> 5770 5771</ul> 5772 5773<p> 5774A hook is disabled by setting <code>mask</code> to zero. 5775 5776 5777 5778 5779 5780<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> 5781<span class="apii">[-(0|1), +0, –]</span> 5782<pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 5783 5784<p> 5785Sets the value of a local variable of a given activation record. 5786It assigns the value at the top of the stack 5787to the variable and returns its name. 5788It also pops the value from the stack. 5789 5790 5791<p> 5792Returns <code>NULL</code> (and pops nothing) 5793when the index is greater than 5794the number of active local variables. 5795 5796 5797<p> 5798Parameters <code>ar</code> and <code>n</code> are as in function <a href="#lua_getlocal"><code>lua_getlocal</code></a>. 5799 5800 5801 5802 5803 5804<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> 5805<span class="apii">[-(0|1), +0, –]</span> 5806<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> 5807 5808<p> 5809Sets the value of a closure's upvalue. 5810It assigns the value at the top of the stack 5811to the upvalue and returns its name. 5812It also pops the value from the stack. 5813 5814 5815<p> 5816Returns <code>NULL</code> (and pops nothing) 5817when the index <code>n</code> is greater than the number of upvalues. 5818 5819 5820<p> 5821Parameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>. 5822 5823 5824 5825 5826 5827<hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p> 5828<span class="apii">[-0, +0, –]</span> 5829<pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre> 5830 5831<p> 5832Returns a unique identifier for the upvalue numbered <code>n</code> 5833from the closure at index <code>funcindex</code>. 5834 5835 5836<p> 5837These unique identifiers allow a program to check whether different 5838closures share upvalues. 5839Lua closures that share an upvalue 5840(that is, that access a same external local variable) 5841will return identical ids for those upvalue indices. 5842 5843 5844<p> 5845Parameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, 5846but <code>n</code> cannot be greater than the number of upvalues. 5847 5848 5849 5850 5851 5852<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p> 5853<span class="apii">[-0, +0, –]</span> 5854<pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1, 5855 int funcindex2, int n2);</pre> 5856 5857<p> 5858Make the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code> 5859refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>. 5860 5861 5862 5863 5864 5865 5866 5867<h1>5 – <a name="5">The Auxiliary Library</a></h1> 5868 5869<p> 5870 5871The <em>auxiliary library</em> provides several convenient functions 5872to interface C with Lua. 5873While the basic API provides the primitive functions for all 5874interactions between C and Lua, 5875the auxiliary library provides higher-level functions for some 5876common tasks. 5877 5878 5879<p> 5880All functions and types from the auxiliary library 5881are defined in header file <code>lauxlib.h</code> and 5882have a prefix <code>luaL_</code>. 5883 5884 5885<p> 5886All functions in the auxiliary library are built on 5887top of the basic API, 5888and so they provide nothing that cannot be done with that API. 5889Nevertheless, the use of the auxiliary library ensures 5890more consistency to your code. 5891 5892 5893<p> 5894Several functions in the auxiliary library use internally some 5895extra stack slots. 5896When a function in the auxiliary library uses less than five slots, 5897it does not check the stack size; 5898it simply assumes that there are enough slots. 5899 5900 5901<p> 5902Several functions in the auxiliary library are used to 5903check C function arguments. 5904Because the error message is formatted for arguments 5905(e.g., "<code>bad argument #1</code>"), 5906you should not use these functions for other stack values. 5907 5908 5909<p> 5910Functions called <code>luaL_check*</code> 5911always raise an error if the check is not satisfied. 5912 5913 5914 5915<h2>5.1 – <a name="5.1">Functions and Types</a></h2> 5916 5917<p> 5918Here we list all functions and types from the auxiliary library 5919in alphabetical order. 5920 5921 5922 5923<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> 5924<span class="apii">[-?, +?, <em>m</em>]</span> 5925<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> 5926 5927<p> 5928Adds the byte <code>c</code> to the buffer <code>B</code> 5929(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5930 5931 5932 5933 5934 5935<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> 5936<span class="apii">[-?, +?, <em>m</em>]</span> 5937<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> 5938 5939<p> 5940Adds the string pointed to by <code>s</code> with length <code>l</code> to 5941the buffer <code>B</code> 5942(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5943The string can contain embedded zeros. 5944 5945 5946 5947 5948 5949<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> 5950<span class="apii">[-?, +?, –]</span> 5951<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> 5952 5953<p> 5954Adds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>) 5955a string of length <code>n</code> previously copied to the 5956buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). 5957 5958 5959 5960 5961 5962<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> 5963<span class="apii">[-?, +?, <em>m</em>]</span> 5964<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> 5965 5966<p> 5967Adds the zero-terminated string pointed to by <code>s</code> 5968to the buffer <code>B</code> 5969(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5970 5971 5972 5973 5974 5975<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> 5976<span class="apii">[-1, +?, <em>m</em>]</span> 5977<pre>void luaL_addvalue (luaL_Buffer *B);</pre> 5978 5979<p> 5980Adds the value at the top of the stack 5981to the buffer <code>B</code> 5982(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5983Pops the value. 5984 5985 5986<p> 5987This is the only function on string buffers that can (and must) 5988be called with an extra element on the stack, 5989which is the value to be added to the buffer. 5990 5991 5992 5993 5994 5995<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> 5996<span class="apii">[-0, +0, <em>v</em>]</span> 5997<pre>void luaL_argcheck (lua_State *L, 5998 int cond, 5999 int arg, 6000 const char *extramsg);</pre> 6001 6002<p> 6003Checks whether <code>cond</code> is true. 6004If it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>). 6005 6006 6007 6008 6009 6010<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> 6011<span class="apii">[-0, +0, <em>v</em>]</span> 6012<pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre> 6013 6014<p> 6015Raises an error reporting a problem with argument <code>arg</code> 6016of the C function that called it, 6017using a standard message 6018that includes <code>extramsg</code> as a comment: 6019 6020<pre> 6021 bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>) 6022</pre><p> 6023This function never returns. 6024 6025 6026 6027 6028 6029<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> 6030<pre>typedef struct luaL_Buffer luaL_Buffer;</pre> 6031 6032<p> 6033Type for a <em>string buffer</em>. 6034 6035 6036<p> 6037A string buffer allows C code to build Lua strings piecemeal. 6038Its pattern of use is as follows: 6039 6040<ul> 6041 6042<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6043 6044<li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> 6045 6046<li> 6047Then add string pieces to the buffer calling any of 6048the <code>luaL_add*</code> functions. 6049</li> 6050 6051<li> 6052Finish by calling <code>luaL_pushresult(&b)</code>. 6053This call leaves the final string on the top of the stack. 6054</li> 6055 6056</ul> 6057 6058<p> 6059If you know beforehand the total size of the resulting string, 6060you can use the buffer like this: 6061 6062<ul> 6063 6064<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6065 6066<li>Then initialize it and preallocate a space of 6067size <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li> 6068 6069<li>Then copy the string into that space.</li> 6070 6071<li> 6072Finish by calling <code>luaL_pushresultsize(&b, sz)</code>, 6073where <code>sz</code> is the total size of the resulting string 6074copied into that space. 6075</li> 6076 6077</ul> 6078 6079<p> 6080During its normal operation, 6081a string buffer uses a variable number of stack slots. 6082So, while using a buffer, you cannot assume that you know where 6083the top of the stack is. 6084You can use the stack between successive calls to buffer operations 6085as long as that use is balanced; 6086that is, 6087when you call a buffer operation, 6088the stack is at the same level 6089it was immediately after the previous buffer operation. 6090(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) 6091After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its 6092level when the buffer was initialized, 6093plus the final string on its top. 6094 6095 6096 6097 6098 6099<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> 6100<span class="apii">[-0, +0, –]</span> 6101<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> 6102 6103<p> 6104Initializes a buffer <code>B</code>. 6105This function does not allocate any space; 6106the buffer must be declared as a variable 6107(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6108 6109 6110 6111 6112 6113<hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p> 6114<span class="apii">[-?, +?, <em>m</em>]</span> 6115<pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre> 6116 6117<p> 6118Equivalent to the sequence 6119<a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>. 6120 6121 6122 6123 6124 6125<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> 6126<span class="apii">[-0, +(0|1), <em>e</em>]</span> 6127<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> 6128 6129<p> 6130Calls a metamethod. 6131 6132 6133<p> 6134If the object at index <code>obj</code> has a metatable and this 6135metatable has a field <code>e</code>, 6136this function calls this field passing the object as its only argument. 6137In this case this function returns true and pushes onto the 6138stack the value returned by the call. 6139If there is no metatable or no metamethod, 6140this function returns false (without pushing any value on the stack). 6141 6142 6143 6144 6145 6146<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> 6147<span class="apii">[-0, +0, <em>v</em>]</span> 6148<pre>void luaL_checkany (lua_State *L, int arg);</pre> 6149 6150<p> 6151Checks whether the function has an argument 6152of any type (including <b>nil</b>) at position <code>arg</code>. 6153 6154 6155 6156 6157 6158<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> 6159<span class="apii">[-0, +0, <em>v</em>]</span> 6160<pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre> 6161 6162<p> 6163Checks whether the function argument <code>arg</code> is an integer 6164(or can be converted to an integer) 6165and returns this integer cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. 6166 6167 6168 6169 6170 6171<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> 6172<span class="apii">[-0, +0, <em>v</em>]</span> 6173<pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre> 6174 6175<p> 6176Checks whether the function argument <code>arg</code> is a string 6177and returns this string; 6178if <code>l</code> is not <code>NULL</code> fills <code>*l</code> 6179with the string's length. 6180 6181 6182<p> 6183This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6184so all conversions and caveats of that function apply here. 6185 6186 6187 6188 6189 6190<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> 6191<span class="apii">[-0, +0, <em>v</em>]</span> 6192<pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre> 6193 6194<p> 6195Checks whether the function argument <code>arg</code> is a number 6196and returns this number. 6197 6198 6199 6200 6201 6202<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> 6203<span class="apii">[-0, +0, <em>v</em>]</span> 6204<pre>int luaL_checkoption (lua_State *L, 6205 int arg, 6206 const char *def, 6207 const char *const lst[]);</pre> 6208 6209<p> 6210Checks whether the function argument <code>arg</code> is a string and 6211searches for this string in the array <code>lst</code> 6212(which must be NULL-terminated). 6213Returns the index in the array where the string was found. 6214Raises an error if the argument is not a string or 6215if the string cannot be found. 6216 6217 6218<p> 6219If <code>def</code> is not <code>NULL</code>, 6220the function uses <code>def</code> as a default value when 6221there is no argument <code>arg</code> or when this argument is <b>nil</b>. 6222 6223 6224<p> 6225This is a useful function for mapping strings to C enums. 6226(The usual convention in Lua libraries is 6227to use strings instead of numbers to select options.) 6228 6229 6230 6231 6232 6233<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> 6234<span class="apii">[-0, +0, <em>v</em>]</span> 6235<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> 6236 6237<p> 6238Grows the stack size to <code>top + sz</code> elements, 6239raising an error if the stack cannot grow to that size. 6240<code>msg</code> is an additional text to go into the error message 6241(or <code>NULL</code> for no additional text). 6242 6243 6244 6245 6246 6247<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> 6248<span class="apii">[-0, +0, <em>v</em>]</span> 6249<pre>const char *luaL_checkstring (lua_State *L, int arg);</pre> 6250 6251<p> 6252Checks whether the function argument <code>arg</code> is a string 6253and returns this string. 6254 6255 6256<p> 6257This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6258so all conversions and caveats of that function apply here. 6259 6260 6261 6262 6263 6264<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> 6265<span class="apii">[-0, +0, <em>v</em>]</span> 6266<pre>void luaL_checktype (lua_State *L, int arg, int t);</pre> 6267 6268<p> 6269Checks whether the function argument <code>arg</code> has type <code>t</code>. 6270See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. 6271 6272 6273 6274 6275 6276<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> 6277<span class="apii">[-0, +0, <em>v</em>]</span> 6278<pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre> 6279 6280<p> 6281Checks whether the function argument <code>arg</code> is a userdata 6282of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and 6283returns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>). 6284 6285 6286 6287 6288 6289<hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p> 6290<span class="apii">[-0, +0, <em>v</em>]</span> 6291<pre>void luaL_checkversion (lua_State *L);</pre> 6292 6293<p> 6294Checks whether the core running the call, 6295the core that created the Lua state, 6296and the code making the call are all using the same version of Lua. 6297Also checks whether the core running the call 6298and the core that created the Lua state 6299are using the same address space. 6300 6301 6302 6303 6304 6305<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> 6306<span class="apii">[-0, +?, <em>e</em>]</span> 6307<pre>int luaL_dofile (lua_State *L, const char *filename);</pre> 6308 6309<p> 6310Loads and runs the given file. 6311It is defined as the following macro: 6312 6313<pre> 6314 (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6315</pre><p> 6316It returns false if there are no errors 6317or true in case of errors. 6318 6319 6320 6321 6322 6323<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> 6324<span class="apii">[-0, +?, –]</span> 6325<pre>int luaL_dostring (lua_State *L, const char *str);</pre> 6326 6327<p> 6328Loads and runs the given string. 6329It is defined as the following macro: 6330 6331<pre> 6332 (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6333</pre><p> 6334It returns false if there are no errors 6335or true in case of errors. 6336 6337 6338 6339 6340 6341<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> 6342<span class="apii">[-0, +0, <em>v</em>]</span> 6343<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> 6344 6345<p> 6346Raises an error. 6347The error message format is given by <code>fmt</code> 6348plus any extra arguments, 6349following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. 6350It also adds at the beginning of the message the file name and 6351the line number where the error occurred, 6352if this information is available. 6353 6354 6355<p> 6356This function never returns, 6357but it is an idiom to use it in C functions 6358as <code>return luaL_error(<em>args</em>)</code>. 6359 6360 6361 6362 6363 6364<hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p> 6365<span class="apii">[-0, +3, <em>m</em>]</span> 6366<pre>int luaL_execresult (lua_State *L, int stat);</pre> 6367 6368<p> 6369This function produces the return values for 6370process-related functions in the standard library 6371(<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>). 6372 6373 6374 6375 6376 6377<hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p> 6378<span class="apii">[-0, +(1|3), <em>m</em>]</span> 6379<pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre> 6380 6381<p> 6382This function produces the return values for 6383file-related functions in the standard library 6384(<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.). 6385 6386 6387 6388 6389 6390<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> 6391<span class="apii">[-0, +(0|1), <em>m</em>]</span> 6392<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> 6393 6394<p> 6395Pushes onto the stack the field <code>e</code> from the metatable 6396of the object at index <code>obj</code> and returns the type of pushed value. 6397If the object does not have a metatable, 6398or if the metatable does not have this field, 6399pushes nothing and returns <code>LUA_TNIL</code>. 6400 6401 6402 6403 6404 6405<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> 6406<span class="apii">[-0, +1, <em>m</em>]</span> 6407<pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre> 6408 6409<p> 6410Pushes onto the stack the metatable associated with name <code>tname</code> 6411in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) 6412(<b>nil</b> if there is no metatable associated with that name). 6413Returns the type of the pushed value. 6414 6415 6416 6417 6418 6419<hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p> 6420<span class="apii">[-0, +1, <em>e</em>]</span> 6421<pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre> 6422 6423<p> 6424Ensures that the value <code>t[fname]</code>, 6425where <code>t</code> is the value at index <code>idx</code>, 6426is a table, 6427and pushes that table onto the stack. 6428Returns true if it finds a previous table there 6429and false if it creates a new table. 6430 6431 6432 6433 6434 6435<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> 6436<span class="apii">[-0, +1, <em>m</em>]</span> 6437<pre>const char *luaL_gsub (lua_State *L, 6438 const char *s, 6439 const char *p, 6440 const char *r);</pre> 6441 6442<p> 6443Creates a copy of string <code>s</code> by replacing 6444any occurrence of the string <code>p</code> 6445with the string <code>r</code>. 6446Pushes the resulting string on the stack and returns it. 6447 6448 6449 6450 6451 6452<hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p> 6453<span class="apii">[-0, +0, <em>e</em>]</span> 6454<pre>lua_Integer luaL_len (lua_State *L, int index);</pre> 6455 6456<p> 6457Returns the "length" of the value at the given index 6458as a number; 6459it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). 6460Raises an error if the result of the operation is not an integer. 6461(This case only can happen through metamethods.) 6462 6463 6464 6465 6466 6467<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> 6468<span class="apii">[-0, +1, –]</span> 6469<pre>int luaL_loadbuffer (lua_State *L, 6470 const char *buff, 6471 size_t sz, 6472 const char *name);</pre> 6473 6474<p> 6475Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>. 6476 6477 6478 6479 6480 6481<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p> 6482<span class="apii">[-0, +1, –]</span> 6483<pre>int luaL_loadbufferx (lua_State *L, 6484 const char *buff, 6485 size_t sz, 6486 const char *name, 6487 const char *mode);</pre> 6488 6489<p> 6490Loads a buffer as a Lua chunk. 6491This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the 6492buffer pointed to by <code>buff</code> with size <code>sz</code>. 6493 6494 6495<p> 6496This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 6497<code>name</code> is the chunk name, 6498used for debug information and error messages. 6499The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. 6500 6501 6502 6503 6504 6505<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> 6506<span class="apii">[-0, +1, <em>m</em>]</span> 6507<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> 6508 6509<p> 6510Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>. 6511 6512 6513 6514 6515 6516<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p> 6517<span class="apii">[-0, +1, <em>m</em>]</span> 6518<pre>int luaL_loadfilex (lua_State *L, const char *filename, 6519 const char *mode);</pre> 6520 6521<p> 6522Loads a file as a Lua chunk. 6523This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file 6524named <code>filename</code>. 6525If <code>filename</code> is <code>NULL</code>, 6526then it loads from the standard input. 6527The first line in the file is ignored if it starts with a <code>#</code>. 6528 6529 6530<p> 6531The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. 6532 6533 6534<p> 6535This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, 6536but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> 6537if it cannot open/read the file or the file has a wrong mode. 6538 6539 6540<p> 6541As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 6542it does not run it. 6543 6544 6545 6546 6547 6548<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> 6549<span class="apii">[-0, +1, –]</span> 6550<pre>int luaL_loadstring (lua_State *L, const char *s);</pre> 6551 6552<p> 6553Loads a string as a Lua chunk. 6554This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in 6555the zero-terminated string <code>s</code>. 6556 6557 6558<p> 6559This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 6560 6561 6562<p> 6563Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 6564it does not run it. 6565 6566 6567 6568 6569 6570<hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p> 6571<span class="apii">[-0, +1, <em>m</em>]</span> 6572<pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre> 6573 6574<p> 6575Creates a new table and registers there 6576the functions in list <code>l</code>. 6577 6578 6579<p> 6580It is implemented as the following macro: 6581 6582<pre> 6583 (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0)) 6584</pre><p> 6585The array <code>l</code> must be the actual array, 6586not a pointer to it. 6587 6588 6589 6590 6591 6592<hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p> 6593<span class="apii">[-0, +1, <em>m</em>]</span> 6594<pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre> 6595 6596<p> 6597Creates a new table with a size optimized 6598to store all entries in the array <code>l</code> 6599(but does not actually store them). 6600It is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> 6601(see <a href="#luaL_newlib"><code>luaL_newlib</code></a>). 6602 6603 6604<p> 6605It is implemented as a macro. 6606The array <code>l</code> must be the actual array, 6607not a pointer to it. 6608 6609 6610 6611 6612 6613<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> 6614<span class="apii">[-0, +1, <em>m</em>]</span> 6615<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> 6616 6617<p> 6618If the registry already has the key <code>tname</code>, 6619returns 0. 6620Otherwise, 6621creates a new table to be used as a metatable for userdata, 6622adds to this new table the pair <code>__name = tname</code>, 6623adds to the registry the pair <code>[tname] = new table</code>, 6624and returns 1. 6625(The entry <code>__name</code> is used by some error-reporting functions.) 6626 6627 6628<p> 6629In both cases pushes onto the stack the final value associated 6630with <code>tname</code> in the registry. 6631 6632 6633 6634 6635 6636<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> 6637<span class="apii">[-0, +0, –]</span> 6638<pre>lua_State *luaL_newstate (void);</pre> 6639 6640<p> 6641Creates a new Lua state. 6642It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an 6643allocator based on the standard C <code>realloc</code> function 6644and then sets a panic function (see <a href="#4.6">§4.6</a>) that prints 6645an error message to the standard error output in case of fatal 6646errors. 6647 6648 6649<p> 6650Returns the new state, 6651or <code>NULL</code> if there is a memory allocation error. 6652 6653 6654 6655 6656 6657<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> 6658<span class="apii">[-0, +0, <em>e</em>]</span> 6659<pre>void luaL_openlibs (lua_State *L);</pre> 6660 6661<p> 6662Opens all standard Lua libraries into the given state. 6663 6664 6665 6666 6667 6668<hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p> 6669<span class="apii">[-0, +0, <em>e</em>]</span> 6670<pre>T luaL_opt (L, func, arg, dflt);</pre> 6671 6672<p> 6673This macro is defined as follows: 6674 6675<pre> 6676 (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg))) 6677</pre><p> 6678In words, if the argument <code>arg</code> is nil or absent, 6679the macro results in the default <code>dflt</code>. 6680Otherwise, it results in the result of calling <code>func</code> 6681with the state <code>L</code> and the argument index <code>arg</code> as 6682parameters. 6683Note that it evaluates the expression <code>dflt</code> only if needed. 6684 6685 6686 6687 6688 6689<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> 6690<span class="apii">[-0, +0, <em>v</em>]</span> 6691<pre>lua_Integer luaL_optinteger (lua_State *L, 6692 int arg, 6693 lua_Integer d);</pre> 6694 6695<p> 6696If the function argument <code>arg</code> is an integer 6697(or convertible to an integer), 6698returns this integer. 6699If this argument is absent or is <b>nil</b>, 6700returns <code>d</code>. 6701Otherwise, raises an error. 6702 6703 6704 6705 6706 6707<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> 6708<span class="apii">[-0, +0, <em>v</em>]</span> 6709<pre>const char *luaL_optlstring (lua_State *L, 6710 int arg, 6711 const char *d, 6712 size_t *l);</pre> 6713 6714<p> 6715If the function argument <code>arg</code> is a string, 6716returns this string. 6717If this argument is absent or is <b>nil</b>, 6718returns <code>d</code>. 6719Otherwise, raises an error. 6720 6721 6722<p> 6723If <code>l</code> is not <code>NULL</code>, 6724fills the position <code>*l</code> with the result's length. 6725If the result is <code>NULL</code> 6726(only possible when returning <code>d</code> and <code>d == NULL</code>), 6727its length is considered zero. 6728 6729 6730 6731 6732 6733<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> 6734<span class="apii">[-0, +0, <em>v</em>]</span> 6735<pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre> 6736 6737<p> 6738If the function argument <code>arg</code> is a number, 6739returns this number. 6740If this argument is absent or is <b>nil</b>, 6741returns <code>d</code>. 6742Otherwise, raises an error. 6743 6744 6745 6746 6747 6748<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> 6749<span class="apii">[-0, +0, <em>v</em>]</span> 6750<pre>const char *luaL_optstring (lua_State *L, 6751 int arg, 6752 const char *d);</pre> 6753 6754<p> 6755If the function argument <code>arg</code> is a string, 6756returns this string. 6757If this argument is absent or is <b>nil</b>, 6758returns <code>d</code>. 6759Otherwise, raises an error. 6760 6761 6762 6763 6764 6765<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> 6766<span class="apii">[-?, +?, <em>m</em>]</span> 6767<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> 6768 6769<p> 6770Equivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a> 6771with the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>. 6772 6773 6774 6775 6776 6777<hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p> 6778<span class="apii">[-?, +?, <em>m</em>]</span> 6779<pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre> 6780 6781<p> 6782Returns an address to a space of size <code>sz</code> 6783where you can copy a string to be added to buffer <code>B</code> 6784(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6785After copying the string into this space you must call 6786<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add 6787it to the buffer. 6788 6789 6790 6791 6792 6793<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> 6794<span class="apii">[-?, +1, <em>m</em>]</span> 6795<pre>void luaL_pushresult (luaL_Buffer *B);</pre> 6796 6797<p> 6798Finishes the use of buffer <code>B</code> leaving the final string on 6799the top of the stack. 6800 6801 6802 6803 6804 6805<hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p> 6806<span class="apii">[-?, +1, <em>m</em>]</span> 6807<pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre> 6808 6809<p> 6810Equivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>. 6811 6812 6813 6814 6815 6816<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> 6817<span class="apii">[-1, +0, <em>m</em>]</span> 6818<pre>int luaL_ref (lua_State *L, int t);</pre> 6819 6820<p> 6821Creates and returns a <em>reference</em>, 6822in the table at index <code>t</code>, 6823for the object at the top of the stack (and pops the object). 6824 6825 6826<p> 6827A reference is a unique integer key. 6828As long as you do not manually add integer keys into table <code>t</code>, 6829<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. 6830You can retrieve an object referred by reference <code>r</code> 6831by calling <code>lua_rawgeti(L, t, r)</code>. 6832Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object. 6833 6834 6835<p> 6836If the object at the top of the stack is <b>nil</b>, 6837<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>. 6838The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different 6839from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. 6840 6841 6842 6843 6844 6845<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> 6846<pre>typedef struct luaL_Reg { 6847 const char *name; 6848 lua_CFunction func; 6849} luaL_Reg;</pre> 6850 6851<p> 6852Type for arrays of functions to be registered by 6853<a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>. 6854<code>name</code> is the function name and <code>func</code> is a pointer to 6855the function. 6856Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry 6857in which both <code>name</code> and <code>func</code> are <code>NULL</code>. 6858 6859 6860 6861 6862 6863<hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p> 6864<span class="apii">[-0, +1, <em>e</em>]</span> 6865<pre>void luaL_requiref (lua_State *L, const char *modname, 6866 lua_CFunction openf, int glb);</pre> 6867 6868<p> 6869If <code>modname</code> is not already present in <a href="#pdf-package.loaded"><code>package.loaded</code></a>, 6870calls function <code>openf</code> with string <code>modname</code> as an argument 6871and sets the call result in <code>package.loaded[modname]</code>, 6872as if that function has been called through <a href="#pdf-require"><code>require</code></a>. 6873 6874 6875<p> 6876If <code>glb</code> is true, 6877also stores the module into global <code>modname</code>. 6878 6879 6880<p> 6881Leaves a copy of the module on the stack. 6882 6883 6884 6885 6886 6887<hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p> 6888<span class="apii">[-nup, +0, <em>m</em>]</span> 6889<pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre> 6890 6891<p> 6892Registers all functions in the array <code>l</code> 6893(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack 6894(below optional upvalues, see next). 6895 6896 6897<p> 6898When <code>nup</code> is not zero, 6899all functions are created sharing <code>nup</code> upvalues, 6900which must be previously pushed on the stack 6901on top of the library table. 6902These values are popped from the stack after the registration. 6903 6904 6905 6906 6907 6908<hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p> 6909<span class="apii">[-0, +0, –]</span> 6910<pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre> 6911 6912<p> 6913Sets the metatable of the object at the top of the stack 6914as the metatable associated with name <code>tname</code> 6915in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 6916 6917 6918 6919 6920 6921<hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3> 6922<pre>typedef struct luaL_Stream { 6923 FILE *f; 6924 lua_CFunction closef; 6925} luaL_Stream;</pre> 6926 6927<p> 6928The standard representation for file handles, 6929which is used by the standard I/O library. 6930 6931 6932<p> 6933A file handle is implemented as a full userdata, 6934with a metatable called <code>LUA_FILEHANDLE</code> 6935(where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name). 6936The metatable is created by the I/O library 6937(see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 6938 6939 6940<p> 6941This userdata must start with the structure <code>luaL_Stream</code>; 6942it can contain other data after this initial structure. 6943Field <code>f</code> points to the corresponding C stream 6944(or it can be <code>NULL</code> to indicate an incompletely created handle). 6945Field <code>closef</code> points to a Lua function 6946that will be called to close the stream 6947when the handle is closed or collected; 6948this function receives the file handle as its sole argument and 6949must return either <b>true</b> (in case of success) 6950or <b>nil</b> plus an error message (in case of error). 6951Once Lua calls this field, 6952it changes the field value to <code>NULL</code> 6953to signal that the handle is closed. 6954 6955 6956 6957 6958 6959<hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p> 6960<span class="apii">[-0, +0, <em>m</em>]</span> 6961<pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre> 6962 6963<p> 6964This function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>, 6965except that, when the test fails, 6966it returns <code>NULL</code> instead of raising an error. 6967 6968 6969 6970 6971 6972<hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p> 6973<span class="apii">[-0, +1, <em>e</em>]</span> 6974<pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre> 6975 6976<p> 6977Converts any Lua value at the given index to a C string 6978in a reasonable format. 6979The resulting string is pushed onto the stack and also 6980returned by the function. 6981If <code>len</code> is not <code>NULL</code>, 6982the function also sets <code>*len</code> with the string length. 6983 6984 6985<p> 6986If the value has a metatable with a <code>__tostring</code> field, 6987then <code>luaL_tolstring</code> calls the corresponding metamethod 6988with the value as argument, 6989and uses the result of the call as its result. 6990 6991 6992 6993 6994 6995<hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p> 6996<span class="apii">[-0, +1, <em>m</em>]</span> 6997<pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, 6998 int level);</pre> 6999 7000<p> 7001Creates and pushes a traceback of the stack <code>L1</code>. 7002If <code>msg</code> is not <code>NULL</code> it is appended 7003at the beginning of the traceback. 7004The <code>level</code> parameter tells at which level 7005to start the traceback. 7006 7007 7008 7009 7010 7011<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> 7012<span class="apii">[-0, +0, –]</span> 7013<pre>const char *luaL_typename (lua_State *L, int index);</pre> 7014 7015<p> 7016Returns the name of the type of the value at the given index. 7017 7018 7019 7020 7021 7022<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> 7023<span class="apii">[-0, +0, –]</span> 7024<pre>void luaL_unref (lua_State *L, int t, int ref);</pre> 7025 7026<p> 7027Releases reference <code>ref</code> from the table at index <code>t</code> 7028(see <a href="#luaL_ref"><code>luaL_ref</code></a>). 7029The entry is removed from the table, 7030so that the referred object can be collected. 7031The reference <code>ref</code> is also freed to be used again. 7032 7033 7034<p> 7035If <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>, 7036<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. 7037 7038 7039 7040 7041 7042<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> 7043<span class="apii">[-0, +1, <em>m</em>]</span> 7044<pre>void luaL_where (lua_State *L, int lvl);</pre> 7045 7046<p> 7047Pushes onto the stack a string identifying the current position 7048of the control at level <code>lvl</code> in the call stack. 7049Typically this string has the following format: 7050 7051<pre> 7052 <em>chunkname</em>:<em>currentline</em>: 7053</pre><p> 7054Level 0 is the running function, 7055level 1 is the function that called the running function, 7056etc. 7057 7058 7059<p> 7060This function is used to build a prefix for error messages. 7061 7062 7063 7064 7065 7066 7067 7068<h1>6 – <a name="6">Standard Libraries</a></h1> 7069 7070<p> 7071The standard Lua libraries provide useful functions 7072that are implemented directly through the C API. 7073Some of these functions provide essential services to the language 7074(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); 7075others provide access to "outside" services (e.g., I/O); 7076and others could be implemented in Lua itself, 7077but are quite useful or have critical performance requirements that 7078deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). 7079 7080 7081<p> 7082All libraries are implemented through the official C API 7083and are provided as separate C modules. 7084Currently, Lua has the following standard libraries: 7085 7086<ul> 7087 7088<li>basic library (<a href="#6.1">§6.1</a>);</li> 7089 7090<li>coroutine library (<a href="#6.2">§6.2</a>);</li> 7091 7092<li>package library (<a href="#6.3">§6.3</a>);</li> 7093 7094<li>string manipulation (<a href="#6.4">§6.4</a>);</li> 7095 7096<li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li> 7097 7098<li>table manipulation (<a href="#6.6">§6.6</a>);</li> 7099 7100<li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li> 7101 7102<li>input and output (<a href="#6.8">§6.8</a>);</li> 7103 7104<li>operating system facilities (<a href="#6.9">§6.9</a>);</li> 7105 7106<li>debug facilities (<a href="#6.10">§6.10</a>).</li> 7107 7108</ul><p> 7109Except for the basic and the package libraries, 7110each library provides all its functions as fields of a global table 7111or as methods of its objects. 7112 7113 7114<p> 7115To have access to these libraries, 7116the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, 7117which opens all standard libraries. 7118Alternatively, 7119the host program can open them individually by using 7120<a href="#luaL_requiref"><code>luaL_requiref</code></a> to call 7121<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), 7122<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), 7123<a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library), 7124<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), 7125<a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF8 library), 7126<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), 7127<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), 7128<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), 7129<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library), 7130and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). 7131These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>. 7132 7133 7134 7135<h2>6.1 – <a name="6.1">Basic Functions</a></h2> 7136 7137<p> 7138The basic library provides core functions to Lua. 7139If you do not include this library in your application, 7140you should check carefully whether you need to provide 7141implementations for some of its facilities. 7142 7143 7144<p> 7145<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> 7146 7147 7148<p> 7149Calls <a href="#pdf-error"><code>error</code></a> if 7150the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); 7151otherwise, returns all its arguments. 7152In case of error, 7153<code>message</code> is the error object; 7154when absent, it defaults to "<code>assertion failed!</code>" 7155 7156 7157 7158 7159<p> 7160<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3> 7161 7162 7163<p> 7164This function is a generic interface to the garbage collector. 7165It performs different functions according to its first argument, <code>opt</code>: 7166 7167<ul> 7168 7169<li><b>"<code>collect</code>": </b> 7170performs a full garbage-collection cycle. 7171This is the default option. 7172</li> 7173 7174<li><b>"<code>stop</code>": </b> 7175stops automatic execution of the garbage collector. 7176The collector will run only when explicitly invoked, 7177until a call to restart it. 7178</li> 7179 7180<li><b>"<code>restart</code>": </b> 7181restarts automatic execution of the garbage collector. 7182</li> 7183 7184<li><b>"<code>count</code>": </b> 7185returns the total memory in use by Lua in Kbytes. 7186The value has a fractional part, 7187so that it multiplied by 1024 7188gives the exact number of bytes in use by Lua 7189(except for overflows). 7190</li> 7191 7192<li><b>"<code>step</code>": </b> 7193performs a garbage-collection step. 7194The step "size" is controlled by <code>arg</code>. 7195With a zero value, 7196the collector will perform one basic (indivisible) step. 7197For non-zero values, 7198the collector will perform as if that amount of memory 7199(in KBytes) had been allocated by Lua. 7200Returns <b>true</b> if the step finished a collection cycle. 7201</li> 7202 7203<li><b>"<code>setpause</code>": </b> 7204sets <code>arg</code> as the new value for the <em>pause</em> of 7205the collector (see <a href="#2.5">§2.5</a>). 7206Returns the previous value for <em>pause</em>. 7207</li> 7208 7209<li><b>"<code>setstepmul</code>": </b> 7210sets <code>arg</code> as the new value for the <em>step multiplier</em> of 7211the collector (see <a href="#2.5">§2.5</a>). 7212Returns the previous value for <em>step</em>. 7213</li> 7214 7215<li><b>"<code>isrunning</code>": </b> 7216returns a boolean that tells whether the collector is running 7217(i.e., not stopped). 7218</li> 7219 7220</ul> 7221 7222 7223 7224<p> 7225<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> 7226Opens the named file and executes its contents as a Lua chunk. 7227When called without arguments, 7228<code>dofile</code> executes the contents of the standard input (<code>stdin</code>). 7229Returns all values returned by the chunk. 7230In case of errors, <code>dofile</code> propagates the error 7231to its caller (that is, <code>dofile</code> does not run in protected mode). 7232 7233 7234 7235 7236<p> 7237<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> 7238Terminates the last protected function called 7239and returns <code>message</code> as the error object. 7240Function <code>error</code> never returns. 7241 7242 7243<p> 7244Usually, <code>error</code> adds some information about the error position 7245at the beginning of the message, if the message is a string. 7246The <code>level</code> argument specifies how to get the error position. 7247With level 1 (the default), the error position is where the 7248<code>error</code> function was called. 7249Level 2 points the error to where the function 7250that called <code>error</code> was called; and so on. 7251Passing a level 0 avoids the addition of error position information 7252to the message. 7253 7254 7255 7256 7257<p> 7258<hr><h3><a name="pdf-_G"><code>_G</code></a></h3> 7259A global variable (not a function) that 7260holds the global environment (see <a href="#2.2">§2.2</a>). 7261Lua itself does not use this variable; 7262changing its value does not affect any environment, 7263nor vice versa. 7264 7265 7266 7267 7268<p> 7269<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> 7270 7271 7272<p> 7273If <code>object</code> does not have a metatable, returns <b>nil</b>. 7274Otherwise, 7275if the object's metatable has a <code>__metatable</code> field, 7276returns the associated value. 7277Otherwise, returns the metatable of the given object. 7278 7279 7280 7281 7282<p> 7283<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> 7284 7285 7286<p> 7287Returns three values (an iterator function, the table <code>t</code>, and 0) 7288so that the construction 7289 7290<pre> 7291 for i,v in ipairs(t) do <em>body</em> end 7292</pre><p> 7293will iterate over the key–value pairs 7294(<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., 7295up to the first nil value. 7296 7297 7298 7299 7300<p> 7301<hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3> 7302 7303 7304<p> 7305Loads a chunk. 7306 7307 7308<p> 7309If <code>chunk</code> is a string, the chunk is this string. 7310If <code>chunk</code> is a function, 7311<code>load</code> calls it repeatedly to get the chunk pieces. 7312Each call to <code>chunk</code> must return a string that concatenates 7313with previous results. 7314A return of an empty string, <b>nil</b>, or no value signals the end of the chunk. 7315 7316 7317<p> 7318If there are no syntactic errors, 7319returns the compiled chunk as a function; 7320otherwise, returns <b>nil</b> plus the error message. 7321 7322 7323<p> 7324If the resulting function has upvalues, 7325the first upvalue is set to the value of <code>env</code>, 7326if that parameter is given, 7327or to the value of the global environment. 7328Other upvalues are initialized with <b>nil</b>. 7329(When you load a main chunk, 7330the resulting function will always have exactly one upvalue, 7331the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 7332However, 7333when you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>), 7334the resulting function can have an arbitrary number of upvalues.) 7335All upvalues are fresh, that is, 7336they are not shared with any other function. 7337 7338 7339<p> 7340<code>chunkname</code> is used as the name of the chunk for error messages 7341and debug information (see <a href="#4.9">§4.9</a>). 7342When absent, 7343it defaults to <code>chunk</code>, if <code>chunk</code> is a string, 7344or to "<code>=(load)</code>" otherwise. 7345 7346 7347<p> 7348The string <code>mode</code> controls whether the chunk can be text or binary 7349(that is, a precompiled chunk). 7350It may be the string "<code>b</code>" (only binary chunks), 7351"<code>t</code>" (only text chunks), 7352or "<code>bt</code>" (both binary and text). 7353The default is "<code>bt</code>". 7354 7355 7356<p> 7357Lua does not check the consistency of binary chunks. 7358Maliciously crafted binary chunks can crash 7359the interpreter. 7360 7361 7362 7363 7364<p> 7365<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3> 7366 7367 7368<p> 7369Similar to <a href="#pdf-load"><code>load</code></a>, 7370but gets the chunk from file <code>filename</code> 7371or from the standard input, 7372if no file name is given. 7373 7374 7375 7376 7377<p> 7378<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> 7379 7380 7381<p> 7382Allows a program to traverse all fields of a table. 7383Its first argument is a table and its second argument 7384is an index in this table. 7385<code>next</code> returns the next index of the table 7386and its associated value. 7387When called with <b>nil</b> as its second argument, 7388<code>next</code> returns an initial index 7389and its associated value. 7390When called with the last index, 7391or with <b>nil</b> in an empty table, 7392<code>next</code> returns <b>nil</b>. 7393If the second argument is absent, then it is interpreted as <b>nil</b>. 7394In particular, 7395you can use <code>next(t)</code> to check whether a table is empty. 7396 7397 7398<p> 7399The order in which the indices are enumerated is not specified, 7400<em>even for numeric indices</em>. 7401(To traverse a table in numerical order, 7402use a numerical <b>for</b>.) 7403 7404 7405<p> 7406The behavior of <code>next</code> is undefined if, 7407during the traversal, 7408you assign any value to a non-existent field in the table. 7409You may however modify existing fields. 7410In particular, you may clear existing fields. 7411 7412 7413 7414 7415<p> 7416<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> 7417 7418 7419<p> 7420If <code>t</code> has a metamethod <code>__pairs</code>, 7421calls it with <code>t</code> as argument and returns the first three 7422results from the call. 7423 7424 7425<p> 7426Otherwise, 7427returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, 7428so that the construction 7429 7430<pre> 7431 for k,v in pairs(t) do <em>body</em> end 7432</pre><p> 7433will iterate over all key–value pairs of table <code>t</code>. 7434 7435 7436<p> 7437See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 7438the table during its traversal. 7439 7440 7441 7442 7443<p> 7444<hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3> 7445 7446 7447<p> 7448Calls function <code>f</code> with 7449the given arguments in <em>protected mode</em>. 7450This means that any error inside <code>f</code> is not propagated; 7451instead, <code>pcall</code> catches the error 7452and returns a status code. 7453Its first result is the status code (a boolean), 7454which is true if the call succeeds without errors. 7455In such case, <code>pcall</code> also returns all results from the call, 7456after this first result. 7457In case of any error, <code>pcall</code> returns <b>false</b> plus the error message. 7458 7459 7460 7461 7462<p> 7463<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> 7464Receives any number of arguments 7465and prints their values to <code>stdout</code>, 7466using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string. 7467<code>print</code> is not intended for formatted output, 7468but only as a quick way to show a value, 7469for instance for debugging. 7470For complete control over the output, 7471use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. 7472 7473 7474 7475 7476<p> 7477<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> 7478Checks whether <code>v1</code> is equal to <code>v2</code>, 7479without invoking the <code>__eq</code> metamethod. 7480Returns a boolean. 7481 7482 7483 7484 7485<p> 7486<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> 7487Gets the real value of <code>table[index]</code>, 7488without invoking the <code>__index</code> metamethod. 7489<code>table</code> must be a table; 7490<code>index</code> may be any value. 7491 7492 7493 7494 7495<p> 7496<hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3> 7497Returns the length of the object <code>v</code>, 7498which must be a table or a string, 7499without invoking the <code>__len</code> metamethod. 7500Returns an integer. 7501 7502 7503 7504 7505<p> 7506<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> 7507Sets the real value of <code>table[index]</code> to <code>value</code>, 7508without invoking the <code>__newindex</code> metamethod. 7509<code>table</code> must be a table, 7510<code>index</code> any value different from <b>nil</b> and NaN, 7511and <code>value</code> any Lua value. 7512 7513 7514<p> 7515This function returns <code>table</code>. 7516 7517 7518 7519 7520<p> 7521<hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> 7522 7523 7524<p> 7525If <code>index</code> is a number, 7526returns all arguments after argument number <code>index</code>; 7527a negative number indexes from the end (-1 is the last argument). 7528Otherwise, <code>index</code> must be the string <code>"#"</code>, 7529and <code>select</code> returns the total number of extra arguments it received. 7530 7531 7532 7533 7534<p> 7535<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> 7536 7537 7538<p> 7539Sets the metatable for the given table. 7540(To change the metatable of other types from Lua code, 7541you must use the debug library (<a href="#6.10">§6.10</a>).) 7542If <code>metatable</code> is <b>nil</b>, 7543removes the metatable of the given table. 7544If the original metatable has a <code>__metatable</code> field, 7545raises an error. 7546 7547 7548<p> 7549This function returns <code>table</code>. 7550 7551 7552 7553 7554<p> 7555<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> 7556 7557 7558<p> 7559When called with no <code>base</code>, 7560<code>tonumber</code> tries to convert its argument to a number. 7561If the argument is already a number or 7562a string convertible to a number, 7563then <code>tonumber</code> returns this number; 7564otherwise, it returns <b>nil</b>. 7565 7566 7567<p> 7568The conversion of strings can result in integers or floats, 7569according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 7570(The string may have leading and trailing spaces and a sign.) 7571 7572 7573<p> 7574When called with <code>base</code>, 7575then <code>e</code> must be a string to be interpreted as 7576an integer numeral in that base. 7577The base may be any integer between 2 and 36, inclusive. 7578In bases above 10, the letter '<code>A</code>' (in either upper or lower case) 7579represents 10, '<code>B</code>' represents 11, and so forth, 7580with '<code>Z</code>' representing 35. 7581If the string <code>e</code> is not a valid numeral in the given base, 7582the function returns <b>nil</b>. 7583 7584 7585 7586 7587<p> 7588<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3> 7589Receives a value of any type and 7590converts it to a string in a human-readable format. 7591(For complete control of how numbers are converted, 7592use <a href="#pdf-string.format"><code>string.format</code></a>.) 7593 7594 7595<p> 7596If the metatable of <code>v</code> has a <code>__tostring</code> field, 7597then <code>tostring</code> calls the corresponding value 7598with <code>v</code> as argument, 7599and uses the result of the call as its result. 7600 7601 7602 7603 7604<p> 7605<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> 7606Returns the type of its only argument, coded as a string. 7607The possible results of this function are 7608"<code>nil</code>" (a string, not the value <b>nil</b>), 7609"<code>number</code>", 7610"<code>string</code>", 7611"<code>boolean</code>", 7612"<code>table</code>", 7613"<code>function</code>", 7614"<code>thread</code>", 7615and "<code>userdata</code>". 7616 7617 7618 7619 7620<p> 7621<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> 7622 7623 7624<p> 7625A global variable (not a function) that 7626holds a string containing the running Lua version. 7627The current value of this variable is "<code>Lua 5.3</code>". 7628 7629 7630 7631 7632<p> 7633<hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3> 7634 7635 7636<p> 7637This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, 7638except that it sets a new message handler <code>msgh</code>. 7639 7640 7641 7642 7643 7644 7645 7646<h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2> 7647 7648<p> 7649This library comprises the operations to manipulate coroutines, 7650which come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. 7651See <a href="#2.6">§2.6</a> for a general description of coroutines. 7652 7653 7654<p> 7655<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> 7656 7657 7658<p> 7659Creates a new coroutine, with body <code>f</code>. 7660<code>f</code> must be a function. 7661Returns this new coroutine, 7662an object with type <code>"thread"</code>. 7663 7664 7665 7666 7667<p> 7668<hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ()</code></a></h3> 7669 7670 7671<p> 7672Returns true when the running coroutine can yield. 7673 7674 7675<p> 7676A running coroutine is yieldable if it is not the main thread and 7677it is not inside a non-yieldable C function. 7678 7679 7680 7681 7682<p> 7683<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> 7684 7685 7686<p> 7687Starts or continues the execution of coroutine <code>co</code>. 7688The first time you resume a coroutine, 7689it starts running its body. 7690The values <code>val1</code>, ... are passed 7691as the arguments to the body function. 7692If the coroutine has yielded, 7693<code>resume</code> restarts it; 7694the values <code>val1</code>, ... are passed 7695as the results from the yield. 7696 7697 7698<p> 7699If the coroutine runs without any errors, 7700<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> 7701(when the coroutine yields) or any values returned by the body function 7702(when the coroutine terminates). 7703If there is any error, 7704<code>resume</code> returns <b>false</b> plus the error message. 7705 7706 7707 7708 7709<p> 7710<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> 7711 7712 7713<p> 7714Returns the running coroutine plus a boolean, 7715true when the running coroutine is the main one. 7716 7717 7718 7719 7720<p> 7721<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> 7722 7723 7724<p> 7725Returns the status of coroutine <code>co</code>, as a string: 7726<code>"running"</code>, 7727if the coroutine is running (that is, it called <code>status</code>); 7728<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, 7729or if it has not started running yet; 7730<code>"normal"</code> if the coroutine is active but not running 7731(that is, it has resumed another coroutine); 7732and <code>"dead"</code> if the coroutine has finished its body function, 7733or if it has stopped with an error. 7734 7735 7736 7737 7738<p> 7739<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> 7740 7741 7742<p> 7743Creates a new coroutine, with body <code>f</code>. 7744<code>f</code> must be a function. 7745Returns a function that resumes the coroutine each time it is called. 7746Any arguments passed to the function behave as the 7747extra arguments to <code>resume</code>. 7748Returns the same values returned by <code>resume</code>, 7749except the first boolean. 7750In case of error, propagates the error. 7751 7752 7753 7754 7755<p> 7756<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> 7757 7758 7759<p> 7760Suspends the execution of the calling coroutine. 7761Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>. 7762 7763 7764 7765 7766 7767 7768 7769<h2>6.3 – <a name="6.3">Modules</a></h2> 7770 7771<p> 7772The package library provides basic 7773facilities for loading modules in Lua. 7774It exports one function directly in the global environment: 7775<a href="#pdf-require"><code>require</code></a>. 7776Everything else is exported in a table <a name="pdf-package"><code>package</code></a>. 7777 7778 7779<p> 7780<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> 7781 7782 7783<p> 7784Loads the given module. 7785The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table 7786to determine whether <code>modname</code> is already loaded. 7787If it is, then <code>require</code> returns the value stored 7788at <code>package.loaded[modname]</code>. 7789Otherwise, it tries to find a <em>loader</em> for the module. 7790 7791 7792<p> 7793To find a loader, 7794<code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence. 7795By changing this sequence, 7796we can change how <code>require</code> looks for a module. 7797The following explanation is based on the default configuration 7798for <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 7799 7800 7801<p> 7802First <code>require</code> queries <code>package.preload[modname]</code>. 7803If it has a value, 7804this value (which must be a function) is the loader. 7805Otherwise <code>require</code> searches for a Lua loader using the 7806path stored in <a href="#pdf-package.path"><code>package.path</code></a>. 7807If that also fails, it searches for a C loader using the 7808path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 7809If that also fails, 7810it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>). 7811 7812 7813<p> 7814Once a loader is found, 7815<code>require</code> calls the loader with two arguments: 7816<code>modname</code> and an extra value dependent on how it got the loader. 7817(If the loader came from a file, 7818this extra value is the file name.) 7819If the loader returns any non-nil value, 7820<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. 7821If the loader does not return a non-nil value and 7822has not assigned any value to <code>package.loaded[modname]</code>, 7823then <code>require</code> assigns <b>true</b> to this entry. 7824In any case, <code>require</code> returns the 7825final value of <code>package.loaded[modname]</code>. 7826 7827 7828<p> 7829If there is any error loading or running the module, 7830or if it cannot find any loader for the module, 7831then <code>require</code> raises an error. 7832 7833 7834 7835 7836<p> 7837<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3> 7838 7839 7840<p> 7841A string describing some compile-time configurations for packages. 7842This string is a sequence of lines: 7843 7844<ul> 7845 7846<li>The first line is the directory separator string. 7847Default is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li> 7848 7849<li>The second line is the character that separates templates in a path. 7850Default is '<code>;</code>'.</li> 7851 7852<li>The third line is the string that marks the 7853substitution points in a template. 7854Default is '<code>?</code>'.</li> 7855 7856<li>The fourth line is a string that, in a path in Windows, 7857is replaced by the executable's directory. 7858Default is '<code>!</code>'.</li> 7859 7860<li>The fifth line is a mark to ignore all text after it 7861when building the <code>luaopen_</code> function name. 7862Default is '<code>-</code>'.</li> 7863 7864</ul> 7865 7866 7867 7868<p> 7869<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> 7870 7871 7872<p> 7873The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. 7874 7875 7876<p> 7877Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way 7878it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, 7879using the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a> 7880or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a> 7881or a default path defined in <code>luaconf.h</code>. 7882 7883 7884 7885 7886<p> 7887<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> 7888 7889 7890<p> 7891A table used by <a href="#pdf-require"><code>require</code></a> to control which 7892modules are already loaded. 7893When you require a module <code>modname</code> and 7894<code>package.loaded[modname]</code> is not false, 7895<a href="#pdf-require"><code>require</code></a> simply returns the value stored there. 7896 7897 7898<p> 7899This variable is only a reference to the real table; 7900assignments to this variable do not change the 7901table used by <a href="#pdf-require"><code>require</code></a>. 7902 7903 7904 7905 7906<p> 7907<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> 7908 7909 7910<p> 7911Dynamically links the host program with the C library <code>libname</code>. 7912 7913 7914<p> 7915If <code>funcname</code> is "<code>*</code>", 7916then it only links with the library, 7917making the symbols exported by the library 7918available to other dynamically linked libraries. 7919Otherwise, 7920it looks for a function <code>funcname</code> inside the library 7921and returns this function as a C function. 7922So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype 7923(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 7924 7925 7926<p> 7927This is a low-level function. 7928It completely bypasses the package and module system. 7929Unlike <a href="#pdf-require"><code>require</code></a>, 7930it does not perform any path searching and 7931does not automatically adds extensions. 7932<code>libname</code> must be the complete file name of the C library, 7933including if necessary a path and an extension. 7934<code>funcname</code> must be the exact name exported by the C library 7935(which may depend on the C compiler and linker used). 7936 7937 7938<p> 7939This function is not supported by Standard C. 7940As such, it is only available on some platforms 7941(Windows, Linux, Mac OS X, Solaris, BSD, 7942plus other Unix systems that support the <code>dlfcn</code> standard). 7943 7944 7945 7946 7947<p> 7948<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> 7949 7950 7951<p> 7952The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. 7953 7954 7955<p> 7956At start-up, Lua initializes this variable with 7957the value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or 7958the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or 7959with a default path defined in <code>luaconf.h</code>, 7960if those environment variables are not defined. 7961Any "<code>;;</code>" in the value of the environment variable 7962is replaced by the default path. 7963 7964 7965 7966 7967<p> 7968<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> 7969 7970 7971<p> 7972A table to store loaders for specific modules 7973(see <a href="#pdf-require"><code>require</code></a>). 7974 7975 7976<p> 7977This variable is only a reference to the real table; 7978assignments to this variable do not change the 7979table used by <a href="#pdf-require"><code>require</code></a>. 7980 7981 7982 7983 7984<p> 7985<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3> 7986 7987 7988<p> 7989A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules. 7990 7991 7992<p> 7993Each entry in this table is a <em>searcher function</em>. 7994When looking for a module, 7995<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, 7996with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its 7997sole parameter. 7998The function can return another function (the module <em>loader</em>) 7999plus an extra value that will be passed to that loader, 8000or a string explaining why it did not find that module 8001(or <b>nil</b> if it has nothing to say). 8002 8003 8004<p> 8005Lua initializes this table with four searcher functions. 8006 8007 8008<p> 8009The first searcher simply looks for a loader in the 8010<a href="#pdf-package.preload"><code>package.preload</code></a> table. 8011 8012 8013<p> 8014The second searcher looks for a loader as a Lua library, 8015using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. 8016The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8017 8018 8019<p> 8020The third searcher looks for a loader as a C library, 8021using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 8022Again, 8023the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8024For instance, 8025if the C path is the string 8026 8027<pre> 8028 "./?.so;./?.dll;/usr/local/?/init.so" 8029</pre><p> 8030the searcher for module <code>foo</code> 8031will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, 8032and <code>/usr/local/foo/init.so</code>, in that order. 8033Once it finds a C library, 8034this searcher first uses a dynamic link facility to link the 8035application with the library. 8036Then it tries to find a C function inside the library to 8037be used as the loader. 8038The name of this C function is the string "<code>luaopen_</code>" 8039concatenated with a copy of the module name where each dot 8040is replaced by an underscore. 8041Moreover, if the module name has a hyphen, 8042its suffix after (and including) the first hyphen is removed. 8043For instance, if the module name is <code>a.b.c-v2.1</code>, 8044the function name will be <code>luaopen_a_b_c</code>. 8045 8046 8047<p> 8048The fourth searcher tries an <em>all-in-one loader</em>. 8049It searches the C path for a library for 8050the root name of the given module. 8051For instance, when requiring <code>a.b.c</code>, 8052it will search for a C library for <code>a</code>. 8053If found, it looks into it for an open function for 8054the submodule; 8055in our example, that would be <code>luaopen_a_b_c</code>. 8056With this facility, a package can pack several C submodules 8057into one single library, 8058with each submodule keeping its original open function. 8059 8060 8061<p> 8062All searchers except the first one (preload) return as the extra value 8063the file name where the module was found, 8064as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8065The first searcher returns no extra value. 8066 8067 8068 8069 8070<p> 8071<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3> 8072 8073 8074<p> 8075Searches for the given <code>name</code> in the given <code>path</code>. 8076 8077 8078<p> 8079A path is a string containing a sequence of 8080<em>templates</em> separated by semicolons. 8081For each template, 8082the function replaces each interrogation mark (if any) 8083in the template with a copy of <code>name</code> 8084wherein all occurrences of <code>sep</code> 8085(a dot, by default) 8086were replaced by <code>rep</code> 8087(the system's directory separator, by default), 8088and then tries to open the resulting file name. 8089 8090 8091<p> 8092For instance, if the path is the string 8093 8094<pre> 8095 "./?.lua;./?.lc;/usr/local/?/init.lua" 8096</pre><p> 8097the search for the name <code>foo.a</code> 8098will try to open the files 8099<code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and 8100<code>/usr/local/foo/a/init.lua</code>, in that order. 8101 8102 8103<p> 8104Returns the resulting name of the first file that it can 8105open in read mode (after closing the file), 8106or <b>nil</b> plus an error message if none succeeds. 8107(This error message lists all file names it tried to open.) 8108 8109 8110 8111 8112 8113 8114 8115<h2>6.4 – <a name="6.4">String Manipulation</a></h2> 8116 8117<p> 8118This library provides generic functions for string manipulation, 8119such as finding and extracting substrings, and pattern matching. 8120When indexing a string in Lua, the first character is at position 1 8121(not at 0, as in C). 8122Indices are allowed to be negative and are interpreted as indexing backwards, 8123from the end of the string. 8124Thus, the last character is at position -1, and so on. 8125 8126 8127<p> 8128The string library provides all its functions inside the table 8129<a name="pdf-string"><code>string</code></a>. 8130It also sets a metatable for strings 8131where the <code>__index</code> field points to the <code>string</code> table. 8132Therefore, you can use the string functions in object-oriented style. 8133For instance, <code>string.byte(s,i)</code> 8134can be written as <code>s:byte(i)</code>. 8135 8136 8137<p> 8138The string library assumes one-byte character encodings. 8139 8140 8141<p> 8142<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> 8143Returns the internal numeric codes of the characters <code>s[i]</code>, 8144<code>s[i+1]</code>, ..., <code>s[j]</code>. 8145The default value for <code>i</code> is 1; 8146the default value for <code>j</code> is <code>i</code>. 8147These indices are corrected 8148following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>. 8149 8150 8151<p> 8152Numeric codes are not necessarily portable across platforms. 8153 8154 8155 8156 8157<p> 8158<hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> 8159Receives zero or more integers. 8160Returns a string with length equal to the number of arguments, 8161in which each character has the internal numeric code equal 8162to its corresponding argument. 8163 8164 8165<p> 8166Numeric codes are not necessarily portable across platforms. 8167 8168 8169 8170 8171<p> 8172<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3> 8173 8174 8175<p> 8176Returns a string containing a binary representation 8177(a <em>binary chunk</em>) 8178of the given function, 8179so that a later <a href="#pdf-load"><code>load</code></a> on this string returns 8180a copy of the function (but with new upvalues). 8181If <code>strip</code> is a true value, 8182the binary representation may not include all debug information 8183about the function, 8184to save space. 8185 8186 8187<p> 8188Functions with upvalues have only their number of upvalues saved. 8189When (re)loaded, 8190those upvalues receive fresh instances containing <b>nil</b>. 8191(You can use the debug library to serialize 8192and reload the upvalues of a function 8193in a way adequate to your needs.) 8194 8195 8196 8197 8198<p> 8199<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> 8200 8201 8202<p> 8203Looks for the first match of 8204<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 8205If it finds a match, then <code>find</code> returns the indices of <code>s</code> 8206where this occurrence starts and ends; 8207otherwise, it returns <b>nil</b>. 8208A third, optional numeric argument <code>init</code> specifies 8209where to start the search; 8210its default value is 1 and can be negative. 8211A value of <b>true</b> as a fourth, optional argument <code>plain</code> 8212turns off the pattern matching facilities, 8213so the function does a plain "find substring" operation, 8214with no characters in <code>pattern</code> being considered magic. 8215Note that if <code>plain</code> is given, then <code>init</code> must be given as well. 8216 8217 8218<p> 8219If the pattern has captures, 8220then in a successful match 8221the captured values are also returned, 8222after the two indices. 8223 8224 8225 8226 8227<p> 8228<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> 8229 8230 8231<p> 8232Returns a formatted version of its variable number of arguments 8233following the description given in its first argument (which must be a string). 8234The format string follows the same rules as the ISO C function <code>sprintf</code>. 8235The only differences are that the options/modifiers 8236<code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>, 8237and <code>p</code> are not supported 8238and that there is an extra option, <code>q</code>. 8239 8240 8241<p> 8242The <code>q</code> option formats a string between double quotes, 8243using escape sequences when necessary to ensure that 8244it can safely be read back by the Lua interpreter. 8245For instance, the call 8246 8247<pre> 8248 string.format('%q', 'a string with "quotes" and \n new line') 8249</pre><p> 8250may produce the string: 8251 8252<pre> 8253 "a string with \"quotes\" and \ 8254 new line" 8255</pre> 8256 8257<p> 8258Options 8259<code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>, 8260<code>G</code>, and <code>g</code> all expect a number as argument. 8261Options <code>c</code>, <code>d</code>, 8262<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> 8263expect an integer. 8264When Lua is compiled with a C89 compiler, 8265options <code>A</code> and <code>a</code> (hexadecimal floats) 8266do not support any modifier (flags, width, length). 8267 8268 8269<p> 8270Option <code>s</code> expects a string; 8271if its argument is not a string, 8272it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 8273If the option has any modifier (flags, width, length), 8274the string argument should not contain embedded zeros. 8275 8276 8277 8278 8279<p> 8280<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3> 8281Returns an iterator function that, 8282each time it is called, 8283returns the next captures from <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) 8284over the string <code>s</code>. 8285If <code>pattern</code> specifies no captures, 8286then the whole match is produced in each call. 8287 8288 8289<p> 8290As an example, the following loop 8291will iterate over all the words from string <code>s</code>, 8292printing one per line: 8293 8294<pre> 8295 s = "hello world from Lua" 8296 for w in string.gmatch(s, "%a+") do 8297 print(w) 8298 end 8299</pre><p> 8300The next example collects all pairs <code>key=value</code> from the 8301given string into a table: 8302 8303<pre> 8304 t = {} 8305 s = "from=world, to=Lua" 8306 for k, v in string.gmatch(s, "(%w+)=(%w+)") do 8307 t[k] = v 8308 end 8309</pre> 8310 8311<p> 8312For this function, a caret '<code>^</code>' at the start of a pattern does not 8313work as an anchor, as this would prevent the iteration. 8314 8315 8316 8317 8318<p> 8319<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> 8320Returns a copy of <code>s</code> 8321in which all (or the first <code>n</code>, if given) 8322occurrences of the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) have been 8323replaced by a replacement string specified by <code>repl</code>, 8324which can be a string, a table, or a function. 8325<code>gsub</code> also returns, as its second value, 8326the total number of matches that occurred. 8327The name <code>gsub</code> comes from <em>Global SUBstitution</em>. 8328 8329 8330<p> 8331If <code>repl</code> is a string, then its value is used for replacement. 8332The character <code>%</code> works as an escape character: 8333any sequence in <code>repl</code> of the form <code>%<em>d</em></code>, 8334with <em>d</em> between 1 and 9, 8335stands for the value of the <em>d</em>-th captured substring. 8336The sequence <code>%0</code> stands for the whole match. 8337The sequence <code>%%</code> stands for a single <code>%</code>. 8338 8339 8340<p> 8341If <code>repl</code> is a table, then the table is queried for every match, 8342using the first capture as the key. 8343 8344 8345<p> 8346If <code>repl</code> is a function, then this function is called every time a 8347match occurs, with all captured substrings passed as arguments, 8348in order. 8349 8350 8351<p> 8352In any case, 8353if the pattern specifies no captures, 8354then it behaves as if the whole pattern was inside a capture. 8355 8356 8357<p> 8358If the value returned by the table query or by the function call 8359is a string or a number, 8360then it is used as the replacement string; 8361otherwise, if it is <b>false</b> or <b>nil</b>, 8362then there is no replacement 8363(that is, the original match is kept in the string). 8364 8365 8366<p> 8367Here are some examples: 8368 8369<pre> 8370 x = string.gsub("hello world", "(%w+)", "%1 %1") 8371 --> x="hello hello world world" 8372 8373 x = string.gsub("hello world", "%w+", "%0 %0", 1) 8374 --> x="hello hello world" 8375 8376 x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 8377 --> x="world hello Lua from" 8378 8379 x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) 8380 --> x="home = /home/roberto, user = roberto" 8381 8382 x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 8383 return load(s)() 8384 end) 8385 --> x="4+5 = 9" 8386 8387 local t = {name="lua", version="5.3"} 8388 x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 8389 --> x="lua-5.3.tar.gz" 8390</pre> 8391 8392 8393 8394<p> 8395<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> 8396Receives a string and returns its length. 8397The empty string <code>""</code> has length 0. 8398Embedded zeros are counted, 8399so <code>"a\000bc\000"</code> has length 5. 8400 8401 8402 8403 8404<p> 8405<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> 8406Receives a string and returns a copy of this string with all 8407uppercase letters changed to lowercase. 8408All other characters are left unchanged. 8409The definition of what an uppercase letter is depends on the current locale. 8410 8411 8412 8413 8414<p> 8415<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> 8416Looks for the first <em>match</em> of 8417<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 8418If it finds one, then <code>match</code> returns 8419the captures from the pattern; 8420otherwise it returns <b>nil</b>. 8421If <code>pattern</code> specifies no captures, 8422then the whole match is returned. 8423A third, optional numeric argument <code>init</code> specifies 8424where to start the search; 8425its default value is 1 and can be negative. 8426 8427 8428 8429 8430<p> 8431<hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, ···)</code></a></h3> 8432 8433 8434<p> 8435Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc. 8436packed (that is, serialized in binary form) 8437according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 8438 8439 8440 8441 8442<p> 8443<hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3> 8444 8445 8446<p> 8447Returns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a> 8448with the given format. 8449The format string cannot have the variable-length options 8450'<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">§6.4.2</a>). 8451 8452 8453 8454 8455<p> 8456<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3> 8457Returns a string that is the concatenation of <code>n</code> copies of 8458the string <code>s</code> separated by the string <code>sep</code>. 8459The default value for <code>sep</code> is the empty string 8460(that is, no separator). 8461Returns the empty string if <code>n</code> is not positive. 8462 8463 8464<p> 8465(Note that it is very easy to exhaust the memory of your machine 8466with a single call to this function.) 8467 8468 8469 8470 8471<p> 8472<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> 8473Returns a string that is the string <code>s</code> reversed. 8474 8475 8476 8477 8478<p> 8479<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> 8480Returns the substring of <code>s</code> that 8481starts at <code>i</code> and continues until <code>j</code>; 8482<code>i</code> and <code>j</code> can be negative. 8483If <code>j</code> is absent, then it is assumed to be equal to -1 8484(which is the same as the string length). 8485In particular, 8486the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 8487with length <code>j</code>, 8488and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code> 8489with length <code>i</code>. 8490 8491 8492<p> 8493If, after the translation of negative indices, 8494<code>i</code> is less than 1, 8495it is corrected to 1. 8496If <code>j</code> is greater than the string length, 8497it is corrected to that length. 8498If, after these corrections, 8499<code>i</code> is greater than <code>j</code>, 8500the function returns the empty string. 8501 8502 8503 8504 8505<p> 8506<hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3> 8507 8508 8509<p> 8510Returns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>) 8511according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 8512An optional <code>pos</code> marks where 8513to start reading in <code>s</code> (default is 1). 8514After the read values, 8515this function also returns the index of the first unread byte in <code>s</code>. 8516 8517 8518 8519 8520<p> 8521<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> 8522Receives a string and returns a copy of this string with all 8523lowercase letters changed to uppercase. 8524All other characters are left unchanged. 8525The definition of what a lowercase letter is depends on the current locale. 8526 8527 8528 8529 8530 8531<h3>6.4.1 – <a name="6.4.1">Patterns</a></h3> 8532 8533<p> 8534Patterns in Lua are described by regular strings, 8535which are interpreted as patterns by the pattern-matching functions 8536<a href="#pdf-string.find"><code>string.find</code></a>, 8537<a href="#pdf-string.gmatch"><code>string.gmatch</code></a>, 8538<a href="#pdf-string.gsub"><code>string.gsub</code></a>, 8539and <a href="#pdf-string.match"><code>string.match</code></a>. 8540This section describes the syntax and the meaning 8541(that is, what they match) of these strings. 8542 8543 8544 8545<h4>Character Class:</h4><p> 8546A <em>character class</em> is used to represent a set of characters. 8547The following combinations are allowed in describing a character class: 8548 8549<ul> 8550 8551<li><b><em>x</em>: </b> 8552(where <em>x</em> is not one of the <em>magic characters</em> 8553<code>^$()%.[]*+-?</code>) 8554represents the character <em>x</em> itself. 8555</li> 8556 8557<li><b><code>.</code>: </b> (a dot) represents all characters.</li> 8558 8559<li><b><code>%a</code>: </b> represents all letters.</li> 8560 8561<li><b><code>%c</code>: </b> represents all control characters.</li> 8562 8563<li><b><code>%d</code>: </b> represents all digits.</li> 8564 8565<li><b><code>%g</code>: </b> represents all printable characters except space.</li> 8566 8567<li><b><code>%l</code>: </b> represents all lowercase letters.</li> 8568 8569<li><b><code>%p</code>: </b> represents all punctuation characters.</li> 8570 8571<li><b><code>%s</code>: </b> represents all space characters.</li> 8572 8573<li><b><code>%u</code>: </b> represents all uppercase letters.</li> 8574 8575<li><b><code>%w</code>: </b> represents all alphanumeric characters.</li> 8576 8577<li><b><code>%x</code>: </b> represents all hexadecimal digits.</li> 8578 8579<li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character) 8580represents the character <em>x</em>. 8581This is the standard way to escape the magic characters. 8582Any non-alphanumeric character 8583(including all punctuation characters, even the non-magical) 8584can be preceded by a '<code>%</code>' 8585when used to represent itself in a pattern. 8586</li> 8587 8588<li><b><code>[<em>set</em>]</code>: </b> 8589represents the class which is the union of all 8590characters in <em>set</em>. 8591A range of characters can be specified by 8592separating the end characters of the range, 8593in ascending order, with a '<code>-</code>'. 8594All classes <code>%</code><em>x</em> described above can also be used as 8595components in <em>set</em>. 8596All other characters in <em>set</em> represent themselves. 8597For example, <code>[%w_]</code> (or <code>[_%w]</code>) 8598represents all alphanumeric characters plus the underscore, 8599<code>[0-7]</code> represents the octal digits, 8600and <code>[0-7%l%-]</code> represents the octal digits plus 8601the lowercase letters plus the '<code>-</code>' character. 8602 8603 8604<p> 8605You can put a closing square bracket in a set 8606by positioning it as the first character in the set. 8607You can put an hyphen in a set 8608by positioning it as the first or the last character in the set. 8609(You can also use an escape for both cases.) 8610 8611 8612<p> 8613The interaction between ranges and classes is not defined. 8614Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> 8615have no meaning. 8616</li> 8617 8618<li><b><code>[^<em>set</em>]</code>: </b> 8619represents the complement of <em>set</em>, 8620where <em>set</em> is interpreted as above. 8621</li> 8622 8623</ul><p> 8624For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), 8625the corresponding uppercase letter represents the complement of the class. 8626For instance, <code>%S</code> represents all non-space characters. 8627 8628 8629<p> 8630The definitions of letter, space, and other character groups 8631depend on the current locale. 8632In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. 8633 8634 8635 8636 8637 8638<h4>Pattern Item:</h4><p> 8639A <em>pattern item</em> can be 8640 8641<ul> 8642 8643<li> 8644a single character class, 8645which matches any single character in the class; 8646</li> 8647 8648<li> 8649a single character class followed by '<code>*</code>', 8650which matches zero or more repetitions of characters in the class. 8651These repetition items will always match the longest possible sequence; 8652</li> 8653 8654<li> 8655a single character class followed by '<code>+</code>', 8656which matches one or more repetitions of characters in the class. 8657These repetition items will always match the longest possible sequence; 8658</li> 8659 8660<li> 8661a single character class followed by '<code>-</code>', 8662which also matches zero or more repetitions of characters in the class. 8663Unlike '<code>*</code>', 8664these repetition items will always match the shortest possible sequence; 8665</li> 8666 8667<li> 8668a single character class followed by '<code>?</code>', 8669which matches zero or one occurrence of a character in the class. 8670It always matches one occurrence if possible; 8671</li> 8672 8673<li> 8674<code>%<em>n</em></code>, for <em>n</em> between 1 and 9; 8675such item matches a substring equal to the <em>n</em>-th captured string 8676(see below); 8677</li> 8678 8679<li> 8680<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; 8681such item matches strings that start with <em>x</em>, end with <em>y</em>, 8682and where the <em>x</em> and <em>y</em> are <em>balanced</em>. 8683This means that, if one reads the string from left to right, 8684counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, 8685the ending <em>y</em> is the first <em>y</em> where the count reaches 0. 8686For instance, the item <code>%b()</code> matches expressions with 8687balanced parentheses. 8688</li> 8689 8690<li> 8691<code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>; 8692such item matches an empty string at any position such that 8693the next character belongs to <em>set</em> 8694and the previous character does not belong to <em>set</em>. 8695The set <em>set</em> is interpreted as previously described. 8696The beginning and the end of the subject are handled as if 8697they were the character '<code>\0</code>'. 8698</li> 8699 8700</ul> 8701 8702 8703 8704 8705<h4>Pattern:</h4><p> 8706A <em>pattern</em> is a sequence of pattern items. 8707A caret '<code>^</code>' at the beginning of a pattern anchors the match at the 8708beginning of the subject string. 8709A '<code>$</code>' at the end of a pattern anchors the match at the 8710end of the subject string. 8711At other positions, 8712'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. 8713 8714 8715 8716 8717 8718<h4>Captures:</h4><p> 8719A pattern can contain sub-patterns enclosed in parentheses; 8720they describe <em>captures</em>. 8721When a match succeeds, the substrings of the subject string 8722that match captures are stored (<em>captured</em>) for future use. 8723Captures are numbered according to their left parentheses. 8724For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, 8725the part of the string matching <code>"a*(.)%w(%s*)"</code> is 8726stored as the first capture (and therefore has number 1); 8727the character matching "<code>.</code>" is captured with number 2, 8728and the part matching "<code>%s*</code>" has number 3. 8729 8730 8731<p> 8732As a special case, the empty capture <code>()</code> captures 8733the current string position (a number). 8734For instance, if we apply the pattern <code>"()aa()"</code> on the 8735string <code>"flaaap"</code>, there will be two captures: 3 and 5. 8736 8737 8738 8739 8740 8741 8742 8743<h3>6.4.2 – <a name="6.4.2">Format Strings for Pack and Unpack</a></h3> 8744 8745<p> 8746The first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>, 8747<a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a> 8748is a format string, 8749which describes the layout of the structure being created or read. 8750 8751 8752<p> 8753A format string is a sequence of conversion options. 8754The conversion options are as follows: 8755 8756<ul> 8757<li><b><code><</code>: </b>sets little endian</li> 8758<li><b><code>></code>: </b>sets big endian</li> 8759<li><b><code>=</code>: </b>sets native endian</li> 8760<li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code> 8761(default is native alignment)</li> 8762<li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li> 8763<li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li> 8764<li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li> 8765<li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li> 8766<li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li> 8767<li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li> 8768<li><b><code>j</code>: </b>a <code>lua_Integer</code></li> 8769<li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li> 8770<li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li> 8771<li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes 8772(default is native size)</li> 8773<li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes 8774(default is native size)</li> 8775<li><b><code>f</code>: </b>a <code>float</code> (native size)</li> 8776<li><b><code>d</code>: </b>a <code>double</code> (native size)</li> 8777<li><b><code>n</code>: </b>a <code>lua_Number</code></li> 8778<li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li> 8779<li><b><code>z</code>: </b>a zero-terminated string</li> 8780<li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length 8781coded as an unsigned integer with <code>n</code> bytes 8782(default is a <code>size_t</code>)</li> 8783<li><b><code>x</code>: </b>one byte of padding</li> 8784<li><b><code>X<em>op</em></code>: </b>an empty item that aligns 8785according to option <code>op</code> 8786(which is otherwise ignored)</li> 8787<li><b>'<code> </code>': </b>(empty space) ignored</li> 8788</ul><p> 8789(A "<code>[<em>n</em>]</code>" means an optional integral numeral.) 8790Except for padding, spaces, and configurations 8791(options "<code>xX <=>!</code>"), 8792each option corresponds to an argument (in <a href="#pdf-string.pack"><code>string.pack</code></a>) 8793or a result (in <a href="#pdf-string.unpack"><code>string.unpack</code></a>). 8794 8795 8796<p> 8797For 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>", 8798<code>n</code> can be any integer between 1 and 16. 8799All integral options check overflows; 8800<a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size; 8801<a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer. 8802 8803 8804<p> 8805Any format string starts as if prefixed by "<code>!1=</code>", 8806that is, 8807with maximum alignment of 1 (no alignment) 8808and native endianness. 8809 8810 8811<p> 8812Alignment works as follows: 8813For each option, 8814the format gets extra padding until the data starts 8815at an offset that is a multiple of the minimum between the 8816option size and the maximum alignment; 8817this minimum must be a power of 2. 8818Options "<code>c</code>" and "<code>z</code>" are not aligned; 8819option "<code>s</code>" follows the alignment of its starting integer. 8820 8821 8822<p> 8823All padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a> 8824(and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>). 8825 8826 8827 8828 8829 8830 8831 8832<h2>6.5 – <a name="6.5">UTF-8 Support</a></h2> 8833 8834<p> 8835This library provides basic support for UTF-8 encoding. 8836It provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>. 8837This library does not provide any support for Unicode other 8838than the handling of the encoding. 8839Any operation that needs the meaning of a character, 8840such as character classification, is outside its scope. 8841 8842 8843<p> 8844Unless stated otherwise, 8845all functions that expect a byte position as a parameter 8846assume that the given position is either the start of a byte sequence 8847or one plus the length of the subject string. 8848As in the string library, 8849negative indices count from the end of the string. 8850 8851 8852<p> 8853<hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3> 8854Receives zero or more integers, 8855converts each one to its corresponding UTF-8 byte sequence 8856and returns a string with the concatenation of all these sequences. 8857 8858 8859 8860 8861<p> 8862<hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3> 8863The pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>" 8864(see <a href="#6.4.1">§6.4.1</a>), 8865which matches exactly one UTF-8 byte sequence, 8866assuming that the subject is a valid UTF-8 string. 8867 8868 8869 8870 8871<p> 8872<hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3> 8873 8874 8875<p> 8876Returns values so that the construction 8877 8878<pre> 8879 for p, c in utf8.codes(s) do <em>body</em> end 8880</pre><p> 8881will iterate over all characters in string <code>s</code>, 8882with <code>p</code> being the position (in bytes) and <code>c</code> the code point 8883of each character. 8884It raises an error if it meets any invalid byte sequence. 8885 8886 8887 8888 8889<p> 8890<hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3> 8891Returns the codepoints (as integers) from all characters in <code>s</code> 8892that start between byte position <code>i</code> and <code>j</code> (both included). 8893The default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>. 8894It raises an error if it meets any invalid byte sequence. 8895 8896 8897 8898 8899<p> 8900<hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j]])</code></a></h3> 8901Returns the number of UTF-8 characters in string <code>s</code> 8902that start between positions <code>i</code> and <code>j</code> (both inclusive). 8903The default for <code>i</code> is 1 and for <code>j</code> is -1. 8904If it finds any invalid byte sequence, 8905returns a false value plus the position of the first invalid byte. 8906 8907 8908 8909 8910<p> 8911<hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3> 8912Returns the position (in bytes) where the encoding of the 8913<code>n</code>-th character of <code>s</code> 8914(counting from position <code>i</code>) starts. 8915A negative <code>n</code> gets characters before position <code>i</code>. 8916The default for <code>i</code> is 1 when <code>n</code> is non-negative 8917and <code>#s + 1</code> otherwise, 8918so that <code>utf8.offset(s, -n)</code> gets the offset of the 8919<code>n</code>-th character from the end of the string. 8920If the specified character is neither in the subject 8921nor right after its end, 8922the function returns <b>nil</b>. 8923 8924 8925<p> 8926As a special case, 8927when <code>n</code> is 0 the function returns the start of the encoding 8928of the character that contains the <code>i</code>-th byte of <code>s</code>. 8929 8930 8931<p> 8932This function assumes that <code>s</code> is a valid UTF-8 string. 8933 8934 8935 8936 8937 8938 8939 8940<h2>6.6 – <a name="6.6">Table Manipulation</a></h2> 8941 8942<p> 8943This library provides generic functions for table manipulation. 8944It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. 8945 8946 8947<p> 8948Remember that, whenever an operation needs the length of a table, 8949the table must be a proper sequence 8950or have a <code>__len</code> metamethod (see <a href="#3.4.7">§3.4.7</a>). 8951All functions ignore non-numeric keys 8952in the tables given as arguments. 8953 8954 8955<p> 8956<hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3> 8957 8958 8959<p> 8960Given a list where all elements are strings or numbers, 8961returns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>. 8962The default value for <code>sep</code> is the empty string, 8963the default for <code>i</code> is 1, 8964and the default for <code>j</code> is <code>#list</code>. 8965If <code>i</code> is greater than <code>j</code>, returns the empty string. 8966 8967 8968 8969 8970<p> 8971<hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3> 8972 8973 8974<p> 8975Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>, 8976shifting up the elements 8977<code>list[pos], list[pos+1], ···, list[#list]</code>. 8978The default value for <code>pos</code> is <code>#list+1</code>, 8979so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end 8980of list <code>t</code>. 8981 8982 8983 8984 8985<p> 8986<hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3> 8987 8988 8989<p> 8990Moves elements from table <code>a1</code> to table <code>a2</code>, 8991performing the equivalent to the following 8992multiple assignment: 8993<code>a2[t],··· = a1[f],···,a1[e]</code>. 8994The default for <code>a2</code> is <code>a1</code>. 8995The destination range can overlap with the source range. 8996The number of elements to be moved must fit in a Lua integer. 8997 8998 8999<p> 9000Returns the destination table <code>a2</code>. 9001 9002 9003 9004 9005<p> 9006<hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3> 9007 9008 9009<p> 9010Returns a new table with all parameters stored into keys 1, 2, etc. 9011and with a field "<code>n</code>" with the total number of parameters. 9012Note that the resulting table may not be a sequence. 9013 9014 9015 9016 9017<p> 9018<hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3> 9019 9020 9021<p> 9022Removes from <code>list</code> the element at position <code>pos</code>, 9023returning the value of the removed element. 9024When <code>pos</code> is an integer between 1 and <code>#list</code>, 9025it shifts down the elements 9026<code>list[pos+1], list[pos+2], ···, list[#list]</code> 9027and erases element <code>list[#list]</code>; 9028The index <code>pos</code> can also be 0 when <code>#list</code> is 0, 9029or <code>#list + 1</code>; 9030in those cases, the function erases the element <code>list[pos]</code>. 9031 9032 9033<p> 9034The default value for <code>pos</code> is <code>#list</code>, 9035so that a call <code>table.remove(l)</code> removes the last element 9036of list <code>l</code>. 9037 9038 9039 9040 9041<p> 9042<hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3> 9043 9044 9045<p> 9046Sorts list elements in a given order, <em>in-place</em>, 9047from <code>list[1]</code> to <code>list[#list]</code>. 9048If <code>comp</code> is given, 9049then it must be a function that receives two list elements 9050and returns true when the first element must come 9051before the second in the final order 9052(so that, after the sort, 9053<code>i < j</code> implies <code>not comp(list[j],list[i])</code>). 9054If <code>comp</code> is not given, 9055then the standard Lua operator <code><</code> is used instead. 9056 9057 9058<p> 9059Note that the <code>comp</code> function must define 9060a strict partial order over the elements in the list; 9061that is, it must be asymmetric and transitive. 9062Otherwise, no valid sort may be possible. 9063 9064 9065<p> 9066The sort algorithm is not stable; 9067that is, elements not comparable by the given order 9068(e.g., equal elements) 9069may have their relative positions changed by the sort. 9070 9071 9072 9073 9074<p> 9075<hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3> 9076 9077 9078<p> 9079Returns the elements from the given list. 9080This function is equivalent to 9081 9082<pre> 9083 return list[i], list[i+1], ···, list[j] 9084</pre><p> 9085By default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>. 9086 9087 9088 9089 9090 9091 9092 9093<h2>6.7 – <a name="6.7">Mathematical Functions</a></h2> 9094 9095<p> 9096This library provides basic mathematical functions. 9097It provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>. 9098Functions with the annotation "<code>integer/float</code>" give 9099integer results for integer arguments 9100and float results for float (or mixed) arguments. 9101Rounding functions 9102(<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>) 9103return an integer when the result fits in the range of an integer, 9104or a float otherwise. 9105 9106 9107<p> 9108<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> 9109 9110 9111<p> 9112Returns the absolute value of <code>x</code>. (integer/float) 9113 9114 9115 9116 9117<p> 9118<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> 9119 9120 9121<p> 9122Returns the arc cosine of <code>x</code> (in radians). 9123 9124 9125 9126 9127<p> 9128<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> 9129 9130 9131<p> 9132Returns the arc sine of <code>x</code> (in radians). 9133 9134 9135 9136 9137<p> 9138<hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3> 9139 9140 9141<p> 9142 9143Returns the arc tangent of <code>y/x</code> (in radians), 9144but uses the signs of both parameters to find the 9145quadrant of the result. 9146(It also handles correctly the case of <code>x</code> being zero.) 9147 9148 9149<p> 9150The default value for <code>x</code> is 1, 9151so that the call <code>math.atan(y)</code> 9152returns the arc tangent of <code>y</code>. 9153 9154 9155 9156 9157<p> 9158<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> 9159 9160 9161<p> 9162Returns the smallest integral value larger than or equal to <code>x</code>. 9163 9164 9165 9166 9167<p> 9168<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> 9169 9170 9171<p> 9172Returns the cosine of <code>x</code> (assumed to be in radians). 9173 9174 9175 9176 9177<p> 9178<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> 9179 9180 9181<p> 9182Converts the angle <code>x</code> from radians to degrees. 9183 9184 9185 9186 9187<p> 9188<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> 9189 9190 9191<p> 9192Returns the value <em>e<sup>x</sup></em> 9193(where <code>e</code> is the base of natural logarithms). 9194 9195 9196 9197 9198<p> 9199<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> 9200 9201 9202<p> 9203Returns the largest integral value smaller than or equal to <code>x</code>. 9204 9205 9206 9207 9208<p> 9209<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> 9210 9211 9212<p> 9213Returns the remainder of the division of <code>x</code> by <code>y</code> 9214that rounds the quotient towards zero. (integer/float) 9215 9216 9217 9218 9219<p> 9220<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> 9221 9222 9223<p> 9224The float value <code>HUGE_VAL</code>, 9225a value larger than any other numeric value. 9226 9227 9228 9229 9230<p> 9231<hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3> 9232 9233 9234<p> 9235Returns the logarithm of <code>x</code> in the given base. 9236The default for <code>base</code> is <em>e</em> 9237(so that the function returns the natural logarithm of <code>x</code>). 9238 9239 9240 9241 9242<p> 9243<hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> 9244 9245 9246<p> 9247Returns the argument with the maximum value, 9248according to the Lua operator <code><</code>. (integer/float) 9249 9250 9251 9252 9253<p> 9254<hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3> 9255An integer with the maximum value for an integer. 9256 9257 9258 9259 9260<p> 9261<hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> 9262 9263 9264<p> 9265Returns the argument with the minimum value, 9266according to the Lua operator <code><</code>. (integer/float) 9267 9268 9269 9270 9271<p> 9272<hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3> 9273An integer with the minimum value for an integer. 9274 9275 9276 9277 9278<p> 9279<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> 9280 9281 9282<p> 9283Returns the integral part of <code>x</code> and the fractional part of <code>x</code>. 9284Its second result is always a float. 9285 9286 9287 9288 9289<p> 9290<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> 9291 9292 9293<p> 9294The value of <em>π</em>. 9295 9296 9297 9298 9299<p> 9300<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> 9301 9302 9303<p> 9304Converts the angle <code>x</code> from degrees to radians. 9305 9306 9307 9308 9309<p> 9310<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> 9311 9312 9313<p> 9314When called without arguments, 9315returns a pseudo-random float with uniform distribution 9316in the range <em>[0,1)</em>. 9317When called with two integers <code>m</code> and <code>n</code>, 9318<code>math.random</code> returns a pseudo-random integer 9319with uniform distribution in the range <em>[m, n]</em>. 9320(The value <em>n-m</em> cannot be negative and must fit in a Lua integer.) 9321The call <code>math.random(n)</code> is equivalent to <code>math.random(1,n)</code>. 9322 9323 9324<p> 9325This function is an interface to the underling 9326pseudo-random generator function provided by C. 9327 9328 9329 9330 9331<p> 9332<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3> 9333 9334 9335<p> 9336Sets <code>x</code> as the "seed" 9337for the pseudo-random generator: 9338equal seeds produce equal sequences of numbers. 9339 9340 9341 9342 9343<p> 9344<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> 9345 9346 9347<p> 9348Returns the sine of <code>x</code> (assumed to be in radians). 9349 9350 9351 9352 9353<p> 9354<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> 9355 9356 9357<p> 9358Returns the square root of <code>x</code>. 9359(You can also use the expression <code>x^0.5</code> to compute this value.) 9360 9361 9362 9363 9364<p> 9365<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> 9366 9367 9368<p> 9369Returns the tangent of <code>x</code> (assumed to be in radians). 9370 9371 9372 9373 9374<p> 9375<hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3> 9376 9377 9378<p> 9379If the value <code>x</code> is convertible to an integer, 9380returns that integer. 9381Otherwise, returns <b>nil</b>. 9382 9383 9384 9385 9386<p> 9387<hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3> 9388 9389 9390<p> 9391Returns "<code>integer</code>" if <code>x</code> is an integer, 9392"<code>float</code>" if it is a float, 9393or <b>nil</b> if <code>x</code> is not a number. 9394 9395 9396 9397 9398<p> 9399<hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3> 9400 9401 9402<p> 9403Returns a boolean, 9404true if integer <code>m</code> is below integer <code>n</code> when 9405they are compared as unsigned integers. 9406 9407 9408 9409 9410 9411 9412 9413<h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2> 9414 9415<p> 9416The I/O library provides two different styles for file manipulation. 9417The first one uses implicit file handles; 9418that is, there are operations to set a default input file and a 9419default output file, 9420and all input/output operations are over these default files. 9421The second style uses explicit file handles. 9422 9423 9424<p> 9425When using implicit file handles, 9426all operations are supplied by table <a name="pdf-io"><code>io</code></a>. 9427When using explicit file handles, 9428the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle 9429and then all operations are supplied as methods of the file handle. 9430 9431 9432<p> 9433The table <code>io</code> also provides 9434three predefined file handles with their usual meanings from C: 9435<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>. 9436The I/O library never closes these files. 9437 9438 9439<p> 9440Unless otherwise stated, 9441all I/O functions return <b>nil</b> on failure 9442(plus an error message as a second result and 9443a system-dependent error code as a third result) 9444and some value different from <b>nil</b> on success. 9445On non-POSIX systems, 9446the computation of the error message and error code 9447in case of errors 9448may be not thread safe, 9449because they rely on the global C variable <code>errno</code>. 9450 9451 9452<p> 9453<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> 9454 9455 9456<p> 9457Equivalent to <code>file:close()</code>. 9458Without a <code>file</code>, closes the default output file. 9459 9460 9461 9462 9463<p> 9464<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> 9465 9466 9467<p> 9468Equivalent to <code>io.output():flush()</code>. 9469 9470 9471 9472 9473<p> 9474<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> 9475 9476 9477<p> 9478When called with a file name, it opens the named file (in text mode), 9479and sets its handle as the default input file. 9480When called with a file handle, 9481it simply sets this file handle as the default input file. 9482When called without parameters, 9483it returns the current default input file. 9484 9485 9486<p> 9487In case of errors this function raises the error, 9488instead of returning an error code. 9489 9490 9491 9492 9493<p> 9494<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, ···])</code></a></h3> 9495 9496 9497<p> 9498Opens the given file name in read mode 9499and returns an iterator function that 9500works like <code>file:lines(···)</code> over the opened file. 9501When the iterator function detects the end of file, 9502it returns no values (to finish the loop) and automatically closes the file. 9503 9504 9505<p> 9506The call <code>io.lines()</code> (with no file name) is equivalent 9507to <code>io.input():lines("*l")</code>; 9508that is, it iterates over the lines of the default input file. 9509In this case it does not close the file when the loop ends. 9510 9511 9512<p> 9513In case of errors this function raises the error, 9514instead of returning an error code. 9515 9516 9517 9518 9519<p> 9520<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> 9521 9522 9523<p> 9524This function opens a file, 9525in the mode specified in the string <code>mode</code>. 9526In case of success, 9527it returns a new file handle. 9528 9529 9530<p> 9531The <code>mode</code> string can be any of the following: 9532 9533<ul> 9534<li><b>"<code>r</code>": </b> read mode (the default);</li> 9535<li><b>"<code>w</code>": </b> write mode;</li> 9536<li><b>"<code>a</code>": </b> append mode;</li> 9537<li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li> 9538<li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li> 9539<li><b>"<code>a+</code>": </b> append update mode, previous data is preserved, 9540 writing is only allowed at the end of file.</li> 9541</ul><p> 9542The <code>mode</code> string can also have a '<code>b</code>' at the end, 9543which is needed in some systems to open the file in binary mode. 9544 9545 9546 9547 9548<p> 9549<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> 9550 9551 9552<p> 9553Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. 9554 9555 9556 9557 9558<p> 9559<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> 9560 9561 9562<p> 9563This function is system dependent and is not available 9564on all platforms. 9565 9566 9567<p> 9568Starts program <code>prog</code> in a separated process and returns 9569a file handle that you can use to read data from this program 9570(if <code>mode</code> is <code>"r"</code>, the default) 9571or to write data to this program 9572(if <code>mode</code> is <code>"w"</code>). 9573 9574 9575 9576 9577<p> 9578<hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> 9579 9580 9581<p> 9582Equivalent to <code>io.input():read(···)</code>. 9583 9584 9585 9586 9587<p> 9588<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> 9589 9590 9591<p> 9592In case of success, 9593returns a handle for a temporary file. 9594This file is opened in update mode 9595and it is automatically removed when the program ends. 9596 9597 9598 9599 9600<p> 9601<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> 9602 9603 9604<p> 9605Checks whether <code>obj</code> is a valid file handle. 9606Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, 9607<code>"closed file"</code> if <code>obj</code> is a closed file handle, 9608or <b>nil</b> if <code>obj</code> is not a file handle. 9609 9610 9611 9612 9613<p> 9614<hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> 9615 9616 9617<p> 9618Equivalent to <code>io.output():write(···)</code>. 9619 9620 9621 9622 9623<p> 9624<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> 9625 9626 9627<p> 9628Closes <code>file</code>. 9629Note that files are automatically closed when 9630their handles are garbage collected, 9631but that takes an unpredictable amount of time to happen. 9632 9633 9634<p> 9635When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>, 9636<a href="#pdf-file:close"><code>file:close</code></a> returns the same values 9637returned by <a href="#pdf-os.execute"><code>os.execute</code></a>. 9638 9639 9640 9641 9642<p> 9643<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> 9644 9645 9646<p> 9647Saves any written data to <code>file</code>. 9648 9649 9650 9651 9652<p> 9653<hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3> 9654 9655 9656<p> 9657Returns an iterator function that, 9658each time it is called, 9659reads the file according to the given formats. 9660When no format is given, 9661uses "<code>l</code>" as a default. 9662As an example, the construction 9663 9664<pre> 9665 for c in file:lines(1) do <em>body</em> end 9666</pre><p> 9667will iterate over all characters of the file, 9668starting at the current position. 9669Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file 9670when the loop ends. 9671 9672 9673<p> 9674In case of errors this function raises the error, 9675instead of returning an error code. 9676 9677 9678 9679 9680<p> 9681<hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> 9682 9683 9684<p> 9685Reads the file <code>file</code>, 9686according to the given formats, which specify what to read. 9687For each format, 9688the function returns a string or a number with the characters read, 9689or <b>nil</b> if it cannot read data with the specified format. 9690(In this latter case, 9691the function does not read subsequent formats.) 9692When called without formats, 9693it uses a default format that reads the next line 9694(see below). 9695 9696 9697<p> 9698The available formats are 9699 9700<ul> 9701 9702<li><b>"<code>n</code>": </b> 9703reads a numeral and returns it as a float or an integer, 9704following the lexical conventions of Lua. 9705(The numeral may have leading spaces and a sign.) 9706This format always reads the longest input sequence that 9707is a valid prefix for a numeral; 9708if that prefix does not form a valid numeral 9709(e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"), 9710it is discarded and the function returns <b>nil</b>. 9711</li> 9712 9713<li><b>"<code>a</code>": </b> 9714reads the whole file, starting at the current position. 9715On end of file, it returns the empty string. 9716</li> 9717 9718<li><b>"<code>l</code>": </b> 9719reads the next line skipping the end of line, 9720returning <b>nil</b> on end of file. 9721This is the default format. 9722</li> 9723 9724<li><b>"<code>L</code>": </b> 9725reads the next line keeping the end-of-line character (if present), 9726returning <b>nil</b> on end of file. 9727</li> 9728 9729<li><b><em>number</em>: </b> 9730reads a string with up to this number of bytes, 9731returning <b>nil</b> on end of file. 9732If <code>number</code> is zero, 9733it reads nothing and returns an empty string, 9734or <b>nil</b> on end of file. 9735</li> 9736 9737</ul><p> 9738The formats "<code>l</code>" and "<code>L</code>" should be used only for text files. 9739 9740 9741 9742 9743<p> 9744<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3> 9745 9746 9747<p> 9748Sets and gets the file position, 9749measured from the beginning of the file, 9750to the position given by <code>offset</code> plus a base 9751specified by the string <code>whence</code>, as follows: 9752 9753<ul> 9754<li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li> 9755<li><b>"<code>cur</code>": </b> base is current position;</li> 9756<li><b>"<code>end</code>": </b> base is end of file;</li> 9757</ul><p> 9758In case of success, <code>seek</code> returns the final file position, 9759measured in bytes from the beginning of the file. 9760If <code>seek</code> fails, it returns <b>nil</b>, 9761plus a string describing the error. 9762 9763 9764<p> 9765The default value for <code>whence</code> is <code>"cur"</code>, 9766and for <code>offset</code> is 0. 9767Therefore, the call <code>file:seek()</code> returns the current 9768file position, without changing it; 9769the call <code>file:seek("set")</code> sets the position to the 9770beginning of the file (and returns 0); 9771and the call <code>file:seek("end")</code> sets the position to the 9772end of the file, and returns its size. 9773 9774 9775 9776 9777<p> 9778<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> 9779 9780 9781<p> 9782Sets the buffering mode for an output file. 9783There are three available modes: 9784 9785<ul> 9786 9787<li><b>"<code>no</code>": </b> 9788no buffering; the result of any output operation appears immediately. 9789</li> 9790 9791<li><b>"<code>full</code>": </b> 9792full buffering; output operation is performed only 9793when the buffer is full or when 9794you explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>). 9795</li> 9796 9797<li><b>"<code>line</code>": </b> 9798line buffering; output is buffered until a newline is output 9799or there is any input from some special files 9800(such as a terminal device). 9801</li> 9802 9803</ul><p> 9804For the last two cases, <code>size</code> 9805specifies the size of the buffer, in bytes. 9806The default is an appropriate size. 9807 9808 9809 9810 9811<p> 9812<hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> 9813 9814 9815<p> 9816Writes the value of each of its arguments to <code>file</code>. 9817The arguments must be strings or numbers. 9818 9819 9820<p> 9821In case of success, this function returns <code>file</code>. 9822Otherwise it returns <b>nil</b> plus a string describing the error. 9823 9824 9825 9826 9827 9828 9829 9830<h2>6.9 – <a name="6.9">Operating System Facilities</a></h2> 9831 9832<p> 9833This library is implemented through table <a name="pdf-os"><code>os</code></a>. 9834 9835 9836<p> 9837<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> 9838 9839 9840<p> 9841Returns an approximation of the amount in seconds of CPU time 9842used by the program. 9843 9844 9845 9846 9847<p> 9848<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> 9849 9850 9851<p> 9852Returns a string or a table containing date and time, 9853formatted according to the given string <code>format</code>. 9854 9855 9856<p> 9857If the <code>time</code> argument is present, 9858this is the time to be formatted 9859(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). 9860Otherwise, <code>date</code> formats the current time. 9861 9862 9863<p> 9864If <code>format</code> starts with '<code>!</code>', 9865then the date is formatted in Coordinated Universal Time. 9866After this optional character, 9867if <code>format</code> is the string "<code>*t</code>", 9868then <code>date</code> returns a table with the following fields: 9869<code>year</code>, <code>month</code> (1–12), <code>day</code> (1–31), 9870<code>hour</code> (0–23), <code>min</code> (0–59), <code>sec</code> (0–61), 9871<code>wday</code> (weekday, 1–7, Sunday is 1), 9872<code>yday</code> (day of the year, 1–366), 9873and <code>isdst</code> (daylight saving flag, a boolean). 9874This last field may be absent 9875if the information is not available. 9876 9877 9878<p> 9879If <code>format</code> is not "<code>*t</code>", 9880then <code>date</code> returns the date as a string, 9881formatted according to the same rules as the ISO C function <code>strftime</code>. 9882 9883 9884<p> 9885When called without arguments, 9886<code>date</code> returns a reasonable date and time representation that depends on 9887the host system and on the current locale. 9888(More specifically, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>.) 9889 9890 9891<p> 9892On non-POSIX systems, 9893this function may be not thread safe 9894because of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>. 9895 9896 9897 9898 9899<p> 9900<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> 9901 9902 9903<p> 9904Returns the difference, in seconds, 9905from time <code>t1</code> to time <code>t2</code> 9906(where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>). 9907In POSIX, Windows, and some other systems, 9908this value is exactly <code>t2</code><em>-</em><code>t1</code>. 9909 9910 9911 9912 9913<p> 9914<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> 9915 9916 9917<p> 9918This function is equivalent to the ISO C function <code>system</code>. 9919It passes <code>command</code> to be executed by an operating system shell. 9920Its first result is <b>true</b> 9921if the command terminated successfully, 9922or <b>nil</b> otherwise. 9923After this first result 9924the function returns a string plus a number, 9925as follows: 9926 9927<ul> 9928 9929<li><b>"<code>exit</code>": </b> 9930the command terminated normally; 9931the following number is the exit status of the command. 9932</li> 9933 9934<li><b>"<code>signal</code>": </b> 9935the command was terminated by a signal; 9936the following number is the signal that terminated the command. 9937</li> 9938 9939</ul> 9940 9941<p> 9942When called without a <code>command</code>, 9943<code>os.execute</code> returns a boolean that is true if a shell is available. 9944 9945 9946 9947 9948<p> 9949<hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3> 9950 9951 9952<p> 9953Calls the ISO C function <code>exit</code> to terminate the host program. 9954If <code>code</code> is <b>true</b>, 9955the returned status is <code>EXIT_SUCCESS</code>; 9956if <code>code</code> is <b>false</b>, 9957the returned status is <code>EXIT_FAILURE</code>; 9958if <code>code</code> is a number, 9959the returned status is this number. 9960The default value for <code>code</code> is <b>true</b>. 9961 9962 9963<p> 9964If the optional second argument <code>close</code> is true, 9965closes the Lua state before exiting. 9966 9967 9968 9969 9970<p> 9971<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> 9972 9973 9974<p> 9975Returns the value of the process environment variable <code>varname</code>, 9976or <b>nil</b> if the variable is not defined. 9977 9978 9979 9980 9981<p> 9982<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> 9983 9984 9985<p> 9986Deletes the file (or empty directory, on POSIX systems) 9987with the given name. 9988If this function fails, it returns <b>nil</b>, 9989plus a string describing the error and the error code. 9990 9991 9992 9993 9994<p> 9995<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> 9996 9997 9998<p> 9999Renames file or directory named <code>oldname</code> to <code>newname</code>. 10000If this function fails, it returns <b>nil</b>, 10001plus a string describing the error and the error code. 10002 10003 10004 10005 10006<p> 10007<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> 10008 10009 10010<p> 10011Sets the current locale of the program. 10012<code>locale</code> is a system-dependent string specifying a locale; 10013<code>category</code> is an optional string describing which category to change: 10014<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, 10015<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; 10016the default category is <code>"all"</code>. 10017The function returns the name of the new locale, 10018or <b>nil</b> if the request cannot be honored. 10019 10020 10021<p> 10022If <code>locale</code> is the empty string, 10023the current locale is set to an implementation-defined native locale. 10024If <code>locale</code> is the string "<code>C</code>", 10025the current locale is set to the standard C locale. 10026 10027 10028<p> 10029When called with <b>nil</b> as the first argument, 10030this function only returns the name of the current locale 10031for the given category. 10032 10033 10034<p> 10035This function may be not thread safe 10036because of its reliance on C function <code>setlocale</code>. 10037 10038 10039 10040 10041<p> 10042<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> 10043 10044 10045<p> 10046Returns the current time when called without arguments, 10047or a time representing the local date and time specified by the given table. 10048This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, 10049and may have fields 10050<code>hour</code> (default is 12), 10051<code>min</code> (default is 0), 10052<code>sec</code> (default is 0), 10053and <code>isdst</code> (default is <b>nil</b>). 10054Other fields are ignored. 10055For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function. 10056 10057 10058<p> 10059The values in these fields do not need to be inside their valid ranges. 10060For instance, if <code>sec</code> is -10, 10061it means -10 seconds from the time specified by the other fields; 10062if <code>hour</code> is 1000, 10063it means +1000 hours from the time specified by the other fields. 10064 10065 10066<p> 10067The returned value is a number, whose meaning depends on your system. 10068In POSIX, Windows, and some other systems, 10069this number counts the number 10070of seconds since some given start time (the "epoch"). 10071In other systems, the meaning is not specified, 10072and the number returned by <code>time</code> can be used only as an argument to 10073<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. 10074 10075 10076 10077 10078<p> 10079<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> 10080 10081 10082<p> 10083Returns a string with a file name that can 10084be used for a temporary file. 10085The file must be explicitly opened before its use 10086and explicitly removed when no longer needed. 10087 10088 10089<p> 10090On POSIX systems, 10091this function also creates a file with that name, 10092to avoid security risks. 10093(Someone else might create the file with wrong permissions 10094in the time between getting the name and creating the file.) 10095You still have to open the file to use it 10096and to remove it (even if you do not use it). 10097 10098 10099<p> 10100When possible, 10101you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, 10102which automatically removes the file when the program ends. 10103 10104 10105 10106 10107 10108 10109 10110<h2>6.10 – <a name="6.10">The Debug Library</a></h2> 10111 10112<p> 10113This library provides 10114the functionality of the debug interface (<a href="#4.9">§4.9</a>) to Lua programs. 10115You should exert care when using this library. 10116Several of its functions 10117violate basic assumptions about Lua code 10118(e.g., that variables local to a function 10119cannot be accessed from outside; 10120that userdata metatables cannot be changed by Lua code; 10121that Lua programs do not crash) 10122and therefore can compromise otherwise secure code. 10123Moreover, some functions in this library may be slow. 10124 10125 10126<p> 10127All functions in this library are provided 10128inside the <a name="pdf-debug"><code>debug</code></a> table. 10129All functions that operate over a thread 10130have an optional first argument which is the 10131thread to operate over. 10132The default is always the current thread. 10133 10134 10135<p> 10136<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> 10137 10138 10139<p> 10140Enters an interactive mode with the user, 10141running each string that the user enters. 10142Using simple commands and other debug facilities, 10143the user can inspect global and local variables, 10144change their values, evaluate expressions, and so on. 10145A line containing only the word <code>cont</code> finishes this function, 10146so that the caller continues its execution. 10147 10148 10149<p> 10150Note that commands for <code>debug.debug</code> are not lexically nested 10151within any function and so have no direct access to local variables. 10152 10153 10154 10155 10156<p> 10157<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> 10158 10159 10160<p> 10161Returns the current hook settings of the thread, as three values: 10162the current hook function, the current hook mask, 10163and the current hook count 10164(as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). 10165 10166 10167 10168 10169<p> 10170<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> 10171 10172 10173<p> 10174Returns a table with information about a function. 10175You can give the function directly 10176or you can give a number as the value of <code>f</code>, 10177which means the function running at level <code>f</code> of the call stack 10178of the given thread: 10179level 0 is the current function (<code>getinfo</code> itself); 10180level 1 is the function that called <code>getinfo</code> 10181(except for tail calls, which do not count on the stack); 10182and so on. 10183If <code>f</code> is a number larger than the number of active functions, 10184then <code>getinfo</code> returns <b>nil</b>. 10185 10186 10187<p> 10188The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, 10189with the string <code>what</code> describing which fields to fill in. 10190The default for <code>what</code> is to get all information available, 10191except the table of valid lines. 10192If present, 10193the option '<code>f</code>' 10194adds a field named <code>func</code> with the function itself. 10195If present, 10196the option '<code>L</code>' 10197adds a field named <code>activelines</code> with the table of 10198valid lines. 10199 10200 10201<p> 10202For instance, the expression <code>debug.getinfo(1,"n").name</code> returns 10203a name for the current function, 10204if a reasonable name can be found, 10205and the expression <code>debug.getinfo(print)</code> 10206returns a table with all available information 10207about the <a href="#pdf-print"><code>print</code></a> function. 10208 10209 10210 10211 10212<p> 10213<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3> 10214 10215 10216<p> 10217This function returns the name and the value of the local variable 10218with index <code>local</code> of the function at level <code>f</code> of the stack. 10219This function accesses not only explicit local variables, 10220but also parameters, temporaries, etc. 10221 10222 10223<p> 10224The first parameter or local variable has index 1, and so on, 10225following the order that they are declared in the code, 10226counting only the variables that are active 10227in the current scope of the function. 10228Negative indices refer to vararg parameters; 10229-1 is the first vararg parameter. 10230The function returns <b>nil</b> if there is no variable with the given index, 10231and raises an error when called with a level out of range. 10232(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) 10233 10234 10235<p> 10236Variable names starting with '<code>(</code>' (open parenthesis) 10237represent variables with no known names 10238(internal variables such as loop control variables, 10239and variables from chunks saved without debug information). 10240 10241 10242<p> 10243The parameter <code>f</code> may also be a function. 10244In that case, <code>getlocal</code> returns only the name of function parameters. 10245 10246 10247 10248 10249<p> 10250<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3> 10251 10252 10253<p> 10254Returns the metatable of the given <code>value</code> 10255or <b>nil</b> if it does not have a metatable. 10256 10257 10258 10259 10260<p> 10261<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> 10262 10263 10264<p> 10265Returns the registry table (see <a href="#4.5">§4.5</a>). 10266 10267 10268 10269 10270<p> 10271<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3> 10272 10273 10274<p> 10275This function returns the name and the value of the upvalue 10276with index <code>up</code> of the function <code>f</code>. 10277The function returns <b>nil</b> if there is no upvalue with the given index. 10278 10279 10280<p> 10281Variable names starting with '<code>(</code>' (open parenthesis) 10282represent variables with no known names 10283(variables from chunks saved without debug information). 10284 10285 10286 10287 10288<p> 10289<hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3> 10290 10291 10292<p> 10293Returns the Lua value associated to <code>u</code>. 10294If <code>u</code> is not a userdata, 10295returns <b>nil</b>. 10296 10297 10298 10299 10300<p> 10301<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> 10302 10303 10304<p> 10305Sets the given function as a hook. 10306The string <code>mask</code> and the number <code>count</code> describe 10307when the hook will be called. 10308The string mask may have any combination of the following characters, 10309with the given meaning: 10310 10311<ul> 10312<li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li> 10313<li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li> 10314<li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li> 10315</ul><p> 10316Moreover, 10317with a <code>count</code> different from zero, 10318the hook is called also after every <code>count</code> instructions. 10319 10320 10321<p> 10322When called without arguments, 10323<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. 10324 10325 10326<p> 10327When the hook is called, its first parameter is a string 10328describing the event that has triggered its call: 10329<code>"call"</code> (or <code>"tail call"</code>), 10330<code>"return"</code>, 10331<code>"line"</code>, and <code>"count"</code>. 10332For line events, 10333the hook also gets the new line number as its second parameter. 10334Inside a hook, 10335you can call <code>getinfo</code> with level 2 to get more information about 10336the running function 10337(level 0 is the <code>getinfo</code> function, 10338and level 1 is the hook function). 10339 10340 10341 10342 10343<p> 10344<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> 10345 10346 10347<p> 10348This function assigns the value <code>value</code> to the local variable 10349with index <code>local</code> of the function at level <code>level</code> of the stack. 10350The function returns <b>nil</b> if there is no local 10351variable with the given index, 10352and raises an error when called with a <code>level</code> out of range. 10353(You can call <code>getinfo</code> to check whether the level is valid.) 10354Otherwise, it returns the name of the local variable. 10355 10356 10357<p> 10358See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about 10359variable indices and names. 10360 10361 10362 10363 10364<p> 10365<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> 10366 10367 10368<p> 10369Sets the metatable for the given <code>value</code> to the given <code>table</code> 10370(which can be <b>nil</b>). 10371Returns <code>value</code>. 10372 10373 10374 10375 10376<p> 10377<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> 10378 10379 10380<p> 10381This function assigns the value <code>value</code> to the upvalue 10382with index <code>up</code> of the function <code>f</code>. 10383The function returns <b>nil</b> if there is no upvalue 10384with the given index. 10385Otherwise, it returns the name of the upvalue. 10386 10387 10388 10389 10390<p> 10391<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3> 10392 10393 10394<p> 10395Sets the given <code>value</code> as 10396the Lua value associated to the given <code>udata</code>. 10397<code>udata</code> must be a full userdata. 10398 10399 10400<p> 10401Returns <code>udata</code>. 10402 10403 10404 10405 10406<p> 10407<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> 10408 10409 10410<p> 10411If <code>message</code> is present but is neither a string nor <b>nil</b>, 10412this function returns <code>message</code> without further processing. 10413Otherwise, 10414it returns a string with a traceback of the call stack. 10415The optional <code>message</code> string is appended 10416at the beginning of the traceback. 10417An optional <code>level</code> number tells at which level 10418to start the traceback 10419(default is 1, the function calling <code>traceback</code>). 10420 10421 10422 10423 10424<p> 10425<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3> 10426 10427 10428<p> 10429Returns a unique identifier (as a light userdata) 10430for the upvalue numbered <code>n</code> 10431from the given function. 10432 10433 10434<p> 10435These unique identifiers allow a program to check whether different 10436closures share upvalues. 10437Lua closures that share an upvalue 10438(that is, that access a same external local variable) 10439will return identical ids for those upvalue indices. 10440 10441 10442 10443 10444<p> 10445<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3> 10446 10447 10448<p> 10449Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code> 10450refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>. 10451 10452 10453 10454 10455 10456 10457 10458<h1>7 – <a name="7">Lua Standalone</a></h1> 10459 10460<p> 10461Although Lua has been designed as an extension language, 10462to be embedded in a host C program, 10463it is also frequently used as a standalone language. 10464An interpreter for Lua as a standalone language, 10465called simply <code>lua</code>, 10466is provided with the standard distribution. 10467The standalone interpreter includes 10468all standard libraries, including the debug library. 10469Its usage is: 10470 10471<pre> 10472 lua [options] [script [args]] 10473</pre><p> 10474The options are: 10475 10476<ul> 10477<li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li> 10478<li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li> 10479<li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li> 10480<li><b><code>-v</code>: </b> prints version information;</li> 10481<li><b><code>-E</code>: </b> ignores environment variables;</li> 10482<li><b><code>--</code>: </b> stops handling options;</li> 10483<li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li> 10484</ul><p> 10485After handling its options, <code>lua</code> runs the given <em>script</em>. 10486When called without arguments, 10487<code>lua</code> behaves as <code>lua -v -i</code> 10488when the standard input (<code>stdin</code>) is a terminal, 10489and as <code>lua -</code> otherwise. 10490 10491 10492<p> 10493When called without option <code>-E</code>, 10494the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a> 10495(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined) 10496before running any argument. 10497If the variable content has the format <code>@<em>filename</em></code>, 10498then <code>lua</code> executes the file. 10499Otherwise, <code>lua</code> executes the string itself. 10500 10501 10502<p> 10503When called with option <code>-E</code>, 10504besides ignoring <code>LUA_INIT</code>, 10505Lua also ignores 10506the values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>, 10507setting the values of 10508<a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a> 10509with the default paths defined in <code>luaconf.h</code>. 10510 10511 10512<p> 10513All options are handled in order, except <code>-i</code> and <code>-E</code>. 10514For instance, an invocation like 10515 10516<pre> 10517 $ lua -e'a=1' -e 'print(a)' script.lua 10518</pre><p> 10519will first set <code>a</code> to 1, then print the value of <code>a</code>, 10520and finally run the file <code>script.lua</code> with no arguments. 10521(Here <code>$</code> is the shell prompt. Your prompt may be different.) 10522 10523 10524<p> 10525Before running any code, 10526<code>lua</code> collects all command-line arguments 10527in a global table called <code>arg</code>. 10528The script name goes to index 0, 10529the first argument after the script name goes to index 1, 10530and so on. 10531Any arguments before the script name 10532(that is, the interpreter name plus its options) 10533go to negative indices. 10534For instance, in the call 10535 10536<pre> 10537 $ lua -la b.lua t1 t2 10538</pre><p> 10539the table is like this: 10540 10541<pre> 10542 arg = { [-2] = "lua", [-1] = "-la", 10543 [0] = "b.lua", 10544 [1] = "t1", [2] = "t2" } 10545</pre><p> 10546If there is no script in the call, 10547the interpreter name goes to index 0, 10548followed by the other arguments. 10549For instance, the call 10550 10551<pre> 10552 $ lua -e "print(arg[1])" 10553</pre><p> 10554will print "<code>-e</code>". 10555If there is a script, 10556the script is called with parameters 10557<code>arg[1]</code>, ···, <code>arg[#arg]</code>. 10558(Like all chunks in Lua, 10559the script is compiled as a vararg function.) 10560 10561 10562<p> 10563In interactive mode, 10564Lua repeatedly prompts and waits for a line. 10565After reading a line, 10566Lua first try to interpret the line as an expression. 10567If it succeeds, it prints its value. 10568Otherwise, it interprets the line as a statement. 10569If you write an incomplete statement, 10570the interpreter waits for its completion 10571by issuing a different prompt. 10572 10573 10574<p> 10575If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, 10576then its value is used as the prompt. 10577Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, 10578its value is used as the secondary prompt 10579(issued during incomplete statements). 10580 10581 10582<p> 10583In case of unprotected errors in the script, 10584the interpreter reports the error to the standard error stream. 10585If the error object is not a string but 10586has a metamethod <code>__tostring</code>, 10587the interpreter calls this metamethod to produce the final message. 10588Otherwise, the interpreter converts the error object to a string 10589and adds a stack traceback to it. 10590 10591 10592<p> 10593When finishing normally, 10594the interpreter closes its main Lua state 10595(see <a href="#lua_close"><code>lua_close</code></a>). 10596The script can avoid this step by 10597calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate. 10598 10599 10600<p> 10601To allow the use of Lua as a 10602script interpreter in Unix systems, 10603the standalone interpreter skips 10604the first line of a chunk if it starts with <code>#</code>. 10605Therefore, Lua scripts can be made into executable programs 10606by using <code>chmod +x</code> and the <code>#!</code> form, 10607as in 10608 10609<pre> 10610 #!/usr/local/bin/lua 10611</pre><p> 10612(Of course, 10613the location of the Lua interpreter may be different in your machine. 10614If <code>lua</code> is in your <code>PATH</code>, 10615then 10616 10617<pre> 10618 #!/usr/bin/env lua 10619</pre><p> 10620is a more portable solution.) 10621 10622 10623 10624<h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> 10625 10626<p> 10627Here we list the incompatibilities that you may find when moving a program 10628from Lua 5.2 to Lua 5.3. 10629You can avoid some incompatibilities by compiling Lua with 10630appropriate options (see file <code>luaconf.h</code>). 10631However, 10632all these compatibility options will be removed in the future. 10633 10634 10635<p> 10636Lua versions can always change the C API in ways that 10637do not imply source-code changes in a program, 10638such as the numeric values for constants 10639or the implementation of functions as macros. 10640Therefore, 10641you should not assume that binaries are compatible between 10642different Lua versions. 10643Always recompile clients of the Lua API when 10644using a new version. 10645 10646 10647<p> 10648Similarly, Lua versions can always change the internal representation 10649of precompiled chunks; 10650precompiled chunks are not compatible between different Lua versions. 10651 10652 10653<p> 10654The standard paths in the official distribution may 10655change between versions. 10656 10657 10658 10659<h2>8.1 – <a name="8.1">Changes in the Language</a></h2> 10660<ul> 10661 10662<li> 10663The main difference between Lua 5.2 and Lua 5.3 is the 10664introduction of an integer subtype for numbers. 10665Although this change should not affect "normal" computations, 10666some computations 10667(mainly those that involve some kind of overflow) 10668can give different results. 10669 10670 10671<p> 10672You can fix these differences by forcing a number to be a float 10673(in Lua 5.2 all numbers were float), 10674in particular writing constants with an ending <code>.0</code> 10675or using <code>x = x + 0.0</code> to convert a variable. 10676(This recommendation is only for a quick fix 10677for an occasional incompatibility; 10678it is not a general guideline for good programming. 10679For good programming, 10680use floats where you need floats 10681and integers where you need integers.) 10682</li> 10683 10684<li> 10685The conversion of a float to a string now adds a <code>.0</code> suffix 10686to the result if it looks like an integer. 10687(For instance, the float 2.0 will be printed as <code>2.0</code>, 10688not as <code>2</code>.) 10689You should always use an explicit format 10690when you need a specific format for numbers. 10691 10692 10693<p> 10694(Formally this is not an incompatibility, 10695because Lua does not specify how numbers are formatted as strings, 10696but some programs assumed a specific format.) 10697</li> 10698 10699<li> 10700The generational mode for the garbage collector was removed. 10701(It was an experimental feature in Lua 5.2.) 10702</li> 10703 10704</ul> 10705 10706 10707 10708 10709<h2>8.2 – <a name="8.2">Changes in the Libraries</a></h2> 10710<ul> 10711 10712<li> 10713The <code>bit32</code> library has been deprecated. 10714It is easy to require a compatible external library or, 10715better yet, to replace its functions with appropriate bitwise operations. 10716(Keep in mind that <code>bit32</code> operates on 32-bit integers, 10717while the bitwise operators in Lua 5.3 operate on Lua integers, 10718which by default have 64 bits.) 10719</li> 10720 10721<li> 10722The Table library now respects metamethods 10723for setting and getting elements. 10724</li> 10725 10726<li> 10727The <a href="#pdf-ipairs"><code>ipairs</code></a> iterator now respects metamethods and 10728its <code>__ipairs</code> metamethod has been deprecated. 10729</li> 10730 10731<li> 10732Option names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore. 10733For compatibility, Lua will continue to accept (and ignore) this character. 10734</li> 10735 10736<li> 10737The following functions were deprecated in the mathematical library: 10738<code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>, 10739<code>frexp</code>, and <code>ldexp</code>. 10740You can replace <code>math.pow(x,y)</code> with <code>x^y</code>; 10741you can replace <code>math.atan2</code> with <code>math.atan</code>, 10742which now accepts one or two parameters; 10743you can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>. 10744For the other operations, 10745you can either use an external library or 10746implement them in Lua. 10747</li> 10748 10749<li> 10750The searcher for C loaders used by <a href="#pdf-require"><code>require</code></a> 10751changed the way it handles versioned names. 10752Now, the version should come after the module name 10753(as is usual in most other tools). 10754For compatibility, that searcher still tries the old format 10755if it cannot find an open function according to the new style. 10756(Lua 5.2 already worked that way, 10757but it did not document the change.) 10758</li> 10759 10760<li> 10761The call <code>collectgarbage("count")</code> now returns only one result. 10762(You can compute that second result from the fractional part 10763of the first result.) 10764</li> 10765 10766</ul> 10767 10768 10769 10770 10771<h2>8.3 – <a name="8.3">Changes in the API</a></h2> 10772 10773 10774<ul> 10775 10776<li> 10777Continuation functions now receive as parameters what they needed 10778to get through <code>lua_getctx</code>, 10779so <code>lua_getctx</code> has been removed. 10780Adapt your code accordingly. 10781</li> 10782 10783<li> 10784Function <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>. 10785Use 0 as the value of this parameter to get the old behavior. 10786</li> 10787 10788<li> 10789Functions to inject/project unsigned integers 10790(<code>lua_pushunsigned</code>, <code>lua_tounsigned</code>, <code>lua_tounsignedx</code>, 10791<code>luaL_checkunsigned</code>, <code>luaL_optunsigned</code>) 10792were deprecated. 10793Use their signed equivalents with a type cast. 10794</li> 10795 10796<li> 10797Macros to project non-default integer types 10798(<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>) 10799were deprecated. 10800Use their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast 10801(or, when possible, use <a href="#lua_Integer"><code>lua_Integer</code></a> in your code). 10802</li> 10803 10804</ul> 10805 10806 10807 10808 10809<h1>9 – <a name="9">The Complete Syntax of Lua</a></h1> 10810 10811<p> 10812Here is the complete syntax of Lua in extended BNF. 10813As usual in extended BNF, 10814{A} means 0 or more As, 10815and [A] means an optional A. 10816(For operator precedences, see <a href="#3.4.8">§3.4.8</a>; 10817for a description of the terminals 10818Name, Numeral, 10819and LiteralString, see <a href="#3.1">§3.1</a>.) 10820 10821 10822 10823 10824<pre> 10825 10826 chunk ::= block 10827 10828 block ::= {stat} [retstat] 10829 10830 stat ::= ‘<b>;</b>’ | 10831 varlist ‘<b>=</b>’ explist | 10832 functioncall | 10833 label | 10834 <b>break</b> | 10835 <b>goto</b> Name | 10836 <b>do</b> block <b>end</b> | 10837 <b>while</b> exp <b>do</b> block <b>end</b> | 10838 <b>repeat</b> block <b>until</b> exp | 10839 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 10840 <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> | 10841 <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 10842 <b>function</b> funcname funcbody | 10843 <b>local</b> <b>function</b> Name funcbody | 10844 <b>local</b> namelist [‘<b>=</b>’ explist] 10845 10846 retstat ::= <b>return</b> [explist] [‘<b>;</b>’] 10847 10848 label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 10849 10850 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 10851 10852 varlist ::= var {‘<b>,</b>’ var} 10853 10854 var ::= Name | prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | prefixexp ‘<b>.</b>’ Name 10855 10856 namelist ::= Name {‘<b>,</b>’ Name} 10857 10858 explist ::= exp {‘<b>,</b>’ exp} 10859 10860 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | ‘<b>...</b>’ | functiondef | 10861 prefixexp | tableconstructor | exp binop exp | unop exp 10862 10863 prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 10864 10865 functioncall ::= prefixexp args | prefixexp ‘<b>:</b>’ Name args 10866 10867 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | tableconstructor | LiteralString 10868 10869 functiondef ::= <b>function</b> funcbody 10870 10871 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 10872 10873 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 10874 10875 tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 10876 10877 fieldlist ::= field {fieldsep field} [fieldsep] 10878 10879 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 10880 10881 fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 10882 10883 binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</b>’ | ‘<b>//</b>’ | ‘<b>^</b>’ | ‘<b>%</b>’ | 10884 ‘<b>&</b>’ | ‘<b>~</b>’ | ‘<b>|</b>’ | ‘<b>>></b>’ | ‘<b><<</b>’ | ‘<b>..</b>’ | 10885 ‘<b><</b>’ | ‘<b><=</b>’ | ‘<b>></b>’ | ‘<b>>=</b>’ | ‘<b>==</b>’ | ‘<b>~=</b>’ | 10886 <b>and</b> | <b>or</b> 10887 10888 unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’ | ‘<b>~</b>’ 10889 10890</pre> 10891 10892<p> 10893 10894 10895 10896 10897 10898 10899 10900 10901<P CLASS="footer"> 10902Last update: 10903Mon May 30 13:11:08 BRT 2016 10904</P> 10905<!-- 10906Last change: revised for Lua 5.3.3 10907--> 10908 10909</body></html> 10910 10911
