18e3e3a7aSWarner Losh<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 28e3e3a7aSWarner Losh<HTML> 38e3e3a7aSWarner Losh<HEAD> 48e3e3a7aSWarner Losh<TITLE>Lua 5.3 Reference Manual</TITLE> 58e3e3a7aSWarner Losh<LINK REL="stylesheet" TYPE="text/css" HREF="lua.css"> 68e3e3a7aSWarner Losh<LINK REL="stylesheet" TYPE="text/css" HREF="manual.css"> 78e3e3a7aSWarner Losh<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> 88e3e3a7aSWarner Losh</HEAD> 98e3e3a7aSWarner Losh 108e3e3a7aSWarner Losh<BODY> 118e3e3a7aSWarner Losh 128e3e3a7aSWarner Losh<H1> 138e3e3a7aSWarner Losh<A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A> 148e3e3a7aSWarner LoshLua 5.3 Reference Manual 158e3e3a7aSWarner Losh</H1> 168e3e3a7aSWarner Losh 178e3e3a7aSWarner Losh<P> 188e3e3a7aSWarner Loshby Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes 198e3e3a7aSWarner Losh 208e3e3a7aSWarner Losh<P> 218e3e3a7aSWarner Losh<SMALL> 22*e112e9d2SKyle EvansCopyright © 2015–2018 Lua.org, PUC-Rio. 238e3e3a7aSWarner LoshFreely available under the terms of the 248e3e3a7aSWarner Losh<a href="http://www.lua.org/license.html">Lua license</a>. 258e3e3a7aSWarner Losh</SMALL> 268e3e3a7aSWarner Losh 278e3e3a7aSWarner Losh<DIV CLASS="menubar"> 288e3e3a7aSWarner Losh<A HREF="contents.html#contents">contents</A> 298e3e3a7aSWarner Losh· 308e3e3a7aSWarner Losh<A HREF="contents.html#index">index</A> 318e3e3a7aSWarner Losh· 328e3e3a7aSWarner Losh<A HREF="http://www.lua.org/manual/">other versions</A> 338e3e3a7aSWarner Losh</DIV> 348e3e3a7aSWarner Losh 358e3e3a7aSWarner Losh<!-- ====================================================================== --> 368e3e3a7aSWarner Losh<p> 378e3e3a7aSWarner Losh 38*e112e9d2SKyle Evans<!-- $Id: manual.of,v 1.167.1.2 2018/06/26 15:49:07 roberto Exp $ --> 398e3e3a7aSWarner Losh 408e3e3a7aSWarner Losh 418e3e3a7aSWarner Losh 428e3e3a7aSWarner Losh 438e3e3a7aSWarner Losh<h1>1 – <a name="1">Introduction</a></h1> 448e3e3a7aSWarner Losh 458e3e3a7aSWarner Losh<p> 468e3e3a7aSWarner LoshLua is a powerful, efficient, lightweight, embeddable scripting language. 478e3e3a7aSWarner LoshIt supports procedural programming, 488e3e3a7aSWarner Loshobject-oriented programming, functional programming, 498e3e3a7aSWarner Loshdata-driven programming, and data description. 508e3e3a7aSWarner Losh 518e3e3a7aSWarner Losh 528e3e3a7aSWarner Losh<p> 538e3e3a7aSWarner LoshLua combines simple procedural syntax with powerful data description 548e3e3a7aSWarner Loshconstructs based on associative arrays and extensible semantics. 558e3e3a7aSWarner LoshLua is dynamically typed, 568e3e3a7aSWarner Loshruns by interpreting bytecode with a register-based 578e3e3a7aSWarner Loshvirtual machine, 588e3e3a7aSWarner Loshand has automatic memory management with 598e3e3a7aSWarner Loshincremental garbage collection, 608e3e3a7aSWarner Loshmaking it ideal for configuration, scripting, 618e3e3a7aSWarner Loshand rapid prototyping. 628e3e3a7aSWarner Losh 638e3e3a7aSWarner Losh 648e3e3a7aSWarner Losh<p> 658e3e3a7aSWarner LoshLua is implemented as a library, written in <em>clean C</em>, 668e3e3a7aSWarner Loshthe common subset of Standard C and C++. 678e3e3a7aSWarner LoshThe Lua distribution includes a host program called <code>lua</code>, 688e3e3a7aSWarner Loshwhich uses the Lua library to offer a complete, 698e3e3a7aSWarner Loshstandalone Lua interpreter, 708e3e3a7aSWarner Loshfor interactive or batch use. 718e3e3a7aSWarner LoshLua is intended to be used both as a powerful, lightweight, 728e3e3a7aSWarner Loshembeddable scripting language for any program that needs one, 738e3e3a7aSWarner Loshand as a powerful but lightweight and efficient stand-alone language. 748e3e3a7aSWarner Losh 758e3e3a7aSWarner Losh 768e3e3a7aSWarner Losh<p> 778e3e3a7aSWarner LoshAs an extension language, Lua has no notion of a "main" program: 788e3e3a7aSWarner Loshit works <em>embedded</em> in a host client, 798e3e3a7aSWarner Loshcalled the <em>embedding program</em> or simply the <em>host</em>. 808e3e3a7aSWarner Losh(Frequently, this host is the stand-alone <code>lua</code> program.) 818e3e3a7aSWarner LoshThe host program can invoke functions to execute a piece of Lua code, 828e3e3a7aSWarner Loshcan write and read Lua variables, 838e3e3a7aSWarner Loshand can register C functions to be called by Lua code. 848e3e3a7aSWarner LoshThrough the use of C functions, Lua can be augmented to cope with 858e3e3a7aSWarner Losha wide range of different domains, 868e3e3a7aSWarner Loshthus creating customized programming languages sharing a syntactical framework. 878e3e3a7aSWarner Losh 888e3e3a7aSWarner Losh 898e3e3a7aSWarner Losh<p> 908e3e3a7aSWarner LoshLua is free software, 918e3e3a7aSWarner Loshand is provided as usual with no guarantees, 928e3e3a7aSWarner Loshas stated in its license. 938e3e3a7aSWarner LoshThe implementation described in this manual is available 948e3e3a7aSWarner Loshat Lua's official web site, <code>www.lua.org</code>. 958e3e3a7aSWarner Losh 968e3e3a7aSWarner Losh 978e3e3a7aSWarner Losh<p> 988e3e3a7aSWarner LoshLike any other reference manual, 998e3e3a7aSWarner Loshthis document is dry in places. 1008e3e3a7aSWarner LoshFor a discussion of the decisions behind the design of Lua, 1018e3e3a7aSWarner Loshsee the technical papers available at Lua's web site. 1028e3e3a7aSWarner LoshFor a detailed introduction to programming in Lua, 1038e3e3a7aSWarner Loshsee Roberto's book, <em>Programming in Lua</em>. 1048e3e3a7aSWarner Losh 1058e3e3a7aSWarner Losh 1068e3e3a7aSWarner Losh 1078e3e3a7aSWarner Losh<h1>2 – <a name="2">Basic Concepts</a></h1> 1088e3e3a7aSWarner Losh 1098e3e3a7aSWarner Losh<p> 1108e3e3a7aSWarner LoshThis section describes the basic concepts of the language. 1118e3e3a7aSWarner Losh 1128e3e3a7aSWarner Losh 1138e3e3a7aSWarner Losh 1148e3e3a7aSWarner Losh<h2>2.1 – <a name="2.1">Values and Types</a></h2> 1158e3e3a7aSWarner Losh 1168e3e3a7aSWarner Losh<p> 1178e3e3a7aSWarner LoshLua is a <em>dynamically typed language</em>. 1188e3e3a7aSWarner LoshThis means that 1198e3e3a7aSWarner Loshvariables do not have types; only values do. 1208e3e3a7aSWarner LoshThere are no type definitions in the language. 1218e3e3a7aSWarner LoshAll values carry their own type. 1228e3e3a7aSWarner Losh 1238e3e3a7aSWarner Losh 1248e3e3a7aSWarner Losh<p> 1258e3e3a7aSWarner LoshAll values in Lua are <em>first-class values</em>. 1268e3e3a7aSWarner LoshThis means that all values can be stored in variables, 1278e3e3a7aSWarner Loshpassed as arguments to other functions, and returned as results. 1288e3e3a7aSWarner Losh 1298e3e3a7aSWarner Losh 1308e3e3a7aSWarner Losh<p> 1318e3e3a7aSWarner LoshThere are eight basic types in Lua: 1328e3e3a7aSWarner Losh<em>nil</em>, <em>boolean</em>, <em>number</em>, 1338e3e3a7aSWarner Losh<em>string</em>, <em>function</em>, <em>userdata</em>, 1348e3e3a7aSWarner Losh<em>thread</em>, and <em>table</em>. 1358e3e3a7aSWarner LoshThe type <em>nil</em> has one single value, <b>nil</b>, 1368e3e3a7aSWarner Loshwhose main property is to be different from any other value; 1378e3e3a7aSWarner Loshit usually represents the absence of a useful value. 1388e3e3a7aSWarner LoshThe type <em>boolean</em> has two values, <b>false</b> and <b>true</b>. 1398e3e3a7aSWarner LoshBoth <b>nil</b> and <b>false</b> make a condition false; 1408e3e3a7aSWarner Loshany other value makes it true. 1418e3e3a7aSWarner LoshThe type <em>number</em> represents both 1428e3e3a7aSWarner Loshinteger numbers and real (floating-point) numbers. 1438e3e3a7aSWarner LoshThe type <em>string</em> represents immutable sequences of bytes. 1448e3e3a7aSWarner Losh 1458e3e3a7aSWarner LoshLua is 8-bit clean: 1468e3e3a7aSWarner Loshstrings can contain any 8-bit value, 1478e3e3a7aSWarner Loshincluding embedded zeros ('<code>\0</code>'). 1488e3e3a7aSWarner LoshLua is also encoding-agnostic; 1498e3e3a7aSWarner Loshit makes no assumptions about the contents of a string. 1508e3e3a7aSWarner Losh 1518e3e3a7aSWarner Losh 1528e3e3a7aSWarner Losh<p> 1538e3e3a7aSWarner LoshThe type <em>number</em> uses two internal representations, 1548e3e3a7aSWarner Loshor two subtypes, 1558e3e3a7aSWarner Loshone called <em>integer</em> and the other called <em>float</em>. 1568e3e3a7aSWarner LoshLua has explicit rules about when each representation is used, 1578e3e3a7aSWarner Loshbut it also converts between them automatically as needed (see <a href="#3.4.3">§3.4.3</a>). 1588e3e3a7aSWarner LoshTherefore, 1598e3e3a7aSWarner Loshthe programmer may choose to mostly ignore the difference 1608e3e3a7aSWarner Loshbetween integers and floats 1618e3e3a7aSWarner Loshor to assume complete control over the representation of each number. 1628e3e3a7aSWarner LoshStandard Lua uses 64-bit integers and double-precision (64-bit) floats, 1638e3e3a7aSWarner Loshbut you can also compile Lua so that it 1648e3e3a7aSWarner Loshuses 32-bit integers and/or single-precision (32-bit) floats. 1658e3e3a7aSWarner LoshThe option with 32 bits for both integers and floats 1668e3e3a7aSWarner Loshis particularly attractive 1678e3e3a7aSWarner Loshfor small machines and embedded systems. 1688e3e3a7aSWarner Losh(See macro <code>LUA_32BITS</code> in file <code>luaconf.h</code>.) 1698e3e3a7aSWarner Losh 1708e3e3a7aSWarner Losh 1718e3e3a7aSWarner Losh<p> 1728e3e3a7aSWarner LoshLua can call (and manipulate) functions written in Lua and 1738e3e3a7aSWarner Loshfunctions written in C (see <a href="#3.4.10">§3.4.10</a>). 1748e3e3a7aSWarner LoshBoth are represented by the type <em>function</em>. 1758e3e3a7aSWarner Losh 1768e3e3a7aSWarner Losh 1778e3e3a7aSWarner Losh<p> 1788e3e3a7aSWarner LoshThe type <em>userdata</em> is provided to allow arbitrary C data to 1798e3e3a7aSWarner Loshbe stored in Lua variables. 1808e3e3a7aSWarner LoshA userdata value represents a block of raw memory. 1818e3e3a7aSWarner LoshThere are two kinds of userdata: 1828e3e3a7aSWarner Losh<em>full userdata</em>, 1838e3e3a7aSWarner Loshwhich is an object with a block of memory managed by Lua, 1848e3e3a7aSWarner Loshand <em>light userdata</em>, 1858e3e3a7aSWarner Loshwhich is simply a C pointer value. 1868e3e3a7aSWarner LoshUserdata has no predefined operations in Lua, 1878e3e3a7aSWarner Loshexcept assignment and identity test. 1888e3e3a7aSWarner LoshBy using <em>metatables</em>, 1898e3e3a7aSWarner Loshthe programmer can define operations for full userdata values 1908e3e3a7aSWarner Losh(see <a href="#2.4">§2.4</a>). 1918e3e3a7aSWarner LoshUserdata values cannot be created or modified in Lua, 1928e3e3a7aSWarner Loshonly through the C API. 1938e3e3a7aSWarner LoshThis guarantees the integrity of data owned by the host program. 1948e3e3a7aSWarner Losh 1958e3e3a7aSWarner Losh 1968e3e3a7aSWarner Losh<p> 1978e3e3a7aSWarner LoshThe type <em>thread</em> represents independent threads of execution 1988e3e3a7aSWarner Loshand it is used to implement coroutines (see <a href="#2.6">§2.6</a>). 1998e3e3a7aSWarner LoshLua threads are not related to operating-system threads. 2008e3e3a7aSWarner LoshLua supports coroutines on all systems, 2018e3e3a7aSWarner Losheven those that do not support threads natively. 2028e3e3a7aSWarner Losh 2038e3e3a7aSWarner Losh 2048e3e3a7aSWarner Losh<p> 2058e3e3a7aSWarner LoshThe type <em>table</em> implements associative arrays, 206*e112e9d2SKyle Evansthat is, arrays that can have as indices not only numbers, 207*e112e9d2SKyle Evansbut any Lua value except <b>nil</b> and NaN. 2088e3e3a7aSWarner Losh(<em>Not a Number</em> is a special value used to represent 2098e3e3a7aSWarner Loshundefined or unrepresentable numerical results, such as <code>0/0</code>.) 2108e3e3a7aSWarner LoshTables can be <em>heterogeneous</em>; 2118e3e3a7aSWarner Loshthat is, they can contain values of all types (except <b>nil</b>). 2128e3e3a7aSWarner LoshAny key with value <b>nil</b> is not considered part of the table. 2138e3e3a7aSWarner LoshConversely, any key that is not part of a table has 2148e3e3a7aSWarner Loshan associated value <b>nil</b>. 2158e3e3a7aSWarner Losh 2168e3e3a7aSWarner Losh 2178e3e3a7aSWarner Losh<p> 2188e3e3a7aSWarner LoshTables are the sole data-structuring mechanism in Lua; 2198e3e3a7aSWarner Loshthey can be used to represent ordinary arrays, lists, 2208e3e3a7aSWarner Loshsymbol tables, sets, records, graphs, trees, etc. 2218e3e3a7aSWarner LoshTo represent records, Lua uses the field name as an index. 2228e3e3a7aSWarner LoshThe language supports this representation by 2238e3e3a7aSWarner Loshproviding <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. 2248e3e3a7aSWarner LoshThere are several convenient ways to create tables in Lua 2258e3e3a7aSWarner Losh(see <a href="#3.4.9">§3.4.9</a>). 2268e3e3a7aSWarner Losh 2278e3e3a7aSWarner Losh 2288e3e3a7aSWarner Losh<p> 2298e3e3a7aSWarner LoshLike indices, 2308e3e3a7aSWarner Loshthe values of table fields can be of any type. 2318e3e3a7aSWarner LoshIn particular, 2328e3e3a7aSWarner Loshbecause functions are first-class values, 2338e3e3a7aSWarner Loshtable fields can contain functions. 2348e3e3a7aSWarner LoshThus tables can also carry <em>methods</em> (see <a href="#3.4.11">§3.4.11</a>). 2358e3e3a7aSWarner Losh 2368e3e3a7aSWarner Losh 2378e3e3a7aSWarner Losh<p> 2388e3e3a7aSWarner LoshThe indexing of tables follows 2398e3e3a7aSWarner Loshthe definition of raw equality in the language. 2408e3e3a7aSWarner LoshThe expressions <code>a[i]</code> and <code>a[j]</code> 2418e3e3a7aSWarner Loshdenote the same table element 2428e3e3a7aSWarner Loshif and only if <code>i</code> and <code>j</code> are raw equal 2438e3e3a7aSWarner Losh(that is, equal without metamethods). 2448e3e3a7aSWarner LoshIn particular, floats with integral values 2458e3e3a7aSWarner Loshare equal to their respective integers 2468e3e3a7aSWarner Losh(e.g., <code>1.0 == 1</code>). 2478e3e3a7aSWarner LoshTo avoid ambiguities, 2488e3e3a7aSWarner Loshany float with integral value used as a key 2498e3e3a7aSWarner Loshis converted to its respective integer. 2508e3e3a7aSWarner LoshFor instance, if you write <code>a[2.0] = true</code>, 2518e3e3a7aSWarner Loshthe actual key inserted into the table will be the 2528e3e3a7aSWarner Loshinteger <code>2</code>. 2538e3e3a7aSWarner Losh(On the other hand, 2548e3e3a7aSWarner Losh2 and "<code>2</code>" are different Lua values and therefore 2558e3e3a7aSWarner Loshdenote different table entries.) 2568e3e3a7aSWarner Losh 2578e3e3a7aSWarner Losh 2588e3e3a7aSWarner Losh<p> 2598e3e3a7aSWarner LoshTables, functions, threads, and (full) userdata values are <em>objects</em>: 2608e3e3a7aSWarner Loshvariables do not actually <em>contain</em> these values, 2618e3e3a7aSWarner Loshonly <em>references</em> to them. 2628e3e3a7aSWarner LoshAssignment, parameter passing, and function returns 2638e3e3a7aSWarner Loshalways manipulate references to such values; 2648e3e3a7aSWarner Loshthese operations do not imply any kind of copy. 2658e3e3a7aSWarner Losh 2668e3e3a7aSWarner Losh 2678e3e3a7aSWarner Losh<p> 2688e3e3a7aSWarner LoshThe library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type 2698e3e3a7aSWarner Loshof a given value (see <a href="#6.1">§6.1</a>). 2708e3e3a7aSWarner Losh 2718e3e3a7aSWarner Losh 2728e3e3a7aSWarner Losh 2738e3e3a7aSWarner Losh 2748e3e3a7aSWarner Losh 2758e3e3a7aSWarner Losh<h2>2.2 – <a name="2.2">Environments and the Global Environment</a></h2> 2768e3e3a7aSWarner Losh 2778e3e3a7aSWarner Losh<p> 2788e3e3a7aSWarner LoshAs will be discussed in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>, 2798e3e3a7aSWarner Loshany reference to a free name 2808e3e3a7aSWarner Losh(that is, a name not bound to any declaration) <code>var</code> 2818e3e3a7aSWarner Loshis syntactically translated to <code>_ENV.var</code>. 2828e3e3a7aSWarner LoshMoreover, every chunk is compiled in the scope of 2838e3e3a7aSWarner Loshan external local variable named <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>), 2848e3e3a7aSWarner Loshso <code>_ENV</code> itself is never a free name in a chunk. 2858e3e3a7aSWarner Losh 2868e3e3a7aSWarner Losh 2878e3e3a7aSWarner Losh<p> 2888e3e3a7aSWarner LoshDespite the existence of this external <code>_ENV</code> variable and 2898e3e3a7aSWarner Loshthe translation of free names, 2908e3e3a7aSWarner Losh<code>_ENV</code> is a completely regular name. 2918e3e3a7aSWarner LoshIn particular, 2928e3e3a7aSWarner Loshyou can define new variables and parameters with that name. 2938e3e3a7aSWarner LoshEach reference to a free name uses the <code>_ENV</code> that is 2948e3e3a7aSWarner Loshvisible at that point in the program, 2958e3e3a7aSWarner Loshfollowing the usual visibility rules of Lua (see <a href="#3.5">§3.5</a>). 2968e3e3a7aSWarner Losh 2978e3e3a7aSWarner Losh 2988e3e3a7aSWarner Losh<p> 2998e3e3a7aSWarner LoshAny table used as the value of <code>_ENV</code> is called an <em>environment</em>. 3008e3e3a7aSWarner Losh 3018e3e3a7aSWarner Losh 3028e3e3a7aSWarner Losh<p> 3038e3e3a7aSWarner LoshLua keeps a distinguished environment called the <em>global environment</em>. 3048e3e3a7aSWarner LoshThis value is kept at a special index in the C registry (see <a href="#4.5">§4.5</a>). 3058e3e3a7aSWarner LoshIn Lua, the global variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value. 3068e3e3a7aSWarner Losh(<a href="#pdf-_G"><code>_G</code></a> is never used internally.) 3078e3e3a7aSWarner Losh 3088e3e3a7aSWarner Losh 3098e3e3a7aSWarner Losh<p> 3108e3e3a7aSWarner LoshWhen Lua loads a chunk, 3118e3e3a7aSWarner Loshthe default value for its <code>_ENV</code> upvalue 3128e3e3a7aSWarner Loshis the global environment (see <a href="#pdf-load"><code>load</code></a>). 3138e3e3a7aSWarner LoshTherefore, by default, 3148e3e3a7aSWarner Loshfree names in Lua code refer to entries in the global environment 3158e3e3a7aSWarner Losh(and, therefore, they are also called <em>global variables</em>). 3168e3e3a7aSWarner LoshMoreover, all standard libraries are loaded in the global environment 3178e3e3a7aSWarner Loshand some functions there operate on that environment. 3188e3e3a7aSWarner LoshYou can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>) 3198e3e3a7aSWarner Loshto load a chunk with a different environment. 3208e3e3a7aSWarner Losh(In C, you have to load the chunk and then change the value 3218e3e3a7aSWarner Loshof its first upvalue.) 3228e3e3a7aSWarner Losh 3238e3e3a7aSWarner Losh 3248e3e3a7aSWarner Losh 3258e3e3a7aSWarner Losh 3268e3e3a7aSWarner Losh 3278e3e3a7aSWarner Losh<h2>2.3 – <a name="2.3">Error Handling</a></h2> 3288e3e3a7aSWarner Losh 3298e3e3a7aSWarner Losh<p> 3308e3e3a7aSWarner LoshBecause Lua is an embedded extension language, 3318e3e3a7aSWarner Loshall Lua actions start from C code in the host program 3328e3e3a7aSWarner Loshcalling a function from the Lua library. 3338e3e3a7aSWarner Losh(When you use Lua standalone, 3348e3e3a7aSWarner Loshthe <code>lua</code> application is the host program.) 3358e3e3a7aSWarner LoshWhenever an error occurs during 3368e3e3a7aSWarner Loshthe compilation or execution of a Lua chunk, 3378e3e3a7aSWarner Loshcontrol returns to the host, 3388e3e3a7aSWarner Loshwhich can take appropriate measures 3398e3e3a7aSWarner Losh(such as printing an error message). 3408e3e3a7aSWarner Losh 3418e3e3a7aSWarner Losh 3428e3e3a7aSWarner Losh<p> 3438e3e3a7aSWarner LoshLua code can explicitly generate an error by calling the 3448e3e3a7aSWarner Losh<a href="#pdf-error"><code>error</code></a> function. 3458e3e3a7aSWarner LoshIf you need to catch errors in Lua, 3468e3e3a7aSWarner Loshyou can use <a href="#pdf-pcall"><code>pcall</code></a> or <a href="#pdf-xpcall"><code>xpcall</code></a> 3478e3e3a7aSWarner Loshto call a given function in <em>protected mode</em>. 3488e3e3a7aSWarner Losh 3498e3e3a7aSWarner Losh 3508e3e3a7aSWarner Losh<p> 3518e3e3a7aSWarner LoshWhenever there is an error, 3528e3e3a7aSWarner Loshan <em>error object</em> (also called an <em>error message</em>) 3538e3e3a7aSWarner Loshis propagated with information about the error. 3548e3e3a7aSWarner LoshLua itself only generates errors whose error object is a string, 3558e3e3a7aSWarner Loshbut programs may generate errors with 3568e3e3a7aSWarner Loshany value as the error object. 3578e3e3a7aSWarner LoshIt is up to the Lua program or its host to handle such error objects. 3588e3e3a7aSWarner Losh 3598e3e3a7aSWarner Losh 3608e3e3a7aSWarner Losh<p> 3618e3e3a7aSWarner LoshWhen you use <a href="#pdf-xpcall"><code>xpcall</code></a> or <a href="#lua_pcall"><code>lua_pcall</code></a>, 3628e3e3a7aSWarner Loshyou may give a <em>message handler</em> 3638e3e3a7aSWarner Loshto be called in case of errors. 3648e3e3a7aSWarner LoshThis function is called with the original error object 3658e3e3a7aSWarner Loshand returns a new error object. 3668e3e3a7aSWarner LoshIt is called before the error unwinds the stack, 3678e3e3a7aSWarner Loshso that it can gather more information about the error, 3688e3e3a7aSWarner Loshfor instance by inspecting the stack and creating a stack traceback. 3698e3e3a7aSWarner LoshThis message handler is still protected by the protected call; 3708e3e3a7aSWarner Loshso, an error inside the message handler 3718e3e3a7aSWarner Loshwill call the message handler again. 3728e3e3a7aSWarner LoshIf this loop goes on for too long, 3738e3e3a7aSWarner LoshLua breaks it and returns an appropriate message. 3748e3e3a7aSWarner Losh(The message handler is called only for regular runtime errors. 3758e3e3a7aSWarner LoshIt is not called for memory-allocation errors 3768e3e3a7aSWarner Loshnor for errors while running finalizers.) 3778e3e3a7aSWarner Losh 3788e3e3a7aSWarner Losh 3798e3e3a7aSWarner Losh 3808e3e3a7aSWarner Losh 3818e3e3a7aSWarner Losh 3828e3e3a7aSWarner Losh<h2>2.4 – <a name="2.4">Metatables and Metamethods</a></h2> 3838e3e3a7aSWarner Losh 3848e3e3a7aSWarner Losh<p> 3858e3e3a7aSWarner LoshEvery value in Lua can have a <em>metatable</em>. 3868e3e3a7aSWarner LoshThis <em>metatable</em> is an ordinary Lua table 3878e3e3a7aSWarner Loshthat defines the behavior of the original value 3888e3e3a7aSWarner Loshunder certain special operations. 3898e3e3a7aSWarner LoshYou can change several aspects of the behavior 3908e3e3a7aSWarner Loshof operations over a value by setting specific fields in its metatable. 3918e3e3a7aSWarner LoshFor instance, when a non-numeric value is the operand of an addition, 3928e3e3a7aSWarner LoshLua checks for a function in the field "<code>__add</code>" of the value's metatable. 3938e3e3a7aSWarner LoshIf it finds one, 3948e3e3a7aSWarner LoshLua calls this function to perform the addition. 3958e3e3a7aSWarner Losh 3968e3e3a7aSWarner Losh 3978e3e3a7aSWarner Losh<p> 3988e3e3a7aSWarner LoshThe key for each event in a metatable is a string 3998e3e3a7aSWarner Loshwith the event name prefixed by two underscores; 4008e3e3a7aSWarner Loshthe corresponding values are called <em>metamethods</em>. 4018e3e3a7aSWarner LoshIn the previous example, the key is "<code>__add</code>" 4028e3e3a7aSWarner Loshand the metamethod is the function that performs the addition. 403*e112e9d2SKyle EvansUnless stated otherwise, 404*e112e9d2SKyle Evansmetamethods should be function values. 4058e3e3a7aSWarner Losh 4068e3e3a7aSWarner Losh 4078e3e3a7aSWarner Losh<p> 4088e3e3a7aSWarner LoshYou can query the metatable of any value 4098e3e3a7aSWarner Loshusing the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function. 4108e3e3a7aSWarner LoshLua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>). 4118e3e3a7aSWarner LoshSo, to retrieve the metamethod for event <code>ev</code> in object <code>o</code>, 4128e3e3a7aSWarner LoshLua does the equivalent to the following code: 4138e3e3a7aSWarner Losh 4148e3e3a7aSWarner Losh<pre> 4158e3e3a7aSWarner Losh rawget(getmetatable(<em>o</em>) or {}, "__<em>ev</em>") 4168e3e3a7aSWarner Losh</pre> 4178e3e3a7aSWarner Losh 4188e3e3a7aSWarner Losh<p> 4198e3e3a7aSWarner LoshYou can replace the metatable of tables 4208e3e3a7aSWarner Loshusing the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function. 4218e3e3a7aSWarner LoshYou cannot change the metatable of other types from Lua code 4228e3e3a7aSWarner Losh(except by using the debug library (<a href="#6.10">§6.10</a>)); 4238e3e3a7aSWarner Loshyou should use the C API for that. 4248e3e3a7aSWarner Losh 4258e3e3a7aSWarner Losh 4268e3e3a7aSWarner Losh<p> 4278e3e3a7aSWarner LoshTables and full userdata have individual metatables 4288e3e3a7aSWarner Losh(although multiple tables and userdata can share their metatables). 4298e3e3a7aSWarner LoshValues of all other types share one single metatable per type; 4308e3e3a7aSWarner Loshthat is, there is one single metatable for all numbers, 4318e3e3a7aSWarner Loshone for all strings, etc. 4328e3e3a7aSWarner LoshBy default, a value has no metatable, 4338e3e3a7aSWarner Loshbut the string library sets a metatable for the string type (see <a href="#6.4">§6.4</a>). 4348e3e3a7aSWarner Losh 4358e3e3a7aSWarner Losh 4368e3e3a7aSWarner Losh<p> 4378e3e3a7aSWarner LoshA metatable controls how an object behaves in 4388e3e3a7aSWarner Losharithmetic operations, bitwise operations, 4398e3e3a7aSWarner Loshorder comparisons, concatenation, length operation, calls, and indexing. 4408e3e3a7aSWarner LoshA metatable also can define a function to be called 4418e3e3a7aSWarner Loshwhen a userdata or a table is garbage collected (<a href="#2.5">§2.5</a>). 4428e3e3a7aSWarner Losh 4438e3e3a7aSWarner Losh 4448e3e3a7aSWarner Losh<p> 4458e3e3a7aSWarner LoshFor the unary operators (negation, length, and bitwise NOT), 4468e3e3a7aSWarner Loshthe metamethod is computed and called with a dummy second operand, 4478e3e3a7aSWarner Loshequal to the first one. 4488e3e3a7aSWarner LoshThis extra operand is only to simplify Lua's internals 4498e3e3a7aSWarner Losh(by making these operators behave like a binary operation) 4508e3e3a7aSWarner Loshand may be removed in future versions. 4518e3e3a7aSWarner Losh(For most uses this extra operand is irrelevant.) 4528e3e3a7aSWarner Losh 4538e3e3a7aSWarner Losh 4548e3e3a7aSWarner Losh<p> 4558e3e3a7aSWarner LoshA detailed list of events controlled by metatables is given next. 4568e3e3a7aSWarner LoshEach operation is identified by its corresponding key. 4578e3e3a7aSWarner Losh 4588e3e3a7aSWarner Losh 4598e3e3a7aSWarner Losh 4608e3e3a7aSWarner Losh<ul> 4618e3e3a7aSWarner Losh 4628e3e3a7aSWarner Losh<li><b><code>__add</code>: </b> 4638e3e3a7aSWarner Loshthe addition (<code>+</code>) operation. 4648e3e3a7aSWarner LoshIf any operand for an addition is not a number 4658e3e3a7aSWarner Losh(nor a string coercible to a number), 4668e3e3a7aSWarner LoshLua will try to call a metamethod. 4678e3e3a7aSWarner LoshFirst, Lua will check the first operand (even if it is valid). 4688e3e3a7aSWarner LoshIf that operand does not define a metamethod for <code>__add</code>, 4698e3e3a7aSWarner Loshthen Lua will check the second operand. 4708e3e3a7aSWarner LoshIf Lua can find a metamethod, 4718e3e3a7aSWarner Loshit calls the metamethod with the two operands as arguments, 4728e3e3a7aSWarner Loshand the result of the call 4738e3e3a7aSWarner Losh(adjusted to one value) 4748e3e3a7aSWarner Loshis the result of the operation. 4758e3e3a7aSWarner LoshOtherwise, 4768e3e3a7aSWarner Loshit raises an error. 4778e3e3a7aSWarner Losh</li> 4788e3e3a7aSWarner Losh 4798e3e3a7aSWarner Losh<li><b><code>__sub</code>: </b> 4808e3e3a7aSWarner Loshthe subtraction (<code>-</code>) operation. 4818e3e3a7aSWarner LoshBehavior similar to the addition operation. 4828e3e3a7aSWarner Losh</li> 4838e3e3a7aSWarner Losh 4848e3e3a7aSWarner Losh<li><b><code>__mul</code>: </b> 4858e3e3a7aSWarner Loshthe multiplication (<code>*</code>) operation. 4868e3e3a7aSWarner LoshBehavior similar to the addition operation. 4878e3e3a7aSWarner Losh</li> 4888e3e3a7aSWarner Losh 4898e3e3a7aSWarner Losh<li><b><code>__div</code>: </b> 4908e3e3a7aSWarner Loshthe division (<code>/</code>) operation. 4918e3e3a7aSWarner LoshBehavior similar to the addition operation. 4928e3e3a7aSWarner Losh</li> 4938e3e3a7aSWarner Losh 4948e3e3a7aSWarner Losh<li><b><code>__mod</code>: </b> 4958e3e3a7aSWarner Loshthe modulo (<code>%</code>) operation. 4968e3e3a7aSWarner LoshBehavior similar to the addition operation. 4978e3e3a7aSWarner Losh</li> 4988e3e3a7aSWarner Losh 4998e3e3a7aSWarner Losh<li><b><code>__pow</code>: </b> 5008e3e3a7aSWarner Loshthe exponentiation (<code>^</code>) operation. 5018e3e3a7aSWarner LoshBehavior similar to the addition operation. 5028e3e3a7aSWarner Losh</li> 5038e3e3a7aSWarner Losh 5048e3e3a7aSWarner Losh<li><b><code>__unm</code>: </b> 5058e3e3a7aSWarner Loshthe negation (unary <code>-</code>) operation. 5068e3e3a7aSWarner LoshBehavior similar to the addition operation. 5078e3e3a7aSWarner Losh</li> 5088e3e3a7aSWarner Losh 5098e3e3a7aSWarner Losh<li><b><code>__idiv</code>: </b> 5108e3e3a7aSWarner Loshthe floor division (<code>//</code>) operation. 5118e3e3a7aSWarner LoshBehavior similar to the addition operation. 5128e3e3a7aSWarner Losh</li> 5138e3e3a7aSWarner Losh 5148e3e3a7aSWarner Losh<li><b><code>__band</code>: </b> 5158e3e3a7aSWarner Loshthe bitwise AND (<code>&</code>) operation. 5168e3e3a7aSWarner LoshBehavior similar to the addition operation, 5178e3e3a7aSWarner Loshexcept that Lua will try a metamethod 5188e3e3a7aSWarner Loshif any operand is neither an integer 5198e3e3a7aSWarner Loshnor a value coercible to an integer (see <a href="#3.4.3">§3.4.3</a>). 5208e3e3a7aSWarner Losh</li> 5218e3e3a7aSWarner Losh 5228e3e3a7aSWarner Losh<li><b><code>__bor</code>: </b> 5238e3e3a7aSWarner Loshthe bitwise OR (<code>|</code>) operation. 5248e3e3a7aSWarner LoshBehavior similar to the bitwise AND operation. 5258e3e3a7aSWarner Losh</li> 5268e3e3a7aSWarner Losh 5278e3e3a7aSWarner Losh<li><b><code>__bxor</code>: </b> 5288e3e3a7aSWarner Loshthe bitwise exclusive OR (binary <code>~</code>) operation. 5298e3e3a7aSWarner LoshBehavior similar to the bitwise AND operation. 5308e3e3a7aSWarner Losh</li> 5318e3e3a7aSWarner Losh 5328e3e3a7aSWarner Losh<li><b><code>__bnot</code>: </b> 5338e3e3a7aSWarner Loshthe bitwise NOT (unary <code>~</code>) operation. 5348e3e3a7aSWarner LoshBehavior similar to the bitwise AND operation. 5358e3e3a7aSWarner Losh</li> 5368e3e3a7aSWarner Losh 5378e3e3a7aSWarner Losh<li><b><code>__shl</code>: </b> 5388e3e3a7aSWarner Loshthe bitwise left shift (<code><<</code>) operation. 5398e3e3a7aSWarner LoshBehavior similar to the bitwise AND operation. 5408e3e3a7aSWarner Losh</li> 5418e3e3a7aSWarner Losh 5428e3e3a7aSWarner Losh<li><b><code>__shr</code>: </b> 5438e3e3a7aSWarner Loshthe bitwise right shift (<code>>></code>) operation. 5448e3e3a7aSWarner LoshBehavior similar to the bitwise AND operation. 5458e3e3a7aSWarner Losh</li> 5468e3e3a7aSWarner Losh 5478e3e3a7aSWarner Losh<li><b><code>__concat</code>: </b> 5488e3e3a7aSWarner Loshthe concatenation (<code>..</code>) operation. 5498e3e3a7aSWarner LoshBehavior similar to the addition operation, 5508e3e3a7aSWarner Loshexcept that Lua will try a metamethod 5518e3e3a7aSWarner Loshif any operand is neither a string nor a number 5528e3e3a7aSWarner Losh(which is always coercible to a string). 5538e3e3a7aSWarner Losh</li> 5548e3e3a7aSWarner Losh 5558e3e3a7aSWarner Losh<li><b><code>__len</code>: </b> 5568e3e3a7aSWarner Loshthe length (<code>#</code>) operation. 5578e3e3a7aSWarner LoshIf the object is not a string, 5588e3e3a7aSWarner LoshLua will try its metamethod. 5598e3e3a7aSWarner LoshIf there is a metamethod, 5608e3e3a7aSWarner LoshLua calls it with the object as argument, 5618e3e3a7aSWarner Loshand the result of the call 5628e3e3a7aSWarner Losh(always adjusted to one value) 5638e3e3a7aSWarner Loshis the result of the operation. 5648e3e3a7aSWarner LoshIf there is no metamethod but the object is a table, 5658e3e3a7aSWarner Loshthen Lua uses the table length operation (see <a href="#3.4.7">§3.4.7</a>). 5668e3e3a7aSWarner LoshOtherwise, Lua raises an error. 5678e3e3a7aSWarner Losh</li> 5688e3e3a7aSWarner Losh 5698e3e3a7aSWarner Losh<li><b><code>__eq</code>: </b> 5708e3e3a7aSWarner Loshthe equal (<code>==</code>) operation. 5718e3e3a7aSWarner LoshBehavior similar to the addition operation, 5728e3e3a7aSWarner Loshexcept that Lua will try a metamethod only when the values 5738e3e3a7aSWarner Loshbeing compared are either both tables or both full userdata 5748e3e3a7aSWarner Loshand they are not primitively equal. 5758e3e3a7aSWarner LoshThe result of the call is always converted to a boolean. 5768e3e3a7aSWarner Losh</li> 5778e3e3a7aSWarner Losh 5788e3e3a7aSWarner Losh<li><b><code>__lt</code>: </b> 5798e3e3a7aSWarner Loshthe less than (<code><</code>) operation. 5808e3e3a7aSWarner LoshBehavior similar to the addition operation, 5818e3e3a7aSWarner Loshexcept that Lua will try a metamethod only when the values 5828e3e3a7aSWarner Loshbeing compared are neither both numbers nor both strings. 5838e3e3a7aSWarner LoshThe result of the call is always converted to a boolean. 5848e3e3a7aSWarner Losh</li> 5858e3e3a7aSWarner Losh 5868e3e3a7aSWarner Losh<li><b><code>__le</code>: </b> 5878e3e3a7aSWarner Loshthe less equal (<code><=</code>) operation. 5888e3e3a7aSWarner LoshUnlike other operations, 5898e3e3a7aSWarner Loshthe less-equal operation can use two different events. 5908e3e3a7aSWarner LoshFirst, Lua looks for the <code>__le</code> metamethod in both operands, 5918e3e3a7aSWarner Loshlike in the less than operation. 5928e3e3a7aSWarner LoshIf it cannot find such a metamethod, 5938e3e3a7aSWarner Loshthen it will try the <code>__lt</code> metamethod, 5948e3e3a7aSWarner Loshassuming that <code>a <= b</code> is equivalent to <code>not (b < a)</code>. 5958e3e3a7aSWarner LoshAs with the other comparison operators, 5968e3e3a7aSWarner Loshthe result is always a boolean. 5978e3e3a7aSWarner Losh(This use of the <code>__lt</code> event can be removed in future versions; 5988e3e3a7aSWarner Loshit is also slower than a real <code>__le</code> metamethod.) 5998e3e3a7aSWarner Losh</li> 6008e3e3a7aSWarner Losh 6018e3e3a7aSWarner Losh<li><b><code>__index</code>: </b> 602*e112e9d2SKyle EvansThe indexing access operation <code>table[key]</code>. 6038e3e3a7aSWarner LoshThis event happens when <code>table</code> is not a table or 6048e3e3a7aSWarner Loshwhen <code>key</code> is not present in <code>table</code>. 6058e3e3a7aSWarner LoshThe metamethod is looked up in <code>table</code>. 6068e3e3a7aSWarner Losh 6078e3e3a7aSWarner Losh 6088e3e3a7aSWarner Losh<p> 6098e3e3a7aSWarner LoshDespite the name, 6108e3e3a7aSWarner Loshthe metamethod for this event can be either a function or a table. 6118e3e3a7aSWarner LoshIf it is a function, 6128e3e3a7aSWarner Loshit is called with <code>table</code> and <code>key</code> as arguments, 6138e3e3a7aSWarner Loshand the result of the call 6148e3e3a7aSWarner Losh(adjusted to one value) 6158e3e3a7aSWarner Loshis the result of the operation. 6168e3e3a7aSWarner LoshIf it is a table, 6178e3e3a7aSWarner Loshthe final result is the result of indexing this table with <code>key</code>. 6188e3e3a7aSWarner Losh(This indexing is regular, not raw, 6198e3e3a7aSWarner Loshand therefore can trigger another metamethod.) 6208e3e3a7aSWarner Losh</li> 6218e3e3a7aSWarner Losh 6228e3e3a7aSWarner Losh<li><b><code>__newindex</code>: </b> 6238e3e3a7aSWarner LoshThe indexing assignment <code>table[key] = value</code>. 6248e3e3a7aSWarner LoshLike the index event, 6258e3e3a7aSWarner Loshthis event happens when <code>table</code> is not a table or 6268e3e3a7aSWarner Loshwhen <code>key</code> is not present in <code>table</code>. 6278e3e3a7aSWarner LoshThe metamethod is looked up in <code>table</code>. 6288e3e3a7aSWarner Losh 6298e3e3a7aSWarner Losh 6308e3e3a7aSWarner Losh<p> 6318e3e3a7aSWarner LoshLike with indexing, 6328e3e3a7aSWarner Loshthe metamethod for this event can be either a function or a table. 6338e3e3a7aSWarner LoshIf it is a function, 6348e3e3a7aSWarner Loshit is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments. 6358e3e3a7aSWarner LoshIf it is a table, 6368e3e3a7aSWarner LoshLua does an indexing assignment to this table with the same key and value. 6378e3e3a7aSWarner Losh(This assignment is regular, not raw, 6388e3e3a7aSWarner Loshand therefore can trigger another metamethod.) 6398e3e3a7aSWarner Losh 6408e3e3a7aSWarner Losh 6418e3e3a7aSWarner Losh<p> 6428e3e3a7aSWarner LoshWhenever there is a <code>__newindex</code> metamethod, 6438e3e3a7aSWarner LoshLua does not perform the primitive assignment. 6448e3e3a7aSWarner Losh(If necessary, 6458e3e3a7aSWarner Loshthe metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a> 6468e3e3a7aSWarner Loshto do the assignment.) 6478e3e3a7aSWarner Losh</li> 6488e3e3a7aSWarner Losh 6498e3e3a7aSWarner Losh<li><b><code>__call</code>: </b> 6508e3e3a7aSWarner LoshThe call operation <code>func(args)</code>. 6518e3e3a7aSWarner LoshThis event happens when Lua tries to call a non-function value 6528e3e3a7aSWarner Losh(that is, <code>func</code> is not a function). 6538e3e3a7aSWarner LoshThe metamethod is looked up in <code>func</code>. 6548e3e3a7aSWarner LoshIf present, 6558e3e3a7aSWarner Loshthe metamethod is called with <code>func</code> as its first argument, 6568e3e3a7aSWarner Loshfollowed by the arguments of the original call (<code>args</code>). 6578e3e3a7aSWarner LoshAll results of the call 6588e3e3a7aSWarner Loshare the result of the operation. 6598e3e3a7aSWarner Losh(This is the only metamethod that allows multiple results.) 6608e3e3a7aSWarner Losh</li> 6618e3e3a7aSWarner Losh 6628e3e3a7aSWarner Losh</ul> 6638e3e3a7aSWarner Losh 6648e3e3a7aSWarner Losh<p> 6658e3e3a7aSWarner LoshIt is a good practice to add all needed metamethods to a table 6668e3e3a7aSWarner Loshbefore setting it as a metatable of some object. 6678e3e3a7aSWarner LoshIn particular, the <code>__gc</code> metamethod works only when this order 6688e3e3a7aSWarner Loshis followed (see <a href="#2.5.1">§2.5.1</a>). 6698e3e3a7aSWarner Losh 6708e3e3a7aSWarner Losh 6718e3e3a7aSWarner Losh<p> 6728e3e3a7aSWarner LoshBecause metatables are regular tables, 6738e3e3a7aSWarner Loshthey can contain arbitrary fields, 6748e3e3a7aSWarner Loshnot only the event names defined above. 6758e3e3a7aSWarner LoshSome functions in the standard library 6768e3e3a7aSWarner Losh(e.g., <a href="#pdf-tostring"><code>tostring</code></a>) 6778e3e3a7aSWarner Loshuse other fields in metatables for their own purposes. 6788e3e3a7aSWarner Losh 6798e3e3a7aSWarner Losh 6808e3e3a7aSWarner Losh 6818e3e3a7aSWarner Losh 6828e3e3a7aSWarner Losh 6838e3e3a7aSWarner Losh<h2>2.5 – <a name="2.5">Garbage Collection</a></h2> 6848e3e3a7aSWarner Losh 6858e3e3a7aSWarner Losh<p> 6868e3e3a7aSWarner LoshLua performs automatic memory management. 6878e3e3a7aSWarner LoshThis means that 6888e3e3a7aSWarner Loshyou do not have to worry about allocating memory for new objects 6898e3e3a7aSWarner Loshor freeing it when the objects are no longer needed. 6908e3e3a7aSWarner LoshLua manages memory automatically by running 6918e3e3a7aSWarner Losha <em>garbage collector</em> to collect all <em>dead objects</em> 6928e3e3a7aSWarner Losh(that is, objects that are no longer accessible from Lua). 6938e3e3a7aSWarner LoshAll memory used by Lua is subject to automatic management: 6948e3e3a7aSWarner Loshstrings, tables, userdata, functions, threads, internal structures, etc. 6958e3e3a7aSWarner Losh 6968e3e3a7aSWarner Losh 6978e3e3a7aSWarner Losh<p> 6988e3e3a7aSWarner LoshLua implements an incremental mark-and-sweep collector. 6998e3e3a7aSWarner LoshIt uses two numbers to control its garbage-collection cycles: 7008e3e3a7aSWarner Loshthe <em>garbage-collector pause</em> and 7018e3e3a7aSWarner Loshthe <em>garbage-collector step multiplier</em>. 7028e3e3a7aSWarner LoshBoth use percentage points as units 7038e3e3a7aSWarner Losh(e.g., a value of 100 means an internal value of 1). 7048e3e3a7aSWarner Losh 7058e3e3a7aSWarner Losh 7068e3e3a7aSWarner Losh<p> 7078e3e3a7aSWarner LoshThe garbage-collector pause 7088e3e3a7aSWarner Loshcontrols how long the collector waits before starting a new cycle. 7098e3e3a7aSWarner LoshLarger values make the collector less aggressive. 7108e3e3a7aSWarner LoshValues smaller than 100 mean the collector will not wait to 7118e3e3a7aSWarner Loshstart a new cycle. 7128e3e3a7aSWarner LoshA value of 200 means that the collector waits for the total memory in use 7138e3e3a7aSWarner Loshto double before starting a new cycle. 7148e3e3a7aSWarner Losh 7158e3e3a7aSWarner Losh 7168e3e3a7aSWarner Losh<p> 7178e3e3a7aSWarner LoshThe garbage-collector step multiplier 7188e3e3a7aSWarner Loshcontrols the relative speed of the collector relative to 7198e3e3a7aSWarner Loshmemory allocation. 7208e3e3a7aSWarner LoshLarger values make the collector more aggressive but also increase 7218e3e3a7aSWarner Loshthe size of each incremental step. 7228e3e3a7aSWarner LoshYou should not use values smaller than 100, 7238e3e3a7aSWarner Loshbecause they make the collector too slow and 7248e3e3a7aSWarner Loshcan result in the collector never finishing a cycle. 7258e3e3a7aSWarner LoshThe default is 200, 7268e3e3a7aSWarner Loshwhich means that the collector runs at "twice" 7278e3e3a7aSWarner Loshthe speed of memory allocation. 7288e3e3a7aSWarner Losh 7298e3e3a7aSWarner Losh 7308e3e3a7aSWarner Losh<p> 7318e3e3a7aSWarner LoshIf you set the step multiplier to a very large number 7328e3e3a7aSWarner Losh(larger than 10% of the maximum number of 7338e3e3a7aSWarner Loshbytes that the program may use), 7348e3e3a7aSWarner Loshthe collector behaves like a stop-the-world collector. 7358e3e3a7aSWarner LoshIf you then set the pause to 200, 7368e3e3a7aSWarner Loshthe collector behaves as in old Lua versions, 7378e3e3a7aSWarner Loshdoing a complete collection every time Lua doubles its 7388e3e3a7aSWarner Loshmemory usage. 7398e3e3a7aSWarner Losh 7408e3e3a7aSWarner Losh 7418e3e3a7aSWarner Losh<p> 7428e3e3a7aSWarner LoshYou can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C 7438e3e3a7aSWarner Loshor <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. 7448e3e3a7aSWarner LoshYou can also use these functions to control 7458e3e3a7aSWarner Loshthe collector directly (e.g., stop and restart it). 7468e3e3a7aSWarner Losh 7478e3e3a7aSWarner Losh 7488e3e3a7aSWarner Losh 7498e3e3a7aSWarner Losh<h3>2.5.1 – <a name="2.5.1">Garbage-Collection Metamethods</a></h3> 7508e3e3a7aSWarner Losh 7518e3e3a7aSWarner Losh<p> 7528e3e3a7aSWarner LoshYou can set garbage-collector metamethods for tables 7538e3e3a7aSWarner Loshand, using the C API, 7548e3e3a7aSWarner Loshfor full userdata (see <a href="#2.4">§2.4</a>). 7558e3e3a7aSWarner LoshThese metamethods are also called <em>finalizers</em>. 7568e3e3a7aSWarner LoshFinalizers allow you to coordinate Lua's garbage collection 7578e3e3a7aSWarner Loshwith external resource management 7588e3e3a7aSWarner Losh(such as closing files, network or database connections, 7598e3e3a7aSWarner Loshor freeing your own memory). 7608e3e3a7aSWarner Losh 7618e3e3a7aSWarner Losh 7628e3e3a7aSWarner Losh<p> 7638e3e3a7aSWarner LoshFor an object (table or userdata) to be finalized when collected, 7648e3e3a7aSWarner Loshyou must <em>mark</em> it for finalization. 7658e3e3a7aSWarner Losh 7668e3e3a7aSWarner LoshYou mark an object for finalization when you set its metatable 7678e3e3a7aSWarner Loshand the metatable has a field indexed by the string "<code>__gc</code>". 7688e3e3a7aSWarner LoshNote that if you set a metatable without a <code>__gc</code> field 7698e3e3a7aSWarner Loshand later create that field in the metatable, 7708e3e3a7aSWarner Loshthe object will not be marked for finalization. 7718e3e3a7aSWarner Losh 7728e3e3a7aSWarner Losh 7738e3e3a7aSWarner Losh<p> 7748e3e3a7aSWarner LoshWhen a marked object becomes garbage, 7758e3e3a7aSWarner Loshit is not collected immediately by the garbage collector. 7768e3e3a7aSWarner LoshInstead, Lua puts it in a list. 7778e3e3a7aSWarner LoshAfter the collection, 7788e3e3a7aSWarner LoshLua goes through that list. 7798e3e3a7aSWarner LoshFor each object in the list, 7808e3e3a7aSWarner Loshit checks the object's <code>__gc</code> metamethod: 7818e3e3a7aSWarner LoshIf it is a function, 7828e3e3a7aSWarner LoshLua calls it with the object as its single argument; 7838e3e3a7aSWarner Loshif the metamethod is not a function, 7848e3e3a7aSWarner LoshLua simply ignores it. 7858e3e3a7aSWarner Losh 7868e3e3a7aSWarner Losh 7878e3e3a7aSWarner Losh<p> 7888e3e3a7aSWarner LoshAt the end of each garbage-collection cycle, 7898e3e3a7aSWarner Loshthe finalizers for objects are called in 7908e3e3a7aSWarner Loshthe reverse order that the objects were marked for finalization, 7918e3e3a7aSWarner Loshamong those collected in that cycle; 7928e3e3a7aSWarner Loshthat is, the first finalizer to be called is the one associated 7938e3e3a7aSWarner Loshwith the object marked last in the program. 7948e3e3a7aSWarner LoshThe execution of each finalizer may occur at any point during 7958e3e3a7aSWarner Loshthe execution of the regular code. 7968e3e3a7aSWarner Losh 7978e3e3a7aSWarner Losh 7988e3e3a7aSWarner Losh<p> 7998e3e3a7aSWarner LoshBecause the object being collected must still be used by the finalizer, 8008e3e3a7aSWarner Loshthat object (and other objects accessible only through it) 8018e3e3a7aSWarner Loshmust be <em>resurrected</em> by Lua. 8028e3e3a7aSWarner LoshUsually, this resurrection is transient, 8038e3e3a7aSWarner Loshand the object memory is freed in the next garbage-collection cycle. 8048e3e3a7aSWarner LoshHowever, if the finalizer stores the object in some global place 8058e3e3a7aSWarner Losh(e.g., a global variable), 8068e3e3a7aSWarner Loshthen the resurrection is permanent. 8078e3e3a7aSWarner LoshMoreover, if the finalizer marks a finalizing object for finalization again, 8088e3e3a7aSWarner Loshits finalizer will be called again in the next cycle where the 8098e3e3a7aSWarner Loshobject is unreachable. 8108e3e3a7aSWarner LoshIn any case, 8118e3e3a7aSWarner Loshthe object memory is freed only in a GC cycle where 8128e3e3a7aSWarner Loshthe object is unreachable and not marked for finalization. 8138e3e3a7aSWarner Losh 8148e3e3a7aSWarner Losh 8158e3e3a7aSWarner Losh<p> 8168e3e3a7aSWarner LoshWhen you close a state (see <a href="#lua_close"><code>lua_close</code></a>), 8178e3e3a7aSWarner LoshLua calls the finalizers of all objects marked for finalization, 8188e3e3a7aSWarner Loshfollowing the reverse order that they were marked. 8198e3e3a7aSWarner LoshIf any finalizer marks objects for collection during that phase, 8208e3e3a7aSWarner Loshthese marks have no effect. 8218e3e3a7aSWarner Losh 8228e3e3a7aSWarner Losh 8238e3e3a7aSWarner Losh 8248e3e3a7aSWarner Losh 8258e3e3a7aSWarner Losh 8268e3e3a7aSWarner Losh<h3>2.5.2 – <a name="2.5.2">Weak Tables</a></h3> 8278e3e3a7aSWarner Losh 8288e3e3a7aSWarner Losh<p> 8298e3e3a7aSWarner LoshA <em>weak table</em> is a table whose elements are 8308e3e3a7aSWarner Losh<em>weak references</em>. 8318e3e3a7aSWarner LoshA weak reference is ignored by the garbage collector. 8328e3e3a7aSWarner LoshIn other words, 8338e3e3a7aSWarner Loshif the only references to an object are weak references, 8348e3e3a7aSWarner Loshthen the garbage collector will collect that object. 8358e3e3a7aSWarner Losh 8368e3e3a7aSWarner Losh 8378e3e3a7aSWarner Losh<p> 8388e3e3a7aSWarner LoshA weak table can have weak keys, weak values, or both. 8398e3e3a7aSWarner LoshA table with weak values allows the collection of its values, 8408e3e3a7aSWarner Loshbut prevents the collection of its keys. 8418e3e3a7aSWarner LoshA table with both weak keys and weak values allows the collection of 8428e3e3a7aSWarner Loshboth keys and values. 8438e3e3a7aSWarner LoshIn any case, if either the key or the value is collected, 8448e3e3a7aSWarner Loshthe whole pair is removed from the table. 8458e3e3a7aSWarner LoshThe weakness of a table is controlled by the 8468e3e3a7aSWarner Losh<code>__mode</code> field of its metatable. 8478e3e3a7aSWarner LoshIf the <code>__mode</code> field is a string containing the character '<code>k</code>', 8488e3e3a7aSWarner Loshthe keys in the table are weak. 8498e3e3a7aSWarner LoshIf <code>__mode</code> contains '<code>v</code>', 8508e3e3a7aSWarner Loshthe values in the table are weak. 8518e3e3a7aSWarner Losh 8528e3e3a7aSWarner Losh 8538e3e3a7aSWarner Losh<p> 8548e3e3a7aSWarner LoshA table with weak keys and strong values 8558e3e3a7aSWarner Loshis also called an <em>ephemeron table</em>. 8568e3e3a7aSWarner LoshIn an ephemeron table, 8578e3e3a7aSWarner Losha value is considered reachable only if its key is reachable. 8588e3e3a7aSWarner LoshIn particular, 8598e3e3a7aSWarner Loshif the only reference to a key comes through its value, 8608e3e3a7aSWarner Loshthe pair is removed. 8618e3e3a7aSWarner Losh 8628e3e3a7aSWarner Losh 8638e3e3a7aSWarner Losh<p> 8648e3e3a7aSWarner LoshAny change in the weakness of a table may take effect only 8658e3e3a7aSWarner Loshat the next collect cycle. 8668e3e3a7aSWarner LoshIn particular, if you change the weakness to a stronger mode, 8678e3e3a7aSWarner LoshLua may still collect some items from that table 8688e3e3a7aSWarner Loshbefore the change takes effect. 8698e3e3a7aSWarner Losh 8708e3e3a7aSWarner Losh 8718e3e3a7aSWarner Losh<p> 8728e3e3a7aSWarner LoshOnly objects that have an explicit construction 8738e3e3a7aSWarner Loshare removed from weak tables. 8748e3e3a7aSWarner LoshValues, such as numbers and light C functions, 8758e3e3a7aSWarner Loshare not subject to garbage collection, 8768e3e3a7aSWarner Loshand therefore are not removed from weak tables 8778e3e3a7aSWarner Losh(unless their associated values are collected). 8788e3e3a7aSWarner LoshAlthough strings are subject to garbage collection, 8798e3e3a7aSWarner Loshthey do not have an explicit construction, 8808e3e3a7aSWarner Loshand therefore are not removed from weak tables. 8818e3e3a7aSWarner Losh 8828e3e3a7aSWarner Losh 8838e3e3a7aSWarner Losh<p> 8848e3e3a7aSWarner LoshResurrected objects 8858e3e3a7aSWarner Losh(that is, objects being finalized 8868e3e3a7aSWarner Loshand objects accessible only through objects being finalized) 8878e3e3a7aSWarner Loshhave a special behavior in weak tables. 8888e3e3a7aSWarner LoshThey are removed from weak values before running their finalizers, 8898e3e3a7aSWarner Loshbut are removed from weak keys only in the next collection 8908e3e3a7aSWarner Loshafter running their finalizers, when such objects are actually freed. 8918e3e3a7aSWarner LoshThis behavior allows the finalizer to access properties 8928e3e3a7aSWarner Loshassociated with the object through weak tables. 8938e3e3a7aSWarner Losh 8948e3e3a7aSWarner Losh 8958e3e3a7aSWarner Losh<p> 8968e3e3a7aSWarner LoshIf a weak table is among the resurrected objects in a collection cycle, 8978e3e3a7aSWarner Loshit may not be properly cleared until the next cycle. 8988e3e3a7aSWarner Losh 8998e3e3a7aSWarner Losh 9008e3e3a7aSWarner Losh 9018e3e3a7aSWarner Losh 9028e3e3a7aSWarner Losh 9038e3e3a7aSWarner Losh 9048e3e3a7aSWarner Losh 9058e3e3a7aSWarner Losh<h2>2.6 – <a name="2.6">Coroutines</a></h2> 9068e3e3a7aSWarner Losh 9078e3e3a7aSWarner Losh<p> 9088e3e3a7aSWarner LoshLua supports coroutines, 9098e3e3a7aSWarner Loshalso called <em>collaborative multithreading</em>. 9108e3e3a7aSWarner LoshA coroutine in Lua represents an independent thread of execution. 9118e3e3a7aSWarner LoshUnlike threads in multithread systems, however, 9128e3e3a7aSWarner Losha coroutine only suspends its execution by explicitly calling 9138e3e3a7aSWarner Losha yield function. 9148e3e3a7aSWarner Losh 9158e3e3a7aSWarner Losh 9168e3e3a7aSWarner Losh<p> 9178e3e3a7aSWarner LoshYou create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>. 9188e3e3a7aSWarner LoshIts sole argument is a function 9198e3e3a7aSWarner Loshthat is the main function of the coroutine. 9208e3e3a7aSWarner LoshThe <code>create</code> function only creates a new coroutine and 9218e3e3a7aSWarner Loshreturns a handle to it (an object of type <em>thread</em>); 9228e3e3a7aSWarner Loshit does not start the coroutine. 9238e3e3a7aSWarner Losh 9248e3e3a7aSWarner Losh 9258e3e3a7aSWarner Losh<p> 9268e3e3a7aSWarner LoshYou execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 9278e3e3a7aSWarner LoshWhen you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 9288e3e3a7aSWarner Loshpassing as its first argument 9298e3e3a7aSWarner Losha thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 9308e3e3a7aSWarner Loshthe coroutine starts its execution by 9318e3e3a7aSWarner Loshcalling its main function. 9328e3e3a7aSWarner LoshExtra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed 9338e3e3a7aSWarner Loshas arguments to that function. 9348e3e3a7aSWarner LoshAfter the coroutine starts running, 9358e3e3a7aSWarner Loshit runs until it terminates or <em>yields</em>. 9368e3e3a7aSWarner Losh 9378e3e3a7aSWarner Losh 9388e3e3a7aSWarner Losh<p> 9398e3e3a7aSWarner LoshA coroutine can terminate its execution in two ways: 9408e3e3a7aSWarner Loshnormally, when its main function returns 9418e3e3a7aSWarner Losh(explicitly or implicitly, after the last instruction); 9428e3e3a7aSWarner Loshand abnormally, if there is an unprotected error. 9438e3e3a7aSWarner LoshIn case of normal termination, 9448e3e3a7aSWarner Losh<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>, 9458e3e3a7aSWarner Loshplus any values returned by the coroutine main function. 9468e3e3a7aSWarner LoshIn case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b> 9478e3e3a7aSWarner Loshplus an error object. 9488e3e3a7aSWarner Losh 9498e3e3a7aSWarner Losh 9508e3e3a7aSWarner Losh<p> 9518e3e3a7aSWarner LoshA coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 9528e3e3a7aSWarner LoshWhen a coroutine yields, 9538e3e3a7aSWarner Loshthe corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately, 9548e3e3a7aSWarner Losheven if the yield happens inside nested function calls 9558e3e3a7aSWarner Losh(that is, not in the main function, 9568e3e3a7aSWarner Loshbut in a function directly or indirectly called by the main function). 9578e3e3a7aSWarner LoshIn the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>, 9588e3e3a7aSWarner Loshplus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 9598e3e3a7aSWarner LoshThe next time you resume the same coroutine, 9608e3e3a7aSWarner Loshit continues its execution from the point where it yielded, 9618e3e3a7aSWarner Loshwith the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra 9628e3e3a7aSWarner Losharguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 9638e3e3a7aSWarner Losh 9648e3e3a7aSWarner Losh 9658e3e3a7aSWarner Losh<p> 9668e3e3a7aSWarner LoshLike <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 9678e3e3a7aSWarner Loshthe <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine, 9688e3e3a7aSWarner Loshbut instead of returning the coroutine itself, 9698e3e3a7aSWarner Loshit returns a function that, when called, resumes the coroutine. 9708e3e3a7aSWarner LoshAny arguments passed to this function 9718e3e3a7aSWarner Loshgo as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 9728e3e3a7aSWarner Losh<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>, 9738e3e3a7aSWarner Loshexcept the first one (the boolean error code). 9748e3e3a7aSWarner LoshUnlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 9758e3e3a7aSWarner Losh<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors; 9768e3e3a7aSWarner Loshany error is propagated to the caller. 9778e3e3a7aSWarner Losh 9788e3e3a7aSWarner Losh 9798e3e3a7aSWarner Losh<p> 9808e3e3a7aSWarner LoshAs an example of how coroutines work, 9818e3e3a7aSWarner Loshconsider the following code: 9828e3e3a7aSWarner Losh 9838e3e3a7aSWarner Losh<pre> 9848e3e3a7aSWarner Losh function foo (a) 9858e3e3a7aSWarner Losh print("foo", a) 9868e3e3a7aSWarner Losh return coroutine.yield(2*a) 9878e3e3a7aSWarner Losh end 9888e3e3a7aSWarner Losh 9898e3e3a7aSWarner Losh co = coroutine.create(function (a,b) 9908e3e3a7aSWarner Losh print("co-body", a, b) 9918e3e3a7aSWarner Losh local r = foo(a+1) 9928e3e3a7aSWarner Losh print("co-body", r) 9938e3e3a7aSWarner Losh local r, s = coroutine.yield(a+b, a-b) 9948e3e3a7aSWarner Losh print("co-body", r, s) 9958e3e3a7aSWarner Losh return b, "end" 9968e3e3a7aSWarner Losh end) 9978e3e3a7aSWarner Losh 9988e3e3a7aSWarner Losh print("main", coroutine.resume(co, 1, 10)) 9998e3e3a7aSWarner Losh print("main", coroutine.resume(co, "r")) 10008e3e3a7aSWarner Losh print("main", coroutine.resume(co, "x", "y")) 10018e3e3a7aSWarner Losh print("main", coroutine.resume(co, "x", "y")) 10028e3e3a7aSWarner Losh</pre><p> 10038e3e3a7aSWarner LoshWhen you run it, it produces the following output: 10048e3e3a7aSWarner Losh 10058e3e3a7aSWarner Losh<pre> 10068e3e3a7aSWarner Losh co-body 1 10 10078e3e3a7aSWarner Losh foo 2 10088e3e3a7aSWarner Losh main true 4 10098e3e3a7aSWarner Losh co-body r 10108e3e3a7aSWarner Losh main true 11 -9 10118e3e3a7aSWarner Losh co-body x y 10128e3e3a7aSWarner Losh main true 10 end 10138e3e3a7aSWarner Losh main false cannot resume dead coroutine 10148e3e3a7aSWarner Losh</pre> 10158e3e3a7aSWarner Losh 10168e3e3a7aSWarner Losh<p> 10178e3e3a7aSWarner LoshYou can also create and manipulate coroutines through the C API: 10188e3e3a7aSWarner Loshsee functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>, 10198e3e3a7aSWarner Loshand <a href="#lua_yield"><code>lua_yield</code></a>. 10208e3e3a7aSWarner Losh 10218e3e3a7aSWarner Losh 10228e3e3a7aSWarner Losh 10238e3e3a7aSWarner Losh 10248e3e3a7aSWarner Losh 10258e3e3a7aSWarner Losh<h1>3 – <a name="3">The Language</a></h1> 10268e3e3a7aSWarner Losh 10278e3e3a7aSWarner Losh<p> 10288e3e3a7aSWarner LoshThis section describes the lexis, the syntax, and the semantics of Lua. 10298e3e3a7aSWarner LoshIn other words, 10308e3e3a7aSWarner Loshthis section describes 10318e3e3a7aSWarner Loshwhich tokens are valid, 10328e3e3a7aSWarner Loshhow they can be combined, 10338e3e3a7aSWarner Loshand what their combinations mean. 10348e3e3a7aSWarner Losh 10358e3e3a7aSWarner Losh 10368e3e3a7aSWarner Losh<p> 10378e3e3a7aSWarner LoshLanguage constructs will be explained using the usual extended BNF notation, 10388e3e3a7aSWarner Loshin which 10398e3e3a7aSWarner Losh{<em>a</em>} means 0 or more <em>a</em>'s, and 10408e3e3a7aSWarner Losh[<em>a</em>] means an optional <em>a</em>. 10418e3e3a7aSWarner LoshNon-terminals are shown like non-terminal, 10428e3e3a7aSWarner Loshkeywords are shown like <b>kword</b>, 10438e3e3a7aSWarner Loshand other terminal symbols are shown like ‘<b>=</b>’. 10448e3e3a7aSWarner LoshThe complete syntax of Lua can be found in <a href="#9">§9</a> 10458e3e3a7aSWarner Loshat the end of this manual. 10468e3e3a7aSWarner Losh 10478e3e3a7aSWarner Losh 10488e3e3a7aSWarner Losh 10498e3e3a7aSWarner Losh<h2>3.1 – <a name="3.1">Lexical Conventions</a></h2> 10508e3e3a7aSWarner Losh 10518e3e3a7aSWarner Losh<p> 10528e3e3a7aSWarner LoshLua is a free-form language. 10538e3e3a7aSWarner LoshIt ignores spaces (including new lines) and comments 10548e3e3a7aSWarner Loshbetween lexical elements (tokens), 10558e3e3a7aSWarner Loshexcept as delimiters between names and keywords. 10568e3e3a7aSWarner Losh 10578e3e3a7aSWarner Losh 10588e3e3a7aSWarner Losh<p> 10598e3e3a7aSWarner Losh<em>Names</em> 10608e3e3a7aSWarner Losh(also called <em>identifiers</em>) 10618e3e3a7aSWarner Loshin Lua can be any string of letters, 10628e3e3a7aSWarner Loshdigits, and underscores, 10638e3e3a7aSWarner Loshnot beginning with a digit and 10648e3e3a7aSWarner Loshnot being a reserved word. 10658e3e3a7aSWarner LoshIdentifiers are used to name variables, table fields, and labels. 10668e3e3a7aSWarner Losh 10678e3e3a7aSWarner Losh 10688e3e3a7aSWarner Losh<p> 10698e3e3a7aSWarner LoshThe following <em>keywords</em> are reserved 10708e3e3a7aSWarner Loshand cannot be used as names: 10718e3e3a7aSWarner Losh 10728e3e3a7aSWarner Losh 10738e3e3a7aSWarner Losh<pre> 10748e3e3a7aSWarner Losh and break do else elseif end 10758e3e3a7aSWarner Losh false for function goto if in 10768e3e3a7aSWarner Losh local nil not or repeat return 10778e3e3a7aSWarner Losh then true until while 10788e3e3a7aSWarner Losh</pre> 10798e3e3a7aSWarner Losh 10808e3e3a7aSWarner Losh<p> 10818e3e3a7aSWarner LoshLua is a case-sensitive language: 10828e3e3a7aSWarner Losh<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> 10838e3e3a7aSWarner Loshare two different, valid names. 10848e3e3a7aSWarner LoshAs a convention, 10858e3e3a7aSWarner Loshprograms should avoid creating 10868e3e3a7aSWarner Loshnames that start with an underscore followed by 10878e3e3a7aSWarner Loshone or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>). 10888e3e3a7aSWarner Losh 10898e3e3a7aSWarner Losh 10908e3e3a7aSWarner Losh<p> 10918e3e3a7aSWarner LoshThe following strings denote other tokens: 10928e3e3a7aSWarner Losh 10938e3e3a7aSWarner Losh<pre> 10948e3e3a7aSWarner Losh + - * / % ^ # 10958e3e3a7aSWarner Losh & ~ | << >> // 10968e3e3a7aSWarner Losh == ~= <= >= < > = 10978e3e3a7aSWarner Losh ( ) { } [ ] :: 10988e3e3a7aSWarner Losh ; : , . .. ... 10998e3e3a7aSWarner Losh</pre> 11008e3e3a7aSWarner Losh 11018e3e3a7aSWarner Losh<p> 11028e3e3a7aSWarner LoshA <em>short literal string</em> 11038e3e3a7aSWarner Loshcan be delimited by matching single or double quotes, 11048e3e3a7aSWarner Loshand can contain the following C-like escape sequences: 11058e3e3a7aSWarner Losh'<code>\a</code>' (bell), 11068e3e3a7aSWarner Losh'<code>\b</code>' (backspace), 11078e3e3a7aSWarner Losh'<code>\f</code>' (form feed), 11088e3e3a7aSWarner Losh'<code>\n</code>' (newline), 11098e3e3a7aSWarner Losh'<code>\r</code>' (carriage return), 11108e3e3a7aSWarner Losh'<code>\t</code>' (horizontal tab), 11118e3e3a7aSWarner Losh'<code>\v</code>' (vertical tab), 11128e3e3a7aSWarner Losh'<code>\\</code>' (backslash), 11138e3e3a7aSWarner Losh'<code>\"</code>' (quotation mark [double quote]), 11148e3e3a7aSWarner Loshand '<code>\'</code>' (apostrophe [single quote]). 11158e3e3a7aSWarner LoshA backslash followed by a line break 11168e3e3a7aSWarner Loshresults in a newline in the string. 11178e3e3a7aSWarner LoshThe escape sequence '<code>\z</code>' skips the following span 11188e3e3a7aSWarner Loshof white-space characters, 11198e3e3a7aSWarner Loshincluding line breaks; 11208e3e3a7aSWarner Loshit is particularly useful to break and indent a long literal string 11218e3e3a7aSWarner Loshinto multiple lines without adding the newlines and spaces 11228e3e3a7aSWarner Loshinto the string contents. 11238e3e3a7aSWarner LoshA short literal string cannot contain unescaped line breaks 11248e3e3a7aSWarner Loshnor escapes not forming a valid escape sequence. 11258e3e3a7aSWarner Losh 11268e3e3a7aSWarner Losh 11278e3e3a7aSWarner Losh<p> 11288e3e3a7aSWarner LoshWe can specify any byte in a short literal string by its numeric value 11298e3e3a7aSWarner Losh(including embedded zeros). 11308e3e3a7aSWarner LoshThis can be done 11318e3e3a7aSWarner Loshwith the escape sequence <code>\x<em>XX</em></code>, 11328e3e3a7aSWarner Loshwhere <em>XX</em> is a sequence of exactly two hexadecimal digits, 11338e3e3a7aSWarner Loshor with the escape sequence <code>\<em>ddd</em></code>, 11348e3e3a7aSWarner Loshwhere <em>ddd</em> is a sequence of up to three decimal digits. 11358e3e3a7aSWarner Losh(Note that if a decimal escape sequence is to be followed by a digit, 11368e3e3a7aSWarner Loshit must be expressed using exactly three digits.) 11378e3e3a7aSWarner Losh 11388e3e3a7aSWarner Losh 11398e3e3a7aSWarner Losh<p> 11408e3e3a7aSWarner LoshThe UTF-8 encoding of a Unicode character 11418e3e3a7aSWarner Loshcan be inserted in a literal string with 11428e3e3a7aSWarner Loshthe escape sequence <code>\u{<em>XXX</em>}</code> 11438e3e3a7aSWarner Losh(note the mandatory enclosing brackets), 11448e3e3a7aSWarner Loshwhere <em>XXX</em> is a sequence of one or more hexadecimal digits 11458e3e3a7aSWarner Loshrepresenting the character code point. 11468e3e3a7aSWarner Losh 11478e3e3a7aSWarner Losh 11488e3e3a7aSWarner Losh<p> 11498e3e3a7aSWarner LoshLiteral strings can also be defined using a long format 11508e3e3a7aSWarner Loshenclosed by <em>long brackets</em>. 11518e3e3a7aSWarner LoshWe define an <em>opening long bracket of level <em>n</em></em> as an opening 11528e3e3a7aSWarner Loshsquare bracket followed by <em>n</em> equal signs followed by another 11538e3e3a7aSWarner Loshopening square bracket. 11548e3e3a7aSWarner LoshSo, an opening long bracket of level 0 is written as <code>[[</code>, 11558e3e3a7aSWarner Loshan opening long bracket of level 1 is written as <code>[=[</code>, 11568e3e3a7aSWarner Loshand so on. 11578e3e3a7aSWarner LoshA <em>closing long bracket</em> is defined similarly; 11588e3e3a7aSWarner Loshfor instance, 11598e3e3a7aSWarner Losha closing long bracket of level 4 is written as <code>]====]</code>. 11608e3e3a7aSWarner LoshA <em>long literal</em> starts with an opening long bracket of any level and 11618e3e3a7aSWarner Loshends at the first closing long bracket of the same level. 11628e3e3a7aSWarner LoshIt can contain any text except a closing bracket of the same level. 11638e3e3a7aSWarner LoshLiterals in this bracketed form can run for several lines, 11648e3e3a7aSWarner Loshdo not interpret any escape sequences, 11658e3e3a7aSWarner Loshand ignore long brackets of any other level. 11668e3e3a7aSWarner LoshAny kind of end-of-line sequence 11678e3e3a7aSWarner Losh(carriage return, newline, carriage return followed by newline, 11688e3e3a7aSWarner Loshor newline followed by carriage return) 11698e3e3a7aSWarner Loshis converted to a simple newline. 11708e3e3a7aSWarner Losh 11718e3e3a7aSWarner Losh 11728e3e3a7aSWarner Losh<p> 11738e3e3a7aSWarner LoshFor convenience, 11748e3e3a7aSWarner Loshwhen the opening long bracket is immediately followed by a newline, 11758e3e3a7aSWarner Loshthe newline is not included in the string. 11768e3e3a7aSWarner LoshAs an example, in a system using ASCII 11778e3e3a7aSWarner Losh(in which '<code>a</code>' is coded as 97, 11788e3e3a7aSWarner Loshnewline is coded as 10, and '<code>1</code>' is coded as 49), 11798e3e3a7aSWarner Loshthe five literal strings below denote the same string: 11808e3e3a7aSWarner Losh 11818e3e3a7aSWarner Losh<pre> 11828e3e3a7aSWarner Losh a = 'alo\n123"' 11838e3e3a7aSWarner Losh a = "alo\n123\"" 11848e3e3a7aSWarner Losh a = '\97lo\10\04923"' 11858e3e3a7aSWarner Losh a = [[alo 11868e3e3a7aSWarner Losh 123"]] 11878e3e3a7aSWarner Losh a = [==[ 11888e3e3a7aSWarner Losh alo 11898e3e3a7aSWarner Losh 123"]==] 11908e3e3a7aSWarner Losh</pre> 11918e3e3a7aSWarner Losh 11928e3e3a7aSWarner Losh<p> 11938e3e3a7aSWarner LoshAny byte in a literal string not 11948e3e3a7aSWarner Loshexplicitly affected by the previous rules represents itself. 11958e3e3a7aSWarner LoshHowever, Lua opens files for parsing in text mode, 11968e3e3a7aSWarner Loshand the system file functions may have problems with 11978e3e3a7aSWarner Loshsome control characters. 11988e3e3a7aSWarner LoshSo, it is safer to represent 11998e3e3a7aSWarner Loshnon-text data as a quoted literal with 12008e3e3a7aSWarner Loshexplicit escape sequences for the non-text characters. 12018e3e3a7aSWarner Losh 12028e3e3a7aSWarner Losh 12038e3e3a7aSWarner Losh<p> 12048e3e3a7aSWarner LoshA <em>numeric constant</em> (or <em>numeral</em>) 12058e3e3a7aSWarner Loshcan be written with an optional fractional part 12068e3e3a7aSWarner Loshand an optional decimal exponent, 12078e3e3a7aSWarner Loshmarked by a letter '<code>e</code>' or '<code>E</code>'. 12088e3e3a7aSWarner LoshLua also accepts hexadecimal constants, 12098e3e3a7aSWarner Loshwhich start with <code>0x</code> or <code>0X</code>. 12108e3e3a7aSWarner LoshHexadecimal constants also accept an optional fractional part 12118e3e3a7aSWarner Loshplus an optional binary exponent, 12128e3e3a7aSWarner Loshmarked by a letter '<code>p</code>' or '<code>P</code>'. 12138e3e3a7aSWarner LoshA numeric constant with a radix point or an exponent 12148e3e3a7aSWarner Loshdenotes a float; 12158e3e3a7aSWarner Loshotherwise, 12168e3e3a7aSWarner Loshif its value fits in an integer, 12178e3e3a7aSWarner Loshit denotes an integer. 12188e3e3a7aSWarner LoshExamples of valid integer constants are 12198e3e3a7aSWarner Losh 12208e3e3a7aSWarner Losh<pre> 12218e3e3a7aSWarner Losh 3 345 0xff 0xBEBADA 12228e3e3a7aSWarner Losh</pre><p> 12238e3e3a7aSWarner LoshExamples of valid float constants are 12248e3e3a7aSWarner Losh 12258e3e3a7aSWarner Losh<pre> 12268e3e3a7aSWarner Losh 3.0 3.1416 314.16e-2 0.31416E1 34e1 12278e3e3a7aSWarner Losh 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 12288e3e3a7aSWarner Losh</pre> 12298e3e3a7aSWarner Losh 12308e3e3a7aSWarner Losh<p> 12318e3e3a7aSWarner LoshA <em>comment</em> starts with a double hyphen (<code>--</code>) 12328e3e3a7aSWarner Loshanywhere outside a string. 12338e3e3a7aSWarner LoshIf the text immediately after <code>--</code> is not an opening long bracket, 12348e3e3a7aSWarner Loshthe comment is a <em>short comment</em>, 12358e3e3a7aSWarner Loshwhich runs until the end of the line. 12368e3e3a7aSWarner LoshOtherwise, it is a <em>long comment</em>, 12378e3e3a7aSWarner Loshwhich runs until the corresponding closing long bracket. 12388e3e3a7aSWarner LoshLong comments are frequently used to disable code temporarily. 12398e3e3a7aSWarner Losh 12408e3e3a7aSWarner Losh 12418e3e3a7aSWarner Losh 12428e3e3a7aSWarner Losh 12438e3e3a7aSWarner Losh 12448e3e3a7aSWarner Losh<h2>3.2 – <a name="3.2">Variables</a></h2> 12458e3e3a7aSWarner Losh 12468e3e3a7aSWarner Losh<p> 12478e3e3a7aSWarner LoshVariables are places that store values. 12488e3e3a7aSWarner LoshThere are three kinds of variables in Lua: 12498e3e3a7aSWarner Loshglobal variables, local variables, and table fields. 12508e3e3a7aSWarner Losh 12518e3e3a7aSWarner Losh 12528e3e3a7aSWarner Losh<p> 12538e3e3a7aSWarner LoshA single name can denote a global variable or a local variable 12548e3e3a7aSWarner Losh(or a function's formal parameter, 12558e3e3a7aSWarner Loshwhich is a particular kind of local variable): 12568e3e3a7aSWarner Losh 12578e3e3a7aSWarner Losh<pre> 12588e3e3a7aSWarner Losh var ::= Name 12598e3e3a7aSWarner Losh</pre><p> 12608e3e3a7aSWarner LoshName denotes identifiers, as defined in <a href="#3.1">§3.1</a>. 12618e3e3a7aSWarner Losh 12628e3e3a7aSWarner Losh 12638e3e3a7aSWarner Losh<p> 12648e3e3a7aSWarner LoshAny variable name is assumed to be global unless explicitly declared 12658e3e3a7aSWarner Loshas a local (see <a href="#3.3.7">§3.3.7</a>). 12668e3e3a7aSWarner LoshLocal variables are <em>lexically scoped</em>: 12678e3e3a7aSWarner Loshlocal variables can be freely accessed by functions 12688e3e3a7aSWarner Loshdefined inside their scope (see <a href="#3.5">§3.5</a>). 12698e3e3a7aSWarner Losh 12708e3e3a7aSWarner Losh 12718e3e3a7aSWarner Losh<p> 12728e3e3a7aSWarner LoshBefore the first assignment to a variable, its value is <b>nil</b>. 12738e3e3a7aSWarner Losh 12748e3e3a7aSWarner Losh 12758e3e3a7aSWarner Losh<p> 12768e3e3a7aSWarner LoshSquare brackets are used to index a table: 12778e3e3a7aSWarner Losh 12788e3e3a7aSWarner Losh<pre> 12798e3e3a7aSWarner Losh var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ 12808e3e3a7aSWarner Losh</pre><p> 1281*e112e9d2SKyle EvansThe meaning of accesses to table fields can be changed via metatables 1282*e112e9d2SKyle Evans(see <a href="#2.4">§2.4</a>). 12838e3e3a7aSWarner Losh 12848e3e3a7aSWarner Losh 12858e3e3a7aSWarner Losh<p> 12868e3e3a7aSWarner LoshThe syntax <code>var.Name</code> is just syntactic sugar for 12878e3e3a7aSWarner Losh<code>var["Name"]</code>: 12888e3e3a7aSWarner Losh 12898e3e3a7aSWarner Losh<pre> 12908e3e3a7aSWarner Losh var ::= prefixexp ‘<b>.</b>’ Name 12918e3e3a7aSWarner Losh</pre> 12928e3e3a7aSWarner Losh 12938e3e3a7aSWarner Losh<p> 12948e3e3a7aSWarner LoshAn access to a global variable <code>x</code> 12958e3e3a7aSWarner Loshis equivalent to <code>_ENV.x</code>. 12968e3e3a7aSWarner LoshDue to the way that chunks are compiled, 12978e3e3a7aSWarner Losh<code>_ENV</code> is never a global name (see <a href="#2.2">§2.2</a>). 12988e3e3a7aSWarner Losh 12998e3e3a7aSWarner Losh 13008e3e3a7aSWarner Losh 13018e3e3a7aSWarner Losh 13028e3e3a7aSWarner Losh 13038e3e3a7aSWarner Losh<h2>3.3 – <a name="3.3">Statements</a></h2> 13048e3e3a7aSWarner Losh 13058e3e3a7aSWarner Losh<p> 13068e3e3a7aSWarner LoshLua supports an almost conventional set of statements, 13078e3e3a7aSWarner Loshsimilar to those in Pascal or C. 13088e3e3a7aSWarner LoshThis set includes 13098e3e3a7aSWarner Loshassignments, control structures, function calls, 13108e3e3a7aSWarner Loshand variable declarations. 13118e3e3a7aSWarner Losh 13128e3e3a7aSWarner Losh 13138e3e3a7aSWarner Losh 13148e3e3a7aSWarner Losh<h3>3.3.1 – <a name="3.3.1">Blocks</a></h3> 13158e3e3a7aSWarner Losh 13168e3e3a7aSWarner Losh<p> 13178e3e3a7aSWarner LoshA block is a list of statements, 13188e3e3a7aSWarner Loshwhich are executed sequentially: 13198e3e3a7aSWarner Losh 13208e3e3a7aSWarner Losh<pre> 13218e3e3a7aSWarner Losh block ::= {stat} 13228e3e3a7aSWarner Losh</pre><p> 13238e3e3a7aSWarner LoshLua has <em>empty statements</em> 13248e3e3a7aSWarner Loshthat allow you to separate statements with semicolons, 13258e3e3a7aSWarner Loshstart a block with a semicolon 13268e3e3a7aSWarner Loshor write two semicolons in sequence: 13278e3e3a7aSWarner Losh 13288e3e3a7aSWarner Losh<pre> 13298e3e3a7aSWarner Losh stat ::= ‘<b>;</b>’ 13308e3e3a7aSWarner Losh</pre> 13318e3e3a7aSWarner Losh 13328e3e3a7aSWarner Losh<p> 13338e3e3a7aSWarner LoshFunction calls and assignments 13348e3e3a7aSWarner Loshcan start with an open parenthesis. 13358e3e3a7aSWarner LoshThis possibility leads to an ambiguity in Lua's grammar. 13368e3e3a7aSWarner LoshConsider the following fragment: 13378e3e3a7aSWarner Losh 13388e3e3a7aSWarner Losh<pre> 13398e3e3a7aSWarner Losh a = b + c 13408e3e3a7aSWarner Losh (print or io.write)('done') 13418e3e3a7aSWarner Losh</pre><p> 13428e3e3a7aSWarner LoshThe grammar could see it in two ways: 13438e3e3a7aSWarner Losh 13448e3e3a7aSWarner Losh<pre> 13458e3e3a7aSWarner Losh a = b + c(print or io.write)('done') 13468e3e3a7aSWarner Losh 13478e3e3a7aSWarner Losh a = b + c; (print or io.write)('done') 13488e3e3a7aSWarner Losh</pre><p> 13498e3e3a7aSWarner LoshThe current parser always sees such constructions 13508e3e3a7aSWarner Loshin the first way, 13518e3e3a7aSWarner Loshinterpreting the open parenthesis 13528e3e3a7aSWarner Loshas the start of the arguments to a call. 13538e3e3a7aSWarner LoshTo avoid this ambiguity, 13548e3e3a7aSWarner Loshit is a good practice to always precede with a semicolon 13558e3e3a7aSWarner Loshstatements that start with a parenthesis: 13568e3e3a7aSWarner Losh 13578e3e3a7aSWarner Losh<pre> 13588e3e3a7aSWarner Losh ;(print or io.write)('done') 13598e3e3a7aSWarner Losh</pre> 13608e3e3a7aSWarner Losh 13618e3e3a7aSWarner Losh<p> 13628e3e3a7aSWarner LoshA block can be explicitly delimited to produce a single statement: 13638e3e3a7aSWarner Losh 13648e3e3a7aSWarner Losh<pre> 13658e3e3a7aSWarner Losh stat ::= <b>do</b> block <b>end</b> 13668e3e3a7aSWarner Losh</pre><p> 13678e3e3a7aSWarner LoshExplicit blocks are useful 13688e3e3a7aSWarner Loshto control the scope of variable declarations. 13698e3e3a7aSWarner LoshExplicit blocks are also sometimes used to 13708e3e3a7aSWarner Loshadd a <b>return</b> statement in the middle 13718e3e3a7aSWarner Loshof another block (see <a href="#3.3.4">§3.3.4</a>). 13728e3e3a7aSWarner Losh 13738e3e3a7aSWarner Losh 13748e3e3a7aSWarner Losh 13758e3e3a7aSWarner Losh 13768e3e3a7aSWarner Losh 13778e3e3a7aSWarner Losh<h3>3.3.2 – <a name="3.3.2">Chunks</a></h3> 13788e3e3a7aSWarner Losh 13798e3e3a7aSWarner Losh<p> 13808e3e3a7aSWarner LoshThe unit of compilation of Lua is called a <em>chunk</em>. 13818e3e3a7aSWarner LoshSyntactically, 13828e3e3a7aSWarner Losha chunk is simply a block: 13838e3e3a7aSWarner Losh 13848e3e3a7aSWarner Losh<pre> 13858e3e3a7aSWarner Losh chunk ::= block 13868e3e3a7aSWarner Losh</pre> 13878e3e3a7aSWarner Losh 13888e3e3a7aSWarner Losh<p> 13898e3e3a7aSWarner LoshLua handles a chunk as the body of an anonymous function 13908e3e3a7aSWarner Loshwith a variable number of arguments 13918e3e3a7aSWarner Losh(see <a href="#3.4.11">§3.4.11</a>). 13928e3e3a7aSWarner LoshAs such, chunks can define local variables, 13938e3e3a7aSWarner Loshreceive arguments, and return values. 13948e3e3a7aSWarner LoshMoreover, such anonymous function is compiled as in the 13958e3e3a7aSWarner Loshscope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>). 13968e3e3a7aSWarner LoshThe resulting function always has <code>_ENV</code> as its only upvalue, 13978e3e3a7aSWarner Losheven if it does not use that variable. 13988e3e3a7aSWarner Losh 13998e3e3a7aSWarner Losh 14008e3e3a7aSWarner Losh<p> 14018e3e3a7aSWarner LoshA chunk can be stored in a file or in a string inside the host program. 14028e3e3a7aSWarner LoshTo execute a chunk, 14038e3e3a7aSWarner LoshLua first <em>loads</em> it, 14048e3e3a7aSWarner Loshprecompiling the chunk's code into instructions for a virtual machine, 14058e3e3a7aSWarner Loshand then Lua executes the compiled code 14068e3e3a7aSWarner Loshwith an interpreter for the virtual machine. 14078e3e3a7aSWarner Losh 14088e3e3a7aSWarner Losh 14098e3e3a7aSWarner Losh<p> 14108e3e3a7aSWarner LoshChunks can also be precompiled into binary form; 14118e3e3a7aSWarner Loshsee program <code>luac</code> and function <a href="#pdf-string.dump"><code>string.dump</code></a> for details. 14128e3e3a7aSWarner LoshPrograms in source and compiled forms are interchangeable; 14138e3e3a7aSWarner LoshLua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>). 14148e3e3a7aSWarner Losh 14158e3e3a7aSWarner Losh 14168e3e3a7aSWarner Losh 14178e3e3a7aSWarner Losh 14188e3e3a7aSWarner Losh 14198e3e3a7aSWarner Losh<h3>3.3.3 – <a name="3.3.3">Assignment</a></h3> 14208e3e3a7aSWarner Losh 14218e3e3a7aSWarner Losh<p> 14228e3e3a7aSWarner LoshLua allows multiple assignments. 14238e3e3a7aSWarner LoshTherefore, the syntax for assignment 14248e3e3a7aSWarner Loshdefines a list of variables on the left side 14258e3e3a7aSWarner Loshand a list of expressions on the right side. 14268e3e3a7aSWarner LoshThe elements in both lists are separated by commas: 14278e3e3a7aSWarner Losh 14288e3e3a7aSWarner Losh<pre> 14298e3e3a7aSWarner Losh stat ::= varlist ‘<b>=</b>’ explist 14308e3e3a7aSWarner Losh varlist ::= var {‘<b>,</b>’ var} 14318e3e3a7aSWarner Losh explist ::= exp {‘<b>,</b>’ exp} 14328e3e3a7aSWarner Losh</pre><p> 14338e3e3a7aSWarner LoshExpressions are discussed in <a href="#3.4">§3.4</a>. 14348e3e3a7aSWarner Losh 14358e3e3a7aSWarner Losh 14368e3e3a7aSWarner Losh<p> 14378e3e3a7aSWarner LoshBefore the assignment, 14388e3e3a7aSWarner Loshthe list of values is <em>adjusted</em> to the length of 14398e3e3a7aSWarner Loshthe list of variables. 14408e3e3a7aSWarner LoshIf there are more values than needed, 14418e3e3a7aSWarner Loshthe excess values are thrown away. 14428e3e3a7aSWarner LoshIf there are fewer values than needed, 14438e3e3a7aSWarner Loshthe list is extended with as many <b>nil</b>'s as needed. 14448e3e3a7aSWarner LoshIf the list of expressions ends with a function call, 14458e3e3a7aSWarner Loshthen all values returned by that call enter the list of values, 14468e3e3a7aSWarner Loshbefore the adjustment 14478e3e3a7aSWarner Losh(except when the call is enclosed in parentheses; see <a href="#3.4">§3.4</a>). 14488e3e3a7aSWarner Losh 14498e3e3a7aSWarner Losh 14508e3e3a7aSWarner Losh<p> 14518e3e3a7aSWarner LoshThe assignment statement first evaluates all its expressions 14528e3e3a7aSWarner Loshand only then the assignments are performed. 14538e3e3a7aSWarner LoshThus the code 14548e3e3a7aSWarner Losh 14558e3e3a7aSWarner Losh<pre> 14568e3e3a7aSWarner Losh i = 3 14578e3e3a7aSWarner Losh i, a[i] = i+1, 20 14588e3e3a7aSWarner Losh</pre><p> 14598e3e3a7aSWarner Loshsets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 14608e3e3a7aSWarner Loshbecause the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 14618e3e3a7aSWarner Loshbefore it is assigned 4. 14628e3e3a7aSWarner LoshSimilarly, the line 14638e3e3a7aSWarner Losh 14648e3e3a7aSWarner Losh<pre> 14658e3e3a7aSWarner Losh x, y = y, x 14668e3e3a7aSWarner Losh</pre><p> 14678e3e3a7aSWarner Loshexchanges the values of <code>x</code> and <code>y</code>, 14688e3e3a7aSWarner Loshand 14698e3e3a7aSWarner Losh 14708e3e3a7aSWarner Losh<pre> 14718e3e3a7aSWarner Losh x, y, z = y, z, x 14728e3e3a7aSWarner Losh</pre><p> 14738e3e3a7aSWarner Loshcyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 14748e3e3a7aSWarner Losh 14758e3e3a7aSWarner Losh 14768e3e3a7aSWarner Losh<p> 14778e3e3a7aSWarner LoshAn assignment to a global name <code>x = val</code> 14788e3e3a7aSWarner Loshis equivalent to the assignment 14798e3e3a7aSWarner Losh<code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>). 14808e3e3a7aSWarner Losh 14818e3e3a7aSWarner Losh 1482*e112e9d2SKyle Evans<p> 1483*e112e9d2SKyle EvansThe meaning of assignments to table fields and 1484*e112e9d2SKyle Evansglobal variables (which are actually table fields, too) 1485*e112e9d2SKyle Evanscan be changed via metatables (see <a href="#2.4">§2.4</a>). 1486*e112e9d2SKyle Evans 1487*e112e9d2SKyle Evans 14888e3e3a7aSWarner Losh 14898e3e3a7aSWarner Losh 14908e3e3a7aSWarner Losh 14918e3e3a7aSWarner Losh<h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p> 14928e3e3a7aSWarner LoshThe control structures 14938e3e3a7aSWarner Losh<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 14948e3e3a7aSWarner Loshfamiliar syntax: 14958e3e3a7aSWarner Losh 14968e3e3a7aSWarner Losh 14978e3e3a7aSWarner Losh 14988e3e3a7aSWarner Losh 14998e3e3a7aSWarner Losh<pre> 15008e3e3a7aSWarner Losh stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 15018e3e3a7aSWarner Losh stat ::= <b>repeat</b> block <b>until</b> exp 15028e3e3a7aSWarner Losh stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> 15038e3e3a7aSWarner Losh</pre><p> 15048e3e3a7aSWarner LoshLua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>). 15058e3e3a7aSWarner Losh 15068e3e3a7aSWarner Losh 15078e3e3a7aSWarner Losh<p> 15088e3e3a7aSWarner LoshThe condition expression of a 15098e3e3a7aSWarner Loshcontrol structure can return any value. 15108e3e3a7aSWarner LoshBoth <b>false</b> and <b>nil</b> are considered false. 15118e3e3a7aSWarner LoshAll values different from <b>nil</b> and <b>false</b> are considered true 15128e3e3a7aSWarner Losh(in particular, the number 0 and the empty string are also true). 15138e3e3a7aSWarner Losh 15148e3e3a7aSWarner Losh 15158e3e3a7aSWarner Losh<p> 15168e3e3a7aSWarner LoshIn the <b>repeat</b>–<b>until</b> loop, 15178e3e3a7aSWarner Loshthe inner block does not end at the <b>until</b> keyword, 15188e3e3a7aSWarner Loshbut only after the condition. 15198e3e3a7aSWarner LoshSo, the condition can refer to local variables 15208e3e3a7aSWarner Loshdeclared inside the loop block. 15218e3e3a7aSWarner Losh 15228e3e3a7aSWarner Losh 15238e3e3a7aSWarner Losh<p> 15248e3e3a7aSWarner LoshThe <b>goto</b> statement transfers the program control to a label. 15258e3e3a7aSWarner LoshFor syntactical reasons, 15268e3e3a7aSWarner Loshlabels in Lua are considered statements too: 15278e3e3a7aSWarner Losh 15288e3e3a7aSWarner Losh 15298e3e3a7aSWarner Losh 15308e3e3a7aSWarner Losh<pre> 15318e3e3a7aSWarner Losh stat ::= <b>goto</b> Name 15328e3e3a7aSWarner Losh stat ::= label 15338e3e3a7aSWarner Losh label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 15348e3e3a7aSWarner Losh</pre> 15358e3e3a7aSWarner Losh 15368e3e3a7aSWarner Losh<p> 15378e3e3a7aSWarner LoshA label is visible in the entire block where it is defined, 15388e3e3a7aSWarner Loshexcept 15398e3e3a7aSWarner Loshinside nested blocks where a label with the same name is defined and 15408e3e3a7aSWarner Loshinside nested functions. 15418e3e3a7aSWarner LoshA goto may jump to any visible label as long as it does not 15428e3e3a7aSWarner Loshenter into the scope of a local variable. 15438e3e3a7aSWarner Losh 15448e3e3a7aSWarner Losh 15458e3e3a7aSWarner Losh<p> 15468e3e3a7aSWarner LoshLabels and empty statements are called <em>void statements</em>, 15478e3e3a7aSWarner Loshas they perform no actions. 15488e3e3a7aSWarner Losh 15498e3e3a7aSWarner Losh 15508e3e3a7aSWarner Losh<p> 15518e3e3a7aSWarner LoshThe <b>break</b> statement terminates the execution of a 15528e3e3a7aSWarner Losh<b>while</b>, <b>repeat</b>, or <b>for</b> loop, 15538e3e3a7aSWarner Loshskipping to the next statement after the loop: 15548e3e3a7aSWarner Losh 15558e3e3a7aSWarner Losh 15568e3e3a7aSWarner Losh<pre> 15578e3e3a7aSWarner Losh stat ::= <b>break</b> 15588e3e3a7aSWarner Losh</pre><p> 15598e3e3a7aSWarner LoshA <b>break</b> ends the innermost enclosing loop. 15608e3e3a7aSWarner Losh 15618e3e3a7aSWarner Losh 15628e3e3a7aSWarner Losh<p> 15638e3e3a7aSWarner LoshThe <b>return</b> statement is used to return values 15648e3e3a7aSWarner Loshfrom a function or a chunk 15658e3e3a7aSWarner Losh(which is an anonymous function). 15668e3e3a7aSWarner Losh 15678e3e3a7aSWarner LoshFunctions can return more than one value, 15688e3e3a7aSWarner Loshso the syntax for the <b>return</b> statement is 15698e3e3a7aSWarner Losh 15708e3e3a7aSWarner Losh<pre> 15718e3e3a7aSWarner Losh stat ::= <b>return</b> [explist] [‘<b>;</b>’] 15728e3e3a7aSWarner Losh</pre> 15738e3e3a7aSWarner Losh 15748e3e3a7aSWarner Losh<p> 15758e3e3a7aSWarner LoshThe <b>return</b> statement can only be written 15768e3e3a7aSWarner Loshas the last statement of a block. 15778e3e3a7aSWarner LoshIf it is really necessary to <b>return</b> in the middle of a block, 15788e3e3a7aSWarner Loshthen an explicit inner block can be used, 15798e3e3a7aSWarner Loshas in the idiom <code>do return end</code>, 15808e3e3a7aSWarner Loshbecause now <b>return</b> is the last statement in its (inner) block. 15818e3e3a7aSWarner Losh 15828e3e3a7aSWarner Losh 15838e3e3a7aSWarner Losh 15848e3e3a7aSWarner Losh 15858e3e3a7aSWarner Losh 15868e3e3a7aSWarner Losh<h3>3.3.5 – <a name="3.3.5">For Statement</a></h3> 15878e3e3a7aSWarner Losh 15888e3e3a7aSWarner Losh<p> 15898e3e3a7aSWarner Losh 15908e3e3a7aSWarner LoshThe <b>for</b> statement has two forms: 15918e3e3a7aSWarner Loshone numerical and one generic. 15928e3e3a7aSWarner Losh 15938e3e3a7aSWarner Losh 15948e3e3a7aSWarner Losh<p> 15958e3e3a7aSWarner LoshThe numerical <b>for</b> loop repeats a block of code while a 15968e3e3a7aSWarner Loshcontrol variable runs through an arithmetic progression. 15978e3e3a7aSWarner LoshIt has the following syntax: 15988e3e3a7aSWarner Losh 15998e3e3a7aSWarner Losh<pre> 16008e3e3a7aSWarner Losh stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> 16018e3e3a7aSWarner Losh</pre><p> 16028e3e3a7aSWarner LoshThe <em>block</em> is repeated for <em>name</em> starting at the value of 16038e3e3a7aSWarner Loshthe first <em>exp</em>, until it passes the second <em>exp</em> by steps of the 16048e3e3a7aSWarner Loshthird <em>exp</em>. 16058e3e3a7aSWarner LoshMore precisely, a <b>for</b> statement like 16068e3e3a7aSWarner Losh 16078e3e3a7aSWarner Losh<pre> 16088e3e3a7aSWarner Losh for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end 16098e3e3a7aSWarner Losh</pre><p> 16108e3e3a7aSWarner Loshis equivalent to the code: 16118e3e3a7aSWarner Losh 16128e3e3a7aSWarner Losh<pre> 16138e3e3a7aSWarner Losh do 16148e3e3a7aSWarner Losh local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>) 16158e3e3a7aSWarner Losh if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end 16168e3e3a7aSWarner Losh <em>var</em> = <em>var</em> - <em>step</em> 16178e3e3a7aSWarner Losh while true do 16188e3e3a7aSWarner Losh <em>var</em> = <em>var</em> + <em>step</em> 16198e3e3a7aSWarner Losh 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 16208e3e3a7aSWarner Losh break 16218e3e3a7aSWarner Losh end 16228e3e3a7aSWarner Losh local v = <em>var</em> 16238e3e3a7aSWarner Losh <em>block</em> 16248e3e3a7aSWarner Losh end 16258e3e3a7aSWarner Losh end 16268e3e3a7aSWarner Losh</pre> 16278e3e3a7aSWarner Losh 16288e3e3a7aSWarner Losh<p> 16298e3e3a7aSWarner LoshNote the following: 16308e3e3a7aSWarner Losh 16318e3e3a7aSWarner Losh<ul> 16328e3e3a7aSWarner Losh 16338e3e3a7aSWarner Losh<li> 16348e3e3a7aSWarner LoshAll three control expressions are evaluated only once, 16358e3e3a7aSWarner Loshbefore the loop starts. 16368e3e3a7aSWarner LoshThey must all result in numbers. 16378e3e3a7aSWarner Losh</li> 16388e3e3a7aSWarner Losh 16398e3e3a7aSWarner Losh<li> 16408e3e3a7aSWarner Losh<code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables. 16418e3e3a7aSWarner LoshThe names shown here are for explanatory purposes only. 16428e3e3a7aSWarner Losh</li> 16438e3e3a7aSWarner Losh 16448e3e3a7aSWarner Losh<li> 16458e3e3a7aSWarner LoshIf the third expression (the step) is absent, 16468e3e3a7aSWarner Loshthen a step of 1 is used. 16478e3e3a7aSWarner Losh</li> 16488e3e3a7aSWarner Losh 16498e3e3a7aSWarner Losh<li> 16508e3e3a7aSWarner LoshYou can use <b>break</b> and <b>goto</b> to exit a <b>for</b> loop. 16518e3e3a7aSWarner Losh</li> 16528e3e3a7aSWarner Losh 16538e3e3a7aSWarner Losh<li> 16548e3e3a7aSWarner LoshThe loop variable <code>v</code> is local to the loop body. 16558e3e3a7aSWarner LoshIf you need its value after the loop, 16568e3e3a7aSWarner Loshassign it to another variable before exiting the loop. 16578e3e3a7aSWarner Losh</li> 16588e3e3a7aSWarner Losh 16598e3e3a7aSWarner Losh</ul> 16608e3e3a7aSWarner Losh 16618e3e3a7aSWarner Losh<p> 16628e3e3a7aSWarner LoshThe generic <b>for</b> statement works over functions, 16638e3e3a7aSWarner Loshcalled <em>iterators</em>. 16648e3e3a7aSWarner LoshOn each iteration, the iterator function is called to produce a new value, 16658e3e3a7aSWarner Loshstopping when this new value is <b>nil</b>. 16668e3e3a7aSWarner LoshThe generic <b>for</b> loop has the following syntax: 16678e3e3a7aSWarner Losh 16688e3e3a7aSWarner Losh<pre> 16698e3e3a7aSWarner Losh stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> 16708e3e3a7aSWarner Losh namelist ::= Name {‘<b>,</b>’ Name} 16718e3e3a7aSWarner Losh</pre><p> 16728e3e3a7aSWarner LoshA <b>for</b> statement like 16738e3e3a7aSWarner Losh 16748e3e3a7aSWarner Losh<pre> 16758e3e3a7aSWarner Losh for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end 16768e3e3a7aSWarner Losh</pre><p> 16778e3e3a7aSWarner Loshis equivalent to the code: 16788e3e3a7aSWarner Losh 16798e3e3a7aSWarner Losh<pre> 16808e3e3a7aSWarner Losh do 16818e3e3a7aSWarner Losh local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em> 16828e3e3a7aSWarner Losh while true do 16838e3e3a7aSWarner Losh local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>) 16848e3e3a7aSWarner Losh if <em>var_1</em> == nil then break end 16858e3e3a7aSWarner Losh <em>var</em> = <em>var_1</em> 16868e3e3a7aSWarner Losh <em>block</em> 16878e3e3a7aSWarner Losh end 16888e3e3a7aSWarner Losh end 16898e3e3a7aSWarner Losh</pre><p> 16908e3e3a7aSWarner LoshNote the following: 16918e3e3a7aSWarner Losh 16928e3e3a7aSWarner Losh<ul> 16938e3e3a7aSWarner Losh 16948e3e3a7aSWarner Losh<li> 16958e3e3a7aSWarner Losh<code><em>explist</em></code> is evaluated only once. 16968e3e3a7aSWarner LoshIts results are an <em>iterator</em> function, 16978e3e3a7aSWarner Losha <em>state</em>, 16988e3e3a7aSWarner Loshand an initial value for the first <em>iterator variable</em>. 16998e3e3a7aSWarner Losh</li> 17008e3e3a7aSWarner Losh 17018e3e3a7aSWarner Losh<li> 17028e3e3a7aSWarner Losh<code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables. 17038e3e3a7aSWarner LoshThe names are here for explanatory purposes only. 17048e3e3a7aSWarner Losh</li> 17058e3e3a7aSWarner Losh 17068e3e3a7aSWarner Losh<li> 17078e3e3a7aSWarner LoshYou can use <b>break</b> to exit a <b>for</b> loop. 17088e3e3a7aSWarner Losh</li> 17098e3e3a7aSWarner Losh 17108e3e3a7aSWarner Losh<li> 17118e3e3a7aSWarner LoshThe loop variables <code><em>var_i</em></code> are local to the loop; 17128e3e3a7aSWarner Loshyou cannot use their values after the <b>for</b> ends. 17138e3e3a7aSWarner LoshIf you need these values, 17148e3e3a7aSWarner Loshthen assign them to other variables before breaking or exiting the loop. 17158e3e3a7aSWarner Losh</li> 17168e3e3a7aSWarner Losh 17178e3e3a7aSWarner Losh</ul> 17188e3e3a7aSWarner Losh 17198e3e3a7aSWarner Losh 17208e3e3a7aSWarner Losh 17218e3e3a7aSWarner Losh 17228e3e3a7aSWarner Losh<h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p> 17238e3e3a7aSWarner LoshTo allow possible side-effects, 17248e3e3a7aSWarner Loshfunction calls can be executed as statements: 17258e3e3a7aSWarner Losh 17268e3e3a7aSWarner Losh<pre> 17278e3e3a7aSWarner Losh stat ::= functioncall 17288e3e3a7aSWarner Losh</pre><p> 17298e3e3a7aSWarner LoshIn this case, all returned values are thrown away. 17308e3e3a7aSWarner LoshFunction calls are explained in <a href="#3.4.10">§3.4.10</a>. 17318e3e3a7aSWarner Losh 17328e3e3a7aSWarner Losh 17338e3e3a7aSWarner Losh 17348e3e3a7aSWarner Losh 17358e3e3a7aSWarner Losh 17368e3e3a7aSWarner Losh<h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p> 17378e3e3a7aSWarner LoshLocal variables can be declared anywhere inside a block. 17388e3e3a7aSWarner LoshThe declaration can include an initial assignment: 17398e3e3a7aSWarner Losh 17408e3e3a7aSWarner Losh<pre> 17418e3e3a7aSWarner Losh stat ::= <b>local</b> namelist [‘<b>=</b>’ explist] 17428e3e3a7aSWarner Losh</pre><p> 17438e3e3a7aSWarner LoshIf present, an initial assignment has the same semantics 17448e3e3a7aSWarner Loshof a multiple assignment (see <a href="#3.3.3">§3.3.3</a>). 17458e3e3a7aSWarner LoshOtherwise, all variables are initialized with <b>nil</b>. 17468e3e3a7aSWarner Losh 17478e3e3a7aSWarner Losh 17488e3e3a7aSWarner Losh<p> 17498e3e3a7aSWarner LoshA chunk is also a block (see <a href="#3.3.2">§3.3.2</a>), 17508e3e3a7aSWarner Loshand so local variables can be declared in a chunk outside any explicit block. 17518e3e3a7aSWarner Losh 17528e3e3a7aSWarner Losh 17538e3e3a7aSWarner Losh<p> 17548e3e3a7aSWarner LoshThe visibility rules for local variables are explained in <a href="#3.5">§3.5</a>. 17558e3e3a7aSWarner Losh 17568e3e3a7aSWarner Losh 17578e3e3a7aSWarner Losh 17588e3e3a7aSWarner Losh 17598e3e3a7aSWarner Losh 17608e3e3a7aSWarner Losh 17618e3e3a7aSWarner Losh 17628e3e3a7aSWarner Losh<h2>3.4 – <a name="3.4">Expressions</a></h2> 17638e3e3a7aSWarner Losh 17648e3e3a7aSWarner Losh<p> 17658e3e3a7aSWarner LoshThe basic expressions in Lua are the following: 17668e3e3a7aSWarner Losh 17678e3e3a7aSWarner Losh<pre> 17688e3e3a7aSWarner Losh exp ::= prefixexp 17698e3e3a7aSWarner Losh exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 17708e3e3a7aSWarner Losh exp ::= Numeral 17718e3e3a7aSWarner Losh exp ::= LiteralString 17728e3e3a7aSWarner Losh exp ::= functiondef 17738e3e3a7aSWarner Losh exp ::= tableconstructor 17748e3e3a7aSWarner Losh exp ::= ‘<b>...</b>’ 17758e3e3a7aSWarner Losh exp ::= exp binop exp 17768e3e3a7aSWarner Losh exp ::= unop exp 17778e3e3a7aSWarner Losh prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 17788e3e3a7aSWarner Losh</pre> 17798e3e3a7aSWarner Losh 17808e3e3a7aSWarner Losh<p> 17818e3e3a7aSWarner LoshNumerals and literal strings are explained in <a href="#3.1">§3.1</a>; 17828e3e3a7aSWarner Loshvariables are explained in <a href="#3.2">§3.2</a>; 17838e3e3a7aSWarner Loshfunction definitions are explained in <a href="#3.4.11">§3.4.11</a>; 17848e3e3a7aSWarner Loshfunction calls are explained in <a href="#3.4.10">§3.4.10</a>; 17858e3e3a7aSWarner Loshtable constructors are explained in <a href="#3.4.9">§3.4.9</a>. 17868e3e3a7aSWarner LoshVararg expressions, 17878e3e3a7aSWarner Loshdenoted by three dots ('<code>...</code>'), can only be used when 17888e3e3a7aSWarner Loshdirectly inside a vararg function; 17898e3e3a7aSWarner Loshthey are explained in <a href="#3.4.11">§3.4.11</a>. 17908e3e3a7aSWarner Losh 17918e3e3a7aSWarner Losh 17928e3e3a7aSWarner Losh<p> 17938e3e3a7aSWarner LoshBinary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), 17948e3e3a7aSWarner Loshbitwise operators (see <a href="#3.4.2">§3.4.2</a>), 17958e3e3a7aSWarner Loshrelational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>), 17968e3e3a7aSWarner Loshand the concatenation operator (see <a href="#3.4.6">§3.4.6</a>). 17978e3e3a7aSWarner LoshUnary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), 17988e3e3a7aSWarner Loshthe unary bitwise NOT (see <a href="#3.4.2">§3.4.2</a>), 17998e3e3a7aSWarner Loshthe unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), 18008e3e3a7aSWarner Loshand the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). 18018e3e3a7aSWarner Losh 18028e3e3a7aSWarner Losh 18038e3e3a7aSWarner Losh<p> 18048e3e3a7aSWarner LoshBoth function calls and vararg expressions can result in multiple values. 18058e3e3a7aSWarner LoshIf a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>), 18068e3e3a7aSWarner Loshthen its return list is adjusted to zero elements, 18078e3e3a7aSWarner Loshthus discarding all returned values. 18088e3e3a7aSWarner LoshIf an expression is used as the last (or the only) element 18098e3e3a7aSWarner Loshof a list of expressions, 18108e3e3a7aSWarner Loshthen no adjustment is made 18118e3e3a7aSWarner Losh(unless the expression is enclosed in parentheses). 18128e3e3a7aSWarner LoshIn all other contexts, 18138e3e3a7aSWarner LoshLua adjusts the result list to one element, 18148e3e3a7aSWarner Losheither discarding all values except the first one 18158e3e3a7aSWarner Loshor adding a single <b>nil</b> if there are no values. 18168e3e3a7aSWarner Losh 18178e3e3a7aSWarner Losh 18188e3e3a7aSWarner Losh<p> 18198e3e3a7aSWarner LoshHere are some examples: 18208e3e3a7aSWarner Losh 18218e3e3a7aSWarner Losh<pre> 18228e3e3a7aSWarner Losh f() -- adjusted to 0 results 18238e3e3a7aSWarner Losh g(f(), x) -- f() is adjusted to 1 result 18248e3e3a7aSWarner Losh g(x, f()) -- g gets x plus all results from f() 18258e3e3a7aSWarner Losh a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) 1826*e112e9d2SKyle Evans a,b = ... -- a gets the first vararg argument, b gets 18278e3e3a7aSWarner Losh -- the second (both a and b can get nil if there 1828*e112e9d2SKyle Evans -- is no corresponding vararg argument) 18298e3e3a7aSWarner Losh 18308e3e3a7aSWarner Losh a,b,c = x, f() -- f() is adjusted to 2 results 18318e3e3a7aSWarner Losh a,b,c = f() -- f() is adjusted to 3 results 18328e3e3a7aSWarner Losh return f() -- returns all results from f() 1833*e112e9d2SKyle Evans return ... -- returns all received vararg arguments 18348e3e3a7aSWarner Losh return x,y,f() -- returns x, y, and all results from f() 18358e3e3a7aSWarner Losh {f()} -- creates a list with all results from f() 1836*e112e9d2SKyle Evans {...} -- creates a list with all vararg arguments 18378e3e3a7aSWarner Losh {f(), nil} -- f() is adjusted to 1 result 18388e3e3a7aSWarner Losh</pre> 18398e3e3a7aSWarner Losh 18408e3e3a7aSWarner Losh<p> 18418e3e3a7aSWarner LoshAny expression enclosed in parentheses always results in only one value. 18428e3e3a7aSWarner LoshThus, 18438e3e3a7aSWarner Losh<code>(f(x,y,z))</code> is always a single value, 18448e3e3a7aSWarner Losheven if <code>f</code> returns several values. 18458e3e3a7aSWarner Losh(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> 18468e3e3a7aSWarner Loshor <b>nil</b> if <code>f</code> does not return any values.) 18478e3e3a7aSWarner Losh 18488e3e3a7aSWarner Losh 18498e3e3a7aSWarner Losh 18508e3e3a7aSWarner Losh<h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p> 18518e3e3a7aSWarner LoshLua supports the following arithmetic operators: 18528e3e3a7aSWarner Losh 18538e3e3a7aSWarner Losh<ul> 18548e3e3a7aSWarner Losh<li><b><code>+</code>: </b>addition</li> 18558e3e3a7aSWarner Losh<li><b><code>-</code>: </b>subtraction</li> 18568e3e3a7aSWarner Losh<li><b><code>*</code>: </b>multiplication</li> 18578e3e3a7aSWarner Losh<li><b><code>/</code>: </b>float division</li> 18588e3e3a7aSWarner Losh<li><b><code>//</code>: </b>floor division</li> 18598e3e3a7aSWarner Losh<li><b><code>%</code>: </b>modulo</li> 18608e3e3a7aSWarner Losh<li><b><code>^</code>: </b>exponentiation</li> 18618e3e3a7aSWarner Losh<li><b><code>-</code>: </b>unary minus</li> 18628e3e3a7aSWarner Losh</ul> 18638e3e3a7aSWarner Losh 18648e3e3a7aSWarner Losh<p> 18658e3e3a7aSWarner LoshWith the exception of exponentiation and float division, 18668e3e3a7aSWarner Loshthe arithmetic operators work as follows: 18678e3e3a7aSWarner LoshIf both operands are integers, 18688e3e3a7aSWarner Loshthe operation is performed over integers and the result is an integer. 18698e3e3a7aSWarner LoshOtherwise, if both operands are numbers 18708e3e3a7aSWarner Loshor strings that can be converted to 18718e3e3a7aSWarner Loshnumbers (see <a href="#3.4.3">§3.4.3</a>), 18728e3e3a7aSWarner Loshthen they are converted to floats, 18738e3e3a7aSWarner Loshthe operation is performed following the usual rules 18748e3e3a7aSWarner Loshfor floating-point arithmetic 18758e3e3a7aSWarner Losh(usually the IEEE 754 standard), 18768e3e3a7aSWarner Loshand the result is a float. 18778e3e3a7aSWarner Losh 18788e3e3a7aSWarner Losh 18798e3e3a7aSWarner Losh<p> 18808e3e3a7aSWarner LoshExponentiation and float division (<code>/</code>) 18818e3e3a7aSWarner Loshalways convert their operands to floats 18828e3e3a7aSWarner Loshand the result is always a float. 18838e3e3a7aSWarner LoshExponentiation uses the ISO C function <code>pow</code>, 18848e3e3a7aSWarner Loshso that it works for non-integer exponents too. 18858e3e3a7aSWarner Losh 18868e3e3a7aSWarner Losh 18878e3e3a7aSWarner Losh<p> 18888e3e3a7aSWarner LoshFloor division (<code>//</code>) is a division 18898e3e3a7aSWarner Loshthat rounds the quotient towards minus infinity, 18908e3e3a7aSWarner Loshthat is, the floor of the division of its operands. 18918e3e3a7aSWarner Losh 18928e3e3a7aSWarner Losh 18938e3e3a7aSWarner Losh<p> 18948e3e3a7aSWarner LoshModulo is defined as the remainder of a division 18958e3e3a7aSWarner Loshthat rounds the quotient towards minus infinity (floor division). 18968e3e3a7aSWarner Losh 18978e3e3a7aSWarner Losh 18988e3e3a7aSWarner Losh<p> 18998e3e3a7aSWarner LoshIn case of overflows in integer arithmetic, 19008e3e3a7aSWarner Loshall operations <em>wrap around</em>, 19018e3e3a7aSWarner Loshaccording to the usual rules of two-complement arithmetic. 19028e3e3a7aSWarner Losh(In other words, 19038e3e3a7aSWarner Loshthey return the unique representable integer 19048e3e3a7aSWarner Loshthat is equal modulo <em>2<sup>64</sup></em> to the mathematical result.) 19058e3e3a7aSWarner Losh 19068e3e3a7aSWarner Losh 19078e3e3a7aSWarner Losh 19088e3e3a7aSWarner Losh<h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p> 19098e3e3a7aSWarner LoshLua supports the following bitwise operators: 19108e3e3a7aSWarner Losh 19118e3e3a7aSWarner Losh<ul> 19128e3e3a7aSWarner Losh<li><b><code>&</code>: </b>bitwise AND</li> 19138e3e3a7aSWarner Losh<li><b><code>|</code>: </b>bitwise OR</li> 19148e3e3a7aSWarner Losh<li><b><code>~</code>: </b>bitwise exclusive OR</li> 19158e3e3a7aSWarner Losh<li><b><code>>></code>: </b>right shift</li> 19168e3e3a7aSWarner Losh<li><b><code><<</code>: </b>left shift</li> 19178e3e3a7aSWarner Losh<li><b><code>~</code>: </b>unary bitwise NOT</li> 19188e3e3a7aSWarner Losh</ul> 19198e3e3a7aSWarner Losh 19208e3e3a7aSWarner Losh<p> 19218e3e3a7aSWarner LoshAll bitwise operations convert its operands to integers 19228e3e3a7aSWarner Losh(see <a href="#3.4.3">§3.4.3</a>), 19238e3e3a7aSWarner Loshoperate on all bits of those integers, 19248e3e3a7aSWarner Loshand result in an integer. 19258e3e3a7aSWarner Losh 19268e3e3a7aSWarner Losh 19278e3e3a7aSWarner Losh<p> 19288e3e3a7aSWarner LoshBoth right and left shifts fill the vacant bits with zeros. 19298e3e3a7aSWarner LoshNegative displacements shift to the other direction; 19308e3e3a7aSWarner Loshdisplacements with absolute values equal to or higher than 19318e3e3a7aSWarner Loshthe number of bits in an integer 19328e3e3a7aSWarner Loshresult in zero (as all bits are shifted out). 19338e3e3a7aSWarner Losh 19348e3e3a7aSWarner Losh 19358e3e3a7aSWarner Losh 19368e3e3a7aSWarner Losh 19378e3e3a7aSWarner Losh 19388e3e3a7aSWarner Losh<h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p> 19398e3e3a7aSWarner LoshLua provides some automatic conversions between some 19408e3e3a7aSWarner Loshtypes and representations at run time. 19418e3e3a7aSWarner LoshBitwise operators always convert float operands to integers. 19428e3e3a7aSWarner LoshExponentiation and float division 19438e3e3a7aSWarner Loshalways convert integer operands to floats. 19448e3e3a7aSWarner LoshAll other arithmetic operations applied to mixed numbers 19458e3e3a7aSWarner Losh(integers and floats) convert the integer operand to a float; 19468e3e3a7aSWarner Loshthis is called the <em>usual rule</em>. 19478e3e3a7aSWarner LoshThe C API also converts both integers to floats and 19488e3e3a7aSWarner Loshfloats to integers, as needed. 19498e3e3a7aSWarner LoshMoreover, string concatenation accepts numbers as arguments, 19508e3e3a7aSWarner Loshbesides strings. 19518e3e3a7aSWarner Losh 19528e3e3a7aSWarner Losh 19538e3e3a7aSWarner Losh<p> 19548e3e3a7aSWarner LoshLua also converts strings to numbers, 19558e3e3a7aSWarner Loshwhenever a number is expected. 19568e3e3a7aSWarner Losh 19578e3e3a7aSWarner Losh 19588e3e3a7aSWarner Losh<p> 19598e3e3a7aSWarner LoshIn a conversion from integer to float, 19608e3e3a7aSWarner Loshif the integer value has an exact representation as a float, 19618e3e3a7aSWarner Loshthat is the result. 19628e3e3a7aSWarner LoshOtherwise, 19638e3e3a7aSWarner Loshthe conversion gets the nearest higher or 19648e3e3a7aSWarner Loshthe nearest lower representable value. 19658e3e3a7aSWarner LoshThis kind of conversion never fails. 19668e3e3a7aSWarner Losh 19678e3e3a7aSWarner Losh 19688e3e3a7aSWarner Losh<p> 19698e3e3a7aSWarner LoshThe conversion from float to integer 19708e3e3a7aSWarner Loshchecks whether the float has an exact representation as an integer 19718e3e3a7aSWarner Losh(that is, the float has an integral value and 19728e3e3a7aSWarner Loshit is in the range of integer representation). 19738e3e3a7aSWarner LoshIf it does, that representation is the result. 19748e3e3a7aSWarner LoshOtherwise, the conversion fails. 19758e3e3a7aSWarner Losh 19768e3e3a7aSWarner Losh 19778e3e3a7aSWarner Losh<p> 19788e3e3a7aSWarner LoshThe conversion from strings to numbers goes as follows: 19798e3e3a7aSWarner LoshFirst, the string is converted to an integer or a float, 19808e3e3a7aSWarner Loshfollowing its syntax and the rules of the Lua lexer. 19818e3e3a7aSWarner Losh(The string may have also leading and trailing spaces and a sign.) 19828e3e3a7aSWarner LoshThen, the resulting number (float or integer) 19838e3e3a7aSWarner Loshis converted to the type (float or integer) required by the context 19848e3e3a7aSWarner Losh(e.g., the operation that forced the conversion). 19858e3e3a7aSWarner Losh 19868e3e3a7aSWarner Losh 19878e3e3a7aSWarner Losh<p> 19888e3e3a7aSWarner LoshAll conversions from strings to numbers 19898e3e3a7aSWarner Loshaccept both a dot and the current locale mark 19908e3e3a7aSWarner Loshas the radix character. 19918e3e3a7aSWarner Losh(The Lua lexer, however, accepts only a dot.) 19928e3e3a7aSWarner Losh 19938e3e3a7aSWarner Losh 19948e3e3a7aSWarner Losh<p> 19958e3e3a7aSWarner LoshThe conversion from numbers to strings uses a 19968e3e3a7aSWarner Loshnon-specified human-readable format. 19978e3e3a7aSWarner LoshFor complete control over how numbers are converted to strings, 19988e3e3a7aSWarner Loshuse the <code>format</code> function from the string library 19998e3e3a7aSWarner Losh(see <a href="#pdf-string.format"><code>string.format</code></a>). 20008e3e3a7aSWarner Losh 20018e3e3a7aSWarner Losh 20028e3e3a7aSWarner Losh 20038e3e3a7aSWarner Losh 20048e3e3a7aSWarner Losh 20058e3e3a7aSWarner Losh<h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p> 20068e3e3a7aSWarner LoshLua supports the following relational operators: 20078e3e3a7aSWarner Losh 20088e3e3a7aSWarner Losh<ul> 20098e3e3a7aSWarner Losh<li><b><code>==</code>: </b>equality</li> 20108e3e3a7aSWarner Losh<li><b><code>~=</code>: </b>inequality</li> 20118e3e3a7aSWarner Losh<li><b><code><</code>: </b>less than</li> 20128e3e3a7aSWarner Losh<li><b><code>></code>: </b>greater than</li> 20138e3e3a7aSWarner Losh<li><b><code><=</code>: </b>less or equal</li> 20148e3e3a7aSWarner Losh<li><b><code>>=</code>: </b>greater or equal</li> 20158e3e3a7aSWarner Losh</ul><p> 20168e3e3a7aSWarner LoshThese operators always result in <b>false</b> or <b>true</b>. 20178e3e3a7aSWarner Losh 20188e3e3a7aSWarner Losh 20198e3e3a7aSWarner Losh<p> 20208e3e3a7aSWarner LoshEquality (<code>==</code>) first compares the type of its operands. 20218e3e3a7aSWarner LoshIf the types are different, then the result is <b>false</b>. 20228e3e3a7aSWarner LoshOtherwise, the values of the operands are compared. 20238e3e3a7aSWarner LoshStrings are compared in the obvious way. 20248e3e3a7aSWarner LoshNumbers are equal if they denote the same mathematical value. 20258e3e3a7aSWarner Losh 20268e3e3a7aSWarner Losh 20278e3e3a7aSWarner Losh<p> 20288e3e3a7aSWarner LoshTables, userdata, and threads 20298e3e3a7aSWarner Loshare compared by reference: 20308e3e3a7aSWarner Loshtwo objects are considered equal only if they are the same object. 20318e3e3a7aSWarner LoshEvery time you create a new object 20328e3e3a7aSWarner Losh(a table, userdata, or thread), 20338e3e3a7aSWarner Loshthis new object is different from any previously existing object. 2034*e112e9d2SKyle EvansA closure is always equal to itself. 20358e3e3a7aSWarner LoshClosures with any detectable difference 20368e3e3a7aSWarner Losh(different behavior, different definition) are always different. 2037*e112e9d2SKyle EvansClosures created at different times but with no detectable differences 2038*e112e9d2SKyle Evansmay be classified as equal or not 2039*e112e9d2SKyle Evans(depending on internal caching details). 20408e3e3a7aSWarner Losh 20418e3e3a7aSWarner Losh 20428e3e3a7aSWarner Losh<p> 20438e3e3a7aSWarner LoshYou can change the way that Lua compares tables and userdata 20448e3e3a7aSWarner Loshby using the "eq" metamethod (see <a href="#2.4">§2.4</a>). 20458e3e3a7aSWarner Losh 20468e3e3a7aSWarner Losh 20478e3e3a7aSWarner Losh<p> 20488e3e3a7aSWarner LoshEquality comparisons do not convert strings to numbers 20498e3e3a7aSWarner Loshor vice versa. 20508e3e3a7aSWarner LoshThus, <code>"0"==0</code> evaluates to <b>false</b>, 20518e3e3a7aSWarner Loshand <code>t[0]</code> and <code>t["0"]</code> denote different 20528e3e3a7aSWarner Loshentries in a table. 20538e3e3a7aSWarner Losh 20548e3e3a7aSWarner Losh 20558e3e3a7aSWarner Losh<p> 20568e3e3a7aSWarner LoshThe operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 20578e3e3a7aSWarner Losh 20588e3e3a7aSWarner Losh 20598e3e3a7aSWarner Losh<p> 20608e3e3a7aSWarner LoshThe order operators work as follows. 20618e3e3a7aSWarner LoshIf both arguments are numbers, 20628e3e3a7aSWarner Loshthen they are compared according to their mathematical values 20638e3e3a7aSWarner Losh(regardless of their subtypes). 20648e3e3a7aSWarner LoshOtherwise, if both arguments are strings, 20658e3e3a7aSWarner Loshthen their values are compared according to the current locale. 20668e3e3a7aSWarner LoshOtherwise, Lua tries to call the "lt" or the "le" 20678e3e3a7aSWarner Loshmetamethod (see <a href="#2.4">§2.4</a>). 20688e3e3a7aSWarner LoshA comparison <code>a > b</code> is translated to <code>b < a</code> 20698e3e3a7aSWarner Loshand <code>a >= b</code> is translated to <code>b <= a</code>. 20708e3e3a7aSWarner Losh 20718e3e3a7aSWarner Losh 20728e3e3a7aSWarner Losh<p> 20738e3e3a7aSWarner LoshFollowing the IEEE 754 standard, 20748e3e3a7aSWarner LoshNaN is considered neither smaller than, 20758e3e3a7aSWarner Loshnor equal to, nor greater than any value (including itself). 20768e3e3a7aSWarner Losh 20778e3e3a7aSWarner Losh 20788e3e3a7aSWarner Losh 20798e3e3a7aSWarner Losh 20808e3e3a7aSWarner Losh 20818e3e3a7aSWarner Losh<h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p> 20828e3e3a7aSWarner LoshThe logical operators in Lua are 20838e3e3a7aSWarner Losh<b>and</b>, <b>or</b>, and <b>not</b>. 20848e3e3a7aSWarner LoshLike the control structures (see <a href="#3.3.4">§3.3.4</a>), 20858e3e3a7aSWarner Loshall logical operators consider both <b>false</b> and <b>nil</b> as false 20868e3e3a7aSWarner Loshand anything else as true. 20878e3e3a7aSWarner Losh 20888e3e3a7aSWarner Losh 20898e3e3a7aSWarner Losh<p> 20908e3e3a7aSWarner LoshThe negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 20918e3e3a7aSWarner LoshThe conjunction operator <b>and</b> returns its first argument 20928e3e3a7aSWarner Loshif this value is <b>false</b> or <b>nil</b>; 20938e3e3a7aSWarner Loshotherwise, <b>and</b> returns its second argument. 20948e3e3a7aSWarner LoshThe disjunction operator <b>or</b> returns its first argument 20958e3e3a7aSWarner Loshif this value is different from <b>nil</b> and <b>false</b>; 20968e3e3a7aSWarner Loshotherwise, <b>or</b> returns its second argument. 20978e3e3a7aSWarner LoshBoth <b>and</b> and <b>or</b> use short-circuit evaluation; 20988e3e3a7aSWarner Loshthat is, 20998e3e3a7aSWarner Loshthe second operand is evaluated only if necessary. 21008e3e3a7aSWarner LoshHere are some examples: 21018e3e3a7aSWarner Losh 21028e3e3a7aSWarner Losh<pre> 21038e3e3a7aSWarner Losh 10 or 20 --> 10 21048e3e3a7aSWarner Losh 10 or error() --> 10 21058e3e3a7aSWarner Losh nil or "a" --> "a" 21068e3e3a7aSWarner Losh nil and 10 --> nil 21078e3e3a7aSWarner Losh false and error() --> false 21088e3e3a7aSWarner Losh false and nil --> false 21098e3e3a7aSWarner Losh false or nil --> nil 21108e3e3a7aSWarner Losh 10 and 20 --> 20 21118e3e3a7aSWarner Losh</pre><p> 21128e3e3a7aSWarner Losh(In this manual, 21138e3e3a7aSWarner Losh<code>--></code> indicates the result of the preceding expression.) 21148e3e3a7aSWarner Losh 21158e3e3a7aSWarner Losh 21168e3e3a7aSWarner Losh 21178e3e3a7aSWarner Losh 21188e3e3a7aSWarner Losh 21198e3e3a7aSWarner Losh<h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p> 21208e3e3a7aSWarner LoshThe string concatenation operator in Lua is 21218e3e3a7aSWarner Loshdenoted by two dots ('<code>..</code>'). 21228e3e3a7aSWarner LoshIf both operands are strings or numbers, then they are converted to 21238e3e3a7aSWarner Loshstrings according to the rules described in <a href="#3.4.3">§3.4.3</a>. 21248e3e3a7aSWarner LoshOtherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). 21258e3e3a7aSWarner Losh 21268e3e3a7aSWarner Losh 21278e3e3a7aSWarner Losh 21288e3e3a7aSWarner Losh 21298e3e3a7aSWarner Losh 21308e3e3a7aSWarner Losh<h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3> 21318e3e3a7aSWarner Losh 21328e3e3a7aSWarner Losh<p> 21338e3e3a7aSWarner LoshThe length operator is denoted by the unary prefix operator <code>#</code>. 21348e3e3a7aSWarner Losh 21358e3e3a7aSWarner Losh 21368e3e3a7aSWarner Losh<p> 21378e3e3a7aSWarner LoshThe length of a string is its number of bytes 21388e3e3a7aSWarner Losh(that is, the usual meaning of string length when each 21398e3e3a7aSWarner Loshcharacter is one byte). 21408e3e3a7aSWarner Losh 21418e3e3a7aSWarner Losh 21428e3e3a7aSWarner Losh<p> 21438e3e3a7aSWarner LoshThe length operator applied on a table 21448e3e3a7aSWarner Loshreturns a border in that table. 21458e3e3a7aSWarner LoshA <em>border</em> in a table <code>t</code> is any natural number 21468e3e3a7aSWarner Loshthat satisfies the following condition: 21478e3e3a7aSWarner Losh 21488e3e3a7aSWarner Losh<pre> 21498e3e3a7aSWarner Losh (border == 0 or t[border] ~= nil) and t[border + 1] == nil 21508e3e3a7aSWarner Losh</pre><p> 21518e3e3a7aSWarner LoshIn words, 21528e3e3a7aSWarner Losha border is any (natural) index in a table 21538e3e3a7aSWarner Loshwhere a non-nil value is followed by a nil value 21548e3e3a7aSWarner Losh(or zero, when index 1 is nil). 21558e3e3a7aSWarner Losh 21568e3e3a7aSWarner Losh 21578e3e3a7aSWarner Losh<p> 21588e3e3a7aSWarner LoshA table with exactly one border is called a <em>sequence</em>. 21598e3e3a7aSWarner LoshFor instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence, 21608e3e3a7aSWarner Loshas it has only one border (5). 21618e3e3a7aSWarner LoshThe table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5), 21628e3e3a7aSWarner Loshand therefore it is not a sequence. 21638e3e3a7aSWarner LoshThe table <code>{nil, 20, 30, nil, nil, 60, nil}</code> 21648e3e3a7aSWarner Loshhas three borders (0, 3, and 6), 21658e3e3a7aSWarner Loshso it is not a sequence, too. 21668e3e3a7aSWarner LoshThe table <code>{}</code> is a sequence with border 0. 21678e3e3a7aSWarner LoshNote that non-natural keys do not interfere 21688e3e3a7aSWarner Loshwith whether a table is a sequence. 21698e3e3a7aSWarner Losh 21708e3e3a7aSWarner Losh 21718e3e3a7aSWarner Losh<p> 21728e3e3a7aSWarner LoshWhen <code>t</code> is a sequence, 21738e3e3a7aSWarner Losh<code>#t</code> returns its only border, 21748e3e3a7aSWarner Loshwhich corresponds to the intuitive notion of the length of the sequence. 21758e3e3a7aSWarner LoshWhen <code>t</code> is not a sequence, 21768e3e3a7aSWarner Losh<code>#t</code> can return any of its borders. 21778e3e3a7aSWarner Losh(The exact one depends on details of 21788e3e3a7aSWarner Loshthe internal representation of the table, 21798e3e3a7aSWarner Loshwhich in turn can depend on how the table was populated and 21808e3e3a7aSWarner Loshthe memory addresses of its non-numeric keys.) 21818e3e3a7aSWarner Losh 21828e3e3a7aSWarner Losh 21838e3e3a7aSWarner Losh<p> 21848e3e3a7aSWarner LoshThe computation of the length of a table 21858e3e3a7aSWarner Loshhas a guaranteed worst time of <em>O(log n)</em>, 21868e3e3a7aSWarner Loshwhere <em>n</em> is the largest natural key in the table. 21878e3e3a7aSWarner Losh 21888e3e3a7aSWarner Losh 21898e3e3a7aSWarner Losh<p> 21908e3e3a7aSWarner LoshA program can modify the behavior of the length operator for 21918e3e3a7aSWarner Loshany value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>). 21928e3e3a7aSWarner Losh 21938e3e3a7aSWarner Losh 21948e3e3a7aSWarner Losh 21958e3e3a7aSWarner Losh 21968e3e3a7aSWarner Losh 21978e3e3a7aSWarner Losh<h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p> 21988e3e3a7aSWarner LoshOperator precedence in Lua follows the table below, 21998e3e3a7aSWarner Loshfrom lower to higher priority: 22008e3e3a7aSWarner Losh 22018e3e3a7aSWarner Losh<pre> 22028e3e3a7aSWarner Losh or 22038e3e3a7aSWarner Losh and 22048e3e3a7aSWarner Losh < > <= >= ~= == 22058e3e3a7aSWarner Losh | 22068e3e3a7aSWarner Losh ~ 22078e3e3a7aSWarner Losh & 22088e3e3a7aSWarner Losh << >> 22098e3e3a7aSWarner Losh .. 22108e3e3a7aSWarner Losh + - 22118e3e3a7aSWarner Losh * / // % 22128e3e3a7aSWarner Losh unary operators (not # - ~) 22138e3e3a7aSWarner Losh ^ 22148e3e3a7aSWarner Losh</pre><p> 22158e3e3a7aSWarner LoshAs usual, 22168e3e3a7aSWarner Loshyou can use parentheses to change the precedences of an expression. 22178e3e3a7aSWarner LoshThe concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 22188e3e3a7aSWarner Loshoperators are right associative. 22198e3e3a7aSWarner LoshAll other binary operators are left associative. 22208e3e3a7aSWarner Losh 22218e3e3a7aSWarner Losh 22228e3e3a7aSWarner Losh 22238e3e3a7aSWarner Losh 22248e3e3a7aSWarner Losh 22258e3e3a7aSWarner Losh<h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p> 22268e3e3a7aSWarner LoshTable constructors are expressions that create tables. 22278e3e3a7aSWarner LoshEvery time a constructor is evaluated, a new table is created. 22288e3e3a7aSWarner LoshA constructor can be used to create an empty table 22298e3e3a7aSWarner Loshor to create a table and initialize some of its fields. 22308e3e3a7aSWarner LoshThe general syntax for constructors is 22318e3e3a7aSWarner Losh 22328e3e3a7aSWarner Losh<pre> 22338e3e3a7aSWarner Losh tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 22348e3e3a7aSWarner Losh fieldlist ::= field {fieldsep field} [fieldsep] 22358e3e3a7aSWarner Losh field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 22368e3e3a7aSWarner Losh fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 22378e3e3a7aSWarner Losh</pre> 22388e3e3a7aSWarner Losh 22398e3e3a7aSWarner Losh<p> 22408e3e3a7aSWarner LoshEach field of the form <code>[exp1] = exp2</code> adds to the new table an entry 22418e3e3a7aSWarner Loshwith key <code>exp1</code> and value <code>exp2</code>. 22428e3e3a7aSWarner LoshA field of the form <code>name = exp</code> is equivalent to 22438e3e3a7aSWarner Losh<code>["name"] = exp</code>. 22448e3e3a7aSWarner LoshFinally, fields of the form <code>exp</code> are equivalent to 22458e3e3a7aSWarner Losh<code>[i] = exp</code>, where <code>i</code> are consecutive integers 22468e3e3a7aSWarner Loshstarting with 1. 22478e3e3a7aSWarner LoshFields in the other formats do not affect this counting. 22488e3e3a7aSWarner LoshFor example, 22498e3e3a7aSWarner Losh 22508e3e3a7aSWarner Losh<pre> 22518e3e3a7aSWarner Losh a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 22528e3e3a7aSWarner Losh</pre><p> 22538e3e3a7aSWarner Loshis equivalent to 22548e3e3a7aSWarner Losh 22558e3e3a7aSWarner Losh<pre> 22568e3e3a7aSWarner Losh do 22578e3e3a7aSWarner Losh local t = {} 22588e3e3a7aSWarner Losh t[f(1)] = g 22598e3e3a7aSWarner Losh t[1] = "x" -- 1st exp 22608e3e3a7aSWarner Losh t[2] = "y" -- 2nd exp 22618e3e3a7aSWarner Losh t.x = 1 -- t["x"] = 1 22628e3e3a7aSWarner Losh t[3] = f(x) -- 3rd exp 22638e3e3a7aSWarner Losh t[30] = 23 22648e3e3a7aSWarner Losh t[4] = 45 -- 4th exp 22658e3e3a7aSWarner Losh a = t 22668e3e3a7aSWarner Losh end 22678e3e3a7aSWarner Losh</pre> 22688e3e3a7aSWarner Losh 22698e3e3a7aSWarner Losh<p> 22708e3e3a7aSWarner LoshThe order of the assignments in a constructor is undefined. 22718e3e3a7aSWarner Losh(This order would be relevant only when there are repeated keys.) 22728e3e3a7aSWarner Losh 22738e3e3a7aSWarner Losh 22748e3e3a7aSWarner Losh<p> 22758e3e3a7aSWarner LoshIf the last field in the list has the form <code>exp</code> 22768e3e3a7aSWarner Loshand the expression is a function call or a vararg expression, 22778e3e3a7aSWarner Loshthen all values returned by this expression enter the list consecutively 22788e3e3a7aSWarner Losh(see <a href="#3.4.10">§3.4.10</a>). 22798e3e3a7aSWarner Losh 22808e3e3a7aSWarner Losh 22818e3e3a7aSWarner Losh<p> 22828e3e3a7aSWarner LoshThe field list can have an optional trailing separator, 22838e3e3a7aSWarner Loshas a convenience for machine-generated code. 22848e3e3a7aSWarner Losh 22858e3e3a7aSWarner Losh 22868e3e3a7aSWarner Losh 22878e3e3a7aSWarner Losh 22888e3e3a7aSWarner Losh 22898e3e3a7aSWarner Losh<h3>3.4.10 – <a name="3.4.10">Function Calls</a></h3><p> 22908e3e3a7aSWarner LoshA function call in Lua has the following syntax: 22918e3e3a7aSWarner Losh 22928e3e3a7aSWarner Losh<pre> 22938e3e3a7aSWarner Losh functioncall ::= prefixexp args 22948e3e3a7aSWarner Losh</pre><p> 22958e3e3a7aSWarner LoshIn a function call, 22968e3e3a7aSWarner Loshfirst prefixexp and args are evaluated. 22978e3e3a7aSWarner LoshIf the value of prefixexp has type <em>function</em>, 22988e3e3a7aSWarner Loshthen this function is called 22998e3e3a7aSWarner Loshwith the given arguments. 23008e3e3a7aSWarner LoshOtherwise, the prefixexp "call" metamethod is called, 2301*e112e9d2SKyle Evanshaving as first argument the value of prefixexp, 23028e3e3a7aSWarner Loshfollowed by the original call arguments 23038e3e3a7aSWarner Losh(see <a href="#2.4">§2.4</a>). 23048e3e3a7aSWarner Losh 23058e3e3a7aSWarner Losh 23068e3e3a7aSWarner Losh<p> 23078e3e3a7aSWarner LoshThe form 23088e3e3a7aSWarner Losh 23098e3e3a7aSWarner Losh<pre> 23108e3e3a7aSWarner Losh functioncall ::= prefixexp ‘<b>:</b>’ Name args 23118e3e3a7aSWarner Losh</pre><p> 23128e3e3a7aSWarner Loshcan be used to call "methods". 23138e3e3a7aSWarner LoshA call <code>v:name(<em>args</em>)</code> 23148e3e3a7aSWarner Loshis syntactic sugar for <code>v.name(v,<em>args</em>)</code>, 23158e3e3a7aSWarner Loshexcept that <code>v</code> is evaluated only once. 23168e3e3a7aSWarner Losh 23178e3e3a7aSWarner Losh 23188e3e3a7aSWarner Losh<p> 23198e3e3a7aSWarner LoshArguments have the following syntax: 23208e3e3a7aSWarner Losh 23218e3e3a7aSWarner Losh<pre> 23228e3e3a7aSWarner Losh args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ 23238e3e3a7aSWarner Losh args ::= tableconstructor 23248e3e3a7aSWarner Losh args ::= LiteralString 23258e3e3a7aSWarner Losh</pre><p> 23268e3e3a7aSWarner LoshAll argument expressions are evaluated before the call. 23278e3e3a7aSWarner LoshA call of the form <code>f{<em>fields</em>}</code> is 23288e3e3a7aSWarner Loshsyntactic sugar for <code>f({<em>fields</em>})</code>; 23298e3e3a7aSWarner Loshthat is, the argument list is a single new table. 23308e3e3a7aSWarner LoshA call of the form <code>f'<em>string</em>'</code> 23318e3e3a7aSWarner Losh(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 23328e3e3a7aSWarner Loshis syntactic sugar for <code>f('<em>string</em>')</code>; 23338e3e3a7aSWarner Loshthat is, the argument list is a single literal string. 23348e3e3a7aSWarner Losh 23358e3e3a7aSWarner Losh 23368e3e3a7aSWarner Losh<p> 23378e3e3a7aSWarner LoshA call of the form <code>return <em>functioncall</em></code> is called 23388e3e3a7aSWarner Losha <em>tail call</em>. 23398e3e3a7aSWarner LoshLua implements <em>proper tail calls</em> 23408e3e3a7aSWarner Losh(or <em>proper tail recursion</em>): 23418e3e3a7aSWarner Loshin a tail call, 23428e3e3a7aSWarner Loshthe called function reuses the stack entry of the calling function. 23438e3e3a7aSWarner LoshTherefore, there is no limit on the number of nested tail calls that 23448e3e3a7aSWarner Losha program can execute. 23458e3e3a7aSWarner LoshHowever, a tail call erases any debug information about the 23468e3e3a7aSWarner Loshcalling function. 23478e3e3a7aSWarner LoshNote that a tail call only happens with a particular syntax, 23488e3e3a7aSWarner Loshwhere the <b>return</b> has one single function call as argument; 23498e3e3a7aSWarner Loshthis syntax makes the calling function return exactly 23508e3e3a7aSWarner Loshthe returns of the called function. 23518e3e3a7aSWarner LoshSo, none of the following examples are tail calls: 23528e3e3a7aSWarner Losh 23538e3e3a7aSWarner Losh<pre> 23548e3e3a7aSWarner Losh return (f(x)) -- results adjusted to 1 23558e3e3a7aSWarner Losh return 2 * f(x) 23568e3e3a7aSWarner Losh return x, f(x) -- additional results 23578e3e3a7aSWarner Losh f(x); return -- results discarded 23588e3e3a7aSWarner Losh return x or f(x) -- results adjusted to 1 23598e3e3a7aSWarner Losh</pre> 23608e3e3a7aSWarner Losh 23618e3e3a7aSWarner Losh 23628e3e3a7aSWarner Losh 23638e3e3a7aSWarner Losh 23648e3e3a7aSWarner Losh<h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3> 23658e3e3a7aSWarner Losh 23668e3e3a7aSWarner Losh<p> 23678e3e3a7aSWarner LoshThe syntax for function definition is 23688e3e3a7aSWarner Losh 23698e3e3a7aSWarner Losh<pre> 23708e3e3a7aSWarner Losh functiondef ::= <b>function</b> funcbody 23718e3e3a7aSWarner Losh funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 23728e3e3a7aSWarner Losh</pre> 23738e3e3a7aSWarner Losh 23748e3e3a7aSWarner Losh<p> 23758e3e3a7aSWarner LoshThe following syntactic sugar simplifies function definitions: 23768e3e3a7aSWarner Losh 23778e3e3a7aSWarner Losh<pre> 23788e3e3a7aSWarner Losh stat ::= <b>function</b> funcname funcbody 23798e3e3a7aSWarner Losh stat ::= <b>local</b> <b>function</b> Name funcbody 23808e3e3a7aSWarner Losh funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 23818e3e3a7aSWarner Losh</pre><p> 23828e3e3a7aSWarner LoshThe statement 23838e3e3a7aSWarner Losh 23848e3e3a7aSWarner Losh<pre> 23858e3e3a7aSWarner Losh function f () <em>body</em> end 23868e3e3a7aSWarner Losh</pre><p> 23878e3e3a7aSWarner Loshtranslates to 23888e3e3a7aSWarner Losh 23898e3e3a7aSWarner Losh<pre> 23908e3e3a7aSWarner Losh f = function () <em>body</em> end 23918e3e3a7aSWarner Losh</pre><p> 23928e3e3a7aSWarner LoshThe statement 23938e3e3a7aSWarner Losh 23948e3e3a7aSWarner Losh<pre> 23958e3e3a7aSWarner Losh function t.a.b.c.f () <em>body</em> end 23968e3e3a7aSWarner Losh</pre><p> 23978e3e3a7aSWarner Loshtranslates to 23988e3e3a7aSWarner Losh 23998e3e3a7aSWarner Losh<pre> 24008e3e3a7aSWarner Losh t.a.b.c.f = function () <em>body</em> end 24018e3e3a7aSWarner Losh</pre><p> 24028e3e3a7aSWarner LoshThe statement 24038e3e3a7aSWarner Losh 24048e3e3a7aSWarner Losh<pre> 24058e3e3a7aSWarner Losh local function f () <em>body</em> end 24068e3e3a7aSWarner Losh</pre><p> 24078e3e3a7aSWarner Loshtranslates to 24088e3e3a7aSWarner Losh 24098e3e3a7aSWarner Losh<pre> 24108e3e3a7aSWarner Losh local f; f = function () <em>body</em> end 24118e3e3a7aSWarner Losh</pre><p> 24128e3e3a7aSWarner Loshnot to 24138e3e3a7aSWarner Losh 24148e3e3a7aSWarner Losh<pre> 24158e3e3a7aSWarner Losh local f = function () <em>body</em> end 24168e3e3a7aSWarner Losh</pre><p> 24178e3e3a7aSWarner Losh(This only makes a difference when the body of the function 24188e3e3a7aSWarner Loshcontains references to <code>f</code>.) 24198e3e3a7aSWarner Losh 24208e3e3a7aSWarner Losh 24218e3e3a7aSWarner Losh<p> 24228e3e3a7aSWarner LoshA function definition is an executable expression, 24238e3e3a7aSWarner Loshwhose value has type <em>function</em>. 24248e3e3a7aSWarner LoshWhen Lua precompiles a chunk, 24258e3e3a7aSWarner Loshall its function bodies are precompiled too. 24268e3e3a7aSWarner LoshThen, whenever Lua executes the function definition, 24278e3e3a7aSWarner Loshthe function is <em>instantiated</em> (or <em>closed</em>). 24288e3e3a7aSWarner LoshThis function instance (or <em>closure</em>) 24298e3e3a7aSWarner Loshis the final value of the expression. 24308e3e3a7aSWarner Losh 24318e3e3a7aSWarner Losh 24328e3e3a7aSWarner Losh<p> 24338e3e3a7aSWarner LoshParameters act as local variables that are 24348e3e3a7aSWarner Loshinitialized with the argument values: 24358e3e3a7aSWarner Losh 24368e3e3a7aSWarner Losh<pre> 24378e3e3a7aSWarner Losh parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 24388e3e3a7aSWarner Losh</pre><p> 24398e3e3a7aSWarner LoshWhen a function is called, 24408e3e3a7aSWarner Loshthe list of arguments is adjusted to 24418e3e3a7aSWarner Loshthe length of the list of parameters, 24428e3e3a7aSWarner Loshunless the function is a <em>vararg function</em>, 24438e3e3a7aSWarner Loshwhich is indicated by three dots ('<code>...</code>') 24448e3e3a7aSWarner Loshat the end of its parameter list. 24458e3e3a7aSWarner LoshA vararg function does not adjust its argument list; 24468e3e3a7aSWarner Loshinstead, it collects all extra arguments and supplies them 24478e3e3a7aSWarner Loshto the function through a <em>vararg expression</em>, 24488e3e3a7aSWarner Loshwhich is also written as three dots. 24498e3e3a7aSWarner LoshThe value of this expression is a list of all actual extra arguments, 24508e3e3a7aSWarner Loshsimilar to a function with multiple results. 24518e3e3a7aSWarner LoshIf a vararg expression is used inside another expression 24528e3e3a7aSWarner Loshor in the middle of a list of expressions, 24538e3e3a7aSWarner Loshthen its return list is adjusted to one element. 24548e3e3a7aSWarner LoshIf the expression is used as the last element of a list of expressions, 24558e3e3a7aSWarner Loshthen no adjustment is made 24568e3e3a7aSWarner Losh(unless that last expression is enclosed in parentheses). 24578e3e3a7aSWarner Losh 24588e3e3a7aSWarner Losh 24598e3e3a7aSWarner Losh<p> 24608e3e3a7aSWarner LoshAs an example, consider the following definitions: 24618e3e3a7aSWarner Losh 24628e3e3a7aSWarner Losh<pre> 24638e3e3a7aSWarner Losh function f(a, b) end 24648e3e3a7aSWarner Losh function g(a, b, ...) end 24658e3e3a7aSWarner Losh function r() return 1,2,3 end 24668e3e3a7aSWarner Losh</pre><p> 24678e3e3a7aSWarner LoshThen, we have the following mapping from arguments to parameters and 24688e3e3a7aSWarner Loshto the vararg expression: 24698e3e3a7aSWarner Losh 24708e3e3a7aSWarner Losh<pre> 24718e3e3a7aSWarner Losh CALL PARAMETERS 24728e3e3a7aSWarner Losh 24738e3e3a7aSWarner Losh f(3) a=3, b=nil 24748e3e3a7aSWarner Losh f(3, 4) a=3, b=4 24758e3e3a7aSWarner Losh f(3, 4, 5) a=3, b=4 24768e3e3a7aSWarner Losh f(r(), 10) a=1, b=10 24778e3e3a7aSWarner Losh f(r()) a=1, b=2 24788e3e3a7aSWarner Losh 24798e3e3a7aSWarner Losh g(3) a=3, b=nil, ... --> (nothing) 24808e3e3a7aSWarner Losh g(3, 4) a=3, b=4, ... --> (nothing) 24818e3e3a7aSWarner Losh g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 24828e3e3a7aSWarner Losh g(5, r()) a=5, b=1, ... --> 2 3 24838e3e3a7aSWarner Losh</pre> 24848e3e3a7aSWarner Losh 24858e3e3a7aSWarner Losh<p> 24868e3e3a7aSWarner LoshResults are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>). 24878e3e3a7aSWarner LoshIf control reaches the end of a function 24888e3e3a7aSWarner Loshwithout encountering a <b>return</b> statement, 24898e3e3a7aSWarner Loshthen the function returns with no results. 24908e3e3a7aSWarner Losh 24918e3e3a7aSWarner Losh 24928e3e3a7aSWarner Losh<p> 24938e3e3a7aSWarner Losh 24948e3e3a7aSWarner LoshThere is a system-dependent limit on the number of values 24958e3e3a7aSWarner Loshthat a function may return. 24968e3e3a7aSWarner LoshThis limit is guaranteed to be larger than 1000. 24978e3e3a7aSWarner Losh 24988e3e3a7aSWarner Losh 24998e3e3a7aSWarner Losh<p> 25008e3e3a7aSWarner LoshThe <em>colon</em> syntax 25018e3e3a7aSWarner Loshis used for defining <em>methods</em>, 25028e3e3a7aSWarner Loshthat is, functions that have an implicit extra parameter <code>self</code>. 25038e3e3a7aSWarner LoshThus, the statement 25048e3e3a7aSWarner Losh 25058e3e3a7aSWarner Losh<pre> 25068e3e3a7aSWarner Losh function t.a.b.c:f (<em>params</em>) <em>body</em> end 25078e3e3a7aSWarner Losh</pre><p> 25088e3e3a7aSWarner Loshis syntactic sugar for 25098e3e3a7aSWarner Losh 25108e3e3a7aSWarner Losh<pre> 25118e3e3a7aSWarner Losh t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end 25128e3e3a7aSWarner Losh</pre> 25138e3e3a7aSWarner Losh 25148e3e3a7aSWarner Losh 25158e3e3a7aSWarner Losh 25168e3e3a7aSWarner Losh 25178e3e3a7aSWarner Losh 25188e3e3a7aSWarner Losh 25198e3e3a7aSWarner Losh<h2>3.5 – <a name="3.5">Visibility Rules</a></h2> 25208e3e3a7aSWarner Losh 25218e3e3a7aSWarner Losh<p> 25228e3e3a7aSWarner Losh 25238e3e3a7aSWarner LoshLua is a lexically scoped language. 25248e3e3a7aSWarner LoshThe scope of a local variable begins at the first statement after 25258e3e3a7aSWarner Loshits declaration and lasts until the last non-void statement 25268e3e3a7aSWarner Loshof the innermost block that includes the declaration. 25278e3e3a7aSWarner LoshConsider the following example: 25288e3e3a7aSWarner Losh 25298e3e3a7aSWarner Losh<pre> 25308e3e3a7aSWarner Losh x = 10 -- global variable 25318e3e3a7aSWarner Losh do -- new block 25328e3e3a7aSWarner Losh local x = x -- new 'x', with value 10 25338e3e3a7aSWarner Losh print(x) --> 10 25348e3e3a7aSWarner Losh x = x+1 25358e3e3a7aSWarner Losh do -- another block 25368e3e3a7aSWarner Losh local x = x+1 -- another 'x' 25378e3e3a7aSWarner Losh print(x) --> 12 25388e3e3a7aSWarner Losh end 25398e3e3a7aSWarner Losh print(x) --> 11 25408e3e3a7aSWarner Losh end 25418e3e3a7aSWarner Losh print(x) --> 10 (the global one) 25428e3e3a7aSWarner Losh</pre> 25438e3e3a7aSWarner Losh 25448e3e3a7aSWarner Losh<p> 25458e3e3a7aSWarner LoshNotice that, in a declaration like <code>local x = x</code>, 25468e3e3a7aSWarner Loshthe new <code>x</code> being declared is not in scope yet, 25478e3e3a7aSWarner Loshand so the second <code>x</code> refers to the outside variable. 25488e3e3a7aSWarner Losh 25498e3e3a7aSWarner Losh 25508e3e3a7aSWarner Losh<p> 25518e3e3a7aSWarner LoshBecause of the lexical scoping rules, 25528e3e3a7aSWarner Loshlocal variables can be freely accessed by functions 25538e3e3a7aSWarner Loshdefined inside their scope. 25548e3e3a7aSWarner LoshA local variable used by an inner function is called 25558e3e3a7aSWarner Loshan <em>upvalue</em>, or <em>external local variable</em>, 25568e3e3a7aSWarner Loshinside the inner function. 25578e3e3a7aSWarner Losh 25588e3e3a7aSWarner Losh 25598e3e3a7aSWarner Losh<p> 25608e3e3a7aSWarner LoshNotice that each execution of a <b>local</b> statement 25618e3e3a7aSWarner Loshdefines new local variables. 25628e3e3a7aSWarner LoshConsider the following example: 25638e3e3a7aSWarner Losh 25648e3e3a7aSWarner Losh<pre> 25658e3e3a7aSWarner Losh a = {} 25668e3e3a7aSWarner Losh local x = 20 25678e3e3a7aSWarner Losh for i=1,10 do 25688e3e3a7aSWarner Losh local y = 0 25698e3e3a7aSWarner Losh a[i] = function () y=y+1; return x+y end 25708e3e3a7aSWarner Losh end 25718e3e3a7aSWarner Losh</pre><p> 25728e3e3a7aSWarner LoshThe loop creates ten closures 25738e3e3a7aSWarner Losh(that is, ten instances of the anonymous function). 25748e3e3a7aSWarner LoshEach of these closures uses a different <code>y</code> variable, 25758e3e3a7aSWarner Loshwhile all of them share the same <code>x</code>. 25768e3e3a7aSWarner Losh 25778e3e3a7aSWarner Losh 25788e3e3a7aSWarner Losh 25798e3e3a7aSWarner Losh 25808e3e3a7aSWarner Losh 25818e3e3a7aSWarner Losh<h1>4 – <a name="4">The Application Program Interface</a></h1> 25828e3e3a7aSWarner Losh 25838e3e3a7aSWarner Losh<p> 25848e3e3a7aSWarner Losh 25858e3e3a7aSWarner LoshThis section describes the C API for Lua, that is, 25868e3e3a7aSWarner Loshthe set of C functions available to the host program to communicate 25878e3e3a7aSWarner Loshwith Lua. 25888e3e3a7aSWarner LoshAll API functions and related types and constants 25898e3e3a7aSWarner Loshare declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. 25908e3e3a7aSWarner Losh 25918e3e3a7aSWarner Losh 25928e3e3a7aSWarner Losh<p> 25938e3e3a7aSWarner LoshEven when we use the term "function", 25948e3e3a7aSWarner Loshany facility in the API may be provided as a macro instead. 25958e3e3a7aSWarner LoshExcept where stated otherwise, 25968e3e3a7aSWarner Loshall such macros use each of their arguments exactly once 25978e3e3a7aSWarner Losh(except for the first argument, which is always a Lua state), 25988e3e3a7aSWarner Loshand so do not generate any hidden side-effects. 25998e3e3a7aSWarner Losh 26008e3e3a7aSWarner Losh 26018e3e3a7aSWarner Losh<p> 26028e3e3a7aSWarner LoshAs in most C libraries, 26038e3e3a7aSWarner Loshthe Lua API functions do not check their arguments for validity or consistency. 26048e3e3a7aSWarner LoshHowever, you can change this behavior by compiling Lua 26058e3e3a7aSWarner Loshwith the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined. 26068e3e3a7aSWarner Losh 26078e3e3a7aSWarner Losh 26088e3e3a7aSWarner Losh<p> 26098e3e3a7aSWarner LoshThe Lua library is fully reentrant: 26108e3e3a7aSWarner Loshit has no global variables. 26118e3e3a7aSWarner LoshIt keeps all information it needs in a dynamic structure, 26128e3e3a7aSWarner Loshcalled the <em>Lua state</em>. 26138e3e3a7aSWarner Losh 26148e3e3a7aSWarner Losh 26158e3e3a7aSWarner Losh<p> 26168e3e3a7aSWarner LoshEach Lua state has one or more threads, 26178e3e3a7aSWarner Loshwhich correspond to independent, cooperative lines of execution. 26188e3e3a7aSWarner LoshThe type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread. 26198e3e3a7aSWarner Losh(Indirectly, through the thread, it also refers to the 26208e3e3a7aSWarner LoshLua state associated to the thread.) 26218e3e3a7aSWarner Losh 26228e3e3a7aSWarner Losh 26238e3e3a7aSWarner Losh<p> 26248e3e3a7aSWarner LoshA pointer to a thread must be passed as the first argument to 26258e3e3a7aSWarner Loshevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 26268e3e3a7aSWarner Loshwhich creates a Lua state from scratch and returns a pointer 26278e3e3a7aSWarner Loshto the <em>main thread</em> in the new state. 26288e3e3a7aSWarner Losh 26298e3e3a7aSWarner Losh 26308e3e3a7aSWarner Losh 26318e3e3a7aSWarner Losh<h2>4.1 – <a name="4.1">The Stack</a></h2> 26328e3e3a7aSWarner Losh 26338e3e3a7aSWarner Losh<p> 26348e3e3a7aSWarner LoshLua uses a <em>virtual stack</em> to pass values to and from C. 26358e3e3a7aSWarner LoshEach element in this stack represents a Lua value 26368e3e3a7aSWarner Losh(<b>nil</b>, number, string, etc.). 26378e3e3a7aSWarner LoshFunctions in the API can access this stack through the 26388e3e3a7aSWarner LoshLua state parameter that they receive. 26398e3e3a7aSWarner Losh 26408e3e3a7aSWarner Losh 26418e3e3a7aSWarner Losh<p> 26428e3e3a7aSWarner LoshWhenever Lua calls C, the called function gets a new stack, 26438e3e3a7aSWarner Loshwhich is independent of previous stacks and of stacks of 26448e3e3a7aSWarner LoshC functions that are still active. 26458e3e3a7aSWarner LoshThis stack initially contains any arguments to the C function 26468e3e3a7aSWarner Loshand it is where the C function can store temporary 26478e3e3a7aSWarner LoshLua values and must push its results 26488e3e3a7aSWarner Loshto be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 26498e3e3a7aSWarner Losh 26508e3e3a7aSWarner Losh 26518e3e3a7aSWarner Losh<p> 26528e3e3a7aSWarner LoshFor convenience, 26538e3e3a7aSWarner Loshmost query operations in the API do not follow a strict stack discipline. 26548e3e3a7aSWarner LoshInstead, they can refer to any element in the stack 26558e3e3a7aSWarner Loshby using an <em>index</em>: 26568e3e3a7aSWarner LoshA positive index represents an absolute stack position 26578e3e3a7aSWarner Losh(starting at 1); 26588e3e3a7aSWarner Losha negative index represents an offset relative to the top of the stack. 26598e3e3a7aSWarner LoshMore specifically, if the stack has <em>n</em> elements, 26608e3e3a7aSWarner Loshthen index 1 represents the first element 26618e3e3a7aSWarner Losh(that is, the element that was pushed onto the stack first) 26628e3e3a7aSWarner Loshand 26638e3e3a7aSWarner Loshindex <em>n</em> represents the last element; 26648e3e3a7aSWarner Loshindex -1 also represents the last element 26658e3e3a7aSWarner Losh(that is, the element at the top) 26668e3e3a7aSWarner Loshand index <em>-n</em> represents the first element. 26678e3e3a7aSWarner Losh 26688e3e3a7aSWarner Losh 26698e3e3a7aSWarner Losh 26708e3e3a7aSWarner Losh 26718e3e3a7aSWarner Losh 26728e3e3a7aSWarner Losh<h2>4.2 – <a name="4.2">Stack Size</a></h2> 26738e3e3a7aSWarner Losh 26748e3e3a7aSWarner Losh<p> 26758e3e3a7aSWarner LoshWhen you interact with the Lua API, 26768e3e3a7aSWarner Loshyou are responsible for ensuring consistency. 26778e3e3a7aSWarner LoshIn particular, 26788e3e3a7aSWarner Losh<em>you are responsible for controlling stack overflow</em>. 26798e3e3a7aSWarner LoshYou can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> 26808e3e3a7aSWarner Loshto ensure that the stack has enough space for pushing new elements. 26818e3e3a7aSWarner Losh 26828e3e3a7aSWarner Losh 26838e3e3a7aSWarner Losh<p> 26848e3e3a7aSWarner LoshWhenever Lua calls C, 26858e3e3a7aSWarner Loshit ensures that the stack has space for 26868e3e3a7aSWarner Loshat least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots. 26878e3e3a7aSWarner Losh<code>LUA_MINSTACK</code> is defined as 20, 26888e3e3a7aSWarner Loshso that usually you do not have to worry about stack space 26898e3e3a7aSWarner Loshunless your code has loops pushing elements onto the stack. 26908e3e3a7aSWarner Losh 26918e3e3a7aSWarner Losh 26928e3e3a7aSWarner Losh<p> 26938e3e3a7aSWarner LoshWhen you call a Lua function 26948e3e3a7aSWarner Loshwithout a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>), 26958e3e3a7aSWarner LoshLua ensures that the stack has enough space for all results, 26968e3e3a7aSWarner Loshbut it does not ensure any extra space. 26978e3e3a7aSWarner LoshSo, before pushing anything in the stack after such a call 26988e3e3a7aSWarner Loshyou should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>. 26998e3e3a7aSWarner Losh 27008e3e3a7aSWarner Losh 27018e3e3a7aSWarner Losh 27028e3e3a7aSWarner Losh 27038e3e3a7aSWarner Losh 27048e3e3a7aSWarner Losh<h2>4.3 – <a name="4.3">Valid and Acceptable Indices</a></h2> 27058e3e3a7aSWarner Losh 27068e3e3a7aSWarner Losh<p> 27078e3e3a7aSWarner LoshAny function in the API that receives stack indices 27088e3e3a7aSWarner Loshworks only with <em>valid indices</em> or <em>acceptable indices</em>. 27098e3e3a7aSWarner Losh 27108e3e3a7aSWarner Losh 27118e3e3a7aSWarner Losh<p> 27128e3e3a7aSWarner LoshA <em>valid index</em> is an index that refers to a 27138e3e3a7aSWarner Loshposition that stores a modifiable Lua value. 27148e3e3a7aSWarner LoshIt comprises stack indices between 1 and the stack top 27158e3e3a7aSWarner Losh(<code>1 ≤ abs(index) ≤ top</code>) 27168e3e3a7aSWarner Losh 27178e3e3a7aSWarner Loshplus <em>pseudo-indices</em>, 27188e3e3a7aSWarner Loshwhich represent some positions that are accessible to C code 27198e3e3a7aSWarner Loshbut that are not in the stack. 27208e3e3a7aSWarner LoshPseudo-indices are used to access the registry (see <a href="#4.5">§4.5</a>) 27218e3e3a7aSWarner Loshand the upvalues of a C function (see <a href="#4.4">§4.4</a>). 27228e3e3a7aSWarner Losh 27238e3e3a7aSWarner Losh 27248e3e3a7aSWarner Losh<p> 27258e3e3a7aSWarner LoshFunctions that do not need a specific mutable position, 27268e3e3a7aSWarner Loshbut only a value (e.g., query functions), 27278e3e3a7aSWarner Loshcan be called with acceptable indices. 27288e3e3a7aSWarner LoshAn <em>acceptable index</em> can be any valid index, 27298e3e3a7aSWarner Loshbut it also can be any positive index after the stack top 27308e3e3a7aSWarner Loshwithin the space allocated for the stack, 27318e3e3a7aSWarner Loshthat is, indices up to the stack size. 27328e3e3a7aSWarner Losh(Note that 0 is never an acceptable index.) 27338e3e3a7aSWarner LoshExcept when noted otherwise, 27348e3e3a7aSWarner Loshfunctions in the API work with acceptable indices. 27358e3e3a7aSWarner Losh 27368e3e3a7aSWarner Losh 27378e3e3a7aSWarner Losh<p> 27388e3e3a7aSWarner LoshAcceptable indices serve to avoid extra tests 27398e3e3a7aSWarner Loshagainst the stack top when querying the stack. 27408e3e3a7aSWarner LoshFor instance, a C function can query its third argument 27418e3e3a7aSWarner Loshwithout the need to first check whether there is a third argument, 27428e3e3a7aSWarner Loshthat is, without the need to check whether 3 is a valid index. 27438e3e3a7aSWarner Losh 27448e3e3a7aSWarner Losh 27458e3e3a7aSWarner Losh<p> 27468e3e3a7aSWarner LoshFor functions that can be called with acceptable indices, 27478e3e3a7aSWarner Loshany non-valid index is treated as if it 27488e3e3a7aSWarner Loshcontains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>, 27498e3e3a7aSWarner Loshwhich behaves like a nil value. 27508e3e3a7aSWarner Losh 27518e3e3a7aSWarner Losh 27528e3e3a7aSWarner Losh 27538e3e3a7aSWarner Losh 27548e3e3a7aSWarner Losh 27558e3e3a7aSWarner Losh<h2>4.4 – <a name="4.4">C Closures</a></h2> 27568e3e3a7aSWarner Losh 27578e3e3a7aSWarner Losh<p> 27588e3e3a7aSWarner LoshWhen a C function is created, 27598e3e3a7aSWarner Loshit is possible to associate some values with it, 27608e3e3a7aSWarner Loshthus creating a <em>C closure</em> 27618e3e3a7aSWarner Losh(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>); 27628e3e3a7aSWarner Loshthese values are called <em>upvalues</em> and are 27638e3e3a7aSWarner Loshaccessible to the function whenever it is called. 27648e3e3a7aSWarner Losh 27658e3e3a7aSWarner Losh 27668e3e3a7aSWarner Losh<p> 27678e3e3a7aSWarner LoshWhenever a C function is called, 27688e3e3a7aSWarner Loshits upvalues are located at specific pseudo-indices. 27698e3e3a7aSWarner LoshThese pseudo-indices are produced by the macro 27708e3e3a7aSWarner Losh<a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>. 27718e3e3a7aSWarner LoshThe first upvalue associated with a function is at index 27728e3e3a7aSWarner Losh<code>lua_upvalueindex(1)</code>, and so on. 27738e3e3a7aSWarner LoshAny access to <code>lua_upvalueindex(<em>n</em>)</code>, 27748e3e3a7aSWarner Loshwhere <em>n</em> is greater than the number of upvalues of the 27758e3e3a7aSWarner Loshcurrent function 27768e3e3a7aSWarner Losh(but not greater than 256, 27778e3e3a7aSWarner Loshwhich is one plus the maximum number of upvalues in a closure), 27788e3e3a7aSWarner Loshproduces an acceptable but invalid index. 27798e3e3a7aSWarner Losh 27808e3e3a7aSWarner Losh 27818e3e3a7aSWarner Losh 27828e3e3a7aSWarner Losh 27838e3e3a7aSWarner Losh 27848e3e3a7aSWarner Losh<h2>4.5 – <a name="4.5">Registry</a></h2> 27858e3e3a7aSWarner Losh 27868e3e3a7aSWarner Losh<p> 27878e3e3a7aSWarner LoshLua provides a <em>registry</em>, 27888e3e3a7aSWarner Losha predefined table that can be used by any C code to 27898e3e3a7aSWarner Loshstore whatever Lua values it needs to store. 27908e3e3a7aSWarner LoshThe registry table is always located at pseudo-index 27918e3e3a7aSWarner Losh<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. 27928e3e3a7aSWarner LoshAny C library can store data into this table, 27938e3e3a7aSWarner Loshbut it must take care to choose keys 27948e3e3a7aSWarner Loshthat are different from those used 27958e3e3a7aSWarner Loshby other libraries, to avoid collisions. 27968e3e3a7aSWarner LoshTypically, you should use as key a string containing your library name, 27978e3e3a7aSWarner Loshor a light userdata with the address of a C object in your code, 27988e3e3a7aSWarner Loshor any Lua object created by your code. 27998e3e3a7aSWarner LoshAs with variable names, 28008e3e3a7aSWarner Loshstring keys starting with an underscore followed by 28018e3e3a7aSWarner Loshuppercase letters are reserved for Lua. 28028e3e3a7aSWarner Losh 28038e3e3a7aSWarner Losh 28048e3e3a7aSWarner Losh<p> 28058e3e3a7aSWarner LoshThe integer keys in the registry are used 28068e3e3a7aSWarner Loshby the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>) 28078e3e3a7aSWarner Loshand by some predefined values. 28088e3e3a7aSWarner LoshTherefore, integer keys must not be used for other purposes. 28098e3e3a7aSWarner Losh 28108e3e3a7aSWarner Losh 28118e3e3a7aSWarner Losh<p> 28128e3e3a7aSWarner LoshWhen you create a new Lua state, 28138e3e3a7aSWarner Loshits registry comes with some predefined values. 28148e3e3a7aSWarner LoshThese predefined values are indexed with integer keys 28158e3e3a7aSWarner Loshdefined as constants in <code>lua.h</code>. 28168e3e3a7aSWarner LoshThe following constants are defined: 28178e3e3a7aSWarner Losh 28188e3e3a7aSWarner Losh<ul> 28198e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has 28208e3e3a7aSWarner Loshthe main thread of the state. 28218e3e3a7aSWarner Losh(The main thread is the one created together with the state.) 28228e3e3a7aSWarner Losh</li> 28238e3e3a7aSWarner Losh 28248e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has 28258e3e3a7aSWarner Loshthe global environment. 28268e3e3a7aSWarner Losh</li> 28278e3e3a7aSWarner Losh</ul> 28288e3e3a7aSWarner Losh 28298e3e3a7aSWarner Losh 28308e3e3a7aSWarner Losh 28318e3e3a7aSWarner Losh 28328e3e3a7aSWarner Losh<h2>4.6 – <a name="4.6">Error Handling in C</a></h2> 28338e3e3a7aSWarner Losh 28348e3e3a7aSWarner Losh<p> 28358e3e3a7aSWarner LoshInternally, Lua uses the C <code>longjmp</code> facility to handle errors. 28368e3e3a7aSWarner Losh(Lua will use exceptions if you compile it as C++; 28378e3e3a7aSWarner Loshsearch for <code>LUAI_THROW</code> in the source code for details.) 28388e3e3a7aSWarner LoshWhen Lua faces any error 28398e3e3a7aSWarner Losh(such as a memory allocation error or a type error) 28408e3e3a7aSWarner Loshit <em>raises</em> an error; 28418e3e3a7aSWarner Loshthat is, it does a long jump. 28428e3e3a7aSWarner LoshA <em>protected environment</em> uses <code>setjmp</code> 28438e3e3a7aSWarner Loshto set a recovery point; 28448e3e3a7aSWarner Loshany error jumps to the most recent active recovery point. 28458e3e3a7aSWarner Losh 28468e3e3a7aSWarner Losh 28478e3e3a7aSWarner Losh<p> 28488e3e3a7aSWarner LoshInside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>. 28498e3e3a7aSWarner Losh 28508e3e3a7aSWarner Losh 28518e3e3a7aSWarner Losh<p> 28528e3e3a7aSWarner LoshMost functions in the API can raise an error, 28538e3e3a7aSWarner Loshfor instance due to a memory allocation error. 28548e3e3a7aSWarner LoshThe documentation for each function indicates whether 28558e3e3a7aSWarner Loshit can raise errors. 28568e3e3a7aSWarner Losh 28578e3e3a7aSWarner Losh 28588e3e3a7aSWarner Losh<p> 28598e3e3a7aSWarner LoshIf an error happens outside any protected environment, 28608e3e3a7aSWarner LoshLua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) 28618e3e3a7aSWarner Loshand then calls <code>abort</code>, 28628e3e3a7aSWarner Loshthus exiting the host application. 28638e3e3a7aSWarner LoshYour panic function can avoid this exit by 28648e3e3a7aSWarner Loshnever returning 28658e3e3a7aSWarner Losh(e.g., doing a long jump to your own recovery point outside Lua). 28668e3e3a7aSWarner Losh 28678e3e3a7aSWarner Losh 28688e3e3a7aSWarner Losh<p> 28698e3e3a7aSWarner LoshThe panic function, 28708e3e3a7aSWarner Loshas its name implies, 28718e3e3a7aSWarner Loshis a mechanism of last resort. 28728e3e3a7aSWarner LoshPrograms should avoid it. 28738e3e3a7aSWarner LoshAs a general rule, 28748e3e3a7aSWarner Loshwhen a C function is called by Lua with a Lua state, 28758e3e3a7aSWarner Loshit can do whatever it wants on that Lua state, 28768e3e3a7aSWarner Loshas it should be already protected. 28778e3e3a7aSWarner LoshHowever, 28788e3e3a7aSWarner Loshwhen C code operates on other Lua states 2879*e112e9d2SKyle Evans(e.g., a Lua argument to the function, 28808e3e3a7aSWarner Losha Lua state stored in the registry, or 28818e3e3a7aSWarner Loshthe result of <a href="#lua_newthread"><code>lua_newthread</code></a>), 28828e3e3a7aSWarner Loshit should use them only in API calls that cannot raise errors. 28838e3e3a7aSWarner Losh 28848e3e3a7aSWarner Losh 28858e3e3a7aSWarner Losh<p> 28868e3e3a7aSWarner LoshThe panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>); 28878e3e3a7aSWarner Loshin particular, the error object is at the top of the stack. 28888e3e3a7aSWarner LoshHowever, there is no guarantee about stack space. 28898e3e3a7aSWarner LoshTo push anything on the stack, 28908e3e3a7aSWarner Loshthe panic function must first check the available space (see <a href="#4.2">§4.2</a>). 28918e3e3a7aSWarner Losh 28928e3e3a7aSWarner Losh 28938e3e3a7aSWarner Losh 28948e3e3a7aSWarner Losh 28958e3e3a7aSWarner Losh 28968e3e3a7aSWarner Losh<h2>4.7 – <a name="4.7">Handling Yields in C</a></h2> 28978e3e3a7aSWarner Losh 28988e3e3a7aSWarner Losh<p> 28998e3e3a7aSWarner LoshInternally, Lua uses the C <code>longjmp</code> facility to yield a coroutine. 29008e3e3a7aSWarner LoshTherefore, if a C function <code>foo</code> calls an API function 29018e3e3a7aSWarner Loshand this API function yields 29028e3e3a7aSWarner Losh(directly or indirectly by calling another function that yields), 29038e3e3a7aSWarner LoshLua cannot return to <code>foo</code> any more, 29048e3e3a7aSWarner Loshbecause the <code>longjmp</code> removes its frame from the C stack. 29058e3e3a7aSWarner Losh 29068e3e3a7aSWarner Losh 29078e3e3a7aSWarner Losh<p> 29088e3e3a7aSWarner LoshTo avoid this kind of problem, 29098e3e3a7aSWarner LoshLua raises an error whenever it tries to yield across an API call, 29108e3e3a7aSWarner Loshexcept for three functions: 29118e3e3a7aSWarner Losh<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>. 29128e3e3a7aSWarner LoshAll those functions receive a <em>continuation function</em> 29138e3e3a7aSWarner Losh(as a parameter named <code>k</code>) to continue execution after a yield. 29148e3e3a7aSWarner Losh 29158e3e3a7aSWarner Losh 29168e3e3a7aSWarner Losh<p> 29178e3e3a7aSWarner LoshWe need to set some terminology to explain continuations. 29188e3e3a7aSWarner LoshWe have a C function called from Lua which we will call 29198e3e3a7aSWarner Loshthe <em>original function</em>. 29208e3e3a7aSWarner LoshThis original function then calls one of those three functions in the C API, 29218e3e3a7aSWarner Loshwhich we will call the <em>callee function</em>, 29228e3e3a7aSWarner Loshthat then yields the current thread. 29238e3e3a7aSWarner Losh(This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 29248e3e3a7aSWarner Loshor 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> 29258e3e3a7aSWarner Loshand the function called by them yields.) 29268e3e3a7aSWarner Losh 29278e3e3a7aSWarner Losh 29288e3e3a7aSWarner Losh<p> 29298e3e3a7aSWarner LoshSuppose the running thread yields while executing the callee function. 29308e3e3a7aSWarner LoshAfter the thread resumes, 29318e3e3a7aSWarner Loshit eventually will finish running the callee function. 29328e3e3a7aSWarner LoshHowever, 29338e3e3a7aSWarner Loshthe callee function cannot return to the original function, 29348e3e3a7aSWarner Loshbecause its frame in the C stack was destroyed by the yield. 29358e3e3a7aSWarner LoshInstead, Lua calls a <em>continuation function</em>, 29368e3e3a7aSWarner Loshwhich was given as an argument to the callee function. 29378e3e3a7aSWarner LoshAs the name implies, 29388e3e3a7aSWarner Loshthe continuation function should continue the task 29398e3e3a7aSWarner Loshof the original function. 29408e3e3a7aSWarner Losh 29418e3e3a7aSWarner Losh 29428e3e3a7aSWarner Losh<p> 29438e3e3a7aSWarner LoshAs an illustration, consider the following function: 29448e3e3a7aSWarner Losh 29458e3e3a7aSWarner Losh<pre> 29468e3e3a7aSWarner Losh int original_function (lua_State *L) { 29478e3e3a7aSWarner Losh ... /* code 1 */ 29488e3e3a7aSWarner Losh status = lua_pcall(L, n, m, h); /* calls Lua */ 29498e3e3a7aSWarner Losh ... /* code 2 */ 29508e3e3a7aSWarner Losh } 29518e3e3a7aSWarner Losh</pre><p> 29528e3e3a7aSWarner LoshNow we want to allow 29538e3e3a7aSWarner Loshthe Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield. 29548e3e3a7aSWarner LoshFirst, we can rewrite our function like here: 29558e3e3a7aSWarner Losh 29568e3e3a7aSWarner Losh<pre> 29578e3e3a7aSWarner Losh int k (lua_State *L, int status, lua_KContext ctx) { 29588e3e3a7aSWarner Losh ... /* code 2 */ 29598e3e3a7aSWarner Losh } 29608e3e3a7aSWarner Losh 29618e3e3a7aSWarner Losh int original_function (lua_State *L) { 29628e3e3a7aSWarner Losh ... /* code 1 */ 29638e3e3a7aSWarner Losh return k(L, lua_pcall(L, n, m, h), ctx); 29648e3e3a7aSWarner Losh } 29658e3e3a7aSWarner Losh</pre><p> 29668e3e3a7aSWarner LoshIn the above code, 29678e3e3a7aSWarner Loshthe new function <code>k</code> is a 29688e3e3a7aSWarner Losh<em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>), 29698e3e3a7aSWarner Loshwhich should do all the work that the original function 29708e3e3a7aSWarner Loshwas doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>. 29718e3e3a7aSWarner LoshNow, we must inform Lua that it must call <code>k</code> if the Lua code 29728e3e3a7aSWarner Loshbeing executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way 29738e3e3a7aSWarner Losh(errors or yielding), 29748e3e3a7aSWarner Loshso we rewrite the code as here, 29758e3e3a7aSWarner Loshreplacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>: 29768e3e3a7aSWarner Losh 29778e3e3a7aSWarner Losh<pre> 29788e3e3a7aSWarner Losh int original_function (lua_State *L) { 29798e3e3a7aSWarner Losh ... /* code 1 */ 29808e3e3a7aSWarner Losh return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1); 29818e3e3a7aSWarner Losh } 29828e3e3a7aSWarner Losh</pre><p> 29838e3e3a7aSWarner LoshNote the external, explicit call to the continuation: 29848e3e3a7aSWarner LoshLua will call the continuation only if needed, that is, 29858e3e3a7aSWarner Loshin case of errors or resuming after a yield. 29868e3e3a7aSWarner LoshIf the called function returns normally without ever yielding, 29878e3e3a7aSWarner Losh<a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally. 29888e3e3a7aSWarner Losh(Of course, instead of calling the continuation in that case, 29898e3e3a7aSWarner Loshyou can do the equivalent work directly inside the original function.) 29908e3e3a7aSWarner Losh 29918e3e3a7aSWarner Losh 29928e3e3a7aSWarner Losh<p> 29938e3e3a7aSWarner LoshBesides the Lua state, 29948e3e3a7aSWarner Loshthe continuation function has two other parameters: 29958e3e3a7aSWarner Loshthe final status of the call plus the context value (<code>ctx</code>) that 29968e3e3a7aSWarner Loshwas passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>. 29978e3e3a7aSWarner Losh(Lua does not use this context value; 29988e3e3a7aSWarner Loshit only passes this value from the original function to the 29998e3e3a7aSWarner Loshcontinuation function.) 30008e3e3a7aSWarner LoshFor <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 30018e3e3a7aSWarner Loshthe status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 30028e3e3a7aSWarner Loshexcept that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield 30038e3e3a7aSWarner Losh(instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>). 30048e3e3a7aSWarner LoshFor <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>, 30058e3e3a7aSWarner Loshthe status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation. 30068e3e3a7aSWarner Losh(For these two functions, 30078e3e3a7aSWarner LoshLua will not call the continuation in case of errors, 30088e3e3a7aSWarner Loshbecause they do not handle errors.) 30098e3e3a7aSWarner LoshSimilarly, when using <a href="#lua_callk"><code>lua_callk</code></a>, 30108e3e3a7aSWarner Loshyou should call the continuation function 30118e3e3a7aSWarner Loshwith <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status. 30128e3e3a7aSWarner Losh(For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling 30138e3e3a7aSWarner Loshdirectly the continuation function, 30148e3e3a7aSWarner Loshbecause <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.) 30158e3e3a7aSWarner Losh 30168e3e3a7aSWarner Losh 30178e3e3a7aSWarner Losh<p> 30188e3e3a7aSWarner LoshLua treats the continuation function as if it were the original function. 30198e3e3a7aSWarner LoshThe continuation function receives the same Lua stack 30208e3e3a7aSWarner Loshfrom the original function, 30218e3e3a7aSWarner Loshin the same state it would be if the callee function had returned. 30228e3e3a7aSWarner Losh(For instance, 30238e3e3a7aSWarner Loshafter a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are 30248e3e3a7aSWarner Loshremoved from the stack and replaced by the results from the call.) 30258e3e3a7aSWarner LoshIt also has the same upvalues. 30268e3e3a7aSWarner LoshWhatever it returns is handled by Lua as if it were the return 30278e3e3a7aSWarner Loshof the original function. 30288e3e3a7aSWarner Losh 30298e3e3a7aSWarner Losh 30308e3e3a7aSWarner Losh 30318e3e3a7aSWarner Losh 30328e3e3a7aSWarner Losh 30338e3e3a7aSWarner Losh<h2>4.8 – <a name="4.8">Functions and Types</a></h2> 30348e3e3a7aSWarner Losh 30358e3e3a7aSWarner Losh<p> 30368e3e3a7aSWarner LoshHere we list all functions and types from the C API in 30378e3e3a7aSWarner Loshalphabetical order. 30388e3e3a7aSWarner LoshEach function has an indicator like this: 30398e3e3a7aSWarner Losh<span class="apii">[-o, +p, <em>x</em>]</span> 30408e3e3a7aSWarner Losh 30418e3e3a7aSWarner Losh 30428e3e3a7aSWarner Losh<p> 30438e3e3a7aSWarner LoshThe first field, <code>o</code>, 30448e3e3a7aSWarner Loshis how many elements the function pops from the stack. 30458e3e3a7aSWarner LoshThe second field, <code>p</code>, 30468e3e3a7aSWarner Loshis how many elements the function pushes onto the stack. 30478e3e3a7aSWarner Losh(Any function always pushes its results after popping its arguments.) 30488e3e3a7aSWarner LoshA field in the form <code>x|y</code> means the function can push (or pop) 30498e3e3a7aSWarner Losh<code>x</code> or <code>y</code> elements, 30508e3e3a7aSWarner Loshdepending on the situation; 30518e3e3a7aSWarner Loshan interrogation mark '<code>?</code>' means that 30528e3e3a7aSWarner Loshwe cannot know how many elements the function pops/pushes 30538e3e3a7aSWarner Loshby looking only at its arguments 30548e3e3a7aSWarner Losh(e.g., they may depend on what is on the stack). 30558e3e3a7aSWarner LoshThe third field, <code>x</code>, 30568e3e3a7aSWarner Loshtells whether the function may raise errors: 30578e3e3a7aSWarner Losh'<code>-</code>' means the function never raises any error; 30588e3e3a7aSWarner Losh'<code>m</code>' means the function may raise out-of-memory errors 30598e3e3a7aSWarner Loshand errors running a <code>__gc</code> metamethod; 30608e3e3a7aSWarner Losh'<code>e</code>' means the function may raise any errors 30618e3e3a7aSWarner Losh(it can run arbitrary Lua code, 30628e3e3a7aSWarner Losheither directly or through metamethods); 30638e3e3a7aSWarner Losh'<code>v</code>' means the function may raise an error on purpose. 30648e3e3a7aSWarner Losh 30658e3e3a7aSWarner Losh 30668e3e3a7aSWarner Losh 30678e3e3a7aSWarner Losh<hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p> 30688e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 30698e3e3a7aSWarner Losh<pre>int lua_absindex (lua_State *L, int idx);</pre> 30708e3e3a7aSWarner Losh 30718e3e3a7aSWarner Losh<p> 30728e3e3a7aSWarner LoshConverts the acceptable index <code>idx</code> 30738e3e3a7aSWarner Loshinto an equivalent absolute index 30748e3e3a7aSWarner Losh(that is, one that does not depend on the stack top). 30758e3e3a7aSWarner Losh 30768e3e3a7aSWarner Losh 30778e3e3a7aSWarner Losh 30788e3e3a7aSWarner Losh 30798e3e3a7aSWarner Losh 30808e3e3a7aSWarner Losh<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> 30818e3e3a7aSWarner Losh<pre>typedef void * (*lua_Alloc) (void *ud, 30828e3e3a7aSWarner Losh void *ptr, 30838e3e3a7aSWarner Losh size_t osize, 30848e3e3a7aSWarner Losh size_t nsize);</pre> 30858e3e3a7aSWarner Losh 30868e3e3a7aSWarner Losh<p> 30878e3e3a7aSWarner LoshThe type of the memory-allocation function used by Lua states. 30888e3e3a7aSWarner LoshThe allocator function must provide a 30898e3e3a7aSWarner Loshfunctionality similar to <code>realloc</code>, 30908e3e3a7aSWarner Loshbut not exactly the same. 30918e3e3a7aSWarner LoshIts arguments are 30928e3e3a7aSWarner Losh<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; 30938e3e3a7aSWarner Losh<code>ptr</code>, a pointer to the block being allocated/reallocated/freed; 30948e3e3a7aSWarner Losh<code>osize</code>, the original size of the block or some code about what 30958e3e3a7aSWarner Loshis being allocated; 30968e3e3a7aSWarner Loshand <code>nsize</code>, the new size of the block. 30978e3e3a7aSWarner Losh 30988e3e3a7aSWarner Losh 30998e3e3a7aSWarner Losh<p> 31008e3e3a7aSWarner LoshWhen <code>ptr</code> is not <code>NULL</code>, 31018e3e3a7aSWarner Losh<code>osize</code> is the size of the block pointed by <code>ptr</code>, 31028e3e3a7aSWarner Loshthat is, the size given when it was allocated or reallocated. 31038e3e3a7aSWarner Losh 31048e3e3a7aSWarner Losh 31058e3e3a7aSWarner Losh<p> 31068e3e3a7aSWarner LoshWhen <code>ptr</code> is <code>NULL</code>, 31078e3e3a7aSWarner Losh<code>osize</code> encodes the kind of object that Lua is allocating. 31088e3e3a7aSWarner Losh<code>osize</code> is any of 31098e3e3a7aSWarner Losh<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>, 31108e3e3a7aSWarner Losh<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) 31118e3e3a7aSWarner LoshLua is creating a new object of that type. 31128e3e3a7aSWarner LoshWhen <code>osize</code> is some other value, 31138e3e3a7aSWarner LoshLua is allocating memory for something else. 31148e3e3a7aSWarner Losh 31158e3e3a7aSWarner Losh 31168e3e3a7aSWarner Losh<p> 31178e3e3a7aSWarner LoshLua assumes the following behavior from the allocator function: 31188e3e3a7aSWarner Losh 31198e3e3a7aSWarner Losh 31208e3e3a7aSWarner Losh<p> 31218e3e3a7aSWarner LoshWhen <code>nsize</code> is zero, 31228e3e3a7aSWarner Loshthe allocator must behave like <code>free</code> 31238e3e3a7aSWarner Loshand return <code>NULL</code>. 31248e3e3a7aSWarner Losh 31258e3e3a7aSWarner Losh 31268e3e3a7aSWarner Losh<p> 31278e3e3a7aSWarner LoshWhen <code>nsize</code> is not zero, 31288e3e3a7aSWarner Loshthe allocator must behave like <code>realloc</code>. 31298e3e3a7aSWarner LoshThe allocator returns <code>NULL</code> 31308e3e3a7aSWarner Loshif and only if it cannot fulfill the request. 31318e3e3a7aSWarner LoshLua assumes that the allocator never fails when 31328e3e3a7aSWarner Losh<code>osize >= nsize</code>. 31338e3e3a7aSWarner Losh 31348e3e3a7aSWarner Losh 31358e3e3a7aSWarner Losh<p> 31368e3e3a7aSWarner LoshHere is a simple implementation for the allocator function. 31378e3e3a7aSWarner LoshIt is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. 31388e3e3a7aSWarner Losh 31398e3e3a7aSWarner Losh<pre> 31408e3e3a7aSWarner Losh static void *l_alloc (void *ud, void *ptr, size_t osize, 31418e3e3a7aSWarner Losh size_t nsize) { 31428e3e3a7aSWarner Losh (void)ud; (void)osize; /* not used */ 31438e3e3a7aSWarner Losh if (nsize == 0) { 31448e3e3a7aSWarner Losh free(ptr); 31458e3e3a7aSWarner Losh return NULL; 31468e3e3a7aSWarner Losh } 31478e3e3a7aSWarner Losh else 31488e3e3a7aSWarner Losh return realloc(ptr, nsize); 31498e3e3a7aSWarner Losh } 31508e3e3a7aSWarner Losh</pre><p> 31518e3e3a7aSWarner LoshNote that Standard C ensures 31528e3e3a7aSWarner Loshthat <code>free(NULL)</code> has no effect and that 31538e3e3a7aSWarner Losh<code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>. 31548e3e3a7aSWarner LoshThis code assumes that <code>realloc</code> does not fail when shrinking a block. 31558e3e3a7aSWarner Losh(Although Standard C does not ensure this behavior, 31568e3e3a7aSWarner Loshit seems to be a safe assumption.) 31578e3e3a7aSWarner Losh 31588e3e3a7aSWarner Losh 31598e3e3a7aSWarner Losh 31608e3e3a7aSWarner Losh 31618e3e3a7aSWarner Losh 31628e3e3a7aSWarner Losh<hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p> 31638e3e3a7aSWarner Losh<span class="apii">[-(2|1), +1, <em>e</em>]</span> 31648e3e3a7aSWarner Losh<pre>void lua_arith (lua_State *L, int op);</pre> 31658e3e3a7aSWarner Losh 31668e3e3a7aSWarner Losh<p> 31678e3e3a7aSWarner LoshPerforms an arithmetic or bitwise operation over the two values 31688e3e3a7aSWarner Losh(or one, in the case of negations) 31698e3e3a7aSWarner Loshat the top of the stack, 31708e3e3a7aSWarner Loshwith the value at the top being the second operand, 31718e3e3a7aSWarner Loshpops these values, and pushes the result of the operation. 31728e3e3a7aSWarner LoshThe function follows the semantics of the corresponding Lua operator 31738e3e3a7aSWarner Losh(that is, it may call metamethods). 31748e3e3a7aSWarner Losh 31758e3e3a7aSWarner Losh 31768e3e3a7aSWarner Losh<p> 31778e3e3a7aSWarner LoshThe value of <code>op</code> must be one of the following constants: 31788e3e3a7aSWarner Losh 31798e3e3a7aSWarner Losh<ul> 31808e3e3a7aSWarner Losh 31818e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li> 31828e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li> 31838e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li> 31848e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li> 31858e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li> 31868e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li> 31878e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li> 31888e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li> 31898e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li> 31908e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&</code>)</li> 31918e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li> 31928e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li> 31938e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li> 31948e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li> 31958e3e3a7aSWarner Losh 31968e3e3a7aSWarner Losh</ul> 31978e3e3a7aSWarner Losh 31988e3e3a7aSWarner Losh 31998e3e3a7aSWarner Losh 32008e3e3a7aSWarner Losh 32018e3e3a7aSWarner Losh<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> 32028e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 32038e3e3a7aSWarner Losh<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> 32048e3e3a7aSWarner Losh 32058e3e3a7aSWarner Losh<p> 32068e3e3a7aSWarner LoshSets a new panic function and returns the old one (see <a href="#4.6">§4.6</a>). 32078e3e3a7aSWarner Losh 32088e3e3a7aSWarner Losh 32098e3e3a7aSWarner Losh 32108e3e3a7aSWarner Losh 32118e3e3a7aSWarner Losh 32128e3e3a7aSWarner Losh<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> 32138e3e3a7aSWarner Losh<span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span> 32148e3e3a7aSWarner Losh<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> 32158e3e3a7aSWarner Losh 32168e3e3a7aSWarner Losh<p> 32178e3e3a7aSWarner LoshCalls a function. 32188e3e3a7aSWarner Losh 32198e3e3a7aSWarner Losh 32208e3e3a7aSWarner Losh<p> 32218e3e3a7aSWarner LoshTo call a function you must use the following protocol: 32228e3e3a7aSWarner Loshfirst, the function to be called is pushed onto the stack; 32238e3e3a7aSWarner Loshthen, the arguments to the function are pushed 32248e3e3a7aSWarner Loshin direct order; 32258e3e3a7aSWarner Loshthat is, the first argument is pushed first. 32268e3e3a7aSWarner LoshFinally you call <a href="#lua_call"><code>lua_call</code></a>; 32278e3e3a7aSWarner Losh<code>nargs</code> is the number of arguments that you pushed onto the stack. 32288e3e3a7aSWarner LoshAll arguments and the function value are popped from the stack 32298e3e3a7aSWarner Loshwhen the function is called. 32308e3e3a7aSWarner LoshThe function results are pushed onto the stack when the function returns. 32318e3e3a7aSWarner LoshThe number of results is adjusted to <code>nresults</code>, 32328e3e3a7aSWarner Loshunless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. 32338e3e3a7aSWarner LoshIn this case, all results from the function are pushed; 32348e3e3a7aSWarner LoshLua takes care that the returned values fit into the stack space, 32358e3e3a7aSWarner Loshbut it does not ensure any extra space in the stack. 32368e3e3a7aSWarner LoshThe function results are pushed onto the stack in direct order 32378e3e3a7aSWarner Losh(the first result is pushed first), 32388e3e3a7aSWarner Loshso that after the call the last result is on the top of the stack. 32398e3e3a7aSWarner Losh 32408e3e3a7aSWarner Losh 32418e3e3a7aSWarner Losh<p> 32428e3e3a7aSWarner LoshAny error inside the called function is propagated upwards 32438e3e3a7aSWarner Losh(with a <code>longjmp</code>). 32448e3e3a7aSWarner Losh 32458e3e3a7aSWarner Losh 32468e3e3a7aSWarner Losh<p> 32478e3e3a7aSWarner LoshThe following example shows how the host program can do the 32488e3e3a7aSWarner Loshequivalent to this Lua code: 32498e3e3a7aSWarner Losh 32508e3e3a7aSWarner Losh<pre> 32518e3e3a7aSWarner Losh a = f("how", t.x, 14) 32528e3e3a7aSWarner Losh</pre><p> 32538e3e3a7aSWarner LoshHere it is in C: 32548e3e3a7aSWarner Losh 32558e3e3a7aSWarner Losh<pre> 32568e3e3a7aSWarner Losh lua_getglobal(L, "f"); /* function to be called */ 32578e3e3a7aSWarner Losh lua_pushliteral(L, "how"); /* 1st argument */ 32588e3e3a7aSWarner Losh lua_getglobal(L, "t"); /* table to be indexed */ 32598e3e3a7aSWarner Losh lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 32608e3e3a7aSWarner Losh lua_remove(L, -2); /* remove 't' from the stack */ 32618e3e3a7aSWarner Losh lua_pushinteger(L, 14); /* 3rd argument */ 32628e3e3a7aSWarner Losh lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ 32638e3e3a7aSWarner Losh lua_setglobal(L, "a"); /* set global 'a' */ 32648e3e3a7aSWarner Losh</pre><p> 32658e3e3a7aSWarner LoshNote that the code above is <em>balanced</em>: 32668e3e3a7aSWarner Loshat its end, the stack is back to its original configuration. 32678e3e3a7aSWarner LoshThis is considered good programming practice. 32688e3e3a7aSWarner Losh 32698e3e3a7aSWarner Losh 32708e3e3a7aSWarner Losh 32718e3e3a7aSWarner Losh 32728e3e3a7aSWarner Losh 32738e3e3a7aSWarner Losh<hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p> 32748e3e3a7aSWarner Losh<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> 32758e3e3a7aSWarner Losh<pre>void lua_callk (lua_State *L, 32768e3e3a7aSWarner Losh int nargs, 32778e3e3a7aSWarner Losh int nresults, 32788e3e3a7aSWarner Losh lua_KContext ctx, 32798e3e3a7aSWarner Losh lua_KFunction k);</pre> 32808e3e3a7aSWarner Losh 32818e3e3a7aSWarner Losh<p> 32828e3e3a7aSWarner LoshThis function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>, 32838e3e3a7aSWarner Loshbut allows the called function to yield (see <a href="#4.7">§4.7</a>). 32848e3e3a7aSWarner Losh 32858e3e3a7aSWarner Losh 32868e3e3a7aSWarner Losh 32878e3e3a7aSWarner Losh 32888e3e3a7aSWarner Losh 32898e3e3a7aSWarner Losh<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> 32908e3e3a7aSWarner Losh<pre>typedef int (*lua_CFunction) (lua_State *L);</pre> 32918e3e3a7aSWarner Losh 32928e3e3a7aSWarner Losh<p> 32938e3e3a7aSWarner LoshType for C functions. 32948e3e3a7aSWarner Losh 32958e3e3a7aSWarner Losh 32968e3e3a7aSWarner Losh<p> 32978e3e3a7aSWarner LoshIn order to communicate properly with Lua, 32988e3e3a7aSWarner Losha C function must use the following protocol, 32998e3e3a7aSWarner Loshwhich defines the way parameters and results are passed: 33008e3e3a7aSWarner Losha C function receives its arguments from Lua in its stack 33018e3e3a7aSWarner Loshin direct order (the first argument is pushed first). 33028e3e3a7aSWarner LoshSo, when the function starts, 33038e3e3a7aSWarner Losh<code>lua_gettop(L)</code> returns the number of arguments received by the function. 33048e3e3a7aSWarner LoshThe first argument (if any) is at index 1 33058e3e3a7aSWarner Loshand its last argument is at index <code>lua_gettop(L)</code>. 33068e3e3a7aSWarner LoshTo return values to Lua, a C function just pushes them onto the stack, 33078e3e3a7aSWarner Loshin direct order (the first result is pushed first), 33088e3e3a7aSWarner Loshand returns the number of results. 33098e3e3a7aSWarner LoshAny other value in the stack below the results will be properly 33108e3e3a7aSWarner Loshdiscarded by Lua. 33118e3e3a7aSWarner LoshLike a Lua function, a C function called by Lua can also return 33128e3e3a7aSWarner Loshmany results. 33138e3e3a7aSWarner Losh 33148e3e3a7aSWarner Losh 33158e3e3a7aSWarner Losh<p> 33168e3e3a7aSWarner LoshAs an example, the following function receives a variable number 33178e3e3a7aSWarner Loshof numeric arguments and returns their average and their sum: 33188e3e3a7aSWarner Losh 33198e3e3a7aSWarner Losh<pre> 33208e3e3a7aSWarner Losh static int foo (lua_State *L) { 33218e3e3a7aSWarner Losh int n = lua_gettop(L); /* number of arguments */ 33228e3e3a7aSWarner Losh lua_Number sum = 0.0; 33238e3e3a7aSWarner Losh int i; 33248e3e3a7aSWarner Losh for (i = 1; i <= n; i++) { 33258e3e3a7aSWarner Losh if (!lua_isnumber(L, i)) { 33268e3e3a7aSWarner Losh lua_pushliteral(L, "incorrect argument"); 33278e3e3a7aSWarner Losh lua_error(L); 33288e3e3a7aSWarner Losh } 33298e3e3a7aSWarner Losh sum += lua_tonumber(L, i); 33308e3e3a7aSWarner Losh } 33318e3e3a7aSWarner Losh lua_pushnumber(L, sum/n); /* first result */ 33328e3e3a7aSWarner Losh lua_pushnumber(L, sum); /* second result */ 33338e3e3a7aSWarner Losh return 2; /* number of results */ 33348e3e3a7aSWarner Losh } 33358e3e3a7aSWarner Losh</pre> 33368e3e3a7aSWarner Losh 33378e3e3a7aSWarner Losh 33388e3e3a7aSWarner Losh 33398e3e3a7aSWarner Losh 33408e3e3a7aSWarner Losh<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> 33418e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 33428e3e3a7aSWarner Losh<pre>int lua_checkstack (lua_State *L, int n);</pre> 33438e3e3a7aSWarner Losh 33448e3e3a7aSWarner Losh<p> 33458e3e3a7aSWarner LoshEnsures that the stack has space for at least <code>n</code> extra slots 33468e3e3a7aSWarner Losh(that is, that you can safely push up to <code>n</code> values into it). 33478e3e3a7aSWarner LoshIt returns false if it cannot fulfill the request, 33488e3e3a7aSWarner Losheither because it would cause the stack 33498e3e3a7aSWarner Loshto be larger than a fixed maximum size 33508e3e3a7aSWarner Losh(typically at least several thousand elements) or 33518e3e3a7aSWarner Loshbecause it cannot allocate memory for the extra space. 33528e3e3a7aSWarner LoshThis function never shrinks the stack; 33538e3e3a7aSWarner Loshif the stack already has space for the extra slots, 33548e3e3a7aSWarner Loshit is left unchanged. 33558e3e3a7aSWarner Losh 33568e3e3a7aSWarner Losh 33578e3e3a7aSWarner Losh 33588e3e3a7aSWarner Losh 33598e3e3a7aSWarner Losh 33608e3e3a7aSWarner Losh<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> 33618e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 33628e3e3a7aSWarner Losh<pre>void lua_close (lua_State *L);</pre> 33638e3e3a7aSWarner Losh 33648e3e3a7aSWarner Losh<p> 33658e3e3a7aSWarner LoshDestroys all objects in the given Lua state 33668e3e3a7aSWarner Losh(calling the corresponding garbage-collection metamethods, if any) 33678e3e3a7aSWarner Loshand frees all dynamic memory used by this state. 3368*e112e9d2SKyle EvansIn several platforms, you may not need to call this function, 33698e3e3a7aSWarner Loshbecause all resources are naturally released when the host program ends. 33708e3e3a7aSWarner LoshOn the other hand, long-running programs that create multiple states, 33718e3e3a7aSWarner Loshsuch as daemons or web servers, 33728e3e3a7aSWarner Loshwill probably need to close states as soon as they are not needed. 33738e3e3a7aSWarner Losh 33748e3e3a7aSWarner Losh 33758e3e3a7aSWarner Losh 33768e3e3a7aSWarner Losh 33778e3e3a7aSWarner Losh 33788e3e3a7aSWarner Losh<hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p> 33798e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 33808e3e3a7aSWarner Losh<pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre> 33818e3e3a7aSWarner Losh 33828e3e3a7aSWarner Losh<p> 33838e3e3a7aSWarner LoshCompares two Lua values. 33848e3e3a7aSWarner LoshReturns 1 if the value at index <code>index1</code> satisfies <code>op</code> 33858e3e3a7aSWarner Loshwhen compared with the value at index <code>index2</code>, 33868e3e3a7aSWarner Loshfollowing the semantics of the corresponding Lua operator 33878e3e3a7aSWarner Losh(that is, it may call metamethods). 33888e3e3a7aSWarner LoshOtherwise returns 0. 33898e3e3a7aSWarner LoshAlso returns 0 if any of the indices is not valid. 33908e3e3a7aSWarner Losh 33918e3e3a7aSWarner Losh 33928e3e3a7aSWarner Losh<p> 33938e3e3a7aSWarner LoshThe value of <code>op</code> must be one of the following constants: 33948e3e3a7aSWarner Losh 33958e3e3a7aSWarner Losh<ul> 33968e3e3a7aSWarner Losh 33978e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li> 33988e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li> 33998e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li> 34008e3e3a7aSWarner Losh 34018e3e3a7aSWarner Losh</ul> 34028e3e3a7aSWarner Losh 34038e3e3a7aSWarner Losh 34048e3e3a7aSWarner Losh 34058e3e3a7aSWarner Losh 34068e3e3a7aSWarner Losh<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> 34078e3e3a7aSWarner Losh<span class="apii">[-n, +1, <em>e</em>]</span> 34088e3e3a7aSWarner Losh<pre>void lua_concat (lua_State *L, int n);</pre> 34098e3e3a7aSWarner Losh 34108e3e3a7aSWarner Losh<p> 34118e3e3a7aSWarner LoshConcatenates the <code>n</code> values at the top of the stack, 34128e3e3a7aSWarner Loshpops them, and leaves the result at the top. 34138e3e3a7aSWarner LoshIf <code>n</code> is 1, the result is the single value on the stack 34148e3e3a7aSWarner Losh(that is, the function does nothing); 34158e3e3a7aSWarner Loshif <code>n</code> is 0, the result is the empty string. 34168e3e3a7aSWarner LoshConcatenation is performed following the usual semantics of Lua 34178e3e3a7aSWarner Losh(see <a href="#3.4.6">§3.4.6</a>). 34188e3e3a7aSWarner Losh 34198e3e3a7aSWarner Losh 34208e3e3a7aSWarner Losh 34218e3e3a7aSWarner Losh 34228e3e3a7aSWarner Losh 34238e3e3a7aSWarner Losh<hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p> 34248e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 34258e3e3a7aSWarner Losh<pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre> 34268e3e3a7aSWarner Losh 34278e3e3a7aSWarner Losh<p> 34288e3e3a7aSWarner LoshCopies the element at index <code>fromidx</code> 34298e3e3a7aSWarner Loshinto the valid index <code>toidx</code>, 34308e3e3a7aSWarner Loshreplacing the value at that position. 34318e3e3a7aSWarner LoshValues at other positions are not affected. 34328e3e3a7aSWarner Losh 34338e3e3a7aSWarner Losh 34348e3e3a7aSWarner Losh 34358e3e3a7aSWarner Losh 34368e3e3a7aSWarner Losh 34378e3e3a7aSWarner Losh<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> 34388e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 34398e3e3a7aSWarner Losh<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> 34408e3e3a7aSWarner Losh 34418e3e3a7aSWarner Losh<p> 34428e3e3a7aSWarner LoshCreates a new empty table and pushes it onto the stack. 34438e3e3a7aSWarner LoshParameter <code>narr</code> is a hint for how many elements the table 34448e3e3a7aSWarner Loshwill have as a sequence; 34458e3e3a7aSWarner Loshparameter <code>nrec</code> is a hint for how many other elements 34468e3e3a7aSWarner Loshthe table will have. 34478e3e3a7aSWarner LoshLua may use these hints to preallocate memory for the new table. 34488e3e3a7aSWarner LoshThis preallocation is useful for performance when you know in advance 34498e3e3a7aSWarner Loshhow many elements the table will have. 34508e3e3a7aSWarner LoshOtherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. 34518e3e3a7aSWarner Losh 34528e3e3a7aSWarner Losh 34538e3e3a7aSWarner Losh 34548e3e3a7aSWarner Losh 34558e3e3a7aSWarner Losh 34568e3e3a7aSWarner Losh<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> 34578e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 34588e3e3a7aSWarner Losh<pre>int lua_dump (lua_State *L, 34598e3e3a7aSWarner Losh lua_Writer writer, 34608e3e3a7aSWarner Losh void *data, 34618e3e3a7aSWarner Losh int strip);</pre> 34628e3e3a7aSWarner Losh 34638e3e3a7aSWarner Losh<p> 34648e3e3a7aSWarner LoshDumps a function as a binary chunk. 34658e3e3a7aSWarner LoshReceives a Lua function on the top of the stack 34668e3e3a7aSWarner Loshand produces a binary chunk that, 34678e3e3a7aSWarner Loshif loaded again, 34688e3e3a7aSWarner Loshresults in a function equivalent to the one dumped. 34698e3e3a7aSWarner LoshAs it produces parts of the chunk, 34708e3e3a7aSWarner Losh<a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>) 34718e3e3a7aSWarner Loshwith the given <code>data</code> 34728e3e3a7aSWarner Loshto write them. 34738e3e3a7aSWarner Losh 34748e3e3a7aSWarner Losh 34758e3e3a7aSWarner Losh<p> 34768e3e3a7aSWarner LoshIf <code>strip</code> is true, 34778e3e3a7aSWarner Loshthe binary representation may not include all debug information 34788e3e3a7aSWarner Loshabout the function, 34798e3e3a7aSWarner Loshto save space. 34808e3e3a7aSWarner Losh 34818e3e3a7aSWarner Losh 34828e3e3a7aSWarner Losh<p> 34838e3e3a7aSWarner LoshThe value returned is the error code returned by the last 34848e3e3a7aSWarner Loshcall to the writer; 34858e3e3a7aSWarner Losh0 means no errors. 34868e3e3a7aSWarner Losh 34878e3e3a7aSWarner Losh 34888e3e3a7aSWarner Losh<p> 34898e3e3a7aSWarner LoshThis function does not pop the Lua function from the stack. 34908e3e3a7aSWarner Losh 34918e3e3a7aSWarner Losh 34928e3e3a7aSWarner Losh 34938e3e3a7aSWarner Losh 34948e3e3a7aSWarner Losh 34958e3e3a7aSWarner Losh<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> 34968e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>v</em>]</span> 34978e3e3a7aSWarner Losh<pre>int lua_error (lua_State *L);</pre> 34988e3e3a7aSWarner Losh 34998e3e3a7aSWarner Losh<p> 35008e3e3a7aSWarner LoshGenerates a Lua error, 35018e3e3a7aSWarner Loshusing the value at the top of the stack as the error object. 35028e3e3a7aSWarner LoshThis function does a long jump, 35038e3e3a7aSWarner Loshand therefore never returns 35048e3e3a7aSWarner Losh(see <a href="#luaL_error"><code>luaL_error</code></a>). 35058e3e3a7aSWarner Losh 35068e3e3a7aSWarner Losh 35078e3e3a7aSWarner Losh 35088e3e3a7aSWarner Losh 35098e3e3a7aSWarner Losh 35108e3e3a7aSWarner Losh<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> 35118e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span> 35128e3e3a7aSWarner Losh<pre>int lua_gc (lua_State *L, int what, int data);</pre> 35138e3e3a7aSWarner Losh 35148e3e3a7aSWarner Losh<p> 35158e3e3a7aSWarner LoshControls the garbage collector. 35168e3e3a7aSWarner Losh 35178e3e3a7aSWarner Losh 35188e3e3a7aSWarner Losh<p> 35198e3e3a7aSWarner LoshThis function performs several tasks, 35208e3e3a7aSWarner Loshaccording to the value of the parameter <code>what</code>: 35218e3e3a7aSWarner Losh 35228e3e3a7aSWarner Losh<ul> 35238e3e3a7aSWarner Losh 35248e3e3a7aSWarner Losh<li><b><code>LUA_GCSTOP</code>: </b> 35258e3e3a7aSWarner Loshstops the garbage collector. 35268e3e3a7aSWarner Losh</li> 35278e3e3a7aSWarner Losh 35288e3e3a7aSWarner Losh<li><b><code>LUA_GCRESTART</code>: </b> 35298e3e3a7aSWarner Loshrestarts the garbage collector. 35308e3e3a7aSWarner Losh</li> 35318e3e3a7aSWarner Losh 35328e3e3a7aSWarner Losh<li><b><code>LUA_GCCOLLECT</code>: </b> 35338e3e3a7aSWarner Loshperforms a full garbage-collection cycle. 35348e3e3a7aSWarner Losh</li> 35358e3e3a7aSWarner Losh 35368e3e3a7aSWarner Losh<li><b><code>LUA_GCCOUNT</code>: </b> 35378e3e3a7aSWarner Loshreturns the current amount of memory (in Kbytes) in use by Lua. 35388e3e3a7aSWarner Losh</li> 35398e3e3a7aSWarner Losh 35408e3e3a7aSWarner Losh<li><b><code>LUA_GCCOUNTB</code>: </b> 35418e3e3a7aSWarner Loshreturns the remainder of dividing the current amount of bytes of 35428e3e3a7aSWarner Loshmemory in use by Lua by 1024. 35438e3e3a7aSWarner Losh</li> 35448e3e3a7aSWarner Losh 35458e3e3a7aSWarner Losh<li><b><code>LUA_GCSTEP</code>: </b> 35468e3e3a7aSWarner Loshperforms an incremental step of garbage collection. 35478e3e3a7aSWarner Losh</li> 35488e3e3a7aSWarner Losh 35498e3e3a7aSWarner Losh<li><b><code>LUA_GCSETPAUSE</code>: </b> 35508e3e3a7aSWarner Loshsets <code>data</code> as the new value 35518e3e3a7aSWarner Loshfor the <em>pause</em> of the collector (see <a href="#2.5">§2.5</a>) 35528e3e3a7aSWarner Loshand returns the previous value of the pause. 35538e3e3a7aSWarner Losh</li> 35548e3e3a7aSWarner Losh 35558e3e3a7aSWarner Losh<li><b><code>LUA_GCSETSTEPMUL</code>: </b> 35568e3e3a7aSWarner Loshsets <code>data</code> as the new value for the <em>step multiplier</em> of 35578e3e3a7aSWarner Loshthe collector (see <a href="#2.5">§2.5</a>) 35588e3e3a7aSWarner Loshand returns the previous value of the step multiplier. 35598e3e3a7aSWarner Losh</li> 35608e3e3a7aSWarner Losh 35618e3e3a7aSWarner Losh<li><b><code>LUA_GCISRUNNING</code>: </b> 35628e3e3a7aSWarner Loshreturns a boolean that tells whether the collector is running 35638e3e3a7aSWarner Losh(i.e., not stopped). 35648e3e3a7aSWarner Losh</li> 35658e3e3a7aSWarner Losh 35668e3e3a7aSWarner Losh</ul> 35678e3e3a7aSWarner Losh 35688e3e3a7aSWarner Losh<p> 35698e3e3a7aSWarner LoshFor more details about these options, 35708e3e3a7aSWarner Loshsee <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>. 35718e3e3a7aSWarner Losh 35728e3e3a7aSWarner Losh 35738e3e3a7aSWarner Losh 35748e3e3a7aSWarner Losh 35758e3e3a7aSWarner Losh 35768e3e3a7aSWarner Losh<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> 35778e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 35788e3e3a7aSWarner Losh<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> 35798e3e3a7aSWarner Losh 35808e3e3a7aSWarner Losh<p> 35818e3e3a7aSWarner LoshReturns the memory-allocation function of a given state. 35828e3e3a7aSWarner LoshIf <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the 35838e3e3a7aSWarner Loshopaque pointer given when the memory-allocator function was set. 35848e3e3a7aSWarner Losh 35858e3e3a7aSWarner Losh 35868e3e3a7aSWarner Losh 35878e3e3a7aSWarner Losh 35888e3e3a7aSWarner Losh 35898e3e3a7aSWarner Losh<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> 35908e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 35918e3e3a7aSWarner Losh<pre>int lua_getfield (lua_State *L, int index, const char *k);</pre> 35928e3e3a7aSWarner Losh 35938e3e3a7aSWarner Losh<p> 35948e3e3a7aSWarner LoshPushes onto the stack the value <code>t[k]</code>, 35958e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index. 35968e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 35978e3e3a7aSWarner Loshfor the "index" event (see <a href="#2.4">§2.4</a>). 35988e3e3a7aSWarner Losh 35998e3e3a7aSWarner Losh 36008e3e3a7aSWarner Losh<p> 36018e3e3a7aSWarner LoshReturns the type of the pushed value. 36028e3e3a7aSWarner Losh 36038e3e3a7aSWarner Losh 36048e3e3a7aSWarner Losh 36058e3e3a7aSWarner Losh 36068e3e3a7aSWarner Losh 36078e3e3a7aSWarner Losh<hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p> 36088e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 36098e3e3a7aSWarner Losh<pre>void *lua_getextraspace (lua_State *L);</pre> 36108e3e3a7aSWarner Losh 36118e3e3a7aSWarner Losh<p> 36128e3e3a7aSWarner LoshReturns a pointer to a raw memory area associated with the 36138e3e3a7aSWarner Loshgiven Lua state. 36148e3e3a7aSWarner LoshThe application can use this area for any purpose; 36158e3e3a7aSWarner LoshLua does not use it for anything. 36168e3e3a7aSWarner Losh 36178e3e3a7aSWarner Losh 36188e3e3a7aSWarner Losh<p> 36198e3e3a7aSWarner LoshEach new thread has this area initialized with a copy 36208e3e3a7aSWarner Loshof the area of the main thread. 36218e3e3a7aSWarner Losh 36228e3e3a7aSWarner Losh 36238e3e3a7aSWarner Losh<p> 36248e3e3a7aSWarner LoshBy default, this area has the size of a pointer to void, 36258e3e3a7aSWarner Loshbut you can recompile Lua with a different size for this area. 36268e3e3a7aSWarner Losh(See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.) 36278e3e3a7aSWarner Losh 36288e3e3a7aSWarner Losh 36298e3e3a7aSWarner Losh 36308e3e3a7aSWarner Losh 36318e3e3a7aSWarner Losh 36328e3e3a7aSWarner Losh<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> 36338e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 36348e3e3a7aSWarner Losh<pre>int lua_getglobal (lua_State *L, const char *name);</pre> 36358e3e3a7aSWarner Losh 36368e3e3a7aSWarner Losh<p> 36378e3e3a7aSWarner LoshPushes onto the stack the value of the global <code>name</code>. 36388e3e3a7aSWarner LoshReturns the type of that value. 36398e3e3a7aSWarner Losh 36408e3e3a7aSWarner Losh 36418e3e3a7aSWarner Losh 36428e3e3a7aSWarner Losh 36438e3e3a7aSWarner Losh 36448e3e3a7aSWarner Losh<hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p> 36458e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 36468e3e3a7aSWarner Losh<pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre> 36478e3e3a7aSWarner Losh 36488e3e3a7aSWarner Losh<p> 36498e3e3a7aSWarner LoshPushes onto the stack the value <code>t[i]</code>, 36508e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index. 36518e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 36528e3e3a7aSWarner Loshfor the "index" event (see <a href="#2.4">§2.4</a>). 36538e3e3a7aSWarner Losh 36548e3e3a7aSWarner Losh 36558e3e3a7aSWarner Losh<p> 36568e3e3a7aSWarner LoshReturns the type of the pushed value. 36578e3e3a7aSWarner Losh 36588e3e3a7aSWarner Losh 36598e3e3a7aSWarner Losh 36608e3e3a7aSWarner Losh 36618e3e3a7aSWarner Losh 36628e3e3a7aSWarner Losh<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> 36638e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), –]</span> 36648e3e3a7aSWarner Losh<pre>int lua_getmetatable (lua_State *L, int index);</pre> 36658e3e3a7aSWarner Losh 36668e3e3a7aSWarner Losh<p> 36678e3e3a7aSWarner LoshIf the value at the given index has a metatable, 36688e3e3a7aSWarner Loshthe function pushes that metatable onto the stack and returns 1. 36698e3e3a7aSWarner LoshOtherwise, 36708e3e3a7aSWarner Loshthe function returns 0 and pushes nothing on the stack. 36718e3e3a7aSWarner Losh 36728e3e3a7aSWarner Losh 36738e3e3a7aSWarner Losh 36748e3e3a7aSWarner Losh 36758e3e3a7aSWarner Losh 36768e3e3a7aSWarner Losh<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> 36778e3e3a7aSWarner Losh<span class="apii">[-1, +1, <em>e</em>]</span> 36788e3e3a7aSWarner Losh<pre>int lua_gettable (lua_State *L, int index);</pre> 36798e3e3a7aSWarner Losh 36808e3e3a7aSWarner Losh<p> 36818e3e3a7aSWarner LoshPushes onto the stack the value <code>t[k]</code>, 36828e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index 36838e3e3a7aSWarner Loshand <code>k</code> is the value at the top of the stack. 36848e3e3a7aSWarner Losh 36858e3e3a7aSWarner Losh 36868e3e3a7aSWarner Losh<p> 36878e3e3a7aSWarner LoshThis function pops the key from the stack, 36888e3e3a7aSWarner Loshpushing the resulting value in its place. 36898e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 36908e3e3a7aSWarner Loshfor the "index" event (see <a href="#2.4">§2.4</a>). 36918e3e3a7aSWarner Losh 36928e3e3a7aSWarner Losh 36938e3e3a7aSWarner Losh<p> 36948e3e3a7aSWarner LoshReturns the type of the pushed value. 36958e3e3a7aSWarner Losh 36968e3e3a7aSWarner Losh 36978e3e3a7aSWarner Losh 36988e3e3a7aSWarner Losh 36998e3e3a7aSWarner Losh 37008e3e3a7aSWarner Losh<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> 37018e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 37028e3e3a7aSWarner Losh<pre>int lua_gettop (lua_State *L);</pre> 37038e3e3a7aSWarner Losh 37048e3e3a7aSWarner Losh<p> 37058e3e3a7aSWarner LoshReturns the index of the top element in the stack. 37068e3e3a7aSWarner LoshBecause indices start at 1, 37078e3e3a7aSWarner Loshthis result is equal to the number of elements in the stack; 37088e3e3a7aSWarner Loshin particular, 0 means an empty stack. 37098e3e3a7aSWarner Losh 37108e3e3a7aSWarner Losh 37118e3e3a7aSWarner Losh 37128e3e3a7aSWarner Losh 37138e3e3a7aSWarner Losh 37148e3e3a7aSWarner Losh<hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p> 37158e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 37168e3e3a7aSWarner Losh<pre>int lua_getuservalue (lua_State *L, int index);</pre> 37178e3e3a7aSWarner Losh 37188e3e3a7aSWarner Losh<p> 37198e3e3a7aSWarner LoshPushes onto the stack the Lua value associated with the full userdata 37208e3e3a7aSWarner Loshat the given index. 37218e3e3a7aSWarner Losh 37228e3e3a7aSWarner Losh 37238e3e3a7aSWarner Losh<p> 37248e3e3a7aSWarner LoshReturns the type of the pushed value. 37258e3e3a7aSWarner Losh 37268e3e3a7aSWarner Losh 37278e3e3a7aSWarner Losh 37288e3e3a7aSWarner Losh 37298e3e3a7aSWarner Losh 37308e3e3a7aSWarner Losh<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> 37318e3e3a7aSWarner Losh<span class="apii">[-1, +1, –]</span> 37328e3e3a7aSWarner Losh<pre>void lua_insert (lua_State *L, int index);</pre> 37338e3e3a7aSWarner Losh 37348e3e3a7aSWarner Losh<p> 37358e3e3a7aSWarner LoshMoves the top element into the given valid index, 37368e3e3a7aSWarner Loshshifting up the elements above this index to open space. 37378e3e3a7aSWarner LoshThis function cannot be called with a pseudo-index, 37388e3e3a7aSWarner Loshbecause a pseudo-index is not an actual stack position. 37398e3e3a7aSWarner Losh 37408e3e3a7aSWarner Losh 37418e3e3a7aSWarner Losh 37428e3e3a7aSWarner Losh 37438e3e3a7aSWarner Losh 37448e3e3a7aSWarner Losh<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> 37458e3e3a7aSWarner Losh<pre>typedef ... lua_Integer;</pre> 37468e3e3a7aSWarner Losh 37478e3e3a7aSWarner Losh<p> 37488e3e3a7aSWarner LoshThe type of integers in Lua. 37498e3e3a7aSWarner Losh 37508e3e3a7aSWarner Losh 37518e3e3a7aSWarner Losh<p> 37528e3e3a7aSWarner LoshBy default this type is <code>long long</code>, 37538e3e3a7aSWarner Losh(usually a 64-bit two-complement integer), 37548e3e3a7aSWarner Loshbut that can be changed to <code>long</code> or <code>int</code> 37558e3e3a7aSWarner Losh(usually a 32-bit two-complement integer). 37568e3e3a7aSWarner Losh(See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.) 37578e3e3a7aSWarner Losh 37588e3e3a7aSWarner Losh 37598e3e3a7aSWarner Losh<p> 37608e3e3a7aSWarner LoshLua also defines the constants 37618e3e3a7aSWarner Losh<a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>, 37628e3e3a7aSWarner Loshwith the minimum and the maximum values that fit in this type. 37638e3e3a7aSWarner Losh 37648e3e3a7aSWarner Losh 37658e3e3a7aSWarner Losh 37668e3e3a7aSWarner Losh 37678e3e3a7aSWarner Losh 37688e3e3a7aSWarner Losh<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> 37698e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 37708e3e3a7aSWarner Losh<pre>int lua_isboolean (lua_State *L, int index);</pre> 37718e3e3a7aSWarner Losh 37728e3e3a7aSWarner Losh<p> 37738e3e3a7aSWarner LoshReturns 1 if the value at the given index is a boolean, 37748e3e3a7aSWarner Loshand 0 otherwise. 37758e3e3a7aSWarner Losh 37768e3e3a7aSWarner Losh 37778e3e3a7aSWarner Losh 37788e3e3a7aSWarner Losh 37798e3e3a7aSWarner Losh 37808e3e3a7aSWarner Losh<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> 37818e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 37828e3e3a7aSWarner Losh<pre>int lua_iscfunction (lua_State *L, int index);</pre> 37838e3e3a7aSWarner Losh 37848e3e3a7aSWarner Losh<p> 37858e3e3a7aSWarner LoshReturns 1 if the value at the given index is a C function, 37868e3e3a7aSWarner Loshand 0 otherwise. 37878e3e3a7aSWarner Losh 37888e3e3a7aSWarner Losh 37898e3e3a7aSWarner Losh 37908e3e3a7aSWarner Losh 37918e3e3a7aSWarner Losh 37928e3e3a7aSWarner Losh<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> 37938e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 37948e3e3a7aSWarner Losh<pre>int lua_isfunction (lua_State *L, int index);</pre> 37958e3e3a7aSWarner Losh 37968e3e3a7aSWarner Losh<p> 37978e3e3a7aSWarner LoshReturns 1 if the value at the given index is a function 37988e3e3a7aSWarner Losh(either C or Lua), and 0 otherwise. 37998e3e3a7aSWarner Losh 38008e3e3a7aSWarner Losh 38018e3e3a7aSWarner Losh 38028e3e3a7aSWarner Losh 38038e3e3a7aSWarner Losh 38048e3e3a7aSWarner Losh<hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p> 38058e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 38068e3e3a7aSWarner Losh<pre>int lua_isinteger (lua_State *L, int index);</pre> 38078e3e3a7aSWarner Losh 38088e3e3a7aSWarner Losh<p> 38098e3e3a7aSWarner LoshReturns 1 if the value at the given index is an integer 38108e3e3a7aSWarner Losh(that is, the value is a number and is represented as an integer), 38118e3e3a7aSWarner Loshand 0 otherwise. 38128e3e3a7aSWarner Losh 38138e3e3a7aSWarner Losh 38148e3e3a7aSWarner Losh 38158e3e3a7aSWarner Losh 38168e3e3a7aSWarner Losh 38178e3e3a7aSWarner Losh<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> 38188e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 38198e3e3a7aSWarner Losh<pre>int lua_islightuserdata (lua_State *L, int index);</pre> 38208e3e3a7aSWarner Losh 38218e3e3a7aSWarner Losh<p> 38228e3e3a7aSWarner LoshReturns 1 if the value at the given index is a light userdata, 38238e3e3a7aSWarner Loshand 0 otherwise. 38248e3e3a7aSWarner Losh 38258e3e3a7aSWarner Losh 38268e3e3a7aSWarner Losh 38278e3e3a7aSWarner Losh 38288e3e3a7aSWarner Losh 38298e3e3a7aSWarner Losh<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> 38308e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 38318e3e3a7aSWarner Losh<pre>int lua_isnil (lua_State *L, int index);</pre> 38328e3e3a7aSWarner Losh 38338e3e3a7aSWarner Losh<p> 38348e3e3a7aSWarner LoshReturns 1 if the value at the given index is <b>nil</b>, 38358e3e3a7aSWarner Loshand 0 otherwise. 38368e3e3a7aSWarner Losh 38378e3e3a7aSWarner Losh 38388e3e3a7aSWarner Losh 38398e3e3a7aSWarner Losh 38408e3e3a7aSWarner Losh 38418e3e3a7aSWarner Losh<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> 38428e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 38438e3e3a7aSWarner Losh<pre>int lua_isnone (lua_State *L, int index);</pre> 38448e3e3a7aSWarner Losh 38458e3e3a7aSWarner Losh<p> 38468e3e3a7aSWarner LoshReturns 1 if the given index is not valid, 38478e3e3a7aSWarner Loshand 0 otherwise. 38488e3e3a7aSWarner Losh 38498e3e3a7aSWarner Losh 38508e3e3a7aSWarner Losh 38518e3e3a7aSWarner Losh 38528e3e3a7aSWarner Losh 38538e3e3a7aSWarner Losh<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> 38548e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 38558e3e3a7aSWarner Losh<pre>int lua_isnoneornil (lua_State *L, int index);</pre> 38568e3e3a7aSWarner Losh 38578e3e3a7aSWarner Losh<p> 38588e3e3a7aSWarner LoshReturns 1 if the given index is not valid 38598e3e3a7aSWarner Loshor if the value at this index is <b>nil</b>, 38608e3e3a7aSWarner Loshand 0 otherwise. 38618e3e3a7aSWarner Losh 38628e3e3a7aSWarner Losh 38638e3e3a7aSWarner Losh 38648e3e3a7aSWarner Losh 38658e3e3a7aSWarner Losh 38668e3e3a7aSWarner Losh<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> 38678e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 38688e3e3a7aSWarner Losh<pre>int lua_isnumber (lua_State *L, int index);</pre> 38698e3e3a7aSWarner Losh 38708e3e3a7aSWarner Losh<p> 38718e3e3a7aSWarner LoshReturns 1 if the value at the given index is a number 38728e3e3a7aSWarner Loshor a string convertible to a number, 38738e3e3a7aSWarner Loshand 0 otherwise. 38748e3e3a7aSWarner Losh 38758e3e3a7aSWarner Losh 38768e3e3a7aSWarner Losh 38778e3e3a7aSWarner Losh 38788e3e3a7aSWarner Losh 38798e3e3a7aSWarner Losh<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> 38808e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 38818e3e3a7aSWarner Losh<pre>int lua_isstring (lua_State *L, int index);</pre> 38828e3e3a7aSWarner Losh 38838e3e3a7aSWarner Losh<p> 38848e3e3a7aSWarner LoshReturns 1 if the value at the given index is a string 38858e3e3a7aSWarner Loshor a number (which is always convertible to a string), 38868e3e3a7aSWarner Loshand 0 otherwise. 38878e3e3a7aSWarner Losh 38888e3e3a7aSWarner Losh 38898e3e3a7aSWarner Losh 38908e3e3a7aSWarner Losh 38918e3e3a7aSWarner Losh 38928e3e3a7aSWarner Losh<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> 38938e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 38948e3e3a7aSWarner Losh<pre>int lua_istable (lua_State *L, int index);</pre> 38958e3e3a7aSWarner Losh 38968e3e3a7aSWarner Losh<p> 38978e3e3a7aSWarner LoshReturns 1 if the value at the given index is a table, 38988e3e3a7aSWarner Loshand 0 otherwise. 38998e3e3a7aSWarner Losh 39008e3e3a7aSWarner Losh 39018e3e3a7aSWarner Losh 39028e3e3a7aSWarner Losh 39038e3e3a7aSWarner Losh 39048e3e3a7aSWarner Losh<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> 39058e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 39068e3e3a7aSWarner Losh<pre>int lua_isthread (lua_State *L, int index);</pre> 39078e3e3a7aSWarner Losh 39088e3e3a7aSWarner Losh<p> 39098e3e3a7aSWarner LoshReturns 1 if the value at the given index is a thread, 39108e3e3a7aSWarner Loshand 0 otherwise. 39118e3e3a7aSWarner Losh 39128e3e3a7aSWarner Losh 39138e3e3a7aSWarner Losh 39148e3e3a7aSWarner Losh 39158e3e3a7aSWarner Losh 39168e3e3a7aSWarner Losh<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> 39178e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 39188e3e3a7aSWarner Losh<pre>int lua_isuserdata (lua_State *L, int index);</pre> 39198e3e3a7aSWarner Losh 39208e3e3a7aSWarner Losh<p> 39218e3e3a7aSWarner LoshReturns 1 if the value at the given index is a userdata 39228e3e3a7aSWarner Losh(either full or light), and 0 otherwise. 39238e3e3a7aSWarner Losh 39248e3e3a7aSWarner Losh 39258e3e3a7aSWarner Losh 39268e3e3a7aSWarner Losh 39278e3e3a7aSWarner Losh 39288e3e3a7aSWarner Losh<hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p> 39298e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 39308e3e3a7aSWarner Losh<pre>int lua_isyieldable (lua_State *L);</pre> 39318e3e3a7aSWarner Losh 39328e3e3a7aSWarner Losh<p> 39338e3e3a7aSWarner LoshReturns 1 if the given coroutine can yield, 39348e3e3a7aSWarner Loshand 0 otherwise. 39358e3e3a7aSWarner Losh 39368e3e3a7aSWarner Losh 39378e3e3a7aSWarner Losh 39388e3e3a7aSWarner Losh 39398e3e3a7aSWarner Losh 39408e3e3a7aSWarner Losh<hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3> 39418e3e3a7aSWarner Losh<pre>typedef ... lua_KContext;</pre> 39428e3e3a7aSWarner Losh 39438e3e3a7aSWarner Losh<p> 39448e3e3a7aSWarner LoshThe type for continuation-function contexts. 39458e3e3a7aSWarner LoshIt must be a numeric type. 39468e3e3a7aSWarner LoshThis type is defined as <code>intptr_t</code> 39478e3e3a7aSWarner Loshwhen <code>intptr_t</code> is available, 39488e3e3a7aSWarner Loshso that it can store pointers too. 39498e3e3a7aSWarner LoshOtherwise, it is defined as <code>ptrdiff_t</code>. 39508e3e3a7aSWarner Losh 39518e3e3a7aSWarner Losh 39528e3e3a7aSWarner Losh 39538e3e3a7aSWarner Losh 39548e3e3a7aSWarner Losh 39558e3e3a7aSWarner Losh<hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3> 39568e3e3a7aSWarner Losh<pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre> 39578e3e3a7aSWarner Losh 39588e3e3a7aSWarner Losh<p> 39598e3e3a7aSWarner LoshType for continuation functions (see <a href="#4.7">§4.7</a>). 39608e3e3a7aSWarner Losh 39618e3e3a7aSWarner Losh 39628e3e3a7aSWarner Losh 39638e3e3a7aSWarner Losh 39648e3e3a7aSWarner Losh 39658e3e3a7aSWarner Losh<hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p> 39668e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 39678e3e3a7aSWarner Losh<pre>void lua_len (lua_State *L, int index);</pre> 39688e3e3a7aSWarner Losh 39698e3e3a7aSWarner Losh<p> 39708e3e3a7aSWarner LoshReturns the length of the value at the given index. 39718e3e3a7aSWarner LoshIt is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>) and 39728e3e3a7aSWarner Loshmay trigger a metamethod for the "length" event (see <a href="#2.4">§2.4</a>). 39738e3e3a7aSWarner LoshThe result is pushed on the stack. 39748e3e3a7aSWarner Losh 39758e3e3a7aSWarner Losh 39768e3e3a7aSWarner Losh 39778e3e3a7aSWarner Losh 39788e3e3a7aSWarner Losh 39798e3e3a7aSWarner Losh<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> 39808e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 39818e3e3a7aSWarner Losh<pre>int lua_load (lua_State *L, 39828e3e3a7aSWarner Losh lua_Reader reader, 39838e3e3a7aSWarner Losh void *data, 39848e3e3a7aSWarner Losh const char *chunkname, 39858e3e3a7aSWarner Losh const char *mode);</pre> 39868e3e3a7aSWarner Losh 39878e3e3a7aSWarner Losh<p> 39888e3e3a7aSWarner LoshLoads a Lua chunk without running it. 39898e3e3a7aSWarner LoshIf there are no errors, 39908e3e3a7aSWarner Losh<code>lua_load</code> pushes the compiled chunk as a Lua 39918e3e3a7aSWarner Loshfunction on top of the stack. 39928e3e3a7aSWarner LoshOtherwise, it pushes an error message. 39938e3e3a7aSWarner Losh 39948e3e3a7aSWarner Losh 39958e3e3a7aSWarner Losh<p> 39968e3e3a7aSWarner LoshThe return values of <code>lua_load</code> are: 39978e3e3a7aSWarner Losh 39988e3e3a7aSWarner Losh<ul> 39998e3e3a7aSWarner Losh 40008e3e3a7aSWarner Losh<li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li> 40018e3e3a7aSWarner Losh 40028e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> 40038e3e3a7aSWarner Loshsyntax error during precompilation;</li> 40048e3e3a7aSWarner Losh 40058e3e3a7aSWarner Losh<li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 40068e3e3a7aSWarner Loshmemory allocation (out-of-memory) error;</li> 40078e3e3a7aSWarner Losh 40088e3e3a7aSWarner Losh<li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> 40098e3e3a7aSWarner Losherror while running a <code>__gc</code> metamethod. 40108e3e3a7aSWarner Losh(This error has no relation with the chunk being loaded. 40118e3e3a7aSWarner LoshIt is generated by the garbage collector.) 40128e3e3a7aSWarner Losh</li> 40138e3e3a7aSWarner Losh 40148e3e3a7aSWarner Losh</ul> 40158e3e3a7aSWarner Losh 40168e3e3a7aSWarner Losh<p> 40178e3e3a7aSWarner LoshThe <code>lua_load</code> function uses a user-supplied <code>reader</code> function 40188e3e3a7aSWarner Loshto read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). 40198e3e3a7aSWarner LoshThe <code>data</code> argument is an opaque value passed to the reader function. 40208e3e3a7aSWarner Losh 40218e3e3a7aSWarner Losh 40228e3e3a7aSWarner Losh<p> 40238e3e3a7aSWarner LoshThe <code>chunkname</code> argument gives a name to the chunk, 40248e3e3a7aSWarner Loshwhich is used for error messages and in debug information (see <a href="#4.9">§4.9</a>). 40258e3e3a7aSWarner Losh 40268e3e3a7aSWarner Losh 40278e3e3a7aSWarner Losh<p> 40288e3e3a7aSWarner Losh<code>lua_load</code> automatically detects whether the chunk is text or binary 40298e3e3a7aSWarner Loshand loads it accordingly (see program <code>luac</code>). 40308e3e3a7aSWarner LoshThe string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>, 40318e3e3a7aSWarner Loshwith the addition that 40328e3e3a7aSWarner Losha <code>NULL</code> value is equivalent to the string "<code>bt</code>". 40338e3e3a7aSWarner Losh 40348e3e3a7aSWarner Losh 40358e3e3a7aSWarner Losh<p> 40368e3e3a7aSWarner Losh<code>lua_load</code> uses the stack internally, 40378e3e3a7aSWarner Loshso the reader function must always leave the stack 40388e3e3a7aSWarner Loshunmodified when returning. 40398e3e3a7aSWarner Losh 40408e3e3a7aSWarner Losh 40418e3e3a7aSWarner Losh<p> 40428e3e3a7aSWarner LoshIf the resulting function has upvalues, 40438e3e3a7aSWarner Loshits first upvalue is set to the value of the global environment 40448e3e3a7aSWarner Loshstored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">§4.5</a>). 40458e3e3a7aSWarner LoshWhen loading main chunks, 40468e3e3a7aSWarner Loshthis upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 40478e3e3a7aSWarner LoshOther upvalues are initialized with <b>nil</b>. 40488e3e3a7aSWarner Losh 40498e3e3a7aSWarner Losh 40508e3e3a7aSWarner Losh 40518e3e3a7aSWarner Losh 40528e3e3a7aSWarner Losh 40538e3e3a7aSWarner Losh<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> 40548e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 40558e3e3a7aSWarner Losh<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> 40568e3e3a7aSWarner Losh 40578e3e3a7aSWarner Losh<p> 40588e3e3a7aSWarner LoshCreates a new thread running in a new, independent state. 40598e3e3a7aSWarner LoshReturns <code>NULL</code> if it cannot create the thread or the state 40608e3e3a7aSWarner Losh(due to lack of memory). 40618e3e3a7aSWarner LoshThe argument <code>f</code> is the allocator function; 40628e3e3a7aSWarner LoshLua does all memory allocation for this state 40638e3e3a7aSWarner Loshthrough this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>). 40648e3e3a7aSWarner LoshThe second argument, <code>ud</code>, is an opaque pointer that Lua 40658e3e3a7aSWarner Loshpasses to the allocator in every call. 40668e3e3a7aSWarner Losh 40678e3e3a7aSWarner Losh 40688e3e3a7aSWarner Losh 40698e3e3a7aSWarner Losh 40708e3e3a7aSWarner Losh 40718e3e3a7aSWarner Losh<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> 40728e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 40738e3e3a7aSWarner Losh<pre>void lua_newtable (lua_State *L);</pre> 40748e3e3a7aSWarner Losh 40758e3e3a7aSWarner Losh<p> 40768e3e3a7aSWarner LoshCreates a new empty table and pushes it onto the stack. 40778e3e3a7aSWarner LoshIt is equivalent to <code>lua_createtable(L, 0, 0)</code>. 40788e3e3a7aSWarner Losh 40798e3e3a7aSWarner Losh 40808e3e3a7aSWarner Losh 40818e3e3a7aSWarner Losh 40828e3e3a7aSWarner Losh 40838e3e3a7aSWarner Losh<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> 40848e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 40858e3e3a7aSWarner Losh<pre>lua_State *lua_newthread (lua_State *L);</pre> 40868e3e3a7aSWarner Losh 40878e3e3a7aSWarner Losh<p> 40888e3e3a7aSWarner LoshCreates a new thread, pushes it on the stack, 40898e3e3a7aSWarner Loshand returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. 40908e3e3a7aSWarner LoshThe new thread returned by this function shares with the original thread 40918e3e3a7aSWarner Loshits global environment, 40928e3e3a7aSWarner Loshbut has an independent execution stack. 40938e3e3a7aSWarner Losh 40948e3e3a7aSWarner Losh 40958e3e3a7aSWarner Losh<p> 40968e3e3a7aSWarner LoshThere is no explicit function to close or to destroy a thread. 40978e3e3a7aSWarner LoshThreads are subject to garbage collection, 40988e3e3a7aSWarner Loshlike any Lua object. 40998e3e3a7aSWarner Losh 41008e3e3a7aSWarner Losh 41018e3e3a7aSWarner Losh 41028e3e3a7aSWarner Losh 41038e3e3a7aSWarner Losh 41048e3e3a7aSWarner Losh<hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p> 41058e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 41068e3e3a7aSWarner Losh<pre>void *lua_newuserdata (lua_State *L, size_t size);</pre> 41078e3e3a7aSWarner Losh 41088e3e3a7aSWarner Losh<p> 41098e3e3a7aSWarner LoshThis function allocates a new block of memory with the given size, 41108e3e3a7aSWarner Loshpushes onto the stack a new full userdata with the block address, 41118e3e3a7aSWarner Loshand returns this address. 41128e3e3a7aSWarner LoshThe host program can freely use this memory. 41138e3e3a7aSWarner Losh 41148e3e3a7aSWarner Losh 41158e3e3a7aSWarner Losh 41168e3e3a7aSWarner Losh 41178e3e3a7aSWarner Losh 41188e3e3a7aSWarner Losh<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> 41198e3e3a7aSWarner Losh<span class="apii">[-1, +(2|0), <em>e</em>]</span> 41208e3e3a7aSWarner Losh<pre>int lua_next (lua_State *L, int index);</pre> 41218e3e3a7aSWarner Losh 41228e3e3a7aSWarner Losh<p> 41238e3e3a7aSWarner LoshPops a key from the stack, 41248e3e3a7aSWarner Loshand pushes a key–value pair from the table at the given index 41258e3e3a7aSWarner Losh(the "next" pair after the given key). 41268e3e3a7aSWarner LoshIf there are no more elements in the table, 41278e3e3a7aSWarner Loshthen <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). 41288e3e3a7aSWarner Losh 41298e3e3a7aSWarner Losh 41308e3e3a7aSWarner Losh<p> 41318e3e3a7aSWarner LoshA typical traversal looks like this: 41328e3e3a7aSWarner Losh 41338e3e3a7aSWarner Losh<pre> 41348e3e3a7aSWarner Losh /* table is in the stack at index 't' */ 41358e3e3a7aSWarner Losh lua_pushnil(L); /* first key */ 41368e3e3a7aSWarner Losh while (lua_next(L, t) != 0) { 41378e3e3a7aSWarner Losh /* uses 'key' (at index -2) and 'value' (at index -1) */ 41388e3e3a7aSWarner Losh printf("%s - %s\n", 41398e3e3a7aSWarner Losh lua_typename(L, lua_type(L, -2)), 41408e3e3a7aSWarner Losh lua_typename(L, lua_type(L, -1))); 41418e3e3a7aSWarner Losh /* removes 'value'; keeps 'key' for next iteration */ 41428e3e3a7aSWarner Losh lua_pop(L, 1); 41438e3e3a7aSWarner Losh } 41448e3e3a7aSWarner Losh</pre> 41458e3e3a7aSWarner Losh 41468e3e3a7aSWarner Losh<p> 41478e3e3a7aSWarner LoshWhile traversing a table, 41488e3e3a7aSWarner Loshdo not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, 41498e3e3a7aSWarner Loshunless you know that the key is actually a string. 41508e3e3a7aSWarner LoshRecall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change 41518e3e3a7aSWarner Loshthe value at the given index; 41528e3e3a7aSWarner Loshthis confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. 41538e3e3a7aSWarner Losh 41548e3e3a7aSWarner Losh 41558e3e3a7aSWarner Losh<p> 41568e3e3a7aSWarner LoshSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 41578e3e3a7aSWarner Loshthe table during its traversal. 41588e3e3a7aSWarner Losh 41598e3e3a7aSWarner Losh 41608e3e3a7aSWarner Losh 41618e3e3a7aSWarner Losh 41628e3e3a7aSWarner Losh 41638e3e3a7aSWarner Losh<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> 41648e3e3a7aSWarner Losh<pre>typedef ... lua_Number;</pre> 41658e3e3a7aSWarner Losh 41668e3e3a7aSWarner Losh<p> 41678e3e3a7aSWarner LoshThe type of floats in Lua. 41688e3e3a7aSWarner Losh 41698e3e3a7aSWarner Losh 41708e3e3a7aSWarner Losh<p> 41718e3e3a7aSWarner LoshBy default this type is double, 41728e3e3a7aSWarner Loshbut that can be changed to a single float or a long double. 41738e3e3a7aSWarner Losh(See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.) 41748e3e3a7aSWarner Losh 41758e3e3a7aSWarner Losh 41768e3e3a7aSWarner Losh 41778e3e3a7aSWarner Losh 41788e3e3a7aSWarner Losh 41798e3e3a7aSWarner Losh<hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3> 41808e3e3a7aSWarner Losh<pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre> 41818e3e3a7aSWarner Losh 41828e3e3a7aSWarner Losh<p> 41838e3e3a7aSWarner LoshConverts a Lua float to a Lua integer. 41848e3e3a7aSWarner LoshThis macro assumes that <code>n</code> has an integral value. 41858e3e3a7aSWarner LoshIf that value is within the range of Lua integers, 41868e3e3a7aSWarner Loshit is converted to an integer and assigned to <code>*p</code>. 41878e3e3a7aSWarner LoshThe macro results in a boolean indicating whether the 41888e3e3a7aSWarner Loshconversion was successful. 41898e3e3a7aSWarner Losh(Note that this range test can be tricky to do 41908e3e3a7aSWarner Loshcorrectly without this macro, 41918e3e3a7aSWarner Loshdue to roundings.) 41928e3e3a7aSWarner Losh 41938e3e3a7aSWarner Losh 41948e3e3a7aSWarner Losh<p> 41958e3e3a7aSWarner LoshThis macro may evaluate its arguments more than once. 41968e3e3a7aSWarner Losh 41978e3e3a7aSWarner Losh 41988e3e3a7aSWarner Losh 41998e3e3a7aSWarner Losh 42008e3e3a7aSWarner Losh 42018e3e3a7aSWarner Losh<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> 42028e3e3a7aSWarner Losh<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 42038e3e3a7aSWarner Losh<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre> 42048e3e3a7aSWarner Losh 42058e3e3a7aSWarner Losh<p> 42068e3e3a7aSWarner LoshCalls a function in protected mode. 42078e3e3a7aSWarner Losh 42088e3e3a7aSWarner Losh 42098e3e3a7aSWarner Losh<p> 42108e3e3a7aSWarner LoshBoth <code>nargs</code> and <code>nresults</code> have the same meaning as 42118e3e3a7aSWarner Loshin <a href="#lua_call"><code>lua_call</code></a>. 42128e3e3a7aSWarner LoshIf there are no errors during the call, 42138e3e3a7aSWarner Losh<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. 42148e3e3a7aSWarner LoshHowever, if there is any error, 42158e3e3a7aSWarner Losh<a href="#lua_pcall"><code>lua_pcall</code></a> catches it, 42168e3e3a7aSWarner Loshpushes a single value on the stack (the error object), 42178e3e3a7aSWarner Loshand returns an error code. 42188e3e3a7aSWarner LoshLike <a href="#lua_call"><code>lua_call</code></a>, 42198e3e3a7aSWarner Losh<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function 42208e3e3a7aSWarner Loshand its arguments from the stack. 42218e3e3a7aSWarner Losh 42228e3e3a7aSWarner Losh 42238e3e3a7aSWarner Losh<p> 42248e3e3a7aSWarner LoshIf <code>msgh</code> is 0, 42258e3e3a7aSWarner Loshthen the error object returned on the stack 42268e3e3a7aSWarner Loshis exactly the original error object. 42278e3e3a7aSWarner LoshOtherwise, <code>msgh</code> is the stack index of a 42288e3e3a7aSWarner Losh<em>message handler</em>. 42298e3e3a7aSWarner Losh(This index cannot be a pseudo-index.) 42308e3e3a7aSWarner LoshIn case of runtime errors, 42318e3e3a7aSWarner Loshthis function will be called with the error object 42328e3e3a7aSWarner Loshand its return value will be the object 42338e3e3a7aSWarner Loshreturned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. 42348e3e3a7aSWarner Losh 42358e3e3a7aSWarner Losh 42368e3e3a7aSWarner Losh<p> 42378e3e3a7aSWarner LoshTypically, the message handler is used to add more debug 42388e3e3a7aSWarner Loshinformation to the error object, such as a stack traceback. 42398e3e3a7aSWarner LoshSuch information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, 42408e3e3a7aSWarner Loshsince by then the stack has unwound. 42418e3e3a7aSWarner Losh 42428e3e3a7aSWarner Losh 42438e3e3a7aSWarner Losh<p> 42448e3e3a7aSWarner LoshThe <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following constants 42458e3e3a7aSWarner Losh(defined in <code>lua.h</code>): 42468e3e3a7aSWarner Losh 42478e3e3a7aSWarner Losh<ul> 42488e3e3a7aSWarner Losh 42498e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> 42508e3e3a7aSWarner Loshsuccess.</li> 42518e3e3a7aSWarner Losh 42528e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b> 42538e3e3a7aSWarner Losha runtime error. 42548e3e3a7aSWarner Losh</li> 42558e3e3a7aSWarner Losh 42568e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 42578e3e3a7aSWarner Loshmemory allocation error. 42588e3e3a7aSWarner LoshFor such errors, Lua does not call the message handler. 42598e3e3a7aSWarner Losh</li> 42608e3e3a7aSWarner Losh 42618e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b> 42628e3e3a7aSWarner Losherror while running the message handler. 42638e3e3a7aSWarner Losh</li> 42648e3e3a7aSWarner Losh 42658e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> 42668e3e3a7aSWarner Losherror while running a <code>__gc</code> metamethod. 42678e3e3a7aSWarner LoshFor such errors, Lua does not call the message handler 42688e3e3a7aSWarner Losh(as this kind of error typically has no relation 42698e3e3a7aSWarner Loshwith the function being called). 42708e3e3a7aSWarner Losh</li> 42718e3e3a7aSWarner Losh 42728e3e3a7aSWarner Losh</ul> 42738e3e3a7aSWarner Losh 42748e3e3a7aSWarner Losh 42758e3e3a7aSWarner Losh 42768e3e3a7aSWarner Losh 42778e3e3a7aSWarner Losh<hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p> 42788e3e3a7aSWarner Losh<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 42798e3e3a7aSWarner Losh<pre>int lua_pcallk (lua_State *L, 42808e3e3a7aSWarner Losh int nargs, 42818e3e3a7aSWarner Losh int nresults, 42828e3e3a7aSWarner Losh int msgh, 42838e3e3a7aSWarner Losh lua_KContext ctx, 42848e3e3a7aSWarner Losh lua_KFunction k);</pre> 42858e3e3a7aSWarner Losh 42868e3e3a7aSWarner Losh<p> 42878e3e3a7aSWarner LoshThis function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>, 42888e3e3a7aSWarner Loshbut allows the called function to yield (see <a href="#4.7">§4.7</a>). 42898e3e3a7aSWarner Losh 42908e3e3a7aSWarner Losh 42918e3e3a7aSWarner Losh 42928e3e3a7aSWarner Losh 42938e3e3a7aSWarner Losh 42948e3e3a7aSWarner Losh<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> 42958e3e3a7aSWarner Losh<span class="apii">[-n, +0, –]</span> 42968e3e3a7aSWarner Losh<pre>void lua_pop (lua_State *L, int n);</pre> 42978e3e3a7aSWarner Losh 42988e3e3a7aSWarner Losh<p> 42998e3e3a7aSWarner LoshPops <code>n</code> elements from the stack. 43008e3e3a7aSWarner Losh 43018e3e3a7aSWarner Losh 43028e3e3a7aSWarner Losh 43038e3e3a7aSWarner Losh 43048e3e3a7aSWarner Losh 43058e3e3a7aSWarner Losh<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> 43068e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 43078e3e3a7aSWarner Losh<pre>void lua_pushboolean (lua_State *L, int b);</pre> 43088e3e3a7aSWarner Losh 43098e3e3a7aSWarner Losh<p> 43108e3e3a7aSWarner LoshPushes a boolean value with value <code>b</code> onto the stack. 43118e3e3a7aSWarner Losh 43128e3e3a7aSWarner Losh 43138e3e3a7aSWarner Losh 43148e3e3a7aSWarner Losh 43158e3e3a7aSWarner Losh 43168e3e3a7aSWarner Losh<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> 43178e3e3a7aSWarner Losh<span class="apii">[-n, +1, <em>m</em>]</span> 43188e3e3a7aSWarner Losh<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> 43198e3e3a7aSWarner Losh 43208e3e3a7aSWarner Losh<p> 43218e3e3a7aSWarner LoshPushes a new C closure onto the stack. 43228e3e3a7aSWarner Losh 43238e3e3a7aSWarner Losh 43248e3e3a7aSWarner Losh<p> 43258e3e3a7aSWarner LoshWhen a C function is created, 43268e3e3a7aSWarner Loshit is possible to associate some values with it, 43278e3e3a7aSWarner Loshthus creating a C closure (see <a href="#4.4">§4.4</a>); 43288e3e3a7aSWarner Loshthese values are then accessible to the function whenever it is called. 43298e3e3a7aSWarner LoshTo associate values with a C function, 43308e3e3a7aSWarner Loshfirst these values must be pushed onto the stack 43318e3e3a7aSWarner Losh(when there are multiple values, the first value is pushed first). 43328e3e3a7aSWarner LoshThen <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 43338e3e3a7aSWarner Loshis called to create and push the C function onto the stack, 43348e3e3a7aSWarner Loshwith the argument <code>n</code> telling how many values will be 43358e3e3a7aSWarner Loshassociated with the function. 43368e3e3a7aSWarner Losh<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. 43378e3e3a7aSWarner Losh 43388e3e3a7aSWarner Losh 43398e3e3a7aSWarner Losh<p> 43408e3e3a7aSWarner LoshThe maximum value for <code>n</code> is 255. 43418e3e3a7aSWarner Losh 43428e3e3a7aSWarner Losh 43438e3e3a7aSWarner Losh<p> 43448e3e3a7aSWarner LoshWhen <code>n</code> is zero, 43458e3e3a7aSWarner Loshthis function creates a <em>light C function</em>, 43468e3e3a7aSWarner Loshwhich is just a pointer to the C function. 43478e3e3a7aSWarner LoshIn that case, it never raises a memory error. 43488e3e3a7aSWarner Losh 43498e3e3a7aSWarner Losh 43508e3e3a7aSWarner Losh 43518e3e3a7aSWarner Losh 43528e3e3a7aSWarner Losh 43538e3e3a7aSWarner Losh<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> 43548e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 43558e3e3a7aSWarner Losh<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> 43568e3e3a7aSWarner Losh 43578e3e3a7aSWarner Losh<p> 43588e3e3a7aSWarner LoshPushes a C function onto the stack. 43598e3e3a7aSWarner LoshThis function receives a pointer to a C function 43608e3e3a7aSWarner Loshand pushes onto the stack a Lua value of type <code>function</code> that, 43618e3e3a7aSWarner Loshwhen called, invokes the corresponding C function. 43628e3e3a7aSWarner Losh 43638e3e3a7aSWarner Losh 43648e3e3a7aSWarner Losh<p> 43658e3e3a7aSWarner LoshAny function to be callable by Lua must 43668e3e3a7aSWarner Loshfollow the correct protocol to receive its parameters 43678e3e3a7aSWarner Loshand return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 43688e3e3a7aSWarner Losh 43698e3e3a7aSWarner Losh 43708e3e3a7aSWarner Losh 43718e3e3a7aSWarner Losh 43728e3e3a7aSWarner Losh 43738e3e3a7aSWarner Losh<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> 43748e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 43758e3e3a7aSWarner Losh<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> 43768e3e3a7aSWarner Losh 43778e3e3a7aSWarner Losh<p> 43788e3e3a7aSWarner LoshPushes onto the stack a formatted string 43798e3e3a7aSWarner Loshand returns a pointer to this string. 43808e3e3a7aSWarner LoshIt is similar to the ISO C function <code>sprintf</code>, 43818e3e3a7aSWarner Loshbut has some important differences: 43828e3e3a7aSWarner Losh 43838e3e3a7aSWarner Losh<ul> 43848e3e3a7aSWarner Losh 43858e3e3a7aSWarner Losh<li> 43868e3e3a7aSWarner LoshYou do not have to allocate space for the result: 43878e3e3a7aSWarner Loshthe result is a Lua string and Lua takes care of memory allocation 43888e3e3a7aSWarner Losh(and deallocation, through garbage collection). 43898e3e3a7aSWarner Losh</li> 43908e3e3a7aSWarner Losh 43918e3e3a7aSWarner Losh<li> 43928e3e3a7aSWarner LoshThe conversion specifiers are quite restricted. 43938e3e3a7aSWarner LoshThere are no flags, widths, or precisions. 43948e3e3a7aSWarner LoshThe conversion specifiers can only be 43958e3e3a7aSWarner Losh'<code>%%</code>' (inserts the character '<code>%</code>'), 43968e3e3a7aSWarner Losh'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), 43978e3e3a7aSWarner Losh'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), 43988e3e3a7aSWarner Losh'<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>), 43998e3e3a7aSWarner Losh'<code>%p</code>' (inserts a pointer as a hexadecimal numeral), 44008e3e3a7aSWarner Losh'<code>%d</code>' (inserts an <code>int</code>), 44018e3e3a7aSWarner Losh'<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and 44028e3e3a7aSWarner Losh'<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence). 44038e3e3a7aSWarner Losh</li> 44048e3e3a7aSWarner Losh 44058e3e3a7aSWarner Losh</ul> 44068e3e3a7aSWarner Losh 44078e3e3a7aSWarner Losh<p> 44088e3e3a7aSWarner LoshUnlike other push functions, 44098e3e3a7aSWarner Loshthis function checks for the stack space it needs, 44108e3e3a7aSWarner Loshincluding the slot for its result. 44118e3e3a7aSWarner Losh 44128e3e3a7aSWarner Losh 44138e3e3a7aSWarner Losh 44148e3e3a7aSWarner Losh 44158e3e3a7aSWarner Losh 44168e3e3a7aSWarner Losh<hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p> 44178e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 44188e3e3a7aSWarner Losh<pre>void lua_pushglobaltable (lua_State *L);</pre> 44198e3e3a7aSWarner Losh 44208e3e3a7aSWarner Losh<p> 44218e3e3a7aSWarner LoshPushes the global environment onto the stack. 44228e3e3a7aSWarner Losh 44238e3e3a7aSWarner Losh 44248e3e3a7aSWarner Losh 44258e3e3a7aSWarner Losh 44268e3e3a7aSWarner Losh 44278e3e3a7aSWarner Losh<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> 44288e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 44298e3e3a7aSWarner Losh<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> 44308e3e3a7aSWarner Losh 44318e3e3a7aSWarner Losh<p> 44328e3e3a7aSWarner LoshPushes an integer with value <code>n</code> onto the stack. 44338e3e3a7aSWarner Losh 44348e3e3a7aSWarner Losh 44358e3e3a7aSWarner Losh 44368e3e3a7aSWarner Losh 44378e3e3a7aSWarner Losh 44388e3e3a7aSWarner Losh<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> 44398e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 44408e3e3a7aSWarner Losh<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> 44418e3e3a7aSWarner Losh 44428e3e3a7aSWarner Losh<p> 44438e3e3a7aSWarner LoshPushes a light userdata onto the stack. 44448e3e3a7aSWarner Losh 44458e3e3a7aSWarner Losh 44468e3e3a7aSWarner Losh<p> 44478e3e3a7aSWarner LoshUserdata represent C values in Lua. 44488e3e3a7aSWarner LoshA <em>light userdata</em> represents a pointer, a <code>void*</code>. 44498e3e3a7aSWarner LoshIt is a value (like a number): 44508e3e3a7aSWarner Loshyou do not create it, it has no individual metatable, 44518e3e3a7aSWarner Loshand it is not collected (as it was never created). 44528e3e3a7aSWarner LoshA light userdata is equal to "any" 44538e3e3a7aSWarner Loshlight userdata with the same C address. 44548e3e3a7aSWarner Losh 44558e3e3a7aSWarner Losh 44568e3e3a7aSWarner Losh 44578e3e3a7aSWarner Losh 44588e3e3a7aSWarner Losh 44598e3e3a7aSWarner Losh<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> 44608e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 44618e3e3a7aSWarner Losh<pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre> 44628e3e3a7aSWarner Losh 44638e3e3a7aSWarner Losh<p> 44648e3e3a7aSWarner LoshThis macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>, 44658e3e3a7aSWarner Loshbut should be used only when <code>s</code> is a literal string. 44668e3e3a7aSWarner Losh 44678e3e3a7aSWarner Losh 44688e3e3a7aSWarner Losh 44698e3e3a7aSWarner Losh 44708e3e3a7aSWarner Losh 44718e3e3a7aSWarner Losh<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> 44728e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 44738e3e3a7aSWarner Losh<pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> 44748e3e3a7aSWarner Losh 44758e3e3a7aSWarner Losh<p> 44768e3e3a7aSWarner LoshPushes the string pointed to by <code>s</code> with size <code>len</code> 44778e3e3a7aSWarner Loshonto the stack. 44788e3e3a7aSWarner LoshLua makes (or reuses) an internal copy of the given string, 44798e3e3a7aSWarner Loshso the memory at <code>s</code> can be freed or reused immediately after 44808e3e3a7aSWarner Loshthe function returns. 44818e3e3a7aSWarner LoshThe string can contain any binary data, 44828e3e3a7aSWarner Loshincluding embedded zeros. 44838e3e3a7aSWarner Losh 44848e3e3a7aSWarner Losh 44858e3e3a7aSWarner Losh<p> 44868e3e3a7aSWarner LoshReturns a pointer to the internal copy of the string. 44878e3e3a7aSWarner Losh 44888e3e3a7aSWarner Losh 44898e3e3a7aSWarner Losh 44908e3e3a7aSWarner Losh 44918e3e3a7aSWarner Losh 44928e3e3a7aSWarner Losh<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> 44938e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 44948e3e3a7aSWarner Losh<pre>void lua_pushnil (lua_State *L);</pre> 44958e3e3a7aSWarner Losh 44968e3e3a7aSWarner Losh<p> 44978e3e3a7aSWarner LoshPushes a nil value onto the stack. 44988e3e3a7aSWarner Losh 44998e3e3a7aSWarner Losh 45008e3e3a7aSWarner Losh 45018e3e3a7aSWarner Losh 45028e3e3a7aSWarner Losh 45038e3e3a7aSWarner Losh<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> 45048e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 45058e3e3a7aSWarner Losh<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> 45068e3e3a7aSWarner Losh 45078e3e3a7aSWarner Losh<p> 45088e3e3a7aSWarner LoshPushes a float with value <code>n</code> onto the stack. 45098e3e3a7aSWarner Losh 45108e3e3a7aSWarner Losh 45118e3e3a7aSWarner Losh 45128e3e3a7aSWarner Losh 45138e3e3a7aSWarner Losh 45148e3e3a7aSWarner Losh<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> 45158e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 45168e3e3a7aSWarner Losh<pre>const char *lua_pushstring (lua_State *L, const char *s);</pre> 45178e3e3a7aSWarner Losh 45188e3e3a7aSWarner Losh<p> 45198e3e3a7aSWarner LoshPushes the zero-terminated string pointed to by <code>s</code> 45208e3e3a7aSWarner Loshonto the stack. 45218e3e3a7aSWarner LoshLua makes (or reuses) an internal copy of the given string, 45228e3e3a7aSWarner Loshso the memory at <code>s</code> can be freed or reused immediately after 45238e3e3a7aSWarner Loshthe function returns. 45248e3e3a7aSWarner Losh 45258e3e3a7aSWarner Losh 45268e3e3a7aSWarner Losh<p> 45278e3e3a7aSWarner LoshReturns a pointer to the internal copy of the string. 45288e3e3a7aSWarner Losh 45298e3e3a7aSWarner Losh 45308e3e3a7aSWarner Losh<p> 45318e3e3a7aSWarner LoshIf <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>. 45328e3e3a7aSWarner Losh 45338e3e3a7aSWarner Losh 45348e3e3a7aSWarner Losh 45358e3e3a7aSWarner Losh 45368e3e3a7aSWarner Losh 45378e3e3a7aSWarner Losh<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> 45388e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 45398e3e3a7aSWarner Losh<pre>int lua_pushthread (lua_State *L);</pre> 45408e3e3a7aSWarner Losh 45418e3e3a7aSWarner Losh<p> 45428e3e3a7aSWarner LoshPushes the thread represented by <code>L</code> onto the stack. 45438e3e3a7aSWarner LoshReturns 1 if this thread is the main thread of its state. 45448e3e3a7aSWarner Losh 45458e3e3a7aSWarner Losh 45468e3e3a7aSWarner Losh 45478e3e3a7aSWarner Losh 45488e3e3a7aSWarner Losh 45498e3e3a7aSWarner Losh<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> 45508e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 45518e3e3a7aSWarner Losh<pre>void lua_pushvalue (lua_State *L, int index);</pre> 45528e3e3a7aSWarner Losh 45538e3e3a7aSWarner Losh<p> 45548e3e3a7aSWarner LoshPushes a copy of the element at the given index 45558e3e3a7aSWarner Loshonto the stack. 45568e3e3a7aSWarner Losh 45578e3e3a7aSWarner Losh 45588e3e3a7aSWarner Losh 45598e3e3a7aSWarner Losh 45608e3e3a7aSWarner Losh 45618e3e3a7aSWarner Losh<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> 45628e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 45638e3e3a7aSWarner Losh<pre>const char *lua_pushvfstring (lua_State *L, 45648e3e3a7aSWarner Losh const char *fmt, 45658e3e3a7aSWarner Losh va_list argp);</pre> 45668e3e3a7aSWarner Losh 45678e3e3a7aSWarner Losh<p> 45688e3e3a7aSWarner LoshEquivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> 45698e3e3a7aSWarner Loshinstead of a variable number of arguments. 45708e3e3a7aSWarner Losh 45718e3e3a7aSWarner Losh 45728e3e3a7aSWarner Losh 45738e3e3a7aSWarner Losh 45748e3e3a7aSWarner Losh 45758e3e3a7aSWarner Losh<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> 45768e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 45778e3e3a7aSWarner Losh<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> 45788e3e3a7aSWarner Losh 45798e3e3a7aSWarner Losh<p> 45808e3e3a7aSWarner LoshReturns 1 if the two values in indices <code>index1</code> and 45818e3e3a7aSWarner Losh<code>index2</code> are primitively equal 45828e3e3a7aSWarner Losh(that is, without calling the <code>__eq</code> metamethod). 45838e3e3a7aSWarner LoshOtherwise returns 0. 45848e3e3a7aSWarner LoshAlso returns 0 if any of the indices are not valid. 45858e3e3a7aSWarner Losh 45868e3e3a7aSWarner Losh 45878e3e3a7aSWarner Losh 45888e3e3a7aSWarner Losh 45898e3e3a7aSWarner Losh 45908e3e3a7aSWarner Losh<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> 45918e3e3a7aSWarner Losh<span class="apii">[-1, +1, –]</span> 45928e3e3a7aSWarner Losh<pre>int lua_rawget (lua_State *L, int index);</pre> 45938e3e3a7aSWarner Losh 45948e3e3a7aSWarner Losh<p> 45958e3e3a7aSWarner LoshSimilar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access 45968e3e3a7aSWarner Losh(i.e., without metamethods). 45978e3e3a7aSWarner Losh 45988e3e3a7aSWarner Losh 45998e3e3a7aSWarner Losh 46008e3e3a7aSWarner Losh 46018e3e3a7aSWarner Losh 46028e3e3a7aSWarner Losh<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> 46038e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 46048e3e3a7aSWarner Losh<pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre> 46058e3e3a7aSWarner Losh 46068e3e3a7aSWarner Losh<p> 46078e3e3a7aSWarner LoshPushes onto the stack the value <code>t[n]</code>, 46088e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index. 46098e3e3a7aSWarner LoshThe access is raw, 46108e3e3a7aSWarner Loshthat is, it does not invoke the <code>__index</code> metamethod. 46118e3e3a7aSWarner Losh 46128e3e3a7aSWarner Losh 46138e3e3a7aSWarner Losh<p> 46148e3e3a7aSWarner LoshReturns the type of the pushed value. 46158e3e3a7aSWarner Losh 46168e3e3a7aSWarner Losh 46178e3e3a7aSWarner Losh 46188e3e3a7aSWarner Losh 46198e3e3a7aSWarner Losh 46208e3e3a7aSWarner Losh<hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p> 46218e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 46228e3e3a7aSWarner Losh<pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre> 46238e3e3a7aSWarner Losh 46248e3e3a7aSWarner Losh<p> 46258e3e3a7aSWarner LoshPushes onto the stack the value <code>t[k]</code>, 46268e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index and 46278e3e3a7aSWarner Losh<code>k</code> is the pointer <code>p</code> represented as a light userdata. 46288e3e3a7aSWarner LoshThe access is raw; 46298e3e3a7aSWarner Loshthat is, it does not invoke the <code>__index</code> metamethod. 46308e3e3a7aSWarner Losh 46318e3e3a7aSWarner Losh 46328e3e3a7aSWarner Losh<p> 46338e3e3a7aSWarner LoshReturns the type of the pushed value. 46348e3e3a7aSWarner Losh 46358e3e3a7aSWarner Losh 46368e3e3a7aSWarner Losh 46378e3e3a7aSWarner Losh 46388e3e3a7aSWarner Losh 46398e3e3a7aSWarner Losh<hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p> 46408e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 46418e3e3a7aSWarner Losh<pre>size_t lua_rawlen (lua_State *L, int index);</pre> 46428e3e3a7aSWarner Losh 46438e3e3a7aSWarner Losh<p> 46448e3e3a7aSWarner LoshReturns the raw "length" of the value at the given index: 46458e3e3a7aSWarner Loshfor strings, this is the string length; 46468e3e3a7aSWarner Loshfor tables, this is the result of the length operator ('<code>#</code>') 46478e3e3a7aSWarner Loshwith no metamethods; 46488e3e3a7aSWarner Loshfor userdata, this is the size of the block of memory allocated 46498e3e3a7aSWarner Loshfor the userdata; 46508e3e3a7aSWarner Loshfor other values, it is 0. 46518e3e3a7aSWarner Losh 46528e3e3a7aSWarner Losh 46538e3e3a7aSWarner Losh 46548e3e3a7aSWarner Losh 46558e3e3a7aSWarner Losh 46568e3e3a7aSWarner Losh<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> 46578e3e3a7aSWarner Losh<span class="apii">[-2, +0, <em>m</em>]</span> 46588e3e3a7aSWarner Losh<pre>void lua_rawset (lua_State *L, int index);</pre> 46598e3e3a7aSWarner Losh 46608e3e3a7aSWarner Losh<p> 46618e3e3a7aSWarner LoshSimilar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment 46628e3e3a7aSWarner Losh(i.e., without metamethods). 46638e3e3a7aSWarner Losh 46648e3e3a7aSWarner Losh 46658e3e3a7aSWarner Losh 46668e3e3a7aSWarner Losh 46678e3e3a7aSWarner Losh 46688e3e3a7aSWarner Losh<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> 46698e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span> 46708e3e3a7aSWarner Losh<pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre> 46718e3e3a7aSWarner Losh 46728e3e3a7aSWarner Losh<p> 46738e3e3a7aSWarner LoshDoes the equivalent of <code>t[i] = v</code>, 46748e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index 46758e3e3a7aSWarner Loshand <code>v</code> is the value at the top of the stack. 46768e3e3a7aSWarner Losh 46778e3e3a7aSWarner Losh 46788e3e3a7aSWarner Losh<p> 46798e3e3a7aSWarner LoshThis function pops the value from the stack. 46808e3e3a7aSWarner LoshThe assignment is raw, 46818e3e3a7aSWarner Loshthat is, it does not invoke the <code>__newindex</code> metamethod. 46828e3e3a7aSWarner Losh 46838e3e3a7aSWarner Losh 46848e3e3a7aSWarner Losh 46858e3e3a7aSWarner Losh 46868e3e3a7aSWarner Losh 46878e3e3a7aSWarner Losh<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p> 46888e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span> 46898e3e3a7aSWarner Losh<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre> 46908e3e3a7aSWarner Losh 46918e3e3a7aSWarner Losh<p> 46928e3e3a7aSWarner LoshDoes the equivalent of <code>t[p] = v</code>, 46938e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index, 46948e3e3a7aSWarner Losh<code>p</code> is encoded as a light userdata, 46958e3e3a7aSWarner Loshand <code>v</code> is the value at the top of the stack. 46968e3e3a7aSWarner Losh 46978e3e3a7aSWarner Losh 46988e3e3a7aSWarner Losh<p> 46998e3e3a7aSWarner LoshThis function pops the value from the stack. 47008e3e3a7aSWarner LoshThe assignment is raw, 47018e3e3a7aSWarner Loshthat is, it does not invoke <code>__newindex</code> metamethod. 47028e3e3a7aSWarner Losh 47038e3e3a7aSWarner Losh 47048e3e3a7aSWarner Losh 47058e3e3a7aSWarner Losh 47068e3e3a7aSWarner Losh 47078e3e3a7aSWarner Losh<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> 47088e3e3a7aSWarner Losh<pre>typedef const char * (*lua_Reader) (lua_State *L, 47098e3e3a7aSWarner Losh void *data, 47108e3e3a7aSWarner Losh size_t *size);</pre> 47118e3e3a7aSWarner Losh 47128e3e3a7aSWarner Losh<p> 47138e3e3a7aSWarner LoshThe reader function used by <a href="#lua_load"><code>lua_load</code></a>. 47148e3e3a7aSWarner LoshEvery time it needs another piece of the chunk, 47158e3e3a7aSWarner Losh<a href="#lua_load"><code>lua_load</code></a> calls the reader, 47168e3e3a7aSWarner Loshpassing along its <code>data</code> parameter. 47178e3e3a7aSWarner LoshThe reader must return a pointer to a block of memory 47188e3e3a7aSWarner Loshwith a new piece of the chunk 47198e3e3a7aSWarner Loshand set <code>size</code> to the block size. 47208e3e3a7aSWarner LoshThe block must exist until the reader function is called again. 47218e3e3a7aSWarner LoshTo signal the end of the chunk, 47228e3e3a7aSWarner Loshthe reader must return <code>NULL</code> or set <code>size</code> to zero. 47238e3e3a7aSWarner LoshThe reader function may return pieces of any size greater than zero. 47248e3e3a7aSWarner Losh 47258e3e3a7aSWarner Losh 47268e3e3a7aSWarner Losh 47278e3e3a7aSWarner Losh 47288e3e3a7aSWarner Losh 47298e3e3a7aSWarner Losh<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> 47308e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 47318e3e3a7aSWarner Losh<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre> 47328e3e3a7aSWarner Losh 47338e3e3a7aSWarner Losh<p> 47348e3e3a7aSWarner LoshSets the C function <code>f</code> as the new value of global <code>name</code>. 47358e3e3a7aSWarner LoshIt is defined as a macro: 47368e3e3a7aSWarner Losh 47378e3e3a7aSWarner Losh<pre> 47388e3e3a7aSWarner Losh #define lua_register(L,n,f) \ 47398e3e3a7aSWarner Losh (lua_pushcfunction(L, f), lua_setglobal(L, n)) 47408e3e3a7aSWarner Losh</pre> 47418e3e3a7aSWarner Losh 47428e3e3a7aSWarner Losh 47438e3e3a7aSWarner Losh 47448e3e3a7aSWarner Losh 47458e3e3a7aSWarner Losh<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> 47468e3e3a7aSWarner Losh<span class="apii">[-1, +0, –]</span> 47478e3e3a7aSWarner Losh<pre>void lua_remove (lua_State *L, int index);</pre> 47488e3e3a7aSWarner Losh 47498e3e3a7aSWarner Losh<p> 47508e3e3a7aSWarner LoshRemoves the element at the given valid index, 47518e3e3a7aSWarner Loshshifting down the elements above this index to fill the gap. 47528e3e3a7aSWarner LoshThis function cannot be called with a pseudo-index, 47538e3e3a7aSWarner Loshbecause a pseudo-index is not an actual stack position. 47548e3e3a7aSWarner Losh 47558e3e3a7aSWarner Losh 47568e3e3a7aSWarner Losh 47578e3e3a7aSWarner Losh 47588e3e3a7aSWarner Losh 47598e3e3a7aSWarner Losh<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> 47608e3e3a7aSWarner Losh<span class="apii">[-1, +0, –]</span> 47618e3e3a7aSWarner Losh<pre>void lua_replace (lua_State *L, int index);</pre> 47628e3e3a7aSWarner Losh 47638e3e3a7aSWarner Losh<p> 47648e3e3a7aSWarner LoshMoves the top element into the given valid index 47658e3e3a7aSWarner Loshwithout shifting any element 47668e3e3a7aSWarner Losh(therefore replacing the value at that given index), 47678e3e3a7aSWarner Loshand then pops the top element. 47688e3e3a7aSWarner Losh 47698e3e3a7aSWarner Losh 47708e3e3a7aSWarner Losh 47718e3e3a7aSWarner Losh 47728e3e3a7aSWarner Losh 47738e3e3a7aSWarner Losh<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> 47748e3e3a7aSWarner Losh<span class="apii">[-?, +?, –]</span> 47758e3e3a7aSWarner Losh<pre>int lua_resume (lua_State *L, lua_State *from, int nargs);</pre> 47768e3e3a7aSWarner Losh 47778e3e3a7aSWarner Losh<p> 47788e3e3a7aSWarner LoshStarts and resumes a coroutine in the given thread <code>L</code>. 47798e3e3a7aSWarner Losh 47808e3e3a7aSWarner Losh 47818e3e3a7aSWarner Losh<p> 47828e3e3a7aSWarner LoshTo start a coroutine, 47838e3e3a7aSWarner Loshyou push onto the thread stack the main function plus any arguments; 47848e3e3a7aSWarner Loshthen you call <a href="#lua_resume"><code>lua_resume</code></a>, 47858e3e3a7aSWarner Loshwith <code>nargs</code> being the number of arguments. 47868e3e3a7aSWarner LoshThis call returns when the coroutine suspends or finishes its execution. 47878e3e3a7aSWarner LoshWhen it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>, 47888e3e3a7aSWarner Loshor all values returned by the body function. 47898e3e3a7aSWarner Losh<a href="#lua_resume"><code>lua_resume</code></a> returns 47908e3e3a7aSWarner Losh<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, 47918e3e3a7aSWarner Losh<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution 47928e3e3a7aSWarner Loshwithout errors, 47938e3e3a7aSWarner Loshor an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). 47948e3e3a7aSWarner Losh 47958e3e3a7aSWarner Losh 47968e3e3a7aSWarner Losh<p> 47978e3e3a7aSWarner LoshIn case of errors, 47988e3e3a7aSWarner Loshthe stack is not unwound, 47998e3e3a7aSWarner Loshso you can use the debug API over it. 48008e3e3a7aSWarner LoshThe error object is on the top of the stack. 48018e3e3a7aSWarner Losh 48028e3e3a7aSWarner Losh 48038e3e3a7aSWarner Losh<p> 48048e3e3a7aSWarner LoshTo resume a coroutine, 48058e3e3a7aSWarner Loshyou remove any results from the last <a href="#lua_yield"><code>lua_yield</code></a>, 48068e3e3a7aSWarner Loshput on its stack only the values to 48078e3e3a7aSWarner Loshbe passed as results from <code>yield</code>, 48088e3e3a7aSWarner Loshand then call <a href="#lua_resume"><code>lua_resume</code></a>. 48098e3e3a7aSWarner Losh 48108e3e3a7aSWarner Losh 48118e3e3a7aSWarner Losh<p> 48128e3e3a7aSWarner LoshThe parameter <code>from</code> represents the coroutine that is resuming <code>L</code>. 48138e3e3a7aSWarner LoshIf there is no such coroutine, 48148e3e3a7aSWarner Loshthis parameter can be <code>NULL</code>. 48158e3e3a7aSWarner Losh 48168e3e3a7aSWarner Losh 48178e3e3a7aSWarner Losh 48188e3e3a7aSWarner Losh 48198e3e3a7aSWarner Losh 48208e3e3a7aSWarner Losh<hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p> 48218e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 48228e3e3a7aSWarner Losh<pre>void lua_rotate (lua_State *L, int idx, int n);</pre> 48238e3e3a7aSWarner Losh 48248e3e3a7aSWarner Losh<p> 48258e3e3a7aSWarner LoshRotates the stack elements between the valid index <code>idx</code> 48268e3e3a7aSWarner Loshand the top of the stack. 48278e3e3a7aSWarner LoshThe elements are rotated <code>n</code> positions in the direction of the top, 48288e3e3a7aSWarner Loshfor a positive <code>n</code>, 48298e3e3a7aSWarner Loshor <code>-n</code> positions in the direction of the bottom, 48308e3e3a7aSWarner Loshfor a negative <code>n</code>. 48318e3e3a7aSWarner LoshThe absolute value of <code>n</code> must not be greater than the size 48328e3e3a7aSWarner Loshof the slice being rotated. 48338e3e3a7aSWarner LoshThis function cannot be called with a pseudo-index, 48348e3e3a7aSWarner Loshbecause a pseudo-index is not an actual stack position. 48358e3e3a7aSWarner Losh 48368e3e3a7aSWarner Losh 48378e3e3a7aSWarner Losh 48388e3e3a7aSWarner Losh 48398e3e3a7aSWarner Losh 48408e3e3a7aSWarner Losh<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> 48418e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 48428e3e3a7aSWarner Losh<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> 48438e3e3a7aSWarner Losh 48448e3e3a7aSWarner Losh<p> 48458e3e3a7aSWarner LoshChanges the allocator function of a given state to <code>f</code> 48468e3e3a7aSWarner Loshwith user data <code>ud</code>. 48478e3e3a7aSWarner Losh 48488e3e3a7aSWarner Losh 48498e3e3a7aSWarner Losh 48508e3e3a7aSWarner Losh 48518e3e3a7aSWarner Losh 48528e3e3a7aSWarner Losh<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> 48538e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>e</em>]</span> 48548e3e3a7aSWarner Losh<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> 48558e3e3a7aSWarner Losh 48568e3e3a7aSWarner Losh<p> 48578e3e3a7aSWarner LoshDoes the equivalent to <code>t[k] = v</code>, 48588e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index 48598e3e3a7aSWarner Loshand <code>v</code> is the value at the top of the stack. 48608e3e3a7aSWarner Losh 48618e3e3a7aSWarner Losh 48628e3e3a7aSWarner Losh<p> 48638e3e3a7aSWarner LoshThis function pops the value from the stack. 48648e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 48658e3e3a7aSWarner Loshfor the "newindex" event (see <a href="#2.4">§2.4</a>). 48668e3e3a7aSWarner Losh 48678e3e3a7aSWarner Losh 48688e3e3a7aSWarner Losh 48698e3e3a7aSWarner Losh 48708e3e3a7aSWarner Losh 48718e3e3a7aSWarner Losh<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> 48728e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>e</em>]</span> 48738e3e3a7aSWarner Losh<pre>void lua_setglobal (lua_State *L, const char *name);</pre> 48748e3e3a7aSWarner Losh 48758e3e3a7aSWarner Losh<p> 48768e3e3a7aSWarner LoshPops a value from the stack and 48778e3e3a7aSWarner Loshsets it as the new value of global <code>name</code>. 48788e3e3a7aSWarner Losh 48798e3e3a7aSWarner Losh 48808e3e3a7aSWarner Losh 48818e3e3a7aSWarner Losh 48828e3e3a7aSWarner Losh 48838e3e3a7aSWarner Losh<hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p> 48848e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>e</em>]</span> 48858e3e3a7aSWarner Losh<pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre> 48868e3e3a7aSWarner Losh 48878e3e3a7aSWarner Losh<p> 48888e3e3a7aSWarner LoshDoes the equivalent to <code>t[n] = v</code>, 48898e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index 48908e3e3a7aSWarner Loshand <code>v</code> is the value at the top of the stack. 48918e3e3a7aSWarner Losh 48928e3e3a7aSWarner Losh 48938e3e3a7aSWarner Losh<p> 48948e3e3a7aSWarner LoshThis function pops the value from the stack. 48958e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 48968e3e3a7aSWarner Loshfor the "newindex" event (see <a href="#2.4">§2.4</a>). 48978e3e3a7aSWarner Losh 48988e3e3a7aSWarner Losh 48998e3e3a7aSWarner Losh 49008e3e3a7aSWarner Losh 49018e3e3a7aSWarner Losh 49028e3e3a7aSWarner Losh<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> 49038e3e3a7aSWarner Losh<span class="apii">[-1, +0, –]</span> 49048e3e3a7aSWarner Losh<pre>void lua_setmetatable (lua_State *L, int index);</pre> 49058e3e3a7aSWarner Losh 49068e3e3a7aSWarner Losh<p> 49078e3e3a7aSWarner LoshPops a table from the stack and 49088e3e3a7aSWarner Loshsets it as the new metatable for the value at the given index. 49098e3e3a7aSWarner Losh 49108e3e3a7aSWarner Losh 49118e3e3a7aSWarner Losh 49128e3e3a7aSWarner Losh 49138e3e3a7aSWarner Losh 49148e3e3a7aSWarner Losh<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> 49158e3e3a7aSWarner Losh<span class="apii">[-2, +0, <em>e</em>]</span> 49168e3e3a7aSWarner Losh<pre>void lua_settable (lua_State *L, int index);</pre> 49178e3e3a7aSWarner Losh 49188e3e3a7aSWarner Losh<p> 49198e3e3a7aSWarner LoshDoes the equivalent to <code>t[k] = v</code>, 49208e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index, 49218e3e3a7aSWarner Losh<code>v</code> is the value at the top of the stack, 49228e3e3a7aSWarner Loshand <code>k</code> is the value just below the top. 49238e3e3a7aSWarner Losh 49248e3e3a7aSWarner Losh 49258e3e3a7aSWarner Losh<p> 49268e3e3a7aSWarner LoshThis function pops both the key and the value from the stack. 49278e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 49288e3e3a7aSWarner Loshfor the "newindex" event (see <a href="#2.4">§2.4</a>). 49298e3e3a7aSWarner Losh 49308e3e3a7aSWarner Losh 49318e3e3a7aSWarner Losh 49328e3e3a7aSWarner Losh 49338e3e3a7aSWarner Losh 49348e3e3a7aSWarner Losh<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> 49358e3e3a7aSWarner Losh<span class="apii">[-?, +?, –]</span> 49368e3e3a7aSWarner Losh<pre>void lua_settop (lua_State *L, int index);</pre> 49378e3e3a7aSWarner Losh 49388e3e3a7aSWarner Losh<p> 49398e3e3a7aSWarner LoshAccepts any index, or 0, 49408e3e3a7aSWarner Loshand sets the stack top to this index. 49418e3e3a7aSWarner LoshIf the new top is larger than the old one, 49428e3e3a7aSWarner Loshthen the new elements are filled with <b>nil</b>. 49438e3e3a7aSWarner LoshIf <code>index</code> is 0, then all stack elements are removed. 49448e3e3a7aSWarner Losh 49458e3e3a7aSWarner Losh 49468e3e3a7aSWarner Losh 49478e3e3a7aSWarner Losh 49488e3e3a7aSWarner Losh 49498e3e3a7aSWarner Losh<hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p> 49508e3e3a7aSWarner Losh<span class="apii">[-1, +0, –]</span> 49518e3e3a7aSWarner Losh<pre>void lua_setuservalue (lua_State *L, int index);</pre> 49528e3e3a7aSWarner Losh 49538e3e3a7aSWarner Losh<p> 49548e3e3a7aSWarner LoshPops a value from the stack and sets it as 49558e3e3a7aSWarner Loshthe new value associated to the full userdata at the given index. 49568e3e3a7aSWarner Losh 49578e3e3a7aSWarner Losh 49588e3e3a7aSWarner Losh 49598e3e3a7aSWarner Losh 49608e3e3a7aSWarner Losh 49618e3e3a7aSWarner Losh<hr><h3><a name="lua_State"><code>lua_State</code></a></h3> 49628e3e3a7aSWarner Losh<pre>typedef struct lua_State lua_State;</pre> 49638e3e3a7aSWarner Losh 49648e3e3a7aSWarner Losh<p> 49658e3e3a7aSWarner LoshAn opaque structure that points to a thread and indirectly 49668e3e3a7aSWarner Losh(through the thread) to the whole state of a Lua interpreter. 49678e3e3a7aSWarner LoshThe Lua library is fully reentrant: 49688e3e3a7aSWarner Loshit has no global variables. 49698e3e3a7aSWarner LoshAll information about a state is accessible through this structure. 49708e3e3a7aSWarner Losh 49718e3e3a7aSWarner Losh 49728e3e3a7aSWarner Losh<p> 49738e3e3a7aSWarner LoshA pointer to this structure must be passed as the first argument to 49748e3e3a7aSWarner Loshevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 49758e3e3a7aSWarner Loshwhich creates a Lua state from scratch. 49768e3e3a7aSWarner Losh 49778e3e3a7aSWarner Losh 49788e3e3a7aSWarner Losh 49798e3e3a7aSWarner Losh 49808e3e3a7aSWarner Losh 49818e3e3a7aSWarner Losh<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> 49828e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 49838e3e3a7aSWarner Losh<pre>int lua_status (lua_State *L);</pre> 49848e3e3a7aSWarner Losh 49858e3e3a7aSWarner Losh<p> 49868e3e3a7aSWarner LoshReturns the status of the thread <code>L</code>. 49878e3e3a7aSWarner Losh 49888e3e3a7aSWarner Losh 49898e3e3a7aSWarner Losh<p> 49908e3e3a7aSWarner LoshThe status can be 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) for a normal thread, 49918e3e3a7aSWarner Loshan error code if the thread finished the execution 49928e3e3a7aSWarner Loshof a <a href="#lua_resume"><code>lua_resume</code></a> with an error, 49938e3e3a7aSWarner Loshor <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. 49948e3e3a7aSWarner Losh 49958e3e3a7aSWarner Losh 49968e3e3a7aSWarner Losh<p> 49978e3e3a7aSWarner LoshYou can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>. 49988e3e3a7aSWarner LoshYou can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> 49998e3e3a7aSWarner Losh(to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> 50008e3e3a7aSWarner Losh(to resume a coroutine). 50018e3e3a7aSWarner Losh 50028e3e3a7aSWarner Losh 50038e3e3a7aSWarner Losh 50048e3e3a7aSWarner Losh 50058e3e3a7aSWarner Losh 50068e3e3a7aSWarner Losh<hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p> 50078e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 50088e3e3a7aSWarner Losh<pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre> 50098e3e3a7aSWarner Losh 50108e3e3a7aSWarner Losh<p> 50118e3e3a7aSWarner LoshConverts the zero-terminated string <code>s</code> to a number, 50128e3e3a7aSWarner Loshpushes that number into the stack, 50138e3e3a7aSWarner Loshand returns the total size of the string, 50148e3e3a7aSWarner Loshthat is, its length plus one. 50158e3e3a7aSWarner LoshThe conversion can result in an integer or a float, 50168e3e3a7aSWarner Loshaccording to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 50178e3e3a7aSWarner LoshThe string may have leading and trailing spaces and a sign. 50188e3e3a7aSWarner LoshIf the string is not a valid numeral, 50198e3e3a7aSWarner Loshreturns 0 and pushes nothing. 50208e3e3a7aSWarner Losh(Note that the result can be used as a boolean, 50218e3e3a7aSWarner Loshtrue if the conversion succeeds.) 50228e3e3a7aSWarner Losh 50238e3e3a7aSWarner Losh 50248e3e3a7aSWarner Losh 50258e3e3a7aSWarner Losh 50268e3e3a7aSWarner Losh 50278e3e3a7aSWarner Losh<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> 50288e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 50298e3e3a7aSWarner Losh<pre>int lua_toboolean (lua_State *L, int index);</pre> 50308e3e3a7aSWarner Losh 50318e3e3a7aSWarner Losh<p> 50328e3e3a7aSWarner LoshConverts the Lua value at the given index to a C boolean 50338e3e3a7aSWarner Loshvalue (0 or 1). 50348e3e3a7aSWarner LoshLike all tests in Lua, 50358e3e3a7aSWarner Losh<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value 50368e3e3a7aSWarner Loshdifferent from <b>false</b> and <b>nil</b>; 50378e3e3a7aSWarner Loshotherwise it returns false. 50388e3e3a7aSWarner Losh(If you want to accept only actual boolean values, 50398e3e3a7aSWarner Loshuse <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) 50408e3e3a7aSWarner Losh 50418e3e3a7aSWarner Losh 50428e3e3a7aSWarner Losh 50438e3e3a7aSWarner Losh 50448e3e3a7aSWarner Losh 50458e3e3a7aSWarner Losh<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> 50468e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 50478e3e3a7aSWarner Losh<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> 50488e3e3a7aSWarner Losh 50498e3e3a7aSWarner Losh<p> 50508e3e3a7aSWarner LoshConverts a value at the given index to a C function. 50518e3e3a7aSWarner LoshThat value must be a C function; 50528e3e3a7aSWarner Loshotherwise, returns <code>NULL</code>. 50538e3e3a7aSWarner Losh 50548e3e3a7aSWarner Losh 50558e3e3a7aSWarner Losh 50568e3e3a7aSWarner Losh 50578e3e3a7aSWarner Losh 50588e3e3a7aSWarner Losh<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> 50598e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 50608e3e3a7aSWarner Losh<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> 50618e3e3a7aSWarner Losh 50628e3e3a7aSWarner Losh<p> 50638e3e3a7aSWarner LoshEquivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 50648e3e3a7aSWarner Losh 50658e3e3a7aSWarner Losh 50668e3e3a7aSWarner Losh 50678e3e3a7aSWarner Losh 50688e3e3a7aSWarner Losh 50698e3e3a7aSWarner Losh<hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p> 50708e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 50718e3e3a7aSWarner Losh<pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre> 50728e3e3a7aSWarner Losh 50738e3e3a7aSWarner Losh<p> 50748e3e3a7aSWarner LoshConverts the Lua value at the given index 50758e3e3a7aSWarner Loshto the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. 50768e3e3a7aSWarner LoshThe Lua value must be an integer, 50778e3e3a7aSWarner Loshor a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>); 50788e3e3a7aSWarner Loshotherwise, <code>lua_tointegerx</code> returns 0. 50798e3e3a7aSWarner Losh 50808e3e3a7aSWarner Losh 50818e3e3a7aSWarner Losh<p> 50828e3e3a7aSWarner LoshIf <code>isnum</code> is not <code>NULL</code>, 50838e3e3a7aSWarner Loshits referent is assigned a boolean value that 50848e3e3a7aSWarner Loshindicates whether the operation succeeded. 50858e3e3a7aSWarner Losh 50868e3e3a7aSWarner Losh 50878e3e3a7aSWarner Losh 50888e3e3a7aSWarner Losh 50898e3e3a7aSWarner Losh 50908e3e3a7aSWarner Losh<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> 50918e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span> 50928e3e3a7aSWarner Losh<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> 50938e3e3a7aSWarner Losh 50948e3e3a7aSWarner Losh<p> 50958e3e3a7aSWarner LoshConverts the Lua value at the given index to a C string. 50968e3e3a7aSWarner LoshIf <code>len</code> is not <code>NULL</code>, 50978e3e3a7aSWarner Loshit sets <code>*len</code> with the string length. 50988e3e3a7aSWarner LoshThe Lua value must be a string or a number; 50998e3e3a7aSWarner Loshotherwise, the function returns <code>NULL</code>. 51008e3e3a7aSWarner LoshIf the value is a number, 51018e3e3a7aSWarner Loshthen <code>lua_tolstring</code> also 51028e3e3a7aSWarner Losh<em>changes the actual value in the stack to a string</em>. 51038e3e3a7aSWarner Losh(This change confuses <a href="#lua_next"><code>lua_next</code></a> 51048e3e3a7aSWarner Loshwhen <code>lua_tolstring</code> is applied to keys during a table traversal.) 51058e3e3a7aSWarner Losh 51068e3e3a7aSWarner Losh 51078e3e3a7aSWarner Losh<p> 51088e3e3a7aSWarner Losh<code>lua_tolstring</code> returns a pointer 51098e3e3a7aSWarner Loshto a string inside the Lua state. 51108e3e3a7aSWarner LoshThis string always has a zero ('<code>\0</code>') 51118e3e3a7aSWarner Loshafter its last character (as in C), 51128e3e3a7aSWarner Loshbut can contain other zeros in its body. 51138e3e3a7aSWarner Losh 51148e3e3a7aSWarner Losh 51158e3e3a7aSWarner Losh<p> 51168e3e3a7aSWarner LoshBecause Lua has garbage collection, 51178e3e3a7aSWarner Loshthere is no guarantee that the pointer returned by <code>lua_tolstring</code> 51188e3e3a7aSWarner Loshwill be valid after the corresponding Lua value is removed from the stack. 51198e3e3a7aSWarner Losh 51208e3e3a7aSWarner Losh 51218e3e3a7aSWarner Losh 51228e3e3a7aSWarner Losh 51238e3e3a7aSWarner Losh 51248e3e3a7aSWarner Losh<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> 51258e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 51268e3e3a7aSWarner Losh<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> 51278e3e3a7aSWarner Losh 51288e3e3a7aSWarner Losh<p> 51298e3e3a7aSWarner LoshEquivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 51308e3e3a7aSWarner Losh 51318e3e3a7aSWarner Losh 51328e3e3a7aSWarner Losh 51338e3e3a7aSWarner Losh 51348e3e3a7aSWarner Losh 51358e3e3a7aSWarner Losh<hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p> 51368e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 51378e3e3a7aSWarner Losh<pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre> 51388e3e3a7aSWarner Losh 51398e3e3a7aSWarner Losh<p> 51408e3e3a7aSWarner LoshConverts the Lua value at the given index 51418e3e3a7aSWarner Loshto the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). 51428e3e3a7aSWarner LoshThe Lua value must be a number or a string convertible to a number 51438e3e3a7aSWarner Losh(see <a href="#3.4.3">§3.4.3</a>); 51448e3e3a7aSWarner Loshotherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0. 51458e3e3a7aSWarner Losh 51468e3e3a7aSWarner Losh 51478e3e3a7aSWarner Losh<p> 51488e3e3a7aSWarner LoshIf <code>isnum</code> is not <code>NULL</code>, 51498e3e3a7aSWarner Loshits referent is assigned a boolean value that 51508e3e3a7aSWarner Loshindicates whether the operation succeeded. 51518e3e3a7aSWarner Losh 51528e3e3a7aSWarner Losh 51538e3e3a7aSWarner Losh 51548e3e3a7aSWarner Losh 51558e3e3a7aSWarner Losh 51568e3e3a7aSWarner Losh<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> 51578e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 51588e3e3a7aSWarner Losh<pre>const void *lua_topointer (lua_State *L, int index);</pre> 51598e3e3a7aSWarner Losh 51608e3e3a7aSWarner Losh<p> 51618e3e3a7aSWarner LoshConverts the value at the given index to a generic 51628e3e3a7aSWarner LoshC pointer (<code>void*</code>). 51638e3e3a7aSWarner LoshThe value can be a userdata, a table, a thread, or a function; 51648e3e3a7aSWarner Loshotherwise, <code>lua_topointer</code> returns <code>NULL</code>. 51658e3e3a7aSWarner LoshDifferent objects will give different pointers. 51668e3e3a7aSWarner LoshThere is no way to convert the pointer back to its original value. 51678e3e3a7aSWarner Losh 51688e3e3a7aSWarner Losh 51698e3e3a7aSWarner Losh<p> 51708e3e3a7aSWarner LoshTypically this function is used only for hashing and debug information. 51718e3e3a7aSWarner Losh 51728e3e3a7aSWarner Losh 51738e3e3a7aSWarner Losh 51748e3e3a7aSWarner Losh 51758e3e3a7aSWarner Losh 51768e3e3a7aSWarner Losh<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> 51778e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span> 51788e3e3a7aSWarner Losh<pre>const char *lua_tostring (lua_State *L, int index);</pre> 51798e3e3a7aSWarner Losh 51808e3e3a7aSWarner Losh<p> 51818e3e3a7aSWarner LoshEquivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. 51828e3e3a7aSWarner Losh 51838e3e3a7aSWarner Losh 51848e3e3a7aSWarner Losh 51858e3e3a7aSWarner Losh 51868e3e3a7aSWarner Losh 51878e3e3a7aSWarner Losh<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> 51888e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 51898e3e3a7aSWarner Losh<pre>lua_State *lua_tothread (lua_State *L, int index);</pre> 51908e3e3a7aSWarner Losh 51918e3e3a7aSWarner Losh<p> 51928e3e3a7aSWarner LoshConverts the value at the given index to a Lua thread 51938e3e3a7aSWarner Losh(represented as <code>lua_State*</code>). 51948e3e3a7aSWarner LoshThis value must be a thread; 51958e3e3a7aSWarner Loshotherwise, the function returns <code>NULL</code>. 51968e3e3a7aSWarner Losh 51978e3e3a7aSWarner Losh 51988e3e3a7aSWarner Losh 51998e3e3a7aSWarner Losh 52008e3e3a7aSWarner Losh 52018e3e3a7aSWarner Losh<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> 52028e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 52038e3e3a7aSWarner Losh<pre>void *lua_touserdata (lua_State *L, int index);</pre> 52048e3e3a7aSWarner Losh 52058e3e3a7aSWarner Losh<p> 52068e3e3a7aSWarner LoshIf the value at the given index is a full userdata, 52078e3e3a7aSWarner Loshreturns its block address. 52088e3e3a7aSWarner LoshIf the value is a light userdata, 52098e3e3a7aSWarner Loshreturns its pointer. 52108e3e3a7aSWarner LoshOtherwise, returns <code>NULL</code>. 52118e3e3a7aSWarner Losh 52128e3e3a7aSWarner Losh 52138e3e3a7aSWarner Losh 52148e3e3a7aSWarner Losh 52158e3e3a7aSWarner Losh 52168e3e3a7aSWarner Losh<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> 52178e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 52188e3e3a7aSWarner Losh<pre>int lua_type (lua_State *L, int index);</pre> 52198e3e3a7aSWarner Losh 52208e3e3a7aSWarner Losh<p> 52218e3e3a7aSWarner LoshReturns the type of the value in the given valid index, 52228e3e3a7aSWarner Loshor <code>LUA_TNONE</code> for a non-valid (but acceptable) index. 52238e3e3a7aSWarner LoshThe types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants 52248e3e3a7aSWarner Loshdefined in <code>lua.h</code>: 52258e3e3a7aSWarner Losh<a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a> (0), 52268e3e3a7aSWarner Losh<a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>, 52278e3e3a7aSWarner Losh<a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>, 52288e3e3a7aSWarner Losh<a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, 52298e3e3a7aSWarner Losh<a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, 52308e3e3a7aSWarner Losh<a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, 52318e3e3a7aSWarner Losh<a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, 52328e3e3a7aSWarner Losh<a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>, 52338e3e3a7aSWarner Loshand 52348e3e3a7aSWarner Losh<a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>. 52358e3e3a7aSWarner Losh 52368e3e3a7aSWarner Losh 52378e3e3a7aSWarner Losh 52388e3e3a7aSWarner Losh 52398e3e3a7aSWarner Losh 52408e3e3a7aSWarner Losh<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> 52418e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 52428e3e3a7aSWarner Losh<pre>const char *lua_typename (lua_State *L, int tp);</pre> 52438e3e3a7aSWarner Losh 52448e3e3a7aSWarner Losh<p> 52458e3e3a7aSWarner LoshReturns the name of the type encoded by the value <code>tp</code>, 52468e3e3a7aSWarner Loshwhich must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. 52478e3e3a7aSWarner Losh 52488e3e3a7aSWarner Losh 52498e3e3a7aSWarner Losh 52508e3e3a7aSWarner Losh 52518e3e3a7aSWarner Losh 52528e3e3a7aSWarner Losh<hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3> 52538e3e3a7aSWarner Losh<pre>typedef ... lua_Unsigned;</pre> 52548e3e3a7aSWarner Losh 52558e3e3a7aSWarner Losh<p> 52568e3e3a7aSWarner LoshThe unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>. 52578e3e3a7aSWarner Losh 52588e3e3a7aSWarner Losh 52598e3e3a7aSWarner Losh 52608e3e3a7aSWarner Losh 52618e3e3a7aSWarner Losh 52628e3e3a7aSWarner Losh<hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p> 52638e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 52648e3e3a7aSWarner Losh<pre>int lua_upvalueindex (int i);</pre> 52658e3e3a7aSWarner Losh 52668e3e3a7aSWarner Losh<p> 52678e3e3a7aSWarner LoshReturns the pseudo-index that represents the <code>i</code>-th upvalue of 52688e3e3a7aSWarner Loshthe running function (see <a href="#4.4">§4.4</a>). 52698e3e3a7aSWarner Losh 52708e3e3a7aSWarner Losh 52718e3e3a7aSWarner Losh 52728e3e3a7aSWarner Losh 52738e3e3a7aSWarner Losh 52748e3e3a7aSWarner Losh<hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p> 52758e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 52768e3e3a7aSWarner Losh<pre>const lua_Number *lua_version (lua_State *L);</pre> 52778e3e3a7aSWarner Losh 52788e3e3a7aSWarner Losh<p> 52798e3e3a7aSWarner LoshReturns the address of the version number 52808e3e3a7aSWarner Losh(a C static variable) 52818e3e3a7aSWarner Loshstored in the Lua core. 52828e3e3a7aSWarner LoshWhen called with a valid <a href="#lua_State"><code>lua_State</code></a>, 52838e3e3a7aSWarner Loshreturns the address of the version used to create that state. 52848e3e3a7aSWarner LoshWhen called with <code>NULL</code>, 52858e3e3a7aSWarner Loshreturns the address of the version running the call. 52868e3e3a7aSWarner Losh 52878e3e3a7aSWarner Losh 52888e3e3a7aSWarner Losh 52898e3e3a7aSWarner Losh 52908e3e3a7aSWarner Losh 52918e3e3a7aSWarner Losh<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> 52928e3e3a7aSWarner Losh<pre>typedef int (*lua_Writer) (lua_State *L, 52938e3e3a7aSWarner Losh const void* p, 52948e3e3a7aSWarner Losh size_t sz, 52958e3e3a7aSWarner Losh void* ud);</pre> 52968e3e3a7aSWarner Losh 52978e3e3a7aSWarner Losh<p> 52988e3e3a7aSWarner LoshThe type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. 52998e3e3a7aSWarner LoshEvery time it produces another piece of chunk, 53008e3e3a7aSWarner Losh<a href="#lua_dump"><code>lua_dump</code></a> calls the writer, 53018e3e3a7aSWarner Loshpassing along the buffer to be written (<code>p</code>), 53028e3e3a7aSWarner Loshits size (<code>sz</code>), 53038e3e3a7aSWarner Loshand the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. 53048e3e3a7aSWarner Losh 53058e3e3a7aSWarner Losh 53068e3e3a7aSWarner Losh<p> 53078e3e3a7aSWarner LoshThe writer returns an error code: 53088e3e3a7aSWarner Losh0 means no errors; 53098e3e3a7aSWarner Loshany other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from 53108e3e3a7aSWarner Loshcalling the writer again. 53118e3e3a7aSWarner Losh 53128e3e3a7aSWarner Losh 53138e3e3a7aSWarner Losh 53148e3e3a7aSWarner Losh 53158e3e3a7aSWarner Losh 53168e3e3a7aSWarner Losh<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> 53178e3e3a7aSWarner Losh<span class="apii">[-?, +?, –]</span> 53188e3e3a7aSWarner Losh<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> 53198e3e3a7aSWarner Losh 53208e3e3a7aSWarner Losh<p> 53218e3e3a7aSWarner LoshExchange values between different threads of the same state. 53228e3e3a7aSWarner Losh 53238e3e3a7aSWarner Losh 53248e3e3a7aSWarner Losh<p> 53258e3e3a7aSWarner LoshThis function pops <code>n</code> values from the stack <code>from</code>, 53268e3e3a7aSWarner Loshand pushes them onto the stack <code>to</code>. 53278e3e3a7aSWarner Losh 53288e3e3a7aSWarner Losh 53298e3e3a7aSWarner Losh 53308e3e3a7aSWarner Losh 53318e3e3a7aSWarner Losh 53328e3e3a7aSWarner Losh<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> 53338e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>e</em>]</span> 53348e3e3a7aSWarner Losh<pre>int lua_yield (lua_State *L, int nresults);</pre> 53358e3e3a7aSWarner Losh 53368e3e3a7aSWarner Losh<p> 53378e3e3a7aSWarner LoshThis function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 53388e3e3a7aSWarner Loshbut it has no continuation (see <a href="#4.7">§4.7</a>). 53398e3e3a7aSWarner LoshTherefore, when the thread resumes, 53408e3e3a7aSWarner Loshit continues the function that called 53418e3e3a7aSWarner Loshthe function calling <code>lua_yield</code>. 53428e3e3a7aSWarner Losh 53438e3e3a7aSWarner Losh 53448e3e3a7aSWarner Losh 53458e3e3a7aSWarner Losh 53468e3e3a7aSWarner Losh 53478e3e3a7aSWarner Losh<hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p> 53488e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>e</em>]</span> 53498e3e3a7aSWarner Losh<pre>int lua_yieldk (lua_State *L, 53508e3e3a7aSWarner Losh int nresults, 53518e3e3a7aSWarner Losh lua_KContext ctx, 53528e3e3a7aSWarner Losh lua_KFunction k);</pre> 53538e3e3a7aSWarner Losh 53548e3e3a7aSWarner Losh<p> 53558e3e3a7aSWarner LoshYields a coroutine (thread). 53568e3e3a7aSWarner Losh 53578e3e3a7aSWarner Losh 53588e3e3a7aSWarner Losh<p> 53598e3e3a7aSWarner LoshWhen a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 53608e3e3a7aSWarner Loshthe running coroutine suspends its execution, 53618e3e3a7aSWarner Loshand the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. 53628e3e3a7aSWarner LoshThe parameter <code>nresults</code> is the number of values from the stack 53638e3e3a7aSWarner Loshthat will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. 53648e3e3a7aSWarner Losh 53658e3e3a7aSWarner Losh 53668e3e3a7aSWarner Losh<p> 53678e3e3a7aSWarner LoshWhen the coroutine is resumed again, 53688e3e3a7aSWarner LoshLua calls the given continuation function <code>k</code> to continue 53698e3e3a7aSWarner Loshthe execution of the C function that yielded (see <a href="#4.7">§4.7</a>). 53708e3e3a7aSWarner LoshThis continuation function receives the same stack 53718e3e3a7aSWarner Loshfrom the previous function, 53728e3e3a7aSWarner Loshwith the <code>n</code> results removed and 53738e3e3a7aSWarner Loshreplaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>. 53748e3e3a7aSWarner LoshMoreover, 53758e3e3a7aSWarner Loshthe continuation function receives the value <code>ctx</code> 53768e3e3a7aSWarner Loshthat was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>. 53778e3e3a7aSWarner Losh 53788e3e3a7aSWarner Losh 53798e3e3a7aSWarner Losh<p> 53808e3e3a7aSWarner LoshUsually, this function does not return; 53818e3e3a7aSWarner Loshwhen the coroutine eventually resumes, 53828e3e3a7aSWarner Loshit continues executing the continuation function. 53838e3e3a7aSWarner LoshHowever, there is one special case, 53848e3e3a7aSWarner Loshwhich is when this function is called 53858e3e3a7aSWarner Loshfrom inside a line or a count hook (see <a href="#4.9">§4.9</a>). 53868e3e3a7aSWarner LoshIn that case, <code>lua_yieldk</code> should be called with no continuation 53878e3e3a7aSWarner Losh(probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results, 53888e3e3a7aSWarner Loshand the hook should return immediately after the call. 53898e3e3a7aSWarner LoshLua will yield and, 53908e3e3a7aSWarner Loshwhen the coroutine resumes again, 53918e3e3a7aSWarner Loshit will continue the normal execution 53928e3e3a7aSWarner Loshof the (Lua) function that triggered the hook. 53938e3e3a7aSWarner Losh 53948e3e3a7aSWarner Losh 53958e3e3a7aSWarner Losh<p> 53968e3e3a7aSWarner LoshThis function can raise an error if it is called from a thread 53978e3e3a7aSWarner Loshwith a pending C call with no continuation function, 53988e3e3a7aSWarner Loshor it is called from a thread that is not running inside a resume 53998e3e3a7aSWarner Losh(e.g., the main thread). 54008e3e3a7aSWarner Losh 54018e3e3a7aSWarner Losh 54028e3e3a7aSWarner Losh 54038e3e3a7aSWarner Losh 54048e3e3a7aSWarner Losh 54058e3e3a7aSWarner Losh 54068e3e3a7aSWarner Losh 54078e3e3a7aSWarner Losh<h2>4.9 – <a name="4.9">The Debug Interface</a></h2> 54088e3e3a7aSWarner Losh 54098e3e3a7aSWarner Losh<p> 54108e3e3a7aSWarner LoshLua has no built-in debugging facilities. 54118e3e3a7aSWarner LoshInstead, it offers a special interface 54128e3e3a7aSWarner Loshby means of functions and <em>hooks</em>. 54138e3e3a7aSWarner LoshThis interface allows the construction of different 54148e3e3a7aSWarner Loshkinds of debuggers, profilers, and other tools 54158e3e3a7aSWarner Loshthat need "inside information" from the interpreter. 54168e3e3a7aSWarner Losh 54178e3e3a7aSWarner Losh 54188e3e3a7aSWarner Losh 54198e3e3a7aSWarner Losh<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> 54208e3e3a7aSWarner Losh<pre>typedef struct lua_Debug { 54218e3e3a7aSWarner Losh int event; 54228e3e3a7aSWarner Losh const char *name; /* (n) */ 54238e3e3a7aSWarner Losh const char *namewhat; /* (n) */ 54248e3e3a7aSWarner Losh const char *what; /* (S) */ 54258e3e3a7aSWarner Losh const char *source; /* (S) */ 54268e3e3a7aSWarner Losh int currentline; /* (l) */ 54278e3e3a7aSWarner Losh int linedefined; /* (S) */ 54288e3e3a7aSWarner Losh int lastlinedefined; /* (S) */ 54298e3e3a7aSWarner Losh unsigned char nups; /* (u) number of upvalues */ 54308e3e3a7aSWarner Losh unsigned char nparams; /* (u) number of parameters */ 54318e3e3a7aSWarner Losh char isvararg; /* (u) */ 54328e3e3a7aSWarner Losh char istailcall; /* (t) */ 54338e3e3a7aSWarner Losh char short_src[LUA_IDSIZE]; /* (S) */ 54348e3e3a7aSWarner Losh /* private part */ 54358e3e3a7aSWarner Losh <em>other fields</em> 54368e3e3a7aSWarner Losh} lua_Debug;</pre> 54378e3e3a7aSWarner Losh 54388e3e3a7aSWarner Losh<p> 54398e3e3a7aSWarner LoshA structure used to carry different pieces of 54408e3e3a7aSWarner Loshinformation about a function or an activation record. 54418e3e3a7aSWarner Losh<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part 54428e3e3a7aSWarner Loshof this structure, for later use. 54438e3e3a7aSWarner LoshTo fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, 54448e3e3a7aSWarner Loshcall <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 54458e3e3a7aSWarner Losh 54468e3e3a7aSWarner Losh 54478e3e3a7aSWarner Losh<p> 54488e3e3a7aSWarner LoshThe fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: 54498e3e3a7aSWarner Losh 54508e3e3a7aSWarner Losh<ul> 54518e3e3a7aSWarner Losh 54528e3e3a7aSWarner Losh<li><b><code>source</code>: </b> 54538e3e3a7aSWarner Loshthe name of the chunk that created the function. 54548e3e3a7aSWarner LoshIf <code>source</code> starts with a '<code>@</code>', 54558e3e3a7aSWarner Loshit means that the function was defined in a file where 54568e3e3a7aSWarner Loshthe file name follows the '<code>@</code>'. 54578e3e3a7aSWarner LoshIf <code>source</code> starts with a '<code>=</code>', 54588e3e3a7aSWarner Loshthe remainder of its contents describe the source in a user-dependent manner. 54598e3e3a7aSWarner LoshOtherwise, 54608e3e3a7aSWarner Loshthe function was defined in a string where 54618e3e3a7aSWarner Losh<code>source</code> is that string. 54628e3e3a7aSWarner Losh</li> 54638e3e3a7aSWarner Losh 54648e3e3a7aSWarner Losh<li><b><code>short_src</code>: </b> 54658e3e3a7aSWarner Losha "printable" version of <code>source</code>, to be used in error messages. 54668e3e3a7aSWarner Losh</li> 54678e3e3a7aSWarner Losh 54688e3e3a7aSWarner Losh<li><b><code>linedefined</code>: </b> 54698e3e3a7aSWarner Loshthe line number where the definition of the function starts. 54708e3e3a7aSWarner Losh</li> 54718e3e3a7aSWarner Losh 54728e3e3a7aSWarner Losh<li><b><code>lastlinedefined</code>: </b> 54738e3e3a7aSWarner Loshthe line number where the definition of the function ends. 54748e3e3a7aSWarner Losh</li> 54758e3e3a7aSWarner Losh 54768e3e3a7aSWarner Losh<li><b><code>what</code>: </b> 54778e3e3a7aSWarner Loshthe string <code>"Lua"</code> if the function is a Lua function, 54788e3e3a7aSWarner Losh<code>"C"</code> if it is a C function, 54798e3e3a7aSWarner Losh<code>"main"</code> if it is the main part of a chunk. 54808e3e3a7aSWarner Losh</li> 54818e3e3a7aSWarner Losh 54828e3e3a7aSWarner Losh<li><b><code>currentline</code>: </b> 54838e3e3a7aSWarner Loshthe current line where the given function is executing. 54848e3e3a7aSWarner LoshWhen no line information is available, 54858e3e3a7aSWarner Losh<code>currentline</code> is set to -1. 54868e3e3a7aSWarner Losh</li> 54878e3e3a7aSWarner Losh 54888e3e3a7aSWarner Losh<li><b><code>name</code>: </b> 54898e3e3a7aSWarner Losha reasonable name for the given function. 54908e3e3a7aSWarner LoshBecause functions in Lua are first-class values, 54918e3e3a7aSWarner Loshthey do not have a fixed name: 54928e3e3a7aSWarner Loshsome functions can be the value of multiple global variables, 54938e3e3a7aSWarner Loshwhile others can be stored only in a table field. 54948e3e3a7aSWarner LoshThe <code>lua_getinfo</code> function checks how the function was 54958e3e3a7aSWarner Loshcalled to find a suitable name. 54968e3e3a7aSWarner LoshIf it cannot find a name, 54978e3e3a7aSWarner Loshthen <code>name</code> is set to <code>NULL</code>. 54988e3e3a7aSWarner Losh</li> 54998e3e3a7aSWarner Losh 55008e3e3a7aSWarner Losh<li><b><code>namewhat</code>: </b> 55018e3e3a7aSWarner Loshexplains the <code>name</code> field. 55028e3e3a7aSWarner LoshThe value of <code>namewhat</code> can be 55038e3e3a7aSWarner Losh<code>"global"</code>, <code>"local"</code>, <code>"method"</code>, 55048e3e3a7aSWarner Losh<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), 55058e3e3a7aSWarner Loshaccording to how the function was called. 55068e3e3a7aSWarner Losh(Lua uses the empty string when no other option seems to apply.) 55078e3e3a7aSWarner Losh</li> 55088e3e3a7aSWarner Losh 55098e3e3a7aSWarner Losh<li><b><code>istailcall</code>: </b> 55108e3e3a7aSWarner Loshtrue if this function invocation was called by a tail call. 55118e3e3a7aSWarner LoshIn this case, the caller of this level is not in the stack. 55128e3e3a7aSWarner Losh</li> 55138e3e3a7aSWarner Losh 55148e3e3a7aSWarner Losh<li><b><code>nups</code>: </b> 55158e3e3a7aSWarner Loshthe number of upvalues of the function. 55168e3e3a7aSWarner Losh</li> 55178e3e3a7aSWarner Losh 55188e3e3a7aSWarner Losh<li><b><code>nparams</code>: </b> 55198e3e3a7aSWarner Loshthe number of fixed parameters of the function 55208e3e3a7aSWarner Losh(always 0 for C functions). 55218e3e3a7aSWarner Losh</li> 55228e3e3a7aSWarner Losh 55238e3e3a7aSWarner Losh<li><b><code>isvararg</code>: </b> 55248e3e3a7aSWarner Loshtrue if the function is a vararg function 55258e3e3a7aSWarner Losh(always true for C functions). 55268e3e3a7aSWarner Losh</li> 55278e3e3a7aSWarner Losh 55288e3e3a7aSWarner Losh</ul> 55298e3e3a7aSWarner Losh 55308e3e3a7aSWarner Losh 55318e3e3a7aSWarner Losh 55328e3e3a7aSWarner Losh 55338e3e3a7aSWarner Losh<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> 55348e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 55358e3e3a7aSWarner Losh<pre>lua_Hook lua_gethook (lua_State *L);</pre> 55368e3e3a7aSWarner Losh 55378e3e3a7aSWarner Losh<p> 55388e3e3a7aSWarner LoshReturns the current hook function. 55398e3e3a7aSWarner Losh 55408e3e3a7aSWarner Losh 55418e3e3a7aSWarner Losh 55428e3e3a7aSWarner Losh 55438e3e3a7aSWarner Losh 55448e3e3a7aSWarner Losh<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> 55458e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 55468e3e3a7aSWarner Losh<pre>int lua_gethookcount (lua_State *L);</pre> 55478e3e3a7aSWarner Losh 55488e3e3a7aSWarner Losh<p> 55498e3e3a7aSWarner LoshReturns the current hook count. 55508e3e3a7aSWarner Losh 55518e3e3a7aSWarner Losh 55528e3e3a7aSWarner Losh 55538e3e3a7aSWarner Losh 55548e3e3a7aSWarner Losh 55558e3e3a7aSWarner Losh<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> 55568e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 55578e3e3a7aSWarner Losh<pre>int lua_gethookmask (lua_State *L);</pre> 55588e3e3a7aSWarner Losh 55598e3e3a7aSWarner Losh<p> 55608e3e3a7aSWarner LoshReturns the current hook mask. 55618e3e3a7aSWarner Losh 55628e3e3a7aSWarner Losh 55638e3e3a7aSWarner Losh 55648e3e3a7aSWarner Losh 55658e3e3a7aSWarner Losh 55668e3e3a7aSWarner Losh<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> 55678e3e3a7aSWarner Losh<span class="apii">[-(0|1), +(0|1|2), <em>e</em>]</span> 55688e3e3a7aSWarner Losh<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> 55698e3e3a7aSWarner Losh 55708e3e3a7aSWarner Losh<p> 55718e3e3a7aSWarner LoshGets information about a specific function or function invocation. 55728e3e3a7aSWarner Losh 55738e3e3a7aSWarner Losh 55748e3e3a7aSWarner Losh<p> 55758e3e3a7aSWarner LoshTo get information about a function invocation, 55768e3e3a7aSWarner Loshthe parameter <code>ar</code> must be a valid activation record that was 55778e3e3a7aSWarner Loshfilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 55788e3e3a7aSWarner Loshgiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 55798e3e3a7aSWarner Losh 55808e3e3a7aSWarner Losh 55818e3e3a7aSWarner Losh<p> 5582*e112e9d2SKyle EvansTo get information about a function, you push it onto the stack 55838e3e3a7aSWarner Loshand start the <code>what</code> string with the character '<code>></code>'. 55848e3e3a7aSWarner Losh(In that case, 55858e3e3a7aSWarner Losh<code>lua_getinfo</code> pops the function from the top of the stack.) 55868e3e3a7aSWarner LoshFor instance, to know in which line a function <code>f</code> was defined, 55878e3e3a7aSWarner Loshyou can write the following code: 55888e3e3a7aSWarner Losh 55898e3e3a7aSWarner Losh<pre> 55908e3e3a7aSWarner Losh lua_Debug ar; 55918e3e3a7aSWarner Losh lua_getglobal(L, "f"); /* get global 'f' */ 55928e3e3a7aSWarner Losh lua_getinfo(L, ">S", &ar); 55938e3e3a7aSWarner Losh printf("%d\n", ar.linedefined); 55948e3e3a7aSWarner Losh</pre> 55958e3e3a7aSWarner Losh 55968e3e3a7aSWarner Losh<p> 55978e3e3a7aSWarner LoshEach character in the string <code>what</code> 55988e3e3a7aSWarner Loshselects some fields of the structure <code>ar</code> to be filled or 55998e3e3a7aSWarner Losha value to be pushed on the stack: 56008e3e3a7aSWarner Losh 56018e3e3a7aSWarner Losh<ul> 56028e3e3a7aSWarner Losh 56038e3e3a7aSWarner Losh<li><b>'<code>n</code>': </b> fills in the field <code>name</code> and <code>namewhat</code>; 56048e3e3a7aSWarner Losh</li> 56058e3e3a7aSWarner Losh 56068e3e3a7aSWarner Losh<li><b>'<code>S</code>': </b> 56078e3e3a7aSWarner Loshfills in the fields <code>source</code>, <code>short_src</code>, 56088e3e3a7aSWarner Losh<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; 56098e3e3a7aSWarner Losh</li> 56108e3e3a7aSWarner Losh 56118e3e3a7aSWarner Losh<li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>; 56128e3e3a7aSWarner Losh</li> 56138e3e3a7aSWarner Losh 56148e3e3a7aSWarner Losh<li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>; 56158e3e3a7aSWarner Losh</li> 56168e3e3a7aSWarner Losh 56178e3e3a7aSWarner Losh<li><b>'<code>u</code>': </b> fills in the fields 56188e3e3a7aSWarner Losh<code>nups</code>, <code>nparams</code>, and <code>isvararg</code>; 56198e3e3a7aSWarner Losh</li> 56208e3e3a7aSWarner Losh 56218e3e3a7aSWarner Losh<li><b>'<code>f</code>': </b> 56228e3e3a7aSWarner Loshpushes onto the stack the function that is 56238e3e3a7aSWarner Loshrunning at the given level; 56248e3e3a7aSWarner Losh</li> 56258e3e3a7aSWarner Losh 56268e3e3a7aSWarner Losh<li><b>'<code>L</code>': </b> 56278e3e3a7aSWarner Loshpushes onto the stack a table whose indices are the 56288e3e3a7aSWarner Loshnumbers of the lines that are valid on the function. 56298e3e3a7aSWarner Losh(A <em>valid line</em> is a line with some associated code, 56308e3e3a7aSWarner Loshthat is, a line where you can put a break point. 56318e3e3a7aSWarner LoshNon-valid lines include empty lines and comments.) 56328e3e3a7aSWarner Losh 56338e3e3a7aSWarner Losh 56348e3e3a7aSWarner Losh<p> 56358e3e3a7aSWarner LoshIf this option is given together with option '<code>f</code>', 56368e3e3a7aSWarner Loshits table is pushed after the function. 56378e3e3a7aSWarner Losh</li> 56388e3e3a7aSWarner Losh 56398e3e3a7aSWarner Losh</ul> 56408e3e3a7aSWarner Losh 56418e3e3a7aSWarner Losh<p> 56428e3e3a7aSWarner LoshThis function returns 0 on error 56438e3e3a7aSWarner Losh(for instance, an invalid option in <code>what</code>). 56448e3e3a7aSWarner Losh 56458e3e3a7aSWarner Losh 56468e3e3a7aSWarner Losh 56478e3e3a7aSWarner Losh 56488e3e3a7aSWarner Losh 56498e3e3a7aSWarner Losh<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> 56508e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), –]</span> 56518e3e3a7aSWarner Losh<pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 56528e3e3a7aSWarner Losh 56538e3e3a7aSWarner Losh<p> 56548e3e3a7aSWarner LoshGets information about a local variable of 56558e3e3a7aSWarner Losha given activation record or a given function. 56568e3e3a7aSWarner Losh 56578e3e3a7aSWarner Losh 56588e3e3a7aSWarner Losh<p> 56598e3e3a7aSWarner LoshIn the first case, 56608e3e3a7aSWarner Loshthe parameter <code>ar</code> must be a valid activation record that was 56618e3e3a7aSWarner Loshfilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 56628e3e3a7aSWarner Loshgiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 56638e3e3a7aSWarner LoshThe index <code>n</code> selects which local variable to inspect; 56648e3e3a7aSWarner Loshsee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices 56658e3e3a7aSWarner Loshand names. 56668e3e3a7aSWarner Losh 56678e3e3a7aSWarner Losh 56688e3e3a7aSWarner Losh<p> 56698e3e3a7aSWarner Losh<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack 56708e3e3a7aSWarner Loshand returns its name. 56718e3e3a7aSWarner Losh 56728e3e3a7aSWarner Losh 56738e3e3a7aSWarner Losh<p> 56748e3e3a7aSWarner LoshIn the second case, <code>ar</code> must be <code>NULL</code> and the function 56758e3e3a7aSWarner Loshto be inspected must be at the top of the stack. 56768e3e3a7aSWarner LoshIn this case, only parameters of Lua functions are visible 56778e3e3a7aSWarner Losh(as there is no information about what variables are active) 56788e3e3a7aSWarner Loshand no values are pushed onto the stack. 56798e3e3a7aSWarner Losh 56808e3e3a7aSWarner Losh 56818e3e3a7aSWarner Losh<p> 56828e3e3a7aSWarner LoshReturns <code>NULL</code> (and pushes nothing) 56838e3e3a7aSWarner Loshwhen the index is greater than 56848e3e3a7aSWarner Loshthe number of active local variables. 56858e3e3a7aSWarner Losh 56868e3e3a7aSWarner Losh 56878e3e3a7aSWarner Losh 56888e3e3a7aSWarner Losh 56898e3e3a7aSWarner Losh 56908e3e3a7aSWarner Losh<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> 56918e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 56928e3e3a7aSWarner Losh<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> 56938e3e3a7aSWarner Losh 56948e3e3a7aSWarner Losh<p> 56958e3e3a7aSWarner LoshGets information about the interpreter runtime stack. 56968e3e3a7aSWarner Losh 56978e3e3a7aSWarner Losh 56988e3e3a7aSWarner Losh<p> 56998e3e3a7aSWarner LoshThis function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with 57008e3e3a7aSWarner Loshan identification of the <em>activation record</em> 57018e3e3a7aSWarner Loshof the function executing at a given level. 57028e3e3a7aSWarner LoshLevel 0 is the current running function, 57038e3e3a7aSWarner Loshwhereas level <em>n+1</em> is the function that has called level <em>n</em> 57048e3e3a7aSWarner Losh(except for tail calls, which do not count on the stack). 57058e3e3a7aSWarner LoshWhen there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1; 57068e3e3a7aSWarner Loshwhen called with a level greater than the stack depth, 57078e3e3a7aSWarner Loshit returns 0. 57088e3e3a7aSWarner Losh 57098e3e3a7aSWarner Losh 57108e3e3a7aSWarner Losh 57118e3e3a7aSWarner Losh 57128e3e3a7aSWarner Losh 57138e3e3a7aSWarner Losh<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> 57148e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), –]</span> 57158e3e3a7aSWarner Losh<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> 57168e3e3a7aSWarner Losh 57178e3e3a7aSWarner Losh<p> 57188e3e3a7aSWarner LoshGets information about the <code>n</code>-th upvalue 57198e3e3a7aSWarner Loshof the closure at index <code>funcindex</code>. 57208e3e3a7aSWarner LoshIt pushes the upvalue's value onto the stack 57218e3e3a7aSWarner Loshand returns its name. 57228e3e3a7aSWarner LoshReturns <code>NULL</code> (and pushes nothing) 57238e3e3a7aSWarner Loshwhen the index <code>n</code> is greater than the number of upvalues. 57248e3e3a7aSWarner Losh 57258e3e3a7aSWarner Losh 57268e3e3a7aSWarner Losh<p> 57278e3e3a7aSWarner LoshFor C functions, this function uses the empty string <code>""</code> 57288e3e3a7aSWarner Loshas a name for all upvalues. 57298e3e3a7aSWarner Losh(For Lua functions, 57308e3e3a7aSWarner Loshupvalues are the external local variables that the function uses, 57318e3e3a7aSWarner Loshand that are consequently included in its closure.) 57328e3e3a7aSWarner Losh 57338e3e3a7aSWarner Losh 57348e3e3a7aSWarner Losh<p> 57358e3e3a7aSWarner LoshUpvalues have no particular order, 57368e3e3a7aSWarner Loshas they are active through the whole function. 57378e3e3a7aSWarner LoshThey are numbered in an arbitrary order. 57388e3e3a7aSWarner Losh 57398e3e3a7aSWarner Losh 57408e3e3a7aSWarner Losh 57418e3e3a7aSWarner Losh 57428e3e3a7aSWarner Losh 57438e3e3a7aSWarner Losh<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> 57448e3e3a7aSWarner Losh<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> 57458e3e3a7aSWarner Losh 57468e3e3a7aSWarner Losh<p> 57478e3e3a7aSWarner LoshType for debugging hook functions. 57488e3e3a7aSWarner Losh 57498e3e3a7aSWarner Losh 57508e3e3a7aSWarner Losh<p> 57518e3e3a7aSWarner LoshWhenever a hook is called, its <code>ar</code> argument has its field 57528e3e3a7aSWarner Losh<code>event</code> set to the specific event that triggered the hook. 57538e3e3a7aSWarner LoshLua identifies these events with the following constants: 57548e3e3a7aSWarner Losh<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, 57558e3e3a7aSWarner Losh<a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, 57568e3e3a7aSWarner Loshand <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. 57578e3e3a7aSWarner LoshMoreover, for line events, the field <code>currentline</code> is also set. 57588e3e3a7aSWarner LoshTo get the value of any other field in <code>ar</code>, 57598e3e3a7aSWarner Loshthe hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 57608e3e3a7aSWarner Losh 57618e3e3a7aSWarner Losh 57628e3e3a7aSWarner Losh<p> 57638e3e3a7aSWarner LoshFor call events, <code>event</code> can be <code>LUA_HOOKCALL</code>, 57648e3e3a7aSWarner Loshthe normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call; 57658e3e3a7aSWarner Loshin this case, there will be no corresponding return event. 57668e3e3a7aSWarner Losh 57678e3e3a7aSWarner Losh 57688e3e3a7aSWarner Losh<p> 57698e3e3a7aSWarner LoshWhile Lua is running a hook, it disables other calls to hooks. 57708e3e3a7aSWarner LoshTherefore, if a hook calls back Lua to execute a function or a chunk, 57718e3e3a7aSWarner Loshthis execution occurs without any calls to hooks. 57728e3e3a7aSWarner Losh 57738e3e3a7aSWarner Losh 57748e3e3a7aSWarner Losh<p> 57758e3e3a7aSWarner LoshHook functions cannot have continuations, 57768e3e3a7aSWarner Loshthat is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 57778e3e3a7aSWarner Losh<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>. 57788e3e3a7aSWarner Losh 57798e3e3a7aSWarner Losh 57808e3e3a7aSWarner Losh<p> 57818e3e3a7aSWarner LoshHook functions can yield under the following conditions: 57828e3e3a7aSWarner LoshOnly count and line events can yield; 57838e3e3a7aSWarner Loshto yield, a hook function must finish its execution 57848e3e3a7aSWarner Loshcalling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero 57858e3e3a7aSWarner Losh(that is, with no values). 57868e3e3a7aSWarner Losh 57878e3e3a7aSWarner Losh 57888e3e3a7aSWarner Losh 57898e3e3a7aSWarner Losh 57908e3e3a7aSWarner Losh 57918e3e3a7aSWarner Losh<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> 57928e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 57938e3e3a7aSWarner Losh<pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> 57948e3e3a7aSWarner Losh 57958e3e3a7aSWarner Losh<p> 57968e3e3a7aSWarner LoshSets the debugging hook function. 57978e3e3a7aSWarner Losh 57988e3e3a7aSWarner Losh 57998e3e3a7aSWarner Losh<p> 58008e3e3a7aSWarner LoshArgument <code>f</code> is the hook function. 58018e3e3a7aSWarner Losh<code>mask</code> specifies on which events the hook will be called: 58028e3e3a7aSWarner Loshit is formed by a bitwise OR of the constants 58038e3e3a7aSWarner Losh<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, 58048e3e3a7aSWarner Losh<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, 58058e3e3a7aSWarner Losh<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, 58068e3e3a7aSWarner Loshand <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. 58078e3e3a7aSWarner LoshThe <code>count</code> argument is only meaningful when the mask 58088e3e3a7aSWarner Loshincludes <code>LUA_MASKCOUNT</code>. 58098e3e3a7aSWarner LoshFor each event, the hook is called as explained below: 58108e3e3a7aSWarner Losh 58118e3e3a7aSWarner Losh<ul> 58128e3e3a7aSWarner Losh 58138e3e3a7aSWarner Losh<li><b>The call hook: </b> is called when the interpreter calls a function. 58148e3e3a7aSWarner LoshThe hook is called just after Lua enters the new function, 58158e3e3a7aSWarner Loshbefore the function gets its arguments. 58168e3e3a7aSWarner Losh</li> 58178e3e3a7aSWarner Losh 58188e3e3a7aSWarner Losh<li><b>The return hook: </b> is called when the interpreter returns from a function. 58198e3e3a7aSWarner LoshThe hook is called just before Lua leaves the function. 58208e3e3a7aSWarner LoshThere is no standard way to access the values 58218e3e3a7aSWarner Loshto be returned by the function. 58228e3e3a7aSWarner Losh</li> 58238e3e3a7aSWarner Losh 58248e3e3a7aSWarner Losh<li><b>The line hook: </b> is called when the interpreter is about to 58258e3e3a7aSWarner Loshstart the execution of a new line of code, 58268e3e3a7aSWarner Loshor when it jumps back in the code (even to the same line). 58278e3e3a7aSWarner Losh(This event only happens while Lua is executing a Lua function.) 58288e3e3a7aSWarner Losh</li> 58298e3e3a7aSWarner Losh 58308e3e3a7aSWarner Losh<li><b>The count hook: </b> is called after the interpreter executes every 58318e3e3a7aSWarner Losh<code>count</code> instructions. 58328e3e3a7aSWarner Losh(This event only happens while Lua is executing a Lua function.) 58338e3e3a7aSWarner Losh</li> 58348e3e3a7aSWarner Losh 58358e3e3a7aSWarner Losh</ul> 58368e3e3a7aSWarner Losh 58378e3e3a7aSWarner Losh<p> 58388e3e3a7aSWarner LoshA hook is disabled by setting <code>mask</code> to zero. 58398e3e3a7aSWarner Losh 58408e3e3a7aSWarner Losh 58418e3e3a7aSWarner Losh 58428e3e3a7aSWarner Losh 58438e3e3a7aSWarner Losh 58448e3e3a7aSWarner Losh<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> 58458e3e3a7aSWarner Losh<span class="apii">[-(0|1), +0, –]</span> 58468e3e3a7aSWarner Losh<pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 58478e3e3a7aSWarner Losh 58488e3e3a7aSWarner Losh<p> 58498e3e3a7aSWarner LoshSets the value of a local variable of a given activation record. 58508e3e3a7aSWarner LoshIt assigns the value at the top of the stack 58518e3e3a7aSWarner Loshto the variable and returns its name. 58528e3e3a7aSWarner LoshIt also pops the value from the stack. 58538e3e3a7aSWarner Losh 58548e3e3a7aSWarner Losh 58558e3e3a7aSWarner Losh<p> 58568e3e3a7aSWarner LoshReturns <code>NULL</code> (and pops nothing) 58578e3e3a7aSWarner Loshwhen the index is greater than 58588e3e3a7aSWarner Loshthe number of active local variables. 58598e3e3a7aSWarner Losh 58608e3e3a7aSWarner Losh 58618e3e3a7aSWarner Losh<p> 58628e3e3a7aSWarner LoshParameters <code>ar</code> and <code>n</code> are as in function <a href="#lua_getlocal"><code>lua_getlocal</code></a>. 58638e3e3a7aSWarner Losh 58648e3e3a7aSWarner Losh 58658e3e3a7aSWarner Losh 58668e3e3a7aSWarner Losh 58678e3e3a7aSWarner Losh 58688e3e3a7aSWarner Losh<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> 58698e3e3a7aSWarner Losh<span class="apii">[-(0|1), +0, –]</span> 58708e3e3a7aSWarner Losh<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> 58718e3e3a7aSWarner Losh 58728e3e3a7aSWarner Losh<p> 58738e3e3a7aSWarner LoshSets the value of a closure's upvalue. 58748e3e3a7aSWarner LoshIt assigns the value at the top of the stack 58758e3e3a7aSWarner Loshto the upvalue and returns its name. 58768e3e3a7aSWarner LoshIt also pops the value from the stack. 58778e3e3a7aSWarner Losh 58788e3e3a7aSWarner Losh 58798e3e3a7aSWarner Losh<p> 58808e3e3a7aSWarner LoshReturns <code>NULL</code> (and pops nothing) 58818e3e3a7aSWarner Loshwhen the index <code>n</code> is greater than the number of upvalues. 58828e3e3a7aSWarner Losh 58838e3e3a7aSWarner Losh 58848e3e3a7aSWarner Losh<p> 58858e3e3a7aSWarner LoshParameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>. 58868e3e3a7aSWarner Losh 58878e3e3a7aSWarner Losh 58888e3e3a7aSWarner Losh 58898e3e3a7aSWarner Losh 58908e3e3a7aSWarner Losh 58918e3e3a7aSWarner Losh<hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p> 58928e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 58938e3e3a7aSWarner Losh<pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre> 58948e3e3a7aSWarner Losh 58958e3e3a7aSWarner Losh<p> 58968e3e3a7aSWarner LoshReturns a unique identifier for the upvalue numbered <code>n</code> 58978e3e3a7aSWarner Loshfrom the closure at index <code>funcindex</code>. 58988e3e3a7aSWarner Losh 58998e3e3a7aSWarner Losh 59008e3e3a7aSWarner Losh<p> 59018e3e3a7aSWarner LoshThese unique identifiers allow a program to check whether different 59028e3e3a7aSWarner Loshclosures share upvalues. 59038e3e3a7aSWarner LoshLua closures that share an upvalue 59048e3e3a7aSWarner Losh(that is, that access a same external local variable) 59058e3e3a7aSWarner Loshwill return identical ids for those upvalue indices. 59068e3e3a7aSWarner Losh 59078e3e3a7aSWarner Losh 59088e3e3a7aSWarner Losh<p> 59098e3e3a7aSWarner LoshParameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, 59108e3e3a7aSWarner Loshbut <code>n</code> cannot be greater than the number of upvalues. 59118e3e3a7aSWarner Losh 59128e3e3a7aSWarner Losh 59138e3e3a7aSWarner Losh 59148e3e3a7aSWarner Losh 59158e3e3a7aSWarner Losh 59168e3e3a7aSWarner Losh<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p> 59178e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 59188e3e3a7aSWarner Losh<pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1, 59198e3e3a7aSWarner Losh int funcindex2, int n2);</pre> 59208e3e3a7aSWarner Losh 59218e3e3a7aSWarner Losh<p> 59228e3e3a7aSWarner LoshMake the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code> 59238e3e3a7aSWarner Loshrefer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>. 59248e3e3a7aSWarner Losh 59258e3e3a7aSWarner Losh 59268e3e3a7aSWarner Losh 59278e3e3a7aSWarner Losh 59288e3e3a7aSWarner Losh 59298e3e3a7aSWarner Losh 59308e3e3a7aSWarner Losh 59318e3e3a7aSWarner Losh<h1>5 – <a name="5">The Auxiliary Library</a></h1> 59328e3e3a7aSWarner Losh 59338e3e3a7aSWarner Losh<p> 59348e3e3a7aSWarner Losh 59358e3e3a7aSWarner LoshThe <em>auxiliary library</em> provides several convenient functions 59368e3e3a7aSWarner Loshto interface C with Lua. 59378e3e3a7aSWarner LoshWhile the basic API provides the primitive functions for all 59388e3e3a7aSWarner Loshinteractions between C and Lua, 59398e3e3a7aSWarner Loshthe auxiliary library provides higher-level functions for some 59408e3e3a7aSWarner Loshcommon tasks. 59418e3e3a7aSWarner Losh 59428e3e3a7aSWarner Losh 59438e3e3a7aSWarner Losh<p> 59448e3e3a7aSWarner LoshAll functions and types from the auxiliary library 59458e3e3a7aSWarner Loshare defined in header file <code>lauxlib.h</code> and 59468e3e3a7aSWarner Loshhave a prefix <code>luaL_</code>. 59478e3e3a7aSWarner Losh 59488e3e3a7aSWarner Losh 59498e3e3a7aSWarner Losh<p> 59508e3e3a7aSWarner LoshAll functions in the auxiliary library are built on 59518e3e3a7aSWarner Loshtop of the basic API, 59528e3e3a7aSWarner Loshand so they provide nothing that cannot be done with that API. 59538e3e3a7aSWarner LoshNevertheless, the use of the auxiliary library ensures 59548e3e3a7aSWarner Loshmore consistency to your code. 59558e3e3a7aSWarner Losh 59568e3e3a7aSWarner Losh 59578e3e3a7aSWarner Losh<p> 59588e3e3a7aSWarner LoshSeveral functions in the auxiliary library use internally some 59598e3e3a7aSWarner Loshextra stack slots. 59608e3e3a7aSWarner LoshWhen a function in the auxiliary library uses less than five slots, 59618e3e3a7aSWarner Loshit does not check the stack size; 59628e3e3a7aSWarner Loshit simply assumes that there are enough slots. 59638e3e3a7aSWarner Losh 59648e3e3a7aSWarner Losh 59658e3e3a7aSWarner Losh<p> 59668e3e3a7aSWarner LoshSeveral functions in the auxiliary library are used to 59678e3e3a7aSWarner Loshcheck C function arguments. 59688e3e3a7aSWarner LoshBecause the error message is formatted for arguments 59698e3e3a7aSWarner Losh(e.g., "<code>bad argument #1</code>"), 59708e3e3a7aSWarner Loshyou should not use these functions for other stack values. 59718e3e3a7aSWarner Losh 59728e3e3a7aSWarner Losh 59738e3e3a7aSWarner Losh<p> 59748e3e3a7aSWarner LoshFunctions called <code>luaL_check*</code> 59758e3e3a7aSWarner Loshalways raise an error if the check is not satisfied. 59768e3e3a7aSWarner Losh 59778e3e3a7aSWarner Losh 59788e3e3a7aSWarner Losh 59798e3e3a7aSWarner Losh<h2>5.1 – <a name="5.1">Functions and Types</a></h2> 59808e3e3a7aSWarner Losh 59818e3e3a7aSWarner Losh<p> 59828e3e3a7aSWarner LoshHere we list all functions and types from the auxiliary library 59838e3e3a7aSWarner Loshin alphabetical order. 59848e3e3a7aSWarner Losh 59858e3e3a7aSWarner Losh 59868e3e3a7aSWarner Losh 59878e3e3a7aSWarner Losh<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> 59888e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 59898e3e3a7aSWarner Losh<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> 59908e3e3a7aSWarner Losh 59918e3e3a7aSWarner Losh<p> 59928e3e3a7aSWarner LoshAdds the byte <code>c</code> to the buffer <code>B</code> 59938e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 59948e3e3a7aSWarner Losh 59958e3e3a7aSWarner Losh 59968e3e3a7aSWarner Losh 59978e3e3a7aSWarner Losh 59988e3e3a7aSWarner Losh 59998e3e3a7aSWarner Losh<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> 60008e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 60018e3e3a7aSWarner Losh<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> 60028e3e3a7aSWarner Losh 60038e3e3a7aSWarner Losh<p> 60048e3e3a7aSWarner LoshAdds the string pointed to by <code>s</code> with length <code>l</code> to 60058e3e3a7aSWarner Loshthe buffer <code>B</code> 60068e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 60078e3e3a7aSWarner LoshThe string can contain embedded zeros. 60088e3e3a7aSWarner Losh 60098e3e3a7aSWarner Losh 60108e3e3a7aSWarner Losh 60118e3e3a7aSWarner Losh 60128e3e3a7aSWarner Losh 60138e3e3a7aSWarner Losh<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> 60148e3e3a7aSWarner Losh<span class="apii">[-?, +?, –]</span> 60158e3e3a7aSWarner Losh<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> 60168e3e3a7aSWarner Losh 60178e3e3a7aSWarner Losh<p> 60188e3e3a7aSWarner LoshAdds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>) 60198e3e3a7aSWarner Losha string of length <code>n</code> previously copied to the 60208e3e3a7aSWarner Loshbuffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). 60218e3e3a7aSWarner Losh 60228e3e3a7aSWarner Losh 60238e3e3a7aSWarner Losh 60248e3e3a7aSWarner Losh 60258e3e3a7aSWarner Losh 60268e3e3a7aSWarner Losh<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> 60278e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 60288e3e3a7aSWarner Losh<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> 60298e3e3a7aSWarner Losh 60308e3e3a7aSWarner Losh<p> 60318e3e3a7aSWarner LoshAdds the zero-terminated string pointed to by <code>s</code> 60328e3e3a7aSWarner Loshto the buffer <code>B</code> 60338e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 60348e3e3a7aSWarner Losh 60358e3e3a7aSWarner Losh 60368e3e3a7aSWarner Losh 60378e3e3a7aSWarner Losh 60388e3e3a7aSWarner Losh 60398e3e3a7aSWarner Losh<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> 60408e3e3a7aSWarner Losh<span class="apii">[-1, +?, <em>m</em>]</span> 60418e3e3a7aSWarner Losh<pre>void luaL_addvalue (luaL_Buffer *B);</pre> 60428e3e3a7aSWarner Losh 60438e3e3a7aSWarner Losh<p> 60448e3e3a7aSWarner LoshAdds the value at the top of the stack 60458e3e3a7aSWarner Loshto the buffer <code>B</code> 60468e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 60478e3e3a7aSWarner LoshPops the value. 60488e3e3a7aSWarner Losh 60498e3e3a7aSWarner Losh 60508e3e3a7aSWarner Losh<p> 60518e3e3a7aSWarner LoshThis is the only function on string buffers that can (and must) 60528e3e3a7aSWarner Loshbe called with an extra element on the stack, 60538e3e3a7aSWarner Loshwhich is the value to be added to the buffer. 60548e3e3a7aSWarner Losh 60558e3e3a7aSWarner Losh 60568e3e3a7aSWarner Losh 60578e3e3a7aSWarner Losh 60588e3e3a7aSWarner Losh 60598e3e3a7aSWarner Losh<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> 60608e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 60618e3e3a7aSWarner Losh<pre>void luaL_argcheck (lua_State *L, 60628e3e3a7aSWarner Losh int cond, 60638e3e3a7aSWarner Losh int arg, 60648e3e3a7aSWarner Losh const char *extramsg);</pre> 60658e3e3a7aSWarner Losh 60668e3e3a7aSWarner Losh<p> 60678e3e3a7aSWarner LoshChecks whether <code>cond</code> is true. 60688e3e3a7aSWarner LoshIf it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>). 60698e3e3a7aSWarner Losh 60708e3e3a7aSWarner Losh 60718e3e3a7aSWarner Losh 60728e3e3a7aSWarner Losh 60738e3e3a7aSWarner Losh 60748e3e3a7aSWarner Losh<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> 60758e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 60768e3e3a7aSWarner Losh<pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre> 60778e3e3a7aSWarner Losh 60788e3e3a7aSWarner Losh<p> 60798e3e3a7aSWarner LoshRaises an error reporting a problem with argument <code>arg</code> 60808e3e3a7aSWarner Loshof the C function that called it, 60818e3e3a7aSWarner Loshusing a standard message 60828e3e3a7aSWarner Loshthat includes <code>extramsg</code> as a comment: 60838e3e3a7aSWarner Losh 60848e3e3a7aSWarner Losh<pre> 60858e3e3a7aSWarner Losh bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>) 60868e3e3a7aSWarner Losh</pre><p> 60878e3e3a7aSWarner LoshThis function never returns. 60888e3e3a7aSWarner Losh 60898e3e3a7aSWarner Losh 60908e3e3a7aSWarner Losh 60918e3e3a7aSWarner Losh 60928e3e3a7aSWarner Losh 60938e3e3a7aSWarner Losh<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> 60948e3e3a7aSWarner Losh<pre>typedef struct luaL_Buffer luaL_Buffer;</pre> 60958e3e3a7aSWarner Losh 60968e3e3a7aSWarner Losh<p> 60978e3e3a7aSWarner LoshType for a <em>string buffer</em>. 60988e3e3a7aSWarner Losh 60998e3e3a7aSWarner Losh 61008e3e3a7aSWarner Losh<p> 61018e3e3a7aSWarner LoshA string buffer allows C code to build Lua strings piecemeal. 61028e3e3a7aSWarner LoshIts pattern of use is as follows: 61038e3e3a7aSWarner Losh 61048e3e3a7aSWarner Losh<ul> 61058e3e3a7aSWarner Losh 61068e3e3a7aSWarner Losh<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 61078e3e3a7aSWarner Losh 61088e3e3a7aSWarner Losh<li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> 61098e3e3a7aSWarner Losh 61108e3e3a7aSWarner Losh<li> 61118e3e3a7aSWarner LoshThen add string pieces to the buffer calling any of 61128e3e3a7aSWarner Loshthe <code>luaL_add*</code> functions. 61138e3e3a7aSWarner Losh</li> 61148e3e3a7aSWarner Losh 61158e3e3a7aSWarner Losh<li> 61168e3e3a7aSWarner LoshFinish by calling <code>luaL_pushresult(&b)</code>. 61178e3e3a7aSWarner LoshThis call leaves the final string on the top of the stack. 61188e3e3a7aSWarner Losh</li> 61198e3e3a7aSWarner Losh 61208e3e3a7aSWarner Losh</ul> 61218e3e3a7aSWarner Losh 61228e3e3a7aSWarner Losh<p> 61238e3e3a7aSWarner LoshIf you know beforehand the total size of the resulting string, 61248e3e3a7aSWarner Loshyou can use the buffer like this: 61258e3e3a7aSWarner Losh 61268e3e3a7aSWarner Losh<ul> 61278e3e3a7aSWarner Losh 61288e3e3a7aSWarner Losh<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 61298e3e3a7aSWarner Losh 61308e3e3a7aSWarner Losh<li>Then initialize it and preallocate a space of 61318e3e3a7aSWarner Loshsize <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li> 61328e3e3a7aSWarner Losh 61338e3e3a7aSWarner Losh<li>Then copy the string into that space.</li> 61348e3e3a7aSWarner Losh 61358e3e3a7aSWarner Losh<li> 61368e3e3a7aSWarner LoshFinish by calling <code>luaL_pushresultsize(&b, sz)</code>, 61378e3e3a7aSWarner Loshwhere <code>sz</code> is the total size of the resulting string 61388e3e3a7aSWarner Loshcopied into that space. 61398e3e3a7aSWarner Losh</li> 61408e3e3a7aSWarner Losh 61418e3e3a7aSWarner Losh</ul> 61428e3e3a7aSWarner Losh 61438e3e3a7aSWarner Losh<p> 61448e3e3a7aSWarner LoshDuring its normal operation, 61458e3e3a7aSWarner Losha string buffer uses a variable number of stack slots. 61468e3e3a7aSWarner LoshSo, while using a buffer, you cannot assume that you know where 61478e3e3a7aSWarner Loshthe top of the stack is. 61488e3e3a7aSWarner LoshYou can use the stack between successive calls to buffer operations 61498e3e3a7aSWarner Loshas long as that use is balanced; 61508e3e3a7aSWarner Loshthat is, 61518e3e3a7aSWarner Loshwhen you call a buffer operation, 61528e3e3a7aSWarner Loshthe stack is at the same level 61538e3e3a7aSWarner Loshit was immediately after the previous buffer operation. 61548e3e3a7aSWarner Losh(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) 61558e3e3a7aSWarner LoshAfter calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its 61568e3e3a7aSWarner Loshlevel when the buffer was initialized, 61578e3e3a7aSWarner Loshplus the final string on its top. 61588e3e3a7aSWarner Losh 61598e3e3a7aSWarner Losh 61608e3e3a7aSWarner Losh 61618e3e3a7aSWarner Losh 61628e3e3a7aSWarner Losh 61638e3e3a7aSWarner Losh<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> 61648e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 61658e3e3a7aSWarner Losh<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> 61668e3e3a7aSWarner Losh 61678e3e3a7aSWarner Losh<p> 61688e3e3a7aSWarner LoshInitializes a buffer <code>B</code>. 61698e3e3a7aSWarner LoshThis function does not allocate any space; 61708e3e3a7aSWarner Loshthe buffer must be declared as a variable 61718e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 61728e3e3a7aSWarner Losh 61738e3e3a7aSWarner Losh 61748e3e3a7aSWarner Losh 61758e3e3a7aSWarner Losh 61768e3e3a7aSWarner Losh 61778e3e3a7aSWarner Losh<hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p> 61788e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 61798e3e3a7aSWarner Losh<pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre> 61808e3e3a7aSWarner Losh 61818e3e3a7aSWarner Losh<p> 61828e3e3a7aSWarner LoshEquivalent to the sequence 61838e3e3a7aSWarner Losh<a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>. 61848e3e3a7aSWarner Losh 61858e3e3a7aSWarner Losh 61868e3e3a7aSWarner Losh 61878e3e3a7aSWarner Losh 61888e3e3a7aSWarner Losh 61898e3e3a7aSWarner Losh<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> 61908e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), <em>e</em>]</span> 61918e3e3a7aSWarner Losh<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> 61928e3e3a7aSWarner Losh 61938e3e3a7aSWarner Losh<p> 61948e3e3a7aSWarner LoshCalls a metamethod. 61958e3e3a7aSWarner Losh 61968e3e3a7aSWarner Losh 61978e3e3a7aSWarner Losh<p> 61988e3e3a7aSWarner LoshIf the object at index <code>obj</code> has a metatable and this 61998e3e3a7aSWarner Loshmetatable has a field <code>e</code>, 62008e3e3a7aSWarner Loshthis function calls this field passing the object as its only argument. 62018e3e3a7aSWarner LoshIn this case this function returns true and pushes onto the 62028e3e3a7aSWarner Loshstack the value returned by the call. 62038e3e3a7aSWarner LoshIf there is no metatable or no metamethod, 62048e3e3a7aSWarner Loshthis function returns false (without pushing any value on the stack). 62058e3e3a7aSWarner Losh 62068e3e3a7aSWarner Losh 62078e3e3a7aSWarner Losh 62088e3e3a7aSWarner Losh 62098e3e3a7aSWarner Losh 62108e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> 62118e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 62128e3e3a7aSWarner Losh<pre>void luaL_checkany (lua_State *L, int arg);</pre> 62138e3e3a7aSWarner Losh 62148e3e3a7aSWarner Losh<p> 62158e3e3a7aSWarner LoshChecks whether the function has an argument 62168e3e3a7aSWarner Loshof any type (including <b>nil</b>) at position <code>arg</code>. 62178e3e3a7aSWarner Losh 62188e3e3a7aSWarner Losh 62198e3e3a7aSWarner Losh 62208e3e3a7aSWarner Losh 62218e3e3a7aSWarner Losh 62228e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> 62238e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 62248e3e3a7aSWarner Losh<pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre> 62258e3e3a7aSWarner Losh 62268e3e3a7aSWarner Losh<p> 62278e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is an integer 62288e3e3a7aSWarner Losh(or can be converted to an integer) 62298e3e3a7aSWarner Loshand returns this integer cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. 62308e3e3a7aSWarner Losh 62318e3e3a7aSWarner Losh 62328e3e3a7aSWarner Losh 62338e3e3a7aSWarner Losh 62348e3e3a7aSWarner Losh 62358e3e3a7aSWarner Losh<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> 62368e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 62378e3e3a7aSWarner Losh<pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre> 62388e3e3a7aSWarner Losh 62398e3e3a7aSWarner Losh<p> 62408e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string 62418e3e3a7aSWarner Loshand returns this string; 62428e3e3a7aSWarner Loshif <code>l</code> is not <code>NULL</code> fills <code>*l</code> 62438e3e3a7aSWarner Loshwith the string's length. 62448e3e3a7aSWarner Losh 62458e3e3a7aSWarner Losh 62468e3e3a7aSWarner Losh<p> 62478e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 62488e3e3a7aSWarner Loshso all conversions and caveats of that function apply here. 62498e3e3a7aSWarner Losh 62508e3e3a7aSWarner Losh 62518e3e3a7aSWarner Losh 62528e3e3a7aSWarner Losh 62538e3e3a7aSWarner Losh 62548e3e3a7aSWarner Losh<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> 62558e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 62568e3e3a7aSWarner Losh<pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre> 62578e3e3a7aSWarner Losh 62588e3e3a7aSWarner Losh<p> 62598e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a number 62608e3e3a7aSWarner Loshand returns this number. 62618e3e3a7aSWarner Losh 62628e3e3a7aSWarner Losh 62638e3e3a7aSWarner Losh 62648e3e3a7aSWarner Losh 62658e3e3a7aSWarner Losh 62668e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> 62678e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 62688e3e3a7aSWarner Losh<pre>int luaL_checkoption (lua_State *L, 62698e3e3a7aSWarner Losh int arg, 62708e3e3a7aSWarner Losh const char *def, 62718e3e3a7aSWarner Losh const char *const lst[]);</pre> 62728e3e3a7aSWarner Losh 62738e3e3a7aSWarner Losh<p> 62748e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string and 62758e3e3a7aSWarner Loshsearches for this string in the array <code>lst</code> 62768e3e3a7aSWarner Losh(which must be NULL-terminated). 62778e3e3a7aSWarner LoshReturns the index in the array where the string was found. 62788e3e3a7aSWarner LoshRaises an error if the argument is not a string or 62798e3e3a7aSWarner Loshif the string cannot be found. 62808e3e3a7aSWarner Losh 62818e3e3a7aSWarner Losh 62828e3e3a7aSWarner Losh<p> 62838e3e3a7aSWarner LoshIf <code>def</code> is not <code>NULL</code>, 62848e3e3a7aSWarner Loshthe function uses <code>def</code> as a default value when 62858e3e3a7aSWarner Loshthere is no argument <code>arg</code> or when this argument is <b>nil</b>. 62868e3e3a7aSWarner Losh 62878e3e3a7aSWarner Losh 62888e3e3a7aSWarner Losh<p> 62898e3e3a7aSWarner LoshThis is a useful function for mapping strings to C enums. 62908e3e3a7aSWarner Losh(The usual convention in Lua libraries is 62918e3e3a7aSWarner Loshto use strings instead of numbers to select options.) 62928e3e3a7aSWarner Losh 62938e3e3a7aSWarner Losh 62948e3e3a7aSWarner Losh 62958e3e3a7aSWarner Losh 62968e3e3a7aSWarner Losh 62978e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> 62988e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 62998e3e3a7aSWarner Losh<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> 63008e3e3a7aSWarner Losh 63018e3e3a7aSWarner Losh<p> 63028e3e3a7aSWarner LoshGrows the stack size to <code>top + sz</code> elements, 63038e3e3a7aSWarner Loshraising an error if the stack cannot grow to that size. 63048e3e3a7aSWarner Losh<code>msg</code> is an additional text to go into the error message 63058e3e3a7aSWarner Losh(or <code>NULL</code> for no additional text). 63068e3e3a7aSWarner Losh 63078e3e3a7aSWarner Losh 63088e3e3a7aSWarner Losh 63098e3e3a7aSWarner Losh 63108e3e3a7aSWarner Losh 63118e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> 63128e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 63138e3e3a7aSWarner Losh<pre>const char *luaL_checkstring (lua_State *L, int arg);</pre> 63148e3e3a7aSWarner Losh 63158e3e3a7aSWarner Losh<p> 63168e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string 63178e3e3a7aSWarner Loshand returns this string. 63188e3e3a7aSWarner Losh 63198e3e3a7aSWarner Losh 63208e3e3a7aSWarner Losh<p> 63218e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 63228e3e3a7aSWarner Loshso all conversions and caveats of that function apply here. 63238e3e3a7aSWarner Losh 63248e3e3a7aSWarner Losh 63258e3e3a7aSWarner Losh 63268e3e3a7aSWarner Losh 63278e3e3a7aSWarner Losh 63288e3e3a7aSWarner Losh<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> 63298e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 63308e3e3a7aSWarner Losh<pre>void luaL_checktype (lua_State *L, int arg, int t);</pre> 63318e3e3a7aSWarner Losh 63328e3e3a7aSWarner Losh<p> 63338e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> has type <code>t</code>. 63348e3e3a7aSWarner LoshSee <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. 63358e3e3a7aSWarner Losh 63368e3e3a7aSWarner Losh 63378e3e3a7aSWarner Losh 63388e3e3a7aSWarner Losh 63398e3e3a7aSWarner Losh 63408e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> 63418e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 63428e3e3a7aSWarner Losh<pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre> 63438e3e3a7aSWarner Losh 63448e3e3a7aSWarner Losh<p> 63458e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a userdata 63468e3e3a7aSWarner Loshof the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and 63478e3e3a7aSWarner Loshreturns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>). 63488e3e3a7aSWarner Losh 63498e3e3a7aSWarner Losh 63508e3e3a7aSWarner Losh 63518e3e3a7aSWarner Losh 63528e3e3a7aSWarner Losh 63538e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p> 63548e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 63558e3e3a7aSWarner Losh<pre>void luaL_checkversion (lua_State *L);</pre> 63568e3e3a7aSWarner Losh 63578e3e3a7aSWarner Losh<p> 63588e3e3a7aSWarner LoshChecks whether the core running the call, 63598e3e3a7aSWarner Loshthe core that created the Lua state, 63608e3e3a7aSWarner Loshand the code making the call are all using the same version of Lua. 63618e3e3a7aSWarner LoshAlso checks whether the core running the call 63628e3e3a7aSWarner Loshand the core that created the Lua state 63638e3e3a7aSWarner Loshare using the same address space. 63648e3e3a7aSWarner Losh 63658e3e3a7aSWarner Losh 63668e3e3a7aSWarner Losh 63678e3e3a7aSWarner Losh 63688e3e3a7aSWarner Losh 63698e3e3a7aSWarner Losh<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> 63708e3e3a7aSWarner Losh<span class="apii">[-0, +?, <em>e</em>]</span> 63718e3e3a7aSWarner Losh<pre>int luaL_dofile (lua_State *L, const char *filename);</pre> 63728e3e3a7aSWarner Losh 63738e3e3a7aSWarner Losh<p> 63748e3e3a7aSWarner LoshLoads and runs the given file. 63758e3e3a7aSWarner LoshIt is defined as the following macro: 63768e3e3a7aSWarner Losh 63778e3e3a7aSWarner Losh<pre> 63788e3e3a7aSWarner Losh (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) 63798e3e3a7aSWarner Losh</pre><p> 63808e3e3a7aSWarner LoshIt returns false if there are no errors 63818e3e3a7aSWarner Loshor true in case of errors. 63828e3e3a7aSWarner Losh 63838e3e3a7aSWarner Losh 63848e3e3a7aSWarner Losh 63858e3e3a7aSWarner Losh 63868e3e3a7aSWarner Losh 63878e3e3a7aSWarner Losh<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> 63888e3e3a7aSWarner Losh<span class="apii">[-0, +?, –]</span> 63898e3e3a7aSWarner Losh<pre>int luaL_dostring (lua_State *L, const char *str);</pre> 63908e3e3a7aSWarner Losh 63918e3e3a7aSWarner Losh<p> 63928e3e3a7aSWarner LoshLoads and runs the given string. 63938e3e3a7aSWarner LoshIt is defined as the following macro: 63948e3e3a7aSWarner Losh 63958e3e3a7aSWarner Losh<pre> 63968e3e3a7aSWarner Losh (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) 63978e3e3a7aSWarner Losh</pre><p> 63988e3e3a7aSWarner LoshIt returns false if there are no errors 63998e3e3a7aSWarner Loshor true in case of errors. 64008e3e3a7aSWarner Losh 64018e3e3a7aSWarner Losh 64028e3e3a7aSWarner Losh 64038e3e3a7aSWarner Losh 64048e3e3a7aSWarner Losh 64058e3e3a7aSWarner Losh<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> 64068e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 64078e3e3a7aSWarner Losh<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> 64088e3e3a7aSWarner Losh 64098e3e3a7aSWarner Losh<p> 64108e3e3a7aSWarner LoshRaises an error. 64118e3e3a7aSWarner LoshThe error message format is given by <code>fmt</code> 64128e3e3a7aSWarner Loshplus any extra arguments, 64138e3e3a7aSWarner Loshfollowing the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. 64148e3e3a7aSWarner LoshIt also adds at the beginning of the message the file name and 64158e3e3a7aSWarner Loshthe line number where the error occurred, 64168e3e3a7aSWarner Loshif this information is available. 64178e3e3a7aSWarner Losh 64188e3e3a7aSWarner Losh 64198e3e3a7aSWarner Losh<p> 64208e3e3a7aSWarner LoshThis function never returns, 64218e3e3a7aSWarner Loshbut it is an idiom to use it in C functions 64228e3e3a7aSWarner Loshas <code>return luaL_error(<em>args</em>)</code>. 64238e3e3a7aSWarner Losh 64248e3e3a7aSWarner Losh 64258e3e3a7aSWarner Losh 64268e3e3a7aSWarner Losh 64278e3e3a7aSWarner Losh 64288e3e3a7aSWarner Losh<hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p> 64298e3e3a7aSWarner Losh<span class="apii">[-0, +3, <em>m</em>]</span> 64308e3e3a7aSWarner Losh<pre>int luaL_execresult (lua_State *L, int stat);</pre> 64318e3e3a7aSWarner Losh 64328e3e3a7aSWarner Losh<p> 64338e3e3a7aSWarner LoshThis function produces the return values for 64348e3e3a7aSWarner Loshprocess-related functions in the standard library 64358e3e3a7aSWarner Losh(<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>). 64368e3e3a7aSWarner Losh 64378e3e3a7aSWarner Losh 64388e3e3a7aSWarner Losh 64398e3e3a7aSWarner Losh 64408e3e3a7aSWarner Losh 64418e3e3a7aSWarner Losh<hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p> 64428e3e3a7aSWarner Losh<span class="apii">[-0, +(1|3), <em>m</em>]</span> 64438e3e3a7aSWarner Losh<pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre> 64448e3e3a7aSWarner Losh 64458e3e3a7aSWarner Losh<p> 64468e3e3a7aSWarner LoshThis function produces the return values for 64478e3e3a7aSWarner Loshfile-related functions in the standard library 64488e3e3a7aSWarner Losh(<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.). 64498e3e3a7aSWarner Losh 64508e3e3a7aSWarner Losh 64518e3e3a7aSWarner Losh 64528e3e3a7aSWarner Losh 64538e3e3a7aSWarner Losh 64548e3e3a7aSWarner Losh<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> 64558e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), <em>m</em>]</span> 64568e3e3a7aSWarner Losh<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> 64578e3e3a7aSWarner Losh 64588e3e3a7aSWarner Losh<p> 64598e3e3a7aSWarner LoshPushes onto the stack the field <code>e</code> from the metatable 6460*e112e9d2SKyle Evansof the object at index <code>obj</code> and returns the type of the pushed value. 64618e3e3a7aSWarner LoshIf the object does not have a metatable, 64628e3e3a7aSWarner Loshor if the metatable does not have this field, 64638e3e3a7aSWarner Loshpushes nothing and returns <code>LUA_TNIL</code>. 64648e3e3a7aSWarner Losh 64658e3e3a7aSWarner Losh 64668e3e3a7aSWarner Losh 64678e3e3a7aSWarner Losh 64688e3e3a7aSWarner Losh 64698e3e3a7aSWarner Losh<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> 64708e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 64718e3e3a7aSWarner Losh<pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre> 64728e3e3a7aSWarner Losh 64738e3e3a7aSWarner Losh<p> 64748e3e3a7aSWarner LoshPushes onto the stack the metatable associated with name <code>tname</code> 64758e3e3a7aSWarner Loshin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) 64768e3e3a7aSWarner Losh(<b>nil</b> if there is no metatable associated with that name). 64778e3e3a7aSWarner LoshReturns the type of the pushed value. 64788e3e3a7aSWarner Losh 64798e3e3a7aSWarner Losh 64808e3e3a7aSWarner Losh 64818e3e3a7aSWarner Losh 64828e3e3a7aSWarner Losh 64838e3e3a7aSWarner Losh<hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p> 64848e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 64858e3e3a7aSWarner Losh<pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre> 64868e3e3a7aSWarner Losh 64878e3e3a7aSWarner Losh<p> 64888e3e3a7aSWarner LoshEnsures that the value <code>t[fname]</code>, 64898e3e3a7aSWarner Loshwhere <code>t</code> is the value at index <code>idx</code>, 64908e3e3a7aSWarner Loshis a table, 64918e3e3a7aSWarner Loshand pushes that table onto the stack. 64928e3e3a7aSWarner LoshReturns true if it finds a previous table there 64938e3e3a7aSWarner Loshand false if it creates a new table. 64948e3e3a7aSWarner Losh 64958e3e3a7aSWarner Losh 64968e3e3a7aSWarner Losh 64978e3e3a7aSWarner Losh 64988e3e3a7aSWarner Losh 64998e3e3a7aSWarner Losh<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> 65008e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 65018e3e3a7aSWarner Losh<pre>const char *luaL_gsub (lua_State *L, 65028e3e3a7aSWarner Losh const char *s, 65038e3e3a7aSWarner Losh const char *p, 65048e3e3a7aSWarner Losh const char *r);</pre> 65058e3e3a7aSWarner Losh 65068e3e3a7aSWarner Losh<p> 65078e3e3a7aSWarner LoshCreates a copy of string <code>s</code> by replacing 65088e3e3a7aSWarner Loshany occurrence of the string <code>p</code> 65098e3e3a7aSWarner Loshwith the string <code>r</code>. 65108e3e3a7aSWarner LoshPushes the resulting string on the stack and returns it. 65118e3e3a7aSWarner Losh 65128e3e3a7aSWarner Losh 65138e3e3a7aSWarner Losh 65148e3e3a7aSWarner Losh 65158e3e3a7aSWarner Losh 65168e3e3a7aSWarner Losh<hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p> 65178e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 65188e3e3a7aSWarner Losh<pre>lua_Integer luaL_len (lua_State *L, int index);</pre> 65198e3e3a7aSWarner Losh 65208e3e3a7aSWarner Losh<p> 65218e3e3a7aSWarner LoshReturns the "length" of the value at the given index 65228e3e3a7aSWarner Loshas a number; 65238e3e3a7aSWarner Loshit is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). 65248e3e3a7aSWarner LoshRaises an error if the result of the operation is not an integer. 65258e3e3a7aSWarner Losh(This case only can happen through metamethods.) 65268e3e3a7aSWarner Losh 65278e3e3a7aSWarner Losh 65288e3e3a7aSWarner Losh 65298e3e3a7aSWarner Losh 65308e3e3a7aSWarner Losh 65318e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> 65328e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 65338e3e3a7aSWarner Losh<pre>int luaL_loadbuffer (lua_State *L, 65348e3e3a7aSWarner Losh const char *buff, 65358e3e3a7aSWarner Losh size_t sz, 65368e3e3a7aSWarner Losh const char *name);</pre> 65378e3e3a7aSWarner Losh 65388e3e3a7aSWarner Losh<p> 65398e3e3a7aSWarner LoshEquivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>. 65408e3e3a7aSWarner Losh 65418e3e3a7aSWarner Losh 65428e3e3a7aSWarner Losh 65438e3e3a7aSWarner Losh 65448e3e3a7aSWarner Losh 65458e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p> 65468e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 65478e3e3a7aSWarner Losh<pre>int luaL_loadbufferx (lua_State *L, 65488e3e3a7aSWarner Losh const char *buff, 65498e3e3a7aSWarner Losh size_t sz, 65508e3e3a7aSWarner Losh const char *name, 65518e3e3a7aSWarner Losh const char *mode);</pre> 65528e3e3a7aSWarner Losh 65538e3e3a7aSWarner Losh<p> 65548e3e3a7aSWarner LoshLoads a buffer as a Lua chunk. 65558e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the 65568e3e3a7aSWarner Loshbuffer pointed to by <code>buff</code> with size <code>sz</code>. 65578e3e3a7aSWarner Losh 65588e3e3a7aSWarner Losh 65598e3e3a7aSWarner Losh<p> 65608e3e3a7aSWarner LoshThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 65618e3e3a7aSWarner Losh<code>name</code> is the chunk name, 65628e3e3a7aSWarner Loshused for debug information and error messages. 65638e3e3a7aSWarner LoshThe string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. 65648e3e3a7aSWarner Losh 65658e3e3a7aSWarner Losh 65668e3e3a7aSWarner Losh 65678e3e3a7aSWarner Losh 65688e3e3a7aSWarner Losh 65698e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> 65708e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 65718e3e3a7aSWarner Losh<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> 65728e3e3a7aSWarner Losh 65738e3e3a7aSWarner Losh<p> 65748e3e3a7aSWarner LoshEquivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>. 65758e3e3a7aSWarner Losh 65768e3e3a7aSWarner Losh 65778e3e3a7aSWarner Losh 65788e3e3a7aSWarner Losh 65798e3e3a7aSWarner Losh 65808e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p> 65818e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 65828e3e3a7aSWarner Losh<pre>int luaL_loadfilex (lua_State *L, const char *filename, 65838e3e3a7aSWarner Losh const char *mode);</pre> 65848e3e3a7aSWarner Losh 65858e3e3a7aSWarner Losh<p> 65868e3e3a7aSWarner LoshLoads a file as a Lua chunk. 65878e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file 65888e3e3a7aSWarner Loshnamed <code>filename</code>. 65898e3e3a7aSWarner LoshIf <code>filename</code> is <code>NULL</code>, 65908e3e3a7aSWarner Loshthen it loads from the standard input. 65918e3e3a7aSWarner LoshThe first line in the file is ignored if it starts with a <code>#</code>. 65928e3e3a7aSWarner Losh 65938e3e3a7aSWarner Losh 65948e3e3a7aSWarner Losh<p> 65958e3e3a7aSWarner LoshThe string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. 65968e3e3a7aSWarner Losh 65978e3e3a7aSWarner Losh 65988e3e3a7aSWarner Losh<p> 65998e3e3a7aSWarner LoshThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, 66008e3e3a7aSWarner Loshbut it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> 66018e3e3a7aSWarner Loshfor file-related errors 66028e3e3a7aSWarner Losh(e.g., it cannot open or read the file). 66038e3e3a7aSWarner Losh 66048e3e3a7aSWarner Losh 66058e3e3a7aSWarner Losh<p> 66068e3e3a7aSWarner LoshAs <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 66078e3e3a7aSWarner Loshit does not run it. 66088e3e3a7aSWarner Losh 66098e3e3a7aSWarner Losh 66108e3e3a7aSWarner Losh 66118e3e3a7aSWarner Losh 66128e3e3a7aSWarner Losh 66138e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> 66148e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 66158e3e3a7aSWarner Losh<pre>int luaL_loadstring (lua_State *L, const char *s);</pre> 66168e3e3a7aSWarner Losh 66178e3e3a7aSWarner Losh<p> 66188e3e3a7aSWarner LoshLoads a string as a Lua chunk. 66198e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in 66208e3e3a7aSWarner Loshthe zero-terminated string <code>s</code>. 66218e3e3a7aSWarner Losh 66228e3e3a7aSWarner Losh 66238e3e3a7aSWarner Losh<p> 66248e3e3a7aSWarner LoshThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 66258e3e3a7aSWarner Losh 66268e3e3a7aSWarner Losh 66278e3e3a7aSWarner Losh<p> 66288e3e3a7aSWarner LoshAlso as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 66298e3e3a7aSWarner Loshit does not run it. 66308e3e3a7aSWarner Losh 66318e3e3a7aSWarner Losh 66328e3e3a7aSWarner Losh 66338e3e3a7aSWarner Losh 66348e3e3a7aSWarner Losh 66358e3e3a7aSWarner Losh<hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p> 66368e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 66378e3e3a7aSWarner Losh<pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre> 66388e3e3a7aSWarner Losh 66398e3e3a7aSWarner Losh<p> 66408e3e3a7aSWarner LoshCreates a new table and registers there 66418e3e3a7aSWarner Loshthe functions in list <code>l</code>. 66428e3e3a7aSWarner Losh 66438e3e3a7aSWarner Losh 66448e3e3a7aSWarner Losh<p> 66458e3e3a7aSWarner LoshIt is implemented as the following macro: 66468e3e3a7aSWarner Losh 66478e3e3a7aSWarner Losh<pre> 66488e3e3a7aSWarner Losh (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0)) 66498e3e3a7aSWarner Losh</pre><p> 66508e3e3a7aSWarner LoshThe array <code>l</code> must be the actual array, 66518e3e3a7aSWarner Loshnot a pointer to it. 66528e3e3a7aSWarner Losh 66538e3e3a7aSWarner Losh 66548e3e3a7aSWarner Losh 66558e3e3a7aSWarner Losh 66568e3e3a7aSWarner Losh 66578e3e3a7aSWarner Losh<hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p> 66588e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 66598e3e3a7aSWarner Losh<pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre> 66608e3e3a7aSWarner Losh 66618e3e3a7aSWarner Losh<p> 66628e3e3a7aSWarner LoshCreates a new table with a size optimized 66638e3e3a7aSWarner Loshto store all entries in the array <code>l</code> 66648e3e3a7aSWarner Losh(but does not actually store them). 66658e3e3a7aSWarner LoshIt is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> 66668e3e3a7aSWarner Losh(see <a href="#luaL_newlib"><code>luaL_newlib</code></a>). 66678e3e3a7aSWarner Losh 66688e3e3a7aSWarner Losh 66698e3e3a7aSWarner Losh<p> 66708e3e3a7aSWarner LoshIt is implemented as a macro. 66718e3e3a7aSWarner LoshThe array <code>l</code> must be the actual array, 66728e3e3a7aSWarner Loshnot a pointer to it. 66738e3e3a7aSWarner Losh 66748e3e3a7aSWarner Losh 66758e3e3a7aSWarner Losh 66768e3e3a7aSWarner Losh 66778e3e3a7aSWarner Losh 66788e3e3a7aSWarner Losh<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> 66798e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 66808e3e3a7aSWarner Losh<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> 66818e3e3a7aSWarner Losh 66828e3e3a7aSWarner Losh<p> 66838e3e3a7aSWarner LoshIf the registry already has the key <code>tname</code>, 66848e3e3a7aSWarner Loshreturns 0. 66858e3e3a7aSWarner LoshOtherwise, 66868e3e3a7aSWarner Loshcreates a new table to be used as a metatable for userdata, 66878e3e3a7aSWarner Loshadds to this new table the pair <code>__name = tname</code>, 66888e3e3a7aSWarner Loshadds to the registry the pair <code>[tname] = new table</code>, 66898e3e3a7aSWarner Loshand returns 1. 66908e3e3a7aSWarner Losh(The entry <code>__name</code> is used by some error-reporting functions.) 66918e3e3a7aSWarner Losh 66928e3e3a7aSWarner Losh 66938e3e3a7aSWarner Losh<p> 66948e3e3a7aSWarner LoshIn both cases pushes onto the stack the final value associated 66958e3e3a7aSWarner Loshwith <code>tname</code> in the registry. 66968e3e3a7aSWarner Losh 66978e3e3a7aSWarner Losh 66988e3e3a7aSWarner Losh 66998e3e3a7aSWarner Losh 67008e3e3a7aSWarner Losh 67018e3e3a7aSWarner Losh<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> 67028e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 67038e3e3a7aSWarner Losh<pre>lua_State *luaL_newstate (void);</pre> 67048e3e3a7aSWarner Losh 67058e3e3a7aSWarner Losh<p> 67068e3e3a7aSWarner LoshCreates a new Lua state. 67078e3e3a7aSWarner LoshIt calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an 67088e3e3a7aSWarner Loshallocator based on the standard C <code>realloc</code> function 67098e3e3a7aSWarner Loshand then sets a panic function (see <a href="#4.6">§4.6</a>) that prints 67108e3e3a7aSWarner Loshan error message to the standard error output in case of fatal 67118e3e3a7aSWarner Losherrors. 67128e3e3a7aSWarner Losh 67138e3e3a7aSWarner Losh 67148e3e3a7aSWarner Losh<p> 67158e3e3a7aSWarner LoshReturns the new state, 67168e3e3a7aSWarner Loshor <code>NULL</code> if there is a memory allocation error. 67178e3e3a7aSWarner Losh 67188e3e3a7aSWarner Losh 67198e3e3a7aSWarner Losh 67208e3e3a7aSWarner Losh 67218e3e3a7aSWarner Losh 67228e3e3a7aSWarner Losh<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> 67238e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 67248e3e3a7aSWarner Losh<pre>void luaL_openlibs (lua_State *L);</pre> 67258e3e3a7aSWarner Losh 67268e3e3a7aSWarner Losh<p> 67278e3e3a7aSWarner LoshOpens all standard Lua libraries into the given state. 67288e3e3a7aSWarner Losh 67298e3e3a7aSWarner Losh 67308e3e3a7aSWarner Losh 67318e3e3a7aSWarner Losh 67328e3e3a7aSWarner Losh 67338e3e3a7aSWarner Losh<hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p> 67348e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 67358e3e3a7aSWarner Losh<pre>T luaL_opt (L, func, arg, dflt);</pre> 67368e3e3a7aSWarner Losh 67378e3e3a7aSWarner Losh<p> 67388e3e3a7aSWarner LoshThis macro is defined as follows: 67398e3e3a7aSWarner Losh 67408e3e3a7aSWarner Losh<pre> 67418e3e3a7aSWarner Losh (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg))) 67428e3e3a7aSWarner Losh</pre><p> 67438e3e3a7aSWarner LoshIn words, if the argument <code>arg</code> is nil or absent, 67448e3e3a7aSWarner Loshthe macro results in the default <code>dflt</code>. 67458e3e3a7aSWarner LoshOtherwise, it results in the result of calling <code>func</code> 67468e3e3a7aSWarner Loshwith the state <code>L</code> and the argument index <code>arg</code> as 6747*e112e9d2SKyle Evansarguments. 67488e3e3a7aSWarner LoshNote that it evaluates the expression <code>dflt</code> only if needed. 67498e3e3a7aSWarner Losh 67508e3e3a7aSWarner Losh 67518e3e3a7aSWarner Losh 67528e3e3a7aSWarner Losh 67538e3e3a7aSWarner Losh 67548e3e3a7aSWarner Losh<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> 67558e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 67568e3e3a7aSWarner Losh<pre>lua_Integer luaL_optinteger (lua_State *L, 67578e3e3a7aSWarner Losh int arg, 67588e3e3a7aSWarner Losh lua_Integer d);</pre> 67598e3e3a7aSWarner Losh 67608e3e3a7aSWarner Losh<p> 67618e3e3a7aSWarner LoshIf the function argument <code>arg</code> is an integer 67628e3e3a7aSWarner Losh(or convertible to an integer), 67638e3e3a7aSWarner Loshreturns this integer. 67648e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>, 67658e3e3a7aSWarner Loshreturns <code>d</code>. 67668e3e3a7aSWarner LoshOtherwise, raises an error. 67678e3e3a7aSWarner Losh 67688e3e3a7aSWarner Losh 67698e3e3a7aSWarner Losh 67708e3e3a7aSWarner Losh 67718e3e3a7aSWarner Losh 67728e3e3a7aSWarner Losh<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> 67738e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 67748e3e3a7aSWarner Losh<pre>const char *luaL_optlstring (lua_State *L, 67758e3e3a7aSWarner Losh int arg, 67768e3e3a7aSWarner Losh const char *d, 67778e3e3a7aSWarner Losh size_t *l);</pre> 67788e3e3a7aSWarner Losh 67798e3e3a7aSWarner Losh<p> 67808e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a string, 67818e3e3a7aSWarner Loshreturns this string. 67828e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>, 67838e3e3a7aSWarner Loshreturns <code>d</code>. 67848e3e3a7aSWarner LoshOtherwise, raises an error. 67858e3e3a7aSWarner Losh 67868e3e3a7aSWarner Losh 67878e3e3a7aSWarner Losh<p> 67888e3e3a7aSWarner LoshIf <code>l</code> is not <code>NULL</code>, 67898e3e3a7aSWarner Loshfills the position <code>*l</code> with the result's length. 67908e3e3a7aSWarner LoshIf the result is <code>NULL</code> 67918e3e3a7aSWarner Losh(only possible when returning <code>d</code> and <code>d == NULL</code>), 67928e3e3a7aSWarner Loshits length is considered zero. 67938e3e3a7aSWarner Losh 67948e3e3a7aSWarner Losh 67958e3e3a7aSWarner Losh<p> 67968e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 67978e3e3a7aSWarner Loshso all conversions and caveats of that function apply here. 67988e3e3a7aSWarner Losh 67998e3e3a7aSWarner Losh 68008e3e3a7aSWarner Losh 68018e3e3a7aSWarner Losh 68028e3e3a7aSWarner Losh 68038e3e3a7aSWarner Losh<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> 68048e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 68058e3e3a7aSWarner Losh<pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre> 68068e3e3a7aSWarner Losh 68078e3e3a7aSWarner Losh<p> 68088e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a number, 68098e3e3a7aSWarner Loshreturns this number. 68108e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>, 68118e3e3a7aSWarner Loshreturns <code>d</code>. 68128e3e3a7aSWarner LoshOtherwise, raises an error. 68138e3e3a7aSWarner Losh 68148e3e3a7aSWarner Losh 68158e3e3a7aSWarner Losh 68168e3e3a7aSWarner Losh 68178e3e3a7aSWarner Losh 68188e3e3a7aSWarner Losh<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> 68198e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 68208e3e3a7aSWarner Losh<pre>const char *luaL_optstring (lua_State *L, 68218e3e3a7aSWarner Losh int arg, 68228e3e3a7aSWarner Losh const char *d);</pre> 68238e3e3a7aSWarner Losh 68248e3e3a7aSWarner Losh<p> 68258e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a string, 68268e3e3a7aSWarner Loshreturns this string. 68278e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>, 68288e3e3a7aSWarner Loshreturns <code>d</code>. 68298e3e3a7aSWarner LoshOtherwise, raises an error. 68308e3e3a7aSWarner Losh 68318e3e3a7aSWarner Losh 68328e3e3a7aSWarner Losh 68338e3e3a7aSWarner Losh 68348e3e3a7aSWarner Losh 68358e3e3a7aSWarner Losh<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> 68368e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 68378e3e3a7aSWarner Losh<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> 68388e3e3a7aSWarner Losh 68398e3e3a7aSWarner Losh<p> 68408e3e3a7aSWarner LoshEquivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a> 68418e3e3a7aSWarner Loshwith the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>. 68428e3e3a7aSWarner Losh 68438e3e3a7aSWarner Losh 68448e3e3a7aSWarner Losh 68458e3e3a7aSWarner Losh 68468e3e3a7aSWarner Losh 68478e3e3a7aSWarner Losh<hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p> 68488e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 68498e3e3a7aSWarner Losh<pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre> 68508e3e3a7aSWarner Losh 68518e3e3a7aSWarner Losh<p> 68528e3e3a7aSWarner LoshReturns an address to a space of size <code>sz</code> 68538e3e3a7aSWarner Loshwhere you can copy a string to be added to buffer <code>B</code> 68548e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 68558e3e3a7aSWarner LoshAfter copying the string into this space you must call 68568e3e3a7aSWarner Losh<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add 68578e3e3a7aSWarner Loshit to the buffer. 68588e3e3a7aSWarner Losh 68598e3e3a7aSWarner Losh 68608e3e3a7aSWarner Losh 68618e3e3a7aSWarner Losh 68628e3e3a7aSWarner Losh 68638e3e3a7aSWarner Losh<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> 68648e3e3a7aSWarner Losh<span class="apii">[-?, +1, <em>m</em>]</span> 68658e3e3a7aSWarner Losh<pre>void luaL_pushresult (luaL_Buffer *B);</pre> 68668e3e3a7aSWarner Losh 68678e3e3a7aSWarner Losh<p> 68688e3e3a7aSWarner LoshFinishes the use of buffer <code>B</code> leaving the final string on 68698e3e3a7aSWarner Loshthe top of the stack. 68708e3e3a7aSWarner Losh 68718e3e3a7aSWarner Losh 68728e3e3a7aSWarner Losh 68738e3e3a7aSWarner Losh 68748e3e3a7aSWarner Losh 68758e3e3a7aSWarner Losh<hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p> 68768e3e3a7aSWarner Losh<span class="apii">[-?, +1, <em>m</em>]</span> 68778e3e3a7aSWarner Losh<pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre> 68788e3e3a7aSWarner Losh 68798e3e3a7aSWarner Losh<p> 68808e3e3a7aSWarner LoshEquivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>. 68818e3e3a7aSWarner Losh 68828e3e3a7aSWarner Losh 68838e3e3a7aSWarner Losh 68848e3e3a7aSWarner Losh 68858e3e3a7aSWarner Losh 68868e3e3a7aSWarner Losh<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> 68878e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span> 68888e3e3a7aSWarner Losh<pre>int luaL_ref (lua_State *L, int t);</pre> 68898e3e3a7aSWarner Losh 68908e3e3a7aSWarner Losh<p> 68918e3e3a7aSWarner LoshCreates and returns a <em>reference</em>, 68928e3e3a7aSWarner Loshin the table at index <code>t</code>, 68938e3e3a7aSWarner Loshfor the object at the top of the stack (and pops the object). 68948e3e3a7aSWarner Losh 68958e3e3a7aSWarner Losh 68968e3e3a7aSWarner Losh<p> 68978e3e3a7aSWarner LoshA reference is a unique integer key. 68988e3e3a7aSWarner LoshAs long as you do not manually add integer keys into table <code>t</code>, 68998e3e3a7aSWarner Losh<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. 69008e3e3a7aSWarner LoshYou can retrieve an object referred by reference <code>r</code> 69018e3e3a7aSWarner Loshby calling <code>lua_rawgeti(L, t, r)</code>. 69028e3e3a7aSWarner LoshFunction <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object. 69038e3e3a7aSWarner Losh 69048e3e3a7aSWarner Losh 69058e3e3a7aSWarner Losh<p> 69068e3e3a7aSWarner LoshIf the object at the top of the stack is <b>nil</b>, 69078e3e3a7aSWarner Losh<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>. 69088e3e3a7aSWarner LoshThe constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different 69098e3e3a7aSWarner Loshfrom any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. 69108e3e3a7aSWarner Losh 69118e3e3a7aSWarner Losh 69128e3e3a7aSWarner Losh 69138e3e3a7aSWarner Losh 69148e3e3a7aSWarner Losh 69158e3e3a7aSWarner Losh<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> 69168e3e3a7aSWarner Losh<pre>typedef struct luaL_Reg { 69178e3e3a7aSWarner Losh const char *name; 69188e3e3a7aSWarner Losh lua_CFunction func; 69198e3e3a7aSWarner Losh} luaL_Reg;</pre> 69208e3e3a7aSWarner Losh 69218e3e3a7aSWarner Losh<p> 69228e3e3a7aSWarner LoshType for arrays of functions to be registered by 69238e3e3a7aSWarner Losh<a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>. 69248e3e3a7aSWarner Losh<code>name</code> is the function name and <code>func</code> is a pointer to 69258e3e3a7aSWarner Loshthe function. 69268e3e3a7aSWarner LoshAny array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry 69278e3e3a7aSWarner Loshin which both <code>name</code> and <code>func</code> are <code>NULL</code>. 69288e3e3a7aSWarner Losh 69298e3e3a7aSWarner Losh 69308e3e3a7aSWarner Losh 69318e3e3a7aSWarner Losh 69328e3e3a7aSWarner Losh 69338e3e3a7aSWarner Losh<hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p> 69348e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 69358e3e3a7aSWarner Losh<pre>void luaL_requiref (lua_State *L, const char *modname, 69368e3e3a7aSWarner Losh lua_CFunction openf, int glb);</pre> 69378e3e3a7aSWarner Losh 69388e3e3a7aSWarner Losh<p> 69398e3e3a7aSWarner LoshIf <code>modname</code> is not already present in <a href="#pdf-package.loaded"><code>package.loaded</code></a>, 69408e3e3a7aSWarner Loshcalls function <code>openf</code> with string <code>modname</code> as an argument 69418e3e3a7aSWarner Loshand sets the call result in <code>package.loaded[modname]</code>, 69428e3e3a7aSWarner Loshas if that function has been called through <a href="#pdf-require"><code>require</code></a>. 69438e3e3a7aSWarner Losh 69448e3e3a7aSWarner Losh 69458e3e3a7aSWarner Losh<p> 69468e3e3a7aSWarner LoshIf <code>glb</code> is true, 69478e3e3a7aSWarner Loshalso stores the module into global <code>modname</code>. 69488e3e3a7aSWarner Losh 69498e3e3a7aSWarner Losh 69508e3e3a7aSWarner Losh<p> 69518e3e3a7aSWarner LoshLeaves a copy of the module on the stack. 69528e3e3a7aSWarner Losh 69538e3e3a7aSWarner Losh 69548e3e3a7aSWarner Losh 69558e3e3a7aSWarner Losh 69568e3e3a7aSWarner Losh 69578e3e3a7aSWarner Losh<hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p> 69588e3e3a7aSWarner Losh<span class="apii">[-nup, +0, <em>m</em>]</span> 69598e3e3a7aSWarner Losh<pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre> 69608e3e3a7aSWarner Losh 69618e3e3a7aSWarner Losh<p> 69628e3e3a7aSWarner LoshRegisters all functions in the array <code>l</code> 69638e3e3a7aSWarner Losh(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack 69648e3e3a7aSWarner Losh(below optional upvalues, see next). 69658e3e3a7aSWarner Losh 69668e3e3a7aSWarner Losh 69678e3e3a7aSWarner Losh<p> 69688e3e3a7aSWarner LoshWhen <code>nup</code> is not zero, 69698e3e3a7aSWarner Loshall functions are created sharing <code>nup</code> upvalues, 69708e3e3a7aSWarner Loshwhich must be previously pushed on the stack 69718e3e3a7aSWarner Loshon top of the library table. 69728e3e3a7aSWarner LoshThese values are popped from the stack after the registration. 69738e3e3a7aSWarner Losh 69748e3e3a7aSWarner Losh 69758e3e3a7aSWarner Losh 69768e3e3a7aSWarner Losh 69778e3e3a7aSWarner Losh 69788e3e3a7aSWarner Losh<hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p> 69798e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 69808e3e3a7aSWarner Losh<pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre> 69818e3e3a7aSWarner Losh 69828e3e3a7aSWarner Losh<p> 69838e3e3a7aSWarner LoshSets the metatable of the object at the top of the stack 69848e3e3a7aSWarner Loshas the metatable associated with name <code>tname</code> 69858e3e3a7aSWarner Loshin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 69868e3e3a7aSWarner Losh 69878e3e3a7aSWarner Losh 69888e3e3a7aSWarner Losh 69898e3e3a7aSWarner Losh 69908e3e3a7aSWarner Losh 69918e3e3a7aSWarner Losh<hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3> 69928e3e3a7aSWarner Losh<pre>typedef struct luaL_Stream { 69938e3e3a7aSWarner Losh FILE *f; 69948e3e3a7aSWarner Losh lua_CFunction closef; 69958e3e3a7aSWarner Losh} luaL_Stream;</pre> 69968e3e3a7aSWarner Losh 69978e3e3a7aSWarner Losh<p> 69988e3e3a7aSWarner LoshThe standard representation for file handles, 69998e3e3a7aSWarner Loshwhich is used by the standard I/O library. 70008e3e3a7aSWarner Losh 70018e3e3a7aSWarner Losh 70028e3e3a7aSWarner Losh<p> 70038e3e3a7aSWarner LoshA file handle is implemented as a full userdata, 70048e3e3a7aSWarner Loshwith a metatable called <code>LUA_FILEHANDLE</code> 70058e3e3a7aSWarner Losh(where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name). 70068e3e3a7aSWarner LoshThe metatable is created by the I/O library 70078e3e3a7aSWarner Losh(see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 70088e3e3a7aSWarner Losh 70098e3e3a7aSWarner Losh 70108e3e3a7aSWarner Losh<p> 70118e3e3a7aSWarner LoshThis userdata must start with the structure <code>luaL_Stream</code>; 70128e3e3a7aSWarner Loshit can contain other data after this initial structure. 70138e3e3a7aSWarner LoshField <code>f</code> points to the corresponding C stream 70148e3e3a7aSWarner Losh(or it can be <code>NULL</code> to indicate an incompletely created handle). 70158e3e3a7aSWarner LoshField <code>closef</code> points to a Lua function 70168e3e3a7aSWarner Loshthat will be called to close the stream 70178e3e3a7aSWarner Loshwhen the handle is closed or collected; 70188e3e3a7aSWarner Loshthis function receives the file handle as its sole argument and 70198e3e3a7aSWarner Loshmust return either <b>true</b> (in case of success) 70208e3e3a7aSWarner Loshor <b>nil</b> plus an error message (in case of error). 70218e3e3a7aSWarner LoshOnce Lua calls this field, 70228e3e3a7aSWarner Loshit changes the field value to <code>NULL</code> 70238e3e3a7aSWarner Loshto signal that the handle is closed. 70248e3e3a7aSWarner Losh 70258e3e3a7aSWarner Losh 70268e3e3a7aSWarner Losh 70278e3e3a7aSWarner Losh 70288e3e3a7aSWarner Losh 70298e3e3a7aSWarner Losh<hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p> 70308e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span> 70318e3e3a7aSWarner Losh<pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre> 70328e3e3a7aSWarner Losh 70338e3e3a7aSWarner Losh<p> 70348e3e3a7aSWarner LoshThis function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>, 70358e3e3a7aSWarner Loshexcept that, when the test fails, 70368e3e3a7aSWarner Loshit returns <code>NULL</code> instead of raising an error. 70378e3e3a7aSWarner Losh 70388e3e3a7aSWarner Losh 70398e3e3a7aSWarner Losh 70408e3e3a7aSWarner Losh 70418e3e3a7aSWarner Losh 70428e3e3a7aSWarner Losh<hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p> 70438e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 70448e3e3a7aSWarner Losh<pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre> 70458e3e3a7aSWarner Losh 70468e3e3a7aSWarner Losh<p> 70478e3e3a7aSWarner LoshConverts any Lua value at the given index to a C string 70488e3e3a7aSWarner Loshin a reasonable format. 70498e3e3a7aSWarner LoshThe resulting string is pushed onto the stack and also 70508e3e3a7aSWarner Loshreturned by the function. 70518e3e3a7aSWarner LoshIf <code>len</code> is not <code>NULL</code>, 70528e3e3a7aSWarner Loshthe function also sets <code>*len</code> with the string length. 70538e3e3a7aSWarner Losh 70548e3e3a7aSWarner Losh 70558e3e3a7aSWarner Losh<p> 70568e3e3a7aSWarner LoshIf the value has a metatable with a <code>__tostring</code> field, 70578e3e3a7aSWarner Loshthen <code>luaL_tolstring</code> calls the corresponding metamethod 70588e3e3a7aSWarner Loshwith the value as argument, 70598e3e3a7aSWarner Loshand uses the result of the call as its result. 70608e3e3a7aSWarner Losh 70618e3e3a7aSWarner Losh 70628e3e3a7aSWarner Losh 70638e3e3a7aSWarner Losh 70648e3e3a7aSWarner Losh 70658e3e3a7aSWarner Losh<hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p> 70668e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 70678e3e3a7aSWarner Losh<pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, 70688e3e3a7aSWarner Losh int level);</pre> 70698e3e3a7aSWarner Losh 70708e3e3a7aSWarner Losh<p> 70718e3e3a7aSWarner LoshCreates and pushes a traceback of the stack <code>L1</code>. 70728e3e3a7aSWarner LoshIf <code>msg</code> is not <code>NULL</code> it is appended 70738e3e3a7aSWarner Loshat the beginning of the traceback. 70748e3e3a7aSWarner LoshThe <code>level</code> parameter tells at which level 70758e3e3a7aSWarner Loshto start the traceback. 70768e3e3a7aSWarner Losh 70778e3e3a7aSWarner Losh 70788e3e3a7aSWarner Losh 70798e3e3a7aSWarner Losh 70808e3e3a7aSWarner Losh 70818e3e3a7aSWarner Losh<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> 70828e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 70838e3e3a7aSWarner Losh<pre>const char *luaL_typename (lua_State *L, int index);</pre> 70848e3e3a7aSWarner Losh 70858e3e3a7aSWarner Losh<p> 70868e3e3a7aSWarner LoshReturns the name of the type of the value at the given index. 70878e3e3a7aSWarner Losh 70888e3e3a7aSWarner Losh 70898e3e3a7aSWarner Losh 70908e3e3a7aSWarner Losh 70918e3e3a7aSWarner Losh 70928e3e3a7aSWarner Losh<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> 70938e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 70948e3e3a7aSWarner Losh<pre>void luaL_unref (lua_State *L, int t, int ref);</pre> 70958e3e3a7aSWarner Losh 70968e3e3a7aSWarner Losh<p> 70978e3e3a7aSWarner LoshReleases reference <code>ref</code> from the table at index <code>t</code> 70988e3e3a7aSWarner Losh(see <a href="#luaL_ref"><code>luaL_ref</code></a>). 70998e3e3a7aSWarner LoshThe entry is removed from the table, 71008e3e3a7aSWarner Loshso that the referred object can be collected. 71018e3e3a7aSWarner LoshThe reference <code>ref</code> is also freed to be used again. 71028e3e3a7aSWarner Losh 71038e3e3a7aSWarner Losh 71048e3e3a7aSWarner Losh<p> 71058e3e3a7aSWarner LoshIf <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>, 71068e3e3a7aSWarner Losh<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. 71078e3e3a7aSWarner Losh 71088e3e3a7aSWarner Losh 71098e3e3a7aSWarner Losh 71108e3e3a7aSWarner Losh 71118e3e3a7aSWarner Losh 71128e3e3a7aSWarner Losh<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> 71138e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 71148e3e3a7aSWarner Losh<pre>void luaL_where (lua_State *L, int lvl);</pre> 71158e3e3a7aSWarner Losh 71168e3e3a7aSWarner Losh<p> 71178e3e3a7aSWarner LoshPushes onto the stack a string identifying the current position 71188e3e3a7aSWarner Loshof the control at level <code>lvl</code> in the call stack. 71198e3e3a7aSWarner LoshTypically this string has the following format: 71208e3e3a7aSWarner Losh 71218e3e3a7aSWarner Losh<pre> 71228e3e3a7aSWarner Losh <em>chunkname</em>:<em>currentline</em>: 71238e3e3a7aSWarner Losh</pre><p> 71248e3e3a7aSWarner LoshLevel 0 is the running function, 71258e3e3a7aSWarner Loshlevel 1 is the function that called the running function, 71268e3e3a7aSWarner Loshetc. 71278e3e3a7aSWarner Losh 71288e3e3a7aSWarner Losh 71298e3e3a7aSWarner Losh<p> 71308e3e3a7aSWarner LoshThis function is used to build a prefix for error messages. 71318e3e3a7aSWarner Losh 71328e3e3a7aSWarner Losh 71338e3e3a7aSWarner Losh 71348e3e3a7aSWarner Losh 71358e3e3a7aSWarner Losh 71368e3e3a7aSWarner Losh 71378e3e3a7aSWarner Losh 71388e3e3a7aSWarner Losh<h1>6 – <a name="6">Standard Libraries</a></h1> 71398e3e3a7aSWarner Losh 71408e3e3a7aSWarner Losh<p> 71418e3e3a7aSWarner LoshThe standard Lua libraries provide useful functions 71428e3e3a7aSWarner Loshthat are implemented directly through the C API. 71438e3e3a7aSWarner LoshSome of these functions provide essential services to the language 71448e3e3a7aSWarner Losh(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); 71458e3e3a7aSWarner Loshothers provide access to "outside" services (e.g., I/O); 71468e3e3a7aSWarner Loshand others could be implemented in Lua itself, 71478e3e3a7aSWarner Loshbut are quite useful or have critical performance requirements that 71488e3e3a7aSWarner Loshdeserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). 71498e3e3a7aSWarner Losh 71508e3e3a7aSWarner Losh 71518e3e3a7aSWarner Losh<p> 71528e3e3a7aSWarner LoshAll libraries are implemented through the official C API 71538e3e3a7aSWarner Loshand are provided as separate C modules. 71548e3e3a7aSWarner LoshCurrently, Lua has the following standard libraries: 71558e3e3a7aSWarner Losh 71568e3e3a7aSWarner Losh<ul> 71578e3e3a7aSWarner Losh 71588e3e3a7aSWarner Losh<li>basic library (<a href="#6.1">§6.1</a>);</li> 71598e3e3a7aSWarner Losh 71608e3e3a7aSWarner Losh<li>coroutine library (<a href="#6.2">§6.2</a>);</li> 71618e3e3a7aSWarner Losh 71628e3e3a7aSWarner Losh<li>package library (<a href="#6.3">§6.3</a>);</li> 71638e3e3a7aSWarner Losh 71648e3e3a7aSWarner Losh<li>string manipulation (<a href="#6.4">§6.4</a>);</li> 71658e3e3a7aSWarner Losh 71668e3e3a7aSWarner Losh<li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li> 71678e3e3a7aSWarner Losh 71688e3e3a7aSWarner Losh<li>table manipulation (<a href="#6.6">§6.6</a>);</li> 71698e3e3a7aSWarner Losh 71708e3e3a7aSWarner Losh<li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li> 71718e3e3a7aSWarner Losh 71728e3e3a7aSWarner Losh<li>input and output (<a href="#6.8">§6.8</a>);</li> 71738e3e3a7aSWarner Losh 71748e3e3a7aSWarner Losh<li>operating system facilities (<a href="#6.9">§6.9</a>);</li> 71758e3e3a7aSWarner Losh 71768e3e3a7aSWarner Losh<li>debug facilities (<a href="#6.10">§6.10</a>).</li> 71778e3e3a7aSWarner Losh 71788e3e3a7aSWarner Losh</ul><p> 71798e3e3a7aSWarner LoshExcept for the basic and the package libraries, 71808e3e3a7aSWarner Losheach library provides all its functions as fields of a global table 71818e3e3a7aSWarner Loshor as methods of its objects. 71828e3e3a7aSWarner Losh 71838e3e3a7aSWarner Losh 71848e3e3a7aSWarner Losh<p> 71858e3e3a7aSWarner LoshTo have access to these libraries, 71868e3e3a7aSWarner Loshthe C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, 71878e3e3a7aSWarner Loshwhich opens all standard libraries. 71888e3e3a7aSWarner LoshAlternatively, 71898e3e3a7aSWarner Loshthe host program can open them individually by using 71908e3e3a7aSWarner Losh<a href="#luaL_requiref"><code>luaL_requiref</code></a> to call 71918e3e3a7aSWarner Losh<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), 71928e3e3a7aSWarner Losh<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), 71938e3e3a7aSWarner Losh<a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library), 71948e3e3a7aSWarner Losh<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), 71958e3e3a7aSWarner Losh<a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF8 library), 71968e3e3a7aSWarner Losh<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), 71978e3e3a7aSWarner Losh<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), 71988e3e3a7aSWarner Losh<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), 71998e3e3a7aSWarner Losh<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library), 72008e3e3a7aSWarner Loshand <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). 72018e3e3a7aSWarner LoshThese functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>. 72028e3e3a7aSWarner Losh 72038e3e3a7aSWarner Losh 72048e3e3a7aSWarner Losh 72058e3e3a7aSWarner Losh<h2>6.1 – <a name="6.1">Basic Functions</a></h2> 72068e3e3a7aSWarner Losh 72078e3e3a7aSWarner Losh<p> 72088e3e3a7aSWarner LoshThe basic library provides core functions to Lua. 72098e3e3a7aSWarner LoshIf you do not include this library in your application, 72108e3e3a7aSWarner Loshyou should check carefully whether you need to provide 72118e3e3a7aSWarner Loshimplementations for some of its facilities. 72128e3e3a7aSWarner Losh 72138e3e3a7aSWarner Losh 72148e3e3a7aSWarner Losh<p> 72158e3e3a7aSWarner Losh<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> 72168e3e3a7aSWarner Losh 72178e3e3a7aSWarner Losh 72188e3e3a7aSWarner Losh<p> 72198e3e3a7aSWarner LoshCalls <a href="#pdf-error"><code>error</code></a> if 72208e3e3a7aSWarner Loshthe value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); 72218e3e3a7aSWarner Loshotherwise, returns all its arguments. 72228e3e3a7aSWarner LoshIn case of error, 72238e3e3a7aSWarner Losh<code>message</code> is the error object; 72248e3e3a7aSWarner Loshwhen absent, it defaults to "<code>assertion failed!</code>" 72258e3e3a7aSWarner Losh 72268e3e3a7aSWarner Losh 72278e3e3a7aSWarner Losh 72288e3e3a7aSWarner Losh 72298e3e3a7aSWarner Losh<p> 72308e3e3a7aSWarner Losh<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3> 72318e3e3a7aSWarner Losh 72328e3e3a7aSWarner Losh 72338e3e3a7aSWarner Losh<p> 72348e3e3a7aSWarner LoshThis function is a generic interface to the garbage collector. 72358e3e3a7aSWarner LoshIt performs different functions according to its first argument, <code>opt</code>: 72368e3e3a7aSWarner Losh 72378e3e3a7aSWarner Losh<ul> 72388e3e3a7aSWarner Losh 72398e3e3a7aSWarner Losh<li><b>"<code>collect</code>": </b> 72408e3e3a7aSWarner Loshperforms a full garbage-collection cycle. 72418e3e3a7aSWarner LoshThis is the default option. 72428e3e3a7aSWarner Losh</li> 72438e3e3a7aSWarner Losh 72448e3e3a7aSWarner Losh<li><b>"<code>stop</code>": </b> 72458e3e3a7aSWarner Loshstops automatic execution of the garbage collector. 72468e3e3a7aSWarner LoshThe collector will run only when explicitly invoked, 72478e3e3a7aSWarner Loshuntil a call to restart it. 72488e3e3a7aSWarner Losh</li> 72498e3e3a7aSWarner Losh 72508e3e3a7aSWarner Losh<li><b>"<code>restart</code>": </b> 72518e3e3a7aSWarner Loshrestarts automatic execution of the garbage collector. 72528e3e3a7aSWarner Losh</li> 72538e3e3a7aSWarner Losh 72548e3e3a7aSWarner Losh<li><b>"<code>count</code>": </b> 72558e3e3a7aSWarner Loshreturns the total memory in use by Lua in Kbytes. 72568e3e3a7aSWarner LoshThe value has a fractional part, 72578e3e3a7aSWarner Loshso that it multiplied by 1024 72588e3e3a7aSWarner Loshgives the exact number of bytes in use by Lua 72598e3e3a7aSWarner Losh(except for overflows). 72608e3e3a7aSWarner Losh</li> 72618e3e3a7aSWarner Losh 72628e3e3a7aSWarner Losh<li><b>"<code>step</code>": </b> 72638e3e3a7aSWarner Loshperforms a garbage-collection step. 72648e3e3a7aSWarner LoshThe step "size" is controlled by <code>arg</code>. 72658e3e3a7aSWarner LoshWith a zero value, 72668e3e3a7aSWarner Loshthe collector will perform one basic (indivisible) step. 72678e3e3a7aSWarner LoshFor non-zero values, 72688e3e3a7aSWarner Loshthe collector will perform as if that amount of memory 72698e3e3a7aSWarner Losh(in KBytes) had been allocated by Lua. 72708e3e3a7aSWarner LoshReturns <b>true</b> if the step finished a collection cycle. 72718e3e3a7aSWarner Losh</li> 72728e3e3a7aSWarner Losh 72738e3e3a7aSWarner Losh<li><b>"<code>setpause</code>": </b> 72748e3e3a7aSWarner Loshsets <code>arg</code> as the new value for the <em>pause</em> of 72758e3e3a7aSWarner Loshthe collector (see <a href="#2.5">§2.5</a>). 72768e3e3a7aSWarner LoshReturns the previous value for <em>pause</em>. 72778e3e3a7aSWarner Losh</li> 72788e3e3a7aSWarner Losh 72798e3e3a7aSWarner Losh<li><b>"<code>setstepmul</code>": </b> 72808e3e3a7aSWarner Loshsets <code>arg</code> as the new value for the <em>step multiplier</em> of 72818e3e3a7aSWarner Loshthe collector (see <a href="#2.5">§2.5</a>). 72828e3e3a7aSWarner LoshReturns the previous value for <em>step</em>. 72838e3e3a7aSWarner Losh</li> 72848e3e3a7aSWarner Losh 72858e3e3a7aSWarner Losh<li><b>"<code>isrunning</code>": </b> 72868e3e3a7aSWarner Loshreturns a boolean that tells whether the collector is running 72878e3e3a7aSWarner Losh(i.e., not stopped). 72888e3e3a7aSWarner Losh</li> 72898e3e3a7aSWarner Losh 72908e3e3a7aSWarner Losh</ul> 72918e3e3a7aSWarner Losh 72928e3e3a7aSWarner Losh 72938e3e3a7aSWarner Losh 72948e3e3a7aSWarner Losh<p> 72958e3e3a7aSWarner Losh<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> 72968e3e3a7aSWarner LoshOpens the named file and executes its contents as a Lua chunk. 72978e3e3a7aSWarner LoshWhen called without arguments, 72988e3e3a7aSWarner Losh<code>dofile</code> executes the contents of the standard input (<code>stdin</code>). 72998e3e3a7aSWarner LoshReturns all values returned by the chunk. 73008e3e3a7aSWarner LoshIn case of errors, <code>dofile</code> propagates the error 73018e3e3a7aSWarner Loshto its caller (that is, <code>dofile</code> does not run in protected mode). 73028e3e3a7aSWarner Losh 73038e3e3a7aSWarner Losh 73048e3e3a7aSWarner Losh 73058e3e3a7aSWarner Losh 73068e3e3a7aSWarner Losh<p> 73078e3e3a7aSWarner Losh<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> 73088e3e3a7aSWarner LoshTerminates the last protected function called 73098e3e3a7aSWarner Loshand returns <code>message</code> as the error object. 73108e3e3a7aSWarner LoshFunction <code>error</code> never returns. 73118e3e3a7aSWarner Losh 73128e3e3a7aSWarner Losh 73138e3e3a7aSWarner Losh<p> 73148e3e3a7aSWarner LoshUsually, <code>error</code> adds some information about the error position 73158e3e3a7aSWarner Loshat the beginning of the message, if the message is a string. 73168e3e3a7aSWarner LoshThe <code>level</code> argument specifies how to get the error position. 73178e3e3a7aSWarner LoshWith level 1 (the default), the error position is where the 73188e3e3a7aSWarner Losh<code>error</code> function was called. 73198e3e3a7aSWarner LoshLevel 2 points the error to where the function 73208e3e3a7aSWarner Loshthat called <code>error</code> was called; and so on. 73218e3e3a7aSWarner LoshPassing a level 0 avoids the addition of error position information 73228e3e3a7aSWarner Loshto the message. 73238e3e3a7aSWarner Losh 73248e3e3a7aSWarner Losh 73258e3e3a7aSWarner Losh 73268e3e3a7aSWarner Losh 73278e3e3a7aSWarner Losh<p> 73288e3e3a7aSWarner Losh<hr><h3><a name="pdf-_G"><code>_G</code></a></h3> 73298e3e3a7aSWarner LoshA global variable (not a function) that 73308e3e3a7aSWarner Loshholds the global environment (see <a href="#2.2">§2.2</a>). 73318e3e3a7aSWarner LoshLua itself does not use this variable; 73328e3e3a7aSWarner Loshchanging its value does not affect any environment, 73338e3e3a7aSWarner Loshnor vice versa. 73348e3e3a7aSWarner Losh 73358e3e3a7aSWarner Losh 73368e3e3a7aSWarner Losh 73378e3e3a7aSWarner Losh 73388e3e3a7aSWarner Losh<p> 73398e3e3a7aSWarner Losh<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> 73408e3e3a7aSWarner Losh 73418e3e3a7aSWarner Losh 73428e3e3a7aSWarner Losh<p> 73438e3e3a7aSWarner LoshIf <code>object</code> does not have a metatable, returns <b>nil</b>. 73448e3e3a7aSWarner LoshOtherwise, 73458e3e3a7aSWarner Loshif the object's metatable has a <code>__metatable</code> field, 73468e3e3a7aSWarner Loshreturns the associated value. 73478e3e3a7aSWarner LoshOtherwise, returns the metatable of the given object. 73488e3e3a7aSWarner Losh 73498e3e3a7aSWarner Losh 73508e3e3a7aSWarner Losh 73518e3e3a7aSWarner Losh 73528e3e3a7aSWarner Losh<p> 73538e3e3a7aSWarner Losh<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> 73548e3e3a7aSWarner Losh 73558e3e3a7aSWarner Losh 73568e3e3a7aSWarner Losh<p> 73578e3e3a7aSWarner LoshReturns three values (an iterator function, the table <code>t</code>, and 0) 73588e3e3a7aSWarner Loshso that the construction 73598e3e3a7aSWarner Losh 73608e3e3a7aSWarner Losh<pre> 73618e3e3a7aSWarner Losh for i,v in ipairs(t) do <em>body</em> end 73628e3e3a7aSWarner Losh</pre><p> 73638e3e3a7aSWarner Loshwill iterate over the key–value pairs 73648e3e3a7aSWarner Losh(<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., 73658e3e3a7aSWarner Loshup to the first nil value. 73668e3e3a7aSWarner Losh 73678e3e3a7aSWarner Losh 73688e3e3a7aSWarner Losh 73698e3e3a7aSWarner Losh 73708e3e3a7aSWarner Losh<p> 73718e3e3a7aSWarner Losh<hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3> 73728e3e3a7aSWarner Losh 73738e3e3a7aSWarner Losh 73748e3e3a7aSWarner Losh<p> 73758e3e3a7aSWarner LoshLoads a chunk. 73768e3e3a7aSWarner Losh 73778e3e3a7aSWarner Losh 73788e3e3a7aSWarner Losh<p> 73798e3e3a7aSWarner LoshIf <code>chunk</code> is a string, the chunk is this string. 73808e3e3a7aSWarner LoshIf <code>chunk</code> is a function, 73818e3e3a7aSWarner Losh<code>load</code> calls it repeatedly to get the chunk pieces. 73828e3e3a7aSWarner LoshEach call to <code>chunk</code> must return a string that concatenates 73838e3e3a7aSWarner Loshwith previous results. 73848e3e3a7aSWarner LoshA return of an empty string, <b>nil</b>, or no value signals the end of the chunk. 73858e3e3a7aSWarner Losh 73868e3e3a7aSWarner Losh 73878e3e3a7aSWarner Losh<p> 73888e3e3a7aSWarner LoshIf there are no syntactic errors, 73898e3e3a7aSWarner Loshreturns the compiled chunk as a function; 73908e3e3a7aSWarner Loshotherwise, returns <b>nil</b> plus the error message. 73918e3e3a7aSWarner Losh 73928e3e3a7aSWarner Losh 73938e3e3a7aSWarner Losh<p> 73948e3e3a7aSWarner LoshIf the resulting function has upvalues, 73958e3e3a7aSWarner Loshthe first upvalue is set to the value of <code>env</code>, 73968e3e3a7aSWarner Loshif that parameter is given, 73978e3e3a7aSWarner Loshor to the value of the global environment. 73988e3e3a7aSWarner LoshOther upvalues are initialized with <b>nil</b>. 73998e3e3a7aSWarner Losh(When you load a main chunk, 74008e3e3a7aSWarner Loshthe resulting function will always have exactly one upvalue, 74018e3e3a7aSWarner Loshthe <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 74028e3e3a7aSWarner LoshHowever, 74038e3e3a7aSWarner Loshwhen you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>), 74048e3e3a7aSWarner Loshthe resulting function can have an arbitrary number of upvalues.) 74058e3e3a7aSWarner LoshAll upvalues are fresh, that is, 74068e3e3a7aSWarner Loshthey are not shared with any other function. 74078e3e3a7aSWarner Losh 74088e3e3a7aSWarner Losh 74098e3e3a7aSWarner Losh<p> 74108e3e3a7aSWarner Losh<code>chunkname</code> is used as the name of the chunk for error messages 74118e3e3a7aSWarner Loshand debug information (see <a href="#4.9">§4.9</a>). 74128e3e3a7aSWarner LoshWhen absent, 74138e3e3a7aSWarner Loshit defaults to <code>chunk</code>, if <code>chunk</code> is a string, 74148e3e3a7aSWarner Loshor to "<code>=(load)</code>" otherwise. 74158e3e3a7aSWarner Losh 74168e3e3a7aSWarner Losh 74178e3e3a7aSWarner Losh<p> 74188e3e3a7aSWarner LoshThe string <code>mode</code> controls whether the chunk can be text or binary 74198e3e3a7aSWarner Losh(that is, a precompiled chunk). 74208e3e3a7aSWarner LoshIt may be the string "<code>b</code>" (only binary chunks), 74218e3e3a7aSWarner Losh"<code>t</code>" (only text chunks), 74228e3e3a7aSWarner Loshor "<code>bt</code>" (both binary and text). 74238e3e3a7aSWarner LoshThe default is "<code>bt</code>". 74248e3e3a7aSWarner Losh 74258e3e3a7aSWarner Losh 74268e3e3a7aSWarner Losh<p> 74278e3e3a7aSWarner LoshLua does not check the consistency of binary chunks. 74288e3e3a7aSWarner LoshMaliciously crafted binary chunks can crash 74298e3e3a7aSWarner Loshthe interpreter. 74308e3e3a7aSWarner Losh 74318e3e3a7aSWarner Losh 74328e3e3a7aSWarner Losh 74338e3e3a7aSWarner Losh 74348e3e3a7aSWarner Losh<p> 74358e3e3a7aSWarner Losh<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3> 74368e3e3a7aSWarner Losh 74378e3e3a7aSWarner Losh 74388e3e3a7aSWarner Losh<p> 74398e3e3a7aSWarner LoshSimilar to <a href="#pdf-load"><code>load</code></a>, 74408e3e3a7aSWarner Loshbut gets the chunk from file <code>filename</code> 74418e3e3a7aSWarner Loshor from the standard input, 74428e3e3a7aSWarner Loshif no file name is given. 74438e3e3a7aSWarner Losh 74448e3e3a7aSWarner Losh 74458e3e3a7aSWarner Losh 74468e3e3a7aSWarner Losh 74478e3e3a7aSWarner Losh<p> 74488e3e3a7aSWarner Losh<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> 74498e3e3a7aSWarner Losh 74508e3e3a7aSWarner Losh 74518e3e3a7aSWarner Losh<p> 74528e3e3a7aSWarner LoshAllows a program to traverse all fields of a table. 74538e3e3a7aSWarner LoshIts first argument is a table and its second argument 74548e3e3a7aSWarner Loshis an index in this table. 74558e3e3a7aSWarner Losh<code>next</code> returns the next index of the table 74568e3e3a7aSWarner Loshand its associated value. 74578e3e3a7aSWarner LoshWhen called with <b>nil</b> as its second argument, 74588e3e3a7aSWarner Losh<code>next</code> returns an initial index 74598e3e3a7aSWarner Loshand its associated value. 74608e3e3a7aSWarner LoshWhen called with the last index, 74618e3e3a7aSWarner Loshor with <b>nil</b> in an empty table, 74628e3e3a7aSWarner Losh<code>next</code> returns <b>nil</b>. 74638e3e3a7aSWarner LoshIf the second argument is absent, then it is interpreted as <b>nil</b>. 74648e3e3a7aSWarner LoshIn particular, 74658e3e3a7aSWarner Loshyou can use <code>next(t)</code> to check whether a table is empty. 74668e3e3a7aSWarner Losh 74678e3e3a7aSWarner Losh 74688e3e3a7aSWarner Losh<p> 74698e3e3a7aSWarner LoshThe order in which the indices are enumerated is not specified, 74708e3e3a7aSWarner Losh<em>even for numeric indices</em>. 74718e3e3a7aSWarner Losh(To traverse a table in numerical order, 74728e3e3a7aSWarner Loshuse a numerical <b>for</b>.) 74738e3e3a7aSWarner Losh 74748e3e3a7aSWarner Losh 74758e3e3a7aSWarner Losh<p> 74768e3e3a7aSWarner LoshThe behavior of <code>next</code> is undefined if, 74778e3e3a7aSWarner Loshduring the traversal, 74788e3e3a7aSWarner Loshyou assign any value to a non-existent field in the table. 74798e3e3a7aSWarner LoshYou may however modify existing fields. 74808e3e3a7aSWarner LoshIn particular, you may clear existing fields. 74818e3e3a7aSWarner Losh 74828e3e3a7aSWarner Losh 74838e3e3a7aSWarner Losh 74848e3e3a7aSWarner Losh 74858e3e3a7aSWarner Losh<p> 74868e3e3a7aSWarner Losh<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> 74878e3e3a7aSWarner Losh 74888e3e3a7aSWarner Losh 74898e3e3a7aSWarner Losh<p> 74908e3e3a7aSWarner LoshIf <code>t</code> has a metamethod <code>__pairs</code>, 74918e3e3a7aSWarner Loshcalls it with <code>t</code> as argument and returns the first three 74928e3e3a7aSWarner Loshresults from the call. 74938e3e3a7aSWarner Losh 74948e3e3a7aSWarner Losh 74958e3e3a7aSWarner Losh<p> 74968e3e3a7aSWarner LoshOtherwise, 74978e3e3a7aSWarner Loshreturns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, 74988e3e3a7aSWarner Loshso that the construction 74998e3e3a7aSWarner Losh 75008e3e3a7aSWarner Losh<pre> 75018e3e3a7aSWarner Losh for k,v in pairs(t) do <em>body</em> end 75028e3e3a7aSWarner Losh</pre><p> 75038e3e3a7aSWarner Loshwill iterate over all key–value pairs of table <code>t</code>. 75048e3e3a7aSWarner Losh 75058e3e3a7aSWarner Losh 75068e3e3a7aSWarner Losh<p> 75078e3e3a7aSWarner LoshSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 75088e3e3a7aSWarner Loshthe table during its traversal. 75098e3e3a7aSWarner Losh 75108e3e3a7aSWarner Losh 75118e3e3a7aSWarner Losh 75128e3e3a7aSWarner Losh 75138e3e3a7aSWarner Losh<p> 75148e3e3a7aSWarner Losh<hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3> 75158e3e3a7aSWarner Losh 75168e3e3a7aSWarner Losh 75178e3e3a7aSWarner Losh<p> 75188e3e3a7aSWarner LoshCalls function <code>f</code> with 75198e3e3a7aSWarner Loshthe given arguments in <em>protected mode</em>. 75208e3e3a7aSWarner LoshThis means that any error inside <code>f</code> is not propagated; 75218e3e3a7aSWarner Loshinstead, <code>pcall</code> catches the error 75228e3e3a7aSWarner Loshand returns a status code. 75238e3e3a7aSWarner LoshIts first result is the status code (a boolean), 75248e3e3a7aSWarner Loshwhich is true if the call succeeds without errors. 75258e3e3a7aSWarner LoshIn such case, <code>pcall</code> also returns all results from the call, 75268e3e3a7aSWarner Loshafter this first result. 75278e3e3a7aSWarner LoshIn case of any error, <code>pcall</code> returns <b>false</b> plus the error message. 75288e3e3a7aSWarner Losh 75298e3e3a7aSWarner Losh 75308e3e3a7aSWarner Losh 75318e3e3a7aSWarner Losh 75328e3e3a7aSWarner Losh<p> 75338e3e3a7aSWarner Losh<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> 75348e3e3a7aSWarner LoshReceives any number of arguments 75358e3e3a7aSWarner Loshand prints their values to <code>stdout</code>, 75368e3e3a7aSWarner Loshusing the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string. 75378e3e3a7aSWarner Losh<code>print</code> is not intended for formatted output, 75388e3e3a7aSWarner Loshbut only as a quick way to show a value, 75398e3e3a7aSWarner Loshfor instance for debugging. 75408e3e3a7aSWarner LoshFor complete control over the output, 75418e3e3a7aSWarner Loshuse <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. 75428e3e3a7aSWarner Losh 75438e3e3a7aSWarner Losh 75448e3e3a7aSWarner Losh 75458e3e3a7aSWarner Losh 75468e3e3a7aSWarner Losh<p> 75478e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> 75488e3e3a7aSWarner LoshChecks whether <code>v1</code> is equal to <code>v2</code>, 75498e3e3a7aSWarner Loshwithout invoking the <code>__eq</code> metamethod. 75508e3e3a7aSWarner LoshReturns a boolean. 75518e3e3a7aSWarner Losh 75528e3e3a7aSWarner Losh 75538e3e3a7aSWarner Losh 75548e3e3a7aSWarner Losh 75558e3e3a7aSWarner Losh<p> 75568e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> 75578e3e3a7aSWarner LoshGets the real value of <code>table[index]</code>, 75588e3e3a7aSWarner Loshwithout invoking the <code>__index</code> metamethod. 75598e3e3a7aSWarner Losh<code>table</code> must be a table; 75608e3e3a7aSWarner Losh<code>index</code> may be any value. 75618e3e3a7aSWarner Losh 75628e3e3a7aSWarner Losh 75638e3e3a7aSWarner Losh 75648e3e3a7aSWarner Losh 75658e3e3a7aSWarner Losh<p> 75668e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3> 75678e3e3a7aSWarner LoshReturns the length of the object <code>v</code>, 75688e3e3a7aSWarner Loshwhich must be a table or a string, 75698e3e3a7aSWarner Loshwithout invoking the <code>__len</code> metamethod. 75708e3e3a7aSWarner LoshReturns an integer. 75718e3e3a7aSWarner Losh 75728e3e3a7aSWarner Losh 75738e3e3a7aSWarner Losh 75748e3e3a7aSWarner Losh 75758e3e3a7aSWarner Losh<p> 75768e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> 75778e3e3a7aSWarner LoshSets the real value of <code>table[index]</code> to <code>value</code>, 75788e3e3a7aSWarner Loshwithout invoking the <code>__newindex</code> metamethod. 75798e3e3a7aSWarner Losh<code>table</code> must be a table, 75808e3e3a7aSWarner Losh<code>index</code> any value different from <b>nil</b> and NaN, 75818e3e3a7aSWarner Loshand <code>value</code> any Lua value. 75828e3e3a7aSWarner Losh 75838e3e3a7aSWarner Losh 75848e3e3a7aSWarner Losh<p> 75858e3e3a7aSWarner LoshThis function returns <code>table</code>. 75868e3e3a7aSWarner Losh 75878e3e3a7aSWarner Losh 75888e3e3a7aSWarner Losh 75898e3e3a7aSWarner Losh 75908e3e3a7aSWarner Losh<p> 75918e3e3a7aSWarner Losh<hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> 75928e3e3a7aSWarner Losh 75938e3e3a7aSWarner Losh 75948e3e3a7aSWarner Losh<p> 75958e3e3a7aSWarner LoshIf <code>index</code> is a number, 75968e3e3a7aSWarner Loshreturns all arguments after argument number <code>index</code>; 75978e3e3a7aSWarner Losha negative number indexes from the end (-1 is the last argument). 75988e3e3a7aSWarner LoshOtherwise, <code>index</code> must be the string <code>"#"</code>, 75998e3e3a7aSWarner Loshand <code>select</code> returns the total number of extra arguments it received. 76008e3e3a7aSWarner Losh 76018e3e3a7aSWarner Losh 76028e3e3a7aSWarner Losh 76038e3e3a7aSWarner Losh 76048e3e3a7aSWarner Losh<p> 76058e3e3a7aSWarner Losh<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> 76068e3e3a7aSWarner Losh 76078e3e3a7aSWarner Losh 76088e3e3a7aSWarner Losh<p> 76098e3e3a7aSWarner LoshSets the metatable for the given table. 76108e3e3a7aSWarner Losh(To change the metatable of other types from Lua code, 76118e3e3a7aSWarner Loshyou must use the debug library (<a href="#6.10">§6.10</a>).) 76128e3e3a7aSWarner LoshIf <code>metatable</code> is <b>nil</b>, 76138e3e3a7aSWarner Loshremoves the metatable of the given table. 76148e3e3a7aSWarner LoshIf the original metatable has a <code>__metatable</code> field, 76158e3e3a7aSWarner Loshraises an error. 76168e3e3a7aSWarner Losh 76178e3e3a7aSWarner Losh 76188e3e3a7aSWarner Losh<p> 76198e3e3a7aSWarner LoshThis function returns <code>table</code>. 76208e3e3a7aSWarner Losh 76218e3e3a7aSWarner Losh 76228e3e3a7aSWarner Losh 76238e3e3a7aSWarner Losh 76248e3e3a7aSWarner Losh<p> 76258e3e3a7aSWarner Losh<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> 76268e3e3a7aSWarner Losh 76278e3e3a7aSWarner Losh 76288e3e3a7aSWarner Losh<p> 76298e3e3a7aSWarner LoshWhen called with no <code>base</code>, 76308e3e3a7aSWarner Losh<code>tonumber</code> tries to convert its argument to a number. 76318e3e3a7aSWarner LoshIf the argument is already a number or 76328e3e3a7aSWarner Losha string convertible to a number, 76338e3e3a7aSWarner Loshthen <code>tonumber</code> returns this number; 76348e3e3a7aSWarner Loshotherwise, it returns <b>nil</b>. 76358e3e3a7aSWarner Losh 76368e3e3a7aSWarner Losh 76378e3e3a7aSWarner Losh<p> 76388e3e3a7aSWarner LoshThe conversion of strings can result in integers or floats, 76398e3e3a7aSWarner Loshaccording to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 76408e3e3a7aSWarner Losh(The string may have leading and trailing spaces and a sign.) 76418e3e3a7aSWarner Losh 76428e3e3a7aSWarner Losh 76438e3e3a7aSWarner Losh<p> 76448e3e3a7aSWarner LoshWhen called with <code>base</code>, 76458e3e3a7aSWarner Loshthen <code>e</code> must be a string to be interpreted as 76468e3e3a7aSWarner Loshan integer numeral in that base. 76478e3e3a7aSWarner LoshThe base may be any integer between 2 and 36, inclusive. 76488e3e3a7aSWarner LoshIn bases above 10, the letter '<code>A</code>' (in either upper or lower case) 76498e3e3a7aSWarner Loshrepresents 10, '<code>B</code>' represents 11, and so forth, 76508e3e3a7aSWarner Loshwith '<code>Z</code>' representing 35. 76518e3e3a7aSWarner LoshIf the string <code>e</code> is not a valid numeral in the given base, 76528e3e3a7aSWarner Loshthe function returns <b>nil</b>. 76538e3e3a7aSWarner Losh 76548e3e3a7aSWarner Losh 76558e3e3a7aSWarner Losh 76568e3e3a7aSWarner Losh 76578e3e3a7aSWarner Losh<p> 76588e3e3a7aSWarner Losh<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3> 76598e3e3a7aSWarner LoshReceives a value of any type and 76608e3e3a7aSWarner Loshconverts it to a string in a human-readable format. 76618e3e3a7aSWarner Losh(For complete control of how numbers are converted, 76628e3e3a7aSWarner Loshuse <a href="#pdf-string.format"><code>string.format</code></a>.) 76638e3e3a7aSWarner Losh 76648e3e3a7aSWarner Losh 76658e3e3a7aSWarner Losh<p> 76668e3e3a7aSWarner LoshIf the metatable of <code>v</code> has a <code>__tostring</code> field, 76678e3e3a7aSWarner Loshthen <code>tostring</code> calls the corresponding value 76688e3e3a7aSWarner Loshwith <code>v</code> as argument, 76698e3e3a7aSWarner Loshand uses the result of the call as its result. 76708e3e3a7aSWarner Losh 76718e3e3a7aSWarner Losh 76728e3e3a7aSWarner Losh 76738e3e3a7aSWarner Losh 76748e3e3a7aSWarner Losh<p> 76758e3e3a7aSWarner Losh<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> 76768e3e3a7aSWarner LoshReturns the type of its only argument, coded as a string. 76778e3e3a7aSWarner LoshThe possible results of this function are 76788e3e3a7aSWarner Losh"<code>nil</code>" (a string, not the value <b>nil</b>), 76798e3e3a7aSWarner Losh"<code>number</code>", 76808e3e3a7aSWarner Losh"<code>string</code>", 76818e3e3a7aSWarner Losh"<code>boolean</code>", 76828e3e3a7aSWarner Losh"<code>table</code>", 76838e3e3a7aSWarner Losh"<code>function</code>", 76848e3e3a7aSWarner Losh"<code>thread</code>", 76858e3e3a7aSWarner Loshand "<code>userdata</code>". 76868e3e3a7aSWarner Losh 76878e3e3a7aSWarner Losh 76888e3e3a7aSWarner Losh 76898e3e3a7aSWarner Losh 76908e3e3a7aSWarner Losh<p> 76918e3e3a7aSWarner Losh<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> 76928e3e3a7aSWarner Losh 76938e3e3a7aSWarner Losh 76948e3e3a7aSWarner Losh<p> 76958e3e3a7aSWarner LoshA global variable (not a function) that 76968e3e3a7aSWarner Loshholds a string containing the running Lua version. 76978e3e3a7aSWarner LoshThe current value of this variable is "<code>Lua 5.3</code>". 76988e3e3a7aSWarner Losh 76998e3e3a7aSWarner Losh 77008e3e3a7aSWarner Losh 77018e3e3a7aSWarner Losh 77028e3e3a7aSWarner Losh<p> 77038e3e3a7aSWarner Losh<hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3> 77048e3e3a7aSWarner Losh 77058e3e3a7aSWarner Losh 77068e3e3a7aSWarner Losh<p> 77078e3e3a7aSWarner LoshThis function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, 77088e3e3a7aSWarner Loshexcept that it sets a new message handler <code>msgh</code>. 77098e3e3a7aSWarner Losh 77108e3e3a7aSWarner Losh 77118e3e3a7aSWarner Losh 77128e3e3a7aSWarner Losh 77138e3e3a7aSWarner Losh 77148e3e3a7aSWarner Losh 77158e3e3a7aSWarner Losh 77168e3e3a7aSWarner Losh<h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2> 77178e3e3a7aSWarner Losh 77188e3e3a7aSWarner Losh<p> 77198e3e3a7aSWarner LoshThis library comprises the operations to manipulate coroutines, 77208e3e3a7aSWarner Loshwhich come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. 77218e3e3a7aSWarner LoshSee <a href="#2.6">§2.6</a> for a general description of coroutines. 77228e3e3a7aSWarner Losh 77238e3e3a7aSWarner Losh 77248e3e3a7aSWarner Losh<p> 77258e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> 77268e3e3a7aSWarner Losh 77278e3e3a7aSWarner Losh 77288e3e3a7aSWarner Losh<p> 77298e3e3a7aSWarner LoshCreates a new coroutine, with body <code>f</code>. 77308e3e3a7aSWarner Losh<code>f</code> must be a function. 77318e3e3a7aSWarner LoshReturns this new coroutine, 77328e3e3a7aSWarner Loshan object with type <code>"thread"</code>. 77338e3e3a7aSWarner Losh 77348e3e3a7aSWarner Losh 77358e3e3a7aSWarner Losh 77368e3e3a7aSWarner Losh 77378e3e3a7aSWarner Losh<p> 77388e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ()</code></a></h3> 77398e3e3a7aSWarner Losh 77408e3e3a7aSWarner Losh 77418e3e3a7aSWarner Losh<p> 77428e3e3a7aSWarner LoshReturns true when the running coroutine can yield. 77438e3e3a7aSWarner Losh 77448e3e3a7aSWarner Losh 77458e3e3a7aSWarner Losh<p> 77468e3e3a7aSWarner LoshA running coroutine is yieldable if it is not the main thread and 77478e3e3a7aSWarner Loshit is not inside a non-yieldable C function. 77488e3e3a7aSWarner Losh 77498e3e3a7aSWarner Losh 77508e3e3a7aSWarner Losh 77518e3e3a7aSWarner Losh 77528e3e3a7aSWarner Losh<p> 77538e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> 77548e3e3a7aSWarner Losh 77558e3e3a7aSWarner Losh 77568e3e3a7aSWarner Losh<p> 77578e3e3a7aSWarner LoshStarts or continues the execution of coroutine <code>co</code>. 77588e3e3a7aSWarner LoshThe first time you resume a coroutine, 77598e3e3a7aSWarner Loshit starts running its body. 77608e3e3a7aSWarner LoshThe values <code>val1</code>, ... are passed 77618e3e3a7aSWarner Loshas the arguments to the body function. 77628e3e3a7aSWarner LoshIf the coroutine has yielded, 77638e3e3a7aSWarner Losh<code>resume</code> restarts it; 77648e3e3a7aSWarner Loshthe values <code>val1</code>, ... are passed 77658e3e3a7aSWarner Loshas the results from the yield. 77668e3e3a7aSWarner Losh 77678e3e3a7aSWarner Losh 77688e3e3a7aSWarner Losh<p> 77698e3e3a7aSWarner LoshIf the coroutine runs without any errors, 77708e3e3a7aSWarner Losh<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> 77718e3e3a7aSWarner Losh(when the coroutine yields) or any values returned by the body function 77728e3e3a7aSWarner Losh(when the coroutine terminates). 77738e3e3a7aSWarner LoshIf there is any error, 77748e3e3a7aSWarner Losh<code>resume</code> returns <b>false</b> plus the error message. 77758e3e3a7aSWarner Losh 77768e3e3a7aSWarner Losh 77778e3e3a7aSWarner Losh 77788e3e3a7aSWarner Losh 77798e3e3a7aSWarner Losh<p> 77808e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> 77818e3e3a7aSWarner Losh 77828e3e3a7aSWarner Losh 77838e3e3a7aSWarner Losh<p> 77848e3e3a7aSWarner LoshReturns the running coroutine plus a boolean, 77858e3e3a7aSWarner Loshtrue when the running coroutine is the main one. 77868e3e3a7aSWarner Losh 77878e3e3a7aSWarner Losh 77888e3e3a7aSWarner Losh 77898e3e3a7aSWarner Losh 77908e3e3a7aSWarner Losh<p> 77918e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> 77928e3e3a7aSWarner Losh 77938e3e3a7aSWarner Losh 77948e3e3a7aSWarner Losh<p> 77958e3e3a7aSWarner LoshReturns the status of coroutine <code>co</code>, as a string: 77968e3e3a7aSWarner Losh<code>"running"</code>, 77978e3e3a7aSWarner Loshif the coroutine is running (that is, it called <code>status</code>); 77988e3e3a7aSWarner Losh<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, 77998e3e3a7aSWarner Loshor if it has not started running yet; 78008e3e3a7aSWarner Losh<code>"normal"</code> if the coroutine is active but not running 78018e3e3a7aSWarner Losh(that is, it has resumed another coroutine); 78028e3e3a7aSWarner Loshand <code>"dead"</code> if the coroutine has finished its body function, 78038e3e3a7aSWarner Loshor if it has stopped with an error. 78048e3e3a7aSWarner Losh 78058e3e3a7aSWarner Losh 78068e3e3a7aSWarner Losh 78078e3e3a7aSWarner Losh 78088e3e3a7aSWarner Losh<p> 78098e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> 78108e3e3a7aSWarner Losh 78118e3e3a7aSWarner Losh 78128e3e3a7aSWarner Losh<p> 78138e3e3a7aSWarner LoshCreates a new coroutine, with body <code>f</code>. 78148e3e3a7aSWarner Losh<code>f</code> must be a function. 78158e3e3a7aSWarner LoshReturns a function that resumes the coroutine each time it is called. 78168e3e3a7aSWarner LoshAny arguments passed to the function behave as the 78178e3e3a7aSWarner Loshextra arguments to <code>resume</code>. 78188e3e3a7aSWarner LoshReturns the same values returned by <code>resume</code>, 78198e3e3a7aSWarner Loshexcept the first boolean. 78208e3e3a7aSWarner LoshIn case of error, propagates the error. 78218e3e3a7aSWarner Losh 78228e3e3a7aSWarner Losh 78238e3e3a7aSWarner Losh 78248e3e3a7aSWarner Losh 78258e3e3a7aSWarner Losh<p> 78268e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> 78278e3e3a7aSWarner Losh 78288e3e3a7aSWarner Losh 78298e3e3a7aSWarner Losh<p> 78308e3e3a7aSWarner LoshSuspends the execution of the calling coroutine. 78318e3e3a7aSWarner LoshAny arguments to <code>yield</code> are passed as extra results to <code>resume</code>. 78328e3e3a7aSWarner Losh 78338e3e3a7aSWarner Losh 78348e3e3a7aSWarner Losh 78358e3e3a7aSWarner Losh 78368e3e3a7aSWarner Losh 78378e3e3a7aSWarner Losh 78388e3e3a7aSWarner Losh 78398e3e3a7aSWarner Losh<h2>6.3 – <a name="6.3">Modules</a></h2> 78408e3e3a7aSWarner Losh 78418e3e3a7aSWarner Losh<p> 78428e3e3a7aSWarner LoshThe package library provides basic 78438e3e3a7aSWarner Loshfacilities for loading modules in Lua. 78448e3e3a7aSWarner LoshIt exports one function directly in the global environment: 78458e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a>. 78468e3e3a7aSWarner LoshEverything else is exported in a table <a name="pdf-package"><code>package</code></a>. 78478e3e3a7aSWarner Losh 78488e3e3a7aSWarner Losh 78498e3e3a7aSWarner Losh<p> 78508e3e3a7aSWarner Losh<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> 78518e3e3a7aSWarner Losh 78528e3e3a7aSWarner Losh 78538e3e3a7aSWarner Losh<p> 78548e3e3a7aSWarner LoshLoads the given module. 78558e3e3a7aSWarner LoshThe function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table 78568e3e3a7aSWarner Loshto determine whether <code>modname</code> is already loaded. 78578e3e3a7aSWarner LoshIf it is, then <code>require</code> returns the value stored 78588e3e3a7aSWarner Loshat <code>package.loaded[modname]</code>. 78598e3e3a7aSWarner LoshOtherwise, it tries to find a <em>loader</em> for the module. 78608e3e3a7aSWarner Losh 78618e3e3a7aSWarner Losh 78628e3e3a7aSWarner Losh<p> 78638e3e3a7aSWarner LoshTo find a loader, 78648e3e3a7aSWarner Losh<code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence. 78658e3e3a7aSWarner LoshBy changing this sequence, 78668e3e3a7aSWarner Loshwe can change how <code>require</code> looks for a module. 78678e3e3a7aSWarner LoshThe following explanation is based on the default configuration 78688e3e3a7aSWarner Loshfor <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 78698e3e3a7aSWarner Losh 78708e3e3a7aSWarner Losh 78718e3e3a7aSWarner Losh<p> 78728e3e3a7aSWarner LoshFirst <code>require</code> queries <code>package.preload[modname]</code>. 78738e3e3a7aSWarner LoshIf it has a value, 78748e3e3a7aSWarner Loshthis value (which must be a function) is the loader. 78758e3e3a7aSWarner LoshOtherwise <code>require</code> searches for a Lua loader using the 78768e3e3a7aSWarner Loshpath stored in <a href="#pdf-package.path"><code>package.path</code></a>. 78778e3e3a7aSWarner LoshIf that also fails, it searches for a C loader using the 78788e3e3a7aSWarner Loshpath stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 78798e3e3a7aSWarner LoshIf that also fails, 78808e3e3a7aSWarner Loshit tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>). 78818e3e3a7aSWarner Losh 78828e3e3a7aSWarner Losh 78838e3e3a7aSWarner Losh<p> 78848e3e3a7aSWarner LoshOnce a loader is found, 78858e3e3a7aSWarner Losh<code>require</code> calls the loader with two arguments: 78868e3e3a7aSWarner Losh<code>modname</code> and an extra value dependent on how it got the loader. 78878e3e3a7aSWarner Losh(If the loader came from a file, 78888e3e3a7aSWarner Loshthis extra value is the file name.) 78898e3e3a7aSWarner LoshIf the loader returns any non-nil value, 78908e3e3a7aSWarner Losh<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. 78918e3e3a7aSWarner LoshIf the loader does not return a non-nil value and 78928e3e3a7aSWarner Loshhas not assigned any value to <code>package.loaded[modname]</code>, 78938e3e3a7aSWarner Loshthen <code>require</code> assigns <b>true</b> to this entry. 78948e3e3a7aSWarner LoshIn any case, <code>require</code> returns the 78958e3e3a7aSWarner Loshfinal value of <code>package.loaded[modname]</code>. 78968e3e3a7aSWarner Losh 78978e3e3a7aSWarner Losh 78988e3e3a7aSWarner Losh<p> 78998e3e3a7aSWarner LoshIf there is any error loading or running the module, 79008e3e3a7aSWarner Loshor if it cannot find any loader for the module, 79018e3e3a7aSWarner Loshthen <code>require</code> raises an error. 79028e3e3a7aSWarner Losh 79038e3e3a7aSWarner Losh 79048e3e3a7aSWarner Losh 79058e3e3a7aSWarner Losh 79068e3e3a7aSWarner Losh<p> 79078e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3> 79088e3e3a7aSWarner Losh 79098e3e3a7aSWarner Losh 79108e3e3a7aSWarner Losh<p> 79118e3e3a7aSWarner LoshA string describing some compile-time configurations for packages. 79128e3e3a7aSWarner LoshThis string is a sequence of lines: 79138e3e3a7aSWarner Losh 79148e3e3a7aSWarner Losh<ul> 79158e3e3a7aSWarner Losh 79168e3e3a7aSWarner Losh<li>The first line is the directory separator string. 79178e3e3a7aSWarner LoshDefault is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li> 79188e3e3a7aSWarner Losh 79198e3e3a7aSWarner Losh<li>The second line is the character that separates templates in a path. 79208e3e3a7aSWarner LoshDefault is '<code>;</code>'.</li> 79218e3e3a7aSWarner Losh 79228e3e3a7aSWarner Losh<li>The third line is the string that marks the 79238e3e3a7aSWarner Loshsubstitution points in a template. 79248e3e3a7aSWarner LoshDefault is '<code>?</code>'.</li> 79258e3e3a7aSWarner Losh 79268e3e3a7aSWarner Losh<li>The fourth line is a string that, in a path in Windows, 79278e3e3a7aSWarner Loshis replaced by the executable's directory. 79288e3e3a7aSWarner LoshDefault is '<code>!</code>'.</li> 79298e3e3a7aSWarner Losh 79308e3e3a7aSWarner Losh<li>The fifth line is a mark to ignore all text after it 79318e3e3a7aSWarner Loshwhen building the <code>luaopen_</code> function name. 79328e3e3a7aSWarner LoshDefault is '<code>-</code>'.</li> 79338e3e3a7aSWarner Losh 79348e3e3a7aSWarner Losh</ul> 79358e3e3a7aSWarner Losh 79368e3e3a7aSWarner Losh 79378e3e3a7aSWarner Losh 79388e3e3a7aSWarner Losh<p> 79398e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> 79408e3e3a7aSWarner Losh 79418e3e3a7aSWarner Losh 79428e3e3a7aSWarner Losh<p> 79438e3e3a7aSWarner LoshThe path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. 79448e3e3a7aSWarner Losh 79458e3e3a7aSWarner Losh 79468e3e3a7aSWarner Losh<p> 79478e3e3a7aSWarner LoshLua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way 79488e3e3a7aSWarner Loshit initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, 79498e3e3a7aSWarner Loshusing the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>, 79508e3e3a7aSWarner Loshor the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>, 79518e3e3a7aSWarner Loshor a default path defined in <code>luaconf.h</code>. 79528e3e3a7aSWarner Losh 79538e3e3a7aSWarner Losh 79548e3e3a7aSWarner Losh 79558e3e3a7aSWarner Losh 79568e3e3a7aSWarner Losh<p> 79578e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> 79588e3e3a7aSWarner Losh 79598e3e3a7aSWarner Losh 79608e3e3a7aSWarner Losh<p> 79618e3e3a7aSWarner LoshA table used by <a href="#pdf-require"><code>require</code></a> to control which 79628e3e3a7aSWarner Loshmodules are already loaded. 79638e3e3a7aSWarner LoshWhen you require a module <code>modname</code> and 79648e3e3a7aSWarner Losh<code>package.loaded[modname]</code> is not false, 79658e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a> simply returns the value stored there. 79668e3e3a7aSWarner Losh 79678e3e3a7aSWarner Losh 79688e3e3a7aSWarner Losh<p> 79698e3e3a7aSWarner LoshThis variable is only a reference to the real table; 79708e3e3a7aSWarner Loshassignments to this variable do not change the 79718e3e3a7aSWarner Loshtable used by <a href="#pdf-require"><code>require</code></a>. 79728e3e3a7aSWarner Losh 79738e3e3a7aSWarner Losh 79748e3e3a7aSWarner Losh 79758e3e3a7aSWarner Losh 79768e3e3a7aSWarner Losh<p> 79778e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> 79788e3e3a7aSWarner Losh 79798e3e3a7aSWarner Losh 79808e3e3a7aSWarner Losh<p> 79818e3e3a7aSWarner LoshDynamically links the host program with the C library <code>libname</code>. 79828e3e3a7aSWarner Losh 79838e3e3a7aSWarner Losh 79848e3e3a7aSWarner Losh<p> 79858e3e3a7aSWarner LoshIf <code>funcname</code> is "<code>*</code>", 79868e3e3a7aSWarner Loshthen it only links with the library, 79878e3e3a7aSWarner Loshmaking the symbols exported by the library 79888e3e3a7aSWarner Loshavailable to other dynamically linked libraries. 79898e3e3a7aSWarner LoshOtherwise, 79908e3e3a7aSWarner Loshit looks for a function <code>funcname</code> inside the library 79918e3e3a7aSWarner Loshand returns this function as a C function. 79928e3e3a7aSWarner LoshSo, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype 79938e3e3a7aSWarner Losh(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 79948e3e3a7aSWarner Losh 79958e3e3a7aSWarner Losh 79968e3e3a7aSWarner Losh<p> 79978e3e3a7aSWarner LoshThis is a low-level function. 79988e3e3a7aSWarner LoshIt completely bypasses the package and module system. 79998e3e3a7aSWarner LoshUnlike <a href="#pdf-require"><code>require</code></a>, 80008e3e3a7aSWarner Loshit does not perform any path searching and 80018e3e3a7aSWarner Loshdoes not automatically adds extensions. 80028e3e3a7aSWarner Losh<code>libname</code> must be the complete file name of the C library, 80038e3e3a7aSWarner Loshincluding if necessary a path and an extension. 80048e3e3a7aSWarner Losh<code>funcname</code> must be the exact name exported by the C library 80058e3e3a7aSWarner Losh(which may depend on the C compiler and linker used). 80068e3e3a7aSWarner Losh 80078e3e3a7aSWarner Losh 80088e3e3a7aSWarner Losh<p> 80098e3e3a7aSWarner LoshThis function is not supported by Standard C. 80108e3e3a7aSWarner LoshAs such, it is only available on some platforms 80118e3e3a7aSWarner Losh(Windows, Linux, Mac OS X, Solaris, BSD, 80128e3e3a7aSWarner Loshplus other Unix systems that support the <code>dlfcn</code> standard). 80138e3e3a7aSWarner Losh 80148e3e3a7aSWarner Losh 80158e3e3a7aSWarner Losh 80168e3e3a7aSWarner Losh 80178e3e3a7aSWarner Losh<p> 80188e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> 80198e3e3a7aSWarner Losh 80208e3e3a7aSWarner Losh 80218e3e3a7aSWarner Losh<p> 80228e3e3a7aSWarner LoshThe path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. 80238e3e3a7aSWarner Losh 80248e3e3a7aSWarner Losh 80258e3e3a7aSWarner Losh<p> 80268e3e3a7aSWarner LoshAt start-up, Lua initializes this variable with 80278e3e3a7aSWarner Loshthe value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or 80288e3e3a7aSWarner Loshthe environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or 80298e3e3a7aSWarner Loshwith a default path defined in <code>luaconf.h</code>, 80308e3e3a7aSWarner Loshif those environment variables are not defined. 80318e3e3a7aSWarner LoshAny "<code>;;</code>" in the value of the environment variable 80328e3e3a7aSWarner Loshis replaced by the default path. 80338e3e3a7aSWarner Losh 80348e3e3a7aSWarner Losh 80358e3e3a7aSWarner Losh 80368e3e3a7aSWarner Losh 80378e3e3a7aSWarner Losh<p> 80388e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> 80398e3e3a7aSWarner Losh 80408e3e3a7aSWarner Losh 80418e3e3a7aSWarner Losh<p> 80428e3e3a7aSWarner LoshA table to store loaders for specific modules 80438e3e3a7aSWarner Losh(see <a href="#pdf-require"><code>require</code></a>). 80448e3e3a7aSWarner Losh 80458e3e3a7aSWarner Losh 80468e3e3a7aSWarner Losh<p> 80478e3e3a7aSWarner LoshThis variable is only a reference to the real table; 80488e3e3a7aSWarner Loshassignments to this variable do not change the 80498e3e3a7aSWarner Loshtable used by <a href="#pdf-require"><code>require</code></a>. 80508e3e3a7aSWarner Losh 80518e3e3a7aSWarner Losh 80528e3e3a7aSWarner Losh 80538e3e3a7aSWarner Losh 80548e3e3a7aSWarner Losh<p> 80558e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3> 80568e3e3a7aSWarner Losh 80578e3e3a7aSWarner Losh 80588e3e3a7aSWarner Losh<p> 80598e3e3a7aSWarner LoshA table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules. 80608e3e3a7aSWarner Losh 80618e3e3a7aSWarner Losh 80628e3e3a7aSWarner Losh<p> 80638e3e3a7aSWarner LoshEach entry in this table is a <em>searcher function</em>. 80648e3e3a7aSWarner LoshWhen looking for a module, 80658e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, 80668e3e3a7aSWarner Loshwith the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its 80678e3e3a7aSWarner Loshsole parameter. 80688e3e3a7aSWarner LoshThe function can return another function (the module <em>loader</em>) 80698e3e3a7aSWarner Loshplus an extra value that will be passed to that loader, 80708e3e3a7aSWarner Loshor a string explaining why it did not find that module 80718e3e3a7aSWarner Losh(or <b>nil</b> if it has nothing to say). 80728e3e3a7aSWarner Losh 80738e3e3a7aSWarner Losh 80748e3e3a7aSWarner Losh<p> 80758e3e3a7aSWarner LoshLua initializes this table with four searcher functions. 80768e3e3a7aSWarner Losh 80778e3e3a7aSWarner Losh 80788e3e3a7aSWarner Losh<p> 80798e3e3a7aSWarner LoshThe first searcher simply looks for a loader in the 80808e3e3a7aSWarner Losh<a href="#pdf-package.preload"><code>package.preload</code></a> table. 80818e3e3a7aSWarner Losh 80828e3e3a7aSWarner Losh 80838e3e3a7aSWarner Losh<p> 80848e3e3a7aSWarner LoshThe second searcher looks for a loader as a Lua library, 80858e3e3a7aSWarner Loshusing the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. 80868e3e3a7aSWarner LoshThe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 80878e3e3a7aSWarner Losh 80888e3e3a7aSWarner Losh 80898e3e3a7aSWarner Losh<p> 80908e3e3a7aSWarner LoshThe third searcher looks for a loader as a C library, 80918e3e3a7aSWarner Loshusing the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 80928e3e3a7aSWarner LoshAgain, 80938e3e3a7aSWarner Loshthe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 80948e3e3a7aSWarner LoshFor instance, 80958e3e3a7aSWarner Loshif the C path is the string 80968e3e3a7aSWarner Losh 80978e3e3a7aSWarner Losh<pre> 80988e3e3a7aSWarner Losh "./?.so;./?.dll;/usr/local/?/init.so" 80998e3e3a7aSWarner Losh</pre><p> 81008e3e3a7aSWarner Loshthe searcher for module <code>foo</code> 81018e3e3a7aSWarner Loshwill try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, 81028e3e3a7aSWarner Loshand <code>/usr/local/foo/init.so</code>, in that order. 81038e3e3a7aSWarner LoshOnce it finds a C library, 81048e3e3a7aSWarner Loshthis searcher first uses a dynamic link facility to link the 81058e3e3a7aSWarner Loshapplication with the library. 81068e3e3a7aSWarner LoshThen it tries to find a C function inside the library to 81078e3e3a7aSWarner Loshbe used as the loader. 81088e3e3a7aSWarner LoshThe name of this C function is the string "<code>luaopen_</code>" 81098e3e3a7aSWarner Loshconcatenated with a copy of the module name where each dot 81108e3e3a7aSWarner Loshis replaced by an underscore. 81118e3e3a7aSWarner LoshMoreover, if the module name has a hyphen, 81128e3e3a7aSWarner Loshits suffix after (and including) the first hyphen is removed. 81138e3e3a7aSWarner LoshFor instance, if the module name is <code>a.b.c-v2.1</code>, 81148e3e3a7aSWarner Loshthe function name will be <code>luaopen_a_b_c</code>. 81158e3e3a7aSWarner Losh 81168e3e3a7aSWarner Losh 81178e3e3a7aSWarner Losh<p> 81188e3e3a7aSWarner LoshThe fourth searcher tries an <em>all-in-one loader</em>. 81198e3e3a7aSWarner LoshIt searches the C path for a library for 81208e3e3a7aSWarner Loshthe root name of the given module. 81218e3e3a7aSWarner LoshFor instance, when requiring <code>a.b.c</code>, 81228e3e3a7aSWarner Loshit will search for a C library for <code>a</code>. 81238e3e3a7aSWarner LoshIf found, it looks into it for an open function for 81248e3e3a7aSWarner Loshthe submodule; 81258e3e3a7aSWarner Loshin our example, that would be <code>luaopen_a_b_c</code>. 81268e3e3a7aSWarner LoshWith this facility, a package can pack several C submodules 81278e3e3a7aSWarner Loshinto one single library, 81288e3e3a7aSWarner Loshwith each submodule keeping its original open function. 81298e3e3a7aSWarner Losh 81308e3e3a7aSWarner Losh 81318e3e3a7aSWarner Losh<p> 81328e3e3a7aSWarner LoshAll searchers except the first one (preload) return as the extra value 81338e3e3a7aSWarner Loshthe file name where the module was found, 81348e3e3a7aSWarner Loshas returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 81358e3e3a7aSWarner LoshThe first searcher returns no extra value. 81368e3e3a7aSWarner Losh 81378e3e3a7aSWarner Losh 81388e3e3a7aSWarner Losh 81398e3e3a7aSWarner Losh 81408e3e3a7aSWarner Losh<p> 81418e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3> 81428e3e3a7aSWarner Losh 81438e3e3a7aSWarner Losh 81448e3e3a7aSWarner Losh<p> 81458e3e3a7aSWarner LoshSearches for the given <code>name</code> in the given <code>path</code>. 81468e3e3a7aSWarner Losh 81478e3e3a7aSWarner Losh 81488e3e3a7aSWarner Losh<p> 81498e3e3a7aSWarner LoshA path is a string containing a sequence of 81508e3e3a7aSWarner Losh<em>templates</em> separated by semicolons. 81518e3e3a7aSWarner LoshFor each template, 81528e3e3a7aSWarner Loshthe function replaces each interrogation mark (if any) 81538e3e3a7aSWarner Loshin the template with a copy of <code>name</code> 81548e3e3a7aSWarner Loshwherein all occurrences of <code>sep</code> 81558e3e3a7aSWarner Losh(a dot, by default) 81568e3e3a7aSWarner Loshwere replaced by <code>rep</code> 81578e3e3a7aSWarner Losh(the system's directory separator, by default), 81588e3e3a7aSWarner Loshand then tries to open the resulting file name. 81598e3e3a7aSWarner Losh 81608e3e3a7aSWarner Losh 81618e3e3a7aSWarner Losh<p> 81628e3e3a7aSWarner LoshFor instance, if the path is the string 81638e3e3a7aSWarner Losh 81648e3e3a7aSWarner Losh<pre> 81658e3e3a7aSWarner Losh "./?.lua;./?.lc;/usr/local/?/init.lua" 81668e3e3a7aSWarner Losh</pre><p> 81678e3e3a7aSWarner Loshthe search for the name <code>foo.a</code> 81688e3e3a7aSWarner Loshwill try to open the files 81698e3e3a7aSWarner Losh<code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and 81708e3e3a7aSWarner Losh<code>/usr/local/foo/a/init.lua</code>, in that order. 81718e3e3a7aSWarner Losh 81728e3e3a7aSWarner Losh 81738e3e3a7aSWarner Losh<p> 81748e3e3a7aSWarner LoshReturns the resulting name of the first file that it can 81758e3e3a7aSWarner Loshopen in read mode (after closing the file), 81768e3e3a7aSWarner Loshor <b>nil</b> plus an error message if none succeeds. 81778e3e3a7aSWarner Losh(This error message lists all file names it tried to open.) 81788e3e3a7aSWarner Losh 81798e3e3a7aSWarner Losh 81808e3e3a7aSWarner Losh 81818e3e3a7aSWarner Losh 81828e3e3a7aSWarner Losh 81838e3e3a7aSWarner Losh 81848e3e3a7aSWarner Losh 81858e3e3a7aSWarner Losh<h2>6.4 – <a name="6.4">String Manipulation</a></h2> 81868e3e3a7aSWarner Losh 81878e3e3a7aSWarner Losh<p> 81888e3e3a7aSWarner LoshThis library provides generic functions for string manipulation, 81898e3e3a7aSWarner Loshsuch as finding and extracting substrings, and pattern matching. 81908e3e3a7aSWarner LoshWhen indexing a string in Lua, the first character is at position 1 81918e3e3a7aSWarner Losh(not at 0, as in C). 81928e3e3a7aSWarner LoshIndices are allowed to be negative and are interpreted as indexing backwards, 81938e3e3a7aSWarner Loshfrom the end of the string. 81948e3e3a7aSWarner LoshThus, the last character is at position -1, and so on. 81958e3e3a7aSWarner Losh 81968e3e3a7aSWarner Losh 81978e3e3a7aSWarner Losh<p> 81988e3e3a7aSWarner LoshThe string library provides all its functions inside the table 81998e3e3a7aSWarner Losh<a name="pdf-string"><code>string</code></a>. 82008e3e3a7aSWarner LoshIt also sets a metatable for strings 82018e3e3a7aSWarner Loshwhere the <code>__index</code> field points to the <code>string</code> table. 82028e3e3a7aSWarner LoshTherefore, you can use the string functions in object-oriented style. 82038e3e3a7aSWarner LoshFor instance, <code>string.byte(s,i)</code> 82048e3e3a7aSWarner Loshcan be written as <code>s:byte(i)</code>. 82058e3e3a7aSWarner Losh 82068e3e3a7aSWarner Losh 82078e3e3a7aSWarner Losh<p> 82088e3e3a7aSWarner LoshThe string library assumes one-byte character encodings. 82098e3e3a7aSWarner Losh 82108e3e3a7aSWarner Losh 82118e3e3a7aSWarner Losh<p> 82128e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> 82138e3e3a7aSWarner LoshReturns the internal numeric codes of the characters <code>s[i]</code>, 82148e3e3a7aSWarner Losh<code>s[i+1]</code>, ..., <code>s[j]</code>. 82158e3e3a7aSWarner LoshThe default value for <code>i</code> is 1; 82168e3e3a7aSWarner Loshthe default value for <code>j</code> is <code>i</code>. 82178e3e3a7aSWarner LoshThese indices are corrected 82188e3e3a7aSWarner Loshfollowing the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>. 82198e3e3a7aSWarner Losh 82208e3e3a7aSWarner Losh 82218e3e3a7aSWarner Losh<p> 82228e3e3a7aSWarner LoshNumeric codes are not necessarily portable across platforms. 82238e3e3a7aSWarner Losh 82248e3e3a7aSWarner Losh 82258e3e3a7aSWarner Losh 82268e3e3a7aSWarner Losh 82278e3e3a7aSWarner Losh<p> 82288e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> 82298e3e3a7aSWarner LoshReceives zero or more integers. 82308e3e3a7aSWarner LoshReturns a string with length equal to the number of arguments, 82318e3e3a7aSWarner Loshin which each character has the internal numeric code equal 82328e3e3a7aSWarner Loshto its corresponding argument. 82338e3e3a7aSWarner Losh 82348e3e3a7aSWarner Losh 82358e3e3a7aSWarner Losh<p> 82368e3e3a7aSWarner LoshNumeric codes are not necessarily portable across platforms. 82378e3e3a7aSWarner Losh 82388e3e3a7aSWarner Losh 82398e3e3a7aSWarner Losh 82408e3e3a7aSWarner Losh 82418e3e3a7aSWarner Losh<p> 82428e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3> 82438e3e3a7aSWarner Losh 82448e3e3a7aSWarner Losh 82458e3e3a7aSWarner Losh<p> 82468e3e3a7aSWarner LoshReturns a string containing a binary representation 82478e3e3a7aSWarner Losh(a <em>binary chunk</em>) 82488e3e3a7aSWarner Loshof the given function, 82498e3e3a7aSWarner Loshso that a later <a href="#pdf-load"><code>load</code></a> on this string returns 82508e3e3a7aSWarner Losha copy of the function (but with new upvalues). 82518e3e3a7aSWarner LoshIf <code>strip</code> is a true value, 82528e3e3a7aSWarner Loshthe binary representation may not include all debug information 82538e3e3a7aSWarner Loshabout the function, 82548e3e3a7aSWarner Loshto save space. 82558e3e3a7aSWarner Losh 82568e3e3a7aSWarner Losh 82578e3e3a7aSWarner Losh<p> 82588e3e3a7aSWarner LoshFunctions with upvalues have only their number of upvalues saved. 82598e3e3a7aSWarner LoshWhen (re)loaded, 82608e3e3a7aSWarner Loshthose upvalues receive fresh instances containing <b>nil</b>. 82618e3e3a7aSWarner Losh(You can use the debug library to serialize 82628e3e3a7aSWarner Loshand reload the upvalues of a function 82638e3e3a7aSWarner Loshin a way adequate to your needs.) 82648e3e3a7aSWarner Losh 82658e3e3a7aSWarner Losh 82668e3e3a7aSWarner Losh 82678e3e3a7aSWarner Losh 82688e3e3a7aSWarner Losh<p> 82698e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> 82708e3e3a7aSWarner Losh 82718e3e3a7aSWarner Losh 82728e3e3a7aSWarner Losh<p> 82738e3e3a7aSWarner LoshLooks for the first match of 82748e3e3a7aSWarner Losh<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 82758e3e3a7aSWarner LoshIf it finds a match, then <code>find</code> returns the indices of <code>s</code> 82768e3e3a7aSWarner Loshwhere this occurrence starts and ends; 82778e3e3a7aSWarner Loshotherwise, it returns <b>nil</b>. 82788e3e3a7aSWarner LoshA third, optional numeric argument <code>init</code> specifies 82798e3e3a7aSWarner Loshwhere to start the search; 82808e3e3a7aSWarner Loshits default value is 1 and can be negative. 82818e3e3a7aSWarner LoshA value of <b>true</b> as a fourth, optional argument <code>plain</code> 82828e3e3a7aSWarner Loshturns off the pattern matching facilities, 82838e3e3a7aSWarner Loshso the function does a plain "find substring" operation, 82848e3e3a7aSWarner Loshwith no characters in <code>pattern</code> being considered magic. 82858e3e3a7aSWarner LoshNote that if <code>plain</code> is given, then <code>init</code> must be given as well. 82868e3e3a7aSWarner Losh 82878e3e3a7aSWarner Losh 82888e3e3a7aSWarner Losh<p> 82898e3e3a7aSWarner LoshIf the pattern has captures, 82908e3e3a7aSWarner Loshthen in a successful match 82918e3e3a7aSWarner Loshthe captured values are also returned, 82928e3e3a7aSWarner Loshafter the two indices. 82938e3e3a7aSWarner Losh 82948e3e3a7aSWarner Losh 82958e3e3a7aSWarner Losh 82968e3e3a7aSWarner Losh 82978e3e3a7aSWarner Losh<p> 82988e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> 82998e3e3a7aSWarner Losh 83008e3e3a7aSWarner Losh 83018e3e3a7aSWarner Losh<p> 83028e3e3a7aSWarner LoshReturns a formatted version of its variable number of arguments 83038e3e3a7aSWarner Loshfollowing the description given in its first argument (which must be a string). 83048e3e3a7aSWarner LoshThe format string follows the same rules as the ISO C function <code>sprintf</code>. 83058e3e3a7aSWarner LoshThe only differences are that the options/modifiers 83068e3e3a7aSWarner Losh<code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>, 83078e3e3a7aSWarner Loshand <code>p</code> are not supported 83088e3e3a7aSWarner Loshand that there is an extra option, <code>q</code>. 83098e3e3a7aSWarner Losh 83108e3e3a7aSWarner Losh 83118e3e3a7aSWarner Losh<p> 83128e3e3a7aSWarner LoshThe <code>q</code> option formats a string between double quotes, 83138e3e3a7aSWarner Loshusing escape sequences when necessary to ensure that 83148e3e3a7aSWarner Loshit can safely be read back by the Lua interpreter. 83158e3e3a7aSWarner LoshFor instance, the call 83168e3e3a7aSWarner Losh 83178e3e3a7aSWarner Losh<pre> 83188e3e3a7aSWarner Losh string.format('%q', 'a string with "quotes" and \n new line') 83198e3e3a7aSWarner Losh</pre><p> 83208e3e3a7aSWarner Loshmay produce the string: 83218e3e3a7aSWarner Losh 83228e3e3a7aSWarner Losh<pre> 83238e3e3a7aSWarner Losh "a string with \"quotes\" and \ 83248e3e3a7aSWarner Losh new line" 83258e3e3a7aSWarner Losh</pre> 83268e3e3a7aSWarner Losh 83278e3e3a7aSWarner Losh<p> 83288e3e3a7aSWarner LoshOptions 83298e3e3a7aSWarner Losh<code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>, 83308e3e3a7aSWarner Losh<code>G</code>, and <code>g</code> all expect a number as argument. 83318e3e3a7aSWarner LoshOptions <code>c</code>, <code>d</code>, 83328e3e3a7aSWarner Losh<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> 83338e3e3a7aSWarner Loshexpect an integer. 83348e3e3a7aSWarner LoshWhen Lua is compiled with a C89 compiler, 83358e3e3a7aSWarner Loshoptions <code>A</code> and <code>a</code> (hexadecimal floats) 83368e3e3a7aSWarner Loshdo not support any modifier (flags, width, length). 83378e3e3a7aSWarner Losh 83388e3e3a7aSWarner Losh 83398e3e3a7aSWarner Losh<p> 83408e3e3a7aSWarner LoshOption <code>s</code> expects a string; 83418e3e3a7aSWarner Loshif its argument is not a string, 83428e3e3a7aSWarner Loshit is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 83438e3e3a7aSWarner LoshIf the option has any modifier (flags, width, length), 83448e3e3a7aSWarner Loshthe string argument should not contain embedded zeros. 83458e3e3a7aSWarner Losh 83468e3e3a7aSWarner Losh 83478e3e3a7aSWarner Losh 83488e3e3a7aSWarner Losh 83498e3e3a7aSWarner Losh<p> 83508e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3> 83518e3e3a7aSWarner LoshReturns an iterator function that, 83528e3e3a7aSWarner Losheach time it is called, 83538e3e3a7aSWarner Loshreturns the next captures from <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) 83548e3e3a7aSWarner Loshover the string <code>s</code>. 83558e3e3a7aSWarner LoshIf <code>pattern</code> specifies no captures, 83568e3e3a7aSWarner Loshthen the whole match is produced in each call. 83578e3e3a7aSWarner Losh 83588e3e3a7aSWarner Losh 83598e3e3a7aSWarner Losh<p> 83608e3e3a7aSWarner LoshAs an example, the following loop 83618e3e3a7aSWarner Loshwill iterate over all the words from string <code>s</code>, 83628e3e3a7aSWarner Loshprinting one per line: 83638e3e3a7aSWarner Losh 83648e3e3a7aSWarner Losh<pre> 83658e3e3a7aSWarner Losh s = "hello world from Lua" 83668e3e3a7aSWarner Losh for w in string.gmatch(s, "%a+") do 83678e3e3a7aSWarner Losh print(w) 83688e3e3a7aSWarner Losh end 83698e3e3a7aSWarner Losh</pre><p> 83708e3e3a7aSWarner LoshThe next example collects all pairs <code>key=value</code> from the 83718e3e3a7aSWarner Loshgiven string into a table: 83728e3e3a7aSWarner Losh 83738e3e3a7aSWarner Losh<pre> 83748e3e3a7aSWarner Losh t = {} 83758e3e3a7aSWarner Losh s = "from=world, to=Lua" 83768e3e3a7aSWarner Losh for k, v in string.gmatch(s, "(%w+)=(%w+)") do 83778e3e3a7aSWarner Losh t[k] = v 83788e3e3a7aSWarner Losh end 83798e3e3a7aSWarner Losh</pre> 83808e3e3a7aSWarner Losh 83818e3e3a7aSWarner Losh<p> 83828e3e3a7aSWarner LoshFor this function, a caret '<code>^</code>' at the start of a pattern does not 83838e3e3a7aSWarner Loshwork as an anchor, as this would prevent the iteration. 83848e3e3a7aSWarner Losh 83858e3e3a7aSWarner Losh 83868e3e3a7aSWarner Losh 83878e3e3a7aSWarner Losh 83888e3e3a7aSWarner Losh<p> 83898e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> 83908e3e3a7aSWarner LoshReturns a copy of <code>s</code> 83918e3e3a7aSWarner Loshin which all (or the first <code>n</code>, if given) 83928e3e3a7aSWarner Loshoccurrences of the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) have been 83938e3e3a7aSWarner Loshreplaced by a replacement string specified by <code>repl</code>, 83948e3e3a7aSWarner Loshwhich can be a string, a table, or a function. 83958e3e3a7aSWarner Losh<code>gsub</code> also returns, as its second value, 83968e3e3a7aSWarner Loshthe total number of matches that occurred. 83978e3e3a7aSWarner LoshThe name <code>gsub</code> comes from <em>Global SUBstitution</em>. 83988e3e3a7aSWarner Losh 83998e3e3a7aSWarner Losh 84008e3e3a7aSWarner Losh<p> 84018e3e3a7aSWarner LoshIf <code>repl</code> is a string, then its value is used for replacement. 84028e3e3a7aSWarner LoshThe character <code>%</code> works as an escape character: 84038e3e3a7aSWarner Loshany sequence in <code>repl</code> of the form <code>%<em>d</em></code>, 84048e3e3a7aSWarner Loshwith <em>d</em> between 1 and 9, 84058e3e3a7aSWarner Loshstands for the value of the <em>d</em>-th captured substring. 84068e3e3a7aSWarner LoshThe sequence <code>%0</code> stands for the whole match. 84078e3e3a7aSWarner LoshThe sequence <code>%%</code> stands for a single <code>%</code>. 84088e3e3a7aSWarner Losh 84098e3e3a7aSWarner Losh 84108e3e3a7aSWarner Losh<p> 84118e3e3a7aSWarner LoshIf <code>repl</code> is a table, then the table is queried for every match, 84128e3e3a7aSWarner Loshusing the first capture as the key. 84138e3e3a7aSWarner Losh 84148e3e3a7aSWarner Losh 84158e3e3a7aSWarner Losh<p> 84168e3e3a7aSWarner LoshIf <code>repl</code> is a function, then this function is called every time a 84178e3e3a7aSWarner Loshmatch occurs, with all captured substrings passed as arguments, 84188e3e3a7aSWarner Loshin order. 84198e3e3a7aSWarner Losh 84208e3e3a7aSWarner Losh 84218e3e3a7aSWarner Losh<p> 84228e3e3a7aSWarner LoshIn any case, 84238e3e3a7aSWarner Loshif the pattern specifies no captures, 84248e3e3a7aSWarner Loshthen it behaves as if the whole pattern was inside a capture. 84258e3e3a7aSWarner Losh 84268e3e3a7aSWarner Losh 84278e3e3a7aSWarner Losh<p> 84288e3e3a7aSWarner LoshIf the value returned by the table query or by the function call 84298e3e3a7aSWarner Loshis a string or a number, 84308e3e3a7aSWarner Loshthen it is used as the replacement string; 84318e3e3a7aSWarner Loshotherwise, if it is <b>false</b> or <b>nil</b>, 84328e3e3a7aSWarner Loshthen there is no replacement 84338e3e3a7aSWarner Losh(that is, the original match is kept in the string). 84348e3e3a7aSWarner Losh 84358e3e3a7aSWarner Losh 84368e3e3a7aSWarner Losh<p> 84378e3e3a7aSWarner LoshHere are some examples: 84388e3e3a7aSWarner Losh 84398e3e3a7aSWarner Losh<pre> 84408e3e3a7aSWarner Losh x = string.gsub("hello world", "(%w+)", "%1 %1") 84418e3e3a7aSWarner Losh --> x="hello hello world world" 84428e3e3a7aSWarner Losh 84438e3e3a7aSWarner Losh x = string.gsub("hello world", "%w+", "%0 %0", 1) 84448e3e3a7aSWarner Losh --> x="hello hello world" 84458e3e3a7aSWarner Losh 84468e3e3a7aSWarner Losh x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 84478e3e3a7aSWarner Losh --> x="world hello Lua from" 84488e3e3a7aSWarner Losh 84498e3e3a7aSWarner Losh x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) 84508e3e3a7aSWarner Losh --> x="home = /home/roberto, user = roberto" 84518e3e3a7aSWarner Losh 84528e3e3a7aSWarner Losh x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 84538e3e3a7aSWarner Losh return load(s)() 84548e3e3a7aSWarner Losh end) 84558e3e3a7aSWarner Losh --> x="4+5 = 9" 84568e3e3a7aSWarner Losh 84578e3e3a7aSWarner Losh local t = {name="lua", version="5.3"} 84588e3e3a7aSWarner Losh x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 84598e3e3a7aSWarner Losh --> x="lua-5.3.tar.gz" 84608e3e3a7aSWarner Losh</pre> 84618e3e3a7aSWarner Losh 84628e3e3a7aSWarner Losh 84638e3e3a7aSWarner Losh 84648e3e3a7aSWarner Losh<p> 84658e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> 84668e3e3a7aSWarner LoshReceives a string and returns its length. 84678e3e3a7aSWarner LoshThe empty string <code>""</code> has length 0. 84688e3e3a7aSWarner LoshEmbedded zeros are counted, 84698e3e3a7aSWarner Loshso <code>"a\000bc\000"</code> has length 5. 84708e3e3a7aSWarner Losh 84718e3e3a7aSWarner Losh 84728e3e3a7aSWarner Losh 84738e3e3a7aSWarner Losh 84748e3e3a7aSWarner Losh<p> 84758e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> 84768e3e3a7aSWarner LoshReceives a string and returns a copy of this string with all 84778e3e3a7aSWarner Loshuppercase letters changed to lowercase. 84788e3e3a7aSWarner LoshAll other characters are left unchanged. 84798e3e3a7aSWarner LoshThe definition of what an uppercase letter is depends on the current locale. 84808e3e3a7aSWarner Losh 84818e3e3a7aSWarner Losh 84828e3e3a7aSWarner Losh 84838e3e3a7aSWarner Losh 84848e3e3a7aSWarner Losh<p> 84858e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> 84868e3e3a7aSWarner LoshLooks for the first <em>match</em> of 84878e3e3a7aSWarner Losh<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 84888e3e3a7aSWarner LoshIf it finds one, then <code>match</code> returns 84898e3e3a7aSWarner Loshthe captures from the pattern; 84908e3e3a7aSWarner Loshotherwise it returns <b>nil</b>. 84918e3e3a7aSWarner LoshIf <code>pattern</code> specifies no captures, 84928e3e3a7aSWarner Loshthen the whole match is returned. 84938e3e3a7aSWarner LoshA third, optional numeric argument <code>init</code> specifies 84948e3e3a7aSWarner Loshwhere to start the search; 84958e3e3a7aSWarner Loshits default value is 1 and can be negative. 84968e3e3a7aSWarner Losh 84978e3e3a7aSWarner Losh 84988e3e3a7aSWarner Losh 84998e3e3a7aSWarner Losh 85008e3e3a7aSWarner Losh<p> 85018e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, ···)</code></a></h3> 85028e3e3a7aSWarner Losh 85038e3e3a7aSWarner Losh 85048e3e3a7aSWarner Losh<p> 85058e3e3a7aSWarner LoshReturns a binary string containing the values <code>v1</code>, <code>v2</code>, etc. 85068e3e3a7aSWarner Loshpacked (that is, serialized in binary form) 85078e3e3a7aSWarner Loshaccording to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 85088e3e3a7aSWarner Losh 85098e3e3a7aSWarner Losh 85108e3e3a7aSWarner Losh 85118e3e3a7aSWarner Losh 85128e3e3a7aSWarner Losh<p> 85138e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3> 85148e3e3a7aSWarner Losh 85158e3e3a7aSWarner Losh 85168e3e3a7aSWarner Losh<p> 85178e3e3a7aSWarner LoshReturns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a> 85188e3e3a7aSWarner Loshwith the given format. 85198e3e3a7aSWarner LoshThe format string cannot have the variable-length options 85208e3e3a7aSWarner Losh'<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">§6.4.2</a>). 85218e3e3a7aSWarner Losh 85228e3e3a7aSWarner Losh 85238e3e3a7aSWarner Losh 85248e3e3a7aSWarner Losh 85258e3e3a7aSWarner Losh<p> 85268e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3> 85278e3e3a7aSWarner LoshReturns a string that is the concatenation of <code>n</code> copies of 85288e3e3a7aSWarner Loshthe string <code>s</code> separated by the string <code>sep</code>. 85298e3e3a7aSWarner LoshThe default value for <code>sep</code> is the empty string 85308e3e3a7aSWarner Losh(that is, no separator). 85318e3e3a7aSWarner LoshReturns the empty string if <code>n</code> is not positive. 85328e3e3a7aSWarner Losh 85338e3e3a7aSWarner Losh 85348e3e3a7aSWarner Losh<p> 85358e3e3a7aSWarner Losh(Note that it is very easy to exhaust the memory of your machine 85368e3e3a7aSWarner Loshwith a single call to this function.) 85378e3e3a7aSWarner Losh 85388e3e3a7aSWarner Losh 85398e3e3a7aSWarner Losh 85408e3e3a7aSWarner Losh 85418e3e3a7aSWarner Losh<p> 85428e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> 85438e3e3a7aSWarner LoshReturns a string that is the string <code>s</code> reversed. 85448e3e3a7aSWarner Losh 85458e3e3a7aSWarner Losh 85468e3e3a7aSWarner Losh 85478e3e3a7aSWarner Losh 85488e3e3a7aSWarner Losh<p> 85498e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> 85508e3e3a7aSWarner LoshReturns the substring of <code>s</code> that 85518e3e3a7aSWarner Loshstarts at <code>i</code> and continues until <code>j</code>; 85528e3e3a7aSWarner Losh<code>i</code> and <code>j</code> can be negative. 85538e3e3a7aSWarner LoshIf <code>j</code> is absent, then it is assumed to be equal to -1 85548e3e3a7aSWarner Losh(which is the same as the string length). 85558e3e3a7aSWarner LoshIn particular, 85568e3e3a7aSWarner Loshthe call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 85578e3e3a7aSWarner Loshwith length <code>j</code>, 85588e3e3a7aSWarner Loshand <code>string.sub(s, -i)</code> (for a positive <code>i</code>) 85598e3e3a7aSWarner Loshreturns a suffix of <code>s</code> 85608e3e3a7aSWarner Loshwith length <code>i</code>. 85618e3e3a7aSWarner Losh 85628e3e3a7aSWarner Losh 85638e3e3a7aSWarner Losh<p> 85648e3e3a7aSWarner LoshIf, after the translation of negative indices, 85658e3e3a7aSWarner Losh<code>i</code> is less than 1, 85668e3e3a7aSWarner Loshit is corrected to 1. 85678e3e3a7aSWarner LoshIf <code>j</code> is greater than the string length, 85688e3e3a7aSWarner Loshit is corrected to that length. 85698e3e3a7aSWarner LoshIf, after these corrections, 85708e3e3a7aSWarner Losh<code>i</code> is greater than <code>j</code>, 85718e3e3a7aSWarner Loshthe function returns the empty string. 85728e3e3a7aSWarner Losh 85738e3e3a7aSWarner Losh 85748e3e3a7aSWarner Losh 85758e3e3a7aSWarner Losh 85768e3e3a7aSWarner Losh<p> 85778e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3> 85788e3e3a7aSWarner Losh 85798e3e3a7aSWarner Losh 85808e3e3a7aSWarner Losh<p> 85818e3e3a7aSWarner LoshReturns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>) 85828e3e3a7aSWarner Loshaccording to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 85838e3e3a7aSWarner LoshAn optional <code>pos</code> marks where 85848e3e3a7aSWarner Loshto start reading in <code>s</code> (default is 1). 85858e3e3a7aSWarner LoshAfter the read values, 85868e3e3a7aSWarner Loshthis function also returns the index of the first unread byte in <code>s</code>. 85878e3e3a7aSWarner Losh 85888e3e3a7aSWarner Losh 85898e3e3a7aSWarner Losh 85908e3e3a7aSWarner Losh 85918e3e3a7aSWarner Losh<p> 85928e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> 85938e3e3a7aSWarner LoshReceives a string and returns a copy of this string with all 85948e3e3a7aSWarner Loshlowercase letters changed to uppercase. 85958e3e3a7aSWarner LoshAll other characters are left unchanged. 85968e3e3a7aSWarner LoshThe definition of what a lowercase letter is depends on the current locale. 85978e3e3a7aSWarner Losh 85988e3e3a7aSWarner Losh 85998e3e3a7aSWarner Losh 86008e3e3a7aSWarner Losh 86018e3e3a7aSWarner Losh 86028e3e3a7aSWarner Losh<h3>6.4.1 – <a name="6.4.1">Patterns</a></h3> 86038e3e3a7aSWarner Losh 86048e3e3a7aSWarner Losh<p> 86058e3e3a7aSWarner LoshPatterns in Lua are described by regular strings, 86068e3e3a7aSWarner Loshwhich are interpreted as patterns by the pattern-matching functions 86078e3e3a7aSWarner Losh<a href="#pdf-string.find"><code>string.find</code></a>, 86088e3e3a7aSWarner Losh<a href="#pdf-string.gmatch"><code>string.gmatch</code></a>, 86098e3e3a7aSWarner Losh<a href="#pdf-string.gsub"><code>string.gsub</code></a>, 86108e3e3a7aSWarner Loshand <a href="#pdf-string.match"><code>string.match</code></a>. 86118e3e3a7aSWarner LoshThis section describes the syntax and the meaning 86128e3e3a7aSWarner Losh(that is, what they match) of these strings. 86138e3e3a7aSWarner Losh 86148e3e3a7aSWarner Losh 86158e3e3a7aSWarner Losh 86168e3e3a7aSWarner Losh<h4>Character Class:</h4><p> 86178e3e3a7aSWarner LoshA <em>character class</em> is used to represent a set of characters. 86188e3e3a7aSWarner LoshThe following combinations are allowed in describing a character class: 86198e3e3a7aSWarner Losh 86208e3e3a7aSWarner Losh<ul> 86218e3e3a7aSWarner Losh 86228e3e3a7aSWarner Losh<li><b><em>x</em>: </b> 86238e3e3a7aSWarner Losh(where <em>x</em> is not one of the <em>magic characters</em> 86248e3e3a7aSWarner Losh<code>^$()%.[]*+-?</code>) 86258e3e3a7aSWarner Loshrepresents the character <em>x</em> itself. 86268e3e3a7aSWarner Losh</li> 86278e3e3a7aSWarner Losh 86288e3e3a7aSWarner Losh<li><b><code>.</code>: </b> (a dot) represents all characters.</li> 86298e3e3a7aSWarner Losh 86308e3e3a7aSWarner Losh<li><b><code>%a</code>: </b> represents all letters.</li> 86318e3e3a7aSWarner Losh 86328e3e3a7aSWarner Losh<li><b><code>%c</code>: </b> represents all control characters.</li> 86338e3e3a7aSWarner Losh 86348e3e3a7aSWarner Losh<li><b><code>%d</code>: </b> represents all digits.</li> 86358e3e3a7aSWarner Losh 86368e3e3a7aSWarner Losh<li><b><code>%g</code>: </b> represents all printable characters except space.</li> 86378e3e3a7aSWarner Losh 86388e3e3a7aSWarner Losh<li><b><code>%l</code>: </b> represents all lowercase letters.</li> 86398e3e3a7aSWarner Losh 86408e3e3a7aSWarner Losh<li><b><code>%p</code>: </b> represents all punctuation characters.</li> 86418e3e3a7aSWarner Losh 86428e3e3a7aSWarner Losh<li><b><code>%s</code>: </b> represents all space characters.</li> 86438e3e3a7aSWarner Losh 86448e3e3a7aSWarner Losh<li><b><code>%u</code>: </b> represents all uppercase letters.</li> 86458e3e3a7aSWarner Losh 86468e3e3a7aSWarner Losh<li><b><code>%w</code>: </b> represents all alphanumeric characters.</li> 86478e3e3a7aSWarner Losh 86488e3e3a7aSWarner Losh<li><b><code>%x</code>: </b> represents all hexadecimal digits.</li> 86498e3e3a7aSWarner Losh 86508e3e3a7aSWarner Losh<li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character) 86518e3e3a7aSWarner Loshrepresents the character <em>x</em>. 86528e3e3a7aSWarner LoshThis is the standard way to escape the magic characters. 86538e3e3a7aSWarner LoshAny non-alphanumeric character 86548e3e3a7aSWarner Losh(including all punctuation characters, even the non-magical) 86558e3e3a7aSWarner Loshcan be preceded by a '<code>%</code>' 86568e3e3a7aSWarner Loshwhen used to represent itself in a pattern. 86578e3e3a7aSWarner Losh</li> 86588e3e3a7aSWarner Losh 86598e3e3a7aSWarner Losh<li><b><code>[<em>set</em>]</code>: </b> 86608e3e3a7aSWarner Loshrepresents the class which is the union of all 86618e3e3a7aSWarner Loshcharacters in <em>set</em>. 86628e3e3a7aSWarner LoshA range of characters can be specified by 86638e3e3a7aSWarner Loshseparating the end characters of the range, 86648e3e3a7aSWarner Loshin ascending order, with a '<code>-</code>'. 86658e3e3a7aSWarner LoshAll classes <code>%</code><em>x</em> described above can also be used as 86668e3e3a7aSWarner Loshcomponents in <em>set</em>. 86678e3e3a7aSWarner LoshAll other characters in <em>set</em> represent themselves. 86688e3e3a7aSWarner LoshFor example, <code>[%w_]</code> (or <code>[_%w]</code>) 86698e3e3a7aSWarner Loshrepresents all alphanumeric characters plus the underscore, 86708e3e3a7aSWarner Losh<code>[0-7]</code> represents the octal digits, 86718e3e3a7aSWarner Loshand <code>[0-7%l%-]</code> represents the octal digits plus 86728e3e3a7aSWarner Loshthe lowercase letters plus the '<code>-</code>' character. 86738e3e3a7aSWarner Losh 86748e3e3a7aSWarner Losh 86758e3e3a7aSWarner Losh<p> 86768e3e3a7aSWarner LoshYou can put a closing square bracket in a set 86778e3e3a7aSWarner Loshby positioning it as the first character in the set. 8678*e112e9d2SKyle EvansYou can put a hyphen in a set 86798e3e3a7aSWarner Loshby positioning it as the first or the last character in the set. 86808e3e3a7aSWarner Losh(You can also use an escape for both cases.) 86818e3e3a7aSWarner Losh 86828e3e3a7aSWarner Losh 86838e3e3a7aSWarner Losh<p> 86848e3e3a7aSWarner LoshThe interaction between ranges and classes is not defined. 86858e3e3a7aSWarner LoshTherefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> 86868e3e3a7aSWarner Loshhave no meaning. 86878e3e3a7aSWarner Losh</li> 86888e3e3a7aSWarner Losh 86898e3e3a7aSWarner Losh<li><b><code>[^<em>set</em>]</code>: </b> 86908e3e3a7aSWarner Loshrepresents the complement of <em>set</em>, 86918e3e3a7aSWarner Loshwhere <em>set</em> is interpreted as above. 86928e3e3a7aSWarner Losh</li> 86938e3e3a7aSWarner Losh 86948e3e3a7aSWarner Losh</ul><p> 86958e3e3a7aSWarner LoshFor all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), 86968e3e3a7aSWarner Loshthe corresponding uppercase letter represents the complement of the class. 86978e3e3a7aSWarner LoshFor instance, <code>%S</code> represents all non-space characters. 86988e3e3a7aSWarner Losh 86998e3e3a7aSWarner Losh 87008e3e3a7aSWarner Losh<p> 87018e3e3a7aSWarner LoshThe definitions of letter, space, and other character groups 87028e3e3a7aSWarner Loshdepend on the current locale. 87038e3e3a7aSWarner LoshIn particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. 87048e3e3a7aSWarner Losh 87058e3e3a7aSWarner Losh 87068e3e3a7aSWarner Losh 87078e3e3a7aSWarner Losh 87088e3e3a7aSWarner Losh 87098e3e3a7aSWarner Losh<h4>Pattern Item:</h4><p> 87108e3e3a7aSWarner LoshA <em>pattern item</em> can be 87118e3e3a7aSWarner Losh 87128e3e3a7aSWarner Losh<ul> 87138e3e3a7aSWarner Losh 87148e3e3a7aSWarner Losh<li> 87158e3e3a7aSWarner Losha single character class, 87168e3e3a7aSWarner Loshwhich matches any single character in the class; 87178e3e3a7aSWarner Losh</li> 87188e3e3a7aSWarner Losh 87198e3e3a7aSWarner Losh<li> 87208e3e3a7aSWarner Losha single character class followed by '<code>*</code>', 87218e3e3a7aSWarner Loshwhich matches zero or more repetitions of characters in the class. 87228e3e3a7aSWarner LoshThese repetition items will always match the longest possible sequence; 87238e3e3a7aSWarner Losh</li> 87248e3e3a7aSWarner Losh 87258e3e3a7aSWarner Losh<li> 87268e3e3a7aSWarner Losha single character class followed by '<code>+</code>', 87278e3e3a7aSWarner Loshwhich matches one or more repetitions of characters in the class. 87288e3e3a7aSWarner LoshThese repetition items will always match the longest possible sequence; 87298e3e3a7aSWarner Losh</li> 87308e3e3a7aSWarner Losh 87318e3e3a7aSWarner Losh<li> 87328e3e3a7aSWarner Losha single character class followed by '<code>-</code>', 87338e3e3a7aSWarner Loshwhich also matches zero or more repetitions of characters in the class. 87348e3e3a7aSWarner LoshUnlike '<code>*</code>', 87358e3e3a7aSWarner Loshthese repetition items will always match the shortest possible sequence; 87368e3e3a7aSWarner Losh</li> 87378e3e3a7aSWarner Losh 87388e3e3a7aSWarner Losh<li> 87398e3e3a7aSWarner Losha single character class followed by '<code>?</code>', 87408e3e3a7aSWarner Loshwhich matches zero or one occurrence of a character in the class. 87418e3e3a7aSWarner LoshIt always matches one occurrence if possible; 87428e3e3a7aSWarner Losh</li> 87438e3e3a7aSWarner Losh 87448e3e3a7aSWarner Losh<li> 87458e3e3a7aSWarner Losh<code>%<em>n</em></code>, for <em>n</em> between 1 and 9; 87468e3e3a7aSWarner Loshsuch item matches a substring equal to the <em>n</em>-th captured string 87478e3e3a7aSWarner Losh(see below); 87488e3e3a7aSWarner Losh</li> 87498e3e3a7aSWarner Losh 87508e3e3a7aSWarner Losh<li> 87518e3e3a7aSWarner Losh<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; 87528e3e3a7aSWarner Loshsuch item matches strings that start with <em>x</em>, end with <em>y</em>, 87538e3e3a7aSWarner Loshand where the <em>x</em> and <em>y</em> are <em>balanced</em>. 87548e3e3a7aSWarner LoshThis means that, if one reads the string from left to right, 87558e3e3a7aSWarner Loshcounting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, 87568e3e3a7aSWarner Loshthe ending <em>y</em> is the first <em>y</em> where the count reaches 0. 87578e3e3a7aSWarner LoshFor instance, the item <code>%b()</code> matches expressions with 87588e3e3a7aSWarner Loshbalanced parentheses. 87598e3e3a7aSWarner Losh</li> 87608e3e3a7aSWarner Losh 87618e3e3a7aSWarner Losh<li> 87628e3e3a7aSWarner Losh<code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>; 87638e3e3a7aSWarner Loshsuch item matches an empty string at any position such that 87648e3e3a7aSWarner Loshthe next character belongs to <em>set</em> 87658e3e3a7aSWarner Loshand the previous character does not belong to <em>set</em>. 87668e3e3a7aSWarner LoshThe set <em>set</em> is interpreted as previously described. 87678e3e3a7aSWarner LoshThe beginning and the end of the subject are handled as if 87688e3e3a7aSWarner Loshthey were the character '<code>\0</code>'. 87698e3e3a7aSWarner Losh</li> 87708e3e3a7aSWarner Losh 87718e3e3a7aSWarner Losh</ul> 87728e3e3a7aSWarner Losh 87738e3e3a7aSWarner Losh 87748e3e3a7aSWarner Losh 87758e3e3a7aSWarner Losh 87768e3e3a7aSWarner Losh<h4>Pattern:</h4><p> 87778e3e3a7aSWarner LoshA <em>pattern</em> is a sequence of pattern items. 87788e3e3a7aSWarner LoshA caret '<code>^</code>' at the beginning of a pattern anchors the match at the 87798e3e3a7aSWarner Loshbeginning of the subject string. 87808e3e3a7aSWarner LoshA '<code>$</code>' at the end of a pattern anchors the match at the 87818e3e3a7aSWarner Loshend of the subject string. 87828e3e3a7aSWarner LoshAt other positions, 87838e3e3a7aSWarner Losh'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. 87848e3e3a7aSWarner Losh 87858e3e3a7aSWarner Losh 87868e3e3a7aSWarner Losh 87878e3e3a7aSWarner Losh 87888e3e3a7aSWarner Losh 87898e3e3a7aSWarner Losh<h4>Captures:</h4><p> 87908e3e3a7aSWarner LoshA pattern can contain sub-patterns enclosed in parentheses; 87918e3e3a7aSWarner Loshthey describe <em>captures</em>. 87928e3e3a7aSWarner LoshWhen a match succeeds, the substrings of the subject string 87938e3e3a7aSWarner Loshthat match captures are stored (<em>captured</em>) for future use. 87948e3e3a7aSWarner LoshCaptures are numbered according to their left parentheses. 87958e3e3a7aSWarner LoshFor instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, 87968e3e3a7aSWarner Loshthe part of the string matching <code>"a*(.)%w(%s*)"</code> is 87978e3e3a7aSWarner Loshstored as the first capture (and therefore has number 1); 87988e3e3a7aSWarner Loshthe character matching "<code>.</code>" is captured with number 2, 87998e3e3a7aSWarner Loshand the part matching "<code>%s*</code>" has number 3. 88008e3e3a7aSWarner Losh 88018e3e3a7aSWarner Losh 88028e3e3a7aSWarner Losh<p> 88038e3e3a7aSWarner LoshAs a special case, the empty capture <code>()</code> captures 88048e3e3a7aSWarner Loshthe current string position (a number). 88058e3e3a7aSWarner LoshFor instance, if we apply the pattern <code>"()aa()"</code> on the 88068e3e3a7aSWarner Loshstring <code>"flaaap"</code>, there will be two captures: 3 and 5. 88078e3e3a7aSWarner Losh 88088e3e3a7aSWarner Losh 88098e3e3a7aSWarner Losh 88108e3e3a7aSWarner Losh 88118e3e3a7aSWarner Losh 88128e3e3a7aSWarner Losh 88138e3e3a7aSWarner Losh 88148e3e3a7aSWarner Losh<h3>6.4.2 – <a name="6.4.2">Format Strings for Pack and Unpack</a></h3> 88158e3e3a7aSWarner Losh 88168e3e3a7aSWarner Losh<p> 88178e3e3a7aSWarner LoshThe first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>, 88188e3e3a7aSWarner Losh<a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a> 88198e3e3a7aSWarner Loshis a format string, 88208e3e3a7aSWarner Loshwhich describes the layout of the structure being created or read. 88218e3e3a7aSWarner Losh 88228e3e3a7aSWarner Losh 88238e3e3a7aSWarner Losh<p> 88248e3e3a7aSWarner LoshA format string is a sequence of conversion options. 88258e3e3a7aSWarner LoshThe conversion options are as follows: 88268e3e3a7aSWarner Losh 88278e3e3a7aSWarner Losh<ul> 88288e3e3a7aSWarner Losh<li><b><code><</code>: </b>sets little endian</li> 88298e3e3a7aSWarner Losh<li><b><code>></code>: </b>sets big endian</li> 88308e3e3a7aSWarner Losh<li><b><code>=</code>: </b>sets native endian</li> 88318e3e3a7aSWarner Losh<li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code> 88328e3e3a7aSWarner Losh(default is native alignment)</li> 88338e3e3a7aSWarner Losh<li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li> 88348e3e3a7aSWarner Losh<li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li> 88358e3e3a7aSWarner Losh<li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li> 88368e3e3a7aSWarner Losh<li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li> 88378e3e3a7aSWarner Losh<li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li> 88388e3e3a7aSWarner Losh<li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li> 88398e3e3a7aSWarner Losh<li><b><code>j</code>: </b>a <code>lua_Integer</code></li> 88408e3e3a7aSWarner Losh<li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li> 88418e3e3a7aSWarner Losh<li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li> 88428e3e3a7aSWarner Losh<li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes 88438e3e3a7aSWarner Losh(default is native size)</li> 88448e3e3a7aSWarner Losh<li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes 88458e3e3a7aSWarner Losh(default is native size)</li> 88468e3e3a7aSWarner Losh<li><b><code>f</code>: </b>a <code>float</code> (native size)</li> 88478e3e3a7aSWarner Losh<li><b><code>d</code>: </b>a <code>double</code> (native size)</li> 88488e3e3a7aSWarner Losh<li><b><code>n</code>: </b>a <code>lua_Number</code></li> 88498e3e3a7aSWarner Losh<li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li> 88508e3e3a7aSWarner Losh<li><b><code>z</code>: </b>a zero-terminated string</li> 88518e3e3a7aSWarner Losh<li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length 88528e3e3a7aSWarner Loshcoded as an unsigned integer with <code>n</code> bytes 88538e3e3a7aSWarner Losh(default is a <code>size_t</code>)</li> 88548e3e3a7aSWarner Losh<li><b><code>x</code>: </b>one byte of padding</li> 88558e3e3a7aSWarner Losh<li><b><code>X<em>op</em></code>: </b>an empty item that aligns 88568e3e3a7aSWarner Loshaccording to option <code>op</code> 88578e3e3a7aSWarner Losh(which is otherwise ignored)</li> 88588e3e3a7aSWarner Losh<li><b>'<code> </code>': </b>(empty space) ignored</li> 88598e3e3a7aSWarner Losh</ul><p> 88608e3e3a7aSWarner Losh(A "<code>[<em>n</em>]</code>" means an optional integral numeral.) 88618e3e3a7aSWarner LoshExcept for padding, spaces, and configurations 88628e3e3a7aSWarner Losh(options "<code>xX <=>!</code>"), 88638e3e3a7aSWarner Losheach option corresponds to an argument (in <a href="#pdf-string.pack"><code>string.pack</code></a>) 88648e3e3a7aSWarner Loshor a result (in <a href="#pdf-string.unpack"><code>string.unpack</code></a>). 88658e3e3a7aSWarner Losh 88668e3e3a7aSWarner Losh 88678e3e3a7aSWarner Losh<p> 88688e3e3a7aSWarner LoshFor 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>", 88698e3e3a7aSWarner Losh<code>n</code> can be any integer between 1 and 16. 88708e3e3a7aSWarner LoshAll integral options check overflows; 88718e3e3a7aSWarner Losh<a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size; 88728e3e3a7aSWarner Losh<a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer. 88738e3e3a7aSWarner Losh 88748e3e3a7aSWarner Losh 88758e3e3a7aSWarner Losh<p> 88768e3e3a7aSWarner LoshAny format string starts as if prefixed by "<code>!1=</code>", 88778e3e3a7aSWarner Loshthat is, 88788e3e3a7aSWarner Loshwith maximum alignment of 1 (no alignment) 88798e3e3a7aSWarner Loshand native endianness. 88808e3e3a7aSWarner Losh 88818e3e3a7aSWarner Losh 88828e3e3a7aSWarner Losh<p> 88838e3e3a7aSWarner LoshAlignment works as follows: 88848e3e3a7aSWarner LoshFor each option, 88858e3e3a7aSWarner Loshthe format gets extra padding until the data starts 88868e3e3a7aSWarner Loshat an offset that is a multiple of the minimum between the 88878e3e3a7aSWarner Loshoption size and the maximum alignment; 88888e3e3a7aSWarner Loshthis minimum must be a power of 2. 88898e3e3a7aSWarner LoshOptions "<code>c</code>" and "<code>z</code>" are not aligned; 88908e3e3a7aSWarner Loshoption "<code>s</code>" follows the alignment of its starting integer. 88918e3e3a7aSWarner Losh 88928e3e3a7aSWarner Losh 88938e3e3a7aSWarner Losh<p> 88948e3e3a7aSWarner LoshAll padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a> 88958e3e3a7aSWarner Losh(and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>). 88968e3e3a7aSWarner Losh 88978e3e3a7aSWarner Losh 88988e3e3a7aSWarner Losh 88998e3e3a7aSWarner Losh 89008e3e3a7aSWarner Losh 89018e3e3a7aSWarner Losh 89028e3e3a7aSWarner Losh 89038e3e3a7aSWarner Losh<h2>6.5 – <a name="6.5">UTF-8 Support</a></h2> 89048e3e3a7aSWarner Losh 89058e3e3a7aSWarner Losh<p> 89068e3e3a7aSWarner LoshThis library provides basic support for UTF-8 encoding. 89078e3e3a7aSWarner LoshIt provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>. 89088e3e3a7aSWarner LoshThis library does not provide any support for Unicode other 89098e3e3a7aSWarner Loshthan the handling of the encoding. 89108e3e3a7aSWarner LoshAny operation that needs the meaning of a character, 89118e3e3a7aSWarner Loshsuch as character classification, is outside its scope. 89128e3e3a7aSWarner Losh 89138e3e3a7aSWarner Losh 89148e3e3a7aSWarner Losh<p> 89158e3e3a7aSWarner LoshUnless stated otherwise, 89168e3e3a7aSWarner Loshall functions that expect a byte position as a parameter 89178e3e3a7aSWarner Loshassume that the given position is either the start of a byte sequence 89188e3e3a7aSWarner Loshor one plus the length of the subject string. 89198e3e3a7aSWarner LoshAs in the string library, 89208e3e3a7aSWarner Loshnegative indices count from the end of the string. 89218e3e3a7aSWarner Losh 89228e3e3a7aSWarner Losh 89238e3e3a7aSWarner Losh<p> 89248e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3> 89258e3e3a7aSWarner LoshReceives zero or more integers, 89268e3e3a7aSWarner Loshconverts each one to its corresponding UTF-8 byte sequence 89278e3e3a7aSWarner Loshand returns a string with the concatenation of all these sequences. 89288e3e3a7aSWarner Losh 89298e3e3a7aSWarner Losh 89308e3e3a7aSWarner Losh 89318e3e3a7aSWarner Losh 89328e3e3a7aSWarner Losh<p> 89338e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3> 89348e3e3a7aSWarner LoshThe pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>" 89358e3e3a7aSWarner Losh(see <a href="#6.4.1">§6.4.1</a>), 89368e3e3a7aSWarner Loshwhich matches exactly one UTF-8 byte sequence, 89378e3e3a7aSWarner Loshassuming that the subject is a valid UTF-8 string. 89388e3e3a7aSWarner Losh 89398e3e3a7aSWarner Losh 89408e3e3a7aSWarner Losh 89418e3e3a7aSWarner Losh 89428e3e3a7aSWarner Losh<p> 89438e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3> 89448e3e3a7aSWarner Losh 89458e3e3a7aSWarner Losh 89468e3e3a7aSWarner Losh<p> 89478e3e3a7aSWarner LoshReturns values so that the construction 89488e3e3a7aSWarner Losh 89498e3e3a7aSWarner Losh<pre> 89508e3e3a7aSWarner Losh for p, c in utf8.codes(s) do <em>body</em> end 89518e3e3a7aSWarner Losh</pre><p> 89528e3e3a7aSWarner Loshwill iterate over all characters in string <code>s</code>, 89538e3e3a7aSWarner Loshwith <code>p</code> being the position (in bytes) and <code>c</code> the code point 89548e3e3a7aSWarner Loshof each character. 89558e3e3a7aSWarner LoshIt raises an error if it meets any invalid byte sequence. 89568e3e3a7aSWarner Losh 89578e3e3a7aSWarner Losh 89588e3e3a7aSWarner Losh 89598e3e3a7aSWarner Losh 89608e3e3a7aSWarner Losh<p> 89618e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3> 89628e3e3a7aSWarner LoshReturns the codepoints (as integers) from all characters in <code>s</code> 89638e3e3a7aSWarner Loshthat start between byte position <code>i</code> and <code>j</code> (both included). 89648e3e3a7aSWarner LoshThe default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>. 89658e3e3a7aSWarner LoshIt raises an error if it meets any invalid byte sequence. 89668e3e3a7aSWarner Losh 89678e3e3a7aSWarner Losh 89688e3e3a7aSWarner Losh 89698e3e3a7aSWarner Losh 89708e3e3a7aSWarner Losh<p> 89718e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j]])</code></a></h3> 89728e3e3a7aSWarner LoshReturns the number of UTF-8 characters in string <code>s</code> 89738e3e3a7aSWarner Loshthat start between positions <code>i</code> and <code>j</code> (both inclusive). 89748e3e3a7aSWarner LoshThe default for <code>i</code> is 1 and for <code>j</code> is -1. 89758e3e3a7aSWarner LoshIf it finds any invalid byte sequence, 89768e3e3a7aSWarner Loshreturns a false value plus the position of the first invalid byte. 89778e3e3a7aSWarner Losh 89788e3e3a7aSWarner Losh 89798e3e3a7aSWarner Losh 89808e3e3a7aSWarner Losh 89818e3e3a7aSWarner Losh<p> 89828e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3> 89838e3e3a7aSWarner LoshReturns the position (in bytes) where the encoding of the 89848e3e3a7aSWarner Losh<code>n</code>-th character of <code>s</code> 89858e3e3a7aSWarner Losh(counting from position <code>i</code>) starts. 89868e3e3a7aSWarner LoshA negative <code>n</code> gets characters before position <code>i</code>. 89878e3e3a7aSWarner LoshThe default for <code>i</code> is 1 when <code>n</code> is non-negative 89888e3e3a7aSWarner Loshand <code>#s + 1</code> otherwise, 89898e3e3a7aSWarner Loshso that <code>utf8.offset(s, -n)</code> gets the offset of the 89908e3e3a7aSWarner Losh<code>n</code>-th character from the end of the string. 89918e3e3a7aSWarner LoshIf the specified character is neither in the subject 89928e3e3a7aSWarner Loshnor right after its end, 89938e3e3a7aSWarner Loshthe function returns <b>nil</b>. 89948e3e3a7aSWarner Losh 89958e3e3a7aSWarner Losh 89968e3e3a7aSWarner Losh<p> 89978e3e3a7aSWarner LoshAs a special case, 89988e3e3a7aSWarner Loshwhen <code>n</code> is 0 the function returns the start of the encoding 89998e3e3a7aSWarner Loshof the character that contains the <code>i</code>-th byte of <code>s</code>. 90008e3e3a7aSWarner Losh 90018e3e3a7aSWarner Losh 90028e3e3a7aSWarner Losh<p> 90038e3e3a7aSWarner LoshThis function assumes that <code>s</code> is a valid UTF-8 string. 90048e3e3a7aSWarner Losh 90058e3e3a7aSWarner Losh 90068e3e3a7aSWarner Losh 90078e3e3a7aSWarner Losh 90088e3e3a7aSWarner Losh 90098e3e3a7aSWarner Losh 90108e3e3a7aSWarner Losh 90118e3e3a7aSWarner Losh<h2>6.6 – <a name="6.6">Table Manipulation</a></h2> 90128e3e3a7aSWarner Losh 90138e3e3a7aSWarner Losh<p> 90148e3e3a7aSWarner LoshThis library provides generic functions for table manipulation. 90158e3e3a7aSWarner LoshIt provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. 90168e3e3a7aSWarner Losh 90178e3e3a7aSWarner Losh 90188e3e3a7aSWarner Losh<p> 90198e3e3a7aSWarner LoshRemember that, whenever an operation needs the length of a table, 90208e3e3a7aSWarner Loshall caveats about the length operator apply (see <a href="#3.4.7">§3.4.7</a>). 90218e3e3a7aSWarner LoshAll functions ignore non-numeric keys 90228e3e3a7aSWarner Loshin the tables given as arguments. 90238e3e3a7aSWarner Losh 90248e3e3a7aSWarner Losh 90258e3e3a7aSWarner Losh<p> 90268e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3> 90278e3e3a7aSWarner Losh 90288e3e3a7aSWarner Losh 90298e3e3a7aSWarner Losh<p> 90308e3e3a7aSWarner LoshGiven a list where all elements are strings or numbers, 90318e3e3a7aSWarner Loshreturns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>. 90328e3e3a7aSWarner LoshThe default value for <code>sep</code> is the empty string, 90338e3e3a7aSWarner Loshthe default for <code>i</code> is 1, 90348e3e3a7aSWarner Loshand the default for <code>j</code> is <code>#list</code>. 90358e3e3a7aSWarner LoshIf <code>i</code> is greater than <code>j</code>, returns the empty string. 90368e3e3a7aSWarner Losh 90378e3e3a7aSWarner Losh 90388e3e3a7aSWarner Losh 90398e3e3a7aSWarner Losh 90408e3e3a7aSWarner Losh<p> 90418e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3> 90428e3e3a7aSWarner Losh 90438e3e3a7aSWarner Losh 90448e3e3a7aSWarner Losh<p> 90458e3e3a7aSWarner LoshInserts element <code>value</code> at position <code>pos</code> in <code>list</code>, 90468e3e3a7aSWarner Loshshifting up the elements 90478e3e3a7aSWarner Losh<code>list[pos], list[pos+1], ···, list[#list]</code>. 90488e3e3a7aSWarner LoshThe default value for <code>pos</code> is <code>#list+1</code>, 90498e3e3a7aSWarner Loshso that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end 90508e3e3a7aSWarner Loshof list <code>t</code>. 90518e3e3a7aSWarner Losh 90528e3e3a7aSWarner Losh 90538e3e3a7aSWarner Losh 90548e3e3a7aSWarner Losh 90558e3e3a7aSWarner Losh<p> 90568e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3> 90578e3e3a7aSWarner Losh 90588e3e3a7aSWarner Losh 90598e3e3a7aSWarner Losh<p> 90608e3e3a7aSWarner LoshMoves elements from table <code>a1</code> to table <code>a2</code>, 90618e3e3a7aSWarner Loshperforming the equivalent to the following 90628e3e3a7aSWarner Loshmultiple assignment: 90638e3e3a7aSWarner Losh<code>a2[t],··· = a1[f],···,a1[e]</code>. 90648e3e3a7aSWarner LoshThe default for <code>a2</code> is <code>a1</code>. 90658e3e3a7aSWarner LoshThe destination range can overlap with the source range. 90668e3e3a7aSWarner LoshThe number of elements to be moved must fit in a Lua integer. 90678e3e3a7aSWarner Losh 90688e3e3a7aSWarner Losh 90698e3e3a7aSWarner Losh<p> 90708e3e3a7aSWarner LoshReturns the destination table <code>a2</code>. 90718e3e3a7aSWarner Losh 90728e3e3a7aSWarner Losh 90738e3e3a7aSWarner Losh 90748e3e3a7aSWarner Losh 90758e3e3a7aSWarner Losh<p> 90768e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3> 90778e3e3a7aSWarner Losh 90788e3e3a7aSWarner Losh 90798e3e3a7aSWarner Losh<p> 9080*e112e9d2SKyle EvansReturns a new table with all arguments stored into keys 1, 2, etc. 9081*e112e9d2SKyle Evansand with a field "<code>n</code>" with the total number of arguments. 90828e3e3a7aSWarner LoshNote that the resulting table may not be a sequence. 90838e3e3a7aSWarner Losh 90848e3e3a7aSWarner Losh 90858e3e3a7aSWarner Losh 90868e3e3a7aSWarner Losh 90878e3e3a7aSWarner Losh<p> 90888e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3> 90898e3e3a7aSWarner Losh 90908e3e3a7aSWarner Losh 90918e3e3a7aSWarner Losh<p> 90928e3e3a7aSWarner LoshRemoves from <code>list</code> the element at position <code>pos</code>, 90938e3e3a7aSWarner Loshreturning the value of the removed element. 90948e3e3a7aSWarner LoshWhen <code>pos</code> is an integer between 1 and <code>#list</code>, 90958e3e3a7aSWarner Loshit shifts down the elements 90968e3e3a7aSWarner Losh<code>list[pos+1], list[pos+2], ···, list[#list]</code> 90978e3e3a7aSWarner Loshand erases element <code>list[#list]</code>; 90988e3e3a7aSWarner LoshThe index <code>pos</code> can also be 0 when <code>#list</code> is 0, 90998e3e3a7aSWarner Loshor <code>#list + 1</code>; 91008e3e3a7aSWarner Loshin those cases, the function erases the element <code>list[pos]</code>. 91018e3e3a7aSWarner Losh 91028e3e3a7aSWarner Losh 91038e3e3a7aSWarner Losh<p> 91048e3e3a7aSWarner LoshThe default value for <code>pos</code> is <code>#list</code>, 91058e3e3a7aSWarner Loshso that a call <code>table.remove(l)</code> removes the last element 91068e3e3a7aSWarner Loshof list <code>l</code>. 91078e3e3a7aSWarner Losh 91088e3e3a7aSWarner Losh 91098e3e3a7aSWarner Losh 91108e3e3a7aSWarner Losh 91118e3e3a7aSWarner Losh<p> 91128e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3> 91138e3e3a7aSWarner Losh 91148e3e3a7aSWarner Losh 91158e3e3a7aSWarner Losh<p> 91168e3e3a7aSWarner LoshSorts list elements in a given order, <em>in-place</em>, 91178e3e3a7aSWarner Loshfrom <code>list[1]</code> to <code>list[#list]</code>. 91188e3e3a7aSWarner LoshIf <code>comp</code> is given, 91198e3e3a7aSWarner Loshthen it must be a function that receives two list elements 91208e3e3a7aSWarner Loshand returns true when the first element must come 91218e3e3a7aSWarner Loshbefore the second in the final order 91228e3e3a7aSWarner Losh(so that, after the sort, 91238e3e3a7aSWarner Losh<code>i < j</code> implies <code>not comp(list[j],list[i])</code>). 91248e3e3a7aSWarner LoshIf <code>comp</code> is not given, 91258e3e3a7aSWarner Loshthen the standard Lua operator <code><</code> is used instead. 91268e3e3a7aSWarner Losh 91278e3e3a7aSWarner Losh 91288e3e3a7aSWarner Losh<p> 91298e3e3a7aSWarner LoshNote that the <code>comp</code> function must define 91308e3e3a7aSWarner Losha strict partial order over the elements in the list; 91318e3e3a7aSWarner Loshthat is, it must be asymmetric and transitive. 91328e3e3a7aSWarner LoshOtherwise, no valid sort may be possible. 91338e3e3a7aSWarner Losh 91348e3e3a7aSWarner Losh 91358e3e3a7aSWarner Losh<p> 91368e3e3a7aSWarner LoshThe sort algorithm is not stable: 91378e3e3a7aSWarner Loshelements considered equal by the given order 91388e3e3a7aSWarner Loshmay have their relative positions changed by the sort. 91398e3e3a7aSWarner Losh 91408e3e3a7aSWarner Losh 91418e3e3a7aSWarner Losh 91428e3e3a7aSWarner Losh 91438e3e3a7aSWarner Losh<p> 91448e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3> 91458e3e3a7aSWarner Losh 91468e3e3a7aSWarner Losh 91478e3e3a7aSWarner Losh<p> 91488e3e3a7aSWarner LoshReturns the elements from the given list. 91498e3e3a7aSWarner LoshThis function is equivalent to 91508e3e3a7aSWarner Losh 91518e3e3a7aSWarner Losh<pre> 91528e3e3a7aSWarner Losh return list[i], list[i+1], ···, list[j] 91538e3e3a7aSWarner Losh</pre><p> 91548e3e3a7aSWarner LoshBy default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>. 91558e3e3a7aSWarner Losh 91568e3e3a7aSWarner Losh 91578e3e3a7aSWarner Losh 91588e3e3a7aSWarner Losh 91598e3e3a7aSWarner Losh 91608e3e3a7aSWarner Losh 91618e3e3a7aSWarner Losh 91628e3e3a7aSWarner Losh<h2>6.7 – <a name="6.7">Mathematical Functions</a></h2> 91638e3e3a7aSWarner Losh 91648e3e3a7aSWarner Losh<p> 91658e3e3a7aSWarner LoshThis library provides basic mathematical functions. 91668e3e3a7aSWarner LoshIt provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>. 91678e3e3a7aSWarner LoshFunctions with the annotation "<code>integer/float</code>" give 91688e3e3a7aSWarner Loshinteger results for integer arguments 91698e3e3a7aSWarner Loshand float results for float (or mixed) arguments. 91708e3e3a7aSWarner LoshRounding functions 91718e3e3a7aSWarner Losh(<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>) 91728e3e3a7aSWarner Loshreturn an integer when the result fits in the range of an integer, 91738e3e3a7aSWarner Loshor a float otherwise. 91748e3e3a7aSWarner Losh 91758e3e3a7aSWarner Losh 91768e3e3a7aSWarner Losh<p> 91778e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> 91788e3e3a7aSWarner Losh 91798e3e3a7aSWarner Losh 91808e3e3a7aSWarner Losh<p> 91818e3e3a7aSWarner LoshReturns the absolute value of <code>x</code>. (integer/float) 91828e3e3a7aSWarner Losh 91838e3e3a7aSWarner Losh 91848e3e3a7aSWarner Losh 91858e3e3a7aSWarner Losh 91868e3e3a7aSWarner Losh<p> 91878e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> 91888e3e3a7aSWarner Losh 91898e3e3a7aSWarner Losh 91908e3e3a7aSWarner Losh<p> 91918e3e3a7aSWarner LoshReturns the arc cosine of <code>x</code> (in radians). 91928e3e3a7aSWarner Losh 91938e3e3a7aSWarner Losh 91948e3e3a7aSWarner Losh 91958e3e3a7aSWarner Losh 91968e3e3a7aSWarner Losh<p> 91978e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> 91988e3e3a7aSWarner Losh 91998e3e3a7aSWarner Losh 92008e3e3a7aSWarner Losh<p> 92018e3e3a7aSWarner LoshReturns the arc sine of <code>x</code> (in radians). 92028e3e3a7aSWarner Losh 92038e3e3a7aSWarner Losh 92048e3e3a7aSWarner Losh 92058e3e3a7aSWarner Losh 92068e3e3a7aSWarner Losh<p> 92078e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3> 92088e3e3a7aSWarner Losh 92098e3e3a7aSWarner Losh 92108e3e3a7aSWarner Losh<p> 92118e3e3a7aSWarner Losh 92128e3e3a7aSWarner LoshReturns the arc tangent of <code>y/x</code> (in radians), 9213*e112e9d2SKyle Evansbut uses the signs of both arguments to find the 92148e3e3a7aSWarner Loshquadrant of the result. 92158e3e3a7aSWarner Losh(It also handles correctly the case of <code>x</code> being zero.) 92168e3e3a7aSWarner Losh 92178e3e3a7aSWarner Losh 92188e3e3a7aSWarner Losh<p> 92198e3e3a7aSWarner LoshThe default value for <code>x</code> is 1, 92208e3e3a7aSWarner Loshso that the call <code>math.atan(y)</code> 92218e3e3a7aSWarner Loshreturns the arc tangent of <code>y</code>. 92228e3e3a7aSWarner Losh 92238e3e3a7aSWarner Losh 92248e3e3a7aSWarner Losh 92258e3e3a7aSWarner Losh 92268e3e3a7aSWarner Losh<p> 92278e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> 92288e3e3a7aSWarner Losh 92298e3e3a7aSWarner Losh 92308e3e3a7aSWarner Losh<p> 92318e3e3a7aSWarner LoshReturns the smallest integral value larger than or equal to <code>x</code>. 92328e3e3a7aSWarner Losh 92338e3e3a7aSWarner Losh 92348e3e3a7aSWarner Losh 92358e3e3a7aSWarner Losh 92368e3e3a7aSWarner Losh<p> 92378e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> 92388e3e3a7aSWarner Losh 92398e3e3a7aSWarner Losh 92408e3e3a7aSWarner Losh<p> 92418e3e3a7aSWarner LoshReturns the cosine of <code>x</code> (assumed to be in radians). 92428e3e3a7aSWarner Losh 92438e3e3a7aSWarner Losh 92448e3e3a7aSWarner Losh 92458e3e3a7aSWarner Losh 92468e3e3a7aSWarner Losh<p> 92478e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> 92488e3e3a7aSWarner Losh 92498e3e3a7aSWarner Losh 92508e3e3a7aSWarner Losh<p> 92518e3e3a7aSWarner LoshConverts the angle <code>x</code> from radians to degrees. 92528e3e3a7aSWarner Losh 92538e3e3a7aSWarner Losh 92548e3e3a7aSWarner Losh 92558e3e3a7aSWarner Losh 92568e3e3a7aSWarner Losh<p> 92578e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> 92588e3e3a7aSWarner Losh 92598e3e3a7aSWarner Losh 92608e3e3a7aSWarner Losh<p> 92618e3e3a7aSWarner LoshReturns the value <em>e<sup>x</sup></em> 92628e3e3a7aSWarner Losh(where <code>e</code> is the base of natural logarithms). 92638e3e3a7aSWarner Losh 92648e3e3a7aSWarner Losh 92658e3e3a7aSWarner Losh 92668e3e3a7aSWarner Losh 92678e3e3a7aSWarner Losh<p> 92688e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> 92698e3e3a7aSWarner Losh 92708e3e3a7aSWarner Losh 92718e3e3a7aSWarner Losh<p> 92728e3e3a7aSWarner LoshReturns the largest integral value smaller than or equal to <code>x</code>. 92738e3e3a7aSWarner Losh 92748e3e3a7aSWarner Losh 92758e3e3a7aSWarner Losh 92768e3e3a7aSWarner Losh 92778e3e3a7aSWarner Losh<p> 92788e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> 92798e3e3a7aSWarner Losh 92808e3e3a7aSWarner Losh 92818e3e3a7aSWarner Losh<p> 92828e3e3a7aSWarner LoshReturns the remainder of the division of <code>x</code> by <code>y</code> 92838e3e3a7aSWarner Loshthat rounds the quotient towards zero. (integer/float) 92848e3e3a7aSWarner Losh 92858e3e3a7aSWarner Losh 92868e3e3a7aSWarner Losh 92878e3e3a7aSWarner Losh 92888e3e3a7aSWarner Losh<p> 92898e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> 92908e3e3a7aSWarner Losh 92918e3e3a7aSWarner Losh 92928e3e3a7aSWarner Losh<p> 92938e3e3a7aSWarner LoshThe float value <code>HUGE_VAL</code>, 92948e3e3a7aSWarner Losha value larger than any other numeric value. 92958e3e3a7aSWarner Losh 92968e3e3a7aSWarner Losh 92978e3e3a7aSWarner Losh 92988e3e3a7aSWarner Losh 92998e3e3a7aSWarner Losh<p> 93008e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3> 93018e3e3a7aSWarner Losh 93028e3e3a7aSWarner Losh 93038e3e3a7aSWarner Losh<p> 93048e3e3a7aSWarner LoshReturns the logarithm of <code>x</code> in the given base. 93058e3e3a7aSWarner LoshThe default for <code>base</code> is <em>e</em> 93068e3e3a7aSWarner Losh(so that the function returns the natural logarithm of <code>x</code>). 93078e3e3a7aSWarner Losh 93088e3e3a7aSWarner Losh 93098e3e3a7aSWarner Losh 93108e3e3a7aSWarner Losh 93118e3e3a7aSWarner Losh<p> 93128e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> 93138e3e3a7aSWarner Losh 93148e3e3a7aSWarner Losh 93158e3e3a7aSWarner Losh<p> 93168e3e3a7aSWarner LoshReturns the argument with the maximum value, 93178e3e3a7aSWarner Loshaccording to the Lua operator <code><</code>. (integer/float) 93188e3e3a7aSWarner Losh 93198e3e3a7aSWarner Losh 93208e3e3a7aSWarner Losh 93218e3e3a7aSWarner Losh 93228e3e3a7aSWarner Losh<p> 93238e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3> 93248e3e3a7aSWarner LoshAn integer with the maximum value for an integer. 93258e3e3a7aSWarner Losh 93268e3e3a7aSWarner Losh 93278e3e3a7aSWarner Losh 93288e3e3a7aSWarner Losh 93298e3e3a7aSWarner Losh<p> 93308e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> 93318e3e3a7aSWarner Losh 93328e3e3a7aSWarner Losh 93338e3e3a7aSWarner Losh<p> 93348e3e3a7aSWarner LoshReturns the argument with the minimum value, 93358e3e3a7aSWarner Loshaccording to the Lua operator <code><</code>. (integer/float) 93368e3e3a7aSWarner Losh 93378e3e3a7aSWarner Losh 93388e3e3a7aSWarner Losh 93398e3e3a7aSWarner Losh 93408e3e3a7aSWarner Losh<p> 93418e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3> 93428e3e3a7aSWarner LoshAn integer with the minimum value for an integer. 93438e3e3a7aSWarner Losh 93448e3e3a7aSWarner Losh 93458e3e3a7aSWarner Losh 93468e3e3a7aSWarner Losh 93478e3e3a7aSWarner Losh<p> 93488e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> 93498e3e3a7aSWarner Losh 93508e3e3a7aSWarner Losh 93518e3e3a7aSWarner Losh<p> 93528e3e3a7aSWarner LoshReturns the integral part of <code>x</code> and the fractional part of <code>x</code>. 93538e3e3a7aSWarner LoshIts second result is always a float. 93548e3e3a7aSWarner Losh 93558e3e3a7aSWarner Losh 93568e3e3a7aSWarner Losh 93578e3e3a7aSWarner Losh 93588e3e3a7aSWarner Losh<p> 93598e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> 93608e3e3a7aSWarner Losh 93618e3e3a7aSWarner Losh 93628e3e3a7aSWarner Losh<p> 93638e3e3a7aSWarner LoshThe value of <em>π</em>. 93648e3e3a7aSWarner Losh 93658e3e3a7aSWarner Losh 93668e3e3a7aSWarner Losh 93678e3e3a7aSWarner Losh 93688e3e3a7aSWarner Losh<p> 93698e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> 93708e3e3a7aSWarner Losh 93718e3e3a7aSWarner Losh 93728e3e3a7aSWarner Losh<p> 93738e3e3a7aSWarner LoshConverts the angle <code>x</code> from degrees to radians. 93748e3e3a7aSWarner Losh 93758e3e3a7aSWarner Losh 93768e3e3a7aSWarner Losh 93778e3e3a7aSWarner Losh 93788e3e3a7aSWarner Losh<p> 93798e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> 93808e3e3a7aSWarner Losh 93818e3e3a7aSWarner Losh 93828e3e3a7aSWarner Losh<p> 93838e3e3a7aSWarner LoshWhen called without arguments, 93848e3e3a7aSWarner Loshreturns a pseudo-random float with uniform distribution 93858e3e3a7aSWarner Loshin the range <em>[0,1)</em>. 93868e3e3a7aSWarner LoshWhen called with two integers <code>m</code> and <code>n</code>, 93878e3e3a7aSWarner Losh<code>math.random</code> returns a pseudo-random integer 93888e3e3a7aSWarner Loshwith uniform distribution in the range <em>[m, n]</em>. 93898e3e3a7aSWarner Losh(The value <em>n-m</em> cannot be negative and must fit in a Lua integer.) 93908e3e3a7aSWarner LoshThe call <code>math.random(n)</code> is equivalent to <code>math.random(1,n)</code>. 93918e3e3a7aSWarner Losh 93928e3e3a7aSWarner Losh 93938e3e3a7aSWarner Losh<p> 93948e3e3a7aSWarner LoshThis function is an interface to the underling 93958e3e3a7aSWarner Loshpseudo-random generator function provided by C. 93968e3e3a7aSWarner Losh 93978e3e3a7aSWarner Losh 93988e3e3a7aSWarner Losh 93998e3e3a7aSWarner Losh 94008e3e3a7aSWarner Losh<p> 94018e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3> 94028e3e3a7aSWarner Losh 94038e3e3a7aSWarner Losh 94048e3e3a7aSWarner Losh<p> 94058e3e3a7aSWarner LoshSets <code>x</code> as the "seed" 94068e3e3a7aSWarner Loshfor the pseudo-random generator: 94078e3e3a7aSWarner Loshequal seeds produce equal sequences of numbers. 94088e3e3a7aSWarner Losh 94098e3e3a7aSWarner Losh 94108e3e3a7aSWarner Losh 94118e3e3a7aSWarner Losh 94128e3e3a7aSWarner Losh<p> 94138e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> 94148e3e3a7aSWarner Losh 94158e3e3a7aSWarner Losh 94168e3e3a7aSWarner Losh<p> 94178e3e3a7aSWarner LoshReturns the sine of <code>x</code> (assumed to be in radians). 94188e3e3a7aSWarner Losh 94198e3e3a7aSWarner Losh 94208e3e3a7aSWarner Losh 94218e3e3a7aSWarner Losh 94228e3e3a7aSWarner Losh<p> 94238e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> 94248e3e3a7aSWarner Losh 94258e3e3a7aSWarner Losh 94268e3e3a7aSWarner Losh<p> 94278e3e3a7aSWarner LoshReturns the square root of <code>x</code>. 94288e3e3a7aSWarner Losh(You can also use the expression <code>x^0.5</code> to compute this value.) 94298e3e3a7aSWarner Losh 94308e3e3a7aSWarner Losh 94318e3e3a7aSWarner Losh 94328e3e3a7aSWarner Losh 94338e3e3a7aSWarner Losh<p> 94348e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> 94358e3e3a7aSWarner Losh 94368e3e3a7aSWarner Losh 94378e3e3a7aSWarner Losh<p> 94388e3e3a7aSWarner LoshReturns the tangent of <code>x</code> (assumed to be in radians). 94398e3e3a7aSWarner Losh 94408e3e3a7aSWarner Losh 94418e3e3a7aSWarner Losh 94428e3e3a7aSWarner Losh 94438e3e3a7aSWarner Losh<p> 94448e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3> 94458e3e3a7aSWarner Losh 94468e3e3a7aSWarner Losh 94478e3e3a7aSWarner Losh<p> 94488e3e3a7aSWarner LoshIf the value <code>x</code> is convertible to an integer, 94498e3e3a7aSWarner Loshreturns that integer. 94508e3e3a7aSWarner LoshOtherwise, returns <b>nil</b>. 94518e3e3a7aSWarner Losh 94528e3e3a7aSWarner Losh 94538e3e3a7aSWarner Losh 94548e3e3a7aSWarner Losh 94558e3e3a7aSWarner Losh<p> 94568e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3> 94578e3e3a7aSWarner Losh 94588e3e3a7aSWarner Losh 94598e3e3a7aSWarner Losh<p> 94608e3e3a7aSWarner LoshReturns "<code>integer</code>" if <code>x</code> is an integer, 94618e3e3a7aSWarner Losh"<code>float</code>" if it is a float, 94628e3e3a7aSWarner Loshor <b>nil</b> if <code>x</code> is not a number. 94638e3e3a7aSWarner Losh 94648e3e3a7aSWarner Losh 94658e3e3a7aSWarner Losh 94668e3e3a7aSWarner Losh 94678e3e3a7aSWarner Losh<p> 94688e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3> 94698e3e3a7aSWarner Losh 94708e3e3a7aSWarner Losh 94718e3e3a7aSWarner Losh<p> 94728e3e3a7aSWarner LoshReturns a boolean, 94738e3e3a7aSWarner Loshtrue if and only if integer <code>m</code> is below integer <code>n</code> when 94748e3e3a7aSWarner Loshthey are compared as unsigned integers. 94758e3e3a7aSWarner Losh 94768e3e3a7aSWarner Losh 94778e3e3a7aSWarner Losh 94788e3e3a7aSWarner Losh 94798e3e3a7aSWarner Losh 94808e3e3a7aSWarner Losh 94818e3e3a7aSWarner Losh 94828e3e3a7aSWarner Losh<h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2> 94838e3e3a7aSWarner Losh 94848e3e3a7aSWarner Losh<p> 94858e3e3a7aSWarner LoshThe I/O library provides two different styles for file manipulation. 94868e3e3a7aSWarner LoshThe first one uses implicit file handles; 94878e3e3a7aSWarner Loshthat is, there are operations to set a default input file and a 94888e3e3a7aSWarner Loshdefault output file, 94898e3e3a7aSWarner Loshand all input/output operations are over these default files. 94908e3e3a7aSWarner LoshThe second style uses explicit file handles. 94918e3e3a7aSWarner Losh 94928e3e3a7aSWarner Losh 94938e3e3a7aSWarner Losh<p> 94948e3e3a7aSWarner LoshWhen using implicit file handles, 94958e3e3a7aSWarner Loshall operations are supplied by table <a name="pdf-io"><code>io</code></a>. 94968e3e3a7aSWarner LoshWhen using explicit file handles, 94978e3e3a7aSWarner Loshthe operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle 94988e3e3a7aSWarner Loshand then all operations are supplied as methods of the file handle. 94998e3e3a7aSWarner Losh 95008e3e3a7aSWarner Losh 95018e3e3a7aSWarner Losh<p> 95028e3e3a7aSWarner LoshThe table <code>io</code> also provides 95038e3e3a7aSWarner Loshthree predefined file handles with their usual meanings from C: 95048e3e3a7aSWarner Losh<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>. 95058e3e3a7aSWarner LoshThe I/O library never closes these files. 95068e3e3a7aSWarner Losh 95078e3e3a7aSWarner Losh 95088e3e3a7aSWarner Losh<p> 95098e3e3a7aSWarner LoshUnless otherwise stated, 95108e3e3a7aSWarner Loshall I/O functions return <b>nil</b> on failure 95118e3e3a7aSWarner Losh(plus an error message as a second result and 95128e3e3a7aSWarner Losha system-dependent error code as a third result) 95138e3e3a7aSWarner Loshand some value different from <b>nil</b> on success. 9514*e112e9d2SKyle EvansIn non-POSIX systems, 95158e3e3a7aSWarner Loshthe computation of the error message and error code 95168e3e3a7aSWarner Loshin case of errors 95178e3e3a7aSWarner Loshmay be not thread safe, 95188e3e3a7aSWarner Loshbecause they rely on the global C variable <code>errno</code>. 95198e3e3a7aSWarner Losh 95208e3e3a7aSWarner Losh 95218e3e3a7aSWarner Losh<p> 95228e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> 95238e3e3a7aSWarner Losh 95248e3e3a7aSWarner Losh 95258e3e3a7aSWarner Losh<p> 95268e3e3a7aSWarner LoshEquivalent to <code>file:close()</code>. 95278e3e3a7aSWarner LoshWithout a <code>file</code>, closes the default output file. 95288e3e3a7aSWarner Losh 95298e3e3a7aSWarner Losh 95308e3e3a7aSWarner Losh 95318e3e3a7aSWarner Losh 95328e3e3a7aSWarner Losh<p> 95338e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> 95348e3e3a7aSWarner Losh 95358e3e3a7aSWarner Losh 95368e3e3a7aSWarner Losh<p> 95378e3e3a7aSWarner LoshEquivalent to <code>io.output():flush()</code>. 95388e3e3a7aSWarner Losh 95398e3e3a7aSWarner Losh 95408e3e3a7aSWarner Losh 95418e3e3a7aSWarner Losh 95428e3e3a7aSWarner Losh<p> 95438e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> 95448e3e3a7aSWarner Losh 95458e3e3a7aSWarner Losh 95468e3e3a7aSWarner Losh<p> 95478e3e3a7aSWarner LoshWhen called with a file name, it opens the named file (in text mode), 95488e3e3a7aSWarner Loshand sets its handle as the default input file. 95498e3e3a7aSWarner LoshWhen called with a file handle, 95508e3e3a7aSWarner Loshit simply sets this file handle as the default input file. 9551*e112e9d2SKyle EvansWhen called without arguments, 95528e3e3a7aSWarner Loshit returns the current default input file. 95538e3e3a7aSWarner Losh 95548e3e3a7aSWarner Losh 95558e3e3a7aSWarner Losh<p> 95568e3e3a7aSWarner LoshIn case of errors this function raises the error, 95578e3e3a7aSWarner Loshinstead of returning an error code. 95588e3e3a7aSWarner Losh 95598e3e3a7aSWarner Losh 95608e3e3a7aSWarner Losh 95618e3e3a7aSWarner Losh 95628e3e3a7aSWarner Losh<p> 95638e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, ···])</code></a></h3> 95648e3e3a7aSWarner Losh 95658e3e3a7aSWarner Losh 95668e3e3a7aSWarner Losh<p> 95678e3e3a7aSWarner LoshOpens the given file name in read mode 95688e3e3a7aSWarner Loshand returns an iterator function that 95698e3e3a7aSWarner Loshworks like <code>file:lines(···)</code> over the opened file. 95708e3e3a7aSWarner LoshWhen the iterator function detects the end of file, 95718e3e3a7aSWarner Loshit returns no values (to finish the loop) and automatically closes the file. 95728e3e3a7aSWarner Losh 95738e3e3a7aSWarner Losh 95748e3e3a7aSWarner Losh<p> 95758e3e3a7aSWarner LoshThe call <code>io.lines()</code> (with no file name) is equivalent 95768e3e3a7aSWarner Loshto <code>io.input():lines("*l")</code>; 95778e3e3a7aSWarner Loshthat is, it iterates over the lines of the default input file. 9578*e112e9d2SKyle EvansIn this case, the iterator does not close the file when the loop ends. 95798e3e3a7aSWarner Losh 95808e3e3a7aSWarner Losh 95818e3e3a7aSWarner Losh<p> 95828e3e3a7aSWarner LoshIn case of errors this function raises the error, 95838e3e3a7aSWarner Loshinstead of returning an error code. 95848e3e3a7aSWarner Losh 95858e3e3a7aSWarner Losh 95868e3e3a7aSWarner Losh 95878e3e3a7aSWarner Losh 95888e3e3a7aSWarner Losh<p> 95898e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> 95908e3e3a7aSWarner Losh 95918e3e3a7aSWarner Losh 95928e3e3a7aSWarner Losh<p> 95938e3e3a7aSWarner LoshThis function opens a file, 95948e3e3a7aSWarner Loshin the mode specified in the string <code>mode</code>. 95958e3e3a7aSWarner LoshIn case of success, 95968e3e3a7aSWarner Loshit returns a new file handle. 95978e3e3a7aSWarner Losh 95988e3e3a7aSWarner Losh 95998e3e3a7aSWarner Losh<p> 96008e3e3a7aSWarner LoshThe <code>mode</code> string can be any of the following: 96018e3e3a7aSWarner Losh 96028e3e3a7aSWarner Losh<ul> 96038e3e3a7aSWarner Losh<li><b>"<code>r</code>": </b> read mode (the default);</li> 96048e3e3a7aSWarner Losh<li><b>"<code>w</code>": </b> write mode;</li> 96058e3e3a7aSWarner Losh<li><b>"<code>a</code>": </b> append mode;</li> 96068e3e3a7aSWarner Losh<li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li> 96078e3e3a7aSWarner Losh<li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li> 96088e3e3a7aSWarner Losh<li><b>"<code>a+</code>": </b> append update mode, previous data is preserved, 96098e3e3a7aSWarner Losh writing is only allowed at the end of file.</li> 96108e3e3a7aSWarner Losh</ul><p> 96118e3e3a7aSWarner LoshThe <code>mode</code> string can also have a '<code>b</code>' at the end, 96128e3e3a7aSWarner Loshwhich is needed in some systems to open the file in binary mode. 96138e3e3a7aSWarner Losh 96148e3e3a7aSWarner Losh 96158e3e3a7aSWarner Losh 96168e3e3a7aSWarner Losh 96178e3e3a7aSWarner Losh<p> 96188e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> 96198e3e3a7aSWarner Losh 96208e3e3a7aSWarner Losh 96218e3e3a7aSWarner Losh<p> 96228e3e3a7aSWarner LoshSimilar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. 96238e3e3a7aSWarner Losh 96248e3e3a7aSWarner Losh 96258e3e3a7aSWarner Losh 96268e3e3a7aSWarner Losh 96278e3e3a7aSWarner Losh<p> 96288e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> 96298e3e3a7aSWarner Losh 96308e3e3a7aSWarner Losh 96318e3e3a7aSWarner Losh<p> 96328e3e3a7aSWarner LoshThis function is system dependent and is not available 96338e3e3a7aSWarner Loshon all platforms. 96348e3e3a7aSWarner Losh 96358e3e3a7aSWarner Losh 96368e3e3a7aSWarner Losh<p> 96378e3e3a7aSWarner LoshStarts program <code>prog</code> in a separated process and returns 96388e3e3a7aSWarner Losha file handle that you can use to read data from this program 96398e3e3a7aSWarner Losh(if <code>mode</code> is <code>"r"</code>, the default) 96408e3e3a7aSWarner Loshor to write data to this program 96418e3e3a7aSWarner Losh(if <code>mode</code> is <code>"w"</code>). 96428e3e3a7aSWarner Losh 96438e3e3a7aSWarner Losh 96448e3e3a7aSWarner Losh 96458e3e3a7aSWarner Losh 96468e3e3a7aSWarner Losh<p> 96478e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> 96488e3e3a7aSWarner Losh 96498e3e3a7aSWarner Losh 96508e3e3a7aSWarner Losh<p> 96518e3e3a7aSWarner LoshEquivalent to <code>io.input():read(···)</code>. 96528e3e3a7aSWarner Losh 96538e3e3a7aSWarner Losh 96548e3e3a7aSWarner Losh 96558e3e3a7aSWarner Losh 96568e3e3a7aSWarner Losh<p> 96578e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> 96588e3e3a7aSWarner Losh 96598e3e3a7aSWarner Losh 96608e3e3a7aSWarner Losh<p> 96618e3e3a7aSWarner LoshIn case of success, 96628e3e3a7aSWarner Loshreturns a handle for a temporary file. 96638e3e3a7aSWarner LoshThis file is opened in update mode 96648e3e3a7aSWarner Loshand it is automatically removed when the program ends. 96658e3e3a7aSWarner Losh 96668e3e3a7aSWarner Losh 96678e3e3a7aSWarner Losh 96688e3e3a7aSWarner Losh 96698e3e3a7aSWarner Losh<p> 96708e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> 96718e3e3a7aSWarner Losh 96728e3e3a7aSWarner Losh 96738e3e3a7aSWarner Losh<p> 96748e3e3a7aSWarner LoshChecks whether <code>obj</code> is a valid file handle. 96758e3e3a7aSWarner LoshReturns the string <code>"file"</code> if <code>obj</code> is an open file handle, 96768e3e3a7aSWarner Losh<code>"closed file"</code> if <code>obj</code> is a closed file handle, 96778e3e3a7aSWarner Loshor <b>nil</b> if <code>obj</code> is not a file handle. 96788e3e3a7aSWarner Losh 96798e3e3a7aSWarner Losh 96808e3e3a7aSWarner Losh 96818e3e3a7aSWarner Losh 96828e3e3a7aSWarner Losh<p> 96838e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> 96848e3e3a7aSWarner Losh 96858e3e3a7aSWarner Losh 96868e3e3a7aSWarner Losh<p> 96878e3e3a7aSWarner LoshEquivalent to <code>io.output():write(···)</code>. 96888e3e3a7aSWarner Losh 96898e3e3a7aSWarner Losh 96908e3e3a7aSWarner Losh 96918e3e3a7aSWarner Losh 96928e3e3a7aSWarner Losh<p> 96938e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> 96948e3e3a7aSWarner Losh 96958e3e3a7aSWarner Losh 96968e3e3a7aSWarner Losh<p> 96978e3e3a7aSWarner LoshCloses <code>file</code>. 96988e3e3a7aSWarner LoshNote that files are automatically closed when 96998e3e3a7aSWarner Loshtheir handles are garbage collected, 97008e3e3a7aSWarner Loshbut that takes an unpredictable amount of time to happen. 97018e3e3a7aSWarner Losh 97028e3e3a7aSWarner Losh 97038e3e3a7aSWarner Losh<p> 97048e3e3a7aSWarner LoshWhen closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>, 97058e3e3a7aSWarner Losh<a href="#pdf-file:close"><code>file:close</code></a> returns the same values 97068e3e3a7aSWarner Loshreturned by <a href="#pdf-os.execute"><code>os.execute</code></a>. 97078e3e3a7aSWarner Losh 97088e3e3a7aSWarner Losh 97098e3e3a7aSWarner Losh 97108e3e3a7aSWarner Losh 97118e3e3a7aSWarner Losh<p> 97128e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> 97138e3e3a7aSWarner Losh 97148e3e3a7aSWarner Losh 97158e3e3a7aSWarner Losh<p> 97168e3e3a7aSWarner LoshSaves any written data to <code>file</code>. 97178e3e3a7aSWarner Losh 97188e3e3a7aSWarner Losh 97198e3e3a7aSWarner Losh 97208e3e3a7aSWarner Losh 97218e3e3a7aSWarner Losh<p> 97228e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3> 97238e3e3a7aSWarner Losh 97248e3e3a7aSWarner Losh 97258e3e3a7aSWarner Losh<p> 97268e3e3a7aSWarner LoshReturns an iterator function that, 97278e3e3a7aSWarner Losheach time it is called, 97288e3e3a7aSWarner Loshreads the file according to the given formats. 97298e3e3a7aSWarner LoshWhen no format is given, 97308e3e3a7aSWarner Loshuses "<code>l</code>" as a default. 97318e3e3a7aSWarner LoshAs an example, the construction 97328e3e3a7aSWarner Losh 97338e3e3a7aSWarner Losh<pre> 97348e3e3a7aSWarner Losh for c in file:lines(1) do <em>body</em> end 97358e3e3a7aSWarner Losh</pre><p> 97368e3e3a7aSWarner Loshwill iterate over all characters of the file, 97378e3e3a7aSWarner Loshstarting at the current position. 97388e3e3a7aSWarner LoshUnlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file 97398e3e3a7aSWarner Loshwhen the loop ends. 97408e3e3a7aSWarner Losh 97418e3e3a7aSWarner Losh 97428e3e3a7aSWarner Losh<p> 97438e3e3a7aSWarner LoshIn case of errors this function raises the error, 97448e3e3a7aSWarner Loshinstead of returning an error code. 97458e3e3a7aSWarner Losh 97468e3e3a7aSWarner Losh 97478e3e3a7aSWarner Losh 97488e3e3a7aSWarner Losh 97498e3e3a7aSWarner Losh<p> 97508e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> 97518e3e3a7aSWarner Losh 97528e3e3a7aSWarner Losh 97538e3e3a7aSWarner Losh<p> 97548e3e3a7aSWarner LoshReads the file <code>file</code>, 97558e3e3a7aSWarner Loshaccording to the given formats, which specify what to read. 97568e3e3a7aSWarner LoshFor each format, 97578e3e3a7aSWarner Loshthe function returns a string or a number with the characters read, 97588e3e3a7aSWarner Loshor <b>nil</b> if it cannot read data with the specified format. 97598e3e3a7aSWarner Losh(In this latter case, 97608e3e3a7aSWarner Loshthe function does not read subsequent formats.) 97618e3e3a7aSWarner LoshWhen called without formats, 97628e3e3a7aSWarner Loshit uses a default format that reads the next line 97638e3e3a7aSWarner Losh(see below). 97648e3e3a7aSWarner Losh 97658e3e3a7aSWarner Losh 97668e3e3a7aSWarner Losh<p> 97678e3e3a7aSWarner LoshThe available formats are 97688e3e3a7aSWarner Losh 97698e3e3a7aSWarner Losh<ul> 97708e3e3a7aSWarner Losh 97718e3e3a7aSWarner Losh<li><b>"<code>n</code>": </b> 97728e3e3a7aSWarner Loshreads a numeral and returns it as a float or an integer, 97738e3e3a7aSWarner Loshfollowing the lexical conventions of Lua. 97748e3e3a7aSWarner Losh(The numeral may have leading spaces and a sign.) 97758e3e3a7aSWarner LoshThis format always reads the longest input sequence that 97768e3e3a7aSWarner Loshis a valid prefix for a numeral; 97778e3e3a7aSWarner Loshif that prefix does not form a valid numeral 97788e3e3a7aSWarner Losh(e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"), 97798e3e3a7aSWarner Loshit is discarded and the function returns <b>nil</b>. 97808e3e3a7aSWarner Losh</li> 97818e3e3a7aSWarner Losh 97828e3e3a7aSWarner Losh<li><b>"<code>a</code>": </b> 97838e3e3a7aSWarner Loshreads the whole file, starting at the current position. 97848e3e3a7aSWarner LoshOn end of file, it returns the empty string. 97858e3e3a7aSWarner Losh</li> 97868e3e3a7aSWarner Losh 97878e3e3a7aSWarner Losh<li><b>"<code>l</code>": </b> 97888e3e3a7aSWarner Loshreads the next line skipping the end of line, 97898e3e3a7aSWarner Loshreturning <b>nil</b> on end of file. 97908e3e3a7aSWarner LoshThis is the default format. 97918e3e3a7aSWarner Losh</li> 97928e3e3a7aSWarner Losh 97938e3e3a7aSWarner Losh<li><b>"<code>L</code>": </b> 97948e3e3a7aSWarner Loshreads the next line keeping the end-of-line character (if present), 97958e3e3a7aSWarner Loshreturning <b>nil</b> on end of file. 97968e3e3a7aSWarner Losh</li> 97978e3e3a7aSWarner Losh 97988e3e3a7aSWarner Losh<li><b><em>number</em>: </b> 97998e3e3a7aSWarner Loshreads a string with up to this number of bytes, 98008e3e3a7aSWarner Loshreturning <b>nil</b> on end of file. 98018e3e3a7aSWarner LoshIf <code>number</code> is zero, 98028e3e3a7aSWarner Loshit reads nothing and returns an empty string, 98038e3e3a7aSWarner Loshor <b>nil</b> on end of file. 98048e3e3a7aSWarner Losh</li> 98058e3e3a7aSWarner Losh 98068e3e3a7aSWarner Losh</ul><p> 98078e3e3a7aSWarner LoshThe formats "<code>l</code>" and "<code>L</code>" should be used only for text files. 98088e3e3a7aSWarner Losh 98098e3e3a7aSWarner Losh 98108e3e3a7aSWarner Losh 98118e3e3a7aSWarner Losh 98128e3e3a7aSWarner Losh<p> 98138e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3> 98148e3e3a7aSWarner Losh 98158e3e3a7aSWarner Losh 98168e3e3a7aSWarner Losh<p> 98178e3e3a7aSWarner LoshSets and gets the file position, 98188e3e3a7aSWarner Loshmeasured from the beginning of the file, 98198e3e3a7aSWarner Loshto the position given by <code>offset</code> plus a base 98208e3e3a7aSWarner Loshspecified by the string <code>whence</code>, as follows: 98218e3e3a7aSWarner Losh 98228e3e3a7aSWarner Losh<ul> 98238e3e3a7aSWarner Losh<li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li> 98248e3e3a7aSWarner Losh<li><b>"<code>cur</code>": </b> base is current position;</li> 98258e3e3a7aSWarner Losh<li><b>"<code>end</code>": </b> base is end of file;</li> 98268e3e3a7aSWarner Losh</ul><p> 98278e3e3a7aSWarner LoshIn case of success, <code>seek</code> returns the final file position, 98288e3e3a7aSWarner Loshmeasured in bytes from the beginning of the file. 98298e3e3a7aSWarner LoshIf <code>seek</code> fails, it returns <b>nil</b>, 98308e3e3a7aSWarner Loshplus a string describing the error. 98318e3e3a7aSWarner Losh 98328e3e3a7aSWarner Losh 98338e3e3a7aSWarner Losh<p> 98348e3e3a7aSWarner LoshThe default value for <code>whence</code> is <code>"cur"</code>, 98358e3e3a7aSWarner Loshand for <code>offset</code> is 0. 98368e3e3a7aSWarner LoshTherefore, the call <code>file:seek()</code> returns the current 98378e3e3a7aSWarner Loshfile position, without changing it; 98388e3e3a7aSWarner Loshthe call <code>file:seek("set")</code> sets the position to the 98398e3e3a7aSWarner Loshbeginning of the file (and returns 0); 98408e3e3a7aSWarner Loshand the call <code>file:seek("end")</code> sets the position to the 98418e3e3a7aSWarner Loshend of the file, and returns its size. 98428e3e3a7aSWarner Losh 98438e3e3a7aSWarner Losh 98448e3e3a7aSWarner Losh 98458e3e3a7aSWarner Losh 98468e3e3a7aSWarner Losh<p> 98478e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> 98488e3e3a7aSWarner Losh 98498e3e3a7aSWarner Losh 98508e3e3a7aSWarner Losh<p> 98518e3e3a7aSWarner LoshSets the buffering mode for an output file. 98528e3e3a7aSWarner LoshThere are three available modes: 98538e3e3a7aSWarner Losh 98548e3e3a7aSWarner Losh<ul> 98558e3e3a7aSWarner Losh 98568e3e3a7aSWarner Losh<li><b>"<code>no</code>": </b> 98578e3e3a7aSWarner Loshno buffering; the result of any output operation appears immediately. 98588e3e3a7aSWarner Losh</li> 98598e3e3a7aSWarner Losh 98608e3e3a7aSWarner Losh<li><b>"<code>full</code>": </b> 98618e3e3a7aSWarner Loshfull buffering; output operation is performed only 98628e3e3a7aSWarner Loshwhen the buffer is full or when 98638e3e3a7aSWarner Loshyou explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>). 98648e3e3a7aSWarner Losh</li> 98658e3e3a7aSWarner Losh 98668e3e3a7aSWarner Losh<li><b>"<code>line</code>": </b> 98678e3e3a7aSWarner Loshline buffering; output is buffered until a newline is output 98688e3e3a7aSWarner Loshor there is any input from some special files 98698e3e3a7aSWarner Losh(such as a terminal device). 98708e3e3a7aSWarner Losh</li> 98718e3e3a7aSWarner Losh 98728e3e3a7aSWarner Losh</ul><p> 98738e3e3a7aSWarner LoshFor the last two cases, <code>size</code> 98748e3e3a7aSWarner Loshspecifies the size of the buffer, in bytes. 98758e3e3a7aSWarner LoshThe default is an appropriate size. 98768e3e3a7aSWarner Losh 98778e3e3a7aSWarner Losh 98788e3e3a7aSWarner Losh 98798e3e3a7aSWarner Losh 98808e3e3a7aSWarner Losh<p> 98818e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> 98828e3e3a7aSWarner Losh 98838e3e3a7aSWarner Losh 98848e3e3a7aSWarner Losh<p> 98858e3e3a7aSWarner LoshWrites the value of each of its arguments to <code>file</code>. 98868e3e3a7aSWarner LoshThe arguments must be strings or numbers. 98878e3e3a7aSWarner Losh 98888e3e3a7aSWarner Losh 98898e3e3a7aSWarner Losh<p> 98908e3e3a7aSWarner LoshIn case of success, this function returns <code>file</code>. 98918e3e3a7aSWarner LoshOtherwise it returns <b>nil</b> plus a string describing the error. 98928e3e3a7aSWarner Losh 98938e3e3a7aSWarner Losh 98948e3e3a7aSWarner Losh 98958e3e3a7aSWarner Losh 98968e3e3a7aSWarner Losh 98978e3e3a7aSWarner Losh 98988e3e3a7aSWarner Losh 98998e3e3a7aSWarner Losh<h2>6.9 – <a name="6.9">Operating System Facilities</a></h2> 99008e3e3a7aSWarner Losh 99018e3e3a7aSWarner Losh<p> 99028e3e3a7aSWarner LoshThis library is implemented through table <a name="pdf-os"><code>os</code></a>. 99038e3e3a7aSWarner Losh 99048e3e3a7aSWarner Losh 99058e3e3a7aSWarner Losh<p> 99068e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> 99078e3e3a7aSWarner Losh 99088e3e3a7aSWarner Losh 99098e3e3a7aSWarner Losh<p> 99108e3e3a7aSWarner LoshReturns an approximation of the amount in seconds of CPU time 99118e3e3a7aSWarner Loshused by the program. 99128e3e3a7aSWarner Losh 99138e3e3a7aSWarner Losh 99148e3e3a7aSWarner Losh 99158e3e3a7aSWarner Losh 99168e3e3a7aSWarner Losh<p> 99178e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> 99188e3e3a7aSWarner Losh 99198e3e3a7aSWarner Losh 99208e3e3a7aSWarner Losh<p> 99218e3e3a7aSWarner LoshReturns a string or a table containing date and time, 99228e3e3a7aSWarner Loshformatted according to the given string <code>format</code>. 99238e3e3a7aSWarner Losh 99248e3e3a7aSWarner Losh 99258e3e3a7aSWarner Losh<p> 99268e3e3a7aSWarner LoshIf the <code>time</code> argument is present, 99278e3e3a7aSWarner Loshthis is the time to be formatted 99288e3e3a7aSWarner Losh(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). 99298e3e3a7aSWarner LoshOtherwise, <code>date</code> formats the current time. 99308e3e3a7aSWarner Losh 99318e3e3a7aSWarner Losh 99328e3e3a7aSWarner Losh<p> 99338e3e3a7aSWarner LoshIf <code>format</code> starts with '<code>!</code>', 99348e3e3a7aSWarner Loshthen the date is formatted in Coordinated Universal Time. 99358e3e3a7aSWarner LoshAfter this optional character, 99368e3e3a7aSWarner Loshif <code>format</code> is the string "<code>*t</code>", 99378e3e3a7aSWarner Loshthen <code>date</code> returns a table with the following fields: 99388e3e3a7aSWarner Losh<code>year</code>, <code>month</code> (1–12), <code>day</code> (1–31), 99398e3e3a7aSWarner Losh<code>hour</code> (0–23), <code>min</code> (0–59), <code>sec</code> (0–61), 99408e3e3a7aSWarner Losh<code>wday</code> (weekday, 1–7, Sunday is 1), 99418e3e3a7aSWarner Losh<code>yday</code> (day of the year, 1–366), 99428e3e3a7aSWarner Loshand <code>isdst</code> (daylight saving flag, a boolean). 99438e3e3a7aSWarner LoshThis last field may be absent 99448e3e3a7aSWarner Loshif the information is not available. 99458e3e3a7aSWarner Losh 99468e3e3a7aSWarner Losh 99478e3e3a7aSWarner Losh<p> 99488e3e3a7aSWarner LoshIf <code>format</code> is not "<code>*t</code>", 99498e3e3a7aSWarner Loshthen <code>date</code> returns the date as a string, 99508e3e3a7aSWarner Loshformatted according to the same rules as the ISO C function <code>strftime</code>. 99518e3e3a7aSWarner Losh 99528e3e3a7aSWarner Losh 99538e3e3a7aSWarner Losh<p> 99548e3e3a7aSWarner LoshWhen called without arguments, 99558e3e3a7aSWarner Losh<code>date</code> returns a reasonable date and time representation that depends on 99568e3e3a7aSWarner Loshthe host system and on the current locale. 99578e3e3a7aSWarner Losh(More specifically, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>.) 99588e3e3a7aSWarner Losh 99598e3e3a7aSWarner Losh 99608e3e3a7aSWarner Losh<p> 9961*e112e9d2SKyle EvansIn non-POSIX systems, 99628e3e3a7aSWarner Loshthis function may be not thread safe 99638e3e3a7aSWarner Loshbecause of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>. 99648e3e3a7aSWarner Losh 99658e3e3a7aSWarner Losh 99668e3e3a7aSWarner Losh 99678e3e3a7aSWarner Losh 99688e3e3a7aSWarner Losh<p> 99698e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> 99708e3e3a7aSWarner Losh 99718e3e3a7aSWarner Losh 99728e3e3a7aSWarner Losh<p> 99738e3e3a7aSWarner LoshReturns the difference, in seconds, 99748e3e3a7aSWarner Loshfrom time <code>t1</code> to time <code>t2</code> 99758e3e3a7aSWarner Losh(where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>). 99768e3e3a7aSWarner LoshIn POSIX, Windows, and some other systems, 99778e3e3a7aSWarner Loshthis value is exactly <code>t2</code><em>-</em><code>t1</code>. 99788e3e3a7aSWarner Losh 99798e3e3a7aSWarner Losh 99808e3e3a7aSWarner Losh 99818e3e3a7aSWarner Losh 99828e3e3a7aSWarner Losh<p> 99838e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> 99848e3e3a7aSWarner Losh 99858e3e3a7aSWarner Losh 99868e3e3a7aSWarner Losh<p> 99878e3e3a7aSWarner LoshThis function is equivalent to the ISO C function <code>system</code>. 99888e3e3a7aSWarner LoshIt passes <code>command</code> to be executed by an operating system shell. 99898e3e3a7aSWarner LoshIts first result is <b>true</b> 99908e3e3a7aSWarner Loshif the command terminated successfully, 99918e3e3a7aSWarner Loshor <b>nil</b> otherwise. 99928e3e3a7aSWarner LoshAfter this first result 99938e3e3a7aSWarner Loshthe function returns a string plus a number, 99948e3e3a7aSWarner Loshas follows: 99958e3e3a7aSWarner Losh 99968e3e3a7aSWarner Losh<ul> 99978e3e3a7aSWarner Losh 99988e3e3a7aSWarner Losh<li><b>"<code>exit</code>": </b> 99998e3e3a7aSWarner Loshthe command terminated normally; 100008e3e3a7aSWarner Loshthe following number is the exit status of the command. 100018e3e3a7aSWarner Losh</li> 100028e3e3a7aSWarner Losh 100038e3e3a7aSWarner Losh<li><b>"<code>signal</code>": </b> 100048e3e3a7aSWarner Loshthe command was terminated by a signal; 100058e3e3a7aSWarner Loshthe following number is the signal that terminated the command. 100068e3e3a7aSWarner Losh</li> 100078e3e3a7aSWarner Losh 100088e3e3a7aSWarner Losh</ul> 100098e3e3a7aSWarner Losh 100108e3e3a7aSWarner Losh<p> 100118e3e3a7aSWarner LoshWhen called without a <code>command</code>, 100128e3e3a7aSWarner Losh<code>os.execute</code> returns a boolean that is true if a shell is available. 100138e3e3a7aSWarner Losh 100148e3e3a7aSWarner Losh 100158e3e3a7aSWarner Losh 100168e3e3a7aSWarner Losh 100178e3e3a7aSWarner Losh<p> 100188e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3> 100198e3e3a7aSWarner Losh 100208e3e3a7aSWarner Losh 100218e3e3a7aSWarner Losh<p> 100228e3e3a7aSWarner LoshCalls the ISO C function <code>exit</code> to terminate the host program. 100238e3e3a7aSWarner LoshIf <code>code</code> is <b>true</b>, 100248e3e3a7aSWarner Loshthe returned status is <code>EXIT_SUCCESS</code>; 100258e3e3a7aSWarner Loshif <code>code</code> is <b>false</b>, 100268e3e3a7aSWarner Loshthe returned status is <code>EXIT_FAILURE</code>; 100278e3e3a7aSWarner Loshif <code>code</code> is a number, 100288e3e3a7aSWarner Loshthe returned status is this number. 100298e3e3a7aSWarner LoshThe default value for <code>code</code> is <b>true</b>. 100308e3e3a7aSWarner Losh 100318e3e3a7aSWarner Losh 100328e3e3a7aSWarner Losh<p> 100338e3e3a7aSWarner LoshIf the optional second argument <code>close</code> is true, 100348e3e3a7aSWarner Loshcloses the Lua state before exiting. 100358e3e3a7aSWarner Losh 100368e3e3a7aSWarner Losh 100378e3e3a7aSWarner Losh 100388e3e3a7aSWarner Losh 100398e3e3a7aSWarner Losh<p> 100408e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> 100418e3e3a7aSWarner Losh 100428e3e3a7aSWarner Losh 100438e3e3a7aSWarner Losh<p> 100448e3e3a7aSWarner LoshReturns the value of the process environment variable <code>varname</code>, 100458e3e3a7aSWarner Loshor <b>nil</b> if the variable is not defined. 100468e3e3a7aSWarner Losh 100478e3e3a7aSWarner Losh 100488e3e3a7aSWarner Losh 100498e3e3a7aSWarner Losh 100508e3e3a7aSWarner Losh<p> 100518e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> 100528e3e3a7aSWarner Losh 100538e3e3a7aSWarner Losh 100548e3e3a7aSWarner Losh<p> 100558e3e3a7aSWarner LoshDeletes the file (or empty directory, on POSIX systems) 100568e3e3a7aSWarner Loshwith the given name. 100578e3e3a7aSWarner LoshIf this function fails, it returns <b>nil</b>, 100588e3e3a7aSWarner Loshplus a string describing the error and the error code. 100598e3e3a7aSWarner LoshOtherwise, it returns true. 100608e3e3a7aSWarner Losh 100618e3e3a7aSWarner Losh 100628e3e3a7aSWarner Losh 100638e3e3a7aSWarner Losh 100648e3e3a7aSWarner Losh<p> 100658e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> 100668e3e3a7aSWarner Losh 100678e3e3a7aSWarner Losh 100688e3e3a7aSWarner Losh<p> 100698e3e3a7aSWarner LoshRenames the file or directory named <code>oldname</code> to <code>newname</code>. 100708e3e3a7aSWarner LoshIf this function fails, it returns <b>nil</b>, 100718e3e3a7aSWarner Loshplus a string describing the error and the error code. 100728e3e3a7aSWarner LoshOtherwise, it returns true. 100738e3e3a7aSWarner Losh 100748e3e3a7aSWarner Losh 100758e3e3a7aSWarner Losh 100768e3e3a7aSWarner Losh 100778e3e3a7aSWarner Losh<p> 100788e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> 100798e3e3a7aSWarner Losh 100808e3e3a7aSWarner Losh 100818e3e3a7aSWarner Losh<p> 100828e3e3a7aSWarner LoshSets the current locale of the program. 100838e3e3a7aSWarner Losh<code>locale</code> is a system-dependent string specifying a locale; 100848e3e3a7aSWarner Losh<code>category</code> is an optional string describing which category to change: 100858e3e3a7aSWarner Losh<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, 100868e3e3a7aSWarner Losh<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; 100878e3e3a7aSWarner Loshthe default category is <code>"all"</code>. 100888e3e3a7aSWarner LoshThe function returns the name of the new locale, 100898e3e3a7aSWarner Loshor <b>nil</b> if the request cannot be honored. 100908e3e3a7aSWarner Losh 100918e3e3a7aSWarner Losh 100928e3e3a7aSWarner Losh<p> 100938e3e3a7aSWarner LoshIf <code>locale</code> is the empty string, 100948e3e3a7aSWarner Loshthe current locale is set to an implementation-defined native locale. 100958e3e3a7aSWarner LoshIf <code>locale</code> is the string "<code>C</code>", 100968e3e3a7aSWarner Loshthe current locale is set to the standard C locale. 100978e3e3a7aSWarner Losh 100988e3e3a7aSWarner Losh 100998e3e3a7aSWarner Losh<p> 101008e3e3a7aSWarner LoshWhen called with <b>nil</b> as the first argument, 101018e3e3a7aSWarner Loshthis function only returns the name of the current locale 101028e3e3a7aSWarner Loshfor the given category. 101038e3e3a7aSWarner Losh 101048e3e3a7aSWarner Losh 101058e3e3a7aSWarner Losh<p> 101068e3e3a7aSWarner LoshThis function may be not thread safe 101078e3e3a7aSWarner Loshbecause of its reliance on C function <code>setlocale</code>. 101088e3e3a7aSWarner Losh 101098e3e3a7aSWarner Losh 101108e3e3a7aSWarner Losh 101118e3e3a7aSWarner Losh 101128e3e3a7aSWarner Losh<p> 101138e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> 101148e3e3a7aSWarner Losh 101158e3e3a7aSWarner Losh 101168e3e3a7aSWarner Losh<p> 101178e3e3a7aSWarner LoshReturns the current time when called without arguments, 101188e3e3a7aSWarner Loshor a time representing the local date and time specified by the given table. 101198e3e3a7aSWarner LoshThis table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, 101208e3e3a7aSWarner Loshand may have fields 101218e3e3a7aSWarner Losh<code>hour</code> (default is 12), 101228e3e3a7aSWarner Losh<code>min</code> (default is 0), 101238e3e3a7aSWarner Losh<code>sec</code> (default is 0), 101248e3e3a7aSWarner Loshand <code>isdst</code> (default is <b>nil</b>). 101258e3e3a7aSWarner LoshOther fields are ignored. 101268e3e3a7aSWarner LoshFor a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function. 101278e3e3a7aSWarner Losh 101288e3e3a7aSWarner Losh 101298e3e3a7aSWarner Losh<p> 101308e3e3a7aSWarner LoshThe values in these fields do not need to be inside their valid ranges. 101318e3e3a7aSWarner LoshFor instance, if <code>sec</code> is -10, 101328e3e3a7aSWarner Loshit means -10 seconds from the time specified by the other fields; 101338e3e3a7aSWarner Loshif <code>hour</code> is 1000, 101348e3e3a7aSWarner Loshit means +1000 hours from the time specified by the other fields. 101358e3e3a7aSWarner Losh 101368e3e3a7aSWarner Losh 101378e3e3a7aSWarner Losh<p> 101388e3e3a7aSWarner LoshThe returned value is a number, whose meaning depends on your system. 101398e3e3a7aSWarner LoshIn POSIX, Windows, and some other systems, 101408e3e3a7aSWarner Loshthis number counts the number 101418e3e3a7aSWarner Loshof seconds since some given start time (the "epoch"). 101428e3e3a7aSWarner LoshIn other systems, the meaning is not specified, 101438e3e3a7aSWarner Loshand the number returned by <code>time</code> can be used only as an argument to 101448e3e3a7aSWarner Losh<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. 101458e3e3a7aSWarner Losh 101468e3e3a7aSWarner Losh 101478e3e3a7aSWarner Losh 101488e3e3a7aSWarner Losh 101498e3e3a7aSWarner Losh<p> 101508e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> 101518e3e3a7aSWarner Losh 101528e3e3a7aSWarner Losh 101538e3e3a7aSWarner Losh<p> 101548e3e3a7aSWarner LoshReturns a string with a file name that can 101558e3e3a7aSWarner Loshbe used for a temporary file. 101568e3e3a7aSWarner LoshThe file must be explicitly opened before its use 101578e3e3a7aSWarner Loshand explicitly removed when no longer needed. 101588e3e3a7aSWarner Losh 101598e3e3a7aSWarner Losh 101608e3e3a7aSWarner Losh<p> 10161*e112e9d2SKyle EvansIn POSIX systems, 101628e3e3a7aSWarner Loshthis function also creates a file with that name, 101638e3e3a7aSWarner Loshto avoid security risks. 101648e3e3a7aSWarner Losh(Someone else might create the file with wrong permissions 101658e3e3a7aSWarner Loshin the time between getting the name and creating the file.) 101668e3e3a7aSWarner LoshYou still have to open the file to use it 101678e3e3a7aSWarner Loshand to remove it (even if you do not use it). 101688e3e3a7aSWarner Losh 101698e3e3a7aSWarner Losh 101708e3e3a7aSWarner Losh<p> 101718e3e3a7aSWarner LoshWhen possible, 101728e3e3a7aSWarner Loshyou may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, 101738e3e3a7aSWarner Loshwhich automatically removes the file when the program ends. 101748e3e3a7aSWarner Losh 101758e3e3a7aSWarner Losh 101768e3e3a7aSWarner Losh 101778e3e3a7aSWarner Losh 101788e3e3a7aSWarner Losh 101798e3e3a7aSWarner Losh 101808e3e3a7aSWarner Losh 101818e3e3a7aSWarner Losh<h2>6.10 – <a name="6.10">The Debug Library</a></h2> 101828e3e3a7aSWarner Losh 101838e3e3a7aSWarner Losh<p> 101848e3e3a7aSWarner LoshThis library provides 101858e3e3a7aSWarner Loshthe functionality of the debug interface (<a href="#4.9">§4.9</a>) to Lua programs. 101868e3e3a7aSWarner LoshYou should exert care when using this library. 101878e3e3a7aSWarner LoshSeveral of its functions 101888e3e3a7aSWarner Loshviolate basic assumptions about Lua code 101898e3e3a7aSWarner Losh(e.g., that variables local to a function 101908e3e3a7aSWarner Loshcannot be accessed from outside; 101918e3e3a7aSWarner Loshthat userdata metatables cannot be changed by Lua code; 101928e3e3a7aSWarner Loshthat Lua programs do not crash) 101938e3e3a7aSWarner Loshand therefore can compromise otherwise secure code. 101948e3e3a7aSWarner LoshMoreover, some functions in this library may be slow. 101958e3e3a7aSWarner Losh 101968e3e3a7aSWarner Losh 101978e3e3a7aSWarner Losh<p> 101988e3e3a7aSWarner LoshAll functions in this library are provided 101998e3e3a7aSWarner Loshinside the <a name="pdf-debug"><code>debug</code></a> table. 102008e3e3a7aSWarner LoshAll functions that operate over a thread 102018e3e3a7aSWarner Loshhave an optional first argument which is the 102028e3e3a7aSWarner Loshthread to operate over. 102038e3e3a7aSWarner LoshThe default is always the current thread. 102048e3e3a7aSWarner Losh 102058e3e3a7aSWarner Losh 102068e3e3a7aSWarner Losh<p> 102078e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> 102088e3e3a7aSWarner Losh 102098e3e3a7aSWarner Losh 102108e3e3a7aSWarner Losh<p> 102118e3e3a7aSWarner LoshEnters an interactive mode with the user, 102128e3e3a7aSWarner Loshrunning each string that the user enters. 102138e3e3a7aSWarner LoshUsing simple commands and other debug facilities, 102148e3e3a7aSWarner Loshthe user can inspect global and local variables, 102158e3e3a7aSWarner Loshchange their values, evaluate expressions, and so on. 102168e3e3a7aSWarner LoshA line containing only the word <code>cont</code> finishes this function, 102178e3e3a7aSWarner Loshso that the caller continues its execution. 102188e3e3a7aSWarner Losh 102198e3e3a7aSWarner Losh 102208e3e3a7aSWarner Losh<p> 102218e3e3a7aSWarner LoshNote that commands for <code>debug.debug</code> are not lexically nested 102228e3e3a7aSWarner Loshwithin any function and so have no direct access to local variables. 102238e3e3a7aSWarner Losh 102248e3e3a7aSWarner Losh 102258e3e3a7aSWarner Losh 102268e3e3a7aSWarner Losh 102278e3e3a7aSWarner Losh<p> 102288e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> 102298e3e3a7aSWarner Losh 102308e3e3a7aSWarner Losh 102318e3e3a7aSWarner Losh<p> 102328e3e3a7aSWarner LoshReturns the current hook settings of the thread, as three values: 102338e3e3a7aSWarner Loshthe current hook function, the current hook mask, 102348e3e3a7aSWarner Loshand the current hook count 102358e3e3a7aSWarner Losh(as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). 102368e3e3a7aSWarner Losh 102378e3e3a7aSWarner Losh 102388e3e3a7aSWarner Losh 102398e3e3a7aSWarner Losh 102408e3e3a7aSWarner Losh<p> 102418e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> 102428e3e3a7aSWarner Losh 102438e3e3a7aSWarner Losh 102448e3e3a7aSWarner Losh<p> 102458e3e3a7aSWarner LoshReturns a table with information about a function. 102468e3e3a7aSWarner LoshYou can give the function directly 102478e3e3a7aSWarner Loshor you can give a number as the value of <code>f</code>, 102488e3e3a7aSWarner Loshwhich means the function running at level <code>f</code> of the call stack 102498e3e3a7aSWarner Loshof the given thread: 102508e3e3a7aSWarner Loshlevel 0 is the current function (<code>getinfo</code> itself); 102518e3e3a7aSWarner Loshlevel 1 is the function that called <code>getinfo</code> 102528e3e3a7aSWarner Losh(except for tail calls, which do not count on the stack); 102538e3e3a7aSWarner Loshand so on. 102548e3e3a7aSWarner LoshIf <code>f</code> is a number larger than the number of active functions, 102558e3e3a7aSWarner Loshthen <code>getinfo</code> returns <b>nil</b>. 102568e3e3a7aSWarner Losh 102578e3e3a7aSWarner Losh 102588e3e3a7aSWarner Losh<p> 102598e3e3a7aSWarner LoshThe returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, 102608e3e3a7aSWarner Loshwith the string <code>what</code> describing which fields to fill in. 102618e3e3a7aSWarner LoshThe default for <code>what</code> is to get all information available, 102628e3e3a7aSWarner Loshexcept the table of valid lines. 102638e3e3a7aSWarner LoshIf present, 102648e3e3a7aSWarner Loshthe option '<code>f</code>' 102658e3e3a7aSWarner Loshadds a field named <code>func</code> with the function itself. 102668e3e3a7aSWarner LoshIf present, 102678e3e3a7aSWarner Loshthe option '<code>L</code>' 102688e3e3a7aSWarner Loshadds a field named <code>activelines</code> with the table of 102698e3e3a7aSWarner Loshvalid lines. 102708e3e3a7aSWarner Losh 102718e3e3a7aSWarner Losh 102728e3e3a7aSWarner Losh<p> 102738e3e3a7aSWarner LoshFor instance, the expression <code>debug.getinfo(1,"n").name</code> returns 102748e3e3a7aSWarner Losha name for the current function, 102758e3e3a7aSWarner Loshif a reasonable name can be found, 102768e3e3a7aSWarner Loshand the expression <code>debug.getinfo(print)</code> 102778e3e3a7aSWarner Loshreturns a table with all available information 102788e3e3a7aSWarner Loshabout the <a href="#pdf-print"><code>print</code></a> function. 102798e3e3a7aSWarner Losh 102808e3e3a7aSWarner Losh 102818e3e3a7aSWarner Losh 102828e3e3a7aSWarner Losh 102838e3e3a7aSWarner Losh<p> 102848e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3> 102858e3e3a7aSWarner Losh 102868e3e3a7aSWarner Losh 102878e3e3a7aSWarner Losh<p> 102888e3e3a7aSWarner LoshThis function returns the name and the value of the local variable 102898e3e3a7aSWarner Loshwith index <code>local</code> of the function at level <code>f</code> of the stack. 102908e3e3a7aSWarner LoshThis function accesses not only explicit local variables, 102918e3e3a7aSWarner Loshbut also parameters, temporaries, etc. 102928e3e3a7aSWarner Losh 102938e3e3a7aSWarner Losh 102948e3e3a7aSWarner Losh<p> 102958e3e3a7aSWarner LoshThe first parameter or local variable has index 1, and so on, 102968e3e3a7aSWarner Loshfollowing the order that they are declared in the code, 102978e3e3a7aSWarner Loshcounting only the variables that are active 102988e3e3a7aSWarner Loshin the current scope of the function. 10299*e112e9d2SKyle EvansNegative indices refer to vararg arguments; 10300*e112e9d2SKyle Evans-1 is the first vararg argument. 103018e3e3a7aSWarner LoshThe function returns <b>nil</b> if there is no variable with the given index, 103028e3e3a7aSWarner Loshand raises an error when called with a level out of range. 103038e3e3a7aSWarner Losh(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) 103048e3e3a7aSWarner Losh 103058e3e3a7aSWarner Losh 103068e3e3a7aSWarner Losh<p> 103078e3e3a7aSWarner LoshVariable names starting with '<code>(</code>' (open parenthesis) 103088e3e3a7aSWarner Loshrepresent variables with no known names 103098e3e3a7aSWarner Losh(internal variables such as loop control variables, 103108e3e3a7aSWarner Loshand variables from chunks saved without debug information). 103118e3e3a7aSWarner Losh 103128e3e3a7aSWarner Losh 103138e3e3a7aSWarner Losh<p> 103148e3e3a7aSWarner LoshThe parameter <code>f</code> may also be a function. 103158e3e3a7aSWarner LoshIn that case, <code>getlocal</code> returns only the name of function parameters. 103168e3e3a7aSWarner Losh 103178e3e3a7aSWarner Losh 103188e3e3a7aSWarner Losh 103198e3e3a7aSWarner Losh 103208e3e3a7aSWarner Losh<p> 103218e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3> 103228e3e3a7aSWarner Losh 103238e3e3a7aSWarner Losh 103248e3e3a7aSWarner Losh<p> 103258e3e3a7aSWarner LoshReturns the metatable of the given <code>value</code> 103268e3e3a7aSWarner Loshor <b>nil</b> if it does not have a metatable. 103278e3e3a7aSWarner Losh 103288e3e3a7aSWarner Losh 103298e3e3a7aSWarner Losh 103308e3e3a7aSWarner Losh 103318e3e3a7aSWarner Losh<p> 103328e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> 103338e3e3a7aSWarner Losh 103348e3e3a7aSWarner Losh 103358e3e3a7aSWarner Losh<p> 103368e3e3a7aSWarner LoshReturns the registry table (see <a href="#4.5">§4.5</a>). 103378e3e3a7aSWarner Losh 103388e3e3a7aSWarner Losh 103398e3e3a7aSWarner Losh 103408e3e3a7aSWarner Losh 103418e3e3a7aSWarner Losh<p> 103428e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3> 103438e3e3a7aSWarner Losh 103448e3e3a7aSWarner Losh 103458e3e3a7aSWarner Losh<p> 103468e3e3a7aSWarner LoshThis function returns the name and the value of the upvalue 103478e3e3a7aSWarner Loshwith index <code>up</code> of the function <code>f</code>. 103488e3e3a7aSWarner LoshThe function returns <b>nil</b> if there is no upvalue with the given index. 103498e3e3a7aSWarner Losh 103508e3e3a7aSWarner Losh 103518e3e3a7aSWarner Losh<p> 103528e3e3a7aSWarner LoshVariable names starting with '<code>(</code>' (open parenthesis) 103538e3e3a7aSWarner Loshrepresent variables with no known names 103548e3e3a7aSWarner Losh(variables from chunks saved without debug information). 103558e3e3a7aSWarner Losh 103568e3e3a7aSWarner Losh 103578e3e3a7aSWarner Losh 103588e3e3a7aSWarner Losh 103598e3e3a7aSWarner Losh<p> 103608e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3> 103618e3e3a7aSWarner Losh 103628e3e3a7aSWarner Losh 103638e3e3a7aSWarner Losh<p> 103648e3e3a7aSWarner LoshReturns the Lua value associated to <code>u</code>. 103658e3e3a7aSWarner LoshIf <code>u</code> is not a full userdata, 103668e3e3a7aSWarner Loshreturns <b>nil</b>. 103678e3e3a7aSWarner Losh 103688e3e3a7aSWarner Losh 103698e3e3a7aSWarner Losh 103708e3e3a7aSWarner Losh 103718e3e3a7aSWarner Losh<p> 103728e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> 103738e3e3a7aSWarner Losh 103748e3e3a7aSWarner Losh 103758e3e3a7aSWarner Losh<p> 103768e3e3a7aSWarner LoshSets the given function as a hook. 103778e3e3a7aSWarner LoshThe string <code>mask</code> and the number <code>count</code> describe 103788e3e3a7aSWarner Loshwhen the hook will be called. 103798e3e3a7aSWarner LoshThe string mask may have any combination of the following characters, 103808e3e3a7aSWarner Loshwith the given meaning: 103818e3e3a7aSWarner Losh 103828e3e3a7aSWarner Losh<ul> 103838e3e3a7aSWarner Losh<li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li> 103848e3e3a7aSWarner Losh<li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li> 103858e3e3a7aSWarner Losh<li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li> 103868e3e3a7aSWarner Losh</ul><p> 103878e3e3a7aSWarner LoshMoreover, 103888e3e3a7aSWarner Loshwith a <code>count</code> different from zero, 103898e3e3a7aSWarner Loshthe hook is called also after every <code>count</code> instructions. 103908e3e3a7aSWarner Losh 103918e3e3a7aSWarner Losh 103928e3e3a7aSWarner Losh<p> 103938e3e3a7aSWarner LoshWhen called without arguments, 103948e3e3a7aSWarner Losh<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. 103958e3e3a7aSWarner Losh 103968e3e3a7aSWarner Losh 103978e3e3a7aSWarner Losh<p> 10398*e112e9d2SKyle EvansWhen the hook is called, its first argument is a string 103998e3e3a7aSWarner Loshdescribing the event that has triggered its call: 104008e3e3a7aSWarner Losh<code>"call"</code> (or <code>"tail call"</code>), 104018e3e3a7aSWarner Losh<code>"return"</code>, 104028e3e3a7aSWarner Losh<code>"line"</code>, and <code>"count"</code>. 104038e3e3a7aSWarner LoshFor line events, 104048e3e3a7aSWarner Loshthe hook also gets the new line number as its second parameter. 104058e3e3a7aSWarner LoshInside a hook, 104068e3e3a7aSWarner Loshyou can call <code>getinfo</code> with level 2 to get more information about 104078e3e3a7aSWarner Loshthe running function 104088e3e3a7aSWarner Losh(level 0 is the <code>getinfo</code> function, 104098e3e3a7aSWarner Loshand level 1 is the hook function). 104108e3e3a7aSWarner Losh 104118e3e3a7aSWarner Losh 104128e3e3a7aSWarner Losh 104138e3e3a7aSWarner Losh 104148e3e3a7aSWarner Losh<p> 104158e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> 104168e3e3a7aSWarner Losh 104178e3e3a7aSWarner Losh 104188e3e3a7aSWarner Losh<p> 104198e3e3a7aSWarner LoshThis function assigns the value <code>value</code> to the local variable 104208e3e3a7aSWarner Loshwith index <code>local</code> of the function at level <code>level</code> of the stack. 104218e3e3a7aSWarner LoshThe function returns <b>nil</b> if there is no local 104228e3e3a7aSWarner Loshvariable with the given index, 104238e3e3a7aSWarner Loshand raises an error when called with a <code>level</code> out of range. 104248e3e3a7aSWarner Losh(You can call <code>getinfo</code> to check whether the level is valid.) 104258e3e3a7aSWarner LoshOtherwise, it returns the name of the local variable. 104268e3e3a7aSWarner Losh 104278e3e3a7aSWarner Losh 104288e3e3a7aSWarner Losh<p> 104298e3e3a7aSWarner LoshSee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about 104308e3e3a7aSWarner Loshvariable indices and names. 104318e3e3a7aSWarner Losh 104328e3e3a7aSWarner Losh 104338e3e3a7aSWarner Losh 104348e3e3a7aSWarner Losh 104358e3e3a7aSWarner Losh<p> 104368e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> 104378e3e3a7aSWarner Losh 104388e3e3a7aSWarner Losh 104398e3e3a7aSWarner Losh<p> 104408e3e3a7aSWarner LoshSets the metatable for the given <code>value</code> to the given <code>table</code> 104418e3e3a7aSWarner Losh(which can be <b>nil</b>). 104428e3e3a7aSWarner LoshReturns <code>value</code>. 104438e3e3a7aSWarner Losh 104448e3e3a7aSWarner Losh 104458e3e3a7aSWarner Losh 104468e3e3a7aSWarner Losh 104478e3e3a7aSWarner Losh<p> 104488e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> 104498e3e3a7aSWarner Losh 104508e3e3a7aSWarner Losh 104518e3e3a7aSWarner Losh<p> 104528e3e3a7aSWarner LoshThis function assigns the value <code>value</code> to the upvalue 104538e3e3a7aSWarner Loshwith index <code>up</code> of the function <code>f</code>. 104548e3e3a7aSWarner LoshThe function returns <b>nil</b> if there is no upvalue 104558e3e3a7aSWarner Loshwith the given index. 104568e3e3a7aSWarner LoshOtherwise, it returns the name of the upvalue. 104578e3e3a7aSWarner Losh 104588e3e3a7aSWarner Losh 104598e3e3a7aSWarner Losh 104608e3e3a7aSWarner Losh 104618e3e3a7aSWarner Losh<p> 104628e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3> 104638e3e3a7aSWarner Losh 104648e3e3a7aSWarner Losh 104658e3e3a7aSWarner Losh<p> 104668e3e3a7aSWarner LoshSets the given <code>value</code> as 104678e3e3a7aSWarner Loshthe Lua value associated to the given <code>udata</code>. 104688e3e3a7aSWarner Losh<code>udata</code> must be a full userdata. 104698e3e3a7aSWarner Losh 104708e3e3a7aSWarner Losh 104718e3e3a7aSWarner Losh<p> 104728e3e3a7aSWarner LoshReturns <code>udata</code>. 104738e3e3a7aSWarner Losh 104748e3e3a7aSWarner Losh 104758e3e3a7aSWarner Losh 104768e3e3a7aSWarner Losh 104778e3e3a7aSWarner Losh<p> 104788e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> 104798e3e3a7aSWarner Losh 104808e3e3a7aSWarner Losh 104818e3e3a7aSWarner Losh<p> 104828e3e3a7aSWarner LoshIf <code>message</code> is present but is neither a string nor <b>nil</b>, 104838e3e3a7aSWarner Loshthis function returns <code>message</code> without further processing. 104848e3e3a7aSWarner LoshOtherwise, 104858e3e3a7aSWarner Loshit returns a string with a traceback of the call stack. 104868e3e3a7aSWarner LoshThe optional <code>message</code> string is appended 104878e3e3a7aSWarner Loshat the beginning of the traceback. 104888e3e3a7aSWarner LoshAn optional <code>level</code> number tells at which level 104898e3e3a7aSWarner Loshto start the traceback 104908e3e3a7aSWarner Losh(default is 1, the function calling <code>traceback</code>). 104918e3e3a7aSWarner Losh 104928e3e3a7aSWarner Losh 104938e3e3a7aSWarner Losh 104948e3e3a7aSWarner Losh 104958e3e3a7aSWarner Losh<p> 104968e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3> 104978e3e3a7aSWarner Losh 104988e3e3a7aSWarner Losh 104998e3e3a7aSWarner Losh<p> 105008e3e3a7aSWarner LoshReturns a unique identifier (as a light userdata) 105018e3e3a7aSWarner Loshfor the upvalue numbered <code>n</code> 105028e3e3a7aSWarner Loshfrom the given function. 105038e3e3a7aSWarner Losh 105048e3e3a7aSWarner Losh 105058e3e3a7aSWarner Losh<p> 105068e3e3a7aSWarner LoshThese unique identifiers allow a program to check whether different 105078e3e3a7aSWarner Loshclosures share upvalues. 105088e3e3a7aSWarner LoshLua closures that share an upvalue 105098e3e3a7aSWarner Losh(that is, that access a same external local variable) 105108e3e3a7aSWarner Loshwill return identical ids for those upvalue indices. 105118e3e3a7aSWarner Losh 105128e3e3a7aSWarner Losh 105138e3e3a7aSWarner Losh 105148e3e3a7aSWarner Losh 105158e3e3a7aSWarner Losh<p> 105168e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3> 105178e3e3a7aSWarner Losh 105188e3e3a7aSWarner Losh 105198e3e3a7aSWarner Losh<p> 105208e3e3a7aSWarner LoshMake the <code>n1</code>-th upvalue of the Lua closure <code>f1</code> 105218e3e3a7aSWarner Loshrefer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>. 105228e3e3a7aSWarner Losh 105238e3e3a7aSWarner Losh 105248e3e3a7aSWarner Losh 105258e3e3a7aSWarner Losh 105268e3e3a7aSWarner Losh 105278e3e3a7aSWarner Losh 105288e3e3a7aSWarner Losh 105298e3e3a7aSWarner Losh<h1>7 – <a name="7">Lua Standalone</a></h1> 105308e3e3a7aSWarner Losh 105318e3e3a7aSWarner Losh<p> 105328e3e3a7aSWarner LoshAlthough Lua has been designed as an extension language, 105338e3e3a7aSWarner Loshto be embedded in a host C program, 105348e3e3a7aSWarner Loshit is also frequently used as a standalone language. 105358e3e3a7aSWarner LoshAn interpreter for Lua as a standalone language, 105368e3e3a7aSWarner Loshcalled simply <code>lua</code>, 105378e3e3a7aSWarner Loshis provided with the standard distribution. 105388e3e3a7aSWarner LoshThe standalone interpreter includes 105398e3e3a7aSWarner Loshall standard libraries, including the debug library. 105408e3e3a7aSWarner LoshIts usage is: 105418e3e3a7aSWarner Losh 105428e3e3a7aSWarner Losh<pre> 105438e3e3a7aSWarner Losh lua [options] [script [args]] 105448e3e3a7aSWarner Losh</pre><p> 105458e3e3a7aSWarner LoshThe options are: 105468e3e3a7aSWarner Losh 105478e3e3a7aSWarner Losh<ul> 105488e3e3a7aSWarner Losh<li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li> 10549*e112e9d2SKyle Evans<li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em> and assigns the 10550*e112e9d2SKyle Evans result to global @<em>mod</em>;</li> 105518e3e3a7aSWarner Losh<li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li> 105528e3e3a7aSWarner Losh<li><b><code>-v</code>: </b> prints version information;</li> 105538e3e3a7aSWarner Losh<li><b><code>-E</code>: </b> ignores environment variables;</li> 105548e3e3a7aSWarner Losh<li><b><code>--</code>: </b> stops handling options;</li> 105558e3e3a7aSWarner Losh<li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li> 105568e3e3a7aSWarner Losh</ul><p> 105578e3e3a7aSWarner LoshAfter handling its options, <code>lua</code> runs the given <em>script</em>. 105588e3e3a7aSWarner LoshWhen called without arguments, 105598e3e3a7aSWarner Losh<code>lua</code> behaves as <code>lua -v -i</code> 105608e3e3a7aSWarner Loshwhen the standard input (<code>stdin</code>) is a terminal, 105618e3e3a7aSWarner Loshand as <code>lua -</code> otherwise. 105628e3e3a7aSWarner Losh 105638e3e3a7aSWarner Losh 105648e3e3a7aSWarner Losh<p> 105658e3e3a7aSWarner LoshWhen called without option <code>-E</code>, 105668e3e3a7aSWarner Loshthe interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a> 105678e3e3a7aSWarner Losh(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined) 105688e3e3a7aSWarner Loshbefore running any argument. 105698e3e3a7aSWarner LoshIf the variable content has the format <code>@<em>filename</em></code>, 105708e3e3a7aSWarner Loshthen <code>lua</code> executes the file. 105718e3e3a7aSWarner LoshOtherwise, <code>lua</code> executes the string itself. 105728e3e3a7aSWarner Losh 105738e3e3a7aSWarner Losh 105748e3e3a7aSWarner Losh<p> 105758e3e3a7aSWarner LoshWhen called with option <code>-E</code>, 105768e3e3a7aSWarner Loshbesides ignoring <code>LUA_INIT</code>, 105778e3e3a7aSWarner LoshLua also ignores 105788e3e3a7aSWarner Loshthe values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>, 105798e3e3a7aSWarner Loshsetting the values of 105808e3e3a7aSWarner Losh<a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a> 105818e3e3a7aSWarner Loshwith the default paths defined in <code>luaconf.h</code>. 105828e3e3a7aSWarner Losh 105838e3e3a7aSWarner Losh 105848e3e3a7aSWarner Losh<p> 105858e3e3a7aSWarner LoshAll options are handled in order, except <code>-i</code> and <code>-E</code>. 105868e3e3a7aSWarner LoshFor instance, an invocation like 105878e3e3a7aSWarner Losh 105888e3e3a7aSWarner Losh<pre> 105898e3e3a7aSWarner Losh $ lua -e'a=1' -e 'print(a)' script.lua 105908e3e3a7aSWarner Losh</pre><p> 105918e3e3a7aSWarner Loshwill first set <code>a</code> to 1, then print the value of <code>a</code>, 105928e3e3a7aSWarner Loshand finally run the file <code>script.lua</code> with no arguments. 105938e3e3a7aSWarner Losh(Here <code>$</code> is the shell prompt. Your prompt may be different.) 105948e3e3a7aSWarner Losh 105958e3e3a7aSWarner Losh 105968e3e3a7aSWarner Losh<p> 105978e3e3a7aSWarner LoshBefore running any code, 105988e3e3a7aSWarner Losh<code>lua</code> collects all command-line arguments 105998e3e3a7aSWarner Loshin a global table called <code>arg</code>. 106008e3e3a7aSWarner LoshThe script name goes to index 0, 106018e3e3a7aSWarner Loshthe first argument after the script name goes to index 1, 106028e3e3a7aSWarner Loshand so on. 106038e3e3a7aSWarner LoshAny arguments before the script name 106048e3e3a7aSWarner Losh(that is, the interpreter name plus its options) 106058e3e3a7aSWarner Loshgo to negative indices. 106068e3e3a7aSWarner LoshFor instance, in the call 106078e3e3a7aSWarner Losh 106088e3e3a7aSWarner Losh<pre> 106098e3e3a7aSWarner Losh $ lua -la b.lua t1 t2 106108e3e3a7aSWarner Losh</pre><p> 106118e3e3a7aSWarner Loshthe table is like this: 106128e3e3a7aSWarner Losh 106138e3e3a7aSWarner Losh<pre> 106148e3e3a7aSWarner Losh arg = { [-2] = "lua", [-1] = "-la", 106158e3e3a7aSWarner Losh [0] = "b.lua", 106168e3e3a7aSWarner Losh [1] = "t1", [2] = "t2" } 106178e3e3a7aSWarner Losh</pre><p> 106188e3e3a7aSWarner LoshIf there is no script in the call, 106198e3e3a7aSWarner Loshthe interpreter name goes to index 0, 106208e3e3a7aSWarner Loshfollowed by the other arguments. 106218e3e3a7aSWarner LoshFor instance, the call 106228e3e3a7aSWarner Losh 106238e3e3a7aSWarner Losh<pre> 106248e3e3a7aSWarner Losh $ lua -e "print(arg[1])" 106258e3e3a7aSWarner Losh</pre><p> 106268e3e3a7aSWarner Loshwill print "<code>-e</code>". 106278e3e3a7aSWarner LoshIf there is a script, 10628*e112e9d2SKyle Evansthe script is called with arguments 106298e3e3a7aSWarner Losh<code>arg[1]</code>, ···, <code>arg[#arg]</code>. 106308e3e3a7aSWarner Losh(Like all chunks in Lua, 106318e3e3a7aSWarner Loshthe script is compiled as a vararg function.) 106328e3e3a7aSWarner Losh 106338e3e3a7aSWarner Losh 106348e3e3a7aSWarner Losh<p> 106358e3e3a7aSWarner LoshIn interactive mode, 106368e3e3a7aSWarner LoshLua repeatedly prompts and waits for a line. 106378e3e3a7aSWarner LoshAfter reading a line, 106388e3e3a7aSWarner LoshLua first try to interpret the line as an expression. 106398e3e3a7aSWarner LoshIf it succeeds, it prints its value. 106408e3e3a7aSWarner LoshOtherwise, it interprets the line as a statement. 106418e3e3a7aSWarner LoshIf you write an incomplete statement, 106428e3e3a7aSWarner Loshthe interpreter waits for its completion 106438e3e3a7aSWarner Loshby issuing a different prompt. 106448e3e3a7aSWarner Losh 106458e3e3a7aSWarner Losh 106468e3e3a7aSWarner Losh<p> 106478e3e3a7aSWarner LoshIf the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, 106488e3e3a7aSWarner Loshthen its value is used as the prompt. 106498e3e3a7aSWarner LoshSimilarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, 106508e3e3a7aSWarner Loshits value is used as the secondary prompt 106518e3e3a7aSWarner Losh(issued during incomplete statements). 106528e3e3a7aSWarner Losh 106538e3e3a7aSWarner Losh 106548e3e3a7aSWarner Losh<p> 106558e3e3a7aSWarner LoshIn case of unprotected errors in the script, 106568e3e3a7aSWarner Loshthe interpreter reports the error to the standard error stream. 106578e3e3a7aSWarner LoshIf the error object is not a string but 106588e3e3a7aSWarner Loshhas a metamethod <code>__tostring</code>, 106598e3e3a7aSWarner Loshthe interpreter calls this metamethod to produce the final message. 106608e3e3a7aSWarner LoshOtherwise, the interpreter converts the error object to a string 106618e3e3a7aSWarner Loshand adds a stack traceback to it. 106628e3e3a7aSWarner Losh 106638e3e3a7aSWarner Losh 106648e3e3a7aSWarner Losh<p> 106658e3e3a7aSWarner LoshWhen finishing normally, 106668e3e3a7aSWarner Loshthe interpreter closes its main Lua state 106678e3e3a7aSWarner Losh(see <a href="#lua_close"><code>lua_close</code></a>). 106688e3e3a7aSWarner LoshThe script can avoid this step by 106698e3e3a7aSWarner Loshcalling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate. 106708e3e3a7aSWarner Losh 106718e3e3a7aSWarner Losh 106728e3e3a7aSWarner Losh<p> 106738e3e3a7aSWarner LoshTo allow the use of Lua as a 106748e3e3a7aSWarner Loshscript interpreter in Unix systems, 106758e3e3a7aSWarner Loshthe standalone interpreter skips 106768e3e3a7aSWarner Loshthe first line of a chunk if it starts with <code>#</code>. 106778e3e3a7aSWarner LoshTherefore, Lua scripts can be made into executable programs 106788e3e3a7aSWarner Loshby using <code>chmod +x</code> and the <code>#!</code> form, 106798e3e3a7aSWarner Loshas in 106808e3e3a7aSWarner Losh 106818e3e3a7aSWarner Losh<pre> 106828e3e3a7aSWarner Losh #!/usr/local/bin/lua 106838e3e3a7aSWarner Losh</pre><p> 106848e3e3a7aSWarner Losh(Of course, 106858e3e3a7aSWarner Loshthe location of the Lua interpreter may be different in your machine. 106868e3e3a7aSWarner LoshIf <code>lua</code> is in your <code>PATH</code>, 106878e3e3a7aSWarner Loshthen 106888e3e3a7aSWarner Losh 106898e3e3a7aSWarner Losh<pre> 106908e3e3a7aSWarner Losh #!/usr/bin/env lua 106918e3e3a7aSWarner Losh</pre><p> 106928e3e3a7aSWarner Loshis a more portable solution.) 106938e3e3a7aSWarner Losh 106948e3e3a7aSWarner Losh 106958e3e3a7aSWarner Losh 106968e3e3a7aSWarner Losh<h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> 106978e3e3a7aSWarner Losh 106988e3e3a7aSWarner Losh<p> 106998e3e3a7aSWarner LoshHere we list the incompatibilities that you may find when moving a program 107008e3e3a7aSWarner Loshfrom Lua 5.2 to Lua 5.3. 107018e3e3a7aSWarner LoshYou can avoid some incompatibilities by compiling Lua with 107028e3e3a7aSWarner Loshappropriate options (see file <code>luaconf.h</code>). 107038e3e3a7aSWarner LoshHowever, 107048e3e3a7aSWarner Loshall these compatibility options will be removed in the future. 107058e3e3a7aSWarner Losh 107068e3e3a7aSWarner Losh 107078e3e3a7aSWarner Losh<p> 107088e3e3a7aSWarner LoshLua versions can always change the C API in ways that 107098e3e3a7aSWarner Loshdo not imply source-code changes in a program, 107108e3e3a7aSWarner Loshsuch as the numeric values for constants 107118e3e3a7aSWarner Loshor the implementation of functions as macros. 107128e3e3a7aSWarner LoshTherefore, 107138e3e3a7aSWarner Loshyou should not assume that binaries are compatible between 107148e3e3a7aSWarner Loshdifferent Lua versions. 107158e3e3a7aSWarner LoshAlways recompile clients of the Lua API when 107168e3e3a7aSWarner Loshusing a new version. 107178e3e3a7aSWarner Losh 107188e3e3a7aSWarner Losh 107198e3e3a7aSWarner Losh<p> 107208e3e3a7aSWarner LoshSimilarly, Lua versions can always change the internal representation 107218e3e3a7aSWarner Loshof precompiled chunks; 107228e3e3a7aSWarner Loshprecompiled chunks are not compatible between different Lua versions. 107238e3e3a7aSWarner Losh 107248e3e3a7aSWarner Losh 107258e3e3a7aSWarner Losh<p> 107268e3e3a7aSWarner LoshThe standard paths in the official distribution may 107278e3e3a7aSWarner Loshchange between versions. 107288e3e3a7aSWarner Losh 107298e3e3a7aSWarner Losh 107308e3e3a7aSWarner Losh 107318e3e3a7aSWarner Losh<h2>8.1 – <a name="8.1">Changes in the Language</a></h2> 107328e3e3a7aSWarner Losh<ul> 107338e3e3a7aSWarner Losh 107348e3e3a7aSWarner Losh<li> 107358e3e3a7aSWarner LoshThe main difference between Lua 5.2 and Lua 5.3 is the 107368e3e3a7aSWarner Loshintroduction of an integer subtype for numbers. 107378e3e3a7aSWarner LoshAlthough this change should not affect "normal" computations, 107388e3e3a7aSWarner Loshsome computations 107398e3e3a7aSWarner Losh(mainly those that involve some kind of overflow) 107408e3e3a7aSWarner Loshcan give different results. 107418e3e3a7aSWarner Losh 107428e3e3a7aSWarner Losh 107438e3e3a7aSWarner Losh<p> 107448e3e3a7aSWarner LoshYou can fix these differences by forcing a number to be a float 107458e3e3a7aSWarner Losh(in Lua 5.2 all numbers were float), 107468e3e3a7aSWarner Loshin particular writing constants with an ending <code>.0</code> 107478e3e3a7aSWarner Loshor using <code>x = x + 0.0</code> to convert a variable. 107488e3e3a7aSWarner Losh(This recommendation is only for a quick fix 107498e3e3a7aSWarner Loshfor an occasional incompatibility; 107508e3e3a7aSWarner Loshit is not a general guideline for good programming. 107518e3e3a7aSWarner LoshFor good programming, 107528e3e3a7aSWarner Loshuse floats where you need floats 107538e3e3a7aSWarner Loshand integers where you need integers.) 107548e3e3a7aSWarner Losh</li> 107558e3e3a7aSWarner Losh 107568e3e3a7aSWarner Losh<li> 107578e3e3a7aSWarner LoshThe conversion of a float to a string now adds a <code>.0</code> suffix 107588e3e3a7aSWarner Loshto the result if it looks like an integer. 107598e3e3a7aSWarner Losh(For instance, the float 2.0 will be printed as <code>2.0</code>, 107608e3e3a7aSWarner Loshnot as <code>2</code>.) 107618e3e3a7aSWarner LoshYou should always use an explicit format 107628e3e3a7aSWarner Loshwhen you need a specific format for numbers. 107638e3e3a7aSWarner Losh 107648e3e3a7aSWarner Losh 107658e3e3a7aSWarner Losh<p> 107668e3e3a7aSWarner Losh(Formally this is not an incompatibility, 107678e3e3a7aSWarner Loshbecause Lua does not specify how numbers are formatted as strings, 107688e3e3a7aSWarner Loshbut some programs assumed a specific format.) 107698e3e3a7aSWarner Losh</li> 107708e3e3a7aSWarner Losh 107718e3e3a7aSWarner Losh<li> 107728e3e3a7aSWarner LoshThe generational mode for the garbage collector was removed. 107738e3e3a7aSWarner Losh(It was an experimental feature in Lua 5.2.) 107748e3e3a7aSWarner Losh</li> 107758e3e3a7aSWarner Losh 107768e3e3a7aSWarner Losh</ul> 107778e3e3a7aSWarner Losh 107788e3e3a7aSWarner Losh 107798e3e3a7aSWarner Losh 107808e3e3a7aSWarner Losh 107818e3e3a7aSWarner Losh<h2>8.2 – <a name="8.2">Changes in the Libraries</a></h2> 107828e3e3a7aSWarner Losh<ul> 107838e3e3a7aSWarner Losh 107848e3e3a7aSWarner Losh<li> 107858e3e3a7aSWarner LoshThe <code>bit32</code> library has been deprecated. 107868e3e3a7aSWarner LoshIt is easy to require a compatible external library or, 107878e3e3a7aSWarner Loshbetter yet, to replace its functions with appropriate bitwise operations. 107888e3e3a7aSWarner Losh(Keep in mind that <code>bit32</code> operates on 32-bit integers, 107898e3e3a7aSWarner Loshwhile the bitwise operators in Lua 5.3 operate on Lua integers, 107908e3e3a7aSWarner Loshwhich by default have 64 bits.) 107918e3e3a7aSWarner Losh</li> 107928e3e3a7aSWarner Losh 107938e3e3a7aSWarner Losh<li> 107948e3e3a7aSWarner LoshThe Table library now respects metamethods 107958e3e3a7aSWarner Loshfor setting and getting elements. 107968e3e3a7aSWarner Losh</li> 107978e3e3a7aSWarner Losh 107988e3e3a7aSWarner Losh<li> 107998e3e3a7aSWarner LoshThe <a href="#pdf-ipairs"><code>ipairs</code></a> iterator now respects metamethods and 108008e3e3a7aSWarner Loshits <code>__ipairs</code> metamethod has been deprecated. 108018e3e3a7aSWarner Losh</li> 108028e3e3a7aSWarner Losh 108038e3e3a7aSWarner Losh<li> 108048e3e3a7aSWarner LoshOption names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore. 108058e3e3a7aSWarner LoshFor compatibility, Lua will continue to accept (and ignore) this character. 108068e3e3a7aSWarner Losh</li> 108078e3e3a7aSWarner Losh 108088e3e3a7aSWarner Losh<li> 108098e3e3a7aSWarner LoshThe following functions were deprecated in the mathematical library: 108108e3e3a7aSWarner Losh<code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>, 108118e3e3a7aSWarner Losh<code>frexp</code>, and <code>ldexp</code>. 108128e3e3a7aSWarner LoshYou can replace <code>math.pow(x,y)</code> with <code>x^y</code>; 108138e3e3a7aSWarner Loshyou can replace <code>math.atan2</code> with <code>math.atan</code>, 10814*e112e9d2SKyle Evanswhich now accepts one or two arguments; 108158e3e3a7aSWarner Loshyou can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>. 108168e3e3a7aSWarner LoshFor the other operations, 108178e3e3a7aSWarner Loshyou can either use an external library or 108188e3e3a7aSWarner Loshimplement them in Lua. 108198e3e3a7aSWarner Losh</li> 108208e3e3a7aSWarner Losh 108218e3e3a7aSWarner Losh<li> 108228e3e3a7aSWarner LoshThe searcher for C loaders used by <a href="#pdf-require"><code>require</code></a> 108238e3e3a7aSWarner Loshchanged the way it handles versioned names. 108248e3e3a7aSWarner LoshNow, the version should come after the module name 108258e3e3a7aSWarner Losh(as is usual in most other tools). 108268e3e3a7aSWarner LoshFor compatibility, that searcher still tries the old format 108278e3e3a7aSWarner Loshif it cannot find an open function according to the new style. 108288e3e3a7aSWarner Losh(Lua 5.2 already worked that way, 108298e3e3a7aSWarner Loshbut it did not document the change.) 108308e3e3a7aSWarner Losh</li> 108318e3e3a7aSWarner Losh 108328e3e3a7aSWarner Losh<li> 108338e3e3a7aSWarner LoshThe call <code>collectgarbage("count")</code> now returns only one result. 108348e3e3a7aSWarner Losh(You can compute that second result from the fractional part 108358e3e3a7aSWarner Loshof the first result.) 108368e3e3a7aSWarner Losh</li> 108378e3e3a7aSWarner Losh 108388e3e3a7aSWarner Losh</ul> 108398e3e3a7aSWarner Losh 108408e3e3a7aSWarner Losh 108418e3e3a7aSWarner Losh 108428e3e3a7aSWarner Losh 108438e3e3a7aSWarner Losh<h2>8.3 – <a name="8.3">Changes in the API</a></h2> 108448e3e3a7aSWarner Losh 108458e3e3a7aSWarner Losh 108468e3e3a7aSWarner Losh<ul> 108478e3e3a7aSWarner Losh 108488e3e3a7aSWarner Losh<li> 10849*e112e9d2SKyle EvansContinuation functions now receive as arguments what they needed 108508e3e3a7aSWarner Loshto get through <code>lua_getctx</code>, 108518e3e3a7aSWarner Loshso <code>lua_getctx</code> has been removed. 108528e3e3a7aSWarner LoshAdapt your code accordingly. 108538e3e3a7aSWarner Losh</li> 108548e3e3a7aSWarner Losh 108558e3e3a7aSWarner Losh<li> 108568e3e3a7aSWarner LoshFunction <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>. 108578e3e3a7aSWarner LoshUse 0 as the value of this parameter to get the old behavior. 108588e3e3a7aSWarner Losh</li> 108598e3e3a7aSWarner Losh 108608e3e3a7aSWarner Losh<li> 108618e3e3a7aSWarner LoshFunctions to inject/project unsigned integers 108628e3e3a7aSWarner Losh(<code>lua_pushunsigned</code>, <code>lua_tounsigned</code>, <code>lua_tounsignedx</code>, 108638e3e3a7aSWarner Losh<code>luaL_checkunsigned</code>, <code>luaL_optunsigned</code>) 108648e3e3a7aSWarner Loshwere deprecated. 108658e3e3a7aSWarner LoshUse their signed equivalents with a type cast. 108668e3e3a7aSWarner Losh</li> 108678e3e3a7aSWarner Losh 108688e3e3a7aSWarner Losh<li> 108698e3e3a7aSWarner LoshMacros to project non-default integer types 108708e3e3a7aSWarner Losh(<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>) 108718e3e3a7aSWarner Loshwere deprecated. 108728e3e3a7aSWarner LoshUse their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast 108738e3e3a7aSWarner Losh(or, when possible, use <a href="#lua_Integer"><code>lua_Integer</code></a> in your code). 108748e3e3a7aSWarner Losh</li> 108758e3e3a7aSWarner Losh 108768e3e3a7aSWarner Losh</ul> 108778e3e3a7aSWarner Losh 108788e3e3a7aSWarner Losh 108798e3e3a7aSWarner Losh 108808e3e3a7aSWarner Losh 108818e3e3a7aSWarner Losh<h1>9 – <a name="9">The Complete Syntax of Lua</a></h1> 108828e3e3a7aSWarner Losh 108838e3e3a7aSWarner Losh<p> 108848e3e3a7aSWarner LoshHere is the complete syntax of Lua in extended BNF. 108858e3e3a7aSWarner LoshAs usual in extended BNF, 108868e3e3a7aSWarner Losh{A} means 0 or more As, 108878e3e3a7aSWarner Loshand [A] means an optional A. 108888e3e3a7aSWarner Losh(For operator precedences, see <a href="#3.4.8">§3.4.8</a>; 108898e3e3a7aSWarner Loshfor a description of the terminals 108908e3e3a7aSWarner LoshName, Numeral, 108918e3e3a7aSWarner Loshand LiteralString, see <a href="#3.1">§3.1</a>.) 108928e3e3a7aSWarner Losh 108938e3e3a7aSWarner Losh 108948e3e3a7aSWarner Losh 108958e3e3a7aSWarner Losh 108968e3e3a7aSWarner Losh<pre> 108978e3e3a7aSWarner Losh 108988e3e3a7aSWarner Losh chunk ::= block 108998e3e3a7aSWarner Losh 109008e3e3a7aSWarner Losh block ::= {stat} [retstat] 109018e3e3a7aSWarner Losh 109028e3e3a7aSWarner Losh stat ::= ‘<b>;</b>’ | 109038e3e3a7aSWarner Losh varlist ‘<b>=</b>’ explist | 109048e3e3a7aSWarner Losh functioncall | 109058e3e3a7aSWarner Losh label | 109068e3e3a7aSWarner Losh <b>break</b> | 109078e3e3a7aSWarner Losh <b>goto</b> Name | 109088e3e3a7aSWarner Losh <b>do</b> block <b>end</b> | 109098e3e3a7aSWarner Losh <b>while</b> exp <b>do</b> block <b>end</b> | 109108e3e3a7aSWarner Losh <b>repeat</b> block <b>until</b> exp | 109118e3e3a7aSWarner Losh <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 109128e3e3a7aSWarner Losh <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> | 109138e3e3a7aSWarner Losh <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 109148e3e3a7aSWarner Losh <b>function</b> funcname funcbody | 109158e3e3a7aSWarner Losh <b>local</b> <b>function</b> Name funcbody | 109168e3e3a7aSWarner Losh <b>local</b> namelist [‘<b>=</b>’ explist] 109178e3e3a7aSWarner Losh 109188e3e3a7aSWarner Losh retstat ::= <b>return</b> [explist] [‘<b>;</b>’] 109198e3e3a7aSWarner Losh 109208e3e3a7aSWarner Losh label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 109218e3e3a7aSWarner Losh 109228e3e3a7aSWarner Losh funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 109238e3e3a7aSWarner Losh 109248e3e3a7aSWarner Losh varlist ::= var {‘<b>,</b>’ var} 109258e3e3a7aSWarner Losh 109268e3e3a7aSWarner Losh var ::= Name | prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | prefixexp ‘<b>.</b>’ Name 109278e3e3a7aSWarner Losh 109288e3e3a7aSWarner Losh namelist ::= Name {‘<b>,</b>’ Name} 109298e3e3a7aSWarner Losh 109308e3e3a7aSWarner Losh explist ::= exp {‘<b>,</b>’ exp} 109318e3e3a7aSWarner Losh 109328e3e3a7aSWarner Losh exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | ‘<b>...</b>’ | functiondef | 109338e3e3a7aSWarner Losh prefixexp | tableconstructor | exp binop exp | unop exp 109348e3e3a7aSWarner Losh 109358e3e3a7aSWarner Losh prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 109368e3e3a7aSWarner Losh 109378e3e3a7aSWarner Losh functioncall ::= prefixexp args | prefixexp ‘<b>:</b>’ Name args 109388e3e3a7aSWarner Losh 109398e3e3a7aSWarner Losh args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | tableconstructor | LiteralString 109408e3e3a7aSWarner Losh 109418e3e3a7aSWarner Losh functiondef ::= <b>function</b> funcbody 109428e3e3a7aSWarner Losh 109438e3e3a7aSWarner Losh funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 109448e3e3a7aSWarner Losh 109458e3e3a7aSWarner Losh parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 109468e3e3a7aSWarner Losh 109478e3e3a7aSWarner Losh tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 109488e3e3a7aSWarner Losh 109498e3e3a7aSWarner Losh fieldlist ::= field {fieldsep field} [fieldsep] 109508e3e3a7aSWarner Losh 109518e3e3a7aSWarner Losh field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 109528e3e3a7aSWarner Losh 109538e3e3a7aSWarner Losh fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 109548e3e3a7aSWarner Losh 109558e3e3a7aSWarner Losh binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</b>’ | ‘<b>//</b>’ | ‘<b>^</b>’ | ‘<b>%</b>’ | 109568e3e3a7aSWarner Losh ‘<b>&</b>’ | ‘<b>~</b>’ | ‘<b>|</b>’ | ‘<b>>></b>’ | ‘<b><<</b>’ | ‘<b>..</b>’ | 109578e3e3a7aSWarner Losh ‘<b><</b>’ | ‘<b><=</b>’ | ‘<b>></b>’ | ‘<b>>=</b>’ | ‘<b>==</b>’ | ‘<b>~=</b>’ | 109588e3e3a7aSWarner Losh <b>and</b> | <b>or</b> 109598e3e3a7aSWarner Losh 109608e3e3a7aSWarner Losh unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’ | ‘<b>~</b>’ 109618e3e3a7aSWarner Losh 109628e3e3a7aSWarner Losh</pre> 109638e3e3a7aSWarner Losh 109648e3e3a7aSWarner Losh<p> 109658e3e3a7aSWarner Losh 109668e3e3a7aSWarner Losh 109678e3e3a7aSWarner Losh 109688e3e3a7aSWarner Losh 109698e3e3a7aSWarner Losh 109708e3e3a7aSWarner Losh 109718e3e3a7aSWarner Losh 10972*e112e9d2SKyle Evans 109738e3e3a7aSWarner Losh<P CLASS="footer"> 109748e3e3a7aSWarner LoshLast update: 10975*e112e9d2SKyle EvansTue Jun 26 13:16:37 -03 2018 109768e3e3a7aSWarner Losh</P> 109778e3e3a7aSWarner Losh<!-- 10978*e112e9d2SKyle EvansLast change: revised for Lua 5.3.5 109798e3e3a7aSWarner Losh--> 109808e3e3a7aSWarner Losh 109818e3e3a7aSWarner Losh</body></html> 109828e3e3a7aSWarner Losh 10983
