1*8e3e3a7aSWarner Losh<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2*8e3e3a7aSWarner Losh<HTML> 3*8e3e3a7aSWarner Losh<HEAD> 4*8e3e3a7aSWarner Losh<TITLE>Lua 5.3 Reference Manual</TITLE> 5*8e3e3a7aSWarner Losh<LINK REL="stylesheet" TYPE="text/css" HREF="lua.css"> 6*8e3e3a7aSWarner Losh<LINK REL="stylesheet" TYPE="text/css" HREF="manual.css"> 7*8e3e3a7aSWarner Losh<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> 8*8e3e3a7aSWarner Losh</HEAD> 9*8e3e3a7aSWarner Losh 10*8e3e3a7aSWarner Losh<BODY> 11*8e3e3a7aSWarner Losh 12*8e3e3a7aSWarner Losh<H1> 13*8e3e3a7aSWarner Losh<A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A> 14*8e3e3a7aSWarner LoshLua 5.3 Reference Manual 15*8e3e3a7aSWarner Losh</H1> 16*8e3e3a7aSWarner Losh 17*8e3e3a7aSWarner Losh<P> 18*8e3e3a7aSWarner Loshby Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes 19*8e3e3a7aSWarner Losh 20*8e3e3a7aSWarner Losh<P> 21*8e3e3a7aSWarner Losh<SMALL> 22*8e3e3a7aSWarner LoshCopyright © 2015–2017 Lua.org, PUC-Rio. 23*8e3e3a7aSWarner LoshFreely available under the terms of the 24*8e3e3a7aSWarner Losh<a href="http://www.lua.org/license.html">Lua license</a>. 25*8e3e3a7aSWarner Losh</SMALL> 26*8e3e3a7aSWarner Losh 27*8e3e3a7aSWarner Losh<DIV CLASS="menubar"> 28*8e3e3a7aSWarner Losh<A HREF="contents.html#contents">contents</A> 29*8e3e3a7aSWarner Losh· 30*8e3e3a7aSWarner Losh<A HREF="contents.html#index">index</A> 31*8e3e3a7aSWarner Losh· 32*8e3e3a7aSWarner Losh<A HREF="http://www.lua.org/manual/">other versions</A> 33*8e3e3a7aSWarner Losh</DIV> 34*8e3e3a7aSWarner Losh 35*8e3e3a7aSWarner Losh<!-- ====================================================================== --> 36*8e3e3a7aSWarner Losh<p> 37*8e3e3a7aSWarner Losh 38*8e3e3a7aSWarner Losh<!-- $Id: manual.of,v 1.167 2017/01/09 15:18:11 roberto Exp $ --> 39*8e3e3a7aSWarner Losh 40*8e3e3a7aSWarner Losh 41*8e3e3a7aSWarner Losh 42*8e3e3a7aSWarner Losh 43*8e3e3a7aSWarner Losh<h1>1 – <a name="1">Introduction</a></h1> 44*8e3e3a7aSWarner Losh 45*8e3e3a7aSWarner Losh<p> 46*8e3e3a7aSWarner LoshLua is a powerful, efficient, lightweight, embeddable scripting language. 47*8e3e3a7aSWarner LoshIt supports procedural programming, 48*8e3e3a7aSWarner Loshobject-oriented programming, functional programming, 49*8e3e3a7aSWarner Loshdata-driven programming, and data description. 50*8e3e3a7aSWarner Losh 51*8e3e3a7aSWarner Losh 52*8e3e3a7aSWarner Losh<p> 53*8e3e3a7aSWarner LoshLua combines simple procedural syntax with powerful data description 54*8e3e3a7aSWarner Loshconstructs based on associative arrays and extensible semantics. 55*8e3e3a7aSWarner LoshLua is dynamically typed, 56*8e3e3a7aSWarner Loshruns by interpreting bytecode with a register-based 57*8e3e3a7aSWarner Loshvirtual machine, 58*8e3e3a7aSWarner Loshand has automatic memory management with 59*8e3e3a7aSWarner Loshincremental garbage collection, 60*8e3e3a7aSWarner Loshmaking it ideal for configuration, scripting, 61*8e3e3a7aSWarner Loshand rapid prototyping. 62*8e3e3a7aSWarner Losh 63*8e3e3a7aSWarner Losh 64*8e3e3a7aSWarner Losh<p> 65*8e3e3a7aSWarner LoshLua is implemented as a library, written in <em>clean C</em>, 66*8e3e3a7aSWarner Loshthe common subset of Standard C and C++. 67*8e3e3a7aSWarner LoshThe Lua distribution includes a host program called <code>lua</code>, 68*8e3e3a7aSWarner Loshwhich uses the Lua library to offer a complete, 69*8e3e3a7aSWarner Loshstandalone Lua interpreter, 70*8e3e3a7aSWarner Loshfor interactive or batch use. 71*8e3e3a7aSWarner LoshLua is intended to be used both as a powerful, lightweight, 72*8e3e3a7aSWarner Loshembeddable scripting language for any program that needs one, 73*8e3e3a7aSWarner Loshand as a powerful but lightweight and efficient stand-alone language. 74*8e3e3a7aSWarner Losh 75*8e3e3a7aSWarner Losh 76*8e3e3a7aSWarner Losh<p> 77*8e3e3a7aSWarner LoshAs an extension language, Lua has no notion of a "main" program: 78*8e3e3a7aSWarner Loshit works <em>embedded</em> in a host client, 79*8e3e3a7aSWarner Loshcalled the <em>embedding program</em> or simply the <em>host</em>. 80*8e3e3a7aSWarner Losh(Frequently, this host is the stand-alone <code>lua</code> program.) 81*8e3e3a7aSWarner LoshThe host program can invoke functions to execute a piece of Lua code, 82*8e3e3a7aSWarner Loshcan write and read Lua variables, 83*8e3e3a7aSWarner Loshand can register C functions to be called by Lua code. 84*8e3e3a7aSWarner LoshThrough the use of C functions, Lua can be augmented to cope with 85*8e3e3a7aSWarner Losha wide range of different domains, 86*8e3e3a7aSWarner Loshthus creating customized programming languages sharing a syntactical framework. 87*8e3e3a7aSWarner Losh 88*8e3e3a7aSWarner Losh 89*8e3e3a7aSWarner Losh<p> 90*8e3e3a7aSWarner LoshLua is free software, 91*8e3e3a7aSWarner Loshand is provided as usual with no guarantees, 92*8e3e3a7aSWarner Loshas stated in its license. 93*8e3e3a7aSWarner LoshThe implementation described in this manual is available 94*8e3e3a7aSWarner Loshat Lua's official web site, <code>www.lua.org</code>. 95*8e3e3a7aSWarner Losh 96*8e3e3a7aSWarner Losh 97*8e3e3a7aSWarner Losh<p> 98*8e3e3a7aSWarner LoshLike any other reference manual, 99*8e3e3a7aSWarner Loshthis document is dry in places. 100*8e3e3a7aSWarner LoshFor a discussion of the decisions behind the design of Lua, 101*8e3e3a7aSWarner Loshsee the technical papers available at Lua's web site. 102*8e3e3a7aSWarner LoshFor a detailed introduction to programming in Lua, 103*8e3e3a7aSWarner Loshsee Roberto's book, <em>Programming in Lua</em>. 104*8e3e3a7aSWarner Losh 105*8e3e3a7aSWarner Losh 106*8e3e3a7aSWarner Losh 107*8e3e3a7aSWarner Losh<h1>2 – <a name="2">Basic Concepts</a></h1> 108*8e3e3a7aSWarner Losh 109*8e3e3a7aSWarner Losh<p> 110*8e3e3a7aSWarner LoshThis section describes the basic concepts of the language. 111*8e3e3a7aSWarner Losh 112*8e3e3a7aSWarner Losh 113*8e3e3a7aSWarner Losh 114*8e3e3a7aSWarner Losh<h2>2.1 – <a name="2.1">Values and Types</a></h2> 115*8e3e3a7aSWarner Losh 116*8e3e3a7aSWarner Losh<p> 117*8e3e3a7aSWarner LoshLua is a <em>dynamically typed language</em>. 118*8e3e3a7aSWarner LoshThis means that 119*8e3e3a7aSWarner Loshvariables do not have types; only values do. 120*8e3e3a7aSWarner LoshThere are no type definitions in the language. 121*8e3e3a7aSWarner LoshAll values carry their own type. 122*8e3e3a7aSWarner Losh 123*8e3e3a7aSWarner Losh 124*8e3e3a7aSWarner Losh<p> 125*8e3e3a7aSWarner LoshAll values in Lua are <em>first-class values</em>. 126*8e3e3a7aSWarner LoshThis means that all values can be stored in variables, 127*8e3e3a7aSWarner Loshpassed as arguments to other functions, and returned as results. 128*8e3e3a7aSWarner Losh 129*8e3e3a7aSWarner Losh 130*8e3e3a7aSWarner Losh<p> 131*8e3e3a7aSWarner LoshThere are eight basic types in Lua: 132*8e3e3a7aSWarner Losh<em>nil</em>, <em>boolean</em>, <em>number</em>, 133*8e3e3a7aSWarner Losh<em>string</em>, <em>function</em>, <em>userdata</em>, 134*8e3e3a7aSWarner Losh<em>thread</em>, and <em>table</em>. 135*8e3e3a7aSWarner LoshThe type <em>nil</em> has one single value, <b>nil</b>, 136*8e3e3a7aSWarner Loshwhose main property is to be different from any other value; 137*8e3e3a7aSWarner Loshit usually represents the absence of a useful value. 138*8e3e3a7aSWarner LoshThe type <em>boolean</em> has two values, <b>false</b> and <b>true</b>. 139*8e3e3a7aSWarner LoshBoth <b>nil</b> and <b>false</b> make a condition false; 140*8e3e3a7aSWarner Loshany other value makes it true. 141*8e3e3a7aSWarner LoshThe type <em>number</em> represents both 142*8e3e3a7aSWarner Loshinteger numbers and real (floating-point) numbers. 143*8e3e3a7aSWarner LoshThe type <em>string</em> represents immutable sequences of bytes. 144*8e3e3a7aSWarner Losh 145*8e3e3a7aSWarner LoshLua is 8-bit clean: 146*8e3e3a7aSWarner Loshstrings can contain any 8-bit value, 147*8e3e3a7aSWarner Loshincluding embedded zeros ('<code>\0</code>'). 148*8e3e3a7aSWarner LoshLua is also encoding-agnostic; 149*8e3e3a7aSWarner Loshit makes no assumptions about the contents of a string. 150*8e3e3a7aSWarner Losh 151*8e3e3a7aSWarner Losh 152*8e3e3a7aSWarner Losh<p> 153*8e3e3a7aSWarner LoshThe type <em>number</em> uses two internal representations, 154*8e3e3a7aSWarner Loshor two subtypes, 155*8e3e3a7aSWarner Loshone called <em>integer</em> and the other called <em>float</em>. 156*8e3e3a7aSWarner LoshLua has explicit rules about when each representation is used, 157*8e3e3a7aSWarner Loshbut it also converts between them automatically as needed (see <a href="#3.4.3">§3.4.3</a>). 158*8e3e3a7aSWarner LoshTherefore, 159*8e3e3a7aSWarner Loshthe programmer may choose to mostly ignore the difference 160*8e3e3a7aSWarner Loshbetween integers and floats 161*8e3e3a7aSWarner Loshor to assume complete control over the representation of each number. 162*8e3e3a7aSWarner LoshStandard Lua uses 64-bit integers and double-precision (64-bit) floats, 163*8e3e3a7aSWarner Loshbut you can also compile Lua so that it 164*8e3e3a7aSWarner Loshuses 32-bit integers and/or single-precision (32-bit) floats. 165*8e3e3a7aSWarner LoshThe option with 32 bits for both integers and floats 166*8e3e3a7aSWarner Loshis particularly attractive 167*8e3e3a7aSWarner Loshfor small machines and embedded systems. 168*8e3e3a7aSWarner Losh(See macro <code>LUA_32BITS</code> in file <code>luaconf.h</code>.) 169*8e3e3a7aSWarner Losh 170*8e3e3a7aSWarner Losh 171*8e3e3a7aSWarner Losh<p> 172*8e3e3a7aSWarner LoshLua can call (and manipulate) functions written in Lua and 173*8e3e3a7aSWarner Loshfunctions written in C (see <a href="#3.4.10">§3.4.10</a>). 174*8e3e3a7aSWarner LoshBoth are represented by the type <em>function</em>. 175*8e3e3a7aSWarner Losh 176*8e3e3a7aSWarner Losh 177*8e3e3a7aSWarner Losh<p> 178*8e3e3a7aSWarner LoshThe type <em>userdata</em> is provided to allow arbitrary C data to 179*8e3e3a7aSWarner Loshbe stored in Lua variables. 180*8e3e3a7aSWarner LoshA userdata value represents a block of raw memory. 181*8e3e3a7aSWarner LoshThere are two kinds of userdata: 182*8e3e3a7aSWarner Losh<em>full userdata</em>, 183*8e3e3a7aSWarner Loshwhich is an object with a block of memory managed by Lua, 184*8e3e3a7aSWarner Loshand <em>light userdata</em>, 185*8e3e3a7aSWarner Loshwhich is simply a C pointer value. 186*8e3e3a7aSWarner LoshUserdata has no predefined operations in Lua, 187*8e3e3a7aSWarner Loshexcept assignment and identity test. 188*8e3e3a7aSWarner LoshBy using <em>metatables</em>, 189*8e3e3a7aSWarner Loshthe programmer can define operations for full userdata values 190*8e3e3a7aSWarner Losh(see <a href="#2.4">§2.4</a>). 191*8e3e3a7aSWarner LoshUserdata values cannot be created or modified in Lua, 192*8e3e3a7aSWarner Loshonly through the C API. 193*8e3e3a7aSWarner LoshThis guarantees the integrity of data owned by the host program. 194*8e3e3a7aSWarner Losh 195*8e3e3a7aSWarner Losh 196*8e3e3a7aSWarner Losh<p> 197*8e3e3a7aSWarner LoshThe type <em>thread</em> represents independent threads of execution 198*8e3e3a7aSWarner Loshand it is used to implement coroutines (see <a href="#2.6">§2.6</a>). 199*8e3e3a7aSWarner LoshLua threads are not related to operating-system threads. 200*8e3e3a7aSWarner LoshLua supports coroutines on all systems, 201*8e3e3a7aSWarner Losheven those that do not support threads natively. 202*8e3e3a7aSWarner Losh 203*8e3e3a7aSWarner Losh 204*8e3e3a7aSWarner Losh<p> 205*8e3e3a7aSWarner LoshThe type <em>table</em> implements associative arrays, 206*8e3e3a7aSWarner Loshthat is, arrays that can be indexed not only with numbers, 207*8e3e3a7aSWarner Loshbut with any Lua value except <b>nil</b> and NaN. 208*8e3e3a7aSWarner Losh(<em>Not a Number</em> is a special value used to represent 209*8e3e3a7aSWarner Loshundefined or unrepresentable numerical results, such as <code>0/0</code>.) 210*8e3e3a7aSWarner LoshTables can be <em>heterogeneous</em>; 211*8e3e3a7aSWarner Loshthat is, they can contain values of all types (except <b>nil</b>). 212*8e3e3a7aSWarner LoshAny key with value <b>nil</b> is not considered part of the table. 213*8e3e3a7aSWarner LoshConversely, any key that is not part of a table has 214*8e3e3a7aSWarner Loshan associated value <b>nil</b>. 215*8e3e3a7aSWarner Losh 216*8e3e3a7aSWarner Losh 217*8e3e3a7aSWarner Losh<p> 218*8e3e3a7aSWarner LoshTables are the sole data-structuring mechanism in Lua; 219*8e3e3a7aSWarner Loshthey can be used to represent ordinary arrays, lists, 220*8e3e3a7aSWarner Loshsymbol tables, sets, records, graphs, trees, etc. 221*8e3e3a7aSWarner LoshTo represent records, Lua uses the field name as an index. 222*8e3e3a7aSWarner LoshThe language supports this representation by 223*8e3e3a7aSWarner Loshproviding <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. 224*8e3e3a7aSWarner LoshThere are several convenient ways to create tables in Lua 225*8e3e3a7aSWarner Losh(see <a href="#3.4.9">§3.4.9</a>). 226*8e3e3a7aSWarner Losh 227*8e3e3a7aSWarner Losh 228*8e3e3a7aSWarner Losh<p> 229*8e3e3a7aSWarner LoshLike indices, 230*8e3e3a7aSWarner Loshthe values of table fields can be of any type. 231*8e3e3a7aSWarner LoshIn particular, 232*8e3e3a7aSWarner Loshbecause functions are first-class values, 233*8e3e3a7aSWarner Loshtable fields can contain functions. 234*8e3e3a7aSWarner LoshThus tables can also carry <em>methods</em> (see <a href="#3.4.11">§3.4.11</a>). 235*8e3e3a7aSWarner Losh 236*8e3e3a7aSWarner Losh 237*8e3e3a7aSWarner Losh<p> 238*8e3e3a7aSWarner LoshThe indexing of tables follows 239*8e3e3a7aSWarner Loshthe definition of raw equality in the language. 240*8e3e3a7aSWarner LoshThe expressions <code>a[i]</code> and <code>a[j]</code> 241*8e3e3a7aSWarner Loshdenote the same table element 242*8e3e3a7aSWarner Loshif and only if <code>i</code> and <code>j</code> are raw equal 243*8e3e3a7aSWarner Losh(that is, equal without metamethods). 244*8e3e3a7aSWarner LoshIn particular, floats with integral values 245*8e3e3a7aSWarner Loshare equal to their respective integers 246*8e3e3a7aSWarner Losh(e.g., <code>1.0 == 1</code>). 247*8e3e3a7aSWarner LoshTo avoid ambiguities, 248*8e3e3a7aSWarner Loshany float with integral value used as a key 249*8e3e3a7aSWarner Loshis converted to its respective integer. 250*8e3e3a7aSWarner LoshFor instance, if you write <code>a[2.0] = true</code>, 251*8e3e3a7aSWarner Loshthe actual key inserted into the table will be the 252*8e3e3a7aSWarner Loshinteger <code>2</code>. 253*8e3e3a7aSWarner Losh(On the other hand, 254*8e3e3a7aSWarner Losh2 and "<code>2</code>" are different Lua values and therefore 255*8e3e3a7aSWarner Loshdenote different table entries.) 256*8e3e3a7aSWarner Losh 257*8e3e3a7aSWarner Losh 258*8e3e3a7aSWarner Losh<p> 259*8e3e3a7aSWarner LoshTables, functions, threads, and (full) userdata values are <em>objects</em>: 260*8e3e3a7aSWarner Loshvariables do not actually <em>contain</em> these values, 261*8e3e3a7aSWarner Loshonly <em>references</em> to them. 262*8e3e3a7aSWarner LoshAssignment, parameter passing, and function returns 263*8e3e3a7aSWarner Loshalways manipulate references to such values; 264*8e3e3a7aSWarner Loshthese operations do not imply any kind of copy. 265*8e3e3a7aSWarner Losh 266*8e3e3a7aSWarner Losh 267*8e3e3a7aSWarner Losh<p> 268*8e3e3a7aSWarner LoshThe library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type 269*8e3e3a7aSWarner Loshof a given value (see <a href="#6.1">§6.1</a>). 270*8e3e3a7aSWarner Losh 271*8e3e3a7aSWarner Losh 272*8e3e3a7aSWarner Losh 273*8e3e3a7aSWarner Losh 274*8e3e3a7aSWarner Losh 275*8e3e3a7aSWarner Losh<h2>2.2 – <a name="2.2">Environments and the Global Environment</a></h2> 276*8e3e3a7aSWarner Losh 277*8e3e3a7aSWarner Losh<p> 278*8e3e3a7aSWarner LoshAs will be discussed in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>, 279*8e3e3a7aSWarner Loshany reference to a free name 280*8e3e3a7aSWarner Losh(that is, a name not bound to any declaration) <code>var</code> 281*8e3e3a7aSWarner Loshis syntactically translated to <code>_ENV.var</code>. 282*8e3e3a7aSWarner LoshMoreover, every chunk is compiled in the scope of 283*8e3e3a7aSWarner Loshan external local variable named <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>), 284*8e3e3a7aSWarner Loshso <code>_ENV</code> itself is never a free name in a chunk. 285*8e3e3a7aSWarner Losh 286*8e3e3a7aSWarner Losh 287*8e3e3a7aSWarner Losh<p> 288*8e3e3a7aSWarner LoshDespite the existence of this external <code>_ENV</code> variable and 289*8e3e3a7aSWarner Loshthe translation of free names, 290*8e3e3a7aSWarner Losh<code>_ENV</code> is a completely regular name. 291*8e3e3a7aSWarner LoshIn particular, 292*8e3e3a7aSWarner Loshyou can define new variables and parameters with that name. 293*8e3e3a7aSWarner LoshEach reference to a free name uses the <code>_ENV</code> that is 294*8e3e3a7aSWarner Loshvisible at that point in the program, 295*8e3e3a7aSWarner Loshfollowing the usual visibility rules of Lua (see <a href="#3.5">§3.5</a>). 296*8e3e3a7aSWarner Losh 297*8e3e3a7aSWarner Losh 298*8e3e3a7aSWarner Losh<p> 299*8e3e3a7aSWarner LoshAny table used as the value of <code>_ENV</code> is called an <em>environment</em>. 300*8e3e3a7aSWarner Losh 301*8e3e3a7aSWarner Losh 302*8e3e3a7aSWarner Losh<p> 303*8e3e3a7aSWarner LoshLua keeps a distinguished environment called the <em>global environment</em>. 304*8e3e3a7aSWarner LoshThis value is kept at a special index in the C registry (see <a href="#4.5">§4.5</a>). 305*8e3e3a7aSWarner LoshIn Lua, the global variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value. 306*8e3e3a7aSWarner Losh(<a href="#pdf-_G"><code>_G</code></a> is never used internally.) 307*8e3e3a7aSWarner Losh 308*8e3e3a7aSWarner Losh 309*8e3e3a7aSWarner Losh<p> 310*8e3e3a7aSWarner LoshWhen Lua loads a chunk, 311*8e3e3a7aSWarner Loshthe default value for its <code>_ENV</code> upvalue 312*8e3e3a7aSWarner Loshis the global environment (see <a href="#pdf-load"><code>load</code></a>). 313*8e3e3a7aSWarner LoshTherefore, by default, 314*8e3e3a7aSWarner Loshfree names in Lua code refer to entries in the global environment 315*8e3e3a7aSWarner Losh(and, therefore, they are also called <em>global variables</em>). 316*8e3e3a7aSWarner LoshMoreover, all standard libraries are loaded in the global environment 317*8e3e3a7aSWarner Loshand some functions there operate on that environment. 318*8e3e3a7aSWarner LoshYou can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>) 319*8e3e3a7aSWarner Loshto load a chunk with a different environment. 320*8e3e3a7aSWarner Losh(In C, you have to load the chunk and then change the value 321*8e3e3a7aSWarner Loshof its first upvalue.) 322*8e3e3a7aSWarner Losh 323*8e3e3a7aSWarner Losh 324*8e3e3a7aSWarner Losh 325*8e3e3a7aSWarner Losh 326*8e3e3a7aSWarner Losh 327*8e3e3a7aSWarner Losh<h2>2.3 – <a name="2.3">Error Handling</a></h2> 328*8e3e3a7aSWarner Losh 329*8e3e3a7aSWarner Losh<p> 330*8e3e3a7aSWarner LoshBecause Lua is an embedded extension language, 331*8e3e3a7aSWarner Loshall Lua actions start from C code in the host program 332*8e3e3a7aSWarner Loshcalling a function from the Lua library. 333*8e3e3a7aSWarner Losh(When you use Lua standalone, 334*8e3e3a7aSWarner Loshthe <code>lua</code> application is the host program.) 335*8e3e3a7aSWarner LoshWhenever an error occurs during 336*8e3e3a7aSWarner Loshthe compilation or execution of a Lua chunk, 337*8e3e3a7aSWarner Loshcontrol returns to the host, 338*8e3e3a7aSWarner Loshwhich can take appropriate measures 339*8e3e3a7aSWarner Losh(such as printing an error message). 340*8e3e3a7aSWarner Losh 341*8e3e3a7aSWarner Losh 342*8e3e3a7aSWarner Losh<p> 343*8e3e3a7aSWarner LoshLua code can explicitly generate an error by calling the 344*8e3e3a7aSWarner Losh<a href="#pdf-error"><code>error</code></a> function. 345*8e3e3a7aSWarner LoshIf you need to catch errors in Lua, 346*8e3e3a7aSWarner Loshyou can use <a href="#pdf-pcall"><code>pcall</code></a> or <a href="#pdf-xpcall"><code>xpcall</code></a> 347*8e3e3a7aSWarner Loshto call a given function in <em>protected mode</em>. 348*8e3e3a7aSWarner Losh 349*8e3e3a7aSWarner Losh 350*8e3e3a7aSWarner Losh<p> 351*8e3e3a7aSWarner LoshWhenever there is an error, 352*8e3e3a7aSWarner Loshan <em>error object</em> (also called an <em>error message</em>) 353*8e3e3a7aSWarner Loshis propagated with information about the error. 354*8e3e3a7aSWarner LoshLua itself only generates errors whose error object is a string, 355*8e3e3a7aSWarner Loshbut programs may generate errors with 356*8e3e3a7aSWarner Loshany value as the error object. 357*8e3e3a7aSWarner LoshIt is up to the Lua program or its host to handle such error objects. 358*8e3e3a7aSWarner Losh 359*8e3e3a7aSWarner Losh 360*8e3e3a7aSWarner Losh<p> 361*8e3e3a7aSWarner LoshWhen you use <a href="#pdf-xpcall"><code>xpcall</code></a> or <a href="#lua_pcall"><code>lua_pcall</code></a>, 362*8e3e3a7aSWarner Loshyou may give a <em>message handler</em> 363*8e3e3a7aSWarner Loshto be called in case of errors. 364*8e3e3a7aSWarner LoshThis function is called with the original error object 365*8e3e3a7aSWarner Loshand returns a new error object. 366*8e3e3a7aSWarner LoshIt is called before the error unwinds the stack, 367*8e3e3a7aSWarner Loshso that it can gather more information about the error, 368*8e3e3a7aSWarner Loshfor instance by inspecting the stack and creating a stack traceback. 369*8e3e3a7aSWarner LoshThis message handler is still protected by the protected call; 370*8e3e3a7aSWarner Loshso, an error inside the message handler 371*8e3e3a7aSWarner Loshwill call the message handler again. 372*8e3e3a7aSWarner LoshIf this loop goes on for too long, 373*8e3e3a7aSWarner LoshLua breaks it and returns an appropriate message. 374*8e3e3a7aSWarner Losh(The message handler is called only for regular runtime errors. 375*8e3e3a7aSWarner LoshIt is not called for memory-allocation errors 376*8e3e3a7aSWarner Loshnor for errors while running finalizers.) 377*8e3e3a7aSWarner Losh 378*8e3e3a7aSWarner Losh 379*8e3e3a7aSWarner Losh 380*8e3e3a7aSWarner Losh 381*8e3e3a7aSWarner Losh 382*8e3e3a7aSWarner Losh<h2>2.4 – <a name="2.4">Metatables and Metamethods</a></h2> 383*8e3e3a7aSWarner Losh 384*8e3e3a7aSWarner Losh<p> 385*8e3e3a7aSWarner LoshEvery value in Lua can have a <em>metatable</em>. 386*8e3e3a7aSWarner LoshThis <em>metatable</em> is an ordinary Lua table 387*8e3e3a7aSWarner Loshthat defines the behavior of the original value 388*8e3e3a7aSWarner Loshunder certain special operations. 389*8e3e3a7aSWarner LoshYou can change several aspects of the behavior 390*8e3e3a7aSWarner Loshof operations over a value by setting specific fields in its metatable. 391*8e3e3a7aSWarner LoshFor instance, when a non-numeric value is the operand of an addition, 392*8e3e3a7aSWarner LoshLua checks for a function in the field "<code>__add</code>" of the value's metatable. 393*8e3e3a7aSWarner LoshIf it finds one, 394*8e3e3a7aSWarner LoshLua calls this function to perform the addition. 395*8e3e3a7aSWarner Losh 396*8e3e3a7aSWarner Losh 397*8e3e3a7aSWarner Losh<p> 398*8e3e3a7aSWarner LoshThe key for each event in a metatable is a string 399*8e3e3a7aSWarner Loshwith the event name prefixed by two underscores; 400*8e3e3a7aSWarner Loshthe corresponding values are called <em>metamethods</em>. 401*8e3e3a7aSWarner LoshIn the previous example, the key is "<code>__add</code>" 402*8e3e3a7aSWarner Loshand the metamethod is the function that performs the addition. 403*8e3e3a7aSWarner Losh 404*8e3e3a7aSWarner Losh 405*8e3e3a7aSWarner Losh<p> 406*8e3e3a7aSWarner LoshYou can query the metatable of any value 407*8e3e3a7aSWarner Loshusing the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function. 408*8e3e3a7aSWarner LoshLua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>). 409*8e3e3a7aSWarner LoshSo, to retrieve the metamethod for event <code>ev</code> in object <code>o</code>, 410*8e3e3a7aSWarner LoshLua does the equivalent to the following code: 411*8e3e3a7aSWarner Losh 412*8e3e3a7aSWarner Losh<pre> 413*8e3e3a7aSWarner Losh rawget(getmetatable(<em>o</em>) or {}, "__<em>ev</em>") 414*8e3e3a7aSWarner Losh</pre> 415*8e3e3a7aSWarner Losh 416*8e3e3a7aSWarner Losh<p> 417*8e3e3a7aSWarner LoshYou can replace the metatable of tables 418*8e3e3a7aSWarner Loshusing the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function. 419*8e3e3a7aSWarner LoshYou cannot change the metatable of other types from Lua code 420*8e3e3a7aSWarner Losh(except by using the debug library (<a href="#6.10">§6.10</a>)); 421*8e3e3a7aSWarner Loshyou should use the C API for that. 422*8e3e3a7aSWarner Losh 423*8e3e3a7aSWarner Losh 424*8e3e3a7aSWarner Losh<p> 425*8e3e3a7aSWarner LoshTables and full userdata have individual metatables 426*8e3e3a7aSWarner Losh(although multiple tables and userdata can share their metatables). 427*8e3e3a7aSWarner LoshValues of all other types share one single metatable per type; 428*8e3e3a7aSWarner Loshthat is, there is one single metatable for all numbers, 429*8e3e3a7aSWarner Loshone for all strings, etc. 430*8e3e3a7aSWarner LoshBy default, a value has no metatable, 431*8e3e3a7aSWarner Loshbut the string library sets a metatable for the string type (see <a href="#6.4">§6.4</a>). 432*8e3e3a7aSWarner Losh 433*8e3e3a7aSWarner Losh 434*8e3e3a7aSWarner Losh<p> 435*8e3e3a7aSWarner LoshA metatable controls how an object behaves in 436*8e3e3a7aSWarner Losharithmetic operations, bitwise operations, 437*8e3e3a7aSWarner Loshorder comparisons, concatenation, length operation, calls, and indexing. 438*8e3e3a7aSWarner LoshA metatable also can define a function to be called 439*8e3e3a7aSWarner Loshwhen a userdata or a table is garbage collected (<a href="#2.5">§2.5</a>). 440*8e3e3a7aSWarner Losh 441*8e3e3a7aSWarner Losh 442*8e3e3a7aSWarner Losh<p> 443*8e3e3a7aSWarner LoshFor the unary operators (negation, length, and bitwise NOT), 444*8e3e3a7aSWarner Loshthe metamethod is computed and called with a dummy second operand, 445*8e3e3a7aSWarner Loshequal to the first one. 446*8e3e3a7aSWarner LoshThis extra operand is only to simplify Lua's internals 447*8e3e3a7aSWarner Losh(by making these operators behave like a binary operation) 448*8e3e3a7aSWarner Loshand may be removed in future versions. 449*8e3e3a7aSWarner Losh(For most uses this extra operand is irrelevant.) 450*8e3e3a7aSWarner Losh 451*8e3e3a7aSWarner Losh 452*8e3e3a7aSWarner Losh<p> 453*8e3e3a7aSWarner LoshA detailed list of events controlled by metatables is given next. 454*8e3e3a7aSWarner LoshEach operation is identified by its corresponding key. 455*8e3e3a7aSWarner Losh 456*8e3e3a7aSWarner Losh 457*8e3e3a7aSWarner Losh 458*8e3e3a7aSWarner Losh<ul> 459*8e3e3a7aSWarner Losh 460*8e3e3a7aSWarner Losh<li><b><code>__add</code>: </b> 461*8e3e3a7aSWarner Loshthe addition (<code>+</code>) operation. 462*8e3e3a7aSWarner LoshIf any operand for an addition is not a number 463*8e3e3a7aSWarner Losh(nor a string coercible to a number), 464*8e3e3a7aSWarner LoshLua will try to call a metamethod. 465*8e3e3a7aSWarner LoshFirst, Lua will check the first operand (even if it is valid). 466*8e3e3a7aSWarner LoshIf that operand does not define a metamethod for <code>__add</code>, 467*8e3e3a7aSWarner Loshthen Lua will check the second operand. 468*8e3e3a7aSWarner LoshIf Lua can find a metamethod, 469*8e3e3a7aSWarner Loshit calls the metamethod with the two operands as arguments, 470*8e3e3a7aSWarner Loshand the result of the call 471*8e3e3a7aSWarner Losh(adjusted to one value) 472*8e3e3a7aSWarner Loshis the result of the operation. 473*8e3e3a7aSWarner LoshOtherwise, 474*8e3e3a7aSWarner Loshit raises an error. 475*8e3e3a7aSWarner Losh</li> 476*8e3e3a7aSWarner Losh 477*8e3e3a7aSWarner Losh<li><b><code>__sub</code>: </b> 478*8e3e3a7aSWarner Loshthe subtraction (<code>-</code>) operation. 479*8e3e3a7aSWarner LoshBehavior similar to the addition operation. 480*8e3e3a7aSWarner Losh</li> 481*8e3e3a7aSWarner Losh 482*8e3e3a7aSWarner Losh<li><b><code>__mul</code>: </b> 483*8e3e3a7aSWarner Loshthe multiplication (<code>*</code>) operation. 484*8e3e3a7aSWarner LoshBehavior similar to the addition operation. 485*8e3e3a7aSWarner Losh</li> 486*8e3e3a7aSWarner Losh 487*8e3e3a7aSWarner Losh<li><b><code>__div</code>: </b> 488*8e3e3a7aSWarner Loshthe division (<code>/</code>) operation. 489*8e3e3a7aSWarner LoshBehavior similar to the addition operation. 490*8e3e3a7aSWarner Losh</li> 491*8e3e3a7aSWarner Losh 492*8e3e3a7aSWarner Losh<li><b><code>__mod</code>: </b> 493*8e3e3a7aSWarner Loshthe modulo (<code>%</code>) operation. 494*8e3e3a7aSWarner LoshBehavior similar to the addition operation. 495*8e3e3a7aSWarner Losh</li> 496*8e3e3a7aSWarner Losh 497*8e3e3a7aSWarner Losh<li><b><code>__pow</code>: </b> 498*8e3e3a7aSWarner Loshthe exponentiation (<code>^</code>) operation. 499*8e3e3a7aSWarner LoshBehavior similar to the addition operation. 500*8e3e3a7aSWarner Losh</li> 501*8e3e3a7aSWarner Losh 502*8e3e3a7aSWarner Losh<li><b><code>__unm</code>: </b> 503*8e3e3a7aSWarner Loshthe negation (unary <code>-</code>) operation. 504*8e3e3a7aSWarner LoshBehavior similar to the addition operation. 505*8e3e3a7aSWarner Losh</li> 506*8e3e3a7aSWarner Losh 507*8e3e3a7aSWarner Losh<li><b><code>__idiv</code>: </b> 508*8e3e3a7aSWarner Loshthe floor division (<code>//</code>) operation. 509*8e3e3a7aSWarner LoshBehavior similar to the addition operation. 510*8e3e3a7aSWarner Losh</li> 511*8e3e3a7aSWarner Losh 512*8e3e3a7aSWarner Losh<li><b><code>__band</code>: </b> 513*8e3e3a7aSWarner Loshthe bitwise AND (<code>&</code>) operation. 514*8e3e3a7aSWarner LoshBehavior similar to the addition operation, 515*8e3e3a7aSWarner Loshexcept that Lua will try a metamethod 516*8e3e3a7aSWarner Loshif any operand is neither an integer 517*8e3e3a7aSWarner Loshnor a value coercible to an integer (see <a href="#3.4.3">§3.4.3</a>). 518*8e3e3a7aSWarner Losh</li> 519*8e3e3a7aSWarner Losh 520*8e3e3a7aSWarner Losh<li><b><code>__bor</code>: </b> 521*8e3e3a7aSWarner Loshthe bitwise OR (<code>|</code>) operation. 522*8e3e3a7aSWarner LoshBehavior similar to the bitwise AND operation. 523*8e3e3a7aSWarner Losh</li> 524*8e3e3a7aSWarner Losh 525*8e3e3a7aSWarner Losh<li><b><code>__bxor</code>: </b> 526*8e3e3a7aSWarner Loshthe bitwise exclusive OR (binary <code>~</code>) operation. 527*8e3e3a7aSWarner LoshBehavior similar to the bitwise AND operation. 528*8e3e3a7aSWarner Losh</li> 529*8e3e3a7aSWarner Losh 530*8e3e3a7aSWarner Losh<li><b><code>__bnot</code>: </b> 531*8e3e3a7aSWarner Loshthe bitwise NOT (unary <code>~</code>) operation. 532*8e3e3a7aSWarner LoshBehavior similar to the bitwise AND operation. 533*8e3e3a7aSWarner Losh</li> 534*8e3e3a7aSWarner Losh 535*8e3e3a7aSWarner Losh<li><b><code>__shl</code>: </b> 536*8e3e3a7aSWarner Loshthe bitwise left shift (<code><<</code>) operation. 537*8e3e3a7aSWarner LoshBehavior similar to the bitwise AND operation. 538*8e3e3a7aSWarner Losh</li> 539*8e3e3a7aSWarner Losh 540*8e3e3a7aSWarner Losh<li><b><code>__shr</code>: </b> 541*8e3e3a7aSWarner Loshthe bitwise right shift (<code>>></code>) operation. 542*8e3e3a7aSWarner LoshBehavior similar to the bitwise AND operation. 543*8e3e3a7aSWarner Losh</li> 544*8e3e3a7aSWarner Losh 545*8e3e3a7aSWarner Losh<li><b><code>__concat</code>: </b> 546*8e3e3a7aSWarner Loshthe concatenation (<code>..</code>) operation. 547*8e3e3a7aSWarner LoshBehavior similar to the addition operation, 548*8e3e3a7aSWarner Loshexcept that Lua will try a metamethod 549*8e3e3a7aSWarner Loshif any operand is neither a string nor a number 550*8e3e3a7aSWarner Losh(which is always coercible to a string). 551*8e3e3a7aSWarner Losh</li> 552*8e3e3a7aSWarner Losh 553*8e3e3a7aSWarner Losh<li><b><code>__len</code>: </b> 554*8e3e3a7aSWarner Loshthe length (<code>#</code>) operation. 555*8e3e3a7aSWarner LoshIf the object is not a string, 556*8e3e3a7aSWarner LoshLua will try its metamethod. 557*8e3e3a7aSWarner LoshIf there is a metamethod, 558*8e3e3a7aSWarner LoshLua calls it with the object as argument, 559*8e3e3a7aSWarner Loshand the result of the call 560*8e3e3a7aSWarner Losh(always adjusted to one value) 561*8e3e3a7aSWarner Loshis the result of the operation. 562*8e3e3a7aSWarner LoshIf there is no metamethod but the object is a table, 563*8e3e3a7aSWarner Loshthen Lua uses the table length operation (see <a href="#3.4.7">§3.4.7</a>). 564*8e3e3a7aSWarner LoshOtherwise, Lua raises an error. 565*8e3e3a7aSWarner Losh</li> 566*8e3e3a7aSWarner Losh 567*8e3e3a7aSWarner Losh<li><b><code>__eq</code>: </b> 568*8e3e3a7aSWarner Loshthe equal (<code>==</code>) operation. 569*8e3e3a7aSWarner LoshBehavior similar to the addition operation, 570*8e3e3a7aSWarner Loshexcept that Lua will try a metamethod only when the values 571*8e3e3a7aSWarner Loshbeing compared are either both tables or both full userdata 572*8e3e3a7aSWarner Loshand they are not primitively equal. 573*8e3e3a7aSWarner LoshThe result of the call is always converted to a boolean. 574*8e3e3a7aSWarner Losh</li> 575*8e3e3a7aSWarner Losh 576*8e3e3a7aSWarner Losh<li><b><code>__lt</code>: </b> 577*8e3e3a7aSWarner Loshthe less than (<code><</code>) operation. 578*8e3e3a7aSWarner LoshBehavior similar to the addition operation, 579*8e3e3a7aSWarner Loshexcept that Lua will try a metamethod only when the values 580*8e3e3a7aSWarner Loshbeing compared are neither both numbers nor both strings. 581*8e3e3a7aSWarner LoshThe result of the call is always converted to a boolean. 582*8e3e3a7aSWarner Losh</li> 583*8e3e3a7aSWarner Losh 584*8e3e3a7aSWarner Losh<li><b><code>__le</code>: </b> 585*8e3e3a7aSWarner Loshthe less equal (<code><=</code>) operation. 586*8e3e3a7aSWarner LoshUnlike other operations, 587*8e3e3a7aSWarner Loshthe less-equal operation can use two different events. 588*8e3e3a7aSWarner LoshFirst, Lua looks for the <code>__le</code> metamethod in both operands, 589*8e3e3a7aSWarner Loshlike in the less than operation. 590*8e3e3a7aSWarner LoshIf it cannot find such a metamethod, 591*8e3e3a7aSWarner Loshthen it will try the <code>__lt</code> metamethod, 592*8e3e3a7aSWarner Loshassuming that <code>a <= b</code> is equivalent to <code>not (b < a)</code>. 593*8e3e3a7aSWarner LoshAs with the other comparison operators, 594*8e3e3a7aSWarner Loshthe result is always a boolean. 595*8e3e3a7aSWarner Losh(This use of the <code>__lt</code> event can be removed in future versions; 596*8e3e3a7aSWarner Loshit is also slower than a real <code>__le</code> metamethod.) 597*8e3e3a7aSWarner Losh</li> 598*8e3e3a7aSWarner Losh 599*8e3e3a7aSWarner Losh<li><b><code>__index</code>: </b> 600*8e3e3a7aSWarner LoshThe indexing access <code>table[key]</code>. 601*8e3e3a7aSWarner LoshThis event happens when <code>table</code> is not a table or 602*8e3e3a7aSWarner Loshwhen <code>key</code> is not present in <code>table</code>. 603*8e3e3a7aSWarner LoshThe metamethod is looked up in <code>table</code>. 604*8e3e3a7aSWarner Losh 605*8e3e3a7aSWarner Losh 606*8e3e3a7aSWarner Losh<p> 607*8e3e3a7aSWarner LoshDespite the name, 608*8e3e3a7aSWarner Loshthe metamethod for this event can be either a function or a table. 609*8e3e3a7aSWarner LoshIf it is a function, 610*8e3e3a7aSWarner Loshit is called with <code>table</code> and <code>key</code> as arguments, 611*8e3e3a7aSWarner Loshand the result of the call 612*8e3e3a7aSWarner Losh(adjusted to one value) 613*8e3e3a7aSWarner Loshis the result of the operation. 614*8e3e3a7aSWarner LoshIf it is a table, 615*8e3e3a7aSWarner Loshthe final result is the result of indexing this table with <code>key</code>. 616*8e3e3a7aSWarner Losh(This indexing is regular, not raw, 617*8e3e3a7aSWarner Loshand therefore can trigger another metamethod.) 618*8e3e3a7aSWarner Losh</li> 619*8e3e3a7aSWarner Losh 620*8e3e3a7aSWarner Losh<li><b><code>__newindex</code>: </b> 621*8e3e3a7aSWarner LoshThe indexing assignment <code>table[key] = value</code>. 622*8e3e3a7aSWarner LoshLike the index event, 623*8e3e3a7aSWarner Loshthis event happens when <code>table</code> is not a table or 624*8e3e3a7aSWarner Loshwhen <code>key</code> is not present in <code>table</code>. 625*8e3e3a7aSWarner LoshThe metamethod is looked up in <code>table</code>. 626*8e3e3a7aSWarner Losh 627*8e3e3a7aSWarner Losh 628*8e3e3a7aSWarner Losh<p> 629*8e3e3a7aSWarner LoshLike with indexing, 630*8e3e3a7aSWarner Loshthe metamethod for this event can be either a function or a table. 631*8e3e3a7aSWarner LoshIf it is a function, 632*8e3e3a7aSWarner Loshit is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments. 633*8e3e3a7aSWarner LoshIf it is a table, 634*8e3e3a7aSWarner LoshLua does an indexing assignment to this table with the same key and value. 635*8e3e3a7aSWarner Losh(This assignment is regular, not raw, 636*8e3e3a7aSWarner Loshand therefore can trigger another metamethod.) 637*8e3e3a7aSWarner Losh 638*8e3e3a7aSWarner Losh 639*8e3e3a7aSWarner Losh<p> 640*8e3e3a7aSWarner LoshWhenever there is a <code>__newindex</code> metamethod, 641*8e3e3a7aSWarner LoshLua does not perform the primitive assignment. 642*8e3e3a7aSWarner Losh(If necessary, 643*8e3e3a7aSWarner Loshthe metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a> 644*8e3e3a7aSWarner Loshto do the assignment.) 645*8e3e3a7aSWarner Losh</li> 646*8e3e3a7aSWarner Losh 647*8e3e3a7aSWarner Losh<li><b><code>__call</code>: </b> 648*8e3e3a7aSWarner LoshThe call operation <code>func(args)</code>. 649*8e3e3a7aSWarner LoshThis event happens when Lua tries to call a non-function value 650*8e3e3a7aSWarner Losh(that is, <code>func</code> is not a function). 651*8e3e3a7aSWarner LoshThe metamethod is looked up in <code>func</code>. 652*8e3e3a7aSWarner LoshIf present, 653*8e3e3a7aSWarner Loshthe metamethod is called with <code>func</code> as its first argument, 654*8e3e3a7aSWarner Loshfollowed by the arguments of the original call (<code>args</code>). 655*8e3e3a7aSWarner LoshAll results of the call 656*8e3e3a7aSWarner Loshare the result of the operation. 657*8e3e3a7aSWarner Losh(This is the only metamethod that allows multiple results.) 658*8e3e3a7aSWarner Losh</li> 659*8e3e3a7aSWarner Losh 660*8e3e3a7aSWarner Losh</ul> 661*8e3e3a7aSWarner Losh 662*8e3e3a7aSWarner Losh<p> 663*8e3e3a7aSWarner LoshIt is a good practice to add all needed metamethods to a table 664*8e3e3a7aSWarner Loshbefore setting it as a metatable of some object. 665*8e3e3a7aSWarner LoshIn particular, the <code>__gc</code> metamethod works only when this order 666*8e3e3a7aSWarner Loshis followed (see <a href="#2.5.1">§2.5.1</a>). 667*8e3e3a7aSWarner Losh 668*8e3e3a7aSWarner Losh 669*8e3e3a7aSWarner Losh<p> 670*8e3e3a7aSWarner LoshBecause metatables are regular tables, 671*8e3e3a7aSWarner Loshthey can contain arbitrary fields, 672*8e3e3a7aSWarner Loshnot only the event names defined above. 673*8e3e3a7aSWarner LoshSome functions in the standard library 674*8e3e3a7aSWarner Losh(e.g., <a href="#pdf-tostring"><code>tostring</code></a>) 675*8e3e3a7aSWarner Loshuse other fields in metatables for their own purposes. 676*8e3e3a7aSWarner Losh 677*8e3e3a7aSWarner Losh 678*8e3e3a7aSWarner Losh 679*8e3e3a7aSWarner Losh 680*8e3e3a7aSWarner Losh 681*8e3e3a7aSWarner Losh<h2>2.5 – <a name="2.5">Garbage Collection</a></h2> 682*8e3e3a7aSWarner Losh 683*8e3e3a7aSWarner Losh<p> 684*8e3e3a7aSWarner LoshLua performs automatic memory management. 685*8e3e3a7aSWarner LoshThis means that 686*8e3e3a7aSWarner Loshyou do not have to worry about allocating memory for new objects 687*8e3e3a7aSWarner Loshor freeing it when the objects are no longer needed. 688*8e3e3a7aSWarner LoshLua manages memory automatically by running 689*8e3e3a7aSWarner Losha <em>garbage collector</em> to collect all <em>dead objects</em> 690*8e3e3a7aSWarner Losh(that is, objects that are no longer accessible from Lua). 691*8e3e3a7aSWarner LoshAll memory used by Lua is subject to automatic management: 692*8e3e3a7aSWarner Loshstrings, tables, userdata, functions, threads, internal structures, etc. 693*8e3e3a7aSWarner Losh 694*8e3e3a7aSWarner Losh 695*8e3e3a7aSWarner Losh<p> 696*8e3e3a7aSWarner LoshLua implements an incremental mark-and-sweep collector. 697*8e3e3a7aSWarner LoshIt uses two numbers to control its garbage-collection cycles: 698*8e3e3a7aSWarner Loshthe <em>garbage-collector pause</em> and 699*8e3e3a7aSWarner Loshthe <em>garbage-collector step multiplier</em>. 700*8e3e3a7aSWarner LoshBoth use percentage points as units 701*8e3e3a7aSWarner Losh(e.g., a value of 100 means an internal value of 1). 702*8e3e3a7aSWarner Losh 703*8e3e3a7aSWarner Losh 704*8e3e3a7aSWarner Losh<p> 705*8e3e3a7aSWarner LoshThe garbage-collector pause 706*8e3e3a7aSWarner Loshcontrols how long the collector waits before starting a new cycle. 707*8e3e3a7aSWarner LoshLarger values make the collector less aggressive. 708*8e3e3a7aSWarner LoshValues smaller than 100 mean the collector will not wait to 709*8e3e3a7aSWarner Loshstart a new cycle. 710*8e3e3a7aSWarner LoshA value of 200 means that the collector waits for the total memory in use 711*8e3e3a7aSWarner Loshto double before starting a new cycle. 712*8e3e3a7aSWarner Losh 713*8e3e3a7aSWarner Losh 714*8e3e3a7aSWarner Losh<p> 715*8e3e3a7aSWarner LoshThe garbage-collector step multiplier 716*8e3e3a7aSWarner Loshcontrols the relative speed of the collector relative to 717*8e3e3a7aSWarner Loshmemory allocation. 718*8e3e3a7aSWarner LoshLarger values make the collector more aggressive but also increase 719*8e3e3a7aSWarner Loshthe size of each incremental step. 720*8e3e3a7aSWarner LoshYou should not use values smaller than 100, 721*8e3e3a7aSWarner Loshbecause they make the collector too slow and 722*8e3e3a7aSWarner Loshcan result in the collector never finishing a cycle. 723*8e3e3a7aSWarner LoshThe default is 200, 724*8e3e3a7aSWarner Loshwhich means that the collector runs at "twice" 725*8e3e3a7aSWarner Loshthe speed of memory allocation. 726*8e3e3a7aSWarner Losh 727*8e3e3a7aSWarner Losh 728*8e3e3a7aSWarner Losh<p> 729*8e3e3a7aSWarner LoshIf you set the step multiplier to a very large number 730*8e3e3a7aSWarner Losh(larger than 10% of the maximum number of 731*8e3e3a7aSWarner Loshbytes that the program may use), 732*8e3e3a7aSWarner Loshthe collector behaves like a stop-the-world collector. 733*8e3e3a7aSWarner LoshIf you then set the pause to 200, 734*8e3e3a7aSWarner Loshthe collector behaves as in old Lua versions, 735*8e3e3a7aSWarner Loshdoing a complete collection every time Lua doubles its 736*8e3e3a7aSWarner Loshmemory usage. 737*8e3e3a7aSWarner Losh 738*8e3e3a7aSWarner Losh 739*8e3e3a7aSWarner Losh<p> 740*8e3e3a7aSWarner LoshYou can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C 741*8e3e3a7aSWarner Loshor <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. 742*8e3e3a7aSWarner LoshYou can also use these functions to control 743*8e3e3a7aSWarner Loshthe collector directly (e.g., stop and restart it). 744*8e3e3a7aSWarner Losh 745*8e3e3a7aSWarner Losh 746*8e3e3a7aSWarner Losh 747*8e3e3a7aSWarner Losh<h3>2.5.1 – <a name="2.5.1">Garbage-Collection Metamethods</a></h3> 748*8e3e3a7aSWarner Losh 749*8e3e3a7aSWarner Losh<p> 750*8e3e3a7aSWarner LoshYou can set garbage-collector metamethods for tables 751*8e3e3a7aSWarner Loshand, using the C API, 752*8e3e3a7aSWarner Loshfor full userdata (see <a href="#2.4">§2.4</a>). 753*8e3e3a7aSWarner LoshThese metamethods are also called <em>finalizers</em>. 754*8e3e3a7aSWarner LoshFinalizers allow you to coordinate Lua's garbage collection 755*8e3e3a7aSWarner Loshwith external resource management 756*8e3e3a7aSWarner Losh(such as closing files, network or database connections, 757*8e3e3a7aSWarner Loshor freeing your own memory). 758*8e3e3a7aSWarner Losh 759*8e3e3a7aSWarner Losh 760*8e3e3a7aSWarner Losh<p> 761*8e3e3a7aSWarner LoshFor an object (table or userdata) to be finalized when collected, 762*8e3e3a7aSWarner Loshyou must <em>mark</em> it for finalization. 763*8e3e3a7aSWarner Losh 764*8e3e3a7aSWarner LoshYou mark an object for finalization when you set its metatable 765*8e3e3a7aSWarner Loshand the metatable has a field indexed by the string "<code>__gc</code>". 766*8e3e3a7aSWarner LoshNote that if you set a metatable without a <code>__gc</code> field 767*8e3e3a7aSWarner Loshand later create that field in the metatable, 768*8e3e3a7aSWarner Loshthe object will not be marked for finalization. 769*8e3e3a7aSWarner Losh 770*8e3e3a7aSWarner Losh 771*8e3e3a7aSWarner Losh<p> 772*8e3e3a7aSWarner LoshWhen a marked object becomes garbage, 773*8e3e3a7aSWarner Loshit is not collected immediately by the garbage collector. 774*8e3e3a7aSWarner LoshInstead, Lua puts it in a list. 775*8e3e3a7aSWarner LoshAfter the collection, 776*8e3e3a7aSWarner LoshLua goes through that list. 777*8e3e3a7aSWarner LoshFor each object in the list, 778*8e3e3a7aSWarner Loshit checks the object's <code>__gc</code> metamethod: 779*8e3e3a7aSWarner LoshIf it is a function, 780*8e3e3a7aSWarner LoshLua calls it with the object as its single argument; 781*8e3e3a7aSWarner Loshif the metamethod is not a function, 782*8e3e3a7aSWarner LoshLua simply ignores it. 783*8e3e3a7aSWarner Losh 784*8e3e3a7aSWarner Losh 785*8e3e3a7aSWarner Losh<p> 786*8e3e3a7aSWarner LoshAt the end of each garbage-collection cycle, 787*8e3e3a7aSWarner Loshthe finalizers for objects are called in 788*8e3e3a7aSWarner Loshthe reverse order that the objects were marked for finalization, 789*8e3e3a7aSWarner Loshamong those collected in that cycle; 790*8e3e3a7aSWarner Loshthat is, the first finalizer to be called is the one associated 791*8e3e3a7aSWarner Loshwith the object marked last in the program. 792*8e3e3a7aSWarner LoshThe execution of each finalizer may occur at any point during 793*8e3e3a7aSWarner Loshthe execution of the regular code. 794*8e3e3a7aSWarner Losh 795*8e3e3a7aSWarner Losh 796*8e3e3a7aSWarner Losh<p> 797*8e3e3a7aSWarner LoshBecause the object being collected must still be used by the finalizer, 798*8e3e3a7aSWarner Loshthat object (and other objects accessible only through it) 799*8e3e3a7aSWarner Loshmust be <em>resurrected</em> by Lua. 800*8e3e3a7aSWarner LoshUsually, this resurrection is transient, 801*8e3e3a7aSWarner Loshand the object memory is freed in the next garbage-collection cycle. 802*8e3e3a7aSWarner LoshHowever, if the finalizer stores the object in some global place 803*8e3e3a7aSWarner Losh(e.g., a global variable), 804*8e3e3a7aSWarner Loshthen the resurrection is permanent. 805*8e3e3a7aSWarner LoshMoreover, if the finalizer marks a finalizing object for finalization again, 806*8e3e3a7aSWarner Loshits finalizer will be called again in the next cycle where the 807*8e3e3a7aSWarner Loshobject is unreachable. 808*8e3e3a7aSWarner LoshIn any case, 809*8e3e3a7aSWarner Loshthe object memory is freed only in a GC cycle where 810*8e3e3a7aSWarner Loshthe object is unreachable and not marked for finalization. 811*8e3e3a7aSWarner Losh 812*8e3e3a7aSWarner Losh 813*8e3e3a7aSWarner Losh<p> 814*8e3e3a7aSWarner LoshWhen you close a state (see <a href="#lua_close"><code>lua_close</code></a>), 815*8e3e3a7aSWarner LoshLua calls the finalizers of all objects marked for finalization, 816*8e3e3a7aSWarner Loshfollowing the reverse order that they were marked. 817*8e3e3a7aSWarner LoshIf any finalizer marks objects for collection during that phase, 818*8e3e3a7aSWarner Loshthese marks have no effect. 819*8e3e3a7aSWarner Losh 820*8e3e3a7aSWarner Losh 821*8e3e3a7aSWarner Losh 822*8e3e3a7aSWarner Losh 823*8e3e3a7aSWarner Losh 824*8e3e3a7aSWarner Losh<h3>2.5.2 – <a name="2.5.2">Weak Tables</a></h3> 825*8e3e3a7aSWarner Losh 826*8e3e3a7aSWarner Losh<p> 827*8e3e3a7aSWarner LoshA <em>weak table</em> is a table whose elements are 828*8e3e3a7aSWarner Losh<em>weak references</em>. 829*8e3e3a7aSWarner LoshA weak reference is ignored by the garbage collector. 830*8e3e3a7aSWarner LoshIn other words, 831*8e3e3a7aSWarner Loshif the only references to an object are weak references, 832*8e3e3a7aSWarner Loshthen the garbage collector will collect that object. 833*8e3e3a7aSWarner Losh 834*8e3e3a7aSWarner Losh 835*8e3e3a7aSWarner Losh<p> 836*8e3e3a7aSWarner LoshA weak table can have weak keys, weak values, or both. 837*8e3e3a7aSWarner LoshA table with weak values allows the collection of its values, 838*8e3e3a7aSWarner Loshbut prevents the collection of its keys. 839*8e3e3a7aSWarner LoshA table with both weak keys and weak values allows the collection of 840*8e3e3a7aSWarner Loshboth keys and values. 841*8e3e3a7aSWarner LoshIn any case, if either the key or the value is collected, 842*8e3e3a7aSWarner Loshthe whole pair is removed from the table. 843*8e3e3a7aSWarner LoshThe weakness of a table is controlled by the 844*8e3e3a7aSWarner Losh<code>__mode</code> field of its metatable. 845*8e3e3a7aSWarner LoshIf the <code>__mode</code> field is a string containing the character '<code>k</code>', 846*8e3e3a7aSWarner Loshthe keys in the table are weak. 847*8e3e3a7aSWarner LoshIf <code>__mode</code> contains '<code>v</code>', 848*8e3e3a7aSWarner Loshthe values in the table are weak. 849*8e3e3a7aSWarner Losh 850*8e3e3a7aSWarner Losh 851*8e3e3a7aSWarner Losh<p> 852*8e3e3a7aSWarner LoshA table with weak keys and strong values 853*8e3e3a7aSWarner Loshis also called an <em>ephemeron table</em>. 854*8e3e3a7aSWarner LoshIn an ephemeron table, 855*8e3e3a7aSWarner Losha value is considered reachable only if its key is reachable. 856*8e3e3a7aSWarner LoshIn particular, 857*8e3e3a7aSWarner Loshif the only reference to a key comes through its value, 858*8e3e3a7aSWarner Loshthe pair is removed. 859*8e3e3a7aSWarner Losh 860*8e3e3a7aSWarner Losh 861*8e3e3a7aSWarner Losh<p> 862*8e3e3a7aSWarner LoshAny change in the weakness of a table may take effect only 863*8e3e3a7aSWarner Loshat the next collect cycle. 864*8e3e3a7aSWarner LoshIn particular, if you change the weakness to a stronger mode, 865*8e3e3a7aSWarner LoshLua may still collect some items from that table 866*8e3e3a7aSWarner Loshbefore the change takes effect. 867*8e3e3a7aSWarner Losh 868*8e3e3a7aSWarner Losh 869*8e3e3a7aSWarner Losh<p> 870*8e3e3a7aSWarner LoshOnly objects that have an explicit construction 871*8e3e3a7aSWarner Loshare removed from weak tables. 872*8e3e3a7aSWarner LoshValues, such as numbers and light C functions, 873*8e3e3a7aSWarner Loshare not subject to garbage collection, 874*8e3e3a7aSWarner Loshand therefore are not removed from weak tables 875*8e3e3a7aSWarner Losh(unless their associated values are collected). 876*8e3e3a7aSWarner LoshAlthough strings are subject to garbage collection, 877*8e3e3a7aSWarner Loshthey do not have an explicit construction, 878*8e3e3a7aSWarner Loshand therefore are not removed from weak tables. 879*8e3e3a7aSWarner Losh 880*8e3e3a7aSWarner Losh 881*8e3e3a7aSWarner Losh<p> 882*8e3e3a7aSWarner LoshResurrected objects 883*8e3e3a7aSWarner Losh(that is, objects being finalized 884*8e3e3a7aSWarner Loshand objects accessible only through objects being finalized) 885*8e3e3a7aSWarner Loshhave a special behavior in weak tables. 886*8e3e3a7aSWarner LoshThey are removed from weak values before running their finalizers, 887*8e3e3a7aSWarner Loshbut are removed from weak keys only in the next collection 888*8e3e3a7aSWarner Loshafter running their finalizers, when such objects are actually freed. 889*8e3e3a7aSWarner LoshThis behavior allows the finalizer to access properties 890*8e3e3a7aSWarner Loshassociated with the object through weak tables. 891*8e3e3a7aSWarner Losh 892*8e3e3a7aSWarner Losh 893*8e3e3a7aSWarner Losh<p> 894*8e3e3a7aSWarner LoshIf a weak table is among the resurrected objects in a collection cycle, 895*8e3e3a7aSWarner Loshit may not be properly cleared until the next cycle. 896*8e3e3a7aSWarner Losh 897*8e3e3a7aSWarner Losh 898*8e3e3a7aSWarner Losh 899*8e3e3a7aSWarner Losh 900*8e3e3a7aSWarner Losh 901*8e3e3a7aSWarner Losh 902*8e3e3a7aSWarner Losh 903*8e3e3a7aSWarner Losh<h2>2.6 – <a name="2.6">Coroutines</a></h2> 904*8e3e3a7aSWarner Losh 905*8e3e3a7aSWarner Losh<p> 906*8e3e3a7aSWarner LoshLua supports coroutines, 907*8e3e3a7aSWarner Loshalso called <em>collaborative multithreading</em>. 908*8e3e3a7aSWarner LoshA coroutine in Lua represents an independent thread of execution. 909*8e3e3a7aSWarner LoshUnlike threads in multithread systems, however, 910*8e3e3a7aSWarner Losha coroutine only suspends its execution by explicitly calling 911*8e3e3a7aSWarner Losha yield function. 912*8e3e3a7aSWarner Losh 913*8e3e3a7aSWarner Losh 914*8e3e3a7aSWarner Losh<p> 915*8e3e3a7aSWarner LoshYou create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>. 916*8e3e3a7aSWarner LoshIts sole argument is a function 917*8e3e3a7aSWarner Loshthat is the main function of the coroutine. 918*8e3e3a7aSWarner LoshThe <code>create</code> function only creates a new coroutine and 919*8e3e3a7aSWarner Loshreturns a handle to it (an object of type <em>thread</em>); 920*8e3e3a7aSWarner Loshit does not start the coroutine. 921*8e3e3a7aSWarner Losh 922*8e3e3a7aSWarner Losh 923*8e3e3a7aSWarner Losh<p> 924*8e3e3a7aSWarner LoshYou execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 925*8e3e3a7aSWarner LoshWhen you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 926*8e3e3a7aSWarner Loshpassing as its first argument 927*8e3e3a7aSWarner Losha thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 928*8e3e3a7aSWarner Loshthe coroutine starts its execution by 929*8e3e3a7aSWarner Loshcalling its main function. 930*8e3e3a7aSWarner LoshExtra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed 931*8e3e3a7aSWarner Loshas arguments to that function. 932*8e3e3a7aSWarner LoshAfter the coroutine starts running, 933*8e3e3a7aSWarner Loshit runs until it terminates or <em>yields</em>. 934*8e3e3a7aSWarner Losh 935*8e3e3a7aSWarner Losh 936*8e3e3a7aSWarner Losh<p> 937*8e3e3a7aSWarner LoshA coroutine can terminate its execution in two ways: 938*8e3e3a7aSWarner Loshnormally, when its main function returns 939*8e3e3a7aSWarner Losh(explicitly or implicitly, after the last instruction); 940*8e3e3a7aSWarner Loshand abnormally, if there is an unprotected error. 941*8e3e3a7aSWarner LoshIn case of normal termination, 942*8e3e3a7aSWarner Losh<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>, 943*8e3e3a7aSWarner Loshplus any values returned by the coroutine main function. 944*8e3e3a7aSWarner LoshIn case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b> 945*8e3e3a7aSWarner Loshplus an error object. 946*8e3e3a7aSWarner Losh 947*8e3e3a7aSWarner Losh 948*8e3e3a7aSWarner Losh<p> 949*8e3e3a7aSWarner LoshA coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 950*8e3e3a7aSWarner LoshWhen a coroutine yields, 951*8e3e3a7aSWarner Loshthe corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately, 952*8e3e3a7aSWarner Losheven if the yield happens inside nested function calls 953*8e3e3a7aSWarner Losh(that is, not in the main function, 954*8e3e3a7aSWarner Loshbut in a function directly or indirectly called by the main function). 955*8e3e3a7aSWarner LoshIn the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>, 956*8e3e3a7aSWarner Loshplus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 957*8e3e3a7aSWarner LoshThe next time you resume the same coroutine, 958*8e3e3a7aSWarner Loshit continues its execution from the point where it yielded, 959*8e3e3a7aSWarner Loshwith the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra 960*8e3e3a7aSWarner Losharguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 961*8e3e3a7aSWarner Losh 962*8e3e3a7aSWarner Losh 963*8e3e3a7aSWarner Losh<p> 964*8e3e3a7aSWarner LoshLike <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 965*8e3e3a7aSWarner Loshthe <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine, 966*8e3e3a7aSWarner Loshbut instead of returning the coroutine itself, 967*8e3e3a7aSWarner Loshit returns a function that, when called, resumes the coroutine. 968*8e3e3a7aSWarner LoshAny arguments passed to this function 969*8e3e3a7aSWarner Loshgo as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 970*8e3e3a7aSWarner 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>, 971*8e3e3a7aSWarner Loshexcept the first one (the boolean error code). 972*8e3e3a7aSWarner LoshUnlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 973*8e3e3a7aSWarner Losh<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors; 974*8e3e3a7aSWarner Loshany error is propagated to the caller. 975*8e3e3a7aSWarner Losh 976*8e3e3a7aSWarner Losh 977*8e3e3a7aSWarner Losh<p> 978*8e3e3a7aSWarner LoshAs an example of how coroutines work, 979*8e3e3a7aSWarner Loshconsider the following code: 980*8e3e3a7aSWarner Losh 981*8e3e3a7aSWarner Losh<pre> 982*8e3e3a7aSWarner Losh function foo (a) 983*8e3e3a7aSWarner Losh print("foo", a) 984*8e3e3a7aSWarner Losh return coroutine.yield(2*a) 985*8e3e3a7aSWarner Losh end 986*8e3e3a7aSWarner Losh 987*8e3e3a7aSWarner Losh co = coroutine.create(function (a,b) 988*8e3e3a7aSWarner Losh print("co-body", a, b) 989*8e3e3a7aSWarner Losh local r = foo(a+1) 990*8e3e3a7aSWarner Losh print("co-body", r) 991*8e3e3a7aSWarner Losh local r, s = coroutine.yield(a+b, a-b) 992*8e3e3a7aSWarner Losh print("co-body", r, s) 993*8e3e3a7aSWarner Losh return b, "end" 994*8e3e3a7aSWarner Losh end) 995*8e3e3a7aSWarner Losh 996*8e3e3a7aSWarner Losh print("main", coroutine.resume(co, 1, 10)) 997*8e3e3a7aSWarner Losh print("main", coroutine.resume(co, "r")) 998*8e3e3a7aSWarner Losh print("main", coroutine.resume(co, "x", "y")) 999*8e3e3a7aSWarner Losh print("main", coroutine.resume(co, "x", "y")) 1000*8e3e3a7aSWarner Losh</pre><p> 1001*8e3e3a7aSWarner LoshWhen you run it, it produces the following output: 1002*8e3e3a7aSWarner Losh 1003*8e3e3a7aSWarner Losh<pre> 1004*8e3e3a7aSWarner Losh co-body 1 10 1005*8e3e3a7aSWarner Losh foo 2 1006*8e3e3a7aSWarner Losh main true 4 1007*8e3e3a7aSWarner Losh co-body r 1008*8e3e3a7aSWarner Losh main true 11 -9 1009*8e3e3a7aSWarner Losh co-body x y 1010*8e3e3a7aSWarner Losh main true 10 end 1011*8e3e3a7aSWarner Losh main false cannot resume dead coroutine 1012*8e3e3a7aSWarner Losh</pre> 1013*8e3e3a7aSWarner Losh 1014*8e3e3a7aSWarner Losh<p> 1015*8e3e3a7aSWarner LoshYou can also create and manipulate coroutines through the C API: 1016*8e3e3a7aSWarner Loshsee functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>, 1017*8e3e3a7aSWarner Loshand <a href="#lua_yield"><code>lua_yield</code></a>. 1018*8e3e3a7aSWarner Losh 1019*8e3e3a7aSWarner Losh 1020*8e3e3a7aSWarner Losh 1021*8e3e3a7aSWarner Losh 1022*8e3e3a7aSWarner Losh 1023*8e3e3a7aSWarner Losh<h1>3 – <a name="3">The Language</a></h1> 1024*8e3e3a7aSWarner Losh 1025*8e3e3a7aSWarner Losh<p> 1026*8e3e3a7aSWarner LoshThis section describes the lexis, the syntax, and the semantics of Lua. 1027*8e3e3a7aSWarner LoshIn other words, 1028*8e3e3a7aSWarner Loshthis section describes 1029*8e3e3a7aSWarner Loshwhich tokens are valid, 1030*8e3e3a7aSWarner Loshhow they can be combined, 1031*8e3e3a7aSWarner Loshand what their combinations mean. 1032*8e3e3a7aSWarner Losh 1033*8e3e3a7aSWarner Losh 1034*8e3e3a7aSWarner Losh<p> 1035*8e3e3a7aSWarner LoshLanguage constructs will be explained using the usual extended BNF notation, 1036*8e3e3a7aSWarner Loshin which 1037*8e3e3a7aSWarner Losh{<em>a</em>} means 0 or more <em>a</em>'s, and 1038*8e3e3a7aSWarner Losh[<em>a</em>] means an optional <em>a</em>. 1039*8e3e3a7aSWarner LoshNon-terminals are shown like non-terminal, 1040*8e3e3a7aSWarner Loshkeywords are shown like <b>kword</b>, 1041*8e3e3a7aSWarner Loshand other terminal symbols are shown like ‘<b>=</b>’. 1042*8e3e3a7aSWarner LoshThe complete syntax of Lua can be found in <a href="#9">§9</a> 1043*8e3e3a7aSWarner Loshat the end of this manual. 1044*8e3e3a7aSWarner Losh 1045*8e3e3a7aSWarner Losh 1046*8e3e3a7aSWarner Losh 1047*8e3e3a7aSWarner Losh<h2>3.1 – <a name="3.1">Lexical Conventions</a></h2> 1048*8e3e3a7aSWarner Losh 1049*8e3e3a7aSWarner Losh<p> 1050*8e3e3a7aSWarner LoshLua is a free-form language. 1051*8e3e3a7aSWarner LoshIt ignores spaces (including new lines) and comments 1052*8e3e3a7aSWarner Loshbetween lexical elements (tokens), 1053*8e3e3a7aSWarner Loshexcept as delimiters between names and keywords. 1054*8e3e3a7aSWarner Losh 1055*8e3e3a7aSWarner Losh 1056*8e3e3a7aSWarner Losh<p> 1057*8e3e3a7aSWarner Losh<em>Names</em> 1058*8e3e3a7aSWarner Losh(also called <em>identifiers</em>) 1059*8e3e3a7aSWarner Loshin Lua can be any string of letters, 1060*8e3e3a7aSWarner Loshdigits, and underscores, 1061*8e3e3a7aSWarner Loshnot beginning with a digit and 1062*8e3e3a7aSWarner Loshnot being a reserved word. 1063*8e3e3a7aSWarner LoshIdentifiers are used to name variables, table fields, and labels. 1064*8e3e3a7aSWarner Losh 1065*8e3e3a7aSWarner Losh 1066*8e3e3a7aSWarner Losh<p> 1067*8e3e3a7aSWarner LoshThe following <em>keywords</em> are reserved 1068*8e3e3a7aSWarner Loshand cannot be used as names: 1069*8e3e3a7aSWarner Losh 1070*8e3e3a7aSWarner Losh 1071*8e3e3a7aSWarner Losh<pre> 1072*8e3e3a7aSWarner Losh and break do else elseif end 1073*8e3e3a7aSWarner Losh false for function goto if in 1074*8e3e3a7aSWarner Losh local nil not or repeat return 1075*8e3e3a7aSWarner Losh then true until while 1076*8e3e3a7aSWarner Losh</pre> 1077*8e3e3a7aSWarner Losh 1078*8e3e3a7aSWarner Losh<p> 1079*8e3e3a7aSWarner LoshLua is a case-sensitive language: 1080*8e3e3a7aSWarner Losh<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> 1081*8e3e3a7aSWarner Loshare two different, valid names. 1082*8e3e3a7aSWarner LoshAs a convention, 1083*8e3e3a7aSWarner Loshprograms should avoid creating 1084*8e3e3a7aSWarner Loshnames that start with an underscore followed by 1085*8e3e3a7aSWarner Loshone or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>). 1086*8e3e3a7aSWarner Losh 1087*8e3e3a7aSWarner Losh 1088*8e3e3a7aSWarner Losh<p> 1089*8e3e3a7aSWarner LoshThe following strings denote other tokens: 1090*8e3e3a7aSWarner Losh 1091*8e3e3a7aSWarner Losh<pre> 1092*8e3e3a7aSWarner Losh + - * / % ^ # 1093*8e3e3a7aSWarner Losh & ~ | << >> // 1094*8e3e3a7aSWarner Losh == ~= <= >= < > = 1095*8e3e3a7aSWarner Losh ( ) { } [ ] :: 1096*8e3e3a7aSWarner Losh ; : , . .. ... 1097*8e3e3a7aSWarner Losh</pre> 1098*8e3e3a7aSWarner Losh 1099*8e3e3a7aSWarner Losh<p> 1100*8e3e3a7aSWarner LoshA <em>short literal string</em> 1101*8e3e3a7aSWarner Loshcan be delimited by matching single or double quotes, 1102*8e3e3a7aSWarner Loshand can contain the following C-like escape sequences: 1103*8e3e3a7aSWarner Losh'<code>\a</code>' (bell), 1104*8e3e3a7aSWarner Losh'<code>\b</code>' (backspace), 1105*8e3e3a7aSWarner Losh'<code>\f</code>' (form feed), 1106*8e3e3a7aSWarner Losh'<code>\n</code>' (newline), 1107*8e3e3a7aSWarner Losh'<code>\r</code>' (carriage return), 1108*8e3e3a7aSWarner Losh'<code>\t</code>' (horizontal tab), 1109*8e3e3a7aSWarner Losh'<code>\v</code>' (vertical tab), 1110*8e3e3a7aSWarner Losh'<code>\\</code>' (backslash), 1111*8e3e3a7aSWarner Losh'<code>\"</code>' (quotation mark [double quote]), 1112*8e3e3a7aSWarner Loshand '<code>\'</code>' (apostrophe [single quote]). 1113*8e3e3a7aSWarner LoshA backslash followed by a line break 1114*8e3e3a7aSWarner Loshresults in a newline in the string. 1115*8e3e3a7aSWarner LoshThe escape sequence '<code>\z</code>' skips the following span 1116*8e3e3a7aSWarner Loshof white-space characters, 1117*8e3e3a7aSWarner Loshincluding line breaks; 1118*8e3e3a7aSWarner Loshit is particularly useful to break and indent a long literal string 1119*8e3e3a7aSWarner Loshinto multiple lines without adding the newlines and spaces 1120*8e3e3a7aSWarner Loshinto the string contents. 1121*8e3e3a7aSWarner LoshA short literal string cannot contain unescaped line breaks 1122*8e3e3a7aSWarner Loshnor escapes not forming a valid escape sequence. 1123*8e3e3a7aSWarner Losh 1124*8e3e3a7aSWarner Losh 1125*8e3e3a7aSWarner Losh<p> 1126*8e3e3a7aSWarner LoshWe can specify any byte in a short literal string by its numeric value 1127*8e3e3a7aSWarner Losh(including embedded zeros). 1128*8e3e3a7aSWarner LoshThis can be done 1129*8e3e3a7aSWarner Loshwith the escape sequence <code>\x<em>XX</em></code>, 1130*8e3e3a7aSWarner Loshwhere <em>XX</em> is a sequence of exactly two hexadecimal digits, 1131*8e3e3a7aSWarner Loshor with the escape sequence <code>\<em>ddd</em></code>, 1132*8e3e3a7aSWarner Loshwhere <em>ddd</em> is a sequence of up to three decimal digits. 1133*8e3e3a7aSWarner Losh(Note that if a decimal escape sequence is to be followed by a digit, 1134*8e3e3a7aSWarner Loshit must be expressed using exactly three digits.) 1135*8e3e3a7aSWarner Losh 1136*8e3e3a7aSWarner Losh 1137*8e3e3a7aSWarner Losh<p> 1138*8e3e3a7aSWarner LoshThe UTF-8 encoding of a Unicode character 1139*8e3e3a7aSWarner Loshcan be inserted in a literal string with 1140*8e3e3a7aSWarner Loshthe escape sequence <code>\u{<em>XXX</em>}</code> 1141*8e3e3a7aSWarner Losh(note the mandatory enclosing brackets), 1142*8e3e3a7aSWarner Loshwhere <em>XXX</em> is a sequence of one or more hexadecimal digits 1143*8e3e3a7aSWarner Loshrepresenting the character code point. 1144*8e3e3a7aSWarner Losh 1145*8e3e3a7aSWarner Losh 1146*8e3e3a7aSWarner Losh<p> 1147*8e3e3a7aSWarner LoshLiteral strings can also be defined using a long format 1148*8e3e3a7aSWarner Loshenclosed by <em>long brackets</em>. 1149*8e3e3a7aSWarner LoshWe define an <em>opening long bracket of level <em>n</em></em> as an opening 1150*8e3e3a7aSWarner Loshsquare bracket followed by <em>n</em> equal signs followed by another 1151*8e3e3a7aSWarner Loshopening square bracket. 1152*8e3e3a7aSWarner LoshSo, an opening long bracket of level 0 is written as <code>[[</code>, 1153*8e3e3a7aSWarner Loshan opening long bracket of level 1 is written as <code>[=[</code>, 1154*8e3e3a7aSWarner Loshand so on. 1155*8e3e3a7aSWarner LoshA <em>closing long bracket</em> is defined similarly; 1156*8e3e3a7aSWarner Loshfor instance, 1157*8e3e3a7aSWarner Losha closing long bracket of level 4 is written as <code>]====]</code>. 1158*8e3e3a7aSWarner LoshA <em>long literal</em> starts with an opening long bracket of any level and 1159*8e3e3a7aSWarner Loshends at the first closing long bracket of the same level. 1160*8e3e3a7aSWarner LoshIt can contain any text except a closing bracket of the same level. 1161*8e3e3a7aSWarner LoshLiterals in this bracketed form can run for several lines, 1162*8e3e3a7aSWarner Loshdo not interpret any escape sequences, 1163*8e3e3a7aSWarner Loshand ignore long brackets of any other level. 1164*8e3e3a7aSWarner LoshAny kind of end-of-line sequence 1165*8e3e3a7aSWarner Losh(carriage return, newline, carriage return followed by newline, 1166*8e3e3a7aSWarner Loshor newline followed by carriage return) 1167*8e3e3a7aSWarner Loshis converted to a simple newline. 1168*8e3e3a7aSWarner Losh 1169*8e3e3a7aSWarner Losh 1170*8e3e3a7aSWarner Losh<p> 1171*8e3e3a7aSWarner LoshFor convenience, 1172*8e3e3a7aSWarner Loshwhen the opening long bracket is immediately followed by a newline, 1173*8e3e3a7aSWarner Loshthe newline is not included in the string. 1174*8e3e3a7aSWarner LoshAs an example, in a system using ASCII 1175*8e3e3a7aSWarner Losh(in which '<code>a</code>' is coded as 97, 1176*8e3e3a7aSWarner Loshnewline is coded as 10, and '<code>1</code>' is coded as 49), 1177*8e3e3a7aSWarner Loshthe five literal strings below denote the same string: 1178*8e3e3a7aSWarner Losh 1179*8e3e3a7aSWarner Losh<pre> 1180*8e3e3a7aSWarner Losh a = 'alo\n123"' 1181*8e3e3a7aSWarner Losh a = "alo\n123\"" 1182*8e3e3a7aSWarner Losh a = '\97lo\10\04923"' 1183*8e3e3a7aSWarner Losh a = [[alo 1184*8e3e3a7aSWarner Losh 123"]] 1185*8e3e3a7aSWarner Losh a = [==[ 1186*8e3e3a7aSWarner Losh alo 1187*8e3e3a7aSWarner Losh 123"]==] 1188*8e3e3a7aSWarner Losh</pre> 1189*8e3e3a7aSWarner Losh 1190*8e3e3a7aSWarner Losh<p> 1191*8e3e3a7aSWarner LoshAny byte in a literal string not 1192*8e3e3a7aSWarner Loshexplicitly affected by the previous rules represents itself. 1193*8e3e3a7aSWarner LoshHowever, Lua opens files for parsing in text mode, 1194*8e3e3a7aSWarner Loshand the system file functions may have problems with 1195*8e3e3a7aSWarner Loshsome control characters. 1196*8e3e3a7aSWarner LoshSo, it is safer to represent 1197*8e3e3a7aSWarner Loshnon-text data as a quoted literal with 1198*8e3e3a7aSWarner Loshexplicit escape sequences for the non-text characters. 1199*8e3e3a7aSWarner Losh 1200*8e3e3a7aSWarner Losh 1201*8e3e3a7aSWarner Losh<p> 1202*8e3e3a7aSWarner LoshA <em>numeric constant</em> (or <em>numeral</em>) 1203*8e3e3a7aSWarner Loshcan be written with an optional fractional part 1204*8e3e3a7aSWarner Loshand an optional decimal exponent, 1205*8e3e3a7aSWarner Loshmarked by a letter '<code>e</code>' or '<code>E</code>'. 1206*8e3e3a7aSWarner LoshLua also accepts hexadecimal constants, 1207*8e3e3a7aSWarner Loshwhich start with <code>0x</code> or <code>0X</code>. 1208*8e3e3a7aSWarner LoshHexadecimal constants also accept an optional fractional part 1209*8e3e3a7aSWarner Loshplus an optional binary exponent, 1210*8e3e3a7aSWarner Loshmarked by a letter '<code>p</code>' or '<code>P</code>'. 1211*8e3e3a7aSWarner LoshA numeric constant with a radix point or an exponent 1212*8e3e3a7aSWarner Loshdenotes a float; 1213*8e3e3a7aSWarner Loshotherwise, 1214*8e3e3a7aSWarner Loshif its value fits in an integer, 1215*8e3e3a7aSWarner Loshit denotes an integer. 1216*8e3e3a7aSWarner LoshExamples of valid integer constants are 1217*8e3e3a7aSWarner Losh 1218*8e3e3a7aSWarner Losh<pre> 1219*8e3e3a7aSWarner Losh 3 345 0xff 0xBEBADA 1220*8e3e3a7aSWarner Losh</pre><p> 1221*8e3e3a7aSWarner LoshExamples of valid float constants are 1222*8e3e3a7aSWarner Losh 1223*8e3e3a7aSWarner Losh<pre> 1224*8e3e3a7aSWarner Losh 3.0 3.1416 314.16e-2 0.31416E1 34e1 1225*8e3e3a7aSWarner Losh 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 1226*8e3e3a7aSWarner Losh</pre> 1227*8e3e3a7aSWarner Losh 1228*8e3e3a7aSWarner Losh<p> 1229*8e3e3a7aSWarner LoshA <em>comment</em> starts with a double hyphen (<code>--</code>) 1230*8e3e3a7aSWarner Loshanywhere outside a string. 1231*8e3e3a7aSWarner LoshIf the text immediately after <code>--</code> is not an opening long bracket, 1232*8e3e3a7aSWarner Loshthe comment is a <em>short comment</em>, 1233*8e3e3a7aSWarner Loshwhich runs until the end of the line. 1234*8e3e3a7aSWarner LoshOtherwise, it is a <em>long comment</em>, 1235*8e3e3a7aSWarner Loshwhich runs until the corresponding closing long bracket. 1236*8e3e3a7aSWarner LoshLong comments are frequently used to disable code temporarily. 1237*8e3e3a7aSWarner Losh 1238*8e3e3a7aSWarner Losh 1239*8e3e3a7aSWarner Losh 1240*8e3e3a7aSWarner Losh 1241*8e3e3a7aSWarner Losh 1242*8e3e3a7aSWarner Losh<h2>3.2 – <a name="3.2">Variables</a></h2> 1243*8e3e3a7aSWarner Losh 1244*8e3e3a7aSWarner Losh<p> 1245*8e3e3a7aSWarner LoshVariables are places that store values. 1246*8e3e3a7aSWarner LoshThere are three kinds of variables in Lua: 1247*8e3e3a7aSWarner Loshglobal variables, local variables, and table fields. 1248*8e3e3a7aSWarner Losh 1249*8e3e3a7aSWarner Losh 1250*8e3e3a7aSWarner Losh<p> 1251*8e3e3a7aSWarner LoshA single name can denote a global variable or a local variable 1252*8e3e3a7aSWarner Losh(or a function's formal parameter, 1253*8e3e3a7aSWarner Loshwhich is a particular kind of local variable): 1254*8e3e3a7aSWarner Losh 1255*8e3e3a7aSWarner Losh<pre> 1256*8e3e3a7aSWarner Losh var ::= Name 1257*8e3e3a7aSWarner Losh</pre><p> 1258*8e3e3a7aSWarner LoshName denotes identifiers, as defined in <a href="#3.1">§3.1</a>. 1259*8e3e3a7aSWarner Losh 1260*8e3e3a7aSWarner Losh 1261*8e3e3a7aSWarner Losh<p> 1262*8e3e3a7aSWarner LoshAny variable name is assumed to be global unless explicitly declared 1263*8e3e3a7aSWarner Loshas a local (see <a href="#3.3.7">§3.3.7</a>). 1264*8e3e3a7aSWarner LoshLocal variables are <em>lexically scoped</em>: 1265*8e3e3a7aSWarner Loshlocal variables can be freely accessed by functions 1266*8e3e3a7aSWarner Loshdefined inside their scope (see <a href="#3.5">§3.5</a>). 1267*8e3e3a7aSWarner Losh 1268*8e3e3a7aSWarner Losh 1269*8e3e3a7aSWarner Losh<p> 1270*8e3e3a7aSWarner LoshBefore the first assignment to a variable, its value is <b>nil</b>. 1271*8e3e3a7aSWarner Losh 1272*8e3e3a7aSWarner Losh 1273*8e3e3a7aSWarner Losh<p> 1274*8e3e3a7aSWarner LoshSquare brackets are used to index a table: 1275*8e3e3a7aSWarner Losh 1276*8e3e3a7aSWarner Losh<pre> 1277*8e3e3a7aSWarner Losh var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ 1278*8e3e3a7aSWarner Losh</pre><p> 1279*8e3e3a7aSWarner LoshThe meaning of accesses to table fields can be changed via metatables. 1280*8e3e3a7aSWarner LoshAn access to an indexed variable <code>t[i]</code> is equivalent to 1281*8e3e3a7aSWarner Losha call <code>gettable_event(t,i)</code>. 1282*8e3e3a7aSWarner Losh(See <a href="#2.4">§2.4</a> for a complete description of the 1283*8e3e3a7aSWarner Losh<code>gettable_event</code> function. 1284*8e3e3a7aSWarner LoshThis function is not defined or callable in Lua. 1285*8e3e3a7aSWarner LoshWe use it here only for explanatory purposes.) 1286*8e3e3a7aSWarner Losh 1287*8e3e3a7aSWarner Losh 1288*8e3e3a7aSWarner Losh<p> 1289*8e3e3a7aSWarner LoshThe syntax <code>var.Name</code> is just syntactic sugar for 1290*8e3e3a7aSWarner Losh<code>var["Name"]</code>: 1291*8e3e3a7aSWarner Losh 1292*8e3e3a7aSWarner Losh<pre> 1293*8e3e3a7aSWarner Losh var ::= prefixexp ‘<b>.</b>’ Name 1294*8e3e3a7aSWarner Losh</pre> 1295*8e3e3a7aSWarner Losh 1296*8e3e3a7aSWarner Losh<p> 1297*8e3e3a7aSWarner LoshAn access to a global variable <code>x</code> 1298*8e3e3a7aSWarner Loshis equivalent to <code>_ENV.x</code>. 1299*8e3e3a7aSWarner LoshDue to the way that chunks are compiled, 1300*8e3e3a7aSWarner Losh<code>_ENV</code> is never a global name (see <a href="#2.2">§2.2</a>). 1301*8e3e3a7aSWarner Losh 1302*8e3e3a7aSWarner Losh 1303*8e3e3a7aSWarner Losh 1304*8e3e3a7aSWarner Losh 1305*8e3e3a7aSWarner Losh 1306*8e3e3a7aSWarner Losh<h2>3.3 – <a name="3.3">Statements</a></h2> 1307*8e3e3a7aSWarner Losh 1308*8e3e3a7aSWarner Losh<p> 1309*8e3e3a7aSWarner LoshLua supports an almost conventional set of statements, 1310*8e3e3a7aSWarner Loshsimilar to those in Pascal or C. 1311*8e3e3a7aSWarner LoshThis set includes 1312*8e3e3a7aSWarner Loshassignments, control structures, function calls, 1313*8e3e3a7aSWarner Loshand variable declarations. 1314*8e3e3a7aSWarner Losh 1315*8e3e3a7aSWarner Losh 1316*8e3e3a7aSWarner Losh 1317*8e3e3a7aSWarner Losh<h3>3.3.1 – <a name="3.3.1">Blocks</a></h3> 1318*8e3e3a7aSWarner Losh 1319*8e3e3a7aSWarner Losh<p> 1320*8e3e3a7aSWarner LoshA block is a list of statements, 1321*8e3e3a7aSWarner Loshwhich are executed sequentially: 1322*8e3e3a7aSWarner Losh 1323*8e3e3a7aSWarner Losh<pre> 1324*8e3e3a7aSWarner Losh block ::= {stat} 1325*8e3e3a7aSWarner Losh</pre><p> 1326*8e3e3a7aSWarner LoshLua has <em>empty statements</em> 1327*8e3e3a7aSWarner Loshthat allow you to separate statements with semicolons, 1328*8e3e3a7aSWarner Loshstart a block with a semicolon 1329*8e3e3a7aSWarner Loshor write two semicolons in sequence: 1330*8e3e3a7aSWarner Losh 1331*8e3e3a7aSWarner Losh<pre> 1332*8e3e3a7aSWarner Losh stat ::= ‘<b>;</b>’ 1333*8e3e3a7aSWarner Losh</pre> 1334*8e3e3a7aSWarner Losh 1335*8e3e3a7aSWarner Losh<p> 1336*8e3e3a7aSWarner LoshFunction calls and assignments 1337*8e3e3a7aSWarner Loshcan start with an open parenthesis. 1338*8e3e3a7aSWarner LoshThis possibility leads to an ambiguity in Lua's grammar. 1339*8e3e3a7aSWarner LoshConsider the following fragment: 1340*8e3e3a7aSWarner Losh 1341*8e3e3a7aSWarner Losh<pre> 1342*8e3e3a7aSWarner Losh a = b + c 1343*8e3e3a7aSWarner Losh (print or io.write)('done') 1344*8e3e3a7aSWarner Losh</pre><p> 1345*8e3e3a7aSWarner LoshThe grammar could see it in two ways: 1346*8e3e3a7aSWarner Losh 1347*8e3e3a7aSWarner Losh<pre> 1348*8e3e3a7aSWarner Losh a = b + c(print or io.write)('done') 1349*8e3e3a7aSWarner Losh 1350*8e3e3a7aSWarner Losh a = b + c; (print or io.write)('done') 1351*8e3e3a7aSWarner Losh</pre><p> 1352*8e3e3a7aSWarner LoshThe current parser always sees such constructions 1353*8e3e3a7aSWarner Loshin the first way, 1354*8e3e3a7aSWarner Loshinterpreting the open parenthesis 1355*8e3e3a7aSWarner Loshas the start of the arguments to a call. 1356*8e3e3a7aSWarner LoshTo avoid this ambiguity, 1357*8e3e3a7aSWarner Loshit is a good practice to always precede with a semicolon 1358*8e3e3a7aSWarner Loshstatements that start with a parenthesis: 1359*8e3e3a7aSWarner Losh 1360*8e3e3a7aSWarner Losh<pre> 1361*8e3e3a7aSWarner Losh ;(print or io.write)('done') 1362*8e3e3a7aSWarner Losh</pre> 1363*8e3e3a7aSWarner Losh 1364*8e3e3a7aSWarner Losh<p> 1365*8e3e3a7aSWarner LoshA block can be explicitly delimited to produce a single statement: 1366*8e3e3a7aSWarner Losh 1367*8e3e3a7aSWarner Losh<pre> 1368*8e3e3a7aSWarner Losh stat ::= <b>do</b> block <b>end</b> 1369*8e3e3a7aSWarner Losh</pre><p> 1370*8e3e3a7aSWarner LoshExplicit blocks are useful 1371*8e3e3a7aSWarner Loshto control the scope of variable declarations. 1372*8e3e3a7aSWarner LoshExplicit blocks are also sometimes used to 1373*8e3e3a7aSWarner Loshadd a <b>return</b> statement in the middle 1374*8e3e3a7aSWarner Loshof another block (see <a href="#3.3.4">§3.3.4</a>). 1375*8e3e3a7aSWarner Losh 1376*8e3e3a7aSWarner Losh 1377*8e3e3a7aSWarner Losh 1378*8e3e3a7aSWarner Losh 1379*8e3e3a7aSWarner Losh 1380*8e3e3a7aSWarner Losh<h3>3.3.2 – <a name="3.3.2">Chunks</a></h3> 1381*8e3e3a7aSWarner Losh 1382*8e3e3a7aSWarner Losh<p> 1383*8e3e3a7aSWarner LoshThe unit of compilation of Lua is called a <em>chunk</em>. 1384*8e3e3a7aSWarner LoshSyntactically, 1385*8e3e3a7aSWarner Losha chunk is simply a block: 1386*8e3e3a7aSWarner Losh 1387*8e3e3a7aSWarner Losh<pre> 1388*8e3e3a7aSWarner Losh chunk ::= block 1389*8e3e3a7aSWarner Losh</pre> 1390*8e3e3a7aSWarner Losh 1391*8e3e3a7aSWarner Losh<p> 1392*8e3e3a7aSWarner LoshLua handles a chunk as the body of an anonymous function 1393*8e3e3a7aSWarner Loshwith a variable number of arguments 1394*8e3e3a7aSWarner Losh(see <a href="#3.4.11">§3.4.11</a>). 1395*8e3e3a7aSWarner LoshAs such, chunks can define local variables, 1396*8e3e3a7aSWarner Loshreceive arguments, and return values. 1397*8e3e3a7aSWarner LoshMoreover, such anonymous function is compiled as in the 1398*8e3e3a7aSWarner Loshscope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>). 1399*8e3e3a7aSWarner LoshThe resulting function always has <code>_ENV</code> as its only upvalue, 1400*8e3e3a7aSWarner Losheven if it does not use that variable. 1401*8e3e3a7aSWarner Losh 1402*8e3e3a7aSWarner Losh 1403*8e3e3a7aSWarner Losh<p> 1404*8e3e3a7aSWarner LoshA chunk can be stored in a file or in a string inside the host program. 1405*8e3e3a7aSWarner LoshTo execute a chunk, 1406*8e3e3a7aSWarner LoshLua first <em>loads</em> it, 1407*8e3e3a7aSWarner Loshprecompiling the chunk's code into instructions for a virtual machine, 1408*8e3e3a7aSWarner Loshand then Lua executes the compiled code 1409*8e3e3a7aSWarner Loshwith an interpreter for the virtual machine. 1410*8e3e3a7aSWarner Losh 1411*8e3e3a7aSWarner Losh 1412*8e3e3a7aSWarner Losh<p> 1413*8e3e3a7aSWarner LoshChunks can also be precompiled into binary form; 1414*8e3e3a7aSWarner Loshsee program <code>luac</code> and function <a href="#pdf-string.dump"><code>string.dump</code></a> for details. 1415*8e3e3a7aSWarner LoshPrograms in source and compiled forms are interchangeable; 1416*8e3e3a7aSWarner LoshLua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>). 1417*8e3e3a7aSWarner Losh 1418*8e3e3a7aSWarner Losh 1419*8e3e3a7aSWarner Losh 1420*8e3e3a7aSWarner Losh 1421*8e3e3a7aSWarner Losh 1422*8e3e3a7aSWarner Losh<h3>3.3.3 – <a name="3.3.3">Assignment</a></h3> 1423*8e3e3a7aSWarner Losh 1424*8e3e3a7aSWarner Losh<p> 1425*8e3e3a7aSWarner LoshLua allows multiple assignments. 1426*8e3e3a7aSWarner LoshTherefore, the syntax for assignment 1427*8e3e3a7aSWarner Loshdefines a list of variables on the left side 1428*8e3e3a7aSWarner Loshand a list of expressions on the right side. 1429*8e3e3a7aSWarner LoshThe elements in both lists are separated by commas: 1430*8e3e3a7aSWarner Losh 1431*8e3e3a7aSWarner Losh<pre> 1432*8e3e3a7aSWarner Losh stat ::= varlist ‘<b>=</b>’ explist 1433*8e3e3a7aSWarner Losh varlist ::= var {‘<b>,</b>’ var} 1434*8e3e3a7aSWarner Losh explist ::= exp {‘<b>,</b>’ exp} 1435*8e3e3a7aSWarner Losh</pre><p> 1436*8e3e3a7aSWarner LoshExpressions are discussed in <a href="#3.4">§3.4</a>. 1437*8e3e3a7aSWarner Losh 1438*8e3e3a7aSWarner Losh 1439*8e3e3a7aSWarner Losh<p> 1440*8e3e3a7aSWarner LoshBefore the assignment, 1441*8e3e3a7aSWarner Loshthe list of values is <em>adjusted</em> to the length of 1442*8e3e3a7aSWarner Loshthe list of variables. 1443*8e3e3a7aSWarner LoshIf there are more values than needed, 1444*8e3e3a7aSWarner Loshthe excess values are thrown away. 1445*8e3e3a7aSWarner LoshIf there are fewer values than needed, 1446*8e3e3a7aSWarner Loshthe list is extended with as many <b>nil</b>'s as needed. 1447*8e3e3a7aSWarner LoshIf the list of expressions ends with a function call, 1448*8e3e3a7aSWarner Loshthen all values returned by that call enter the list of values, 1449*8e3e3a7aSWarner Loshbefore the adjustment 1450*8e3e3a7aSWarner Losh(except when the call is enclosed in parentheses; see <a href="#3.4">§3.4</a>). 1451*8e3e3a7aSWarner Losh 1452*8e3e3a7aSWarner Losh 1453*8e3e3a7aSWarner Losh<p> 1454*8e3e3a7aSWarner LoshThe assignment statement first evaluates all its expressions 1455*8e3e3a7aSWarner Loshand only then the assignments are performed. 1456*8e3e3a7aSWarner LoshThus the code 1457*8e3e3a7aSWarner Losh 1458*8e3e3a7aSWarner Losh<pre> 1459*8e3e3a7aSWarner Losh i = 3 1460*8e3e3a7aSWarner Losh i, a[i] = i+1, 20 1461*8e3e3a7aSWarner Losh</pre><p> 1462*8e3e3a7aSWarner Loshsets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 1463*8e3e3a7aSWarner Loshbecause the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 1464*8e3e3a7aSWarner Loshbefore it is assigned 4. 1465*8e3e3a7aSWarner LoshSimilarly, the line 1466*8e3e3a7aSWarner Losh 1467*8e3e3a7aSWarner Losh<pre> 1468*8e3e3a7aSWarner Losh x, y = y, x 1469*8e3e3a7aSWarner Losh</pre><p> 1470*8e3e3a7aSWarner Loshexchanges the values of <code>x</code> and <code>y</code>, 1471*8e3e3a7aSWarner Loshand 1472*8e3e3a7aSWarner Losh 1473*8e3e3a7aSWarner Losh<pre> 1474*8e3e3a7aSWarner Losh x, y, z = y, z, x 1475*8e3e3a7aSWarner Losh</pre><p> 1476*8e3e3a7aSWarner Loshcyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 1477*8e3e3a7aSWarner Losh 1478*8e3e3a7aSWarner Losh 1479*8e3e3a7aSWarner Losh<p> 1480*8e3e3a7aSWarner LoshThe meaning of assignments to global variables 1481*8e3e3a7aSWarner Loshand table fields can be changed via metatables. 1482*8e3e3a7aSWarner LoshAn assignment to an indexed variable <code>t[i] = val</code> is equivalent to 1483*8e3e3a7aSWarner Losh<code>settable_event(t,i,val)</code>. 1484*8e3e3a7aSWarner Losh(See <a href="#2.4">§2.4</a> for a complete description of the 1485*8e3e3a7aSWarner Losh<code>settable_event</code> function. 1486*8e3e3a7aSWarner LoshThis function is not defined or callable in Lua. 1487*8e3e3a7aSWarner LoshWe use it here only for explanatory purposes.) 1488*8e3e3a7aSWarner Losh 1489*8e3e3a7aSWarner Losh 1490*8e3e3a7aSWarner Losh<p> 1491*8e3e3a7aSWarner LoshAn assignment to a global name <code>x = val</code> 1492*8e3e3a7aSWarner Loshis equivalent to the assignment 1493*8e3e3a7aSWarner Losh<code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>). 1494*8e3e3a7aSWarner Losh 1495*8e3e3a7aSWarner Losh 1496*8e3e3a7aSWarner Losh 1497*8e3e3a7aSWarner Losh 1498*8e3e3a7aSWarner Losh 1499*8e3e3a7aSWarner Losh<h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p> 1500*8e3e3a7aSWarner LoshThe control structures 1501*8e3e3a7aSWarner Losh<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 1502*8e3e3a7aSWarner Loshfamiliar syntax: 1503*8e3e3a7aSWarner Losh 1504*8e3e3a7aSWarner Losh 1505*8e3e3a7aSWarner Losh 1506*8e3e3a7aSWarner Losh 1507*8e3e3a7aSWarner Losh<pre> 1508*8e3e3a7aSWarner Losh stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 1509*8e3e3a7aSWarner Losh stat ::= <b>repeat</b> block <b>until</b> exp 1510*8e3e3a7aSWarner 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> 1511*8e3e3a7aSWarner Losh</pre><p> 1512*8e3e3a7aSWarner LoshLua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>). 1513*8e3e3a7aSWarner Losh 1514*8e3e3a7aSWarner Losh 1515*8e3e3a7aSWarner Losh<p> 1516*8e3e3a7aSWarner LoshThe condition expression of a 1517*8e3e3a7aSWarner Loshcontrol structure can return any value. 1518*8e3e3a7aSWarner LoshBoth <b>false</b> and <b>nil</b> are considered false. 1519*8e3e3a7aSWarner LoshAll values different from <b>nil</b> and <b>false</b> are considered true 1520*8e3e3a7aSWarner Losh(in particular, the number 0 and the empty string are also true). 1521*8e3e3a7aSWarner Losh 1522*8e3e3a7aSWarner Losh 1523*8e3e3a7aSWarner Losh<p> 1524*8e3e3a7aSWarner LoshIn the <b>repeat</b>–<b>until</b> loop, 1525*8e3e3a7aSWarner Loshthe inner block does not end at the <b>until</b> keyword, 1526*8e3e3a7aSWarner Loshbut only after the condition. 1527*8e3e3a7aSWarner LoshSo, the condition can refer to local variables 1528*8e3e3a7aSWarner Loshdeclared inside the loop block. 1529*8e3e3a7aSWarner Losh 1530*8e3e3a7aSWarner Losh 1531*8e3e3a7aSWarner Losh<p> 1532*8e3e3a7aSWarner LoshThe <b>goto</b> statement transfers the program control to a label. 1533*8e3e3a7aSWarner LoshFor syntactical reasons, 1534*8e3e3a7aSWarner Loshlabels in Lua are considered statements too: 1535*8e3e3a7aSWarner Losh 1536*8e3e3a7aSWarner Losh 1537*8e3e3a7aSWarner Losh 1538*8e3e3a7aSWarner Losh<pre> 1539*8e3e3a7aSWarner Losh stat ::= <b>goto</b> Name 1540*8e3e3a7aSWarner Losh stat ::= label 1541*8e3e3a7aSWarner Losh label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 1542*8e3e3a7aSWarner Losh</pre> 1543*8e3e3a7aSWarner Losh 1544*8e3e3a7aSWarner Losh<p> 1545*8e3e3a7aSWarner LoshA label is visible in the entire block where it is defined, 1546*8e3e3a7aSWarner Loshexcept 1547*8e3e3a7aSWarner Loshinside nested blocks where a label with the same name is defined and 1548*8e3e3a7aSWarner Loshinside nested functions. 1549*8e3e3a7aSWarner LoshA goto may jump to any visible label as long as it does not 1550*8e3e3a7aSWarner Loshenter into the scope of a local variable. 1551*8e3e3a7aSWarner Losh 1552*8e3e3a7aSWarner Losh 1553*8e3e3a7aSWarner Losh<p> 1554*8e3e3a7aSWarner LoshLabels and empty statements are called <em>void statements</em>, 1555*8e3e3a7aSWarner Loshas they perform no actions. 1556*8e3e3a7aSWarner Losh 1557*8e3e3a7aSWarner Losh 1558*8e3e3a7aSWarner Losh<p> 1559*8e3e3a7aSWarner LoshThe <b>break</b> statement terminates the execution of a 1560*8e3e3a7aSWarner Losh<b>while</b>, <b>repeat</b>, or <b>for</b> loop, 1561*8e3e3a7aSWarner Loshskipping to the next statement after the loop: 1562*8e3e3a7aSWarner Losh 1563*8e3e3a7aSWarner Losh 1564*8e3e3a7aSWarner Losh<pre> 1565*8e3e3a7aSWarner Losh stat ::= <b>break</b> 1566*8e3e3a7aSWarner Losh</pre><p> 1567*8e3e3a7aSWarner LoshA <b>break</b> ends the innermost enclosing loop. 1568*8e3e3a7aSWarner Losh 1569*8e3e3a7aSWarner Losh 1570*8e3e3a7aSWarner Losh<p> 1571*8e3e3a7aSWarner LoshThe <b>return</b> statement is used to return values 1572*8e3e3a7aSWarner Loshfrom a function or a chunk 1573*8e3e3a7aSWarner Losh(which is an anonymous function). 1574*8e3e3a7aSWarner Losh 1575*8e3e3a7aSWarner LoshFunctions can return more than one value, 1576*8e3e3a7aSWarner Loshso the syntax for the <b>return</b> statement is 1577*8e3e3a7aSWarner Losh 1578*8e3e3a7aSWarner Losh<pre> 1579*8e3e3a7aSWarner Losh stat ::= <b>return</b> [explist] [‘<b>;</b>’] 1580*8e3e3a7aSWarner Losh</pre> 1581*8e3e3a7aSWarner Losh 1582*8e3e3a7aSWarner Losh<p> 1583*8e3e3a7aSWarner LoshThe <b>return</b> statement can only be written 1584*8e3e3a7aSWarner Loshas the last statement of a block. 1585*8e3e3a7aSWarner LoshIf it is really necessary to <b>return</b> in the middle of a block, 1586*8e3e3a7aSWarner Loshthen an explicit inner block can be used, 1587*8e3e3a7aSWarner Loshas in the idiom <code>do return end</code>, 1588*8e3e3a7aSWarner Loshbecause now <b>return</b> is the last statement in its (inner) block. 1589*8e3e3a7aSWarner Losh 1590*8e3e3a7aSWarner Losh 1591*8e3e3a7aSWarner Losh 1592*8e3e3a7aSWarner Losh 1593*8e3e3a7aSWarner Losh 1594*8e3e3a7aSWarner Losh<h3>3.3.5 – <a name="3.3.5">For Statement</a></h3> 1595*8e3e3a7aSWarner Losh 1596*8e3e3a7aSWarner Losh<p> 1597*8e3e3a7aSWarner Losh 1598*8e3e3a7aSWarner LoshThe <b>for</b> statement has two forms: 1599*8e3e3a7aSWarner Loshone numerical and one generic. 1600*8e3e3a7aSWarner Losh 1601*8e3e3a7aSWarner Losh 1602*8e3e3a7aSWarner Losh<p> 1603*8e3e3a7aSWarner LoshThe numerical <b>for</b> loop repeats a block of code while a 1604*8e3e3a7aSWarner Loshcontrol variable runs through an arithmetic progression. 1605*8e3e3a7aSWarner LoshIt has the following syntax: 1606*8e3e3a7aSWarner Losh 1607*8e3e3a7aSWarner Losh<pre> 1608*8e3e3a7aSWarner Losh stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> 1609*8e3e3a7aSWarner Losh</pre><p> 1610*8e3e3a7aSWarner LoshThe <em>block</em> is repeated for <em>name</em> starting at the value of 1611*8e3e3a7aSWarner Loshthe first <em>exp</em>, until it passes the second <em>exp</em> by steps of the 1612*8e3e3a7aSWarner Loshthird <em>exp</em>. 1613*8e3e3a7aSWarner LoshMore precisely, a <b>for</b> statement like 1614*8e3e3a7aSWarner Losh 1615*8e3e3a7aSWarner Losh<pre> 1616*8e3e3a7aSWarner Losh for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end 1617*8e3e3a7aSWarner Losh</pre><p> 1618*8e3e3a7aSWarner Loshis equivalent to the code: 1619*8e3e3a7aSWarner Losh 1620*8e3e3a7aSWarner Losh<pre> 1621*8e3e3a7aSWarner Losh do 1622*8e3e3a7aSWarner Losh local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>) 1623*8e3e3a7aSWarner Losh if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end 1624*8e3e3a7aSWarner Losh <em>var</em> = <em>var</em> - <em>step</em> 1625*8e3e3a7aSWarner Losh while true do 1626*8e3e3a7aSWarner Losh <em>var</em> = <em>var</em> + <em>step</em> 1627*8e3e3a7aSWarner 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 1628*8e3e3a7aSWarner Losh break 1629*8e3e3a7aSWarner Losh end 1630*8e3e3a7aSWarner Losh local v = <em>var</em> 1631*8e3e3a7aSWarner Losh <em>block</em> 1632*8e3e3a7aSWarner Losh end 1633*8e3e3a7aSWarner Losh end 1634*8e3e3a7aSWarner Losh</pre> 1635*8e3e3a7aSWarner Losh 1636*8e3e3a7aSWarner Losh<p> 1637*8e3e3a7aSWarner LoshNote the following: 1638*8e3e3a7aSWarner Losh 1639*8e3e3a7aSWarner Losh<ul> 1640*8e3e3a7aSWarner Losh 1641*8e3e3a7aSWarner Losh<li> 1642*8e3e3a7aSWarner LoshAll three control expressions are evaluated only once, 1643*8e3e3a7aSWarner Loshbefore the loop starts. 1644*8e3e3a7aSWarner LoshThey must all result in numbers. 1645*8e3e3a7aSWarner Losh</li> 1646*8e3e3a7aSWarner Losh 1647*8e3e3a7aSWarner Losh<li> 1648*8e3e3a7aSWarner Losh<code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables. 1649*8e3e3a7aSWarner LoshThe names shown here are for explanatory purposes only. 1650*8e3e3a7aSWarner Losh</li> 1651*8e3e3a7aSWarner Losh 1652*8e3e3a7aSWarner Losh<li> 1653*8e3e3a7aSWarner LoshIf the third expression (the step) is absent, 1654*8e3e3a7aSWarner Loshthen a step of 1 is used. 1655*8e3e3a7aSWarner Losh</li> 1656*8e3e3a7aSWarner Losh 1657*8e3e3a7aSWarner Losh<li> 1658*8e3e3a7aSWarner LoshYou can use <b>break</b> and <b>goto</b> to exit a <b>for</b> loop. 1659*8e3e3a7aSWarner Losh</li> 1660*8e3e3a7aSWarner Losh 1661*8e3e3a7aSWarner Losh<li> 1662*8e3e3a7aSWarner LoshThe loop variable <code>v</code> is local to the loop body. 1663*8e3e3a7aSWarner LoshIf you need its value after the loop, 1664*8e3e3a7aSWarner Loshassign it to another variable before exiting the loop. 1665*8e3e3a7aSWarner Losh</li> 1666*8e3e3a7aSWarner Losh 1667*8e3e3a7aSWarner Losh</ul> 1668*8e3e3a7aSWarner Losh 1669*8e3e3a7aSWarner Losh<p> 1670*8e3e3a7aSWarner LoshThe generic <b>for</b> statement works over functions, 1671*8e3e3a7aSWarner Loshcalled <em>iterators</em>. 1672*8e3e3a7aSWarner LoshOn each iteration, the iterator function is called to produce a new value, 1673*8e3e3a7aSWarner Loshstopping when this new value is <b>nil</b>. 1674*8e3e3a7aSWarner LoshThe generic <b>for</b> loop has the following syntax: 1675*8e3e3a7aSWarner Losh 1676*8e3e3a7aSWarner Losh<pre> 1677*8e3e3a7aSWarner Losh stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> 1678*8e3e3a7aSWarner Losh namelist ::= Name {‘<b>,</b>’ Name} 1679*8e3e3a7aSWarner Losh</pre><p> 1680*8e3e3a7aSWarner LoshA <b>for</b> statement like 1681*8e3e3a7aSWarner Losh 1682*8e3e3a7aSWarner Losh<pre> 1683*8e3e3a7aSWarner Losh for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end 1684*8e3e3a7aSWarner Losh</pre><p> 1685*8e3e3a7aSWarner Loshis equivalent to the code: 1686*8e3e3a7aSWarner Losh 1687*8e3e3a7aSWarner Losh<pre> 1688*8e3e3a7aSWarner Losh do 1689*8e3e3a7aSWarner Losh local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em> 1690*8e3e3a7aSWarner Losh while true do 1691*8e3e3a7aSWarner Losh local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>) 1692*8e3e3a7aSWarner Losh if <em>var_1</em> == nil then break end 1693*8e3e3a7aSWarner Losh <em>var</em> = <em>var_1</em> 1694*8e3e3a7aSWarner Losh <em>block</em> 1695*8e3e3a7aSWarner Losh end 1696*8e3e3a7aSWarner Losh end 1697*8e3e3a7aSWarner Losh</pre><p> 1698*8e3e3a7aSWarner LoshNote the following: 1699*8e3e3a7aSWarner Losh 1700*8e3e3a7aSWarner Losh<ul> 1701*8e3e3a7aSWarner Losh 1702*8e3e3a7aSWarner Losh<li> 1703*8e3e3a7aSWarner Losh<code><em>explist</em></code> is evaluated only once. 1704*8e3e3a7aSWarner LoshIts results are an <em>iterator</em> function, 1705*8e3e3a7aSWarner Losha <em>state</em>, 1706*8e3e3a7aSWarner Loshand an initial value for the first <em>iterator variable</em>. 1707*8e3e3a7aSWarner Losh</li> 1708*8e3e3a7aSWarner Losh 1709*8e3e3a7aSWarner Losh<li> 1710*8e3e3a7aSWarner Losh<code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables. 1711*8e3e3a7aSWarner LoshThe names are here for explanatory purposes only. 1712*8e3e3a7aSWarner Losh</li> 1713*8e3e3a7aSWarner Losh 1714*8e3e3a7aSWarner Losh<li> 1715*8e3e3a7aSWarner LoshYou can use <b>break</b> to exit a <b>for</b> loop. 1716*8e3e3a7aSWarner Losh</li> 1717*8e3e3a7aSWarner Losh 1718*8e3e3a7aSWarner Losh<li> 1719*8e3e3a7aSWarner LoshThe loop variables <code><em>var_i</em></code> are local to the loop; 1720*8e3e3a7aSWarner Loshyou cannot use their values after the <b>for</b> ends. 1721*8e3e3a7aSWarner LoshIf you need these values, 1722*8e3e3a7aSWarner Loshthen assign them to other variables before breaking or exiting the loop. 1723*8e3e3a7aSWarner Losh</li> 1724*8e3e3a7aSWarner Losh 1725*8e3e3a7aSWarner Losh</ul> 1726*8e3e3a7aSWarner Losh 1727*8e3e3a7aSWarner Losh 1728*8e3e3a7aSWarner Losh 1729*8e3e3a7aSWarner Losh 1730*8e3e3a7aSWarner Losh<h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p> 1731*8e3e3a7aSWarner LoshTo allow possible side-effects, 1732*8e3e3a7aSWarner Loshfunction calls can be executed as statements: 1733*8e3e3a7aSWarner Losh 1734*8e3e3a7aSWarner Losh<pre> 1735*8e3e3a7aSWarner Losh stat ::= functioncall 1736*8e3e3a7aSWarner Losh</pre><p> 1737*8e3e3a7aSWarner LoshIn this case, all returned values are thrown away. 1738*8e3e3a7aSWarner LoshFunction calls are explained in <a href="#3.4.10">§3.4.10</a>. 1739*8e3e3a7aSWarner Losh 1740*8e3e3a7aSWarner Losh 1741*8e3e3a7aSWarner Losh 1742*8e3e3a7aSWarner Losh 1743*8e3e3a7aSWarner Losh 1744*8e3e3a7aSWarner Losh<h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p> 1745*8e3e3a7aSWarner LoshLocal variables can be declared anywhere inside a block. 1746*8e3e3a7aSWarner LoshThe declaration can include an initial assignment: 1747*8e3e3a7aSWarner Losh 1748*8e3e3a7aSWarner Losh<pre> 1749*8e3e3a7aSWarner Losh stat ::= <b>local</b> namelist [‘<b>=</b>’ explist] 1750*8e3e3a7aSWarner Losh</pre><p> 1751*8e3e3a7aSWarner LoshIf present, an initial assignment has the same semantics 1752*8e3e3a7aSWarner Loshof a multiple assignment (see <a href="#3.3.3">§3.3.3</a>). 1753*8e3e3a7aSWarner LoshOtherwise, all variables are initialized with <b>nil</b>. 1754*8e3e3a7aSWarner Losh 1755*8e3e3a7aSWarner Losh 1756*8e3e3a7aSWarner Losh<p> 1757*8e3e3a7aSWarner LoshA chunk is also a block (see <a href="#3.3.2">§3.3.2</a>), 1758*8e3e3a7aSWarner Loshand so local variables can be declared in a chunk outside any explicit block. 1759*8e3e3a7aSWarner Losh 1760*8e3e3a7aSWarner Losh 1761*8e3e3a7aSWarner Losh<p> 1762*8e3e3a7aSWarner LoshThe visibility rules for local variables are explained in <a href="#3.5">§3.5</a>. 1763*8e3e3a7aSWarner Losh 1764*8e3e3a7aSWarner Losh 1765*8e3e3a7aSWarner Losh 1766*8e3e3a7aSWarner Losh 1767*8e3e3a7aSWarner Losh 1768*8e3e3a7aSWarner Losh 1769*8e3e3a7aSWarner Losh 1770*8e3e3a7aSWarner Losh<h2>3.4 – <a name="3.4">Expressions</a></h2> 1771*8e3e3a7aSWarner Losh 1772*8e3e3a7aSWarner Losh<p> 1773*8e3e3a7aSWarner LoshThe basic expressions in Lua are the following: 1774*8e3e3a7aSWarner Losh 1775*8e3e3a7aSWarner Losh<pre> 1776*8e3e3a7aSWarner Losh exp ::= prefixexp 1777*8e3e3a7aSWarner Losh exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 1778*8e3e3a7aSWarner Losh exp ::= Numeral 1779*8e3e3a7aSWarner Losh exp ::= LiteralString 1780*8e3e3a7aSWarner Losh exp ::= functiondef 1781*8e3e3a7aSWarner Losh exp ::= tableconstructor 1782*8e3e3a7aSWarner Losh exp ::= ‘<b>...</b>’ 1783*8e3e3a7aSWarner Losh exp ::= exp binop exp 1784*8e3e3a7aSWarner Losh exp ::= unop exp 1785*8e3e3a7aSWarner Losh prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 1786*8e3e3a7aSWarner Losh</pre> 1787*8e3e3a7aSWarner Losh 1788*8e3e3a7aSWarner Losh<p> 1789*8e3e3a7aSWarner LoshNumerals and literal strings are explained in <a href="#3.1">§3.1</a>; 1790*8e3e3a7aSWarner Loshvariables are explained in <a href="#3.2">§3.2</a>; 1791*8e3e3a7aSWarner Loshfunction definitions are explained in <a href="#3.4.11">§3.4.11</a>; 1792*8e3e3a7aSWarner Loshfunction calls are explained in <a href="#3.4.10">§3.4.10</a>; 1793*8e3e3a7aSWarner Loshtable constructors are explained in <a href="#3.4.9">§3.4.9</a>. 1794*8e3e3a7aSWarner LoshVararg expressions, 1795*8e3e3a7aSWarner Loshdenoted by three dots ('<code>...</code>'), can only be used when 1796*8e3e3a7aSWarner Loshdirectly inside a vararg function; 1797*8e3e3a7aSWarner Loshthey are explained in <a href="#3.4.11">§3.4.11</a>. 1798*8e3e3a7aSWarner Losh 1799*8e3e3a7aSWarner Losh 1800*8e3e3a7aSWarner Losh<p> 1801*8e3e3a7aSWarner LoshBinary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), 1802*8e3e3a7aSWarner Loshbitwise operators (see <a href="#3.4.2">§3.4.2</a>), 1803*8e3e3a7aSWarner Loshrelational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>), 1804*8e3e3a7aSWarner Loshand the concatenation operator (see <a href="#3.4.6">§3.4.6</a>). 1805*8e3e3a7aSWarner LoshUnary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), 1806*8e3e3a7aSWarner Loshthe unary bitwise NOT (see <a href="#3.4.2">§3.4.2</a>), 1807*8e3e3a7aSWarner Loshthe unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), 1808*8e3e3a7aSWarner Loshand the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). 1809*8e3e3a7aSWarner Losh 1810*8e3e3a7aSWarner Losh 1811*8e3e3a7aSWarner Losh<p> 1812*8e3e3a7aSWarner LoshBoth function calls and vararg expressions can result in multiple values. 1813*8e3e3a7aSWarner LoshIf a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>), 1814*8e3e3a7aSWarner Loshthen its return list is adjusted to zero elements, 1815*8e3e3a7aSWarner Loshthus discarding all returned values. 1816*8e3e3a7aSWarner LoshIf an expression is used as the last (or the only) element 1817*8e3e3a7aSWarner Loshof a list of expressions, 1818*8e3e3a7aSWarner Loshthen no adjustment is made 1819*8e3e3a7aSWarner Losh(unless the expression is enclosed in parentheses). 1820*8e3e3a7aSWarner LoshIn all other contexts, 1821*8e3e3a7aSWarner LoshLua adjusts the result list to one element, 1822*8e3e3a7aSWarner Losheither discarding all values except the first one 1823*8e3e3a7aSWarner Loshor adding a single <b>nil</b> if there are no values. 1824*8e3e3a7aSWarner Losh 1825*8e3e3a7aSWarner Losh 1826*8e3e3a7aSWarner Losh<p> 1827*8e3e3a7aSWarner LoshHere are some examples: 1828*8e3e3a7aSWarner Losh 1829*8e3e3a7aSWarner Losh<pre> 1830*8e3e3a7aSWarner Losh f() -- adjusted to 0 results 1831*8e3e3a7aSWarner Losh g(f(), x) -- f() is adjusted to 1 result 1832*8e3e3a7aSWarner Losh g(x, f()) -- g gets x plus all results from f() 1833*8e3e3a7aSWarner Losh a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) 1834*8e3e3a7aSWarner Losh a,b = ... -- a gets the first vararg parameter, b gets 1835*8e3e3a7aSWarner Losh -- the second (both a and b can get nil if there 1836*8e3e3a7aSWarner Losh -- is no corresponding vararg parameter) 1837*8e3e3a7aSWarner Losh 1838*8e3e3a7aSWarner Losh a,b,c = x, f() -- f() is adjusted to 2 results 1839*8e3e3a7aSWarner Losh a,b,c = f() -- f() is adjusted to 3 results 1840*8e3e3a7aSWarner Losh return f() -- returns all results from f() 1841*8e3e3a7aSWarner Losh return ... -- returns all received vararg parameters 1842*8e3e3a7aSWarner Losh return x,y,f() -- returns x, y, and all results from f() 1843*8e3e3a7aSWarner Losh {f()} -- creates a list with all results from f() 1844*8e3e3a7aSWarner Losh {...} -- creates a list with all vararg parameters 1845*8e3e3a7aSWarner Losh {f(), nil} -- f() is adjusted to 1 result 1846*8e3e3a7aSWarner Losh</pre> 1847*8e3e3a7aSWarner Losh 1848*8e3e3a7aSWarner Losh<p> 1849*8e3e3a7aSWarner LoshAny expression enclosed in parentheses always results in only one value. 1850*8e3e3a7aSWarner LoshThus, 1851*8e3e3a7aSWarner Losh<code>(f(x,y,z))</code> is always a single value, 1852*8e3e3a7aSWarner Losheven if <code>f</code> returns several values. 1853*8e3e3a7aSWarner Losh(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> 1854*8e3e3a7aSWarner Loshor <b>nil</b> if <code>f</code> does not return any values.) 1855*8e3e3a7aSWarner Losh 1856*8e3e3a7aSWarner Losh 1857*8e3e3a7aSWarner Losh 1858*8e3e3a7aSWarner Losh<h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p> 1859*8e3e3a7aSWarner LoshLua supports the following arithmetic operators: 1860*8e3e3a7aSWarner Losh 1861*8e3e3a7aSWarner Losh<ul> 1862*8e3e3a7aSWarner Losh<li><b><code>+</code>: </b>addition</li> 1863*8e3e3a7aSWarner Losh<li><b><code>-</code>: </b>subtraction</li> 1864*8e3e3a7aSWarner Losh<li><b><code>*</code>: </b>multiplication</li> 1865*8e3e3a7aSWarner Losh<li><b><code>/</code>: </b>float division</li> 1866*8e3e3a7aSWarner Losh<li><b><code>//</code>: </b>floor division</li> 1867*8e3e3a7aSWarner Losh<li><b><code>%</code>: </b>modulo</li> 1868*8e3e3a7aSWarner Losh<li><b><code>^</code>: </b>exponentiation</li> 1869*8e3e3a7aSWarner Losh<li><b><code>-</code>: </b>unary minus</li> 1870*8e3e3a7aSWarner Losh</ul> 1871*8e3e3a7aSWarner Losh 1872*8e3e3a7aSWarner Losh<p> 1873*8e3e3a7aSWarner LoshWith the exception of exponentiation and float division, 1874*8e3e3a7aSWarner Loshthe arithmetic operators work as follows: 1875*8e3e3a7aSWarner LoshIf both operands are integers, 1876*8e3e3a7aSWarner Loshthe operation is performed over integers and the result is an integer. 1877*8e3e3a7aSWarner LoshOtherwise, if both operands are numbers 1878*8e3e3a7aSWarner Loshor strings that can be converted to 1879*8e3e3a7aSWarner Loshnumbers (see <a href="#3.4.3">§3.4.3</a>), 1880*8e3e3a7aSWarner Loshthen they are converted to floats, 1881*8e3e3a7aSWarner Loshthe operation is performed following the usual rules 1882*8e3e3a7aSWarner Loshfor floating-point arithmetic 1883*8e3e3a7aSWarner Losh(usually the IEEE 754 standard), 1884*8e3e3a7aSWarner Loshand the result is a float. 1885*8e3e3a7aSWarner Losh 1886*8e3e3a7aSWarner Losh 1887*8e3e3a7aSWarner Losh<p> 1888*8e3e3a7aSWarner LoshExponentiation and float division (<code>/</code>) 1889*8e3e3a7aSWarner Loshalways convert their operands to floats 1890*8e3e3a7aSWarner Loshand the result is always a float. 1891*8e3e3a7aSWarner LoshExponentiation uses the ISO C function <code>pow</code>, 1892*8e3e3a7aSWarner Loshso that it works for non-integer exponents too. 1893*8e3e3a7aSWarner Losh 1894*8e3e3a7aSWarner Losh 1895*8e3e3a7aSWarner Losh<p> 1896*8e3e3a7aSWarner LoshFloor division (<code>//</code>) is a division 1897*8e3e3a7aSWarner Loshthat rounds the quotient towards minus infinity, 1898*8e3e3a7aSWarner Loshthat is, the floor of the division of its operands. 1899*8e3e3a7aSWarner Losh 1900*8e3e3a7aSWarner Losh 1901*8e3e3a7aSWarner Losh<p> 1902*8e3e3a7aSWarner LoshModulo is defined as the remainder of a division 1903*8e3e3a7aSWarner Loshthat rounds the quotient towards minus infinity (floor division). 1904*8e3e3a7aSWarner Losh 1905*8e3e3a7aSWarner Losh 1906*8e3e3a7aSWarner Losh<p> 1907*8e3e3a7aSWarner LoshIn case of overflows in integer arithmetic, 1908*8e3e3a7aSWarner Loshall operations <em>wrap around</em>, 1909*8e3e3a7aSWarner Loshaccording to the usual rules of two-complement arithmetic. 1910*8e3e3a7aSWarner Losh(In other words, 1911*8e3e3a7aSWarner Loshthey return the unique representable integer 1912*8e3e3a7aSWarner Loshthat is equal modulo <em>2<sup>64</sup></em> to the mathematical result.) 1913*8e3e3a7aSWarner Losh 1914*8e3e3a7aSWarner Losh 1915*8e3e3a7aSWarner Losh 1916*8e3e3a7aSWarner Losh<h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p> 1917*8e3e3a7aSWarner LoshLua supports the following bitwise operators: 1918*8e3e3a7aSWarner Losh 1919*8e3e3a7aSWarner Losh<ul> 1920*8e3e3a7aSWarner Losh<li><b><code>&</code>: </b>bitwise AND</li> 1921*8e3e3a7aSWarner Losh<li><b><code>|</code>: </b>bitwise OR</li> 1922*8e3e3a7aSWarner Losh<li><b><code>~</code>: </b>bitwise exclusive OR</li> 1923*8e3e3a7aSWarner Losh<li><b><code>>></code>: </b>right shift</li> 1924*8e3e3a7aSWarner Losh<li><b><code><<</code>: </b>left shift</li> 1925*8e3e3a7aSWarner Losh<li><b><code>~</code>: </b>unary bitwise NOT</li> 1926*8e3e3a7aSWarner Losh</ul> 1927*8e3e3a7aSWarner Losh 1928*8e3e3a7aSWarner Losh<p> 1929*8e3e3a7aSWarner LoshAll bitwise operations convert its operands to integers 1930*8e3e3a7aSWarner Losh(see <a href="#3.4.3">§3.4.3</a>), 1931*8e3e3a7aSWarner Loshoperate on all bits of those integers, 1932*8e3e3a7aSWarner Loshand result in an integer. 1933*8e3e3a7aSWarner Losh 1934*8e3e3a7aSWarner Losh 1935*8e3e3a7aSWarner Losh<p> 1936*8e3e3a7aSWarner LoshBoth right and left shifts fill the vacant bits with zeros. 1937*8e3e3a7aSWarner LoshNegative displacements shift to the other direction; 1938*8e3e3a7aSWarner Loshdisplacements with absolute values equal to or higher than 1939*8e3e3a7aSWarner Loshthe number of bits in an integer 1940*8e3e3a7aSWarner Loshresult in zero (as all bits are shifted out). 1941*8e3e3a7aSWarner Losh 1942*8e3e3a7aSWarner Losh 1943*8e3e3a7aSWarner Losh 1944*8e3e3a7aSWarner Losh 1945*8e3e3a7aSWarner Losh 1946*8e3e3a7aSWarner Losh<h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p> 1947*8e3e3a7aSWarner LoshLua provides some automatic conversions between some 1948*8e3e3a7aSWarner Loshtypes and representations at run time. 1949*8e3e3a7aSWarner LoshBitwise operators always convert float operands to integers. 1950*8e3e3a7aSWarner LoshExponentiation and float division 1951*8e3e3a7aSWarner Loshalways convert integer operands to floats. 1952*8e3e3a7aSWarner LoshAll other arithmetic operations applied to mixed numbers 1953*8e3e3a7aSWarner Losh(integers and floats) convert the integer operand to a float; 1954*8e3e3a7aSWarner Loshthis is called the <em>usual rule</em>. 1955*8e3e3a7aSWarner LoshThe C API also converts both integers to floats and 1956*8e3e3a7aSWarner Loshfloats to integers, as needed. 1957*8e3e3a7aSWarner LoshMoreover, string concatenation accepts numbers as arguments, 1958*8e3e3a7aSWarner Loshbesides strings. 1959*8e3e3a7aSWarner Losh 1960*8e3e3a7aSWarner Losh 1961*8e3e3a7aSWarner Losh<p> 1962*8e3e3a7aSWarner LoshLua also converts strings to numbers, 1963*8e3e3a7aSWarner Loshwhenever a number is expected. 1964*8e3e3a7aSWarner Losh 1965*8e3e3a7aSWarner Losh 1966*8e3e3a7aSWarner Losh<p> 1967*8e3e3a7aSWarner LoshIn a conversion from integer to float, 1968*8e3e3a7aSWarner Loshif the integer value has an exact representation as a float, 1969*8e3e3a7aSWarner Loshthat is the result. 1970*8e3e3a7aSWarner LoshOtherwise, 1971*8e3e3a7aSWarner Loshthe conversion gets the nearest higher or 1972*8e3e3a7aSWarner Loshthe nearest lower representable value. 1973*8e3e3a7aSWarner LoshThis kind of conversion never fails. 1974*8e3e3a7aSWarner Losh 1975*8e3e3a7aSWarner Losh 1976*8e3e3a7aSWarner Losh<p> 1977*8e3e3a7aSWarner LoshThe conversion from float to integer 1978*8e3e3a7aSWarner Loshchecks whether the float has an exact representation as an integer 1979*8e3e3a7aSWarner Losh(that is, the float has an integral value and 1980*8e3e3a7aSWarner Loshit is in the range of integer representation). 1981*8e3e3a7aSWarner LoshIf it does, that representation is the result. 1982*8e3e3a7aSWarner LoshOtherwise, the conversion fails. 1983*8e3e3a7aSWarner Losh 1984*8e3e3a7aSWarner Losh 1985*8e3e3a7aSWarner Losh<p> 1986*8e3e3a7aSWarner LoshThe conversion from strings to numbers goes as follows: 1987*8e3e3a7aSWarner LoshFirst, the string is converted to an integer or a float, 1988*8e3e3a7aSWarner Loshfollowing its syntax and the rules of the Lua lexer. 1989*8e3e3a7aSWarner Losh(The string may have also leading and trailing spaces and a sign.) 1990*8e3e3a7aSWarner LoshThen, the resulting number (float or integer) 1991*8e3e3a7aSWarner Loshis converted to the type (float or integer) required by the context 1992*8e3e3a7aSWarner Losh(e.g., the operation that forced the conversion). 1993*8e3e3a7aSWarner Losh 1994*8e3e3a7aSWarner Losh 1995*8e3e3a7aSWarner Losh<p> 1996*8e3e3a7aSWarner LoshAll conversions from strings to numbers 1997*8e3e3a7aSWarner Loshaccept both a dot and the current locale mark 1998*8e3e3a7aSWarner Loshas the radix character. 1999*8e3e3a7aSWarner Losh(The Lua lexer, however, accepts only a dot.) 2000*8e3e3a7aSWarner Losh 2001*8e3e3a7aSWarner Losh 2002*8e3e3a7aSWarner Losh<p> 2003*8e3e3a7aSWarner LoshThe conversion from numbers to strings uses a 2004*8e3e3a7aSWarner Loshnon-specified human-readable format. 2005*8e3e3a7aSWarner LoshFor complete control over how numbers are converted to strings, 2006*8e3e3a7aSWarner Loshuse the <code>format</code> function from the string library 2007*8e3e3a7aSWarner Losh(see <a href="#pdf-string.format"><code>string.format</code></a>). 2008*8e3e3a7aSWarner Losh 2009*8e3e3a7aSWarner Losh 2010*8e3e3a7aSWarner Losh 2011*8e3e3a7aSWarner Losh 2012*8e3e3a7aSWarner Losh 2013*8e3e3a7aSWarner Losh<h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p> 2014*8e3e3a7aSWarner LoshLua supports the following relational operators: 2015*8e3e3a7aSWarner Losh 2016*8e3e3a7aSWarner Losh<ul> 2017*8e3e3a7aSWarner Losh<li><b><code>==</code>: </b>equality</li> 2018*8e3e3a7aSWarner Losh<li><b><code>~=</code>: </b>inequality</li> 2019*8e3e3a7aSWarner Losh<li><b><code><</code>: </b>less than</li> 2020*8e3e3a7aSWarner Losh<li><b><code>></code>: </b>greater than</li> 2021*8e3e3a7aSWarner Losh<li><b><code><=</code>: </b>less or equal</li> 2022*8e3e3a7aSWarner Losh<li><b><code>>=</code>: </b>greater or equal</li> 2023*8e3e3a7aSWarner Losh</ul><p> 2024*8e3e3a7aSWarner LoshThese operators always result in <b>false</b> or <b>true</b>. 2025*8e3e3a7aSWarner Losh 2026*8e3e3a7aSWarner Losh 2027*8e3e3a7aSWarner Losh<p> 2028*8e3e3a7aSWarner LoshEquality (<code>==</code>) first compares the type of its operands. 2029*8e3e3a7aSWarner LoshIf the types are different, then the result is <b>false</b>. 2030*8e3e3a7aSWarner LoshOtherwise, the values of the operands are compared. 2031*8e3e3a7aSWarner LoshStrings are compared in the obvious way. 2032*8e3e3a7aSWarner LoshNumbers are equal if they denote the same mathematical value. 2033*8e3e3a7aSWarner Losh 2034*8e3e3a7aSWarner Losh 2035*8e3e3a7aSWarner Losh<p> 2036*8e3e3a7aSWarner LoshTables, userdata, and threads 2037*8e3e3a7aSWarner Loshare compared by reference: 2038*8e3e3a7aSWarner Loshtwo objects are considered equal only if they are the same object. 2039*8e3e3a7aSWarner LoshEvery time you create a new object 2040*8e3e3a7aSWarner Losh(a table, userdata, or thread), 2041*8e3e3a7aSWarner Loshthis new object is different from any previously existing object. 2042*8e3e3a7aSWarner LoshClosures with the same reference are always equal. 2043*8e3e3a7aSWarner LoshClosures with any detectable difference 2044*8e3e3a7aSWarner Losh(different behavior, different definition) are always different. 2045*8e3e3a7aSWarner Losh 2046*8e3e3a7aSWarner Losh 2047*8e3e3a7aSWarner Losh<p> 2048*8e3e3a7aSWarner LoshYou can change the way that Lua compares tables and userdata 2049*8e3e3a7aSWarner Loshby using the "eq" metamethod (see <a href="#2.4">§2.4</a>). 2050*8e3e3a7aSWarner Losh 2051*8e3e3a7aSWarner Losh 2052*8e3e3a7aSWarner Losh<p> 2053*8e3e3a7aSWarner LoshEquality comparisons do not convert strings to numbers 2054*8e3e3a7aSWarner Loshor vice versa. 2055*8e3e3a7aSWarner LoshThus, <code>"0"==0</code> evaluates to <b>false</b>, 2056*8e3e3a7aSWarner Loshand <code>t[0]</code> and <code>t["0"]</code> denote different 2057*8e3e3a7aSWarner Loshentries in a table. 2058*8e3e3a7aSWarner Losh 2059*8e3e3a7aSWarner Losh 2060*8e3e3a7aSWarner Losh<p> 2061*8e3e3a7aSWarner LoshThe operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 2062*8e3e3a7aSWarner Losh 2063*8e3e3a7aSWarner Losh 2064*8e3e3a7aSWarner Losh<p> 2065*8e3e3a7aSWarner LoshThe order operators work as follows. 2066*8e3e3a7aSWarner LoshIf both arguments are numbers, 2067*8e3e3a7aSWarner Loshthen they are compared according to their mathematical values 2068*8e3e3a7aSWarner Losh(regardless of their subtypes). 2069*8e3e3a7aSWarner LoshOtherwise, if both arguments are strings, 2070*8e3e3a7aSWarner Loshthen their values are compared according to the current locale. 2071*8e3e3a7aSWarner LoshOtherwise, Lua tries to call the "lt" or the "le" 2072*8e3e3a7aSWarner Loshmetamethod (see <a href="#2.4">§2.4</a>). 2073*8e3e3a7aSWarner LoshA comparison <code>a > b</code> is translated to <code>b < a</code> 2074*8e3e3a7aSWarner Loshand <code>a >= b</code> is translated to <code>b <= a</code>. 2075*8e3e3a7aSWarner Losh 2076*8e3e3a7aSWarner Losh 2077*8e3e3a7aSWarner Losh<p> 2078*8e3e3a7aSWarner LoshFollowing the IEEE 754 standard, 2079*8e3e3a7aSWarner LoshNaN is considered neither smaller than, 2080*8e3e3a7aSWarner Loshnor equal to, nor greater than any value (including itself). 2081*8e3e3a7aSWarner Losh 2082*8e3e3a7aSWarner Losh 2083*8e3e3a7aSWarner Losh 2084*8e3e3a7aSWarner Losh 2085*8e3e3a7aSWarner Losh 2086*8e3e3a7aSWarner Losh<h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p> 2087*8e3e3a7aSWarner LoshThe logical operators in Lua are 2088*8e3e3a7aSWarner Losh<b>and</b>, <b>or</b>, and <b>not</b>. 2089*8e3e3a7aSWarner LoshLike the control structures (see <a href="#3.3.4">§3.3.4</a>), 2090*8e3e3a7aSWarner Loshall logical operators consider both <b>false</b> and <b>nil</b> as false 2091*8e3e3a7aSWarner Loshand anything else as true. 2092*8e3e3a7aSWarner Losh 2093*8e3e3a7aSWarner Losh 2094*8e3e3a7aSWarner Losh<p> 2095*8e3e3a7aSWarner LoshThe negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 2096*8e3e3a7aSWarner LoshThe conjunction operator <b>and</b> returns its first argument 2097*8e3e3a7aSWarner Loshif this value is <b>false</b> or <b>nil</b>; 2098*8e3e3a7aSWarner Loshotherwise, <b>and</b> returns its second argument. 2099*8e3e3a7aSWarner LoshThe disjunction operator <b>or</b> returns its first argument 2100*8e3e3a7aSWarner Loshif this value is different from <b>nil</b> and <b>false</b>; 2101*8e3e3a7aSWarner Loshotherwise, <b>or</b> returns its second argument. 2102*8e3e3a7aSWarner LoshBoth <b>and</b> and <b>or</b> use short-circuit evaluation; 2103*8e3e3a7aSWarner Loshthat is, 2104*8e3e3a7aSWarner Loshthe second operand is evaluated only if necessary. 2105*8e3e3a7aSWarner LoshHere are some examples: 2106*8e3e3a7aSWarner Losh 2107*8e3e3a7aSWarner Losh<pre> 2108*8e3e3a7aSWarner Losh 10 or 20 --> 10 2109*8e3e3a7aSWarner Losh 10 or error() --> 10 2110*8e3e3a7aSWarner Losh nil or "a" --> "a" 2111*8e3e3a7aSWarner Losh nil and 10 --> nil 2112*8e3e3a7aSWarner Losh false and error() --> false 2113*8e3e3a7aSWarner Losh false and nil --> false 2114*8e3e3a7aSWarner Losh false or nil --> nil 2115*8e3e3a7aSWarner Losh 10 and 20 --> 20 2116*8e3e3a7aSWarner Losh</pre><p> 2117*8e3e3a7aSWarner Losh(In this manual, 2118*8e3e3a7aSWarner Losh<code>--></code> indicates the result of the preceding expression.) 2119*8e3e3a7aSWarner Losh 2120*8e3e3a7aSWarner Losh 2121*8e3e3a7aSWarner Losh 2122*8e3e3a7aSWarner Losh 2123*8e3e3a7aSWarner Losh 2124*8e3e3a7aSWarner Losh<h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p> 2125*8e3e3a7aSWarner LoshThe string concatenation operator in Lua is 2126*8e3e3a7aSWarner Loshdenoted by two dots ('<code>..</code>'). 2127*8e3e3a7aSWarner LoshIf both operands are strings or numbers, then they are converted to 2128*8e3e3a7aSWarner Loshstrings according to the rules described in <a href="#3.4.3">§3.4.3</a>. 2129*8e3e3a7aSWarner LoshOtherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). 2130*8e3e3a7aSWarner Losh 2131*8e3e3a7aSWarner Losh 2132*8e3e3a7aSWarner Losh 2133*8e3e3a7aSWarner Losh 2134*8e3e3a7aSWarner Losh 2135*8e3e3a7aSWarner Losh<h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3> 2136*8e3e3a7aSWarner Losh 2137*8e3e3a7aSWarner Losh<p> 2138*8e3e3a7aSWarner LoshThe length operator is denoted by the unary prefix operator <code>#</code>. 2139*8e3e3a7aSWarner Losh 2140*8e3e3a7aSWarner Losh 2141*8e3e3a7aSWarner Losh<p> 2142*8e3e3a7aSWarner LoshThe length of a string is its number of bytes 2143*8e3e3a7aSWarner Losh(that is, the usual meaning of string length when each 2144*8e3e3a7aSWarner Loshcharacter is one byte). 2145*8e3e3a7aSWarner Losh 2146*8e3e3a7aSWarner Losh 2147*8e3e3a7aSWarner Losh<p> 2148*8e3e3a7aSWarner LoshThe length operator applied on a table 2149*8e3e3a7aSWarner Loshreturns a border in that table. 2150*8e3e3a7aSWarner LoshA <em>border</em> in a table <code>t</code> is any natural number 2151*8e3e3a7aSWarner Loshthat satisfies the following condition: 2152*8e3e3a7aSWarner Losh 2153*8e3e3a7aSWarner Losh<pre> 2154*8e3e3a7aSWarner Losh (border == 0 or t[border] ~= nil) and t[border + 1] == nil 2155*8e3e3a7aSWarner Losh</pre><p> 2156*8e3e3a7aSWarner LoshIn words, 2157*8e3e3a7aSWarner Losha border is any (natural) index in a table 2158*8e3e3a7aSWarner Loshwhere a non-nil value is followed by a nil value 2159*8e3e3a7aSWarner Losh(or zero, when index 1 is nil). 2160*8e3e3a7aSWarner Losh 2161*8e3e3a7aSWarner Losh 2162*8e3e3a7aSWarner Losh<p> 2163*8e3e3a7aSWarner LoshA table with exactly one border is called a <em>sequence</em>. 2164*8e3e3a7aSWarner LoshFor instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence, 2165*8e3e3a7aSWarner Loshas it has only one border (5). 2166*8e3e3a7aSWarner LoshThe table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5), 2167*8e3e3a7aSWarner Loshand therefore it is not a sequence. 2168*8e3e3a7aSWarner LoshThe table <code>{nil, 20, 30, nil, nil, 60, nil}</code> 2169*8e3e3a7aSWarner Loshhas three borders (0, 3, and 6), 2170*8e3e3a7aSWarner Loshso it is not a sequence, too. 2171*8e3e3a7aSWarner LoshThe table <code>{}</code> is a sequence with border 0. 2172*8e3e3a7aSWarner LoshNote that non-natural keys do not interfere 2173*8e3e3a7aSWarner Loshwith whether a table is a sequence. 2174*8e3e3a7aSWarner Losh 2175*8e3e3a7aSWarner Losh 2176*8e3e3a7aSWarner Losh<p> 2177*8e3e3a7aSWarner LoshWhen <code>t</code> is a sequence, 2178*8e3e3a7aSWarner Losh<code>#t</code> returns its only border, 2179*8e3e3a7aSWarner Loshwhich corresponds to the intuitive notion of the length of the sequence. 2180*8e3e3a7aSWarner LoshWhen <code>t</code> is not a sequence, 2181*8e3e3a7aSWarner Losh<code>#t</code> can return any of its borders. 2182*8e3e3a7aSWarner Losh(The exact one depends on details of 2183*8e3e3a7aSWarner Loshthe internal representation of the table, 2184*8e3e3a7aSWarner Loshwhich in turn can depend on how the table was populated and 2185*8e3e3a7aSWarner Loshthe memory addresses of its non-numeric keys.) 2186*8e3e3a7aSWarner Losh 2187*8e3e3a7aSWarner Losh 2188*8e3e3a7aSWarner Losh<p> 2189*8e3e3a7aSWarner LoshThe computation of the length of a table 2190*8e3e3a7aSWarner Loshhas a guaranteed worst time of <em>O(log n)</em>, 2191*8e3e3a7aSWarner Loshwhere <em>n</em> is the largest natural key in the table. 2192*8e3e3a7aSWarner Losh 2193*8e3e3a7aSWarner Losh 2194*8e3e3a7aSWarner Losh<p> 2195*8e3e3a7aSWarner LoshA program can modify the behavior of the length operator for 2196*8e3e3a7aSWarner Loshany value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>). 2197*8e3e3a7aSWarner Losh 2198*8e3e3a7aSWarner Losh 2199*8e3e3a7aSWarner Losh 2200*8e3e3a7aSWarner Losh 2201*8e3e3a7aSWarner Losh 2202*8e3e3a7aSWarner Losh<h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p> 2203*8e3e3a7aSWarner LoshOperator precedence in Lua follows the table below, 2204*8e3e3a7aSWarner Loshfrom lower to higher priority: 2205*8e3e3a7aSWarner Losh 2206*8e3e3a7aSWarner Losh<pre> 2207*8e3e3a7aSWarner Losh or 2208*8e3e3a7aSWarner Losh and 2209*8e3e3a7aSWarner Losh < > <= >= ~= == 2210*8e3e3a7aSWarner Losh | 2211*8e3e3a7aSWarner Losh ~ 2212*8e3e3a7aSWarner Losh & 2213*8e3e3a7aSWarner Losh << >> 2214*8e3e3a7aSWarner Losh .. 2215*8e3e3a7aSWarner Losh + - 2216*8e3e3a7aSWarner Losh * / // % 2217*8e3e3a7aSWarner Losh unary operators (not # - ~) 2218*8e3e3a7aSWarner Losh ^ 2219*8e3e3a7aSWarner Losh</pre><p> 2220*8e3e3a7aSWarner LoshAs usual, 2221*8e3e3a7aSWarner Loshyou can use parentheses to change the precedences of an expression. 2222*8e3e3a7aSWarner LoshThe concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 2223*8e3e3a7aSWarner Loshoperators are right associative. 2224*8e3e3a7aSWarner LoshAll other binary operators are left associative. 2225*8e3e3a7aSWarner Losh 2226*8e3e3a7aSWarner Losh 2227*8e3e3a7aSWarner Losh 2228*8e3e3a7aSWarner Losh 2229*8e3e3a7aSWarner Losh 2230*8e3e3a7aSWarner Losh<h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p> 2231*8e3e3a7aSWarner LoshTable constructors are expressions that create tables. 2232*8e3e3a7aSWarner LoshEvery time a constructor is evaluated, a new table is created. 2233*8e3e3a7aSWarner LoshA constructor can be used to create an empty table 2234*8e3e3a7aSWarner Loshor to create a table and initialize some of its fields. 2235*8e3e3a7aSWarner LoshThe general syntax for constructors is 2236*8e3e3a7aSWarner Losh 2237*8e3e3a7aSWarner Losh<pre> 2238*8e3e3a7aSWarner Losh tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 2239*8e3e3a7aSWarner Losh fieldlist ::= field {fieldsep field} [fieldsep] 2240*8e3e3a7aSWarner Losh field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 2241*8e3e3a7aSWarner Losh fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 2242*8e3e3a7aSWarner Losh</pre> 2243*8e3e3a7aSWarner Losh 2244*8e3e3a7aSWarner Losh<p> 2245*8e3e3a7aSWarner LoshEach field of the form <code>[exp1] = exp2</code> adds to the new table an entry 2246*8e3e3a7aSWarner Loshwith key <code>exp1</code> and value <code>exp2</code>. 2247*8e3e3a7aSWarner LoshA field of the form <code>name = exp</code> is equivalent to 2248*8e3e3a7aSWarner Losh<code>["name"] = exp</code>. 2249*8e3e3a7aSWarner LoshFinally, fields of the form <code>exp</code> are equivalent to 2250*8e3e3a7aSWarner Losh<code>[i] = exp</code>, where <code>i</code> are consecutive integers 2251*8e3e3a7aSWarner Loshstarting with 1. 2252*8e3e3a7aSWarner LoshFields in the other formats do not affect this counting. 2253*8e3e3a7aSWarner LoshFor example, 2254*8e3e3a7aSWarner Losh 2255*8e3e3a7aSWarner Losh<pre> 2256*8e3e3a7aSWarner Losh a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 2257*8e3e3a7aSWarner Losh</pre><p> 2258*8e3e3a7aSWarner Loshis equivalent to 2259*8e3e3a7aSWarner Losh 2260*8e3e3a7aSWarner Losh<pre> 2261*8e3e3a7aSWarner Losh do 2262*8e3e3a7aSWarner Losh local t = {} 2263*8e3e3a7aSWarner Losh t[f(1)] = g 2264*8e3e3a7aSWarner Losh t[1] = "x" -- 1st exp 2265*8e3e3a7aSWarner Losh t[2] = "y" -- 2nd exp 2266*8e3e3a7aSWarner Losh t.x = 1 -- t["x"] = 1 2267*8e3e3a7aSWarner Losh t[3] = f(x) -- 3rd exp 2268*8e3e3a7aSWarner Losh t[30] = 23 2269*8e3e3a7aSWarner Losh t[4] = 45 -- 4th exp 2270*8e3e3a7aSWarner Losh a = t 2271*8e3e3a7aSWarner Losh end 2272*8e3e3a7aSWarner Losh</pre> 2273*8e3e3a7aSWarner Losh 2274*8e3e3a7aSWarner Losh<p> 2275*8e3e3a7aSWarner LoshThe order of the assignments in a constructor is undefined. 2276*8e3e3a7aSWarner Losh(This order would be relevant only when there are repeated keys.) 2277*8e3e3a7aSWarner Losh 2278*8e3e3a7aSWarner Losh 2279*8e3e3a7aSWarner Losh<p> 2280*8e3e3a7aSWarner LoshIf the last field in the list has the form <code>exp</code> 2281*8e3e3a7aSWarner Loshand the expression is a function call or a vararg expression, 2282*8e3e3a7aSWarner Loshthen all values returned by this expression enter the list consecutively 2283*8e3e3a7aSWarner Losh(see <a href="#3.4.10">§3.4.10</a>). 2284*8e3e3a7aSWarner Losh 2285*8e3e3a7aSWarner Losh 2286*8e3e3a7aSWarner Losh<p> 2287*8e3e3a7aSWarner LoshThe field list can have an optional trailing separator, 2288*8e3e3a7aSWarner Loshas a convenience for machine-generated code. 2289*8e3e3a7aSWarner Losh 2290*8e3e3a7aSWarner Losh 2291*8e3e3a7aSWarner Losh 2292*8e3e3a7aSWarner Losh 2293*8e3e3a7aSWarner Losh 2294*8e3e3a7aSWarner Losh<h3>3.4.10 – <a name="3.4.10">Function Calls</a></h3><p> 2295*8e3e3a7aSWarner LoshA function call in Lua has the following syntax: 2296*8e3e3a7aSWarner Losh 2297*8e3e3a7aSWarner Losh<pre> 2298*8e3e3a7aSWarner Losh functioncall ::= prefixexp args 2299*8e3e3a7aSWarner Losh</pre><p> 2300*8e3e3a7aSWarner LoshIn a function call, 2301*8e3e3a7aSWarner Loshfirst prefixexp and args are evaluated. 2302*8e3e3a7aSWarner LoshIf the value of prefixexp has type <em>function</em>, 2303*8e3e3a7aSWarner Loshthen this function is called 2304*8e3e3a7aSWarner Loshwith the given arguments. 2305*8e3e3a7aSWarner LoshOtherwise, the prefixexp "call" metamethod is called, 2306*8e3e3a7aSWarner Loshhaving as first parameter the value of prefixexp, 2307*8e3e3a7aSWarner Loshfollowed by the original call arguments 2308*8e3e3a7aSWarner Losh(see <a href="#2.4">§2.4</a>). 2309*8e3e3a7aSWarner Losh 2310*8e3e3a7aSWarner Losh 2311*8e3e3a7aSWarner Losh<p> 2312*8e3e3a7aSWarner LoshThe form 2313*8e3e3a7aSWarner Losh 2314*8e3e3a7aSWarner Losh<pre> 2315*8e3e3a7aSWarner Losh functioncall ::= prefixexp ‘<b>:</b>’ Name args 2316*8e3e3a7aSWarner Losh</pre><p> 2317*8e3e3a7aSWarner Loshcan be used to call "methods". 2318*8e3e3a7aSWarner LoshA call <code>v:name(<em>args</em>)</code> 2319*8e3e3a7aSWarner Loshis syntactic sugar for <code>v.name(v,<em>args</em>)</code>, 2320*8e3e3a7aSWarner Loshexcept that <code>v</code> is evaluated only once. 2321*8e3e3a7aSWarner Losh 2322*8e3e3a7aSWarner Losh 2323*8e3e3a7aSWarner Losh<p> 2324*8e3e3a7aSWarner LoshArguments have the following syntax: 2325*8e3e3a7aSWarner Losh 2326*8e3e3a7aSWarner Losh<pre> 2327*8e3e3a7aSWarner Losh args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ 2328*8e3e3a7aSWarner Losh args ::= tableconstructor 2329*8e3e3a7aSWarner Losh args ::= LiteralString 2330*8e3e3a7aSWarner Losh</pre><p> 2331*8e3e3a7aSWarner LoshAll argument expressions are evaluated before the call. 2332*8e3e3a7aSWarner LoshA call of the form <code>f{<em>fields</em>}</code> is 2333*8e3e3a7aSWarner Loshsyntactic sugar for <code>f({<em>fields</em>})</code>; 2334*8e3e3a7aSWarner Loshthat is, the argument list is a single new table. 2335*8e3e3a7aSWarner LoshA call of the form <code>f'<em>string</em>'</code> 2336*8e3e3a7aSWarner Losh(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 2337*8e3e3a7aSWarner Loshis syntactic sugar for <code>f('<em>string</em>')</code>; 2338*8e3e3a7aSWarner Loshthat is, the argument list is a single literal string. 2339*8e3e3a7aSWarner Losh 2340*8e3e3a7aSWarner Losh 2341*8e3e3a7aSWarner Losh<p> 2342*8e3e3a7aSWarner LoshA call of the form <code>return <em>functioncall</em></code> is called 2343*8e3e3a7aSWarner Losha <em>tail call</em>. 2344*8e3e3a7aSWarner LoshLua implements <em>proper tail calls</em> 2345*8e3e3a7aSWarner Losh(or <em>proper tail recursion</em>): 2346*8e3e3a7aSWarner Loshin a tail call, 2347*8e3e3a7aSWarner Loshthe called function reuses the stack entry of the calling function. 2348*8e3e3a7aSWarner LoshTherefore, there is no limit on the number of nested tail calls that 2349*8e3e3a7aSWarner Losha program can execute. 2350*8e3e3a7aSWarner LoshHowever, a tail call erases any debug information about the 2351*8e3e3a7aSWarner Loshcalling function. 2352*8e3e3a7aSWarner LoshNote that a tail call only happens with a particular syntax, 2353*8e3e3a7aSWarner Loshwhere the <b>return</b> has one single function call as argument; 2354*8e3e3a7aSWarner Loshthis syntax makes the calling function return exactly 2355*8e3e3a7aSWarner Loshthe returns of the called function. 2356*8e3e3a7aSWarner LoshSo, none of the following examples are tail calls: 2357*8e3e3a7aSWarner Losh 2358*8e3e3a7aSWarner Losh<pre> 2359*8e3e3a7aSWarner Losh return (f(x)) -- results adjusted to 1 2360*8e3e3a7aSWarner Losh return 2 * f(x) 2361*8e3e3a7aSWarner Losh return x, f(x) -- additional results 2362*8e3e3a7aSWarner Losh f(x); return -- results discarded 2363*8e3e3a7aSWarner Losh return x or f(x) -- results adjusted to 1 2364*8e3e3a7aSWarner Losh</pre> 2365*8e3e3a7aSWarner Losh 2366*8e3e3a7aSWarner Losh 2367*8e3e3a7aSWarner Losh 2368*8e3e3a7aSWarner Losh 2369*8e3e3a7aSWarner Losh<h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3> 2370*8e3e3a7aSWarner Losh 2371*8e3e3a7aSWarner Losh<p> 2372*8e3e3a7aSWarner LoshThe syntax for function definition is 2373*8e3e3a7aSWarner Losh 2374*8e3e3a7aSWarner Losh<pre> 2375*8e3e3a7aSWarner Losh functiondef ::= <b>function</b> funcbody 2376*8e3e3a7aSWarner Losh funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 2377*8e3e3a7aSWarner Losh</pre> 2378*8e3e3a7aSWarner Losh 2379*8e3e3a7aSWarner Losh<p> 2380*8e3e3a7aSWarner LoshThe following syntactic sugar simplifies function definitions: 2381*8e3e3a7aSWarner Losh 2382*8e3e3a7aSWarner Losh<pre> 2383*8e3e3a7aSWarner Losh stat ::= <b>function</b> funcname funcbody 2384*8e3e3a7aSWarner Losh stat ::= <b>local</b> <b>function</b> Name funcbody 2385*8e3e3a7aSWarner Losh funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 2386*8e3e3a7aSWarner Losh</pre><p> 2387*8e3e3a7aSWarner LoshThe statement 2388*8e3e3a7aSWarner Losh 2389*8e3e3a7aSWarner Losh<pre> 2390*8e3e3a7aSWarner Losh function f () <em>body</em> end 2391*8e3e3a7aSWarner Losh</pre><p> 2392*8e3e3a7aSWarner Loshtranslates to 2393*8e3e3a7aSWarner Losh 2394*8e3e3a7aSWarner Losh<pre> 2395*8e3e3a7aSWarner Losh f = function () <em>body</em> end 2396*8e3e3a7aSWarner Losh</pre><p> 2397*8e3e3a7aSWarner LoshThe statement 2398*8e3e3a7aSWarner Losh 2399*8e3e3a7aSWarner Losh<pre> 2400*8e3e3a7aSWarner Losh function t.a.b.c.f () <em>body</em> end 2401*8e3e3a7aSWarner Losh</pre><p> 2402*8e3e3a7aSWarner Loshtranslates to 2403*8e3e3a7aSWarner Losh 2404*8e3e3a7aSWarner Losh<pre> 2405*8e3e3a7aSWarner Losh t.a.b.c.f = function () <em>body</em> end 2406*8e3e3a7aSWarner Losh</pre><p> 2407*8e3e3a7aSWarner LoshThe statement 2408*8e3e3a7aSWarner Losh 2409*8e3e3a7aSWarner Losh<pre> 2410*8e3e3a7aSWarner Losh local function f () <em>body</em> end 2411*8e3e3a7aSWarner Losh</pre><p> 2412*8e3e3a7aSWarner Loshtranslates to 2413*8e3e3a7aSWarner Losh 2414*8e3e3a7aSWarner Losh<pre> 2415*8e3e3a7aSWarner Losh local f; f = function () <em>body</em> end 2416*8e3e3a7aSWarner Losh</pre><p> 2417*8e3e3a7aSWarner Loshnot to 2418*8e3e3a7aSWarner Losh 2419*8e3e3a7aSWarner Losh<pre> 2420*8e3e3a7aSWarner Losh local f = function () <em>body</em> end 2421*8e3e3a7aSWarner Losh</pre><p> 2422*8e3e3a7aSWarner Losh(This only makes a difference when the body of the function 2423*8e3e3a7aSWarner Loshcontains references to <code>f</code>.) 2424*8e3e3a7aSWarner Losh 2425*8e3e3a7aSWarner Losh 2426*8e3e3a7aSWarner Losh<p> 2427*8e3e3a7aSWarner LoshA function definition is an executable expression, 2428*8e3e3a7aSWarner Loshwhose value has type <em>function</em>. 2429*8e3e3a7aSWarner LoshWhen Lua precompiles a chunk, 2430*8e3e3a7aSWarner Loshall its function bodies are precompiled too. 2431*8e3e3a7aSWarner LoshThen, whenever Lua executes the function definition, 2432*8e3e3a7aSWarner Loshthe function is <em>instantiated</em> (or <em>closed</em>). 2433*8e3e3a7aSWarner LoshThis function instance (or <em>closure</em>) 2434*8e3e3a7aSWarner Loshis the final value of the expression. 2435*8e3e3a7aSWarner Losh 2436*8e3e3a7aSWarner Losh 2437*8e3e3a7aSWarner Losh<p> 2438*8e3e3a7aSWarner LoshParameters act as local variables that are 2439*8e3e3a7aSWarner Loshinitialized with the argument values: 2440*8e3e3a7aSWarner Losh 2441*8e3e3a7aSWarner Losh<pre> 2442*8e3e3a7aSWarner Losh parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 2443*8e3e3a7aSWarner Losh</pre><p> 2444*8e3e3a7aSWarner LoshWhen a function is called, 2445*8e3e3a7aSWarner Loshthe list of arguments is adjusted to 2446*8e3e3a7aSWarner Loshthe length of the list of parameters, 2447*8e3e3a7aSWarner Loshunless the function is a <em>vararg function</em>, 2448*8e3e3a7aSWarner Loshwhich is indicated by three dots ('<code>...</code>') 2449*8e3e3a7aSWarner Loshat the end of its parameter list. 2450*8e3e3a7aSWarner LoshA vararg function does not adjust its argument list; 2451*8e3e3a7aSWarner Loshinstead, it collects all extra arguments and supplies them 2452*8e3e3a7aSWarner Loshto the function through a <em>vararg expression</em>, 2453*8e3e3a7aSWarner Loshwhich is also written as three dots. 2454*8e3e3a7aSWarner LoshThe value of this expression is a list of all actual extra arguments, 2455*8e3e3a7aSWarner Loshsimilar to a function with multiple results. 2456*8e3e3a7aSWarner LoshIf a vararg expression is used inside another expression 2457*8e3e3a7aSWarner Loshor in the middle of a list of expressions, 2458*8e3e3a7aSWarner Loshthen its return list is adjusted to one element. 2459*8e3e3a7aSWarner LoshIf the expression is used as the last element of a list of expressions, 2460*8e3e3a7aSWarner Loshthen no adjustment is made 2461*8e3e3a7aSWarner Losh(unless that last expression is enclosed in parentheses). 2462*8e3e3a7aSWarner Losh 2463*8e3e3a7aSWarner Losh 2464*8e3e3a7aSWarner Losh<p> 2465*8e3e3a7aSWarner LoshAs an example, consider the following definitions: 2466*8e3e3a7aSWarner Losh 2467*8e3e3a7aSWarner Losh<pre> 2468*8e3e3a7aSWarner Losh function f(a, b) end 2469*8e3e3a7aSWarner Losh function g(a, b, ...) end 2470*8e3e3a7aSWarner Losh function r() return 1,2,3 end 2471*8e3e3a7aSWarner Losh</pre><p> 2472*8e3e3a7aSWarner LoshThen, we have the following mapping from arguments to parameters and 2473*8e3e3a7aSWarner Loshto the vararg expression: 2474*8e3e3a7aSWarner Losh 2475*8e3e3a7aSWarner Losh<pre> 2476*8e3e3a7aSWarner Losh CALL PARAMETERS 2477*8e3e3a7aSWarner Losh 2478*8e3e3a7aSWarner Losh f(3) a=3, b=nil 2479*8e3e3a7aSWarner Losh f(3, 4) a=3, b=4 2480*8e3e3a7aSWarner Losh f(3, 4, 5) a=3, b=4 2481*8e3e3a7aSWarner Losh f(r(), 10) a=1, b=10 2482*8e3e3a7aSWarner Losh f(r()) a=1, b=2 2483*8e3e3a7aSWarner Losh 2484*8e3e3a7aSWarner Losh g(3) a=3, b=nil, ... --> (nothing) 2485*8e3e3a7aSWarner Losh g(3, 4) a=3, b=4, ... --> (nothing) 2486*8e3e3a7aSWarner Losh g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 2487*8e3e3a7aSWarner Losh g(5, r()) a=5, b=1, ... --> 2 3 2488*8e3e3a7aSWarner Losh</pre> 2489*8e3e3a7aSWarner Losh 2490*8e3e3a7aSWarner Losh<p> 2491*8e3e3a7aSWarner LoshResults are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>). 2492*8e3e3a7aSWarner LoshIf control reaches the end of a function 2493*8e3e3a7aSWarner Loshwithout encountering a <b>return</b> statement, 2494*8e3e3a7aSWarner Loshthen the function returns with no results. 2495*8e3e3a7aSWarner Losh 2496*8e3e3a7aSWarner Losh 2497*8e3e3a7aSWarner Losh<p> 2498*8e3e3a7aSWarner Losh 2499*8e3e3a7aSWarner LoshThere is a system-dependent limit on the number of values 2500*8e3e3a7aSWarner Loshthat a function may return. 2501*8e3e3a7aSWarner LoshThis limit is guaranteed to be larger than 1000. 2502*8e3e3a7aSWarner Losh 2503*8e3e3a7aSWarner Losh 2504*8e3e3a7aSWarner Losh<p> 2505*8e3e3a7aSWarner LoshThe <em>colon</em> syntax 2506*8e3e3a7aSWarner Loshis used for defining <em>methods</em>, 2507*8e3e3a7aSWarner Loshthat is, functions that have an implicit extra parameter <code>self</code>. 2508*8e3e3a7aSWarner LoshThus, the statement 2509*8e3e3a7aSWarner Losh 2510*8e3e3a7aSWarner Losh<pre> 2511*8e3e3a7aSWarner Losh function t.a.b.c:f (<em>params</em>) <em>body</em> end 2512*8e3e3a7aSWarner Losh</pre><p> 2513*8e3e3a7aSWarner Loshis syntactic sugar for 2514*8e3e3a7aSWarner Losh 2515*8e3e3a7aSWarner Losh<pre> 2516*8e3e3a7aSWarner Losh t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end 2517*8e3e3a7aSWarner Losh</pre> 2518*8e3e3a7aSWarner Losh 2519*8e3e3a7aSWarner Losh 2520*8e3e3a7aSWarner Losh 2521*8e3e3a7aSWarner Losh 2522*8e3e3a7aSWarner Losh 2523*8e3e3a7aSWarner Losh 2524*8e3e3a7aSWarner Losh<h2>3.5 – <a name="3.5">Visibility Rules</a></h2> 2525*8e3e3a7aSWarner Losh 2526*8e3e3a7aSWarner Losh<p> 2527*8e3e3a7aSWarner Losh 2528*8e3e3a7aSWarner LoshLua is a lexically scoped language. 2529*8e3e3a7aSWarner LoshThe scope of a local variable begins at the first statement after 2530*8e3e3a7aSWarner Loshits declaration and lasts until the last non-void statement 2531*8e3e3a7aSWarner Loshof the innermost block that includes the declaration. 2532*8e3e3a7aSWarner LoshConsider the following example: 2533*8e3e3a7aSWarner Losh 2534*8e3e3a7aSWarner Losh<pre> 2535*8e3e3a7aSWarner Losh x = 10 -- global variable 2536*8e3e3a7aSWarner Losh do -- new block 2537*8e3e3a7aSWarner Losh local x = x -- new 'x', with value 10 2538*8e3e3a7aSWarner Losh print(x) --> 10 2539*8e3e3a7aSWarner Losh x = x+1 2540*8e3e3a7aSWarner Losh do -- another block 2541*8e3e3a7aSWarner Losh local x = x+1 -- another 'x' 2542*8e3e3a7aSWarner Losh print(x) --> 12 2543*8e3e3a7aSWarner Losh end 2544*8e3e3a7aSWarner Losh print(x) --> 11 2545*8e3e3a7aSWarner Losh end 2546*8e3e3a7aSWarner Losh print(x) --> 10 (the global one) 2547*8e3e3a7aSWarner Losh</pre> 2548*8e3e3a7aSWarner Losh 2549*8e3e3a7aSWarner Losh<p> 2550*8e3e3a7aSWarner LoshNotice that, in a declaration like <code>local x = x</code>, 2551*8e3e3a7aSWarner Loshthe new <code>x</code> being declared is not in scope yet, 2552*8e3e3a7aSWarner Loshand so the second <code>x</code> refers to the outside variable. 2553*8e3e3a7aSWarner Losh 2554*8e3e3a7aSWarner Losh 2555*8e3e3a7aSWarner Losh<p> 2556*8e3e3a7aSWarner LoshBecause of the lexical scoping rules, 2557*8e3e3a7aSWarner Loshlocal variables can be freely accessed by functions 2558*8e3e3a7aSWarner Loshdefined inside their scope. 2559*8e3e3a7aSWarner LoshA local variable used by an inner function is called 2560*8e3e3a7aSWarner Loshan <em>upvalue</em>, or <em>external local variable</em>, 2561*8e3e3a7aSWarner Loshinside the inner function. 2562*8e3e3a7aSWarner Losh 2563*8e3e3a7aSWarner Losh 2564*8e3e3a7aSWarner Losh<p> 2565*8e3e3a7aSWarner LoshNotice that each execution of a <b>local</b> statement 2566*8e3e3a7aSWarner Loshdefines new local variables. 2567*8e3e3a7aSWarner LoshConsider the following example: 2568*8e3e3a7aSWarner Losh 2569*8e3e3a7aSWarner Losh<pre> 2570*8e3e3a7aSWarner Losh a = {} 2571*8e3e3a7aSWarner Losh local x = 20 2572*8e3e3a7aSWarner Losh for i=1,10 do 2573*8e3e3a7aSWarner Losh local y = 0 2574*8e3e3a7aSWarner Losh a[i] = function () y=y+1; return x+y end 2575*8e3e3a7aSWarner Losh end 2576*8e3e3a7aSWarner Losh</pre><p> 2577*8e3e3a7aSWarner LoshThe loop creates ten closures 2578*8e3e3a7aSWarner Losh(that is, ten instances of the anonymous function). 2579*8e3e3a7aSWarner LoshEach of these closures uses a different <code>y</code> variable, 2580*8e3e3a7aSWarner Loshwhile all of them share the same <code>x</code>. 2581*8e3e3a7aSWarner Losh 2582*8e3e3a7aSWarner Losh 2583*8e3e3a7aSWarner Losh 2584*8e3e3a7aSWarner Losh 2585*8e3e3a7aSWarner Losh 2586*8e3e3a7aSWarner Losh<h1>4 – <a name="4">The Application Program Interface</a></h1> 2587*8e3e3a7aSWarner Losh 2588*8e3e3a7aSWarner Losh<p> 2589*8e3e3a7aSWarner Losh 2590*8e3e3a7aSWarner LoshThis section describes the C API for Lua, that is, 2591*8e3e3a7aSWarner Loshthe set of C functions available to the host program to communicate 2592*8e3e3a7aSWarner Loshwith Lua. 2593*8e3e3a7aSWarner LoshAll API functions and related types and constants 2594*8e3e3a7aSWarner Loshare declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. 2595*8e3e3a7aSWarner Losh 2596*8e3e3a7aSWarner Losh 2597*8e3e3a7aSWarner Losh<p> 2598*8e3e3a7aSWarner LoshEven when we use the term "function", 2599*8e3e3a7aSWarner Loshany facility in the API may be provided as a macro instead. 2600*8e3e3a7aSWarner LoshExcept where stated otherwise, 2601*8e3e3a7aSWarner Loshall such macros use each of their arguments exactly once 2602*8e3e3a7aSWarner Losh(except for the first argument, which is always a Lua state), 2603*8e3e3a7aSWarner Loshand so do not generate any hidden side-effects. 2604*8e3e3a7aSWarner Losh 2605*8e3e3a7aSWarner Losh 2606*8e3e3a7aSWarner Losh<p> 2607*8e3e3a7aSWarner LoshAs in most C libraries, 2608*8e3e3a7aSWarner Loshthe Lua API functions do not check their arguments for validity or consistency. 2609*8e3e3a7aSWarner LoshHowever, you can change this behavior by compiling Lua 2610*8e3e3a7aSWarner Loshwith the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined. 2611*8e3e3a7aSWarner Losh 2612*8e3e3a7aSWarner Losh 2613*8e3e3a7aSWarner Losh<p> 2614*8e3e3a7aSWarner LoshThe Lua library is fully reentrant: 2615*8e3e3a7aSWarner Loshit has no global variables. 2616*8e3e3a7aSWarner LoshIt keeps all information it needs in a dynamic structure, 2617*8e3e3a7aSWarner Loshcalled the <em>Lua state</em>. 2618*8e3e3a7aSWarner Losh 2619*8e3e3a7aSWarner Losh 2620*8e3e3a7aSWarner Losh<p> 2621*8e3e3a7aSWarner LoshEach Lua state has one or more threads, 2622*8e3e3a7aSWarner Loshwhich correspond to independent, cooperative lines of execution. 2623*8e3e3a7aSWarner LoshThe type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread. 2624*8e3e3a7aSWarner Losh(Indirectly, through the thread, it also refers to the 2625*8e3e3a7aSWarner LoshLua state associated to the thread.) 2626*8e3e3a7aSWarner Losh 2627*8e3e3a7aSWarner Losh 2628*8e3e3a7aSWarner Losh<p> 2629*8e3e3a7aSWarner LoshA pointer to a thread must be passed as the first argument to 2630*8e3e3a7aSWarner Loshevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 2631*8e3e3a7aSWarner Loshwhich creates a Lua state from scratch and returns a pointer 2632*8e3e3a7aSWarner Loshto the <em>main thread</em> in the new state. 2633*8e3e3a7aSWarner Losh 2634*8e3e3a7aSWarner Losh 2635*8e3e3a7aSWarner Losh 2636*8e3e3a7aSWarner Losh<h2>4.1 – <a name="4.1">The Stack</a></h2> 2637*8e3e3a7aSWarner Losh 2638*8e3e3a7aSWarner Losh<p> 2639*8e3e3a7aSWarner LoshLua uses a <em>virtual stack</em> to pass values to and from C. 2640*8e3e3a7aSWarner LoshEach element in this stack represents a Lua value 2641*8e3e3a7aSWarner Losh(<b>nil</b>, number, string, etc.). 2642*8e3e3a7aSWarner LoshFunctions in the API can access this stack through the 2643*8e3e3a7aSWarner LoshLua state parameter that they receive. 2644*8e3e3a7aSWarner Losh 2645*8e3e3a7aSWarner Losh 2646*8e3e3a7aSWarner Losh<p> 2647*8e3e3a7aSWarner LoshWhenever Lua calls C, the called function gets a new stack, 2648*8e3e3a7aSWarner Loshwhich is independent of previous stacks and of stacks of 2649*8e3e3a7aSWarner LoshC functions that are still active. 2650*8e3e3a7aSWarner LoshThis stack initially contains any arguments to the C function 2651*8e3e3a7aSWarner Loshand it is where the C function can store temporary 2652*8e3e3a7aSWarner LoshLua values and must push its results 2653*8e3e3a7aSWarner Loshto be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 2654*8e3e3a7aSWarner Losh 2655*8e3e3a7aSWarner Losh 2656*8e3e3a7aSWarner Losh<p> 2657*8e3e3a7aSWarner LoshFor convenience, 2658*8e3e3a7aSWarner Loshmost query operations in the API do not follow a strict stack discipline. 2659*8e3e3a7aSWarner LoshInstead, they can refer to any element in the stack 2660*8e3e3a7aSWarner Loshby using an <em>index</em>: 2661*8e3e3a7aSWarner LoshA positive index represents an absolute stack position 2662*8e3e3a7aSWarner Losh(starting at 1); 2663*8e3e3a7aSWarner Losha negative index represents an offset relative to the top of the stack. 2664*8e3e3a7aSWarner LoshMore specifically, if the stack has <em>n</em> elements, 2665*8e3e3a7aSWarner Loshthen index 1 represents the first element 2666*8e3e3a7aSWarner Losh(that is, the element that was pushed onto the stack first) 2667*8e3e3a7aSWarner Loshand 2668*8e3e3a7aSWarner Loshindex <em>n</em> represents the last element; 2669*8e3e3a7aSWarner Loshindex -1 also represents the last element 2670*8e3e3a7aSWarner Losh(that is, the element at the top) 2671*8e3e3a7aSWarner Loshand index <em>-n</em> represents the first element. 2672*8e3e3a7aSWarner Losh 2673*8e3e3a7aSWarner Losh 2674*8e3e3a7aSWarner Losh 2675*8e3e3a7aSWarner Losh 2676*8e3e3a7aSWarner Losh 2677*8e3e3a7aSWarner Losh<h2>4.2 – <a name="4.2">Stack Size</a></h2> 2678*8e3e3a7aSWarner Losh 2679*8e3e3a7aSWarner Losh<p> 2680*8e3e3a7aSWarner LoshWhen you interact with the Lua API, 2681*8e3e3a7aSWarner Loshyou are responsible for ensuring consistency. 2682*8e3e3a7aSWarner LoshIn particular, 2683*8e3e3a7aSWarner Losh<em>you are responsible for controlling stack overflow</em>. 2684*8e3e3a7aSWarner LoshYou can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> 2685*8e3e3a7aSWarner Loshto ensure that the stack has enough space for pushing new elements. 2686*8e3e3a7aSWarner Losh 2687*8e3e3a7aSWarner Losh 2688*8e3e3a7aSWarner Losh<p> 2689*8e3e3a7aSWarner LoshWhenever Lua calls C, 2690*8e3e3a7aSWarner Loshit ensures that the stack has space for 2691*8e3e3a7aSWarner Loshat least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots. 2692*8e3e3a7aSWarner Losh<code>LUA_MINSTACK</code> is defined as 20, 2693*8e3e3a7aSWarner Loshso that usually you do not have to worry about stack space 2694*8e3e3a7aSWarner Loshunless your code has loops pushing elements onto the stack. 2695*8e3e3a7aSWarner Losh 2696*8e3e3a7aSWarner Losh 2697*8e3e3a7aSWarner Losh<p> 2698*8e3e3a7aSWarner LoshWhen you call a Lua function 2699*8e3e3a7aSWarner Loshwithout a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>), 2700*8e3e3a7aSWarner LoshLua ensures that the stack has enough space for all results, 2701*8e3e3a7aSWarner Loshbut it does not ensure any extra space. 2702*8e3e3a7aSWarner LoshSo, before pushing anything in the stack after such a call 2703*8e3e3a7aSWarner Loshyou should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>. 2704*8e3e3a7aSWarner Losh 2705*8e3e3a7aSWarner Losh 2706*8e3e3a7aSWarner Losh 2707*8e3e3a7aSWarner Losh 2708*8e3e3a7aSWarner Losh 2709*8e3e3a7aSWarner Losh<h2>4.3 – <a name="4.3">Valid and Acceptable Indices</a></h2> 2710*8e3e3a7aSWarner Losh 2711*8e3e3a7aSWarner Losh<p> 2712*8e3e3a7aSWarner LoshAny function in the API that receives stack indices 2713*8e3e3a7aSWarner Loshworks only with <em>valid indices</em> or <em>acceptable indices</em>. 2714*8e3e3a7aSWarner Losh 2715*8e3e3a7aSWarner Losh 2716*8e3e3a7aSWarner Losh<p> 2717*8e3e3a7aSWarner LoshA <em>valid index</em> is an index that refers to a 2718*8e3e3a7aSWarner Loshposition that stores a modifiable Lua value. 2719*8e3e3a7aSWarner LoshIt comprises stack indices between 1 and the stack top 2720*8e3e3a7aSWarner Losh(<code>1 ≤ abs(index) ≤ top</code>) 2721*8e3e3a7aSWarner Losh 2722*8e3e3a7aSWarner Loshplus <em>pseudo-indices</em>, 2723*8e3e3a7aSWarner Loshwhich represent some positions that are accessible to C code 2724*8e3e3a7aSWarner Loshbut that are not in the stack. 2725*8e3e3a7aSWarner LoshPseudo-indices are used to access the registry (see <a href="#4.5">§4.5</a>) 2726*8e3e3a7aSWarner Loshand the upvalues of a C function (see <a href="#4.4">§4.4</a>). 2727*8e3e3a7aSWarner Losh 2728*8e3e3a7aSWarner Losh 2729*8e3e3a7aSWarner Losh<p> 2730*8e3e3a7aSWarner LoshFunctions that do not need a specific mutable position, 2731*8e3e3a7aSWarner Loshbut only a value (e.g., query functions), 2732*8e3e3a7aSWarner Loshcan be called with acceptable indices. 2733*8e3e3a7aSWarner LoshAn <em>acceptable index</em> can be any valid index, 2734*8e3e3a7aSWarner Loshbut it also can be any positive index after the stack top 2735*8e3e3a7aSWarner Loshwithin the space allocated for the stack, 2736*8e3e3a7aSWarner Loshthat is, indices up to the stack size. 2737*8e3e3a7aSWarner Losh(Note that 0 is never an acceptable index.) 2738*8e3e3a7aSWarner LoshExcept when noted otherwise, 2739*8e3e3a7aSWarner Loshfunctions in the API work with acceptable indices. 2740*8e3e3a7aSWarner Losh 2741*8e3e3a7aSWarner Losh 2742*8e3e3a7aSWarner Losh<p> 2743*8e3e3a7aSWarner LoshAcceptable indices serve to avoid extra tests 2744*8e3e3a7aSWarner Loshagainst the stack top when querying the stack. 2745*8e3e3a7aSWarner LoshFor instance, a C function can query its third argument 2746*8e3e3a7aSWarner Loshwithout the need to first check whether there is a third argument, 2747*8e3e3a7aSWarner Loshthat is, without the need to check whether 3 is a valid index. 2748*8e3e3a7aSWarner Losh 2749*8e3e3a7aSWarner Losh 2750*8e3e3a7aSWarner Losh<p> 2751*8e3e3a7aSWarner LoshFor functions that can be called with acceptable indices, 2752*8e3e3a7aSWarner Loshany non-valid index is treated as if it 2753*8e3e3a7aSWarner Loshcontains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>, 2754*8e3e3a7aSWarner Loshwhich behaves like a nil value. 2755*8e3e3a7aSWarner Losh 2756*8e3e3a7aSWarner Losh 2757*8e3e3a7aSWarner Losh 2758*8e3e3a7aSWarner Losh 2759*8e3e3a7aSWarner Losh 2760*8e3e3a7aSWarner Losh<h2>4.4 – <a name="4.4">C Closures</a></h2> 2761*8e3e3a7aSWarner Losh 2762*8e3e3a7aSWarner Losh<p> 2763*8e3e3a7aSWarner LoshWhen a C function is created, 2764*8e3e3a7aSWarner Loshit is possible to associate some values with it, 2765*8e3e3a7aSWarner Loshthus creating a <em>C closure</em> 2766*8e3e3a7aSWarner Losh(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>); 2767*8e3e3a7aSWarner Loshthese values are called <em>upvalues</em> and are 2768*8e3e3a7aSWarner Loshaccessible to the function whenever it is called. 2769*8e3e3a7aSWarner Losh 2770*8e3e3a7aSWarner Losh 2771*8e3e3a7aSWarner Losh<p> 2772*8e3e3a7aSWarner LoshWhenever a C function is called, 2773*8e3e3a7aSWarner Loshits upvalues are located at specific pseudo-indices. 2774*8e3e3a7aSWarner LoshThese pseudo-indices are produced by the macro 2775*8e3e3a7aSWarner Losh<a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>. 2776*8e3e3a7aSWarner LoshThe first upvalue associated with a function is at index 2777*8e3e3a7aSWarner Losh<code>lua_upvalueindex(1)</code>, and so on. 2778*8e3e3a7aSWarner LoshAny access to <code>lua_upvalueindex(<em>n</em>)</code>, 2779*8e3e3a7aSWarner Loshwhere <em>n</em> is greater than the number of upvalues of the 2780*8e3e3a7aSWarner Loshcurrent function 2781*8e3e3a7aSWarner Losh(but not greater than 256, 2782*8e3e3a7aSWarner Loshwhich is one plus the maximum number of upvalues in a closure), 2783*8e3e3a7aSWarner Loshproduces an acceptable but invalid index. 2784*8e3e3a7aSWarner Losh 2785*8e3e3a7aSWarner Losh 2786*8e3e3a7aSWarner Losh 2787*8e3e3a7aSWarner Losh 2788*8e3e3a7aSWarner Losh 2789*8e3e3a7aSWarner Losh<h2>4.5 – <a name="4.5">Registry</a></h2> 2790*8e3e3a7aSWarner Losh 2791*8e3e3a7aSWarner Losh<p> 2792*8e3e3a7aSWarner LoshLua provides a <em>registry</em>, 2793*8e3e3a7aSWarner Losha predefined table that can be used by any C code to 2794*8e3e3a7aSWarner Loshstore whatever Lua values it needs to store. 2795*8e3e3a7aSWarner LoshThe registry table is always located at pseudo-index 2796*8e3e3a7aSWarner Losh<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. 2797*8e3e3a7aSWarner LoshAny C library can store data into this table, 2798*8e3e3a7aSWarner Loshbut it must take care to choose keys 2799*8e3e3a7aSWarner Loshthat are different from those used 2800*8e3e3a7aSWarner Loshby other libraries, to avoid collisions. 2801*8e3e3a7aSWarner LoshTypically, you should use as key a string containing your library name, 2802*8e3e3a7aSWarner Loshor a light userdata with the address of a C object in your code, 2803*8e3e3a7aSWarner Loshor any Lua object created by your code. 2804*8e3e3a7aSWarner LoshAs with variable names, 2805*8e3e3a7aSWarner Loshstring keys starting with an underscore followed by 2806*8e3e3a7aSWarner Loshuppercase letters are reserved for Lua. 2807*8e3e3a7aSWarner Losh 2808*8e3e3a7aSWarner Losh 2809*8e3e3a7aSWarner Losh<p> 2810*8e3e3a7aSWarner LoshThe integer keys in the registry are used 2811*8e3e3a7aSWarner Loshby the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>) 2812*8e3e3a7aSWarner Loshand by some predefined values. 2813*8e3e3a7aSWarner LoshTherefore, integer keys must not be used for other purposes. 2814*8e3e3a7aSWarner Losh 2815*8e3e3a7aSWarner Losh 2816*8e3e3a7aSWarner Losh<p> 2817*8e3e3a7aSWarner LoshWhen you create a new Lua state, 2818*8e3e3a7aSWarner Loshits registry comes with some predefined values. 2819*8e3e3a7aSWarner LoshThese predefined values are indexed with integer keys 2820*8e3e3a7aSWarner Loshdefined as constants in <code>lua.h</code>. 2821*8e3e3a7aSWarner LoshThe following constants are defined: 2822*8e3e3a7aSWarner Losh 2823*8e3e3a7aSWarner Losh<ul> 2824*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has 2825*8e3e3a7aSWarner Loshthe main thread of the state. 2826*8e3e3a7aSWarner Losh(The main thread is the one created together with the state.) 2827*8e3e3a7aSWarner Losh</li> 2828*8e3e3a7aSWarner Losh 2829*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has 2830*8e3e3a7aSWarner Loshthe global environment. 2831*8e3e3a7aSWarner Losh</li> 2832*8e3e3a7aSWarner Losh</ul> 2833*8e3e3a7aSWarner Losh 2834*8e3e3a7aSWarner Losh 2835*8e3e3a7aSWarner Losh 2836*8e3e3a7aSWarner Losh 2837*8e3e3a7aSWarner Losh<h2>4.6 – <a name="4.6">Error Handling in C</a></h2> 2838*8e3e3a7aSWarner Losh 2839*8e3e3a7aSWarner Losh<p> 2840*8e3e3a7aSWarner LoshInternally, Lua uses the C <code>longjmp</code> facility to handle errors. 2841*8e3e3a7aSWarner Losh(Lua will use exceptions if you compile it as C++; 2842*8e3e3a7aSWarner Loshsearch for <code>LUAI_THROW</code> in the source code for details.) 2843*8e3e3a7aSWarner LoshWhen Lua faces any error 2844*8e3e3a7aSWarner Losh(such as a memory allocation error or a type error) 2845*8e3e3a7aSWarner Loshit <em>raises</em> an error; 2846*8e3e3a7aSWarner Loshthat is, it does a long jump. 2847*8e3e3a7aSWarner LoshA <em>protected environment</em> uses <code>setjmp</code> 2848*8e3e3a7aSWarner Loshto set a recovery point; 2849*8e3e3a7aSWarner Loshany error jumps to the most recent active recovery point. 2850*8e3e3a7aSWarner Losh 2851*8e3e3a7aSWarner Losh 2852*8e3e3a7aSWarner Losh<p> 2853*8e3e3a7aSWarner LoshInside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>. 2854*8e3e3a7aSWarner Losh 2855*8e3e3a7aSWarner Losh 2856*8e3e3a7aSWarner Losh<p> 2857*8e3e3a7aSWarner LoshMost functions in the API can raise an error, 2858*8e3e3a7aSWarner Loshfor instance due to a memory allocation error. 2859*8e3e3a7aSWarner LoshThe documentation for each function indicates whether 2860*8e3e3a7aSWarner Loshit can raise errors. 2861*8e3e3a7aSWarner Losh 2862*8e3e3a7aSWarner Losh 2863*8e3e3a7aSWarner Losh<p> 2864*8e3e3a7aSWarner LoshIf an error happens outside any protected environment, 2865*8e3e3a7aSWarner LoshLua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) 2866*8e3e3a7aSWarner Loshand then calls <code>abort</code>, 2867*8e3e3a7aSWarner Loshthus exiting the host application. 2868*8e3e3a7aSWarner LoshYour panic function can avoid this exit by 2869*8e3e3a7aSWarner Loshnever returning 2870*8e3e3a7aSWarner Losh(e.g., doing a long jump to your own recovery point outside Lua). 2871*8e3e3a7aSWarner Losh 2872*8e3e3a7aSWarner Losh 2873*8e3e3a7aSWarner Losh<p> 2874*8e3e3a7aSWarner LoshThe panic function, 2875*8e3e3a7aSWarner Loshas its name implies, 2876*8e3e3a7aSWarner Loshis a mechanism of last resort. 2877*8e3e3a7aSWarner LoshPrograms should avoid it. 2878*8e3e3a7aSWarner LoshAs a general rule, 2879*8e3e3a7aSWarner Loshwhen a C function is called by Lua with a Lua state, 2880*8e3e3a7aSWarner Loshit can do whatever it wants on that Lua state, 2881*8e3e3a7aSWarner Loshas it should be already protected. 2882*8e3e3a7aSWarner LoshHowever, 2883*8e3e3a7aSWarner Loshwhen C code operates on other Lua states 2884*8e3e3a7aSWarner Losh(e.g., a Lua parameter to the function, 2885*8e3e3a7aSWarner Losha Lua state stored in the registry, or 2886*8e3e3a7aSWarner Loshthe result of <a href="#lua_newthread"><code>lua_newthread</code></a>), 2887*8e3e3a7aSWarner Loshit should use them only in API calls that cannot raise errors. 2888*8e3e3a7aSWarner Losh 2889*8e3e3a7aSWarner Losh 2890*8e3e3a7aSWarner Losh<p> 2891*8e3e3a7aSWarner LoshThe panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>); 2892*8e3e3a7aSWarner Loshin particular, the error object is at the top of the stack. 2893*8e3e3a7aSWarner LoshHowever, there is no guarantee about stack space. 2894*8e3e3a7aSWarner LoshTo push anything on the stack, 2895*8e3e3a7aSWarner Loshthe panic function must first check the available space (see <a href="#4.2">§4.2</a>). 2896*8e3e3a7aSWarner Losh 2897*8e3e3a7aSWarner Losh 2898*8e3e3a7aSWarner Losh 2899*8e3e3a7aSWarner Losh 2900*8e3e3a7aSWarner Losh 2901*8e3e3a7aSWarner Losh<h2>4.7 – <a name="4.7">Handling Yields in C</a></h2> 2902*8e3e3a7aSWarner Losh 2903*8e3e3a7aSWarner Losh<p> 2904*8e3e3a7aSWarner LoshInternally, Lua uses the C <code>longjmp</code> facility to yield a coroutine. 2905*8e3e3a7aSWarner LoshTherefore, if a C function <code>foo</code> calls an API function 2906*8e3e3a7aSWarner Loshand this API function yields 2907*8e3e3a7aSWarner Losh(directly or indirectly by calling another function that yields), 2908*8e3e3a7aSWarner LoshLua cannot return to <code>foo</code> any more, 2909*8e3e3a7aSWarner Loshbecause the <code>longjmp</code> removes its frame from the C stack. 2910*8e3e3a7aSWarner Losh 2911*8e3e3a7aSWarner Losh 2912*8e3e3a7aSWarner Losh<p> 2913*8e3e3a7aSWarner LoshTo avoid this kind of problem, 2914*8e3e3a7aSWarner LoshLua raises an error whenever it tries to yield across an API call, 2915*8e3e3a7aSWarner Loshexcept for three functions: 2916*8e3e3a7aSWarner 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>. 2917*8e3e3a7aSWarner LoshAll those functions receive a <em>continuation function</em> 2918*8e3e3a7aSWarner Losh(as a parameter named <code>k</code>) to continue execution after a yield. 2919*8e3e3a7aSWarner Losh 2920*8e3e3a7aSWarner Losh 2921*8e3e3a7aSWarner Losh<p> 2922*8e3e3a7aSWarner LoshWe need to set some terminology to explain continuations. 2923*8e3e3a7aSWarner LoshWe have a C function called from Lua which we will call 2924*8e3e3a7aSWarner Loshthe <em>original function</em>. 2925*8e3e3a7aSWarner LoshThis original function then calls one of those three functions in the C API, 2926*8e3e3a7aSWarner Loshwhich we will call the <em>callee function</em>, 2927*8e3e3a7aSWarner Loshthat then yields the current thread. 2928*8e3e3a7aSWarner Losh(This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 2929*8e3e3a7aSWarner 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> 2930*8e3e3a7aSWarner Loshand the function called by them yields.) 2931*8e3e3a7aSWarner Losh 2932*8e3e3a7aSWarner Losh 2933*8e3e3a7aSWarner Losh<p> 2934*8e3e3a7aSWarner LoshSuppose the running thread yields while executing the callee function. 2935*8e3e3a7aSWarner LoshAfter the thread resumes, 2936*8e3e3a7aSWarner Loshit eventually will finish running the callee function. 2937*8e3e3a7aSWarner LoshHowever, 2938*8e3e3a7aSWarner Loshthe callee function cannot return to the original function, 2939*8e3e3a7aSWarner Loshbecause its frame in the C stack was destroyed by the yield. 2940*8e3e3a7aSWarner LoshInstead, Lua calls a <em>continuation function</em>, 2941*8e3e3a7aSWarner Loshwhich was given as an argument to the callee function. 2942*8e3e3a7aSWarner LoshAs the name implies, 2943*8e3e3a7aSWarner Loshthe continuation function should continue the task 2944*8e3e3a7aSWarner Loshof the original function. 2945*8e3e3a7aSWarner Losh 2946*8e3e3a7aSWarner Losh 2947*8e3e3a7aSWarner Losh<p> 2948*8e3e3a7aSWarner LoshAs an illustration, consider the following function: 2949*8e3e3a7aSWarner Losh 2950*8e3e3a7aSWarner Losh<pre> 2951*8e3e3a7aSWarner Losh int original_function (lua_State *L) { 2952*8e3e3a7aSWarner Losh ... /* code 1 */ 2953*8e3e3a7aSWarner Losh status = lua_pcall(L, n, m, h); /* calls Lua */ 2954*8e3e3a7aSWarner Losh ... /* code 2 */ 2955*8e3e3a7aSWarner Losh } 2956*8e3e3a7aSWarner Losh</pre><p> 2957*8e3e3a7aSWarner LoshNow we want to allow 2958*8e3e3a7aSWarner Loshthe Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield. 2959*8e3e3a7aSWarner LoshFirst, we can rewrite our function like here: 2960*8e3e3a7aSWarner Losh 2961*8e3e3a7aSWarner Losh<pre> 2962*8e3e3a7aSWarner Losh int k (lua_State *L, int status, lua_KContext ctx) { 2963*8e3e3a7aSWarner Losh ... /* code 2 */ 2964*8e3e3a7aSWarner Losh } 2965*8e3e3a7aSWarner Losh 2966*8e3e3a7aSWarner Losh int original_function (lua_State *L) { 2967*8e3e3a7aSWarner Losh ... /* code 1 */ 2968*8e3e3a7aSWarner Losh return k(L, lua_pcall(L, n, m, h), ctx); 2969*8e3e3a7aSWarner Losh } 2970*8e3e3a7aSWarner Losh</pre><p> 2971*8e3e3a7aSWarner LoshIn the above code, 2972*8e3e3a7aSWarner Loshthe new function <code>k</code> is a 2973*8e3e3a7aSWarner Losh<em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>), 2974*8e3e3a7aSWarner Loshwhich should do all the work that the original function 2975*8e3e3a7aSWarner Loshwas doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>. 2976*8e3e3a7aSWarner LoshNow, we must inform Lua that it must call <code>k</code> if the Lua code 2977*8e3e3a7aSWarner Loshbeing executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way 2978*8e3e3a7aSWarner Losh(errors or yielding), 2979*8e3e3a7aSWarner Loshso we rewrite the code as here, 2980*8e3e3a7aSWarner Loshreplacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>: 2981*8e3e3a7aSWarner Losh 2982*8e3e3a7aSWarner Losh<pre> 2983*8e3e3a7aSWarner Losh int original_function (lua_State *L) { 2984*8e3e3a7aSWarner Losh ... /* code 1 */ 2985*8e3e3a7aSWarner Losh return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1); 2986*8e3e3a7aSWarner Losh } 2987*8e3e3a7aSWarner Losh</pre><p> 2988*8e3e3a7aSWarner LoshNote the external, explicit call to the continuation: 2989*8e3e3a7aSWarner LoshLua will call the continuation only if needed, that is, 2990*8e3e3a7aSWarner Loshin case of errors or resuming after a yield. 2991*8e3e3a7aSWarner LoshIf the called function returns normally without ever yielding, 2992*8e3e3a7aSWarner Losh<a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally. 2993*8e3e3a7aSWarner Losh(Of course, instead of calling the continuation in that case, 2994*8e3e3a7aSWarner Loshyou can do the equivalent work directly inside the original function.) 2995*8e3e3a7aSWarner Losh 2996*8e3e3a7aSWarner Losh 2997*8e3e3a7aSWarner Losh<p> 2998*8e3e3a7aSWarner LoshBesides the Lua state, 2999*8e3e3a7aSWarner Loshthe continuation function has two other parameters: 3000*8e3e3a7aSWarner Loshthe final status of the call plus the context value (<code>ctx</code>) that 3001*8e3e3a7aSWarner Loshwas passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>. 3002*8e3e3a7aSWarner Losh(Lua does not use this context value; 3003*8e3e3a7aSWarner Loshit only passes this value from the original function to the 3004*8e3e3a7aSWarner Loshcontinuation function.) 3005*8e3e3a7aSWarner LoshFor <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 3006*8e3e3a7aSWarner Loshthe status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 3007*8e3e3a7aSWarner Loshexcept that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield 3008*8e3e3a7aSWarner Losh(instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>). 3009*8e3e3a7aSWarner LoshFor <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>, 3010*8e3e3a7aSWarner Loshthe status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation. 3011*8e3e3a7aSWarner Losh(For these two functions, 3012*8e3e3a7aSWarner LoshLua will not call the continuation in case of errors, 3013*8e3e3a7aSWarner Loshbecause they do not handle errors.) 3014*8e3e3a7aSWarner LoshSimilarly, when using <a href="#lua_callk"><code>lua_callk</code></a>, 3015*8e3e3a7aSWarner Loshyou should call the continuation function 3016*8e3e3a7aSWarner Loshwith <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status. 3017*8e3e3a7aSWarner Losh(For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling 3018*8e3e3a7aSWarner Loshdirectly the continuation function, 3019*8e3e3a7aSWarner Loshbecause <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.) 3020*8e3e3a7aSWarner Losh 3021*8e3e3a7aSWarner Losh 3022*8e3e3a7aSWarner Losh<p> 3023*8e3e3a7aSWarner LoshLua treats the continuation function as if it were the original function. 3024*8e3e3a7aSWarner LoshThe continuation function receives the same Lua stack 3025*8e3e3a7aSWarner Loshfrom the original function, 3026*8e3e3a7aSWarner Loshin the same state it would be if the callee function had returned. 3027*8e3e3a7aSWarner Losh(For instance, 3028*8e3e3a7aSWarner Loshafter a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are 3029*8e3e3a7aSWarner Loshremoved from the stack and replaced by the results from the call.) 3030*8e3e3a7aSWarner LoshIt also has the same upvalues. 3031*8e3e3a7aSWarner LoshWhatever it returns is handled by Lua as if it were the return 3032*8e3e3a7aSWarner Loshof the original function. 3033*8e3e3a7aSWarner Losh 3034*8e3e3a7aSWarner Losh 3035*8e3e3a7aSWarner Losh 3036*8e3e3a7aSWarner Losh 3037*8e3e3a7aSWarner Losh 3038*8e3e3a7aSWarner Losh<h2>4.8 – <a name="4.8">Functions and Types</a></h2> 3039*8e3e3a7aSWarner Losh 3040*8e3e3a7aSWarner Losh<p> 3041*8e3e3a7aSWarner LoshHere we list all functions and types from the C API in 3042*8e3e3a7aSWarner Loshalphabetical order. 3043*8e3e3a7aSWarner LoshEach function has an indicator like this: 3044*8e3e3a7aSWarner Losh<span class="apii">[-o, +p, <em>x</em>]</span> 3045*8e3e3a7aSWarner Losh 3046*8e3e3a7aSWarner Losh 3047*8e3e3a7aSWarner Losh<p> 3048*8e3e3a7aSWarner LoshThe first field, <code>o</code>, 3049*8e3e3a7aSWarner Loshis how many elements the function pops from the stack. 3050*8e3e3a7aSWarner LoshThe second field, <code>p</code>, 3051*8e3e3a7aSWarner Loshis how many elements the function pushes onto the stack. 3052*8e3e3a7aSWarner Losh(Any function always pushes its results after popping its arguments.) 3053*8e3e3a7aSWarner LoshA field in the form <code>x|y</code> means the function can push (or pop) 3054*8e3e3a7aSWarner Losh<code>x</code> or <code>y</code> elements, 3055*8e3e3a7aSWarner Loshdepending on the situation; 3056*8e3e3a7aSWarner Loshan interrogation mark '<code>?</code>' means that 3057*8e3e3a7aSWarner Loshwe cannot know how many elements the function pops/pushes 3058*8e3e3a7aSWarner Loshby looking only at its arguments 3059*8e3e3a7aSWarner Losh(e.g., they may depend on what is on the stack). 3060*8e3e3a7aSWarner LoshThe third field, <code>x</code>, 3061*8e3e3a7aSWarner Loshtells whether the function may raise errors: 3062*8e3e3a7aSWarner Losh'<code>-</code>' means the function never raises any error; 3063*8e3e3a7aSWarner Losh'<code>m</code>' means the function may raise out-of-memory errors 3064*8e3e3a7aSWarner Loshand errors running a <code>__gc</code> metamethod; 3065*8e3e3a7aSWarner Losh'<code>e</code>' means the function may raise any errors 3066*8e3e3a7aSWarner Losh(it can run arbitrary Lua code, 3067*8e3e3a7aSWarner Losheither directly or through metamethods); 3068*8e3e3a7aSWarner Losh'<code>v</code>' means the function may raise an error on purpose. 3069*8e3e3a7aSWarner Losh 3070*8e3e3a7aSWarner Losh 3071*8e3e3a7aSWarner Losh 3072*8e3e3a7aSWarner Losh<hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p> 3073*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3074*8e3e3a7aSWarner Losh<pre>int lua_absindex (lua_State *L, int idx);</pre> 3075*8e3e3a7aSWarner Losh 3076*8e3e3a7aSWarner Losh<p> 3077*8e3e3a7aSWarner LoshConverts the acceptable index <code>idx</code> 3078*8e3e3a7aSWarner Loshinto an equivalent absolute index 3079*8e3e3a7aSWarner Losh(that is, one that does not depend on the stack top). 3080*8e3e3a7aSWarner Losh 3081*8e3e3a7aSWarner Losh 3082*8e3e3a7aSWarner Losh 3083*8e3e3a7aSWarner Losh 3084*8e3e3a7aSWarner Losh 3085*8e3e3a7aSWarner Losh<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> 3086*8e3e3a7aSWarner Losh<pre>typedef void * (*lua_Alloc) (void *ud, 3087*8e3e3a7aSWarner Losh void *ptr, 3088*8e3e3a7aSWarner Losh size_t osize, 3089*8e3e3a7aSWarner Losh size_t nsize);</pre> 3090*8e3e3a7aSWarner Losh 3091*8e3e3a7aSWarner Losh<p> 3092*8e3e3a7aSWarner LoshThe type of the memory-allocation function used by Lua states. 3093*8e3e3a7aSWarner LoshThe allocator function must provide a 3094*8e3e3a7aSWarner Loshfunctionality similar to <code>realloc</code>, 3095*8e3e3a7aSWarner Loshbut not exactly the same. 3096*8e3e3a7aSWarner LoshIts arguments are 3097*8e3e3a7aSWarner Losh<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; 3098*8e3e3a7aSWarner Losh<code>ptr</code>, a pointer to the block being allocated/reallocated/freed; 3099*8e3e3a7aSWarner Losh<code>osize</code>, the original size of the block or some code about what 3100*8e3e3a7aSWarner Loshis being allocated; 3101*8e3e3a7aSWarner Loshand <code>nsize</code>, the new size of the block. 3102*8e3e3a7aSWarner Losh 3103*8e3e3a7aSWarner Losh 3104*8e3e3a7aSWarner Losh<p> 3105*8e3e3a7aSWarner LoshWhen <code>ptr</code> is not <code>NULL</code>, 3106*8e3e3a7aSWarner Losh<code>osize</code> is the size of the block pointed by <code>ptr</code>, 3107*8e3e3a7aSWarner Loshthat is, the size given when it was allocated or reallocated. 3108*8e3e3a7aSWarner Losh 3109*8e3e3a7aSWarner Losh 3110*8e3e3a7aSWarner Losh<p> 3111*8e3e3a7aSWarner LoshWhen <code>ptr</code> is <code>NULL</code>, 3112*8e3e3a7aSWarner Losh<code>osize</code> encodes the kind of object that Lua is allocating. 3113*8e3e3a7aSWarner Losh<code>osize</code> is any of 3114*8e3e3a7aSWarner 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>, 3115*8e3e3a7aSWarner 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) 3116*8e3e3a7aSWarner LoshLua is creating a new object of that type. 3117*8e3e3a7aSWarner LoshWhen <code>osize</code> is some other value, 3118*8e3e3a7aSWarner LoshLua is allocating memory for something else. 3119*8e3e3a7aSWarner Losh 3120*8e3e3a7aSWarner Losh 3121*8e3e3a7aSWarner Losh<p> 3122*8e3e3a7aSWarner LoshLua assumes the following behavior from the allocator function: 3123*8e3e3a7aSWarner Losh 3124*8e3e3a7aSWarner Losh 3125*8e3e3a7aSWarner Losh<p> 3126*8e3e3a7aSWarner LoshWhen <code>nsize</code> is zero, 3127*8e3e3a7aSWarner Loshthe allocator must behave like <code>free</code> 3128*8e3e3a7aSWarner Loshand return <code>NULL</code>. 3129*8e3e3a7aSWarner Losh 3130*8e3e3a7aSWarner Losh 3131*8e3e3a7aSWarner Losh<p> 3132*8e3e3a7aSWarner LoshWhen <code>nsize</code> is not zero, 3133*8e3e3a7aSWarner Loshthe allocator must behave like <code>realloc</code>. 3134*8e3e3a7aSWarner LoshThe allocator returns <code>NULL</code> 3135*8e3e3a7aSWarner Loshif and only if it cannot fulfill the request. 3136*8e3e3a7aSWarner LoshLua assumes that the allocator never fails when 3137*8e3e3a7aSWarner Losh<code>osize >= nsize</code>. 3138*8e3e3a7aSWarner Losh 3139*8e3e3a7aSWarner Losh 3140*8e3e3a7aSWarner Losh<p> 3141*8e3e3a7aSWarner LoshHere is a simple implementation for the allocator function. 3142*8e3e3a7aSWarner LoshIt is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. 3143*8e3e3a7aSWarner Losh 3144*8e3e3a7aSWarner Losh<pre> 3145*8e3e3a7aSWarner Losh static void *l_alloc (void *ud, void *ptr, size_t osize, 3146*8e3e3a7aSWarner Losh size_t nsize) { 3147*8e3e3a7aSWarner Losh (void)ud; (void)osize; /* not used */ 3148*8e3e3a7aSWarner Losh if (nsize == 0) { 3149*8e3e3a7aSWarner Losh free(ptr); 3150*8e3e3a7aSWarner Losh return NULL; 3151*8e3e3a7aSWarner Losh } 3152*8e3e3a7aSWarner Losh else 3153*8e3e3a7aSWarner Losh return realloc(ptr, nsize); 3154*8e3e3a7aSWarner Losh } 3155*8e3e3a7aSWarner Losh</pre><p> 3156*8e3e3a7aSWarner LoshNote that Standard C ensures 3157*8e3e3a7aSWarner Loshthat <code>free(NULL)</code> has no effect and that 3158*8e3e3a7aSWarner Losh<code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>. 3159*8e3e3a7aSWarner LoshThis code assumes that <code>realloc</code> does not fail when shrinking a block. 3160*8e3e3a7aSWarner Losh(Although Standard C does not ensure this behavior, 3161*8e3e3a7aSWarner Loshit seems to be a safe assumption.) 3162*8e3e3a7aSWarner Losh 3163*8e3e3a7aSWarner Losh 3164*8e3e3a7aSWarner Losh 3165*8e3e3a7aSWarner Losh 3166*8e3e3a7aSWarner Losh 3167*8e3e3a7aSWarner Losh<hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p> 3168*8e3e3a7aSWarner Losh<span class="apii">[-(2|1), +1, <em>e</em>]</span> 3169*8e3e3a7aSWarner Losh<pre>void lua_arith (lua_State *L, int op);</pre> 3170*8e3e3a7aSWarner Losh 3171*8e3e3a7aSWarner Losh<p> 3172*8e3e3a7aSWarner LoshPerforms an arithmetic or bitwise operation over the two values 3173*8e3e3a7aSWarner Losh(or one, in the case of negations) 3174*8e3e3a7aSWarner Loshat the top of the stack, 3175*8e3e3a7aSWarner Loshwith the value at the top being the second operand, 3176*8e3e3a7aSWarner Loshpops these values, and pushes the result of the operation. 3177*8e3e3a7aSWarner LoshThe function follows the semantics of the corresponding Lua operator 3178*8e3e3a7aSWarner Losh(that is, it may call metamethods). 3179*8e3e3a7aSWarner Losh 3180*8e3e3a7aSWarner Losh 3181*8e3e3a7aSWarner Losh<p> 3182*8e3e3a7aSWarner LoshThe value of <code>op</code> must be one of the following constants: 3183*8e3e3a7aSWarner Losh 3184*8e3e3a7aSWarner Losh<ul> 3185*8e3e3a7aSWarner Losh 3186*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li> 3187*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li> 3188*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li> 3189*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li> 3190*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li> 3191*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li> 3192*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li> 3193*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li> 3194*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li> 3195*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&</code>)</li> 3196*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li> 3197*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li> 3198*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li> 3199*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li> 3200*8e3e3a7aSWarner Losh 3201*8e3e3a7aSWarner Losh</ul> 3202*8e3e3a7aSWarner Losh 3203*8e3e3a7aSWarner Losh 3204*8e3e3a7aSWarner Losh 3205*8e3e3a7aSWarner Losh 3206*8e3e3a7aSWarner Losh<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> 3207*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3208*8e3e3a7aSWarner Losh<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> 3209*8e3e3a7aSWarner Losh 3210*8e3e3a7aSWarner Losh<p> 3211*8e3e3a7aSWarner LoshSets a new panic function and returns the old one (see <a href="#4.6">§4.6</a>). 3212*8e3e3a7aSWarner Losh 3213*8e3e3a7aSWarner Losh 3214*8e3e3a7aSWarner Losh 3215*8e3e3a7aSWarner Losh 3216*8e3e3a7aSWarner Losh 3217*8e3e3a7aSWarner Losh<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> 3218*8e3e3a7aSWarner Losh<span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span> 3219*8e3e3a7aSWarner Losh<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> 3220*8e3e3a7aSWarner Losh 3221*8e3e3a7aSWarner Losh<p> 3222*8e3e3a7aSWarner LoshCalls a function. 3223*8e3e3a7aSWarner Losh 3224*8e3e3a7aSWarner Losh 3225*8e3e3a7aSWarner Losh<p> 3226*8e3e3a7aSWarner LoshTo call a function you must use the following protocol: 3227*8e3e3a7aSWarner Loshfirst, the function to be called is pushed onto the stack; 3228*8e3e3a7aSWarner Loshthen, the arguments to the function are pushed 3229*8e3e3a7aSWarner Loshin direct order; 3230*8e3e3a7aSWarner Loshthat is, the first argument is pushed first. 3231*8e3e3a7aSWarner LoshFinally you call <a href="#lua_call"><code>lua_call</code></a>; 3232*8e3e3a7aSWarner Losh<code>nargs</code> is the number of arguments that you pushed onto the stack. 3233*8e3e3a7aSWarner LoshAll arguments and the function value are popped from the stack 3234*8e3e3a7aSWarner Loshwhen the function is called. 3235*8e3e3a7aSWarner LoshThe function results are pushed onto the stack when the function returns. 3236*8e3e3a7aSWarner LoshThe number of results is adjusted to <code>nresults</code>, 3237*8e3e3a7aSWarner Loshunless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. 3238*8e3e3a7aSWarner LoshIn this case, all results from the function are pushed; 3239*8e3e3a7aSWarner LoshLua takes care that the returned values fit into the stack space, 3240*8e3e3a7aSWarner Loshbut it does not ensure any extra space in the stack. 3241*8e3e3a7aSWarner LoshThe function results are pushed onto the stack in direct order 3242*8e3e3a7aSWarner Losh(the first result is pushed first), 3243*8e3e3a7aSWarner Loshso that after the call the last result is on the top of the stack. 3244*8e3e3a7aSWarner Losh 3245*8e3e3a7aSWarner Losh 3246*8e3e3a7aSWarner Losh<p> 3247*8e3e3a7aSWarner LoshAny error inside the called function is propagated upwards 3248*8e3e3a7aSWarner Losh(with a <code>longjmp</code>). 3249*8e3e3a7aSWarner Losh 3250*8e3e3a7aSWarner Losh 3251*8e3e3a7aSWarner Losh<p> 3252*8e3e3a7aSWarner LoshThe following example shows how the host program can do the 3253*8e3e3a7aSWarner Loshequivalent to this Lua code: 3254*8e3e3a7aSWarner Losh 3255*8e3e3a7aSWarner Losh<pre> 3256*8e3e3a7aSWarner Losh a = f("how", t.x, 14) 3257*8e3e3a7aSWarner Losh</pre><p> 3258*8e3e3a7aSWarner LoshHere it is in C: 3259*8e3e3a7aSWarner Losh 3260*8e3e3a7aSWarner Losh<pre> 3261*8e3e3a7aSWarner Losh lua_getglobal(L, "f"); /* function to be called */ 3262*8e3e3a7aSWarner Losh lua_pushliteral(L, "how"); /* 1st argument */ 3263*8e3e3a7aSWarner Losh lua_getglobal(L, "t"); /* table to be indexed */ 3264*8e3e3a7aSWarner Losh lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 3265*8e3e3a7aSWarner Losh lua_remove(L, -2); /* remove 't' from the stack */ 3266*8e3e3a7aSWarner Losh lua_pushinteger(L, 14); /* 3rd argument */ 3267*8e3e3a7aSWarner Losh lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ 3268*8e3e3a7aSWarner Losh lua_setglobal(L, "a"); /* set global 'a' */ 3269*8e3e3a7aSWarner Losh</pre><p> 3270*8e3e3a7aSWarner LoshNote that the code above is <em>balanced</em>: 3271*8e3e3a7aSWarner Loshat its end, the stack is back to its original configuration. 3272*8e3e3a7aSWarner LoshThis is considered good programming practice. 3273*8e3e3a7aSWarner Losh 3274*8e3e3a7aSWarner Losh 3275*8e3e3a7aSWarner Losh 3276*8e3e3a7aSWarner Losh 3277*8e3e3a7aSWarner Losh 3278*8e3e3a7aSWarner Losh<hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p> 3279*8e3e3a7aSWarner Losh<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> 3280*8e3e3a7aSWarner Losh<pre>void lua_callk (lua_State *L, 3281*8e3e3a7aSWarner Losh int nargs, 3282*8e3e3a7aSWarner Losh int nresults, 3283*8e3e3a7aSWarner Losh lua_KContext ctx, 3284*8e3e3a7aSWarner Losh lua_KFunction k);</pre> 3285*8e3e3a7aSWarner Losh 3286*8e3e3a7aSWarner Losh<p> 3287*8e3e3a7aSWarner LoshThis function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>, 3288*8e3e3a7aSWarner Loshbut allows the called function to yield (see <a href="#4.7">§4.7</a>). 3289*8e3e3a7aSWarner Losh 3290*8e3e3a7aSWarner Losh 3291*8e3e3a7aSWarner Losh 3292*8e3e3a7aSWarner Losh 3293*8e3e3a7aSWarner Losh 3294*8e3e3a7aSWarner Losh<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> 3295*8e3e3a7aSWarner Losh<pre>typedef int (*lua_CFunction) (lua_State *L);</pre> 3296*8e3e3a7aSWarner Losh 3297*8e3e3a7aSWarner Losh<p> 3298*8e3e3a7aSWarner LoshType for C functions. 3299*8e3e3a7aSWarner Losh 3300*8e3e3a7aSWarner Losh 3301*8e3e3a7aSWarner Losh<p> 3302*8e3e3a7aSWarner LoshIn order to communicate properly with Lua, 3303*8e3e3a7aSWarner Losha C function must use the following protocol, 3304*8e3e3a7aSWarner Loshwhich defines the way parameters and results are passed: 3305*8e3e3a7aSWarner Losha C function receives its arguments from Lua in its stack 3306*8e3e3a7aSWarner Loshin direct order (the first argument is pushed first). 3307*8e3e3a7aSWarner LoshSo, when the function starts, 3308*8e3e3a7aSWarner Losh<code>lua_gettop(L)</code> returns the number of arguments received by the function. 3309*8e3e3a7aSWarner LoshThe first argument (if any) is at index 1 3310*8e3e3a7aSWarner Loshand its last argument is at index <code>lua_gettop(L)</code>. 3311*8e3e3a7aSWarner LoshTo return values to Lua, a C function just pushes them onto the stack, 3312*8e3e3a7aSWarner Loshin direct order (the first result is pushed first), 3313*8e3e3a7aSWarner Loshand returns the number of results. 3314*8e3e3a7aSWarner LoshAny other value in the stack below the results will be properly 3315*8e3e3a7aSWarner Loshdiscarded by Lua. 3316*8e3e3a7aSWarner LoshLike a Lua function, a C function called by Lua can also return 3317*8e3e3a7aSWarner Loshmany results. 3318*8e3e3a7aSWarner Losh 3319*8e3e3a7aSWarner Losh 3320*8e3e3a7aSWarner Losh<p> 3321*8e3e3a7aSWarner LoshAs an example, the following function receives a variable number 3322*8e3e3a7aSWarner Loshof numeric arguments and returns their average and their sum: 3323*8e3e3a7aSWarner Losh 3324*8e3e3a7aSWarner Losh<pre> 3325*8e3e3a7aSWarner Losh static int foo (lua_State *L) { 3326*8e3e3a7aSWarner Losh int n = lua_gettop(L); /* number of arguments */ 3327*8e3e3a7aSWarner Losh lua_Number sum = 0.0; 3328*8e3e3a7aSWarner Losh int i; 3329*8e3e3a7aSWarner Losh for (i = 1; i <= n; i++) { 3330*8e3e3a7aSWarner Losh if (!lua_isnumber(L, i)) { 3331*8e3e3a7aSWarner Losh lua_pushliteral(L, "incorrect argument"); 3332*8e3e3a7aSWarner Losh lua_error(L); 3333*8e3e3a7aSWarner Losh } 3334*8e3e3a7aSWarner Losh sum += lua_tonumber(L, i); 3335*8e3e3a7aSWarner Losh } 3336*8e3e3a7aSWarner Losh lua_pushnumber(L, sum/n); /* first result */ 3337*8e3e3a7aSWarner Losh lua_pushnumber(L, sum); /* second result */ 3338*8e3e3a7aSWarner Losh return 2; /* number of results */ 3339*8e3e3a7aSWarner Losh } 3340*8e3e3a7aSWarner Losh</pre> 3341*8e3e3a7aSWarner Losh 3342*8e3e3a7aSWarner Losh 3343*8e3e3a7aSWarner Losh 3344*8e3e3a7aSWarner Losh 3345*8e3e3a7aSWarner Losh<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> 3346*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3347*8e3e3a7aSWarner Losh<pre>int lua_checkstack (lua_State *L, int n);</pre> 3348*8e3e3a7aSWarner Losh 3349*8e3e3a7aSWarner Losh<p> 3350*8e3e3a7aSWarner LoshEnsures that the stack has space for at least <code>n</code> extra slots 3351*8e3e3a7aSWarner Losh(that is, that you can safely push up to <code>n</code> values into it). 3352*8e3e3a7aSWarner LoshIt returns false if it cannot fulfill the request, 3353*8e3e3a7aSWarner Losheither because it would cause the stack 3354*8e3e3a7aSWarner Loshto be larger than a fixed maximum size 3355*8e3e3a7aSWarner Losh(typically at least several thousand elements) or 3356*8e3e3a7aSWarner Loshbecause it cannot allocate memory for the extra space. 3357*8e3e3a7aSWarner LoshThis function never shrinks the stack; 3358*8e3e3a7aSWarner Loshif the stack already has space for the extra slots, 3359*8e3e3a7aSWarner Loshit is left unchanged. 3360*8e3e3a7aSWarner Losh 3361*8e3e3a7aSWarner Losh 3362*8e3e3a7aSWarner Losh 3363*8e3e3a7aSWarner Losh 3364*8e3e3a7aSWarner Losh 3365*8e3e3a7aSWarner Losh<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> 3366*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3367*8e3e3a7aSWarner Losh<pre>void lua_close (lua_State *L);</pre> 3368*8e3e3a7aSWarner Losh 3369*8e3e3a7aSWarner Losh<p> 3370*8e3e3a7aSWarner LoshDestroys all objects in the given Lua state 3371*8e3e3a7aSWarner Losh(calling the corresponding garbage-collection metamethods, if any) 3372*8e3e3a7aSWarner Loshand frees all dynamic memory used by this state. 3373*8e3e3a7aSWarner LoshOn several platforms, you may not need to call this function, 3374*8e3e3a7aSWarner Loshbecause all resources are naturally released when the host program ends. 3375*8e3e3a7aSWarner LoshOn the other hand, long-running programs that create multiple states, 3376*8e3e3a7aSWarner Loshsuch as daemons or web servers, 3377*8e3e3a7aSWarner Loshwill probably need to close states as soon as they are not needed. 3378*8e3e3a7aSWarner Losh 3379*8e3e3a7aSWarner Losh 3380*8e3e3a7aSWarner Losh 3381*8e3e3a7aSWarner Losh 3382*8e3e3a7aSWarner Losh 3383*8e3e3a7aSWarner Losh<hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p> 3384*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 3385*8e3e3a7aSWarner Losh<pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre> 3386*8e3e3a7aSWarner Losh 3387*8e3e3a7aSWarner Losh<p> 3388*8e3e3a7aSWarner LoshCompares two Lua values. 3389*8e3e3a7aSWarner LoshReturns 1 if the value at index <code>index1</code> satisfies <code>op</code> 3390*8e3e3a7aSWarner Loshwhen compared with the value at index <code>index2</code>, 3391*8e3e3a7aSWarner Loshfollowing the semantics of the corresponding Lua operator 3392*8e3e3a7aSWarner Losh(that is, it may call metamethods). 3393*8e3e3a7aSWarner LoshOtherwise returns 0. 3394*8e3e3a7aSWarner LoshAlso returns 0 if any of the indices is not valid. 3395*8e3e3a7aSWarner Losh 3396*8e3e3a7aSWarner Losh 3397*8e3e3a7aSWarner Losh<p> 3398*8e3e3a7aSWarner LoshThe value of <code>op</code> must be one of the following constants: 3399*8e3e3a7aSWarner Losh 3400*8e3e3a7aSWarner Losh<ul> 3401*8e3e3a7aSWarner Losh 3402*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li> 3403*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li> 3404*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li> 3405*8e3e3a7aSWarner Losh 3406*8e3e3a7aSWarner Losh</ul> 3407*8e3e3a7aSWarner Losh 3408*8e3e3a7aSWarner Losh 3409*8e3e3a7aSWarner Losh 3410*8e3e3a7aSWarner Losh 3411*8e3e3a7aSWarner Losh<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> 3412*8e3e3a7aSWarner Losh<span class="apii">[-n, +1, <em>e</em>]</span> 3413*8e3e3a7aSWarner Losh<pre>void lua_concat (lua_State *L, int n);</pre> 3414*8e3e3a7aSWarner Losh 3415*8e3e3a7aSWarner Losh<p> 3416*8e3e3a7aSWarner LoshConcatenates the <code>n</code> values at the top of the stack, 3417*8e3e3a7aSWarner Loshpops them, and leaves the result at the top. 3418*8e3e3a7aSWarner LoshIf <code>n</code> is 1, the result is the single value on the stack 3419*8e3e3a7aSWarner Losh(that is, the function does nothing); 3420*8e3e3a7aSWarner Loshif <code>n</code> is 0, the result is the empty string. 3421*8e3e3a7aSWarner LoshConcatenation is performed following the usual semantics of Lua 3422*8e3e3a7aSWarner Losh(see <a href="#3.4.6">§3.4.6</a>). 3423*8e3e3a7aSWarner Losh 3424*8e3e3a7aSWarner Losh 3425*8e3e3a7aSWarner Losh 3426*8e3e3a7aSWarner Losh 3427*8e3e3a7aSWarner Losh 3428*8e3e3a7aSWarner Losh<hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p> 3429*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3430*8e3e3a7aSWarner Losh<pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre> 3431*8e3e3a7aSWarner Losh 3432*8e3e3a7aSWarner Losh<p> 3433*8e3e3a7aSWarner LoshCopies the element at index <code>fromidx</code> 3434*8e3e3a7aSWarner Loshinto the valid index <code>toidx</code>, 3435*8e3e3a7aSWarner Loshreplacing the value at that position. 3436*8e3e3a7aSWarner LoshValues at other positions are not affected. 3437*8e3e3a7aSWarner Losh 3438*8e3e3a7aSWarner Losh 3439*8e3e3a7aSWarner Losh 3440*8e3e3a7aSWarner Losh 3441*8e3e3a7aSWarner Losh 3442*8e3e3a7aSWarner Losh<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> 3443*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 3444*8e3e3a7aSWarner Losh<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> 3445*8e3e3a7aSWarner Losh 3446*8e3e3a7aSWarner Losh<p> 3447*8e3e3a7aSWarner LoshCreates a new empty table and pushes it onto the stack. 3448*8e3e3a7aSWarner LoshParameter <code>narr</code> is a hint for how many elements the table 3449*8e3e3a7aSWarner Loshwill have as a sequence; 3450*8e3e3a7aSWarner Loshparameter <code>nrec</code> is a hint for how many other elements 3451*8e3e3a7aSWarner Loshthe table will have. 3452*8e3e3a7aSWarner LoshLua may use these hints to preallocate memory for the new table. 3453*8e3e3a7aSWarner LoshThis preallocation is useful for performance when you know in advance 3454*8e3e3a7aSWarner Loshhow many elements the table will have. 3455*8e3e3a7aSWarner LoshOtherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. 3456*8e3e3a7aSWarner Losh 3457*8e3e3a7aSWarner Losh 3458*8e3e3a7aSWarner Losh 3459*8e3e3a7aSWarner Losh 3460*8e3e3a7aSWarner Losh 3461*8e3e3a7aSWarner Losh<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> 3462*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3463*8e3e3a7aSWarner Losh<pre>int lua_dump (lua_State *L, 3464*8e3e3a7aSWarner Losh lua_Writer writer, 3465*8e3e3a7aSWarner Losh void *data, 3466*8e3e3a7aSWarner Losh int strip);</pre> 3467*8e3e3a7aSWarner Losh 3468*8e3e3a7aSWarner Losh<p> 3469*8e3e3a7aSWarner LoshDumps a function as a binary chunk. 3470*8e3e3a7aSWarner LoshReceives a Lua function on the top of the stack 3471*8e3e3a7aSWarner Loshand produces a binary chunk that, 3472*8e3e3a7aSWarner Loshif loaded again, 3473*8e3e3a7aSWarner Loshresults in a function equivalent to the one dumped. 3474*8e3e3a7aSWarner LoshAs it produces parts of the chunk, 3475*8e3e3a7aSWarner 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>) 3476*8e3e3a7aSWarner Loshwith the given <code>data</code> 3477*8e3e3a7aSWarner Loshto write them. 3478*8e3e3a7aSWarner Losh 3479*8e3e3a7aSWarner Losh 3480*8e3e3a7aSWarner Losh<p> 3481*8e3e3a7aSWarner LoshIf <code>strip</code> is true, 3482*8e3e3a7aSWarner Loshthe binary representation may not include all debug information 3483*8e3e3a7aSWarner Loshabout the function, 3484*8e3e3a7aSWarner Loshto save space. 3485*8e3e3a7aSWarner Losh 3486*8e3e3a7aSWarner Losh 3487*8e3e3a7aSWarner Losh<p> 3488*8e3e3a7aSWarner LoshThe value returned is the error code returned by the last 3489*8e3e3a7aSWarner Loshcall to the writer; 3490*8e3e3a7aSWarner Losh0 means no errors. 3491*8e3e3a7aSWarner Losh 3492*8e3e3a7aSWarner Losh 3493*8e3e3a7aSWarner Losh<p> 3494*8e3e3a7aSWarner LoshThis function does not pop the Lua function from the stack. 3495*8e3e3a7aSWarner Losh 3496*8e3e3a7aSWarner Losh 3497*8e3e3a7aSWarner Losh 3498*8e3e3a7aSWarner Losh 3499*8e3e3a7aSWarner Losh 3500*8e3e3a7aSWarner Losh<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> 3501*8e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>v</em>]</span> 3502*8e3e3a7aSWarner Losh<pre>int lua_error (lua_State *L);</pre> 3503*8e3e3a7aSWarner Losh 3504*8e3e3a7aSWarner Losh<p> 3505*8e3e3a7aSWarner LoshGenerates a Lua error, 3506*8e3e3a7aSWarner Loshusing the value at the top of the stack as the error object. 3507*8e3e3a7aSWarner LoshThis function does a long jump, 3508*8e3e3a7aSWarner Loshand therefore never returns 3509*8e3e3a7aSWarner Losh(see <a href="#luaL_error"><code>luaL_error</code></a>). 3510*8e3e3a7aSWarner Losh 3511*8e3e3a7aSWarner Losh 3512*8e3e3a7aSWarner Losh 3513*8e3e3a7aSWarner Losh 3514*8e3e3a7aSWarner Losh 3515*8e3e3a7aSWarner Losh<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> 3516*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span> 3517*8e3e3a7aSWarner Losh<pre>int lua_gc (lua_State *L, int what, int data);</pre> 3518*8e3e3a7aSWarner Losh 3519*8e3e3a7aSWarner Losh<p> 3520*8e3e3a7aSWarner LoshControls the garbage collector. 3521*8e3e3a7aSWarner Losh 3522*8e3e3a7aSWarner Losh 3523*8e3e3a7aSWarner Losh<p> 3524*8e3e3a7aSWarner LoshThis function performs several tasks, 3525*8e3e3a7aSWarner Loshaccording to the value of the parameter <code>what</code>: 3526*8e3e3a7aSWarner Losh 3527*8e3e3a7aSWarner Losh<ul> 3528*8e3e3a7aSWarner Losh 3529*8e3e3a7aSWarner Losh<li><b><code>LUA_GCSTOP</code>: </b> 3530*8e3e3a7aSWarner Loshstops the garbage collector. 3531*8e3e3a7aSWarner Losh</li> 3532*8e3e3a7aSWarner Losh 3533*8e3e3a7aSWarner Losh<li><b><code>LUA_GCRESTART</code>: </b> 3534*8e3e3a7aSWarner Loshrestarts the garbage collector. 3535*8e3e3a7aSWarner Losh</li> 3536*8e3e3a7aSWarner Losh 3537*8e3e3a7aSWarner Losh<li><b><code>LUA_GCCOLLECT</code>: </b> 3538*8e3e3a7aSWarner Loshperforms a full garbage-collection cycle. 3539*8e3e3a7aSWarner Losh</li> 3540*8e3e3a7aSWarner Losh 3541*8e3e3a7aSWarner Losh<li><b><code>LUA_GCCOUNT</code>: </b> 3542*8e3e3a7aSWarner Loshreturns the current amount of memory (in Kbytes) in use by Lua. 3543*8e3e3a7aSWarner Losh</li> 3544*8e3e3a7aSWarner Losh 3545*8e3e3a7aSWarner Losh<li><b><code>LUA_GCCOUNTB</code>: </b> 3546*8e3e3a7aSWarner Loshreturns the remainder of dividing the current amount of bytes of 3547*8e3e3a7aSWarner Loshmemory in use by Lua by 1024. 3548*8e3e3a7aSWarner Losh</li> 3549*8e3e3a7aSWarner Losh 3550*8e3e3a7aSWarner Losh<li><b><code>LUA_GCSTEP</code>: </b> 3551*8e3e3a7aSWarner Loshperforms an incremental step of garbage collection. 3552*8e3e3a7aSWarner Losh</li> 3553*8e3e3a7aSWarner Losh 3554*8e3e3a7aSWarner Losh<li><b><code>LUA_GCSETPAUSE</code>: </b> 3555*8e3e3a7aSWarner Loshsets <code>data</code> as the new value 3556*8e3e3a7aSWarner Loshfor the <em>pause</em> of the collector (see <a href="#2.5">§2.5</a>) 3557*8e3e3a7aSWarner Loshand returns the previous value of the pause. 3558*8e3e3a7aSWarner Losh</li> 3559*8e3e3a7aSWarner Losh 3560*8e3e3a7aSWarner Losh<li><b><code>LUA_GCSETSTEPMUL</code>: </b> 3561*8e3e3a7aSWarner Loshsets <code>data</code> as the new value for the <em>step multiplier</em> of 3562*8e3e3a7aSWarner Loshthe collector (see <a href="#2.5">§2.5</a>) 3563*8e3e3a7aSWarner Loshand returns the previous value of the step multiplier. 3564*8e3e3a7aSWarner Losh</li> 3565*8e3e3a7aSWarner Losh 3566*8e3e3a7aSWarner Losh<li><b><code>LUA_GCISRUNNING</code>: </b> 3567*8e3e3a7aSWarner Loshreturns a boolean that tells whether the collector is running 3568*8e3e3a7aSWarner Losh(i.e., not stopped). 3569*8e3e3a7aSWarner Losh</li> 3570*8e3e3a7aSWarner Losh 3571*8e3e3a7aSWarner Losh</ul> 3572*8e3e3a7aSWarner Losh 3573*8e3e3a7aSWarner Losh<p> 3574*8e3e3a7aSWarner LoshFor more details about these options, 3575*8e3e3a7aSWarner Loshsee <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>. 3576*8e3e3a7aSWarner Losh 3577*8e3e3a7aSWarner Losh 3578*8e3e3a7aSWarner Losh 3579*8e3e3a7aSWarner Losh 3580*8e3e3a7aSWarner Losh 3581*8e3e3a7aSWarner Losh<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> 3582*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3583*8e3e3a7aSWarner Losh<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> 3584*8e3e3a7aSWarner Losh 3585*8e3e3a7aSWarner Losh<p> 3586*8e3e3a7aSWarner LoshReturns the memory-allocation function of a given state. 3587*8e3e3a7aSWarner LoshIf <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the 3588*8e3e3a7aSWarner Loshopaque pointer given when the memory-allocator function was set. 3589*8e3e3a7aSWarner Losh 3590*8e3e3a7aSWarner Losh 3591*8e3e3a7aSWarner Losh 3592*8e3e3a7aSWarner Losh 3593*8e3e3a7aSWarner Losh 3594*8e3e3a7aSWarner Losh<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> 3595*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 3596*8e3e3a7aSWarner Losh<pre>int lua_getfield (lua_State *L, int index, const char *k);</pre> 3597*8e3e3a7aSWarner Losh 3598*8e3e3a7aSWarner Losh<p> 3599*8e3e3a7aSWarner LoshPushes onto the stack the value <code>t[k]</code>, 3600*8e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index. 3601*8e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 3602*8e3e3a7aSWarner Loshfor the "index" event (see <a href="#2.4">§2.4</a>). 3603*8e3e3a7aSWarner Losh 3604*8e3e3a7aSWarner Losh 3605*8e3e3a7aSWarner Losh<p> 3606*8e3e3a7aSWarner LoshReturns the type of the pushed value. 3607*8e3e3a7aSWarner Losh 3608*8e3e3a7aSWarner Losh 3609*8e3e3a7aSWarner Losh 3610*8e3e3a7aSWarner Losh 3611*8e3e3a7aSWarner Losh 3612*8e3e3a7aSWarner Losh<hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p> 3613*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3614*8e3e3a7aSWarner Losh<pre>void *lua_getextraspace (lua_State *L);</pre> 3615*8e3e3a7aSWarner Losh 3616*8e3e3a7aSWarner Losh<p> 3617*8e3e3a7aSWarner LoshReturns a pointer to a raw memory area associated with the 3618*8e3e3a7aSWarner Loshgiven Lua state. 3619*8e3e3a7aSWarner LoshThe application can use this area for any purpose; 3620*8e3e3a7aSWarner LoshLua does not use it for anything. 3621*8e3e3a7aSWarner Losh 3622*8e3e3a7aSWarner Losh 3623*8e3e3a7aSWarner Losh<p> 3624*8e3e3a7aSWarner LoshEach new thread has this area initialized with a copy 3625*8e3e3a7aSWarner Loshof the area of the main thread. 3626*8e3e3a7aSWarner Losh 3627*8e3e3a7aSWarner Losh 3628*8e3e3a7aSWarner Losh<p> 3629*8e3e3a7aSWarner LoshBy default, this area has the size of a pointer to void, 3630*8e3e3a7aSWarner Loshbut you can recompile Lua with a different size for this area. 3631*8e3e3a7aSWarner Losh(See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.) 3632*8e3e3a7aSWarner Losh 3633*8e3e3a7aSWarner Losh 3634*8e3e3a7aSWarner Losh 3635*8e3e3a7aSWarner Losh 3636*8e3e3a7aSWarner Losh 3637*8e3e3a7aSWarner Losh<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> 3638*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 3639*8e3e3a7aSWarner Losh<pre>int lua_getglobal (lua_State *L, const char *name);</pre> 3640*8e3e3a7aSWarner Losh 3641*8e3e3a7aSWarner Losh<p> 3642*8e3e3a7aSWarner LoshPushes onto the stack the value of the global <code>name</code>. 3643*8e3e3a7aSWarner LoshReturns the type of that value. 3644*8e3e3a7aSWarner Losh 3645*8e3e3a7aSWarner Losh 3646*8e3e3a7aSWarner Losh 3647*8e3e3a7aSWarner Losh 3648*8e3e3a7aSWarner Losh 3649*8e3e3a7aSWarner Losh<hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p> 3650*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 3651*8e3e3a7aSWarner Losh<pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre> 3652*8e3e3a7aSWarner Losh 3653*8e3e3a7aSWarner Losh<p> 3654*8e3e3a7aSWarner LoshPushes onto the stack the value <code>t[i]</code>, 3655*8e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index. 3656*8e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 3657*8e3e3a7aSWarner Loshfor the "index" event (see <a href="#2.4">§2.4</a>). 3658*8e3e3a7aSWarner Losh 3659*8e3e3a7aSWarner Losh 3660*8e3e3a7aSWarner Losh<p> 3661*8e3e3a7aSWarner LoshReturns the type of the pushed value. 3662*8e3e3a7aSWarner Losh 3663*8e3e3a7aSWarner Losh 3664*8e3e3a7aSWarner Losh 3665*8e3e3a7aSWarner Losh 3666*8e3e3a7aSWarner Losh 3667*8e3e3a7aSWarner Losh<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> 3668*8e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), –]</span> 3669*8e3e3a7aSWarner Losh<pre>int lua_getmetatable (lua_State *L, int index);</pre> 3670*8e3e3a7aSWarner Losh 3671*8e3e3a7aSWarner Losh<p> 3672*8e3e3a7aSWarner LoshIf the value at the given index has a metatable, 3673*8e3e3a7aSWarner Loshthe function pushes that metatable onto the stack and returns 1. 3674*8e3e3a7aSWarner LoshOtherwise, 3675*8e3e3a7aSWarner Loshthe function returns 0 and pushes nothing on the stack. 3676*8e3e3a7aSWarner Losh 3677*8e3e3a7aSWarner Losh 3678*8e3e3a7aSWarner Losh 3679*8e3e3a7aSWarner Losh 3680*8e3e3a7aSWarner Losh 3681*8e3e3a7aSWarner Losh<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> 3682*8e3e3a7aSWarner Losh<span class="apii">[-1, +1, <em>e</em>]</span> 3683*8e3e3a7aSWarner Losh<pre>int lua_gettable (lua_State *L, int index);</pre> 3684*8e3e3a7aSWarner Losh 3685*8e3e3a7aSWarner Losh<p> 3686*8e3e3a7aSWarner LoshPushes onto the stack the value <code>t[k]</code>, 3687*8e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index 3688*8e3e3a7aSWarner Loshand <code>k</code> is the value at the top of the stack. 3689*8e3e3a7aSWarner Losh 3690*8e3e3a7aSWarner Losh 3691*8e3e3a7aSWarner Losh<p> 3692*8e3e3a7aSWarner LoshThis function pops the key from the stack, 3693*8e3e3a7aSWarner Loshpushing the resulting value in its place. 3694*8e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 3695*8e3e3a7aSWarner Loshfor the "index" event (see <a href="#2.4">§2.4</a>). 3696*8e3e3a7aSWarner Losh 3697*8e3e3a7aSWarner Losh 3698*8e3e3a7aSWarner Losh<p> 3699*8e3e3a7aSWarner LoshReturns the type of the pushed value. 3700*8e3e3a7aSWarner Losh 3701*8e3e3a7aSWarner Losh 3702*8e3e3a7aSWarner Losh 3703*8e3e3a7aSWarner Losh 3704*8e3e3a7aSWarner Losh 3705*8e3e3a7aSWarner Losh<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> 3706*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3707*8e3e3a7aSWarner Losh<pre>int lua_gettop (lua_State *L);</pre> 3708*8e3e3a7aSWarner Losh 3709*8e3e3a7aSWarner Losh<p> 3710*8e3e3a7aSWarner LoshReturns the index of the top element in the stack. 3711*8e3e3a7aSWarner LoshBecause indices start at 1, 3712*8e3e3a7aSWarner Loshthis result is equal to the number of elements in the stack; 3713*8e3e3a7aSWarner Loshin particular, 0 means an empty stack. 3714*8e3e3a7aSWarner Losh 3715*8e3e3a7aSWarner Losh 3716*8e3e3a7aSWarner Losh 3717*8e3e3a7aSWarner Losh 3718*8e3e3a7aSWarner Losh 3719*8e3e3a7aSWarner Losh<hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p> 3720*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 3721*8e3e3a7aSWarner Losh<pre>int lua_getuservalue (lua_State *L, int index);</pre> 3722*8e3e3a7aSWarner Losh 3723*8e3e3a7aSWarner Losh<p> 3724*8e3e3a7aSWarner LoshPushes onto the stack the Lua value associated with the full userdata 3725*8e3e3a7aSWarner Loshat the given index. 3726*8e3e3a7aSWarner Losh 3727*8e3e3a7aSWarner Losh 3728*8e3e3a7aSWarner Losh<p> 3729*8e3e3a7aSWarner LoshReturns the type of the pushed value. 3730*8e3e3a7aSWarner Losh 3731*8e3e3a7aSWarner Losh 3732*8e3e3a7aSWarner Losh 3733*8e3e3a7aSWarner Losh 3734*8e3e3a7aSWarner Losh 3735*8e3e3a7aSWarner Losh<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> 3736*8e3e3a7aSWarner Losh<span class="apii">[-1, +1, –]</span> 3737*8e3e3a7aSWarner Losh<pre>void lua_insert (lua_State *L, int index);</pre> 3738*8e3e3a7aSWarner Losh 3739*8e3e3a7aSWarner Losh<p> 3740*8e3e3a7aSWarner LoshMoves the top element into the given valid index, 3741*8e3e3a7aSWarner Loshshifting up the elements above this index to open space. 3742*8e3e3a7aSWarner LoshThis function cannot be called with a pseudo-index, 3743*8e3e3a7aSWarner Loshbecause a pseudo-index is not an actual stack position. 3744*8e3e3a7aSWarner Losh 3745*8e3e3a7aSWarner Losh 3746*8e3e3a7aSWarner Losh 3747*8e3e3a7aSWarner Losh 3748*8e3e3a7aSWarner Losh 3749*8e3e3a7aSWarner Losh<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> 3750*8e3e3a7aSWarner Losh<pre>typedef ... lua_Integer;</pre> 3751*8e3e3a7aSWarner Losh 3752*8e3e3a7aSWarner Losh<p> 3753*8e3e3a7aSWarner LoshThe type of integers in Lua. 3754*8e3e3a7aSWarner Losh 3755*8e3e3a7aSWarner Losh 3756*8e3e3a7aSWarner Losh<p> 3757*8e3e3a7aSWarner LoshBy default this type is <code>long long</code>, 3758*8e3e3a7aSWarner Losh(usually a 64-bit two-complement integer), 3759*8e3e3a7aSWarner Loshbut that can be changed to <code>long</code> or <code>int</code> 3760*8e3e3a7aSWarner Losh(usually a 32-bit two-complement integer). 3761*8e3e3a7aSWarner Losh(See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.) 3762*8e3e3a7aSWarner Losh 3763*8e3e3a7aSWarner Losh 3764*8e3e3a7aSWarner Losh<p> 3765*8e3e3a7aSWarner LoshLua also defines the constants 3766*8e3e3a7aSWarner Losh<a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>, 3767*8e3e3a7aSWarner Loshwith the minimum and the maximum values that fit in this type. 3768*8e3e3a7aSWarner Losh 3769*8e3e3a7aSWarner Losh 3770*8e3e3a7aSWarner Losh 3771*8e3e3a7aSWarner Losh 3772*8e3e3a7aSWarner Losh 3773*8e3e3a7aSWarner Losh<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> 3774*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3775*8e3e3a7aSWarner Losh<pre>int lua_isboolean (lua_State *L, int index);</pre> 3776*8e3e3a7aSWarner Losh 3777*8e3e3a7aSWarner Losh<p> 3778*8e3e3a7aSWarner LoshReturns 1 if the value at the given index is a boolean, 3779*8e3e3a7aSWarner Loshand 0 otherwise. 3780*8e3e3a7aSWarner Losh 3781*8e3e3a7aSWarner Losh 3782*8e3e3a7aSWarner Losh 3783*8e3e3a7aSWarner Losh 3784*8e3e3a7aSWarner Losh 3785*8e3e3a7aSWarner Losh<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> 3786*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3787*8e3e3a7aSWarner Losh<pre>int lua_iscfunction (lua_State *L, int index);</pre> 3788*8e3e3a7aSWarner Losh 3789*8e3e3a7aSWarner Losh<p> 3790*8e3e3a7aSWarner LoshReturns 1 if the value at the given index is a C function, 3791*8e3e3a7aSWarner Loshand 0 otherwise. 3792*8e3e3a7aSWarner Losh 3793*8e3e3a7aSWarner Losh 3794*8e3e3a7aSWarner Losh 3795*8e3e3a7aSWarner Losh 3796*8e3e3a7aSWarner Losh 3797*8e3e3a7aSWarner Losh<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> 3798*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3799*8e3e3a7aSWarner Losh<pre>int lua_isfunction (lua_State *L, int index);</pre> 3800*8e3e3a7aSWarner Losh 3801*8e3e3a7aSWarner Losh<p> 3802*8e3e3a7aSWarner LoshReturns 1 if the value at the given index is a function 3803*8e3e3a7aSWarner Losh(either C or Lua), and 0 otherwise. 3804*8e3e3a7aSWarner Losh 3805*8e3e3a7aSWarner Losh 3806*8e3e3a7aSWarner Losh 3807*8e3e3a7aSWarner Losh 3808*8e3e3a7aSWarner Losh 3809*8e3e3a7aSWarner Losh<hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p> 3810*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3811*8e3e3a7aSWarner Losh<pre>int lua_isinteger (lua_State *L, int index);</pre> 3812*8e3e3a7aSWarner Losh 3813*8e3e3a7aSWarner Losh<p> 3814*8e3e3a7aSWarner LoshReturns 1 if the value at the given index is an integer 3815*8e3e3a7aSWarner Losh(that is, the value is a number and is represented as an integer), 3816*8e3e3a7aSWarner Loshand 0 otherwise. 3817*8e3e3a7aSWarner Losh 3818*8e3e3a7aSWarner Losh 3819*8e3e3a7aSWarner Losh 3820*8e3e3a7aSWarner Losh 3821*8e3e3a7aSWarner Losh 3822*8e3e3a7aSWarner Losh<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> 3823*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3824*8e3e3a7aSWarner Losh<pre>int lua_islightuserdata (lua_State *L, int index);</pre> 3825*8e3e3a7aSWarner Losh 3826*8e3e3a7aSWarner Losh<p> 3827*8e3e3a7aSWarner LoshReturns 1 if the value at the given index is a light userdata, 3828*8e3e3a7aSWarner Loshand 0 otherwise. 3829*8e3e3a7aSWarner Losh 3830*8e3e3a7aSWarner Losh 3831*8e3e3a7aSWarner Losh 3832*8e3e3a7aSWarner Losh 3833*8e3e3a7aSWarner Losh 3834*8e3e3a7aSWarner Losh<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> 3835*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3836*8e3e3a7aSWarner Losh<pre>int lua_isnil (lua_State *L, int index);</pre> 3837*8e3e3a7aSWarner Losh 3838*8e3e3a7aSWarner Losh<p> 3839*8e3e3a7aSWarner LoshReturns 1 if the value at the given index is <b>nil</b>, 3840*8e3e3a7aSWarner Loshand 0 otherwise. 3841*8e3e3a7aSWarner Losh 3842*8e3e3a7aSWarner Losh 3843*8e3e3a7aSWarner Losh 3844*8e3e3a7aSWarner Losh 3845*8e3e3a7aSWarner Losh 3846*8e3e3a7aSWarner Losh<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> 3847*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3848*8e3e3a7aSWarner Losh<pre>int lua_isnone (lua_State *L, int index);</pre> 3849*8e3e3a7aSWarner Losh 3850*8e3e3a7aSWarner Losh<p> 3851*8e3e3a7aSWarner LoshReturns 1 if the given index is not valid, 3852*8e3e3a7aSWarner Loshand 0 otherwise. 3853*8e3e3a7aSWarner Losh 3854*8e3e3a7aSWarner Losh 3855*8e3e3a7aSWarner Losh 3856*8e3e3a7aSWarner Losh 3857*8e3e3a7aSWarner Losh 3858*8e3e3a7aSWarner Losh<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> 3859*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3860*8e3e3a7aSWarner Losh<pre>int lua_isnoneornil (lua_State *L, int index);</pre> 3861*8e3e3a7aSWarner Losh 3862*8e3e3a7aSWarner Losh<p> 3863*8e3e3a7aSWarner LoshReturns 1 if the given index is not valid 3864*8e3e3a7aSWarner Loshor if the value at this index is <b>nil</b>, 3865*8e3e3a7aSWarner Loshand 0 otherwise. 3866*8e3e3a7aSWarner Losh 3867*8e3e3a7aSWarner Losh 3868*8e3e3a7aSWarner Losh 3869*8e3e3a7aSWarner Losh 3870*8e3e3a7aSWarner Losh 3871*8e3e3a7aSWarner Losh<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> 3872*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3873*8e3e3a7aSWarner Losh<pre>int lua_isnumber (lua_State *L, int index);</pre> 3874*8e3e3a7aSWarner Losh 3875*8e3e3a7aSWarner Losh<p> 3876*8e3e3a7aSWarner LoshReturns 1 if the value at the given index is a number 3877*8e3e3a7aSWarner Loshor a string convertible to a number, 3878*8e3e3a7aSWarner Loshand 0 otherwise. 3879*8e3e3a7aSWarner Losh 3880*8e3e3a7aSWarner Losh 3881*8e3e3a7aSWarner Losh 3882*8e3e3a7aSWarner Losh 3883*8e3e3a7aSWarner Losh 3884*8e3e3a7aSWarner Losh<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> 3885*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3886*8e3e3a7aSWarner Losh<pre>int lua_isstring (lua_State *L, int index);</pre> 3887*8e3e3a7aSWarner Losh 3888*8e3e3a7aSWarner Losh<p> 3889*8e3e3a7aSWarner LoshReturns 1 if the value at the given index is a string 3890*8e3e3a7aSWarner Loshor a number (which is always convertible to a string), 3891*8e3e3a7aSWarner Loshand 0 otherwise. 3892*8e3e3a7aSWarner Losh 3893*8e3e3a7aSWarner Losh 3894*8e3e3a7aSWarner Losh 3895*8e3e3a7aSWarner Losh 3896*8e3e3a7aSWarner Losh 3897*8e3e3a7aSWarner Losh<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> 3898*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3899*8e3e3a7aSWarner Losh<pre>int lua_istable (lua_State *L, int index);</pre> 3900*8e3e3a7aSWarner Losh 3901*8e3e3a7aSWarner Losh<p> 3902*8e3e3a7aSWarner LoshReturns 1 if the value at the given index is a table, 3903*8e3e3a7aSWarner Loshand 0 otherwise. 3904*8e3e3a7aSWarner Losh 3905*8e3e3a7aSWarner Losh 3906*8e3e3a7aSWarner Losh 3907*8e3e3a7aSWarner Losh 3908*8e3e3a7aSWarner Losh 3909*8e3e3a7aSWarner Losh<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> 3910*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3911*8e3e3a7aSWarner Losh<pre>int lua_isthread (lua_State *L, int index);</pre> 3912*8e3e3a7aSWarner Losh 3913*8e3e3a7aSWarner Losh<p> 3914*8e3e3a7aSWarner LoshReturns 1 if the value at the given index is a thread, 3915*8e3e3a7aSWarner Loshand 0 otherwise. 3916*8e3e3a7aSWarner Losh 3917*8e3e3a7aSWarner Losh 3918*8e3e3a7aSWarner Losh 3919*8e3e3a7aSWarner Losh 3920*8e3e3a7aSWarner Losh 3921*8e3e3a7aSWarner Losh<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> 3922*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3923*8e3e3a7aSWarner Losh<pre>int lua_isuserdata (lua_State *L, int index);</pre> 3924*8e3e3a7aSWarner Losh 3925*8e3e3a7aSWarner Losh<p> 3926*8e3e3a7aSWarner LoshReturns 1 if the value at the given index is a userdata 3927*8e3e3a7aSWarner Losh(either full or light), and 0 otherwise. 3928*8e3e3a7aSWarner Losh 3929*8e3e3a7aSWarner Losh 3930*8e3e3a7aSWarner Losh 3931*8e3e3a7aSWarner Losh 3932*8e3e3a7aSWarner Losh 3933*8e3e3a7aSWarner Losh<hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p> 3934*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 3935*8e3e3a7aSWarner Losh<pre>int lua_isyieldable (lua_State *L);</pre> 3936*8e3e3a7aSWarner Losh 3937*8e3e3a7aSWarner Losh<p> 3938*8e3e3a7aSWarner LoshReturns 1 if the given coroutine can yield, 3939*8e3e3a7aSWarner Loshand 0 otherwise. 3940*8e3e3a7aSWarner Losh 3941*8e3e3a7aSWarner Losh 3942*8e3e3a7aSWarner Losh 3943*8e3e3a7aSWarner Losh 3944*8e3e3a7aSWarner Losh 3945*8e3e3a7aSWarner Losh<hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3> 3946*8e3e3a7aSWarner Losh<pre>typedef ... lua_KContext;</pre> 3947*8e3e3a7aSWarner Losh 3948*8e3e3a7aSWarner Losh<p> 3949*8e3e3a7aSWarner LoshThe type for continuation-function contexts. 3950*8e3e3a7aSWarner LoshIt must be a numeric type. 3951*8e3e3a7aSWarner LoshThis type is defined as <code>intptr_t</code> 3952*8e3e3a7aSWarner Loshwhen <code>intptr_t</code> is available, 3953*8e3e3a7aSWarner Loshso that it can store pointers too. 3954*8e3e3a7aSWarner LoshOtherwise, it is defined as <code>ptrdiff_t</code>. 3955*8e3e3a7aSWarner Losh 3956*8e3e3a7aSWarner Losh 3957*8e3e3a7aSWarner Losh 3958*8e3e3a7aSWarner Losh 3959*8e3e3a7aSWarner Losh 3960*8e3e3a7aSWarner Losh<hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3> 3961*8e3e3a7aSWarner Losh<pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre> 3962*8e3e3a7aSWarner Losh 3963*8e3e3a7aSWarner Losh<p> 3964*8e3e3a7aSWarner LoshType for continuation functions (see <a href="#4.7">§4.7</a>). 3965*8e3e3a7aSWarner Losh 3966*8e3e3a7aSWarner Losh 3967*8e3e3a7aSWarner Losh 3968*8e3e3a7aSWarner Losh 3969*8e3e3a7aSWarner Losh 3970*8e3e3a7aSWarner Losh<hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p> 3971*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 3972*8e3e3a7aSWarner Losh<pre>void lua_len (lua_State *L, int index);</pre> 3973*8e3e3a7aSWarner Losh 3974*8e3e3a7aSWarner Losh<p> 3975*8e3e3a7aSWarner LoshReturns the length of the value at the given index. 3976*8e3e3a7aSWarner LoshIt is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>) and 3977*8e3e3a7aSWarner Loshmay trigger a metamethod for the "length" event (see <a href="#2.4">§2.4</a>). 3978*8e3e3a7aSWarner LoshThe result is pushed on the stack. 3979*8e3e3a7aSWarner Losh 3980*8e3e3a7aSWarner Losh 3981*8e3e3a7aSWarner Losh 3982*8e3e3a7aSWarner Losh 3983*8e3e3a7aSWarner Losh 3984*8e3e3a7aSWarner Losh<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> 3985*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 3986*8e3e3a7aSWarner Losh<pre>int lua_load (lua_State *L, 3987*8e3e3a7aSWarner Losh lua_Reader reader, 3988*8e3e3a7aSWarner Losh void *data, 3989*8e3e3a7aSWarner Losh const char *chunkname, 3990*8e3e3a7aSWarner Losh const char *mode);</pre> 3991*8e3e3a7aSWarner Losh 3992*8e3e3a7aSWarner Losh<p> 3993*8e3e3a7aSWarner LoshLoads a Lua chunk without running it. 3994*8e3e3a7aSWarner LoshIf there are no errors, 3995*8e3e3a7aSWarner Losh<code>lua_load</code> pushes the compiled chunk as a Lua 3996*8e3e3a7aSWarner Loshfunction on top of the stack. 3997*8e3e3a7aSWarner LoshOtherwise, it pushes an error message. 3998*8e3e3a7aSWarner Losh 3999*8e3e3a7aSWarner Losh 4000*8e3e3a7aSWarner Losh<p> 4001*8e3e3a7aSWarner LoshThe return values of <code>lua_load</code> are: 4002*8e3e3a7aSWarner Losh 4003*8e3e3a7aSWarner Losh<ul> 4004*8e3e3a7aSWarner Losh 4005*8e3e3a7aSWarner Losh<li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li> 4006*8e3e3a7aSWarner Losh 4007*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> 4008*8e3e3a7aSWarner Loshsyntax error during precompilation;</li> 4009*8e3e3a7aSWarner Losh 4010*8e3e3a7aSWarner Losh<li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 4011*8e3e3a7aSWarner Loshmemory allocation (out-of-memory) error;</li> 4012*8e3e3a7aSWarner Losh 4013*8e3e3a7aSWarner Losh<li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> 4014*8e3e3a7aSWarner Losherror while running a <code>__gc</code> metamethod. 4015*8e3e3a7aSWarner Losh(This error has no relation with the chunk being loaded. 4016*8e3e3a7aSWarner LoshIt is generated by the garbage collector.) 4017*8e3e3a7aSWarner Losh</li> 4018*8e3e3a7aSWarner Losh 4019*8e3e3a7aSWarner Losh</ul> 4020*8e3e3a7aSWarner Losh 4021*8e3e3a7aSWarner Losh<p> 4022*8e3e3a7aSWarner LoshThe <code>lua_load</code> function uses a user-supplied <code>reader</code> function 4023*8e3e3a7aSWarner Loshto read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). 4024*8e3e3a7aSWarner LoshThe <code>data</code> argument is an opaque value passed to the reader function. 4025*8e3e3a7aSWarner Losh 4026*8e3e3a7aSWarner Losh 4027*8e3e3a7aSWarner Losh<p> 4028*8e3e3a7aSWarner LoshThe <code>chunkname</code> argument gives a name to the chunk, 4029*8e3e3a7aSWarner Loshwhich is used for error messages and in debug information (see <a href="#4.9">§4.9</a>). 4030*8e3e3a7aSWarner Losh 4031*8e3e3a7aSWarner Losh 4032*8e3e3a7aSWarner Losh<p> 4033*8e3e3a7aSWarner Losh<code>lua_load</code> automatically detects whether the chunk is text or binary 4034*8e3e3a7aSWarner Loshand loads it accordingly (see program <code>luac</code>). 4035*8e3e3a7aSWarner LoshThe string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>, 4036*8e3e3a7aSWarner Loshwith the addition that 4037*8e3e3a7aSWarner Losha <code>NULL</code> value is equivalent to the string "<code>bt</code>". 4038*8e3e3a7aSWarner Losh 4039*8e3e3a7aSWarner Losh 4040*8e3e3a7aSWarner Losh<p> 4041*8e3e3a7aSWarner Losh<code>lua_load</code> uses the stack internally, 4042*8e3e3a7aSWarner Loshso the reader function must always leave the stack 4043*8e3e3a7aSWarner Loshunmodified when returning. 4044*8e3e3a7aSWarner Losh 4045*8e3e3a7aSWarner Losh 4046*8e3e3a7aSWarner Losh<p> 4047*8e3e3a7aSWarner LoshIf the resulting function has upvalues, 4048*8e3e3a7aSWarner Loshits first upvalue is set to the value of the global environment 4049*8e3e3a7aSWarner Loshstored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">§4.5</a>). 4050*8e3e3a7aSWarner LoshWhen loading main chunks, 4051*8e3e3a7aSWarner Loshthis upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 4052*8e3e3a7aSWarner LoshOther upvalues are initialized with <b>nil</b>. 4053*8e3e3a7aSWarner Losh 4054*8e3e3a7aSWarner Losh 4055*8e3e3a7aSWarner Losh 4056*8e3e3a7aSWarner Losh 4057*8e3e3a7aSWarner Losh 4058*8e3e3a7aSWarner Losh<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> 4059*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 4060*8e3e3a7aSWarner Losh<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> 4061*8e3e3a7aSWarner Losh 4062*8e3e3a7aSWarner Losh<p> 4063*8e3e3a7aSWarner LoshCreates a new thread running in a new, independent state. 4064*8e3e3a7aSWarner LoshReturns <code>NULL</code> if it cannot create the thread or the state 4065*8e3e3a7aSWarner Losh(due to lack of memory). 4066*8e3e3a7aSWarner LoshThe argument <code>f</code> is the allocator function; 4067*8e3e3a7aSWarner LoshLua does all memory allocation for this state 4068*8e3e3a7aSWarner Loshthrough this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>). 4069*8e3e3a7aSWarner LoshThe second argument, <code>ud</code>, is an opaque pointer that Lua 4070*8e3e3a7aSWarner Loshpasses to the allocator in every call. 4071*8e3e3a7aSWarner Losh 4072*8e3e3a7aSWarner Losh 4073*8e3e3a7aSWarner Losh 4074*8e3e3a7aSWarner Losh 4075*8e3e3a7aSWarner Losh 4076*8e3e3a7aSWarner Losh<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> 4077*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 4078*8e3e3a7aSWarner Losh<pre>void lua_newtable (lua_State *L);</pre> 4079*8e3e3a7aSWarner Losh 4080*8e3e3a7aSWarner Losh<p> 4081*8e3e3a7aSWarner LoshCreates a new empty table and pushes it onto the stack. 4082*8e3e3a7aSWarner LoshIt is equivalent to <code>lua_createtable(L, 0, 0)</code>. 4083*8e3e3a7aSWarner Losh 4084*8e3e3a7aSWarner Losh 4085*8e3e3a7aSWarner Losh 4086*8e3e3a7aSWarner Losh 4087*8e3e3a7aSWarner Losh 4088*8e3e3a7aSWarner Losh<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> 4089*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 4090*8e3e3a7aSWarner Losh<pre>lua_State *lua_newthread (lua_State *L);</pre> 4091*8e3e3a7aSWarner Losh 4092*8e3e3a7aSWarner Losh<p> 4093*8e3e3a7aSWarner LoshCreates a new thread, pushes it on the stack, 4094*8e3e3a7aSWarner Loshand returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. 4095*8e3e3a7aSWarner LoshThe new thread returned by this function shares with the original thread 4096*8e3e3a7aSWarner Loshits global environment, 4097*8e3e3a7aSWarner Loshbut has an independent execution stack. 4098*8e3e3a7aSWarner Losh 4099*8e3e3a7aSWarner Losh 4100*8e3e3a7aSWarner Losh<p> 4101*8e3e3a7aSWarner LoshThere is no explicit function to close or to destroy a thread. 4102*8e3e3a7aSWarner LoshThreads are subject to garbage collection, 4103*8e3e3a7aSWarner Loshlike any Lua object. 4104*8e3e3a7aSWarner Losh 4105*8e3e3a7aSWarner Losh 4106*8e3e3a7aSWarner Losh 4107*8e3e3a7aSWarner Losh 4108*8e3e3a7aSWarner Losh 4109*8e3e3a7aSWarner Losh<hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p> 4110*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 4111*8e3e3a7aSWarner Losh<pre>void *lua_newuserdata (lua_State *L, size_t size);</pre> 4112*8e3e3a7aSWarner Losh 4113*8e3e3a7aSWarner Losh<p> 4114*8e3e3a7aSWarner LoshThis function allocates a new block of memory with the given size, 4115*8e3e3a7aSWarner Loshpushes onto the stack a new full userdata with the block address, 4116*8e3e3a7aSWarner Loshand returns this address. 4117*8e3e3a7aSWarner LoshThe host program can freely use this memory. 4118*8e3e3a7aSWarner Losh 4119*8e3e3a7aSWarner Losh 4120*8e3e3a7aSWarner Losh 4121*8e3e3a7aSWarner Losh 4122*8e3e3a7aSWarner Losh 4123*8e3e3a7aSWarner Losh<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> 4124*8e3e3a7aSWarner Losh<span class="apii">[-1, +(2|0), <em>e</em>]</span> 4125*8e3e3a7aSWarner Losh<pre>int lua_next (lua_State *L, int index);</pre> 4126*8e3e3a7aSWarner Losh 4127*8e3e3a7aSWarner Losh<p> 4128*8e3e3a7aSWarner LoshPops a key from the stack, 4129*8e3e3a7aSWarner Loshand pushes a key–value pair from the table at the given index 4130*8e3e3a7aSWarner Losh(the "next" pair after the given key). 4131*8e3e3a7aSWarner LoshIf there are no more elements in the table, 4132*8e3e3a7aSWarner Loshthen <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). 4133*8e3e3a7aSWarner Losh 4134*8e3e3a7aSWarner Losh 4135*8e3e3a7aSWarner Losh<p> 4136*8e3e3a7aSWarner LoshA typical traversal looks like this: 4137*8e3e3a7aSWarner Losh 4138*8e3e3a7aSWarner Losh<pre> 4139*8e3e3a7aSWarner Losh /* table is in the stack at index 't' */ 4140*8e3e3a7aSWarner Losh lua_pushnil(L); /* first key */ 4141*8e3e3a7aSWarner Losh while (lua_next(L, t) != 0) { 4142*8e3e3a7aSWarner Losh /* uses 'key' (at index -2) and 'value' (at index -1) */ 4143*8e3e3a7aSWarner Losh printf("%s - %s\n", 4144*8e3e3a7aSWarner Losh lua_typename(L, lua_type(L, -2)), 4145*8e3e3a7aSWarner Losh lua_typename(L, lua_type(L, -1))); 4146*8e3e3a7aSWarner Losh /* removes 'value'; keeps 'key' for next iteration */ 4147*8e3e3a7aSWarner Losh lua_pop(L, 1); 4148*8e3e3a7aSWarner Losh } 4149*8e3e3a7aSWarner Losh</pre> 4150*8e3e3a7aSWarner Losh 4151*8e3e3a7aSWarner Losh<p> 4152*8e3e3a7aSWarner LoshWhile traversing a table, 4153*8e3e3a7aSWarner Loshdo not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, 4154*8e3e3a7aSWarner Loshunless you know that the key is actually a string. 4155*8e3e3a7aSWarner LoshRecall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change 4156*8e3e3a7aSWarner Loshthe value at the given index; 4157*8e3e3a7aSWarner Loshthis confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. 4158*8e3e3a7aSWarner Losh 4159*8e3e3a7aSWarner Losh 4160*8e3e3a7aSWarner Losh<p> 4161*8e3e3a7aSWarner LoshSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 4162*8e3e3a7aSWarner Loshthe table during its traversal. 4163*8e3e3a7aSWarner Losh 4164*8e3e3a7aSWarner Losh 4165*8e3e3a7aSWarner Losh 4166*8e3e3a7aSWarner Losh 4167*8e3e3a7aSWarner Losh 4168*8e3e3a7aSWarner Losh<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> 4169*8e3e3a7aSWarner Losh<pre>typedef ... lua_Number;</pre> 4170*8e3e3a7aSWarner Losh 4171*8e3e3a7aSWarner Losh<p> 4172*8e3e3a7aSWarner LoshThe type of floats in Lua. 4173*8e3e3a7aSWarner Losh 4174*8e3e3a7aSWarner Losh 4175*8e3e3a7aSWarner Losh<p> 4176*8e3e3a7aSWarner LoshBy default this type is double, 4177*8e3e3a7aSWarner Loshbut that can be changed to a single float or a long double. 4178*8e3e3a7aSWarner Losh(See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.) 4179*8e3e3a7aSWarner Losh 4180*8e3e3a7aSWarner Losh 4181*8e3e3a7aSWarner Losh 4182*8e3e3a7aSWarner Losh 4183*8e3e3a7aSWarner Losh 4184*8e3e3a7aSWarner Losh<hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3> 4185*8e3e3a7aSWarner Losh<pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre> 4186*8e3e3a7aSWarner Losh 4187*8e3e3a7aSWarner Losh<p> 4188*8e3e3a7aSWarner LoshConverts a Lua float to a Lua integer. 4189*8e3e3a7aSWarner LoshThis macro assumes that <code>n</code> has an integral value. 4190*8e3e3a7aSWarner LoshIf that value is within the range of Lua integers, 4191*8e3e3a7aSWarner Loshit is converted to an integer and assigned to <code>*p</code>. 4192*8e3e3a7aSWarner LoshThe macro results in a boolean indicating whether the 4193*8e3e3a7aSWarner Loshconversion was successful. 4194*8e3e3a7aSWarner Losh(Note that this range test can be tricky to do 4195*8e3e3a7aSWarner Loshcorrectly without this macro, 4196*8e3e3a7aSWarner Loshdue to roundings.) 4197*8e3e3a7aSWarner Losh 4198*8e3e3a7aSWarner Losh 4199*8e3e3a7aSWarner Losh<p> 4200*8e3e3a7aSWarner LoshThis macro may evaluate its arguments more than once. 4201*8e3e3a7aSWarner Losh 4202*8e3e3a7aSWarner Losh 4203*8e3e3a7aSWarner Losh 4204*8e3e3a7aSWarner Losh 4205*8e3e3a7aSWarner Losh 4206*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> 4207*8e3e3a7aSWarner Losh<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4208*8e3e3a7aSWarner Losh<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre> 4209*8e3e3a7aSWarner Losh 4210*8e3e3a7aSWarner Losh<p> 4211*8e3e3a7aSWarner LoshCalls a function in protected mode. 4212*8e3e3a7aSWarner Losh 4213*8e3e3a7aSWarner Losh 4214*8e3e3a7aSWarner Losh<p> 4215*8e3e3a7aSWarner LoshBoth <code>nargs</code> and <code>nresults</code> have the same meaning as 4216*8e3e3a7aSWarner Loshin <a href="#lua_call"><code>lua_call</code></a>. 4217*8e3e3a7aSWarner LoshIf there are no errors during the call, 4218*8e3e3a7aSWarner Losh<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. 4219*8e3e3a7aSWarner LoshHowever, if there is any error, 4220*8e3e3a7aSWarner Losh<a href="#lua_pcall"><code>lua_pcall</code></a> catches it, 4221*8e3e3a7aSWarner Loshpushes a single value on the stack (the error object), 4222*8e3e3a7aSWarner Loshand returns an error code. 4223*8e3e3a7aSWarner LoshLike <a href="#lua_call"><code>lua_call</code></a>, 4224*8e3e3a7aSWarner Losh<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function 4225*8e3e3a7aSWarner Loshand its arguments from the stack. 4226*8e3e3a7aSWarner Losh 4227*8e3e3a7aSWarner Losh 4228*8e3e3a7aSWarner Losh<p> 4229*8e3e3a7aSWarner LoshIf <code>msgh</code> is 0, 4230*8e3e3a7aSWarner Loshthen the error object returned on the stack 4231*8e3e3a7aSWarner Loshis exactly the original error object. 4232*8e3e3a7aSWarner LoshOtherwise, <code>msgh</code> is the stack index of a 4233*8e3e3a7aSWarner Losh<em>message handler</em>. 4234*8e3e3a7aSWarner Losh(This index cannot be a pseudo-index.) 4235*8e3e3a7aSWarner LoshIn case of runtime errors, 4236*8e3e3a7aSWarner Loshthis function will be called with the error object 4237*8e3e3a7aSWarner Loshand its return value will be the object 4238*8e3e3a7aSWarner Loshreturned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. 4239*8e3e3a7aSWarner Losh 4240*8e3e3a7aSWarner Losh 4241*8e3e3a7aSWarner Losh<p> 4242*8e3e3a7aSWarner LoshTypically, the message handler is used to add more debug 4243*8e3e3a7aSWarner Loshinformation to the error object, such as a stack traceback. 4244*8e3e3a7aSWarner LoshSuch information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, 4245*8e3e3a7aSWarner Loshsince by then the stack has unwound. 4246*8e3e3a7aSWarner Losh 4247*8e3e3a7aSWarner Losh 4248*8e3e3a7aSWarner Losh<p> 4249*8e3e3a7aSWarner LoshThe <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following constants 4250*8e3e3a7aSWarner Losh(defined in <code>lua.h</code>): 4251*8e3e3a7aSWarner Losh 4252*8e3e3a7aSWarner Losh<ul> 4253*8e3e3a7aSWarner Losh 4254*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> 4255*8e3e3a7aSWarner Loshsuccess.</li> 4256*8e3e3a7aSWarner Losh 4257*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b> 4258*8e3e3a7aSWarner Losha runtime error. 4259*8e3e3a7aSWarner Losh</li> 4260*8e3e3a7aSWarner Losh 4261*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 4262*8e3e3a7aSWarner Loshmemory allocation error. 4263*8e3e3a7aSWarner LoshFor such errors, Lua does not call the message handler. 4264*8e3e3a7aSWarner Losh</li> 4265*8e3e3a7aSWarner Losh 4266*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b> 4267*8e3e3a7aSWarner Losherror while running the message handler. 4268*8e3e3a7aSWarner Losh</li> 4269*8e3e3a7aSWarner Losh 4270*8e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> 4271*8e3e3a7aSWarner Losherror while running a <code>__gc</code> metamethod. 4272*8e3e3a7aSWarner LoshFor such errors, Lua does not call the message handler 4273*8e3e3a7aSWarner Losh(as this kind of error typically has no relation 4274*8e3e3a7aSWarner Loshwith the function being called). 4275*8e3e3a7aSWarner Losh</li> 4276*8e3e3a7aSWarner Losh 4277*8e3e3a7aSWarner Losh</ul> 4278*8e3e3a7aSWarner Losh 4279*8e3e3a7aSWarner Losh 4280*8e3e3a7aSWarner Losh 4281*8e3e3a7aSWarner Losh 4282*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p> 4283*8e3e3a7aSWarner Losh<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4284*8e3e3a7aSWarner Losh<pre>int lua_pcallk (lua_State *L, 4285*8e3e3a7aSWarner Losh int nargs, 4286*8e3e3a7aSWarner Losh int nresults, 4287*8e3e3a7aSWarner Losh int msgh, 4288*8e3e3a7aSWarner Losh lua_KContext ctx, 4289*8e3e3a7aSWarner Losh lua_KFunction k);</pre> 4290*8e3e3a7aSWarner Losh 4291*8e3e3a7aSWarner Losh<p> 4292*8e3e3a7aSWarner LoshThis function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>, 4293*8e3e3a7aSWarner Loshbut allows the called function to yield (see <a href="#4.7">§4.7</a>). 4294*8e3e3a7aSWarner Losh 4295*8e3e3a7aSWarner Losh 4296*8e3e3a7aSWarner Losh 4297*8e3e3a7aSWarner Losh 4298*8e3e3a7aSWarner Losh 4299*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> 4300*8e3e3a7aSWarner Losh<span class="apii">[-n, +0, –]</span> 4301*8e3e3a7aSWarner Losh<pre>void lua_pop (lua_State *L, int n);</pre> 4302*8e3e3a7aSWarner Losh 4303*8e3e3a7aSWarner Losh<p> 4304*8e3e3a7aSWarner LoshPops <code>n</code> elements from the stack. 4305*8e3e3a7aSWarner Losh 4306*8e3e3a7aSWarner Losh 4307*8e3e3a7aSWarner Losh 4308*8e3e3a7aSWarner Losh 4309*8e3e3a7aSWarner Losh 4310*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> 4311*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 4312*8e3e3a7aSWarner Losh<pre>void lua_pushboolean (lua_State *L, int b);</pre> 4313*8e3e3a7aSWarner Losh 4314*8e3e3a7aSWarner Losh<p> 4315*8e3e3a7aSWarner LoshPushes a boolean value with value <code>b</code> onto the stack. 4316*8e3e3a7aSWarner Losh 4317*8e3e3a7aSWarner Losh 4318*8e3e3a7aSWarner Losh 4319*8e3e3a7aSWarner Losh 4320*8e3e3a7aSWarner Losh 4321*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> 4322*8e3e3a7aSWarner Losh<span class="apii">[-n, +1, <em>m</em>]</span> 4323*8e3e3a7aSWarner Losh<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> 4324*8e3e3a7aSWarner Losh 4325*8e3e3a7aSWarner Losh<p> 4326*8e3e3a7aSWarner LoshPushes a new C closure onto the stack. 4327*8e3e3a7aSWarner Losh 4328*8e3e3a7aSWarner Losh 4329*8e3e3a7aSWarner Losh<p> 4330*8e3e3a7aSWarner LoshWhen a C function is created, 4331*8e3e3a7aSWarner Loshit is possible to associate some values with it, 4332*8e3e3a7aSWarner Loshthus creating a C closure (see <a href="#4.4">§4.4</a>); 4333*8e3e3a7aSWarner Loshthese values are then accessible to the function whenever it is called. 4334*8e3e3a7aSWarner LoshTo associate values with a C function, 4335*8e3e3a7aSWarner Loshfirst these values must be pushed onto the stack 4336*8e3e3a7aSWarner Losh(when there are multiple values, the first value is pushed first). 4337*8e3e3a7aSWarner LoshThen <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 4338*8e3e3a7aSWarner Loshis called to create and push the C function onto the stack, 4339*8e3e3a7aSWarner Loshwith the argument <code>n</code> telling how many values will be 4340*8e3e3a7aSWarner Loshassociated with the function. 4341*8e3e3a7aSWarner Losh<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. 4342*8e3e3a7aSWarner Losh 4343*8e3e3a7aSWarner Losh 4344*8e3e3a7aSWarner Losh<p> 4345*8e3e3a7aSWarner LoshThe maximum value for <code>n</code> is 255. 4346*8e3e3a7aSWarner Losh 4347*8e3e3a7aSWarner Losh 4348*8e3e3a7aSWarner Losh<p> 4349*8e3e3a7aSWarner LoshWhen <code>n</code> is zero, 4350*8e3e3a7aSWarner Loshthis function creates a <em>light C function</em>, 4351*8e3e3a7aSWarner Loshwhich is just a pointer to the C function. 4352*8e3e3a7aSWarner LoshIn that case, it never raises a memory error. 4353*8e3e3a7aSWarner Losh 4354*8e3e3a7aSWarner Losh 4355*8e3e3a7aSWarner Losh 4356*8e3e3a7aSWarner Losh 4357*8e3e3a7aSWarner Losh 4358*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> 4359*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 4360*8e3e3a7aSWarner Losh<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> 4361*8e3e3a7aSWarner Losh 4362*8e3e3a7aSWarner Losh<p> 4363*8e3e3a7aSWarner LoshPushes a C function onto the stack. 4364*8e3e3a7aSWarner LoshThis function receives a pointer to a C function 4365*8e3e3a7aSWarner Loshand pushes onto the stack a Lua value of type <code>function</code> that, 4366*8e3e3a7aSWarner Loshwhen called, invokes the corresponding C function. 4367*8e3e3a7aSWarner Losh 4368*8e3e3a7aSWarner Losh 4369*8e3e3a7aSWarner Losh<p> 4370*8e3e3a7aSWarner LoshAny function to be callable by Lua must 4371*8e3e3a7aSWarner Loshfollow the correct protocol to receive its parameters 4372*8e3e3a7aSWarner Loshand return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 4373*8e3e3a7aSWarner Losh 4374*8e3e3a7aSWarner Losh 4375*8e3e3a7aSWarner Losh 4376*8e3e3a7aSWarner Losh 4377*8e3e3a7aSWarner Losh 4378*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> 4379*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 4380*8e3e3a7aSWarner Losh<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> 4381*8e3e3a7aSWarner Losh 4382*8e3e3a7aSWarner Losh<p> 4383*8e3e3a7aSWarner LoshPushes onto the stack a formatted string 4384*8e3e3a7aSWarner Loshand returns a pointer to this string. 4385*8e3e3a7aSWarner LoshIt is similar to the ISO C function <code>sprintf</code>, 4386*8e3e3a7aSWarner Loshbut has some important differences: 4387*8e3e3a7aSWarner Losh 4388*8e3e3a7aSWarner Losh<ul> 4389*8e3e3a7aSWarner Losh 4390*8e3e3a7aSWarner Losh<li> 4391*8e3e3a7aSWarner LoshYou do not have to allocate space for the result: 4392*8e3e3a7aSWarner Loshthe result is a Lua string and Lua takes care of memory allocation 4393*8e3e3a7aSWarner Losh(and deallocation, through garbage collection). 4394*8e3e3a7aSWarner Losh</li> 4395*8e3e3a7aSWarner Losh 4396*8e3e3a7aSWarner Losh<li> 4397*8e3e3a7aSWarner LoshThe conversion specifiers are quite restricted. 4398*8e3e3a7aSWarner LoshThere are no flags, widths, or precisions. 4399*8e3e3a7aSWarner LoshThe conversion specifiers can only be 4400*8e3e3a7aSWarner Losh'<code>%%</code>' (inserts the character '<code>%</code>'), 4401*8e3e3a7aSWarner Losh'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), 4402*8e3e3a7aSWarner Losh'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), 4403*8e3e3a7aSWarner Losh'<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>), 4404*8e3e3a7aSWarner Losh'<code>%p</code>' (inserts a pointer as a hexadecimal numeral), 4405*8e3e3a7aSWarner Losh'<code>%d</code>' (inserts an <code>int</code>), 4406*8e3e3a7aSWarner Losh'<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and 4407*8e3e3a7aSWarner Losh'<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence). 4408*8e3e3a7aSWarner Losh</li> 4409*8e3e3a7aSWarner Losh 4410*8e3e3a7aSWarner Losh</ul> 4411*8e3e3a7aSWarner Losh 4412*8e3e3a7aSWarner Losh<p> 4413*8e3e3a7aSWarner LoshUnlike other push functions, 4414*8e3e3a7aSWarner Loshthis function checks for the stack space it needs, 4415*8e3e3a7aSWarner Loshincluding the slot for its result. 4416*8e3e3a7aSWarner Losh 4417*8e3e3a7aSWarner Losh 4418*8e3e3a7aSWarner Losh 4419*8e3e3a7aSWarner Losh 4420*8e3e3a7aSWarner Losh 4421*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p> 4422*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 4423*8e3e3a7aSWarner Losh<pre>void lua_pushglobaltable (lua_State *L);</pre> 4424*8e3e3a7aSWarner Losh 4425*8e3e3a7aSWarner Losh<p> 4426*8e3e3a7aSWarner LoshPushes the global environment onto the stack. 4427*8e3e3a7aSWarner Losh 4428*8e3e3a7aSWarner Losh 4429*8e3e3a7aSWarner Losh 4430*8e3e3a7aSWarner Losh 4431*8e3e3a7aSWarner Losh 4432*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> 4433*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 4434*8e3e3a7aSWarner Losh<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> 4435*8e3e3a7aSWarner Losh 4436*8e3e3a7aSWarner Losh<p> 4437*8e3e3a7aSWarner LoshPushes an integer with value <code>n</code> onto the stack. 4438*8e3e3a7aSWarner Losh 4439*8e3e3a7aSWarner Losh 4440*8e3e3a7aSWarner Losh 4441*8e3e3a7aSWarner Losh 4442*8e3e3a7aSWarner Losh 4443*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> 4444*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 4445*8e3e3a7aSWarner Losh<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> 4446*8e3e3a7aSWarner Losh 4447*8e3e3a7aSWarner Losh<p> 4448*8e3e3a7aSWarner LoshPushes a light userdata onto the stack. 4449*8e3e3a7aSWarner Losh 4450*8e3e3a7aSWarner Losh 4451*8e3e3a7aSWarner Losh<p> 4452*8e3e3a7aSWarner LoshUserdata represent C values in Lua. 4453*8e3e3a7aSWarner LoshA <em>light userdata</em> represents a pointer, a <code>void*</code>. 4454*8e3e3a7aSWarner LoshIt is a value (like a number): 4455*8e3e3a7aSWarner Loshyou do not create it, it has no individual metatable, 4456*8e3e3a7aSWarner Loshand it is not collected (as it was never created). 4457*8e3e3a7aSWarner LoshA light userdata is equal to "any" 4458*8e3e3a7aSWarner Loshlight userdata with the same C address. 4459*8e3e3a7aSWarner Losh 4460*8e3e3a7aSWarner Losh 4461*8e3e3a7aSWarner Losh 4462*8e3e3a7aSWarner Losh 4463*8e3e3a7aSWarner Losh 4464*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> 4465*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 4466*8e3e3a7aSWarner Losh<pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre> 4467*8e3e3a7aSWarner Losh 4468*8e3e3a7aSWarner Losh<p> 4469*8e3e3a7aSWarner LoshThis macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>, 4470*8e3e3a7aSWarner Loshbut should be used only when <code>s</code> is a literal string. 4471*8e3e3a7aSWarner Losh 4472*8e3e3a7aSWarner Losh 4473*8e3e3a7aSWarner Losh 4474*8e3e3a7aSWarner Losh 4475*8e3e3a7aSWarner Losh 4476*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> 4477*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 4478*8e3e3a7aSWarner Losh<pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> 4479*8e3e3a7aSWarner Losh 4480*8e3e3a7aSWarner Losh<p> 4481*8e3e3a7aSWarner LoshPushes the string pointed to by <code>s</code> with size <code>len</code> 4482*8e3e3a7aSWarner Loshonto the stack. 4483*8e3e3a7aSWarner LoshLua makes (or reuses) an internal copy of the given string, 4484*8e3e3a7aSWarner Loshso the memory at <code>s</code> can be freed or reused immediately after 4485*8e3e3a7aSWarner Loshthe function returns. 4486*8e3e3a7aSWarner LoshThe string can contain any binary data, 4487*8e3e3a7aSWarner Loshincluding embedded zeros. 4488*8e3e3a7aSWarner Losh 4489*8e3e3a7aSWarner Losh 4490*8e3e3a7aSWarner Losh<p> 4491*8e3e3a7aSWarner LoshReturns a pointer to the internal copy of the string. 4492*8e3e3a7aSWarner Losh 4493*8e3e3a7aSWarner Losh 4494*8e3e3a7aSWarner Losh 4495*8e3e3a7aSWarner Losh 4496*8e3e3a7aSWarner Losh 4497*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> 4498*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 4499*8e3e3a7aSWarner Losh<pre>void lua_pushnil (lua_State *L);</pre> 4500*8e3e3a7aSWarner Losh 4501*8e3e3a7aSWarner Losh<p> 4502*8e3e3a7aSWarner LoshPushes a nil value onto the stack. 4503*8e3e3a7aSWarner Losh 4504*8e3e3a7aSWarner Losh 4505*8e3e3a7aSWarner Losh 4506*8e3e3a7aSWarner Losh 4507*8e3e3a7aSWarner Losh 4508*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> 4509*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 4510*8e3e3a7aSWarner Losh<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> 4511*8e3e3a7aSWarner Losh 4512*8e3e3a7aSWarner Losh<p> 4513*8e3e3a7aSWarner LoshPushes a float with value <code>n</code> onto the stack. 4514*8e3e3a7aSWarner Losh 4515*8e3e3a7aSWarner Losh 4516*8e3e3a7aSWarner Losh 4517*8e3e3a7aSWarner Losh 4518*8e3e3a7aSWarner Losh 4519*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> 4520*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 4521*8e3e3a7aSWarner Losh<pre>const char *lua_pushstring (lua_State *L, const char *s);</pre> 4522*8e3e3a7aSWarner Losh 4523*8e3e3a7aSWarner Losh<p> 4524*8e3e3a7aSWarner LoshPushes the zero-terminated string pointed to by <code>s</code> 4525*8e3e3a7aSWarner Loshonto the stack. 4526*8e3e3a7aSWarner LoshLua makes (or reuses) an internal copy of the given string, 4527*8e3e3a7aSWarner Loshso the memory at <code>s</code> can be freed or reused immediately after 4528*8e3e3a7aSWarner Loshthe function returns. 4529*8e3e3a7aSWarner Losh 4530*8e3e3a7aSWarner Losh 4531*8e3e3a7aSWarner Losh<p> 4532*8e3e3a7aSWarner LoshReturns a pointer to the internal copy of the string. 4533*8e3e3a7aSWarner Losh 4534*8e3e3a7aSWarner Losh 4535*8e3e3a7aSWarner Losh<p> 4536*8e3e3a7aSWarner LoshIf <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>. 4537*8e3e3a7aSWarner Losh 4538*8e3e3a7aSWarner Losh 4539*8e3e3a7aSWarner Losh 4540*8e3e3a7aSWarner Losh 4541*8e3e3a7aSWarner Losh 4542*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> 4543*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 4544*8e3e3a7aSWarner Losh<pre>int lua_pushthread (lua_State *L);</pre> 4545*8e3e3a7aSWarner Losh 4546*8e3e3a7aSWarner Losh<p> 4547*8e3e3a7aSWarner LoshPushes the thread represented by <code>L</code> onto the stack. 4548*8e3e3a7aSWarner LoshReturns 1 if this thread is the main thread of its state. 4549*8e3e3a7aSWarner Losh 4550*8e3e3a7aSWarner Losh 4551*8e3e3a7aSWarner Losh 4552*8e3e3a7aSWarner Losh 4553*8e3e3a7aSWarner Losh 4554*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> 4555*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 4556*8e3e3a7aSWarner Losh<pre>void lua_pushvalue (lua_State *L, int index);</pre> 4557*8e3e3a7aSWarner Losh 4558*8e3e3a7aSWarner Losh<p> 4559*8e3e3a7aSWarner LoshPushes a copy of the element at the given index 4560*8e3e3a7aSWarner Loshonto the stack. 4561*8e3e3a7aSWarner Losh 4562*8e3e3a7aSWarner Losh 4563*8e3e3a7aSWarner Losh 4564*8e3e3a7aSWarner Losh 4565*8e3e3a7aSWarner Losh 4566*8e3e3a7aSWarner Losh<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> 4567*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 4568*8e3e3a7aSWarner Losh<pre>const char *lua_pushvfstring (lua_State *L, 4569*8e3e3a7aSWarner Losh const char *fmt, 4570*8e3e3a7aSWarner Losh va_list argp);</pre> 4571*8e3e3a7aSWarner Losh 4572*8e3e3a7aSWarner Losh<p> 4573*8e3e3a7aSWarner LoshEquivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> 4574*8e3e3a7aSWarner Loshinstead of a variable number of arguments. 4575*8e3e3a7aSWarner Losh 4576*8e3e3a7aSWarner Losh 4577*8e3e3a7aSWarner Losh 4578*8e3e3a7aSWarner Losh 4579*8e3e3a7aSWarner Losh 4580*8e3e3a7aSWarner Losh<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> 4581*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 4582*8e3e3a7aSWarner Losh<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> 4583*8e3e3a7aSWarner Losh 4584*8e3e3a7aSWarner Losh<p> 4585*8e3e3a7aSWarner LoshReturns 1 if the two values in indices <code>index1</code> and 4586*8e3e3a7aSWarner Losh<code>index2</code> are primitively equal 4587*8e3e3a7aSWarner Losh(that is, without calling the <code>__eq</code> metamethod). 4588*8e3e3a7aSWarner LoshOtherwise returns 0. 4589*8e3e3a7aSWarner LoshAlso returns 0 if any of the indices are not valid. 4590*8e3e3a7aSWarner Losh 4591*8e3e3a7aSWarner Losh 4592*8e3e3a7aSWarner Losh 4593*8e3e3a7aSWarner Losh 4594*8e3e3a7aSWarner Losh 4595*8e3e3a7aSWarner Losh<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> 4596*8e3e3a7aSWarner Losh<span class="apii">[-1, +1, –]</span> 4597*8e3e3a7aSWarner Losh<pre>int lua_rawget (lua_State *L, int index);</pre> 4598*8e3e3a7aSWarner Losh 4599*8e3e3a7aSWarner Losh<p> 4600*8e3e3a7aSWarner LoshSimilar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access 4601*8e3e3a7aSWarner Losh(i.e., without metamethods). 4602*8e3e3a7aSWarner Losh 4603*8e3e3a7aSWarner Losh 4604*8e3e3a7aSWarner Losh 4605*8e3e3a7aSWarner Losh 4606*8e3e3a7aSWarner Losh 4607*8e3e3a7aSWarner Losh<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> 4608*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 4609*8e3e3a7aSWarner Losh<pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre> 4610*8e3e3a7aSWarner Losh 4611*8e3e3a7aSWarner Losh<p> 4612*8e3e3a7aSWarner LoshPushes onto the stack the value <code>t[n]</code>, 4613*8e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index. 4614*8e3e3a7aSWarner LoshThe access is raw, 4615*8e3e3a7aSWarner Loshthat is, it does not invoke the <code>__index</code> metamethod. 4616*8e3e3a7aSWarner Losh 4617*8e3e3a7aSWarner Losh 4618*8e3e3a7aSWarner Losh<p> 4619*8e3e3a7aSWarner LoshReturns the type of the pushed value. 4620*8e3e3a7aSWarner Losh 4621*8e3e3a7aSWarner Losh 4622*8e3e3a7aSWarner Losh 4623*8e3e3a7aSWarner Losh 4624*8e3e3a7aSWarner Losh 4625*8e3e3a7aSWarner Losh<hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p> 4626*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 4627*8e3e3a7aSWarner Losh<pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre> 4628*8e3e3a7aSWarner Losh 4629*8e3e3a7aSWarner Losh<p> 4630*8e3e3a7aSWarner LoshPushes onto the stack the value <code>t[k]</code>, 4631*8e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index and 4632*8e3e3a7aSWarner Losh<code>k</code> is the pointer <code>p</code> represented as a light userdata. 4633*8e3e3a7aSWarner LoshThe access is raw; 4634*8e3e3a7aSWarner Loshthat is, it does not invoke the <code>__index</code> metamethod. 4635*8e3e3a7aSWarner Losh 4636*8e3e3a7aSWarner Losh 4637*8e3e3a7aSWarner Losh<p> 4638*8e3e3a7aSWarner LoshReturns the type of the pushed value. 4639*8e3e3a7aSWarner Losh 4640*8e3e3a7aSWarner Losh 4641*8e3e3a7aSWarner Losh 4642*8e3e3a7aSWarner Losh 4643*8e3e3a7aSWarner Losh 4644*8e3e3a7aSWarner Losh<hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p> 4645*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 4646*8e3e3a7aSWarner Losh<pre>size_t lua_rawlen (lua_State *L, int index);</pre> 4647*8e3e3a7aSWarner Losh 4648*8e3e3a7aSWarner Losh<p> 4649*8e3e3a7aSWarner LoshReturns the raw "length" of the value at the given index: 4650*8e3e3a7aSWarner Loshfor strings, this is the string length; 4651*8e3e3a7aSWarner Loshfor tables, this is the result of the length operator ('<code>#</code>') 4652*8e3e3a7aSWarner Loshwith no metamethods; 4653*8e3e3a7aSWarner Loshfor userdata, this is the size of the block of memory allocated 4654*8e3e3a7aSWarner Loshfor the userdata; 4655*8e3e3a7aSWarner Loshfor other values, it is 0. 4656*8e3e3a7aSWarner Losh 4657*8e3e3a7aSWarner Losh 4658*8e3e3a7aSWarner Losh 4659*8e3e3a7aSWarner Losh 4660*8e3e3a7aSWarner Losh 4661*8e3e3a7aSWarner Losh<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> 4662*8e3e3a7aSWarner Losh<span class="apii">[-2, +0, <em>m</em>]</span> 4663*8e3e3a7aSWarner Losh<pre>void lua_rawset (lua_State *L, int index);</pre> 4664*8e3e3a7aSWarner Losh 4665*8e3e3a7aSWarner Losh<p> 4666*8e3e3a7aSWarner LoshSimilar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment 4667*8e3e3a7aSWarner Losh(i.e., without metamethods). 4668*8e3e3a7aSWarner Losh 4669*8e3e3a7aSWarner Losh 4670*8e3e3a7aSWarner Losh 4671*8e3e3a7aSWarner Losh 4672*8e3e3a7aSWarner Losh 4673*8e3e3a7aSWarner Losh<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> 4674*8e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span> 4675*8e3e3a7aSWarner Losh<pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre> 4676*8e3e3a7aSWarner Losh 4677*8e3e3a7aSWarner Losh<p> 4678*8e3e3a7aSWarner LoshDoes the equivalent of <code>t[i] = v</code>, 4679*8e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index 4680*8e3e3a7aSWarner Loshand <code>v</code> is the value at the top of the stack. 4681*8e3e3a7aSWarner Losh 4682*8e3e3a7aSWarner Losh 4683*8e3e3a7aSWarner Losh<p> 4684*8e3e3a7aSWarner LoshThis function pops the value from the stack. 4685*8e3e3a7aSWarner LoshThe assignment is raw, 4686*8e3e3a7aSWarner Loshthat is, it does not invoke the <code>__newindex</code> metamethod. 4687*8e3e3a7aSWarner Losh 4688*8e3e3a7aSWarner Losh 4689*8e3e3a7aSWarner Losh 4690*8e3e3a7aSWarner Losh 4691*8e3e3a7aSWarner Losh 4692*8e3e3a7aSWarner Losh<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p> 4693*8e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span> 4694*8e3e3a7aSWarner Losh<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre> 4695*8e3e3a7aSWarner Losh 4696*8e3e3a7aSWarner Losh<p> 4697*8e3e3a7aSWarner LoshDoes the equivalent of <code>t[p] = v</code>, 4698*8e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index, 4699*8e3e3a7aSWarner Losh<code>p</code> is encoded as a light userdata, 4700*8e3e3a7aSWarner Loshand <code>v</code> is the value at the top of the stack. 4701*8e3e3a7aSWarner Losh 4702*8e3e3a7aSWarner Losh 4703*8e3e3a7aSWarner Losh<p> 4704*8e3e3a7aSWarner LoshThis function pops the value from the stack. 4705*8e3e3a7aSWarner LoshThe assignment is raw, 4706*8e3e3a7aSWarner Loshthat is, it does not invoke <code>__newindex</code> metamethod. 4707*8e3e3a7aSWarner Losh 4708*8e3e3a7aSWarner Losh 4709*8e3e3a7aSWarner Losh 4710*8e3e3a7aSWarner Losh 4711*8e3e3a7aSWarner Losh 4712*8e3e3a7aSWarner Losh<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> 4713*8e3e3a7aSWarner Losh<pre>typedef const char * (*lua_Reader) (lua_State *L, 4714*8e3e3a7aSWarner Losh void *data, 4715*8e3e3a7aSWarner Losh size_t *size);</pre> 4716*8e3e3a7aSWarner Losh 4717*8e3e3a7aSWarner Losh<p> 4718*8e3e3a7aSWarner LoshThe reader function used by <a href="#lua_load"><code>lua_load</code></a>. 4719*8e3e3a7aSWarner LoshEvery time it needs another piece of the chunk, 4720*8e3e3a7aSWarner Losh<a href="#lua_load"><code>lua_load</code></a> calls the reader, 4721*8e3e3a7aSWarner Loshpassing along its <code>data</code> parameter. 4722*8e3e3a7aSWarner LoshThe reader must return a pointer to a block of memory 4723*8e3e3a7aSWarner Loshwith a new piece of the chunk 4724*8e3e3a7aSWarner Loshand set <code>size</code> to the block size. 4725*8e3e3a7aSWarner LoshThe block must exist until the reader function is called again. 4726*8e3e3a7aSWarner LoshTo signal the end of the chunk, 4727*8e3e3a7aSWarner Loshthe reader must return <code>NULL</code> or set <code>size</code> to zero. 4728*8e3e3a7aSWarner LoshThe reader function may return pieces of any size greater than zero. 4729*8e3e3a7aSWarner Losh 4730*8e3e3a7aSWarner Losh 4731*8e3e3a7aSWarner Losh 4732*8e3e3a7aSWarner Losh 4733*8e3e3a7aSWarner Losh 4734*8e3e3a7aSWarner Losh<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> 4735*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 4736*8e3e3a7aSWarner Losh<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre> 4737*8e3e3a7aSWarner Losh 4738*8e3e3a7aSWarner Losh<p> 4739*8e3e3a7aSWarner LoshSets the C function <code>f</code> as the new value of global <code>name</code>. 4740*8e3e3a7aSWarner LoshIt is defined as a macro: 4741*8e3e3a7aSWarner Losh 4742*8e3e3a7aSWarner Losh<pre> 4743*8e3e3a7aSWarner Losh #define lua_register(L,n,f) \ 4744*8e3e3a7aSWarner Losh (lua_pushcfunction(L, f), lua_setglobal(L, n)) 4745*8e3e3a7aSWarner Losh</pre> 4746*8e3e3a7aSWarner Losh 4747*8e3e3a7aSWarner Losh 4748*8e3e3a7aSWarner Losh 4749*8e3e3a7aSWarner Losh 4750*8e3e3a7aSWarner Losh<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> 4751*8e3e3a7aSWarner Losh<span class="apii">[-1, +0, –]</span> 4752*8e3e3a7aSWarner Losh<pre>void lua_remove (lua_State *L, int index);</pre> 4753*8e3e3a7aSWarner Losh 4754*8e3e3a7aSWarner Losh<p> 4755*8e3e3a7aSWarner LoshRemoves the element at the given valid index, 4756*8e3e3a7aSWarner Loshshifting down the elements above this index to fill the gap. 4757*8e3e3a7aSWarner LoshThis function cannot be called with a pseudo-index, 4758*8e3e3a7aSWarner Loshbecause a pseudo-index is not an actual stack position. 4759*8e3e3a7aSWarner Losh 4760*8e3e3a7aSWarner Losh 4761*8e3e3a7aSWarner Losh 4762*8e3e3a7aSWarner Losh 4763*8e3e3a7aSWarner Losh 4764*8e3e3a7aSWarner Losh<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> 4765*8e3e3a7aSWarner Losh<span class="apii">[-1, +0, –]</span> 4766*8e3e3a7aSWarner Losh<pre>void lua_replace (lua_State *L, int index);</pre> 4767*8e3e3a7aSWarner Losh 4768*8e3e3a7aSWarner Losh<p> 4769*8e3e3a7aSWarner LoshMoves the top element into the given valid index 4770*8e3e3a7aSWarner Loshwithout shifting any element 4771*8e3e3a7aSWarner Losh(therefore replacing the value at that given index), 4772*8e3e3a7aSWarner Loshand then pops the top element. 4773*8e3e3a7aSWarner Losh 4774*8e3e3a7aSWarner Losh 4775*8e3e3a7aSWarner Losh 4776*8e3e3a7aSWarner Losh 4777*8e3e3a7aSWarner Losh 4778*8e3e3a7aSWarner Losh<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> 4779*8e3e3a7aSWarner Losh<span class="apii">[-?, +?, –]</span> 4780*8e3e3a7aSWarner Losh<pre>int lua_resume (lua_State *L, lua_State *from, int nargs);</pre> 4781*8e3e3a7aSWarner Losh 4782*8e3e3a7aSWarner Losh<p> 4783*8e3e3a7aSWarner LoshStarts and resumes a coroutine in the given thread <code>L</code>. 4784*8e3e3a7aSWarner Losh 4785*8e3e3a7aSWarner Losh 4786*8e3e3a7aSWarner Losh<p> 4787*8e3e3a7aSWarner LoshTo start a coroutine, 4788*8e3e3a7aSWarner Loshyou push onto the thread stack the main function plus any arguments; 4789*8e3e3a7aSWarner Loshthen you call <a href="#lua_resume"><code>lua_resume</code></a>, 4790*8e3e3a7aSWarner Loshwith <code>nargs</code> being the number of arguments. 4791*8e3e3a7aSWarner LoshThis call returns when the coroutine suspends or finishes its execution. 4792*8e3e3a7aSWarner LoshWhen it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>, 4793*8e3e3a7aSWarner Loshor all values returned by the body function. 4794*8e3e3a7aSWarner Losh<a href="#lua_resume"><code>lua_resume</code></a> returns 4795*8e3e3a7aSWarner Losh<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, 4796*8e3e3a7aSWarner Losh<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution 4797*8e3e3a7aSWarner Loshwithout errors, 4798*8e3e3a7aSWarner Loshor an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). 4799*8e3e3a7aSWarner Losh 4800*8e3e3a7aSWarner Losh 4801*8e3e3a7aSWarner Losh<p> 4802*8e3e3a7aSWarner LoshIn case of errors, 4803*8e3e3a7aSWarner Loshthe stack is not unwound, 4804*8e3e3a7aSWarner Loshso you can use the debug API over it. 4805*8e3e3a7aSWarner LoshThe error object is on the top of the stack. 4806*8e3e3a7aSWarner Losh 4807*8e3e3a7aSWarner Losh 4808*8e3e3a7aSWarner Losh<p> 4809*8e3e3a7aSWarner LoshTo resume a coroutine, 4810*8e3e3a7aSWarner Loshyou remove any results from the last <a href="#lua_yield"><code>lua_yield</code></a>, 4811*8e3e3a7aSWarner Loshput on its stack only the values to 4812*8e3e3a7aSWarner Loshbe passed as results from <code>yield</code>, 4813*8e3e3a7aSWarner Loshand then call <a href="#lua_resume"><code>lua_resume</code></a>. 4814*8e3e3a7aSWarner Losh 4815*8e3e3a7aSWarner Losh 4816*8e3e3a7aSWarner Losh<p> 4817*8e3e3a7aSWarner LoshThe parameter <code>from</code> represents the coroutine that is resuming <code>L</code>. 4818*8e3e3a7aSWarner LoshIf there is no such coroutine, 4819*8e3e3a7aSWarner Loshthis parameter can be <code>NULL</code>. 4820*8e3e3a7aSWarner Losh 4821*8e3e3a7aSWarner Losh 4822*8e3e3a7aSWarner Losh 4823*8e3e3a7aSWarner Losh 4824*8e3e3a7aSWarner Losh 4825*8e3e3a7aSWarner Losh<hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p> 4826*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 4827*8e3e3a7aSWarner Losh<pre>void lua_rotate (lua_State *L, int idx, int n);</pre> 4828*8e3e3a7aSWarner Losh 4829*8e3e3a7aSWarner Losh<p> 4830*8e3e3a7aSWarner LoshRotates the stack elements between the valid index <code>idx</code> 4831*8e3e3a7aSWarner Loshand the top of the stack. 4832*8e3e3a7aSWarner LoshThe elements are rotated <code>n</code> positions in the direction of the top, 4833*8e3e3a7aSWarner Loshfor a positive <code>n</code>, 4834*8e3e3a7aSWarner Loshor <code>-n</code> positions in the direction of the bottom, 4835*8e3e3a7aSWarner Loshfor a negative <code>n</code>. 4836*8e3e3a7aSWarner LoshThe absolute value of <code>n</code> must not be greater than the size 4837*8e3e3a7aSWarner Loshof the slice being rotated. 4838*8e3e3a7aSWarner LoshThis function cannot be called with a pseudo-index, 4839*8e3e3a7aSWarner Loshbecause a pseudo-index is not an actual stack position. 4840*8e3e3a7aSWarner Losh 4841*8e3e3a7aSWarner Losh 4842*8e3e3a7aSWarner Losh 4843*8e3e3a7aSWarner Losh 4844*8e3e3a7aSWarner Losh 4845*8e3e3a7aSWarner Losh<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> 4846*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 4847*8e3e3a7aSWarner Losh<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> 4848*8e3e3a7aSWarner Losh 4849*8e3e3a7aSWarner Losh<p> 4850*8e3e3a7aSWarner LoshChanges the allocator function of a given state to <code>f</code> 4851*8e3e3a7aSWarner Loshwith user data <code>ud</code>. 4852*8e3e3a7aSWarner Losh 4853*8e3e3a7aSWarner Losh 4854*8e3e3a7aSWarner Losh 4855*8e3e3a7aSWarner Losh 4856*8e3e3a7aSWarner Losh 4857*8e3e3a7aSWarner Losh<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> 4858*8e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>e</em>]</span> 4859*8e3e3a7aSWarner Losh<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> 4860*8e3e3a7aSWarner Losh 4861*8e3e3a7aSWarner Losh<p> 4862*8e3e3a7aSWarner LoshDoes the equivalent to <code>t[k] = v</code>, 4863*8e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index 4864*8e3e3a7aSWarner Loshand <code>v</code> is the value at the top of the stack. 4865*8e3e3a7aSWarner Losh 4866*8e3e3a7aSWarner Losh 4867*8e3e3a7aSWarner Losh<p> 4868*8e3e3a7aSWarner LoshThis function pops the value from the stack. 4869*8e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 4870*8e3e3a7aSWarner Loshfor the "newindex" event (see <a href="#2.4">§2.4</a>). 4871*8e3e3a7aSWarner Losh 4872*8e3e3a7aSWarner Losh 4873*8e3e3a7aSWarner Losh 4874*8e3e3a7aSWarner Losh 4875*8e3e3a7aSWarner Losh 4876*8e3e3a7aSWarner Losh<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> 4877*8e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>e</em>]</span> 4878*8e3e3a7aSWarner Losh<pre>void lua_setglobal (lua_State *L, const char *name);</pre> 4879*8e3e3a7aSWarner Losh 4880*8e3e3a7aSWarner Losh<p> 4881*8e3e3a7aSWarner LoshPops a value from the stack and 4882*8e3e3a7aSWarner Loshsets it as the new value of global <code>name</code>. 4883*8e3e3a7aSWarner Losh 4884*8e3e3a7aSWarner Losh 4885*8e3e3a7aSWarner Losh 4886*8e3e3a7aSWarner Losh 4887*8e3e3a7aSWarner Losh 4888*8e3e3a7aSWarner Losh<hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p> 4889*8e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>e</em>]</span> 4890*8e3e3a7aSWarner Losh<pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre> 4891*8e3e3a7aSWarner Losh 4892*8e3e3a7aSWarner Losh<p> 4893*8e3e3a7aSWarner LoshDoes the equivalent to <code>t[n] = v</code>, 4894*8e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index 4895*8e3e3a7aSWarner Loshand <code>v</code> is the value at the top of the stack. 4896*8e3e3a7aSWarner Losh 4897*8e3e3a7aSWarner Losh 4898*8e3e3a7aSWarner Losh<p> 4899*8e3e3a7aSWarner LoshThis function pops the value from the stack. 4900*8e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 4901*8e3e3a7aSWarner Loshfor the "newindex" event (see <a href="#2.4">§2.4</a>). 4902*8e3e3a7aSWarner Losh 4903*8e3e3a7aSWarner Losh 4904*8e3e3a7aSWarner Losh 4905*8e3e3a7aSWarner Losh 4906*8e3e3a7aSWarner Losh 4907*8e3e3a7aSWarner Losh<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> 4908*8e3e3a7aSWarner Losh<span class="apii">[-1, +0, –]</span> 4909*8e3e3a7aSWarner Losh<pre>void lua_setmetatable (lua_State *L, int index);</pre> 4910*8e3e3a7aSWarner Losh 4911*8e3e3a7aSWarner Losh<p> 4912*8e3e3a7aSWarner LoshPops a table from the stack and 4913*8e3e3a7aSWarner Loshsets it as the new metatable for the value at the given index. 4914*8e3e3a7aSWarner Losh 4915*8e3e3a7aSWarner Losh 4916*8e3e3a7aSWarner Losh 4917*8e3e3a7aSWarner Losh 4918*8e3e3a7aSWarner Losh 4919*8e3e3a7aSWarner Losh<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> 4920*8e3e3a7aSWarner Losh<span class="apii">[-2, +0, <em>e</em>]</span> 4921*8e3e3a7aSWarner Losh<pre>void lua_settable (lua_State *L, int index);</pre> 4922*8e3e3a7aSWarner Losh 4923*8e3e3a7aSWarner Losh<p> 4924*8e3e3a7aSWarner LoshDoes the equivalent to <code>t[k] = v</code>, 4925*8e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index, 4926*8e3e3a7aSWarner Losh<code>v</code> is the value at the top of the stack, 4927*8e3e3a7aSWarner Loshand <code>k</code> is the value just below the top. 4928*8e3e3a7aSWarner Losh 4929*8e3e3a7aSWarner Losh 4930*8e3e3a7aSWarner Losh<p> 4931*8e3e3a7aSWarner LoshThis function pops both the key and the value from the stack. 4932*8e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 4933*8e3e3a7aSWarner Loshfor the "newindex" event (see <a href="#2.4">§2.4</a>). 4934*8e3e3a7aSWarner Losh 4935*8e3e3a7aSWarner Losh 4936*8e3e3a7aSWarner Losh 4937*8e3e3a7aSWarner Losh 4938*8e3e3a7aSWarner Losh 4939*8e3e3a7aSWarner Losh<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> 4940*8e3e3a7aSWarner Losh<span class="apii">[-?, +?, –]</span> 4941*8e3e3a7aSWarner Losh<pre>void lua_settop (lua_State *L, int index);</pre> 4942*8e3e3a7aSWarner Losh 4943*8e3e3a7aSWarner Losh<p> 4944*8e3e3a7aSWarner LoshAccepts any index, or 0, 4945*8e3e3a7aSWarner Loshand sets the stack top to this index. 4946*8e3e3a7aSWarner LoshIf the new top is larger than the old one, 4947*8e3e3a7aSWarner Loshthen the new elements are filled with <b>nil</b>. 4948*8e3e3a7aSWarner LoshIf <code>index</code> is 0, then all stack elements are removed. 4949*8e3e3a7aSWarner Losh 4950*8e3e3a7aSWarner Losh 4951*8e3e3a7aSWarner Losh 4952*8e3e3a7aSWarner Losh 4953*8e3e3a7aSWarner Losh 4954*8e3e3a7aSWarner Losh<hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p> 4955*8e3e3a7aSWarner Losh<span class="apii">[-1, +0, –]</span> 4956*8e3e3a7aSWarner Losh<pre>void lua_setuservalue (lua_State *L, int index);</pre> 4957*8e3e3a7aSWarner Losh 4958*8e3e3a7aSWarner Losh<p> 4959*8e3e3a7aSWarner LoshPops a value from the stack and sets it as 4960*8e3e3a7aSWarner Loshthe new value associated to the full userdata at the given index. 4961*8e3e3a7aSWarner Losh 4962*8e3e3a7aSWarner Losh 4963*8e3e3a7aSWarner Losh 4964*8e3e3a7aSWarner Losh 4965*8e3e3a7aSWarner Losh 4966*8e3e3a7aSWarner Losh<hr><h3><a name="lua_State"><code>lua_State</code></a></h3> 4967*8e3e3a7aSWarner Losh<pre>typedef struct lua_State lua_State;</pre> 4968*8e3e3a7aSWarner Losh 4969*8e3e3a7aSWarner Losh<p> 4970*8e3e3a7aSWarner LoshAn opaque structure that points to a thread and indirectly 4971*8e3e3a7aSWarner Losh(through the thread) to the whole state of a Lua interpreter. 4972*8e3e3a7aSWarner LoshThe Lua library is fully reentrant: 4973*8e3e3a7aSWarner Loshit has no global variables. 4974*8e3e3a7aSWarner LoshAll information about a state is accessible through this structure. 4975*8e3e3a7aSWarner Losh 4976*8e3e3a7aSWarner Losh 4977*8e3e3a7aSWarner Losh<p> 4978*8e3e3a7aSWarner LoshA pointer to this structure must be passed as the first argument to 4979*8e3e3a7aSWarner Loshevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 4980*8e3e3a7aSWarner Loshwhich creates a Lua state from scratch. 4981*8e3e3a7aSWarner Losh 4982*8e3e3a7aSWarner Losh 4983*8e3e3a7aSWarner Losh 4984*8e3e3a7aSWarner Losh 4985*8e3e3a7aSWarner Losh 4986*8e3e3a7aSWarner Losh<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> 4987*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 4988*8e3e3a7aSWarner Losh<pre>int lua_status (lua_State *L);</pre> 4989*8e3e3a7aSWarner Losh 4990*8e3e3a7aSWarner Losh<p> 4991*8e3e3a7aSWarner LoshReturns the status of the thread <code>L</code>. 4992*8e3e3a7aSWarner Losh 4993*8e3e3a7aSWarner Losh 4994*8e3e3a7aSWarner Losh<p> 4995*8e3e3a7aSWarner LoshThe status can be 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) for a normal thread, 4996*8e3e3a7aSWarner Loshan error code if the thread finished the execution 4997*8e3e3a7aSWarner Loshof a <a href="#lua_resume"><code>lua_resume</code></a> with an error, 4998*8e3e3a7aSWarner Loshor <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. 4999*8e3e3a7aSWarner Losh 5000*8e3e3a7aSWarner Losh 5001*8e3e3a7aSWarner Losh<p> 5002*8e3e3a7aSWarner LoshYou can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>. 5003*8e3e3a7aSWarner LoshYou can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> 5004*8e3e3a7aSWarner Losh(to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> 5005*8e3e3a7aSWarner Losh(to resume a coroutine). 5006*8e3e3a7aSWarner Losh 5007*8e3e3a7aSWarner Losh 5008*8e3e3a7aSWarner Losh 5009*8e3e3a7aSWarner Losh 5010*8e3e3a7aSWarner Losh 5011*8e3e3a7aSWarner Losh<hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p> 5012*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 5013*8e3e3a7aSWarner Losh<pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre> 5014*8e3e3a7aSWarner Losh 5015*8e3e3a7aSWarner Losh<p> 5016*8e3e3a7aSWarner LoshConverts the zero-terminated string <code>s</code> to a number, 5017*8e3e3a7aSWarner Loshpushes that number into the stack, 5018*8e3e3a7aSWarner Loshand returns the total size of the string, 5019*8e3e3a7aSWarner Loshthat is, its length plus one. 5020*8e3e3a7aSWarner LoshThe conversion can result in an integer or a float, 5021*8e3e3a7aSWarner Loshaccording to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 5022*8e3e3a7aSWarner LoshThe string may have leading and trailing spaces and a sign. 5023*8e3e3a7aSWarner LoshIf the string is not a valid numeral, 5024*8e3e3a7aSWarner Loshreturns 0 and pushes nothing. 5025*8e3e3a7aSWarner Losh(Note that the result can be used as a boolean, 5026*8e3e3a7aSWarner Loshtrue if the conversion succeeds.) 5027*8e3e3a7aSWarner Losh 5028*8e3e3a7aSWarner Losh 5029*8e3e3a7aSWarner Losh 5030*8e3e3a7aSWarner Losh 5031*8e3e3a7aSWarner Losh 5032*8e3e3a7aSWarner Losh<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> 5033*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5034*8e3e3a7aSWarner Losh<pre>int lua_toboolean (lua_State *L, int index);</pre> 5035*8e3e3a7aSWarner Losh 5036*8e3e3a7aSWarner Losh<p> 5037*8e3e3a7aSWarner LoshConverts the Lua value at the given index to a C boolean 5038*8e3e3a7aSWarner Loshvalue (0 or 1). 5039*8e3e3a7aSWarner LoshLike all tests in Lua, 5040*8e3e3a7aSWarner Losh<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value 5041*8e3e3a7aSWarner Loshdifferent from <b>false</b> and <b>nil</b>; 5042*8e3e3a7aSWarner Loshotherwise it returns false. 5043*8e3e3a7aSWarner Losh(If you want to accept only actual boolean values, 5044*8e3e3a7aSWarner Loshuse <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) 5045*8e3e3a7aSWarner Losh 5046*8e3e3a7aSWarner Losh 5047*8e3e3a7aSWarner Losh 5048*8e3e3a7aSWarner Losh 5049*8e3e3a7aSWarner Losh 5050*8e3e3a7aSWarner Losh<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> 5051*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5052*8e3e3a7aSWarner Losh<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> 5053*8e3e3a7aSWarner Losh 5054*8e3e3a7aSWarner Losh<p> 5055*8e3e3a7aSWarner LoshConverts a value at the given index to a C function. 5056*8e3e3a7aSWarner LoshThat value must be a C function; 5057*8e3e3a7aSWarner Loshotherwise, returns <code>NULL</code>. 5058*8e3e3a7aSWarner Losh 5059*8e3e3a7aSWarner Losh 5060*8e3e3a7aSWarner Losh 5061*8e3e3a7aSWarner Losh 5062*8e3e3a7aSWarner Losh 5063*8e3e3a7aSWarner Losh<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> 5064*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5065*8e3e3a7aSWarner Losh<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> 5066*8e3e3a7aSWarner Losh 5067*8e3e3a7aSWarner Losh<p> 5068*8e3e3a7aSWarner LoshEquivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5069*8e3e3a7aSWarner Losh 5070*8e3e3a7aSWarner Losh 5071*8e3e3a7aSWarner Losh 5072*8e3e3a7aSWarner Losh 5073*8e3e3a7aSWarner Losh 5074*8e3e3a7aSWarner Losh<hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p> 5075*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5076*8e3e3a7aSWarner Losh<pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre> 5077*8e3e3a7aSWarner Losh 5078*8e3e3a7aSWarner Losh<p> 5079*8e3e3a7aSWarner LoshConverts the Lua value at the given index 5080*8e3e3a7aSWarner Loshto the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. 5081*8e3e3a7aSWarner LoshThe Lua value must be an integer, 5082*8e3e3a7aSWarner Loshor a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>); 5083*8e3e3a7aSWarner Loshotherwise, <code>lua_tointegerx</code> returns 0. 5084*8e3e3a7aSWarner Losh 5085*8e3e3a7aSWarner Losh 5086*8e3e3a7aSWarner Losh<p> 5087*8e3e3a7aSWarner LoshIf <code>isnum</code> is not <code>NULL</code>, 5088*8e3e3a7aSWarner Loshits referent is assigned a boolean value that 5089*8e3e3a7aSWarner Loshindicates whether the operation succeeded. 5090*8e3e3a7aSWarner Losh 5091*8e3e3a7aSWarner Losh 5092*8e3e3a7aSWarner Losh 5093*8e3e3a7aSWarner Losh 5094*8e3e3a7aSWarner Losh 5095*8e3e3a7aSWarner Losh<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> 5096*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span> 5097*8e3e3a7aSWarner Losh<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> 5098*8e3e3a7aSWarner Losh 5099*8e3e3a7aSWarner Losh<p> 5100*8e3e3a7aSWarner LoshConverts the Lua value at the given index to a C string. 5101*8e3e3a7aSWarner LoshIf <code>len</code> is not <code>NULL</code>, 5102*8e3e3a7aSWarner Loshit sets <code>*len</code> with the string length. 5103*8e3e3a7aSWarner LoshThe Lua value must be a string or a number; 5104*8e3e3a7aSWarner Loshotherwise, the function returns <code>NULL</code>. 5105*8e3e3a7aSWarner LoshIf the value is a number, 5106*8e3e3a7aSWarner Loshthen <code>lua_tolstring</code> also 5107*8e3e3a7aSWarner Losh<em>changes the actual value in the stack to a string</em>. 5108*8e3e3a7aSWarner Losh(This change confuses <a href="#lua_next"><code>lua_next</code></a> 5109*8e3e3a7aSWarner Loshwhen <code>lua_tolstring</code> is applied to keys during a table traversal.) 5110*8e3e3a7aSWarner Losh 5111*8e3e3a7aSWarner Losh 5112*8e3e3a7aSWarner Losh<p> 5113*8e3e3a7aSWarner Losh<code>lua_tolstring</code> returns a pointer 5114*8e3e3a7aSWarner Loshto a string inside the Lua state. 5115*8e3e3a7aSWarner LoshThis string always has a zero ('<code>\0</code>') 5116*8e3e3a7aSWarner Loshafter its last character (as in C), 5117*8e3e3a7aSWarner Loshbut can contain other zeros in its body. 5118*8e3e3a7aSWarner Losh 5119*8e3e3a7aSWarner Losh 5120*8e3e3a7aSWarner Losh<p> 5121*8e3e3a7aSWarner LoshBecause Lua has garbage collection, 5122*8e3e3a7aSWarner Loshthere is no guarantee that the pointer returned by <code>lua_tolstring</code> 5123*8e3e3a7aSWarner Loshwill be valid after the corresponding Lua value is removed from the stack. 5124*8e3e3a7aSWarner Losh 5125*8e3e3a7aSWarner Losh 5126*8e3e3a7aSWarner Losh 5127*8e3e3a7aSWarner Losh 5128*8e3e3a7aSWarner Losh 5129*8e3e3a7aSWarner Losh<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> 5130*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5131*8e3e3a7aSWarner Losh<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> 5132*8e3e3a7aSWarner Losh 5133*8e3e3a7aSWarner Losh<p> 5134*8e3e3a7aSWarner LoshEquivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5135*8e3e3a7aSWarner Losh 5136*8e3e3a7aSWarner Losh 5137*8e3e3a7aSWarner Losh 5138*8e3e3a7aSWarner Losh 5139*8e3e3a7aSWarner Losh 5140*8e3e3a7aSWarner Losh<hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p> 5141*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5142*8e3e3a7aSWarner Losh<pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre> 5143*8e3e3a7aSWarner Losh 5144*8e3e3a7aSWarner Losh<p> 5145*8e3e3a7aSWarner LoshConverts the Lua value at the given index 5146*8e3e3a7aSWarner Loshto the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). 5147*8e3e3a7aSWarner LoshThe Lua value must be a number or a string convertible to a number 5148*8e3e3a7aSWarner Losh(see <a href="#3.4.3">§3.4.3</a>); 5149*8e3e3a7aSWarner Loshotherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0. 5150*8e3e3a7aSWarner Losh 5151*8e3e3a7aSWarner Losh 5152*8e3e3a7aSWarner Losh<p> 5153*8e3e3a7aSWarner LoshIf <code>isnum</code> is not <code>NULL</code>, 5154*8e3e3a7aSWarner Loshits referent is assigned a boolean value that 5155*8e3e3a7aSWarner Loshindicates whether the operation succeeded. 5156*8e3e3a7aSWarner Losh 5157*8e3e3a7aSWarner Losh 5158*8e3e3a7aSWarner Losh 5159*8e3e3a7aSWarner Losh 5160*8e3e3a7aSWarner Losh 5161*8e3e3a7aSWarner Losh<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> 5162*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5163*8e3e3a7aSWarner Losh<pre>const void *lua_topointer (lua_State *L, int index);</pre> 5164*8e3e3a7aSWarner Losh 5165*8e3e3a7aSWarner Losh<p> 5166*8e3e3a7aSWarner LoshConverts the value at the given index to a generic 5167*8e3e3a7aSWarner LoshC pointer (<code>void*</code>). 5168*8e3e3a7aSWarner LoshThe value can be a userdata, a table, a thread, or a function; 5169*8e3e3a7aSWarner Loshotherwise, <code>lua_topointer</code> returns <code>NULL</code>. 5170*8e3e3a7aSWarner LoshDifferent objects will give different pointers. 5171*8e3e3a7aSWarner LoshThere is no way to convert the pointer back to its original value. 5172*8e3e3a7aSWarner Losh 5173*8e3e3a7aSWarner Losh 5174*8e3e3a7aSWarner Losh<p> 5175*8e3e3a7aSWarner LoshTypically this function is used only for hashing and debug information. 5176*8e3e3a7aSWarner Losh 5177*8e3e3a7aSWarner Losh 5178*8e3e3a7aSWarner Losh 5179*8e3e3a7aSWarner Losh 5180*8e3e3a7aSWarner Losh 5181*8e3e3a7aSWarner Losh<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> 5182*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span> 5183*8e3e3a7aSWarner Losh<pre>const char *lua_tostring (lua_State *L, int index);</pre> 5184*8e3e3a7aSWarner Losh 5185*8e3e3a7aSWarner Losh<p> 5186*8e3e3a7aSWarner LoshEquivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. 5187*8e3e3a7aSWarner Losh 5188*8e3e3a7aSWarner Losh 5189*8e3e3a7aSWarner Losh 5190*8e3e3a7aSWarner Losh 5191*8e3e3a7aSWarner Losh 5192*8e3e3a7aSWarner Losh<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> 5193*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5194*8e3e3a7aSWarner Losh<pre>lua_State *lua_tothread (lua_State *L, int index);</pre> 5195*8e3e3a7aSWarner Losh 5196*8e3e3a7aSWarner Losh<p> 5197*8e3e3a7aSWarner LoshConverts the value at the given index to a Lua thread 5198*8e3e3a7aSWarner Losh(represented as <code>lua_State*</code>). 5199*8e3e3a7aSWarner LoshThis value must be a thread; 5200*8e3e3a7aSWarner Loshotherwise, the function returns <code>NULL</code>. 5201*8e3e3a7aSWarner Losh 5202*8e3e3a7aSWarner Losh 5203*8e3e3a7aSWarner Losh 5204*8e3e3a7aSWarner Losh 5205*8e3e3a7aSWarner Losh 5206*8e3e3a7aSWarner Losh<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> 5207*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5208*8e3e3a7aSWarner Losh<pre>void *lua_touserdata (lua_State *L, int index);</pre> 5209*8e3e3a7aSWarner Losh 5210*8e3e3a7aSWarner Losh<p> 5211*8e3e3a7aSWarner LoshIf the value at the given index is a full userdata, 5212*8e3e3a7aSWarner Loshreturns its block address. 5213*8e3e3a7aSWarner LoshIf the value is a light userdata, 5214*8e3e3a7aSWarner Loshreturns its pointer. 5215*8e3e3a7aSWarner LoshOtherwise, returns <code>NULL</code>. 5216*8e3e3a7aSWarner Losh 5217*8e3e3a7aSWarner Losh 5218*8e3e3a7aSWarner Losh 5219*8e3e3a7aSWarner Losh 5220*8e3e3a7aSWarner Losh 5221*8e3e3a7aSWarner Losh<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> 5222*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5223*8e3e3a7aSWarner Losh<pre>int lua_type (lua_State *L, int index);</pre> 5224*8e3e3a7aSWarner Losh 5225*8e3e3a7aSWarner Losh<p> 5226*8e3e3a7aSWarner LoshReturns the type of the value in the given valid index, 5227*8e3e3a7aSWarner Loshor <code>LUA_TNONE</code> for a non-valid (but acceptable) index. 5228*8e3e3a7aSWarner LoshThe types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants 5229*8e3e3a7aSWarner Loshdefined in <code>lua.h</code>: 5230*8e3e3a7aSWarner Losh<a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a> (0), 5231*8e3e3a7aSWarner Losh<a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>, 5232*8e3e3a7aSWarner Losh<a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>, 5233*8e3e3a7aSWarner Losh<a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, 5234*8e3e3a7aSWarner Losh<a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, 5235*8e3e3a7aSWarner Losh<a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, 5236*8e3e3a7aSWarner Losh<a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, 5237*8e3e3a7aSWarner Losh<a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>, 5238*8e3e3a7aSWarner Loshand 5239*8e3e3a7aSWarner Losh<a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>. 5240*8e3e3a7aSWarner Losh 5241*8e3e3a7aSWarner Losh 5242*8e3e3a7aSWarner Losh 5243*8e3e3a7aSWarner Losh 5244*8e3e3a7aSWarner Losh 5245*8e3e3a7aSWarner Losh<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> 5246*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5247*8e3e3a7aSWarner Losh<pre>const char *lua_typename (lua_State *L, int tp);</pre> 5248*8e3e3a7aSWarner Losh 5249*8e3e3a7aSWarner Losh<p> 5250*8e3e3a7aSWarner LoshReturns the name of the type encoded by the value <code>tp</code>, 5251*8e3e3a7aSWarner Loshwhich must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. 5252*8e3e3a7aSWarner Losh 5253*8e3e3a7aSWarner Losh 5254*8e3e3a7aSWarner Losh 5255*8e3e3a7aSWarner Losh 5256*8e3e3a7aSWarner Losh 5257*8e3e3a7aSWarner Losh<hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3> 5258*8e3e3a7aSWarner Losh<pre>typedef ... lua_Unsigned;</pre> 5259*8e3e3a7aSWarner Losh 5260*8e3e3a7aSWarner Losh<p> 5261*8e3e3a7aSWarner LoshThe unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>. 5262*8e3e3a7aSWarner Losh 5263*8e3e3a7aSWarner Losh 5264*8e3e3a7aSWarner Losh 5265*8e3e3a7aSWarner Losh 5266*8e3e3a7aSWarner Losh 5267*8e3e3a7aSWarner Losh<hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p> 5268*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5269*8e3e3a7aSWarner Losh<pre>int lua_upvalueindex (int i);</pre> 5270*8e3e3a7aSWarner Losh 5271*8e3e3a7aSWarner Losh<p> 5272*8e3e3a7aSWarner LoshReturns the pseudo-index that represents the <code>i</code>-th upvalue of 5273*8e3e3a7aSWarner Loshthe running function (see <a href="#4.4">§4.4</a>). 5274*8e3e3a7aSWarner Losh 5275*8e3e3a7aSWarner Losh 5276*8e3e3a7aSWarner Losh 5277*8e3e3a7aSWarner Losh 5278*8e3e3a7aSWarner Losh 5279*8e3e3a7aSWarner Losh<hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p> 5280*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5281*8e3e3a7aSWarner Losh<pre>const lua_Number *lua_version (lua_State *L);</pre> 5282*8e3e3a7aSWarner Losh 5283*8e3e3a7aSWarner Losh<p> 5284*8e3e3a7aSWarner LoshReturns the address of the version number 5285*8e3e3a7aSWarner Losh(a C static variable) 5286*8e3e3a7aSWarner Loshstored in the Lua core. 5287*8e3e3a7aSWarner LoshWhen called with a valid <a href="#lua_State"><code>lua_State</code></a>, 5288*8e3e3a7aSWarner Loshreturns the address of the version used to create that state. 5289*8e3e3a7aSWarner LoshWhen called with <code>NULL</code>, 5290*8e3e3a7aSWarner Loshreturns the address of the version running the call. 5291*8e3e3a7aSWarner Losh 5292*8e3e3a7aSWarner Losh 5293*8e3e3a7aSWarner Losh 5294*8e3e3a7aSWarner Losh 5295*8e3e3a7aSWarner Losh 5296*8e3e3a7aSWarner Losh<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> 5297*8e3e3a7aSWarner Losh<pre>typedef int (*lua_Writer) (lua_State *L, 5298*8e3e3a7aSWarner Losh const void* p, 5299*8e3e3a7aSWarner Losh size_t sz, 5300*8e3e3a7aSWarner Losh void* ud);</pre> 5301*8e3e3a7aSWarner Losh 5302*8e3e3a7aSWarner Losh<p> 5303*8e3e3a7aSWarner LoshThe type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. 5304*8e3e3a7aSWarner LoshEvery time it produces another piece of chunk, 5305*8e3e3a7aSWarner Losh<a href="#lua_dump"><code>lua_dump</code></a> calls the writer, 5306*8e3e3a7aSWarner Loshpassing along the buffer to be written (<code>p</code>), 5307*8e3e3a7aSWarner Loshits size (<code>sz</code>), 5308*8e3e3a7aSWarner Loshand the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. 5309*8e3e3a7aSWarner Losh 5310*8e3e3a7aSWarner Losh 5311*8e3e3a7aSWarner Losh<p> 5312*8e3e3a7aSWarner LoshThe writer returns an error code: 5313*8e3e3a7aSWarner Losh0 means no errors; 5314*8e3e3a7aSWarner Loshany other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from 5315*8e3e3a7aSWarner Loshcalling the writer again. 5316*8e3e3a7aSWarner Losh 5317*8e3e3a7aSWarner Losh 5318*8e3e3a7aSWarner Losh 5319*8e3e3a7aSWarner Losh 5320*8e3e3a7aSWarner Losh 5321*8e3e3a7aSWarner Losh<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> 5322*8e3e3a7aSWarner Losh<span class="apii">[-?, +?, –]</span> 5323*8e3e3a7aSWarner Losh<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> 5324*8e3e3a7aSWarner Losh 5325*8e3e3a7aSWarner Losh<p> 5326*8e3e3a7aSWarner LoshExchange values between different threads of the same state. 5327*8e3e3a7aSWarner Losh 5328*8e3e3a7aSWarner Losh 5329*8e3e3a7aSWarner Losh<p> 5330*8e3e3a7aSWarner LoshThis function pops <code>n</code> values from the stack <code>from</code>, 5331*8e3e3a7aSWarner Loshand pushes them onto the stack <code>to</code>. 5332*8e3e3a7aSWarner Losh 5333*8e3e3a7aSWarner Losh 5334*8e3e3a7aSWarner Losh 5335*8e3e3a7aSWarner Losh 5336*8e3e3a7aSWarner Losh 5337*8e3e3a7aSWarner Losh<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> 5338*8e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>e</em>]</span> 5339*8e3e3a7aSWarner Losh<pre>int lua_yield (lua_State *L, int nresults);</pre> 5340*8e3e3a7aSWarner Losh 5341*8e3e3a7aSWarner Losh<p> 5342*8e3e3a7aSWarner LoshThis function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5343*8e3e3a7aSWarner Loshbut it has no continuation (see <a href="#4.7">§4.7</a>). 5344*8e3e3a7aSWarner LoshTherefore, when the thread resumes, 5345*8e3e3a7aSWarner Loshit continues the function that called 5346*8e3e3a7aSWarner Loshthe function calling <code>lua_yield</code>. 5347*8e3e3a7aSWarner Losh 5348*8e3e3a7aSWarner Losh 5349*8e3e3a7aSWarner Losh 5350*8e3e3a7aSWarner Losh 5351*8e3e3a7aSWarner Losh 5352*8e3e3a7aSWarner Losh<hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p> 5353*8e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>e</em>]</span> 5354*8e3e3a7aSWarner Losh<pre>int lua_yieldk (lua_State *L, 5355*8e3e3a7aSWarner Losh int nresults, 5356*8e3e3a7aSWarner Losh lua_KContext ctx, 5357*8e3e3a7aSWarner Losh lua_KFunction k);</pre> 5358*8e3e3a7aSWarner Losh 5359*8e3e3a7aSWarner Losh<p> 5360*8e3e3a7aSWarner LoshYields a coroutine (thread). 5361*8e3e3a7aSWarner Losh 5362*8e3e3a7aSWarner Losh 5363*8e3e3a7aSWarner Losh<p> 5364*8e3e3a7aSWarner LoshWhen a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5365*8e3e3a7aSWarner Loshthe running coroutine suspends its execution, 5366*8e3e3a7aSWarner Loshand the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. 5367*8e3e3a7aSWarner LoshThe parameter <code>nresults</code> is the number of values from the stack 5368*8e3e3a7aSWarner Loshthat will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. 5369*8e3e3a7aSWarner Losh 5370*8e3e3a7aSWarner Losh 5371*8e3e3a7aSWarner Losh<p> 5372*8e3e3a7aSWarner LoshWhen the coroutine is resumed again, 5373*8e3e3a7aSWarner LoshLua calls the given continuation function <code>k</code> to continue 5374*8e3e3a7aSWarner Loshthe execution of the C function that yielded (see <a href="#4.7">§4.7</a>). 5375*8e3e3a7aSWarner LoshThis continuation function receives the same stack 5376*8e3e3a7aSWarner Loshfrom the previous function, 5377*8e3e3a7aSWarner Loshwith the <code>n</code> results removed and 5378*8e3e3a7aSWarner Loshreplaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>. 5379*8e3e3a7aSWarner LoshMoreover, 5380*8e3e3a7aSWarner Loshthe continuation function receives the value <code>ctx</code> 5381*8e3e3a7aSWarner Loshthat was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>. 5382*8e3e3a7aSWarner Losh 5383*8e3e3a7aSWarner Losh 5384*8e3e3a7aSWarner Losh<p> 5385*8e3e3a7aSWarner LoshUsually, this function does not return; 5386*8e3e3a7aSWarner Loshwhen the coroutine eventually resumes, 5387*8e3e3a7aSWarner Loshit continues executing the continuation function. 5388*8e3e3a7aSWarner LoshHowever, there is one special case, 5389*8e3e3a7aSWarner Loshwhich is when this function is called 5390*8e3e3a7aSWarner Loshfrom inside a line or a count hook (see <a href="#4.9">§4.9</a>). 5391*8e3e3a7aSWarner LoshIn that case, <code>lua_yieldk</code> should be called with no continuation 5392*8e3e3a7aSWarner Losh(probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results, 5393*8e3e3a7aSWarner Loshand the hook should return immediately after the call. 5394*8e3e3a7aSWarner LoshLua will yield and, 5395*8e3e3a7aSWarner Loshwhen the coroutine resumes again, 5396*8e3e3a7aSWarner Loshit will continue the normal execution 5397*8e3e3a7aSWarner Loshof the (Lua) function that triggered the hook. 5398*8e3e3a7aSWarner Losh 5399*8e3e3a7aSWarner Losh 5400*8e3e3a7aSWarner Losh<p> 5401*8e3e3a7aSWarner LoshThis function can raise an error if it is called from a thread 5402*8e3e3a7aSWarner Loshwith a pending C call with no continuation function, 5403*8e3e3a7aSWarner Loshor it is called from a thread that is not running inside a resume 5404*8e3e3a7aSWarner Losh(e.g., the main thread). 5405*8e3e3a7aSWarner Losh 5406*8e3e3a7aSWarner Losh 5407*8e3e3a7aSWarner Losh 5408*8e3e3a7aSWarner Losh 5409*8e3e3a7aSWarner Losh 5410*8e3e3a7aSWarner Losh 5411*8e3e3a7aSWarner Losh 5412*8e3e3a7aSWarner Losh<h2>4.9 – <a name="4.9">The Debug Interface</a></h2> 5413*8e3e3a7aSWarner Losh 5414*8e3e3a7aSWarner Losh<p> 5415*8e3e3a7aSWarner LoshLua has no built-in debugging facilities. 5416*8e3e3a7aSWarner LoshInstead, it offers a special interface 5417*8e3e3a7aSWarner Loshby means of functions and <em>hooks</em>. 5418*8e3e3a7aSWarner LoshThis interface allows the construction of different 5419*8e3e3a7aSWarner Loshkinds of debuggers, profilers, and other tools 5420*8e3e3a7aSWarner Loshthat need "inside information" from the interpreter. 5421*8e3e3a7aSWarner Losh 5422*8e3e3a7aSWarner Losh 5423*8e3e3a7aSWarner Losh 5424*8e3e3a7aSWarner Losh<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> 5425*8e3e3a7aSWarner Losh<pre>typedef struct lua_Debug { 5426*8e3e3a7aSWarner Losh int event; 5427*8e3e3a7aSWarner Losh const char *name; /* (n) */ 5428*8e3e3a7aSWarner Losh const char *namewhat; /* (n) */ 5429*8e3e3a7aSWarner Losh const char *what; /* (S) */ 5430*8e3e3a7aSWarner Losh const char *source; /* (S) */ 5431*8e3e3a7aSWarner Losh int currentline; /* (l) */ 5432*8e3e3a7aSWarner Losh int linedefined; /* (S) */ 5433*8e3e3a7aSWarner Losh int lastlinedefined; /* (S) */ 5434*8e3e3a7aSWarner Losh unsigned char nups; /* (u) number of upvalues */ 5435*8e3e3a7aSWarner Losh unsigned char nparams; /* (u) number of parameters */ 5436*8e3e3a7aSWarner Losh char isvararg; /* (u) */ 5437*8e3e3a7aSWarner Losh char istailcall; /* (t) */ 5438*8e3e3a7aSWarner Losh char short_src[LUA_IDSIZE]; /* (S) */ 5439*8e3e3a7aSWarner Losh /* private part */ 5440*8e3e3a7aSWarner Losh <em>other fields</em> 5441*8e3e3a7aSWarner Losh} lua_Debug;</pre> 5442*8e3e3a7aSWarner Losh 5443*8e3e3a7aSWarner Losh<p> 5444*8e3e3a7aSWarner LoshA structure used to carry different pieces of 5445*8e3e3a7aSWarner Loshinformation about a function or an activation record. 5446*8e3e3a7aSWarner Losh<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part 5447*8e3e3a7aSWarner Loshof this structure, for later use. 5448*8e3e3a7aSWarner LoshTo fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, 5449*8e3e3a7aSWarner Loshcall <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 5450*8e3e3a7aSWarner Losh 5451*8e3e3a7aSWarner Losh 5452*8e3e3a7aSWarner Losh<p> 5453*8e3e3a7aSWarner LoshThe fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: 5454*8e3e3a7aSWarner Losh 5455*8e3e3a7aSWarner Losh<ul> 5456*8e3e3a7aSWarner Losh 5457*8e3e3a7aSWarner Losh<li><b><code>source</code>: </b> 5458*8e3e3a7aSWarner Loshthe name of the chunk that created the function. 5459*8e3e3a7aSWarner LoshIf <code>source</code> starts with a '<code>@</code>', 5460*8e3e3a7aSWarner Loshit means that the function was defined in a file where 5461*8e3e3a7aSWarner Loshthe file name follows the '<code>@</code>'. 5462*8e3e3a7aSWarner LoshIf <code>source</code> starts with a '<code>=</code>', 5463*8e3e3a7aSWarner Loshthe remainder of its contents describe the source in a user-dependent manner. 5464*8e3e3a7aSWarner LoshOtherwise, 5465*8e3e3a7aSWarner Loshthe function was defined in a string where 5466*8e3e3a7aSWarner Losh<code>source</code> is that string. 5467*8e3e3a7aSWarner Losh</li> 5468*8e3e3a7aSWarner Losh 5469*8e3e3a7aSWarner Losh<li><b><code>short_src</code>: </b> 5470*8e3e3a7aSWarner Losha "printable" version of <code>source</code>, to be used in error messages. 5471*8e3e3a7aSWarner Losh</li> 5472*8e3e3a7aSWarner Losh 5473*8e3e3a7aSWarner Losh<li><b><code>linedefined</code>: </b> 5474*8e3e3a7aSWarner Loshthe line number where the definition of the function starts. 5475*8e3e3a7aSWarner Losh</li> 5476*8e3e3a7aSWarner Losh 5477*8e3e3a7aSWarner Losh<li><b><code>lastlinedefined</code>: </b> 5478*8e3e3a7aSWarner Loshthe line number where the definition of the function ends. 5479*8e3e3a7aSWarner Losh</li> 5480*8e3e3a7aSWarner Losh 5481*8e3e3a7aSWarner Losh<li><b><code>what</code>: </b> 5482*8e3e3a7aSWarner Loshthe string <code>"Lua"</code> if the function is a Lua function, 5483*8e3e3a7aSWarner Losh<code>"C"</code> if it is a C function, 5484*8e3e3a7aSWarner Losh<code>"main"</code> if it is the main part of a chunk. 5485*8e3e3a7aSWarner Losh</li> 5486*8e3e3a7aSWarner Losh 5487*8e3e3a7aSWarner Losh<li><b><code>currentline</code>: </b> 5488*8e3e3a7aSWarner Loshthe current line where the given function is executing. 5489*8e3e3a7aSWarner LoshWhen no line information is available, 5490*8e3e3a7aSWarner Losh<code>currentline</code> is set to -1. 5491*8e3e3a7aSWarner Losh</li> 5492*8e3e3a7aSWarner Losh 5493*8e3e3a7aSWarner Losh<li><b><code>name</code>: </b> 5494*8e3e3a7aSWarner Losha reasonable name for the given function. 5495*8e3e3a7aSWarner LoshBecause functions in Lua are first-class values, 5496*8e3e3a7aSWarner Loshthey do not have a fixed name: 5497*8e3e3a7aSWarner Loshsome functions can be the value of multiple global variables, 5498*8e3e3a7aSWarner Loshwhile others can be stored only in a table field. 5499*8e3e3a7aSWarner LoshThe <code>lua_getinfo</code> function checks how the function was 5500*8e3e3a7aSWarner Loshcalled to find a suitable name. 5501*8e3e3a7aSWarner LoshIf it cannot find a name, 5502*8e3e3a7aSWarner Loshthen <code>name</code> is set to <code>NULL</code>. 5503*8e3e3a7aSWarner Losh</li> 5504*8e3e3a7aSWarner Losh 5505*8e3e3a7aSWarner Losh<li><b><code>namewhat</code>: </b> 5506*8e3e3a7aSWarner Loshexplains the <code>name</code> field. 5507*8e3e3a7aSWarner LoshThe value of <code>namewhat</code> can be 5508*8e3e3a7aSWarner Losh<code>"global"</code>, <code>"local"</code>, <code>"method"</code>, 5509*8e3e3a7aSWarner Losh<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), 5510*8e3e3a7aSWarner Loshaccording to how the function was called. 5511*8e3e3a7aSWarner Losh(Lua uses the empty string when no other option seems to apply.) 5512*8e3e3a7aSWarner Losh</li> 5513*8e3e3a7aSWarner Losh 5514*8e3e3a7aSWarner Losh<li><b><code>istailcall</code>: </b> 5515*8e3e3a7aSWarner Loshtrue if this function invocation was called by a tail call. 5516*8e3e3a7aSWarner LoshIn this case, the caller of this level is not in the stack. 5517*8e3e3a7aSWarner Losh</li> 5518*8e3e3a7aSWarner Losh 5519*8e3e3a7aSWarner Losh<li><b><code>nups</code>: </b> 5520*8e3e3a7aSWarner Loshthe number of upvalues of the function. 5521*8e3e3a7aSWarner Losh</li> 5522*8e3e3a7aSWarner Losh 5523*8e3e3a7aSWarner Losh<li><b><code>nparams</code>: </b> 5524*8e3e3a7aSWarner Loshthe number of fixed parameters of the function 5525*8e3e3a7aSWarner Losh(always 0 for C functions). 5526*8e3e3a7aSWarner Losh</li> 5527*8e3e3a7aSWarner Losh 5528*8e3e3a7aSWarner Losh<li><b><code>isvararg</code>: </b> 5529*8e3e3a7aSWarner Loshtrue if the function is a vararg function 5530*8e3e3a7aSWarner Losh(always true for C functions). 5531*8e3e3a7aSWarner Losh</li> 5532*8e3e3a7aSWarner Losh 5533*8e3e3a7aSWarner Losh</ul> 5534*8e3e3a7aSWarner Losh 5535*8e3e3a7aSWarner Losh 5536*8e3e3a7aSWarner Losh 5537*8e3e3a7aSWarner Losh 5538*8e3e3a7aSWarner Losh<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> 5539*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5540*8e3e3a7aSWarner Losh<pre>lua_Hook lua_gethook (lua_State *L);</pre> 5541*8e3e3a7aSWarner Losh 5542*8e3e3a7aSWarner Losh<p> 5543*8e3e3a7aSWarner LoshReturns the current hook function. 5544*8e3e3a7aSWarner Losh 5545*8e3e3a7aSWarner Losh 5546*8e3e3a7aSWarner Losh 5547*8e3e3a7aSWarner Losh 5548*8e3e3a7aSWarner Losh 5549*8e3e3a7aSWarner Losh<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> 5550*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5551*8e3e3a7aSWarner Losh<pre>int lua_gethookcount (lua_State *L);</pre> 5552*8e3e3a7aSWarner Losh 5553*8e3e3a7aSWarner Losh<p> 5554*8e3e3a7aSWarner LoshReturns the current hook count. 5555*8e3e3a7aSWarner Losh 5556*8e3e3a7aSWarner Losh 5557*8e3e3a7aSWarner Losh 5558*8e3e3a7aSWarner Losh 5559*8e3e3a7aSWarner Losh 5560*8e3e3a7aSWarner Losh<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> 5561*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5562*8e3e3a7aSWarner Losh<pre>int lua_gethookmask (lua_State *L);</pre> 5563*8e3e3a7aSWarner Losh 5564*8e3e3a7aSWarner Losh<p> 5565*8e3e3a7aSWarner LoshReturns the current hook mask. 5566*8e3e3a7aSWarner Losh 5567*8e3e3a7aSWarner Losh 5568*8e3e3a7aSWarner Losh 5569*8e3e3a7aSWarner Losh 5570*8e3e3a7aSWarner Losh 5571*8e3e3a7aSWarner Losh<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> 5572*8e3e3a7aSWarner Losh<span class="apii">[-(0|1), +(0|1|2), <em>e</em>]</span> 5573*8e3e3a7aSWarner Losh<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> 5574*8e3e3a7aSWarner Losh 5575*8e3e3a7aSWarner Losh<p> 5576*8e3e3a7aSWarner LoshGets information about a specific function or function invocation. 5577*8e3e3a7aSWarner Losh 5578*8e3e3a7aSWarner Losh 5579*8e3e3a7aSWarner Losh<p> 5580*8e3e3a7aSWarner LoshTo get information about a function invocation, 5581*8e3e3a7aSWarner Loshthe parameter <code>ar</code> must be a valid activation record that was 5582*8e3e3a7aSWarner Loshfilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 5583*8e3e3a7aSWarner Loshgiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 5584*8e3e3a7aSWarner Losh 5585*8e3e3a7aSWarner Losh 5586*8e3e3a7aSWarner Losh<p> 5587*8e3e3a7aSWarner LoshTo get information about a function you push it onto the stack 5588*8e3e3a7aSWarner Loshand start the <code>what</code> string with the character '<code>></code>'. 5589*8e3e3a7aSWarner Losh(In that case, 5590*8e3e3a7aSWarner Losh<code>lua_getinfo</code> pops the function from the top of the stack.) 5591*8e3e3a7aSWarner LoshFor instance, to know in which line a function <code>f</code> was defined, 5592*8e3e3a7aSWarner Loshyou can write the following code: 5593*8e3e3a7aSWarner Losh 5594*8e3e3a7aSWarner Losh<pre> 5595*8e3e3a7aSWarner Losh lua_Debug ar; 5596*8e3e3a7aSWarner Losh lua_getglobal(L, "f"); /* get global 'f' */ 5597*8e3e3a7aSWarner Losh lua_getinfo(L, ">S", &ar); 5598*8e3e3a7aSWarner Losh printf("%d\n", ar.linedefined); 5599*8e3e3a7aSWarner Losh</pre> 5600*8e3e3a7aSWarner Losh 5601*8e3e3a7aSWarner Losh<p> 5602*8e3e3a7aSWarner LoshEach character in the string <code>what</code> 5603*8e3e3a7aSWarner Loshselects some fields of the structure <code>ar</code> to be filled or 5604*8e3e3a7aSWarner Losha value to be pushed on the stack: 5605*8e3e3a7aSWarner Losh 5606*8e3e3a7aSWarner Losh<ul> 5607*8e3e3a7aSWarner Losh 5608*8e3e3a7aSWarner Losh<li><b>'<code>n</code>': </b> fills in the field <code>name</code> and <code>namewhat</code>; 5609*8e3e3a7aSWarner Losh</li> 5610*8e3e3a7aSWarner Losh 5611*8e3e3a7aSWarner Losh<li><b>'<code>S</code>': </b> 5612*8e3e3a7aSWarner Loshfills in the fields <code>source</code>, <code>short_src</code>, 5613*8e3e3a7aSWarner Losh<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; 5614*8e3e3a7aSWarner Losh</li> 5615*8e3e3a7aSWarner Losh 5616*8e3e3a7aSWarner Losh<li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>; 5617*8e3e3a7aSWarner Losh</li> 5618*8e3e3a7aSWarner Losh 5619*8e3e3a7aSWarner Losh<li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>; 5620*8e3e3a7aSWarner Losh</li> 5621*8e3e3a7aSWarner Losh 5622*8e3e3a7aSWarner Losh<li><b>'<code>u</code>': </b> fills in the fields 5623*8e3e3a7aSWarner Losh<code>nups</code>, <code>nparams</code>, and <code>isvararg</code>; 5624*8e3e3a7aSWarner Losh</li> 5625*8e3e3a7aSWarner Losh 5626*8e3e3a7aSWarner Losh<li><b>'<code>f</code>': </b> 5627*8e3e3a7aSWarner Loshpushes onto the stack the function that is 5628*8e3e3a7aSWarner Loshrunning at the given level; 5629*8e3e3a7aSWarner Losh</li> 5630*8e3e3a7aSWarner Losh 5631*8e3e3a7aSWarner Losh<li><b>'<code>L</code>': </b> 5632*8e3e3a7aSWarner Loshpushes onto the stack a table whose indices are the 5633*8e3e3a7aSWarner Loshnumbers of the lines that are valid on the function. 5634*8e3e3a7aSWarner Losh(A <em>valid line</em> is a line with some associated code, 5635*8e3e3a7aSWarner Loshthat is, a line where you can put a break point. 5636*8e3e3a7aSWarner LoshNon-valid lines include empty lines and comments.) 5637*8e3e3a7aSWarner Losh 5638*8e3e3a7aSWarner Losh 5639*8e3e3a7aSWarner Losh<p> 5640*8e3e3a7aSWarner LoshIf this option is given together with option '<code>f</code>', 5641*8e3e3a7aSWarner Loshits table is pushed after the function. 5642*8e3e3a7aSWarner Losh</li> 5643*8e3e3a7aSWarner Losh 5644*8e3e3a7aSWarner Losh</ul> 5645*8e3e3a7aSWarner Losh 5646*8e3e3a7aSWarner Losh<p> 5647*8e3e3a7aSWarner LoshThis function returns 0 on error 5648*8e3e3a7aSWarner Losh(for instance, an invalid option in <code>what</code>). 5649*8e3e3a7aSWarner Losh 5650*8e3e3a7aSWarner Losh 5651*8e3e3a7aSWarner Losh 5652*8e3e3a7aSWarner Losh 5653*8e3e3a7aSWarner Losh 5654*8e3e3a7aSWarner Losh<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> 5655*8e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), –]</span> 5656*8e3e3a7aSWarner Losh<pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 5657*8e3e3a7aSWarner Losh 5658*8e3e3a7aSWarner Losh<p> 5659*8e3e3a7aSWarner LoshGets information about a local variable of 5660*8e3e3a7aSWarner Losha given activation record or a given function. 5661*8e3e3a7aSWarner Losh 5662*8e3e3a7aSWarner Losh 5663*8e3e3a7aSWarner Losh<p> 5664*8e3e3a7aSWarner LoshIn the first case, 5665*8e3e3a7aSWarner Loshthe parameter <code>ar</code> must be a valid activation record that was 5666*8e3e3a7aSWarner Loshfilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 5667*8e3e3a7aSWarner Loshgiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 5668*8e3e3a7aSWarner LoshThe index <code>n</code> selects which local variable to inspect; 5669*8e3e3a7aSWarner Loshsee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices 5670*8e3e3a7aSWarner Loshand names. 5671*8e3e3a7aSWarner Losh 5672*8e3e3a7aSWarner Losh 5673*8e3e3a7aSWarner Losh<p> 5674*8e3e3a7aSWarner Losh<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack 5675*8e3e3a7aSWarner Loshand returns its name. 5676*8e3e3a7aSWarner Losh 5677*8e3e3a7aSWarner Losh 5678*8e3e3a7aSWarner Losh<p> 5679*8e3e3a7aSWarner LoshIn the second case, <code>ar</code> must be <code>NULL</code> and the function 5680*8e3e3a7aSWarner Loshto be inspected must be at the top of the stack. 5681*8e3e3a7aSWarner LoshIn this case, only parameters of Lua functions are visible 5682*8e3e3a7aSWarner Losh(as there is no information about what variables are active) 5683*8e3e3a7aSWarner Loshand no values are pushed onto the stack. 5684*8e3e3a7aSWarner Losh 5685*8e3e3a7aSWarner Losh 5686*8e3e3a7aSWarner Losh<p> 5687*8e3e3a7aSWarner LoshReturns <code>NULL</code> (and pushes nothing) 5688*8e3e3a7aSWarner Loshwhen the index is greater than 5689*8e3e3a7aSWarner Loshthe number of active local variables. 5690*8e3e3a7aSWarner Losh 5691*8e3e3a7aSWarner Losh 5692*8e3e3a7aSWarner Losh 5693*8e3e3a7aSWarner Losh 5694*8e3e3a7aSWarner Losh 5695*8e3e3a7aSWarner Losh<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> 5696*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5697*8e3e3a7aSWarner Losh<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> 5698*8e3e3a7aSWarner Losh 5699*8e3e3a7aSWarner Losh<p> 5700*8e3e3a7aSWarner LoshGets information about the interpreter runtime stack. 5701*8e3e3a7aSWarner Losh 5702*8e3e3a7aSWarner Losh 5703*8e3e3a7aSWarner Losh<p> 5704*8e3e3a7aSWarner LoshThis function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with 5705*8e3e3a7aSWarner Loshan identification of the <em>activation record</em> 5706*8e3e3a7aSWarner Loshof the function executing at a given level. 5707*8e3e3a7aSWarner LoshLevel 0 is the current running function, 5708*8e3e3a7aSWarner Loshwhereas level <em>n+1</em> is the function that has called level <em>n</em> 5709*8e3e3a7aSWarner Losh(except for tail calls, which do not count on the stack). 5710*8e3e3a7aSWarner LoshWhen there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1; 5711*8e3e3a7aSWarner Loshwhen called with a level greater than the stack depth, 5712*8e3e3a7aSWarner Loshit returns 0. 5713*8e3e3a7aSWarner Losh 5714*8e3e3a7aSWarner Losh 5715*8e3e3a7aSWarner Losh 5716*8e3e3a7aSWarner Losh 5717*8e3e3a7aSWarner Losh 5718*8e3e3a7aSWarner Losh<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> 5719*8e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), –]</span> 5720*8e3e3a7aSWarner Losh<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> 5721*8e3e3a7aSWarner Losh 5722*8e3e3a7aSWarner Losh<p> 5723*8e3e3a7aSWarner LoshGets information about the <code>n</code>-th upvalue 5724*8e3e3a7aSWarner Loshof the closure at index <code>funcindex</code>. 5725*8e3e3a7aSWarner LoshIt pushes the upvalue's value onto the stack 5726*8e3e3a7aSWarner Loshand returns its name. 5727*8e3e3a7aSWarner LoshReturns <code>NULL</code> (and pushes nothing) 5728*8e3e3a7aSWarner Loshwhen the index <code>n</code> is greater than the number of upvalues. 5729*8e3e3a7aSWarner Losh 5730*8e3e3a7aSWarner Losh 5731*8e3e3a7aSWarner Losh<p> 5732*8e3e3a7aSWarner LoshFor C functions, this function uses the empty string <code>""</code> 5733*8e3e3a7aSWarner Loshas a name for all upvalues. 5734*8e3e3a7aSWarner Losh(For Lua functions, 5735*8e3e3a7aSWarner Loshupvalues are the external local variables that the function uses, 5736*8e3e3a7aSWarner Loshand that are consequently included in its closure.) 5737*8e3e3a7aSWarner Losh 5738*8e3e3a7aSWarner Losh 5739*8e3e3a7aSWarner Losh<p> 5740*8e3e3a7aSWarner LoshUpvalues have no particular order, 5741*8e3e3a7aSWarner Loshas they are active through the whole function. 5742*8e3e3a7aSWarner LoshThey are numbered in an arbitrary order. 5743*8e3e3a7aSWarner Losh 5744*8e3e3a7aSWarner Losh 5745*8e3e3a7aSWarner Losh 5746*8e3e3a7aSWarner Losh 5747*8e3e3a7aSWarner Losh 5748*8e3e3a7aSWarner Losh<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> 5749*8e3e3a7aSWarner Losh<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> 5750*8e3e3a7aSWarner Losh 5751*8e3e3a7aSWarner Losh<p> 5752*8e3e3a7aSWarner LoshType for debugging hook functions. 5753*8e3e3a7aSWarner Losh 5754*8e3e3a7aSWarner Losh 5755*8e3e3a7aSWarner Losh<p> 5756*8e3e3a7aSWarner LoshWhenever a hook is called, its <code>ar</code> argument has its field 5757*8e3e3a7aSWarner Losh<code>event</code> set to the specific event that triggered the hook. 5758*8e3e3a7aSWarner LoshLua identifies these events with the following constants: 5759*8e3e3a7aSWarner Losh<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, 5760*8e3e3a7aSWarner Losh<a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, 5761*8e3e3a7aSWarner Loshand <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. 5762*8e3e3a7aSWarner LoshMoreover, for line events, the field <code>currentline</code> is also set. 5763*8e3e3a7aSWarner LoshTo get the value of any other field in <code>ar</code>, 5764*8e3e3a7aSWarner Loshthe hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 5765*8e3e3a7aSWarner Losh 5766*8e3e3a7aSWarner Losh 5767*8e3e3a7aSWarner Losh<p> 5768*8e3e3a7aSWarner LoshFor call events, <code>event</code> can be <code>LUA_HOOKCALL</code>, 5769*8e3e3a7aSWarner Loshthe normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call; 5770*8e3e3a7aSWarner Loshin this case, there will be no corresponding return event. 5771*8e3e3a7aSWarner Losh 5772*8e3e3a7aSWarner Losh 5773*8e3e3a7aSWarner Losh<p> 5774*8e3e3a7aSWarner LoshWhile Lua is running a hook, it disables other calls to hooks. 5775*8e3e3a7aSWarner LoshTherefore, if a hook calls back Lua to execute a function or a chunk, 5776*8e3e3a7aSWarner Loshthis execution occurs without any calls to hooks. 5777*8e3e3a7aSWarner Losh 5778*8e3e3a7aSWarner Losh 5779*8e3e3a7aSWarner Losh<p> 5780*8e3e3a7aSWarner LoshHook functions cannot have continuations, 5781*8e3e3a7aSWarner Loshthat is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5782*8e3e3a7aSWarner 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>. 5783*8e3e3a7aSWarner Losh 5784*8e3e3a7aSWarner Losh 5785*8e3e3a7aSWarner Losh<p> 5786*8e3e3a7aSWarner LoshHook functions can yield under the following conditions: 5787*8e3e3a7aSWarner LoshOnly count and line events can yield; 5788*8e3e3a7aSWarner Loshto yield, a hook function must finish its execution 5789*8e3e3a7aSWarner Loshcalling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero 5790*8e3e3a7aSWarner Losh(that is, with no values). 5791*8e3e3a7aSWarner Losh 5792*8e3e3a7aSWarner Losh 5793*8e3e3a7aSWarner Losh 5794*8e3e3a7aSWarner Losh 5795*8e3e3a7aSWarner Losh 5796*8e3e3a7aSWarner Losh<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> 5797*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5798*8e3e3a7aSWarner Losh<pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> 5799*8e3e3a7aSWarner Losh 5800*8e3e3a7aSWarner Losh<p> 5801*8e3e3a7aSWarner LoshSets the debugging hook function. 5802*8e3e3a7aSWarner Losh 5803*8e3e3a7aSWarner Losh 5804*8e3e3a7aSWarner Losh<p> 5805*8e3e3a7aSWarner LoshArgument <code>f</code> is the hook function. 5806*8e3e3a7aSWarner Losh<code>mask</code> specifies on which events the hook will be called: 5807*8e3e3a7aSWarner Loshit is formed by a bitwise OR of the constants 5808*8e3e3a7aSWarner Losh<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, 5809*8e3e3a7aSWarner Losh<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, 5810*8e3e3a7aSWarner Losh<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, 5811*8e3e3a7aSWarner Loshand <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. 5812*8e3e3a7aSWarner LoshThe <code>count</code> argument is only meaningful when the mask 5813*8e3e3a7aSWarner Loshincludes <code>LUA_MASKCOUNT</code>. 5814*8e3e3a7aSWarner LoshFor each event, the hook is called as explained below: 5815*8e3e3a7aSWarner Losh 5816*8e3e3a7aSWarner Losh<ul> 5817*8e3e3a7aSWarner Losh 5818*8e3e3a7aSWarner Losh<li><b>The call hook: </b> is called when the interpreter calls a function. 5819*8e3e3a7aSWarner LoshThe hook is called just after Lua enters the new function, 5820*8e3e3a7aSWarner Loshbefore the function gets its arguments. 5821*8e3e3a7aSWarner Losh</li> 5822*8e3e3a7aSWarner Losh 5823*8e3e3a7aSWarner Losh<li><b>The return hook: </b> is called when the interpreter returns from a function. 5824*8e3e3a7aSWarner LoshThe hook is called just before Lua leaves the function. 5825*8e3e3a7aSWarner LoshThere is no standard way to access the values 5826*8e3e3a7aSWarner Loshto be returned by the function. 5827*8e3e3a7aSWarner Losh</li> 5828*8e3e3a7aSWarner Losh 5829*8e3e3a7aSWarner Losh<li><b>The line hook: </b> is called when the interpreter is about to 5830*8e3e3a7aSWarner Loshstart the execution of a new line of code, 5831*8e3e3a7aSWarner Loshor when it jumps back in the code (even to the same line). 5832*8e3e3a7aSWarner Losh(This event only happens while Lua is executing a Lua function.) 5833*8e3e3a7aSWarner Losh</li> 5834*8e3e3a7aSWarner Losh 5835*8e3e3a7aSWarner Losh<li><b>The count hook: </b> is called after the interpreter executes every 5836*8e3e3a7aSWarner Losh<code>count</code> instructions. 5837*8e3e3a7aSWarner Losh(This event only happens while Lua is executing a Lua function.) 5838*8e3e3a7aSWarner Losh</li> 5839*8e3e3a7aSWarner Losh 5840*8e3e3a7aSWarner Losh</ul> 5841*8e3e3a7aSWarner Losh 5842*8e3e3a7aSWarner Losh<p> 5843*8e3e3a7aSWarner LoshA hook is disabled by setting <code>mask</code> to zero. 5844*8e3e3a7aSWarner Losh 5845*8e3e3a7aSWarner Losh 5846*8e3e3a7aSWarner Losh 5847*8e3e3a7aSWarner Losh 5848*8e3e3a7aSWarner Losh 5849*8e3e3a7aSWarner Losh<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> 5850*8e3e3a7aSWarner Losh<span class="apii">[-(0|1), +0, –]</span> 5851*8e3e3a7aSWarner Losh<pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 5852*8e3e3a7aSWarner Losh 5853*8e3e3a7aSWarner Losh<p> 5854*8e3e3a7aSWarner LoshSets the value of a local variable of a given activation record. 5855*8e3e3a7aSWarner LoshIt assigns the value at the top of the stack 5856*8e3e3a7aSWarner Loshto the variable and returns its name. 5857*8e3e3a7aSWarner LoshIt also pops the value from the stack. 5858*8e3e3a7aSWarner Losh 5859*8e3e3a7aSWarner Losh 5860*8e3e3a7aSWarner Losh<p> 5861*8e3e3a7aSWarner LoshReturns <code>NULL</code> (and pops nothing) 5862*8e3e3a7aSWarner Loshwhen the index is greater than 5863*8e3e3a7aSWarner Loshthe number of active local variables. 5864*8e3e3a7aSWarner Losh 5865*8e3e3a7aSWarner Losh 5866*8e3e3a7aSWarner Losh<p> 5867*8e3e3a7aSWarner LoshParameters <code>ar</code> and <code>n</code> are as in function <a href="#lua_getlocal"><code>lua_getlocal</code></a>. 5868*8e3e3a7aSWarner Losh 5869*8e3e3a7aSWarner Losh 5870*8e3e3a7aSWarner Losh 5871*8e3e3a7aSWarner Losh 5872*8e3e3a7aSWarner Losh 5873*8e3e3a7aSWarner Losh<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> 5874*8e3e3a7aSWarner Losh<span class="apii">[-(0|1), +0, –]</span> 5875*8e3e3a7aSWarner Losh<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> 5876*8e3e3a7aSWarner Losh 5877*8e3e3a7aSWarner Losh<p> 5878*8e3e3a7aSWarner LoshSets the value of a closure's upvalue. 5879*8e3e3a7aSWarner LoshIt assigns the value at the top of the stack 5880*8e3e3a7aSWarner Loshto the upvalue and returns its name. 5881*8e3e3a7aSWarner LoshIt also pops the value from the stack. 5882*8e3e3a7aSWarner Losh 5883*8e3e3a7aSWarner Losh 5884*8e3e3a7aSWarner Losh<p> 5885*8e3e3a7aSWarner LoshReturns <code>NULL</code> (and pops nothing) 5886*8e3e3a7aSWarner Loshwhen the index <code>n</code> is greater than the number of upvalues. 5887*8e3e3a7aSWarner Losh 5888*8e3e3a7aSWarner Losh 5889*8e3e3a7aSWarner Losh<p> 5890*8e3e3a7aSWarner LoshParameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>. 5891*8e3e3a7aSWarner Losh 5892*8e3e3a7aSWarner Losh 5893*8e3e3a7aSWarner Losh 5894*8e3e3a7aSWarner Losh 5895*8e3e3a7aSWarner Losh 5896*8e3e3a7aSWarner Losh<hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p> 5897*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5898*8e3e3a7aSWarner Losh<pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre> 5899*8e3e3a7aSWarner Losh 5900*8e3e3a7aSWarner Losh<p> 5901*8e3e3a7aSWarner LoshReturns a unique identifier for the upvalue numbered <code>n</code> 5902*8e3e3a7aSWarner Loshfrom the closure at index <code>funcindex</code>. 5903*8e3e3a7aSWarner Losh 5904*8e3e3a7aSWarner Losh 5905*8e3e3a7aSWarner Losh<p> 5906*8e3e3a7aSWarner LoshThese unique identifiers allow a program to check whether different 5907*8e3e3a7aSWarner Loshclosures share upvalues. 5908*8e3e3a7aSWarner LoshLua closures that share an upvalue 5909*8e3e3a7aSWarner Losh(that is, that access a same external local variable) 5910*8e3e3a7aSWarner Loshwill return identical ids for those upvalue indices. 5911*8e3e3a7aSWarner Losh 5912*8e3e3a7aSWarner Losh 5913*8e3e3a7aSWarner Losh<p> 5914*8e3e3a7aSWarner LoshParameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, 5915*8e3e3a7aSWarner Loshbut <code>n</code> cannot be greater than the number of upvalues. 5916*8e3e3a7aSWarner Losh 5917*8e3e3a7aSWarner Losh 5918*8e3e3a7aSWarner Losh 5919*8e3e3a7aSWarner Losh 5920*8e3e3a7aSWarner Losh 5921*8e3e3a7aSWarner Losh<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p> 5922*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 5923*8e3e3a7aSWarner Losh<pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1, 5924*8e3e3a7aSWarner Losh int funcindex2, int n2);</pre> 5925*8e3e3a7aSWarner Losh 5926*8e3e3a7aSWarner Losh<p> 5927*8e3e3a7aSWarner LoshMake the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code> 5928*8e3e3a7aSWarner Loshrefer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>. 5929*8e3e3a7aSWarner Losh 5930*8e3e3a7aSWarner Losh 5931*8e3e3a7aSWarner Losh 5932*8e3e3a7aSWarner Losh 5933*8e3e3a7aSWarner Losh 5934*8e3e3a7aSWarner Losh 5935*8e3e3a7aSWarner Losh 5936*8e3e3a7aSWarner Losh<h1>5 – <a name="5">The Auxiliary Library</a></h1> 5937*8e3e3a7aSWarner Losh 5938*8e3e3a7aSWarner Losh<p> 5939*8e3e3a7aSWarner Losh 5940*8e3e3a7aSWarner LoshThe <em>auxiliary library</em> provides several convenient functions 5941*8e3e3a7aSWarner Loshto interface C with Lua. 5942*8e3e3a7aSWarner LoshWhile the basic API provides the primitive functions for all 5943*8e3e3a7aSWarner Loshinteractions between C and Lua, 5944*8e3e3a7aSWarner Loshthe auxiliary library provides higher-level functions for some 5945*8e3e3a7aSWarner Loshcommon tasks. 5946*8e3e3a7aSWarner Losh 5947*8e3e3a7aSWarner Losh 5948*8e3e3a7aSWarner Losh<p> 5949*8e3e3a7aSWarner LoshAll functions and types from the auxiliary library 5950*8e3e3a7aSWarner Loshare defined in header file <code>lauxlib.h</code> and 5951*8e3e3a7aSWarner Loshhave a prefix <code>luaL_</code>. 5952*8e3e3a7aSWarner Losh 5953*8e3e3a7aSWarner Losh 5954*8e3e3a7aSWarner Losh<p> 5955*8e3e3a7aSWarner LoshAll functions in the auxiliary library are built on 5956*8e3e3a7aSWarner Loshtop of the basic API, 5957*8e3e3a7aSWarner Loshand so they provide nothing that cannot be done with that API. 5958*8e3e3a7aSWarner LoshNevertheless, the use of the auxiliary library ensures 5959*8e3e3a7aSWarner Loshmore consistency to your code. 5960*8e3e3a7aSWarner Losh 5961*8e3e3a7aSWarner Losh 5962*8e3e3a7aSWarner Losh<p> 5963*8e3e3a7aSWarner LoshSeveral functions in the auxiliary library use internally some 5964*8e3e3a7aSWarner Loshextra stack slots. 5965*8e3e3a7aSWarner LoshWhen a function in the auxiliary library uses less than five slots, 5966*8e3e3a7aSWarner Loshit does not check the stack size; 5967*8e3e3a7aSWarner Loshit simply assumes that there are enough slots. 5968*8e3e3a7aSWarner Losh 5969*8e3e3a7aSWarner Losh 5970*8e3e3a7aSWarner Losh<p> 5971*8e3e3a7aSWarner LoshSeveral functions in the auxiliary library are used to 5972*8e3e3a7aSWarner Loshcheck C function arguments. 5973*8e3e3a7aSWarner LoshBecause the error message is formatted for arguments 5974*8e3e3a7aSWarner Losh(e.g., "<code>bad argument #1</code>"), 5975*8e3e3a7aSWarner Loshyou should not use these functions for other stack values. 5976*8e3e3a7aSWarner Losh 5977*8e3e3a7aSWarner Losh 5978*8e3e3a7aSWarner Losh<p> 5979*8e3e3a7aSWarner LoshFunctions called <code>luaL_check*</code> 5980*8e3e3a7aSWarner Loshalways raise an error if the check is not satisfied. 5981*8e3e3a7aSWarner Losh 5982*8e3e3a7aSWarner Losh 5983*8e3e3a7aSWarner Losh 5984*8e3e3a7aSWarner Losh<h2>5.1 – <a name="5.1">Functions and Types</a></h2> 5985*8e3e3a7aSWarner Losh 5986*8e3e3a7aSWarner Losh<p> 5987*8e3e3a7aSWarner LoshHere we list all functions and types from the auxiliary library 5988*8e3e3a7aSWarner Loshin alphabetical order. 5989*8e3e3a7aSWarner Losh 5990*8e3e3a7aSWarner Losh 5991*8e3e3a7aSWarner Losh 5992*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> 5993*8e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 5994*8e3e3a7aSWarner Losh<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> 5995*8e3e3a7aSWarner Losh 5996*8e3e3a7aSWarner Losh<p> 5997*8e3e3a7aSWarner LoshAdds the byte <code>c</code> to the buffer <code>B</code> 5998*8e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5999*8e3e3a7aSWarner Losh 6000*8e3e3a7aSWarner Losh 6001*8e3e3a7aSWarner Losh 6002*8e3e3a7aSWarner Losh 6003*8e3e3a7aSWarner Losh 6004*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> 6005*8e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 6006*8e3e3a7aSWarner Losh<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> 6007*8e3e3a7aSWarner Losh 6008*8e3e3a7aSWarner Losh<p> 6009*8e3e3a7aSWarner LoshAdds the string pointed to by <code>s</code> with length <code>l</code> to 6010*8e3e3a7aSWarner Loshthe buffer <code>B</code> 6011*8e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6012*8e3e3a7aSWarner LoshThe string can contain embedded zeros. 6013*8e3e3a7aSWarner Losh 6014*8e3e3a7aSWarner Losh 6015*8e3e3a7aSWarner Losh 6016*8e3e3a7aSWarner Losh 6017*8e3e3a7aSWarner Losh 6018*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> 6019*8e3e3a7aSWarner Losh<span class="apii">[-?, +?, –]</span> 6020*8e3e3a7aSWarner Losh<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> 6021*8e3e3a7aSWarner Losh 6022*8e3e3a7aSWarner Losh<p> 6023*8e3e3a7aSWarner LoshAdds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>) 6024*8e3e3a7aSWarner Losha string of length <code>n</code> previously copied to the 6025*8e3e3a7aSWarner Loshbuffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). 6026*8e3e3a7aSWarner Losh 6027*8e3e3a7aSWarner Losh 6028*8e3e3a7aSWarner Losh 6029*8e3e3a7aSWarner Losh 6030*8e3e3a7aSWarner Losh 6031*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> 6032*8e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 6033*8e3e3a7aSWarner Losh<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> 6034*8e3e3a7aSWarner Losh 6035*8e3e3a7aSWarner Losh<p> 6036*8e3e3a7aSWarner LoshAdds the zero-terminated string pointed to by <code>s</code> 6037*8e3e3a7aSWarner Loshto the buffer <code>B</code> 6038*8e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6039*8e3e3a7aSWarner Losh 6040*8e3e3a7aSWarner Losh 6041*8e3e3a7aSWarner Losh 6042*8e3e3a7aSWarner Losh 6043*8e3e3a7aSWarner Losh 6044*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> 6045*8e3e3a7aSWarner Losh<span class="apii">[-1, +?, <em>m</em>]</span> 6046*8e3e3a7aSWarner Losh<pre>void luaL_addvalue (luaL_Buffer *B);</pre> 6047*8e3e3a7aSWarner Losh 6048*8e3e3a7aSWarner Losh<p> 6049*8e3e3a7aSWarner LoshAdds the value at the top of the stack 6050*8e3e3a7aSWarner Loshto the buffer <code>B</code> 6051*8e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6052*8e3e3a7aSWarner LoshPops the value. 6053*8e3e3a7aSWarner Losh 6054*8e3e3a7aSWarner Losh 6055*8e3e3a7aSWarner Losh<p> 6056*8e3e3a7aSWarner LoshThis is the only function on string buffers that can (and must) 6057*8e3e3a7aSWarner Loshbe called with an extra element on the stack, 6058*8e3e3a7aSWarner Loshwhich is the value to be added to the buffer. 6059*8e3e3a7aSWarner Losh 6060*8e3e3a7aSWarner Losh 6061*8e3e3a7aSWarner Losh 6062*8e3e3a7aSWarner Losh 6063*8e3e3a7aSWarner Losh 6064*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> 6065*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6066*8e3e3a7aSWarner Losh<pre>void luaL_argcheck (lua_State *L, 6067*8e3e3a7aSWarner Losh int cond, 6068*8e3e3a7aSWarner Losh int arg, 6069*8e3e3a7aSWarner Losh const char *extramsg);</pre> 6070*8e3e3a7aSWarner Losh 6071*8e3e3a7aSWarner Losh<p> 6072*8e3e3a7aSWarner LoshChecks whether <code>cond</code> is true. 6073*8e3e3a7aSWarner LoshIf it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>). 6074*8e3e3a7aSWarner Losh 6075*8e3e3a7aSWarner Losh 6076*8e3e3a7aSWarner Losh 6077*8e3e3a7aSWarner Losh 6078*8e3e3a7aSWarner Losh 6079*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> 6080*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6081*8e3e3a7aSWarner Losh<pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre> 6082*8e3e3a7aSWarner Losh 6083*8e3e3a7aSWarner Losh<p> 6084*8e3e3a7aSWarner LoshRaises an error reporting a problem with argument <code>arg</code> 6085*8e3e3a7aSWarner Loshof the C function that called it, 6086*8e3e3a7aSWarner Loshusing a standard message 6087*8e3e3a7aSWarner Loshthat includes <code>extramsg</code> as a comment: 6088*8e3e3a7aSWarner Losh 6089*8e3e3a7aSWarner Losh<pre> 6090*8e3e3a7aSWarner Losh bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>) 6091*8e3e3a7aSWarner Losh</pre><p> 6092*8e3e3a7aSWarner LoshThis function never returns. 6093*8e3e3a7aSWarner Losh 6094*8e3e3a7aSWarner Losh 6095*8e3e3a7aSWarner Losh 6096*8e3e3a7aSWarner Losh 6097*8e3e3a7aSWarner Losh 6098*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> 6099*8e3e3a7aSWarner Losh<pre>typedef struct luaL_Buffer luaL_Buffer;</pre> 6100*8e3e3a7aSWarner Losh 6101*8e3e3a7aSWarner Losh<p> 6102*8e3e3a7aSWarner LoshType for a <em>string buffer</em>. 6103*8e3e3a7aSWarner Losh 6104*8e3e3a7aSWarner Losh 6105*8e3e3a7aSWarner Losh<p> 6106*8e3e3a7aSWarner LoshA string buffer allows C code to build Lua strings piecemeal. 6107*8e3e3a7aSWarner LoshIts pattern of use is as follows: 6108*8e3e3a7aSWarner Losh 6109*8e3e3a7aSWarner Losh<ul> 6110*8e3e3a7aSWarner Losh 6111*8e3e3a7aSWarner Losh<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6112*8e3e3a7aSWarner Losh 6113*8e3e3a7aSWarner Losh<li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> 6114*8e3e3a7aSWarner Losh 6115*8e3e3a7aSWarner Losh<li> 6116*8e3e3a7aSWarner LoshThen add string pieces to the buffer calling any of 6117*8e3e3a7aSWarner Loshthe <code>luaL_add*</code> functions. 6118*8e3e3a7aSWarner Losh</li> 6119*8e3e3a7aSWarner Losh 6120*8e3e3a7aSWarner Losh<li> 6121*8e3e3a7aSWarner LoshFinish by calling <code>luaL_pushresult(&b)</code>. 6122*8e3e3a7aSWarner LoshThis call leaves the final string on the top of the stack. 6123*8e3e3a7aSWarner Losh</li> 6124*8e3e3a7aSWarner Losh 6125*8e3e3a7aSWarner Losh</ul> 6126*8e3e3a7aSWarner Losh 6127*8e3e3a7aSWarner Losh<p> 6128*8e3e3a7aSWarner LoshIf you know beforehand the total size of the resulting string, 6129*8e3e3a7aSWarner Loshyou can use the buffer like this: 6130*8e3e3a7aSWarner Losh 6131*8e3e3a7aSWarner Losh<ul> 6132*8e3e3a7aSWarner Losh 6133*8e3e3a7aSWarner Losh<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6134*8e3e3a7aSWarner Losh 6135*8e3e3a7aSWarner Losh<li>Then initialize it and preallocate a space of 6136*8e3e3a7aSWarner Loshsize <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li> 6137*8e3e3a7aSWarner Losh 6138*8e3e3a7aSWarner Losh<li>Then copy the string into that space.</li> 6139*8e3e3a7aSWarner Losh 6140*8e3e3a7aSWarner Losh<li> 6141*8e3e3a7aSWarner LoshFinish by calling <code>luaL_pushresultsize(&b, sz)</code>, 6142*8e3e3a7aSWarner Loshwhere <code>sz</code> is the total size of the resulting string 6143*8e3e3a7aSWarner Loshcopied into that space. 6144*8e3e3a7aSWarner Losh</li> 6145*8e3e3a7aSWarner Losh 6146*8e3e3a7aSWarner Losh</ul> 6147*8e3e3a7aSWarner Losh 6148*8e3e3a7aSWarner Losh<p> 6149*8e3e3a7aSWarner LoshDuring its normal operation, 6150*8e3e3a7aSWarner Losha string buffer uses a variable number of stack slots. 6151*8e3e3a7aSWarner LoshSo, while using a buffer, you cannot assume that you know where 6152*8e3e3a7aSWarner Loshthe top of the stack is. 6153*8e3e3a7aSWarner LoshYou can use the stack between successive calls to buffer operations 6154*8e3e3a7aSWarner Loshas long as that use is balanced; 6155*8e3e3a7aSWarner Loshthat is, 6156*8e3e3a7aSWarner Loshwhen you call a buffer operation, 6157*8e3e3a7aSWarner Loshthe stack is at the same level 6158*8e3e3a7aSWarner Loshit was immediately after the previous buffer operation. 6159*8e3e3a7aSWarner Losh(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) 6160*8e3e3a7aSWarner LoshAfter calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its 6161*8e3e3a7aSWarner Loshlevel when the buffer was initialized, 6162*8e3e3a7aSWarner Loshplus the final string on its top. 6163*8e3e3a7aSWarner Losh 6164*8e3e3a7aSWarner Losh 6165*8e3e3a7aSWarner Losh 6166*8e3e3a7aSWarner Losh 6167*8e3e3a7aSWarner Losh 6168*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> 6169*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 6170*8e3e3a7aSWarner Losh<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> 6171*8e3e3a7aSWarner Losh 6172*8e3e3a7aSWarner Losh<p> 6173*8e3e3a7aSWarner LoshInitializes a buffer <code>B</code>. 6174*8e3e3a7aSWarner LoshThis function does not allocate any space; 6175*8e3e3a7aSWarner Loshthe buffer must be declared as a variable 6176*8e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6177*8e3e3a7aSWarner Losh 6178*8e3e3a7aSWarner Losh 6179*8e3e3a7aSWarner Losh 6180*8e3e3a7aSWarner Losh 6181*8e3e3a7aSWarner Losh 6182*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p> 6183*8e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 6184*8e3e3a7aSWarner Losh<pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre> 6185*8e3e3a7aSWarner Losh 6186*8e3e3a7aSWarner Losh<p> 6187*8e3e3a7aSWarner LoshEquivalent to the sequence 6188*8e3e3a7aSWarner Losh<a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>. 6189*8e3e3a7aSWarner Losh 6190*8e3e3a7aSWarner Losh 6191*8e3e3a7aSWarner Losh 6192*8e3e3a7aSWarner Losh 6193*8e3e3a7aSWarner Losh 6194*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> 6195*8e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), <em>e</em>]</span> 6196*8e3e3a7aSWarner Losh<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> 6197*8e3e3a7aSWarner Losh 6198*8e3e3a7aSWarner Losh<p> 6199*8e3e3a7aSWarner LoshCalls a metamethod. 6200*8e3e3a7aSWarner Losh 6201*8e3e3a7aSWarner Losh 6202*8e3e3a7aSWarner Losh<p> 6203*8e3e3a7aSWarner LoshIf the object at index <code>obj</code> has a metatable and this 6204*8e3e3a7aSWarner Loshmetatable has a field <code>e</code>, 6205*8e3e3a7aSWarner Loshthis function calls this field passing the object as its only argument. 6206*8e3e3a7aSWarner LoshIn this case this function returns true and pushes onto the 6207*8e3e3a7aSWarner Loshstack the value returned by the call. 6208*8e3e3a7aSWarner LoshIf there is no metatable or no metamethod, 6209*8e3e3a7aSWarner Loshthis function returns false (without pushing any value on the stack). 6210*8e3e3a7aSWarner Losh 6211*8e3e3a7aSWarner Losh 6212*8e3e3a7aSWarner Losh 6213*8e3e3a7aSWarner Losh 6214*8e3e3a7aSWarner Losh 6215*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> 6216*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6217*8e3e3a7aSWarner Losh<pre>void luaL_checkany (lua_State *L, int arg);</pre> 6218*8e3e3a7aSWarner Losh 6219*8e3e3a7aSWarner Losh<p> 6220*8e3e3a7aSWarner LoshChecks whether the function has an argument 6221*8e3e3a7aSWarner Loshof any type (including <b>nil</b>) at position <code>arg</code>. 6222*8e3e3a7aSWarner Losh 6223*8e3e3a7aSWarner Losh 6224*8e3e3a7aSWarner Losh 6225*8e3e3a7aSWarner Losh 6226*8e3e3a7aSWarner Losh 6227*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> 6228*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6229*8e3e3a7aSWarner Losh<pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre> 6230*8e3e3a7aSWarner Losh 6231*8e3e3a7aSWarner Losh<p> 6232*8e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is an integer 6233*8e3e3a7aSWarner Losh(or can be converted to an integer) 6234*8e3e3a7aSWarner Loshand returns this integer cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. 6235*8e3e3a7aSWarner Losh 6236*8e3e3a7aSWarner Losh 6237*8e3e3a7aSWarner Losh 6238*8e3e3a7aSWarner Losh 6239*8e3e3a7aSWarner Losh 6240*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> 6241*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6242*8e3e3a7aSWarner Losh<pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre> 6243*8e3e3a7aSWarner Losh 6244*8e3e3a7aSWarner Losh<p> 6245*8e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string 6246*8e3e3a7aSWarner Loshand returns this string; 6247*8e3e3a7aSWarner Loshif <code>l</code> is not <code>NULL</code> fills <code>*l</code> 6248*8e3e3a7aSWarner Loshwith the string's length. 6249*8e3e3a7aSWarner Losh 6250*8e3e3a7aSWarner Losh 6251*8e3e3a7aSWarner Losh<p> 6252*8e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6253*8e3e3a7aSWarner Loshso all conversions and caveats of that function apply here. 6254*8e3e3a7aSWarner Losh 6255*8e3e3a7aSWarner Losh 6256*8e3e3a7aSWarner Losh 6257*8e3e3a7aSWarner Losh 6258*8e3e3a7aSWarner Losh 6259*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> 6260*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6261*8e3e3a7aSWarner Losh<pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre> 6262*8e3e3a7aSWarner Losh 6263*8e3e3a7aSWarner Losh<p> 6264*8e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a number 6265*8e3e3a7aSWarner Loshand returns this number. 6266*8e3e3a7aSWarner Losh 6267*8e3e3a7aSWarner Losh 6268*8e3e3a7aSWarner Losh 6269*8e3e3a7aSWarner Losh 6270*8e3e3a7aSWarner Losh 6271*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> 6272*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6273*8e3e3a7aSWarner Losh<pre>int luaL_checkoption (lua_State *L, 6274*8e3e3a7aSWarner Losh int arg, 6275*8e3e3a7aSWarner Losh const char *def, 6276*8e3e3a7aSWarner Losh const char *const lst[]);</pre> 6277*8e3e3a7aSWarner Losh 6278*8e3e3a7aSWarner Losh<p> 6279*8e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string and 6280*8e3e3a7aSWarner Loshsearches for this string in the array <code>lst</code> 6281*8e3e3a7aSWarner Losh(which must be NULL-terminated). 6282*8e3e3a7aSWarner LoshReturns the index in the array where the string was found. 6283*8e3e3a7aSWarner LoshRaises an error if the argument is not a string or 6284*8e3e3a7aSWarner Loshif the string cannot be found. 6285*8e3e3a7aSWarner Losh 6286*8e3e3a7aSWarner Losh 6287*8e3e3a7aSWarner Losh<p> 6288*8e3e3a7aSWarner LoshIf <code>def</code> is not <code>NULL</code>, 6289*8e3e3a7aSWarner Loshthe function uses <code>def</code> as a default value when 6290*8e3e3a7aSWarner Loshthere is no argument <code>arg</code> or when this argument is <b>nil</b>. 6291*8e3e3a7aSWarner Losh 6292*8e3e3a7aSWarner Losh 6293*8e3e3a7aSWarner Losh<p> 6294*8e3e3a7aSWarner LoshThis is a useful function for mapping strings to C enums. 6295*8e3e3a7aSWarner Losh(The usual convention in Lua libraries is 6296*8e3e3a7aSWarner Loshto use strings instead of numbers to select options.) 6297*8e3e3a7aSWarner Losh 6298*8e3e3a7aSWarner Losh 6299*8e3e3a7aSWarner Losh 6300*8e3e3a7aSWarner Losh 6301*8e3e3a7aSWarner Losh 6302*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> 6303*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6304*8e3e3a7aSWarner Losh<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> 6305*8e3e3a7aSWarner Losh 6306*8e3e3a7aSWarner Losh<p> 6307*8e3e3a7aSWarner LoshGrows the stack size to <code>top + sz</code> elements, 6308*8e3e3a7aSWarner Loshraising an error if the stack cannot grow to that size. 6309*8e3e3a7aSWarner Losh<code>msg</code> is an additional text to go into the error message 6310*8e3e3a7aSWarner Losh(or <code>NULL</code> for no additional text). 6311*8e3e3a7aSWarner Losh 6312*8e3e3a7aSWarner Losh 6313*8e3e3a7aSWarner Losh 6314*8e3e3a7aSWarner Losh 6315*8e3e3a7aSWarner Losh 6316*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> 6317*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6318*8e3e3a7aSWarner Losh<pre>const char *luaL_checkstring (lua_State *L, int arg);</pre> 6319*8e3e3a7aSWarner Losh 6320*8e3e3a7aSWarner Losh<p> 6321*8e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string 6322*8e3e3a7aSWarner Loshand returns this string. 6323*8e3e3a7aSWarner Losh 6324*8e3e3a7aSWarner Losh 6325*8e3e3a7aSWarner Losh<p> 6326*8e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6327*8e3e3a7aSWarner Loshso all conversions and caveats of that function apply here. 6328*8e3e3a7aSWarner Losh 6329*8e3e3a7aSWarner Losh 6330*8e3e3a7aSWarner Losh 6331*8e3e3a7aSWarner Losh 6332*8e3e3a7aSWarner Losh 6333*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> 6334*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6335*8e3e3a7aSWarner Losh<pre>void luaL_checktype (lua_State *L, int arg, int t);</pre> 6336*8e3e3a7aSWarner Losh 6337*8e3e3a7aSWarner Losh<p> 6338*8e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> has type <code>t</code>. 6339*8e3e3a7aSWarner LoshSee <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. 6340*8e3e3a7aSWarner Losh 6341*8e3e3a7aSWarner Losh 6342*8e3e3a7aSWarner Losh 6343*8e3e3a7aSWarner Losh 6344*8e3e3a7aSWarner Losh 6345*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> 6346*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6347*8e3e3a7aSWarner Losh<pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre> 6348*8e3e3a7aSWarner Losh 6349*8e3e3a7aSWarner Losh<p> 6350*8e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a userdata 6351*8e3e3a7aSWarner Loshof the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and 6352*8e3e3a7aSWarner Loshreturns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>). 6353*8e3e3a7aSWarner Losh 6354*8e3e3a7aSWarner Losh 6355*8e3e3a7aSWarner Losh 6356*8e3e3a7aSWarner Losh 6357*8e3e3a7aSWarner Losh 6358*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p> 6359*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6360*8e3e3a7aSWarner Losh<pre>void luaL_checkversion (lua_State *L);</pre> 6361*8e3e3a7aSWarner Losh 6362*8e3e3a7aSWarner Losh<p> 6363*8e3e3a7aSWarner LoshChecks whether the core running the call, 6364*8e3e3a7aSWarner Loshthe core that created the Lua state, 6365*8e3e3a7aSWarner Loshand the code making the call are all using the same version of Lua. 6366*8e3e3a7aSWarner LoshAlso checks whether the core running the call 6367*8e3e3a7aSWarner Loshand the core that created the Lua state 6368*8e3e3a7aSWarner Loshare using the same address space. 6369*8e3e3a7aSWarner Losh 6370*8e3e3a7aSWarner Losh 6371*8e3e3a7aSWarner Losh 6372*8e3e3a7aSWarner Losh 6373*8e3e3a7aSWarner Losh 6374*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> 6375*8e3e3a7aSWarner Losh<span class="apii">[-0, +?, <em>e</em>]</span> 6376*8e3e3a7aSWarner Losh<pre>int luaL_dofile (lua_State *L, const char *filename);</pre> 6377*8e3e3a7aSWarner Losh 6378*8e3e3a7aSWarner Losh<p> 6379*8e3e3a7aSWarner LoshLoads and runs the given file. 6380*8e3e3a7aSWarner LoshIt is defined as the following macro: 6381*8e3e3a7aSWarner Losh 6382*8e3e3a7aSWarner Losh<pre> 6383*8e3e3a7aSWarner Losh (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6384*8e3e3a7aSWarner Losh</pre><p> 6385*8e3e3a7aSWarner LoshIt returns false if there are no errors 6386*8e3e3a7aSWarner Loshor true in case of errors. 6387*8e3e3a7aSWarner Losh 6388*8e3e3a7aSWarner Losh 6389*8e3e3a7aSWarner Losh 6390*8e3e3a7aSWarner Losh 6391*8e3e3a7aSWarner Losh 6392*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> 6393*8e3e3a7aSWarner Losh<span class="apii">[-0, +?, –]</span> 6394*8e3e3a7aSWarner Losh<pre>int luaL_dostring (lua_State *L, const char *str);</pre> 6395*8e3e3a7aSWarner Losh 6396*8e3e3a7aSWarner Losh<p> 6397*8e3e3a7aSWarner LoshLoads and runs the given string. 6398*8e3e3a7aSWarner LoshIt is defined as the following macro: 6399*8e3e3a7aSWarner Losh 6400*8e3e3a7aSWarner Losh<pre> 6401*8e3e3a7aSWarner Losh (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6402*8e3e3a7aSWarner Losh</pre><p> 6403*8e3e3a7aSWarner LoshIt returns false if there are no errors 6404*8e3e3a7aSWarner Loshor true in case of errors. 6405*8e3e3a7aSWarner Losh 6406*8e3e3a7aSWarner Losh 6407*8e3e3a7aSWarner Losh 6408*8e3e3a7aSWarner Losh 6409*8e3e3a7aSWarner Losh 6410*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> 6411*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6412*8e3e3a7aSWarner Losh<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> 6413*8e3e3a7aSWarner Losh 6414*8e3e3a7aSWarner Losh<p> 6415*8e3e3a7aSWarner LoshRaises an error. 6416*8e3e3a7aSWarner LoshThe error message format is given by <code>fmt</code> 6417*8e3e3a7aSWarner Loshplus any extra arguments, 6418*8e3e3a7aSWarner Loshfollowing the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. 6419*8e3e3a7aSWarner LoshIt also adds at the beginning of the message the file name and 6420*8e3e3a7aSWarner Loshthe line number where the error occurred, 6421*8e3e3a7aSWarner Loshif this information is available. 6422*8e3e3a7aSWarner Losh 6423*8e3e3a7aSWarner Losh 6424*8e3e3a7aSWarner Losh<p> 6425*8e3e3a7aSWarner LoshThis function never returns, 6426*8e3e3a7aSWarner Loshbut it is an idiom to use it in C functions 6427*8e3e3a7aSWarner Loshas <code>return luaL_error(<em>args</em>)</code>. 6428*8e3e3a7aSWarner Losh 6429*8e3e3a7aSWarner Losh 6430*8e3e3a7aSWarner Losh 6431*8e3e3a7aSWarner Losh 6432*8e3e3a7aSWarner Losh 6433*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p> 6434*8e3e3a7aSWarner Losh<span class="apii">[-0, +3, <em>m</em>]</span> 6435*8e3e3a7aSWarner Losh<pre>int luaL_execresult (lua_State *L, int stat);</pre> 6436*8e3e3a7aSWarner Losh 6437*8e3e3a7aSWarner Losh<p> 6438*8e3e3a7aSWarner LoshThis function produces the return values for 6439*8e3e3a7aSWarner Loshprocess-related functions in the standard library 6440*8e3e3a7aSWarner Losh(<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>). 6441*8e3e3a7aSWarner Losh 6442*8e3e3a7aSWarner Losh 6443*8e3e3a7aSWarner Losh 6444*8e3e3a7aSWarner Losh 6445*8e3e3a7aSWarner Losh 6446*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p> 6447*8e3e3a7aSWarner Losh<span class="apii">[-0, +(1|3), <em>m</em>]</span> 6448*8e3e3a7aSWarner Losh<pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre> 6449*8e3e3a7aSWarner Losh 6450*8e3e3a7aSWarner Losh<p> 6451*8e3e3a7aSWarner LoshThis function produces the return values for 6452*8e3e3a7aSWarner Loshfile-related functions in the standard library 6453*8e3e3a7aSWarner 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.). 6454*8e3e3a7aSWarner Losh 6455*8e3e3a7aSWarner Losh 6456*8e3e3a7aSWarner Losh 6457*8e3e3a7aSWarner Losh 6458*8e3e3a7aSWarner Losh 6459*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> 6460*8e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), <em>m</em>]</span> 6461*8e3e3a7aSWarner Losh<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> 6462*8e3e3a7aSWarner Losh 6463*8e3e3a7aSWarner Losh<p> 6464*8e3e3a7aSWarner LoshPushes onto the stack the field <code>e</code> from the metatable 6465*8e3e3a7aSWarner Loshof the object at index <code>obj</code> and returns the type of pushed value. 6466*8e3e3a7aSWarner LoshIf the object does not have a metatable, 6467*8e3e3a7aSWarner Loshor if the metatable does not have this field, 6468*8e3e3a7aSWarner Loshpushes nothing and returns <code>LUA_TNIL</code>. 6469*8e3e3a7aSWarner Losh 6470*8e3e3a7aSWarner Losh 6471*8e3e3a7aSWarner Losh 6472*8e3e3a7aSWarner Losh 6473*8e3e3a7aSWarner Losh 6474*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> 6475*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 6476*8e3e3a7aSWarner Losh<pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre> 6477*8e3e3a7aSWarner Losh 6478*8e3e3a7aSWarner Losh<p> 6479*8e3e3a7aSWarner LoshPushes onto the stack the metatable associated with name <code>tname</code> 6480*8e3e3a7aSWarner Loshin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) 6481*8e3e3a7aSWarner Losh(<b>nil</b> if there is no metatable associated with that name). 6482*8e3e3a7aSWarner LoshReturns the type of the pushed value. 6483*8e3e3a7aSWarner Losh 6484*8e3e3a7aSWarner Losh 6485*8e3e3a7aSWarner Losh 6486*8e3e3a7aSWarner Losh 6487*8e3e3a7aSWarner Losh 6488*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p> 6489*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 6490*8e3e3a7aSWarner Losh<pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre> 6491*8e3e3a7aSWarner Losh 6492*8e3e3a7aSWarner Losh<p> 6493*8e3e3a7aSWarner LoshEnsures that the value <code>t[fname]</code>, 6494*8e3e3a7aSWarner Loshwhere <code>t</code> is the value at index <code>idx</code>, 6495*8e3e3a7aSWarner Loshis a table, 6496*8e3e3a7aSWarner Loshand pushes that table onto the stack. 6497*8e3e3a7aSWarner LoshReturns true if it finds a previous table there 6498*8e3e3a7aSWarner Loshand false if it creates a new table. 6499*8e3e3a7aSWarner Losh 6500*8e3e3a7aSWarner Losh 6501*8e3e3a7aSWarner Losh 6502*8e3e3a7aSWarner Losh 6503*8e3e3a7aSWarner Losh 6504*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> 6505*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 6506*8e3e3a7aSWarner Losh<pre>const char *luaL_gsub (lua_State *L, 6507*8e3e3a7aSWarner Losh const char *s, 6508*8e3e3a7aSWarner Losh const char *p, 6509*8e3e3a7aSWarner Losh const char *r);</pre> 6510*8e3e3a7aSWarner Losh 6511*8e3e3a7aSWarner Losh<p> 6512*8e3e3a7aSWarner LoshCreates a copy of string <code>s</code> by replacing 6513*8e3e3a7aSWarner Loshany occurrence of the string <code>p</code> 6514*8e3e3a7aSWarner Loshwith the string <code>r</code>. 6515*8e3e3a7aSWarner LoshPushes the resulting string on the stack and returns it. 6516*8e3e3a7aSWarner Losh 6517*8e3e3a7aSWarner Losh 6518*8e3e3a7aSWarner Losh 6519*8e3e3a7aSWarner Losh 6520*8e3e3a7aSWarner Losh 6521*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p> 6522*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 6523*8e3e3a7aSWarner Losh<pre>lua_Integer luaL_len (lua_State *L, int index);</pre> 6524*8e3e3a7aSWarner Losh 6525*8e3e3a7aSWarner Losh<p> 6526*8e3e3a7aSWarner LoshReturns the "length" of the value at the given index 6527*8e3e3a7aSWarner Loshas a number; 6528*8e3e3a7aSWarner Loshit is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). 6529*8e3e3a7aSWarner LoshRaises an error if the result of the operation is not an integer. 6530*8e3e3a7aSWarner Losh(This case only can happen through metamethods.) 6531*8e3e3a7aSWarner Losh 6532*8e3e3a7aSWarner Losh 6533*8e3e3a7aSWarner Losh 6534*8e3e3a7aSWarner Losh 6535*8e3e3a7aSWarner Losh 6536*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> 6537*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 6538*8e3e3a7aSWarner Losh<pre>int luaL_loadbuffer (lua_State *L, 6539*8e3e3a7aSWarner Losh const char *buff, 6540*8e3e3a7aSWarner Losh size_t sz, 6541*8e3e3a7aSWarner Losh const char *name);</pre> 6542*8e3e3a7aSWarner Losh 6543*8e3e3a7aSWarner Losh<p> 6544*8e3e3a7aSWarner LoshEquivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>. 6545*8e3e3a7aSWarner Losh 6546*8e3e3a7aSWarner Losh 6547*8e3e3a7aSWarner Losh 6548*8e3e3a7aSWarner Losh 6549*8e3e3a7aSWarner Losh 6550*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p> 6551*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 6552*8e3e3a7aSWarner Losh<pre>int luaL_loadbufferx (lua_State *L, 6553*8e3e3a7aSWarner Losh const char *buff, 6554*8e3e3a7aSWarner Losh size_t sz, 6555*8e3e3a7aSWarner Losh const char *name, 6556*8e3e3a7aSWarner Losh const char *mode);</pre> 6557*8e3e3a7aSWarner Losh 6558*8e3e3a7aSWarner Losh<p> 6559*8e3e3a7aSWarner LoshLoads a buffer as a Lua chunk. 6560*8e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the 6561*8e3e3a7aSWarner Loshbuffer pointed to by <code>buff</code> with size <code>sz</code>. 6562*8e3e3a7aSWarner Losh 6563*8e3e3a7aSWarner Losh 6564*8e3e3a7aSWarner Losh<p> 6565*8e3e3a7aSWarner LoshThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 6566*8e3e3a7aSWarner Losh<code>name</code> is the chunk name, 6567*8e3e3a7aSWarner Loshused for debug information and error messages. 6568*8e3e3a7aSWarner LoshThe string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. 6569*8e3e3a7aSWarner Losh 6570*8e3e3a7aSWarner Losh 6571*8e3e3a7aSWarner Losh 6572*8e3e3a7aSWarner Losh 6573*8e3e3a7aSWarner Losh 6574*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> 6575*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 6576*8e3e3a7aSWarner Losh<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> 6577*8e3e3a7aSWarner Losh 6578*8e3e3a7aSWarner Losh<p> 6579*8e3e3a7aSWarner LoshEquivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>. 6580*8e3e3a7aSWarner Losh 6581*8e3e3a7aSWarner Losh 6582*8e3e3a7aSWarner Losh 6583*8e3e3a7aSWarner Losh 6584*8e3e3a7aSWarner Losh 6585*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p> 6586*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 6587*8e3e3a7aSWarner Losh<pre>int luaL_loadfilex (lua_State *L, const char *filename, 6588*8e3e3a7aSWarner Losh const char *mode);</pre> 6589*8e3e3a7aSWarner Losh 6590*8e3e3a7aSWarner Losh<p> 6591*8e3e3a7aSWarner LoshLoads a file as a Lua chunk. 6592*8e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file 6593*8e3e3a7aSWarner Loshnamed <code>filename</code>. 6594*8e3e3a7aSWarner LoshIf <code>filename</code> is <code>NULL</code>, 6595*8e3e3a7aSWarner Loshthen it loads from the standard input. 6596*8e3e3a7aSWarner LoshThe first line in the file is ignored if it starts with a <code>#</code>. 6597*8e3e3a7aSWarner Losh 6598*8e3e3a7aSWarner Losh 6599*8e3e3a7aSWarner Losh<p> 6600*8e3e3a7aSWarner LoshThe string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. 6601*8e3e3a7aSWarner Losh 6602*8e3e3a7aSWarner Losh 6603*8e3e3a7aSWarner Losh<p> 6604*8e3e3a7aSWarner LoshThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, 6605*8e3e3a7aSWarner Loshbut it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> 6606*8e3e3a7aSWarner Loshfor file-related errors 6607*8e3e3a7aSWarner Losh(e.g., it cannot open or read the file). 6608*8e3e3a7aSWarner Losh 6609*8e3e3a7aSWarner Losh 6610*8e3e3a7aSWarner Losh<p> 6611*8e3e3a7aSWarner LoshAs <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 6612*8e3e3a7aSWarner Loshit does not run it. 6613*8e3e3a7aSWarner Losh 6614*8e3e3a7aSWarner Losh 6615*8e3e3a7aSWarner Losh 6616*8e3e3a7aSWarner Losh 6617*8e3e3a7aSWarner Losh 6618*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> 6619*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 6620*8e3e3a7aSWarner Losh<pre>int luaL_loadstring (lua_State *L, const char *s);</pre> 6621*8e3e3a7aSWarner Losh 6622*8e3e3a7aSWarner Losh<p> 6623*8e3e3a7aSWarner LoshLoads a string as a Lua chunk. 6624*8e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in 6625*8e3e3a7aSWarner Loshthe zero-terminated string <code>s</code>. 6626*8e3e3a7aSWarner Losh 6627*8e3e3a7aSWarner Losh 6628*8e3e3a7aSWarner Losh<p> 6629*8e3e3a7aSWarner LoshThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 6630*8e3e3a7aSWarner Losh 6631*8e3e3a7aSWarner Losh 6632*8e3e3a7aSWarner Losh<p> 6633*8e3e3a7aSWarner LoshAlso as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 6634*8e3e3a7aSWarner Loshit does not run it. 6635*8e3e3a7aSWarner Losh 6636*8e3e3a7aSWarner Losh 6637*8e3e3a7aSWarner Losh 6638*8e3e3a7aSWarner Losh 6639*8e3e3a7aSWarner Losh 6640*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p> 6641*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 6642*8e3e3a7aSWarner Losh<pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre> 6643*8e3e3a7aSWarner Losh 6644*8e3e3a7aSWarner Losh<p> 6645*8e3e3a7aSWarner LoshCreates a new table and registers there 6646*8e3e3a7aSWarner Loshthe functions in list <code>l</code>. 6647*8e3e3a7aSWarner Losh 6648*8e3e3a7aSWarner Losh 6649*8e3e3a7aSWarner Losh<p> 6650*8e3e3a7aSWarner LoshIt is implemented as the following macro: 6651*8e3e3a7aSWarner Losh 6652*8e3e3a7aSWarner Losh<pre> 6653*8e3e3a7aSWarner Losh (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0)) 6654*8e3e3a7aSWarner Losh</pre><p> 6655*8e3e3a7aSWarner LoshThe array <code>l</code> must be the actual array, 6656*8e3e3a7aSWarner Loshnot a pointer to it. 6657*8e3e3a7aSWarner Losh 6658*8e3e3a7aSWarner Losh 6659*8e3e3a7aSWarner Losh 6660*8e3e3a7aSWarner Losh 6661*8e3e3a7aSWarner Losh 6662*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p> 6663*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 6664*8e3e3a7aSWarner Losh<pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre> 6665*8e3e3a7aSWarner Losh 6666*8e3e3a7aSWarner Losh<p> 6667*8e3e3a7aSWarner LoshCreates a new table with a size optimized 6668*8e3e3a7aSWarner Loshto store all entries in the array <code>l</code> 6669*8e3e3a7aSWarner Losh(but does not actually store them). 6670*8e3e3a7aSWarner LoshIt is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> 6671*8e3e3a7aSWarner Losh(see <a href="#luaL_newlib"><code>luaL_newlib</code></a>). 6672*8e3e3a7aSWarner Losh 6673*8e3e3a7aSWarner Losh 6674*8e3e3a7aSWarner Losh<p> 6675*8e3e3a7aSWarner LoshIt is implemented as a macro. 6676*8e3e3a7aSWarner LoshThe array <code>l</code> must be the actual array, 6677*8e3e3a7aSWarner Loshnot a pointer to it. 6678*8e3e3a7aSWarner Losh 6679*8e3e3a7aSWarner Losh 6680*8e3e3a7aSWarner Losh 6681*8e3e3a7aSWarner Losh 6682*8e3e3a7aSWarner Losh 6683*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> 6684*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 6685*8e3e3a7aSWarner Losh<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> 6686*8e3e3a7aSWarner Losh 6687*8e3e3a7aSWarner Losh<p> 6688*8e3e3a7aSWarner LoshIf the registry already has the key <code>tname</code>, 6689*8e3e3a7aSWarner Loshreturns 0. 6690*8e3e3a7aSWarner LoshOtherwise, 6691*8e3e3a7aSWarner Loshcreates a new table to be used as a metatable for userdata, 6692*8e3e3a7aSWarner Loshadds to this new table the pair <code>__name = tname</code>, 6693*8e3e3a7aSWarner Loshadds to the registry the pair <code>[tname] = new table</code>, 6694*8e3e3a7aSWarner Loshand returns 1. 6695*8e3e3a7aSWarner Losh(The entry <code>__name</code> is used by some error-reporting functions.) 6696*8e3e3a7aSWarner Losh 6697*8e3e3a7aSWarner Losh 6698*8e3e3a7aSWarner Losh<p> 6699*8e3e3a7aSWarner LoshIn both cases pushes onto the stack the final value associated 6700*8e3e3a7aSWarner Loshwith <code>tname</code> in the registry. 6701*8e3e3a7aSWarner Losh 6702*8e3e3a7aSWarner Losh 6703*8e3e3a7aSWarner Losh 6704*8e3e3a7aSWarner Losh 6705*8e3e3a7aSWarner Losh 6706*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> 6707*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 6708*8e3e3a7aSWarner Losh<pre>lua_State *luaL_newstate (void);</pre> 6709*8e3e3a7aSWarner Losh 6710*8e3e3a7aSWarner Losh<p> 6711*8e3e3a7aSWarner LoshCreates a new Lua state. 6712*8e3e3a7aSWarner LoshIt calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an 6713*8e3e3a7aSWarner Loshallocator based on the standard C <code>realloc</code> function 6714*8e3e3a7aSWarner Loshand then sets a panic function (see <a href="#4.6">§4.6</a>) that prints 6715*8e3e3a7aSWarner Loshan error message to the standard error output in case of fatal 6716*8e3e3a7aSWarner Losherrors. 6717*8e3e3a7aSWarner Losh 6718*8e3e3a7aSWarner Losh 6719*8e3e3a7aSWarner Losh<p> 6720*8e3e3a7aSWarner LoshReturns the new state, 6721*8e3e3a7aSWarner Loshor <code>NULL</code> if there is a memory allocation error. 6722*8e3e3a7aSWarner Losh 6723*8e3e3a7aSWarner Losh 6724*8e3e3a7aSWarner Losh 6725*8e3e3a7aSWarner Losh 6726*8e3e3a7aSWarner Losh 6727*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> 6728*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 6729*8e3e3a7aSWarner Losh<pre>void luaL_openlibs (lua_State *L);</pre> 6730*8e3e3a7aSWarner Losh 6731*8e3e3a7aSWarner Losh<p> 6732*8e3e3a7aSWarner LoshOpens all standard Lua libraries into the given state. 6733*8e3e3a7aSWarner Losh 6734*8e3e3a7aSWarner Losh 6735*8e3e3a7aSWarner Losh 6736*8e3e3a7aSWarner Losh 6737*8e3e3a7aSWarner Losh 6738*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p> 6739*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 6740*8e3e3a7aSWarner Losh<pre>T luaL_opt (L, func, arg, dflt);</pre> 6741*8e3e3a7aSWarner Losh 6742*8e3e3a7aSWarner Losh<p> 6743*8e3e3a7aSWarner LoshThis macro is defined as follows: 6744*8e3e3a7aSWarner Losh 6745*8e3e3a7aSWarner Losh<pre> 6746*8e3e3a7aSWarner Losh (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg))) 6747*8e3e3a7aSWarner Losh</pre><p> 6748*8e3e3a7aSWarner LoshIn words, if the argument <code>arg</code> is nil or absent, 6749*8e3e3a7aSWarner Loshthe macro results in the default <code>dflt</code>. 6750*8e3e3a7aSWarner LoshOtherwise, it results in the result of calling <code>func</code> 6751*8e3e3a7aSWarner Loshwith the state <code>L</code> and the argument index <code>arg</code> as 6752*8e3e3a7aSWarner Loshparameters. 6753*8e3e3a7aSWarner LoshNote that it evaluates the expression <code>dflt</code> only if needed. 6754*8e3e3a7aSWarner Losh 6755*8e3e3a7aSWarner Losh 6756*8e3e3a7aSWarner Losh 6757*8e3e3a7aSWarner Losh 6758*8e3e3a7aSWarner Losh 6759*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> 6760*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6761*8e3e3a7aSWarner Losh<pre>lua_Integer luaL_optinteger (lua_State *L, 6762*8e3e3a7aSWarner Losh int arg, 6763*8e3e3a7aSWarner Losh lua_Integer d);</pre> 6764*8e3e3a7aSWarner Losh 6765*8e3e3a7aSWarner Losh<p> 6766*8e3e3a7aSWarner LoshIf the function argument <code>arg</code> is an integer 6767*8e3e3a7aSWarner Losh(or convertible to an integer), 6768*8e3e3a7aSWarner Loshreturns this integer. 6769*8e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>, 6770*8e3e3a7aSWarner Loshreturns <code>d</code>. 6771*8e3e3a7aSWarner LoshOtherwise, raises an error. 6772*8e3e3a7aSWarner Losh 6773*8e3e3a7aSWarner Losh 6774*8e3e3a7aSWarner Losh 6775*8e3e3a7aSWarner Losh 6776*8e3e3a7aSWarner Losh 6777*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> 6778*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6779*8e3e3a7aSWarner Losh<pre>const char *luaL_optlstring (lua_State *L, 6780*8e3e3a7aSWarner Losh int arg, 6781*8e3e3a7aSWarner Losh const char *d, 6782*8e3e3a7aSWarner Losh size_t *l);</pre> 6783*8e3e3a7aSWarner Losh 6784*8e3e3a7aSWarner Losh<p> 6785*8e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a string, 6786*8e3e3a7aSWarner Loshreturns this string. 6787*8e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>, 6788*8e3e3a7aSWarner Loshreturns <code>d</code>. 6789*8e3e3a7aSWarner LoshOtherwise, raises an error. 6790*8e3e3a7aSWarner Losh 6791*8e3e3a7aSWarner Losh 6792*8e3e3a7aSWarner Losh<p> 6793*8e3e3a7aSWarner LoshIf <code>l</code> is not <code>NULL</code>, 6794*8e3e3a7aSWarner Loshfills the position <code>*l</code> with the result's length. 6795*8e3e3a7aSWarner LoshIf the result is <code>NULL</code> 6796*8e3e3a7aSWarner Losh(only possible when returning <code>d</code> and <code>d == NULL</code>), 6797*8e3e3a7aSWarner Loshits length is considered zero. 6798*8e3e3a7aSWarner Losh 6799*8e3e3a7aSWarner Losh 6800*8e3e3a7aSWarner Losh<p> 6801*8e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6802*8e3e3a7aSWarner Loshso all conversions and caveats of that function apply here. 6803*8e3e3a7aSWarner Losh 6804*8e3e3a7aSWarner Losh 6805*8e3e3a7aSWarner Losh 6806*8e3e3a7aSWarner Losh 6807*8e3e3a7aSWarner Losh 6808*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> 6809*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6810*8e3e3a7aSWarner Losh<pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre> 6811*8e3e3a7aSWarner Losh 6812*8e3e3a7aSWarner Losh<p> 6813*8e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a number, 6814*8e3e3a7aSWarner Loshreturns this number. 6815*8e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>, 6816*8e3e3a7aSWarner Loshreturns <code>d</code>. 6817*8e3e3a7aSWarner LoshOtherwise, raises an error. 6818*8e3e3a7aSWarner Losh 6819*8e3e3a7aSWarner Losh 6820*8e3e3a7aSWarner Losh 6821*8e3e3a7aSWarner Losh 6822*8e3e3a7aSWarner Losh 6823*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> 6824*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 6825*8e3e3a7aSWarner Losh<pre>const char *luaL_optstring (lua_State *L, 6826*8e3e3a7aSWarner Losh int arg, 6827*8e3e3a7aSWarner Losh const char *d);</pre> 6828*8e3e3a7aSWarner Losh 6829*8e3e3a7aSWarner Losh<p> 6830*8e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a string, 6831*8e3e3a7aSWarner Loshreturns this string. 6832*8e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>, 6833*8e3e3a7aSWarner Loshreturns <code>d</code>. 6834*8e3e3a7aSWarner LoshOtherwise, raises an error. 6835*8e3e3a7aSWarner Losh 6836*8e3e3a7aSWarner Losh 6837*8e3e3a7aSWarner Losh 6838*8e3e3a7aSWarner Losh 6839*8e3e3a7aSWarner Losh 6840*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> 6841*8e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 6842*8e3e3a7aSWarner Losh<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> 6843*8e3e3a7aSWarner Losh 6844*8e3e3a7aSWarner Losh<p> 6845*8e3e3a7aSWarner LoshEquivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a> 6846*8e3e3a7aSWarner Loshwith the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>. 6847*8e3e3a7aSWarner Losh 6848*8e3e3a7aSWarner Losh 6849*8e3e3a7aSWarner Losh 6850*8e3e3a7aSWarner Losh 6851*8e3e3a7aSWarner Losh 6852*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p> 6853*8e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 6854*8e3e3a7aSWarner Losh<pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre> 6855*8e3e3a7aSWarner Losh 6856*8e3e3a7aSWarner Losh<p> 6857*8e3e3a7aSWarner LoshReturns an address to a space of size <code>sz</code> 6858*8e3e3a7aSWarner Loshwhere you can copy a string to be added to buffer <code>B</code> 6859*8e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6860*8e3e3a7aSWarner LoshAfter copying the string into this space you must call 6861*8e3e3a7aSWarner Losh<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add 6862*8e3e3a7aSWarner Loshit to the buffer. 6863*8e3e3a7aSWarner Losh 6864*8e3e3a7aSWarner Losh 6865*8e3e3a7aSWarner Losh 6866*8e3e3a7aSWarner Losh 6867*8e3e3a7aSWarner Losh 6868*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> 6869*8e3e3a7aSWarner Losh<span class="apii">[-?, +1, <em>m</em>]</span> 6870*8e3e3a7aSWarner Losh<pre>void luaL_pushresult (luaL_Buffer *B);</pre> 6871*8e3e3a7aSWarner Losh 6872*8e3e3a7aSWarner Losh<p> 6873*8e3e3a7aSWarner LoshFinishes the use of buffer <code>B</code> leaving the final string on 6874*8e3e3a7aSWarner Loshthe top of the stack. 6875*8e3e3a7aSWarner Losh 6876*8e3e3a7aSWarner Losh 6877*8e3e3a7aSWarner Losh 6878*8e3e3a7aSWarner Losh 6879*8e3e3a7aSWarner Losh 6880*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p> 6881*8e3e3a7aSWarner Losh<span class="apii">[-?, +1, <em>m</em>]</span> 6882*8e3e3a7aSWarner Losh<pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre> 6883*8e3e3a7aSWarner Losh 6884*8e3e3a7aSWarner Losh<p> 6885*8e3e3a7aSWarner LoshEquivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>. 6886*8e3e3a7aSWarner Losh 6887*8e3e3a7aSWarner Losh 6888*8e3e3a7aSWarner Losh 6889*8e3e3a7aSWarner Losh 6890*8e3e3a7aSWarner Losh 6891*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> 6892*8e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span> 6893*8e3e3a7aSWarner Losh<pre>int luaL_ref (lua_State *L, int t);</pre> 6894*8e3e3a7aSWarner Losh 6895*8e3e3a7aSWarner Losh<p> 6896*8e3e3a7aSWarner LoshCreates and returns a <em>reference</em>, 6897*8e3e3a7aSWarner Loshin the table at index <code>t</code>, 6898*8e3e3a7aSWarner Loshfor the object at the top of the stack (and pops the object). 6899*8e3e3a7aSWarner Losh 6900*8e3e3a7aSWarner Losh 6901*8e3e3a7aSWarner Losh<p> 6902*8e3e3a7aSWarner LoshA reference is a unique integer key. 6903*8e3e3a7aSWarner LoshAs long as you do not manually add integer keys into table <code>t</code>, 6904*8e3e3a7aSWarner Losh<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. 6905*8e3e3a7aSWarner LoshYou can retrieve an object referred by reference <code>r</code> 6906*8e3e3a7aSWarner Loshby calling <code>lua_rawgeti(L, t, r)</code>. 6907*8e3e3a7aSWarner LoshFunction <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object. 6908*8e3e3a7aSWarner Losh 6909*8e3e3a7aSWarner Losh 6910*8e3e3a7aSWarner Losh<p> 6911*8e3e3a7aSWarner LoshIf the object at the top of the stack is <b>nil</b>, 6912*8e3e3a7aSWarner Losh<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>. 6913*8e3e3a7aSWarner LoshThe constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different 6914*8e3e3a7aSWarner Loshfrom any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. 6915*8e3e3a7aSWarner Losh 6916*8e3e3a7aSWarner Losh 6917*8e3e3a7aSWarner Losh 6918*8e3e3a7aSWarner Losh 6919*8e3e3a7aSWarner Losh 6920*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> 6921*8e3e3a7aSWarner Losh<pre>typedef struct luaL_Reg { 6922*8e3e3a7aSWarner Losh const char *name; 6923*8e3e3a7aSWarner Losh lua_CFunction func; 6924*8e3e3a7aSWarner Losh} luaL_Reg;</pre> 6925*8e3e3a7aSWarner Losh 6926*8e3e3a7aSWarner Losh<p> 6927*8e3e3a7aSWarner LoshType for arrays of functions to be registered by 6928*8e3e3a7aSWarner Losh<a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>. 6929*8e3e3a7aSWarner Losh<code>name</code> is the function name and <code>func</code> is a pointer to 6930*8e3e3a7aSWarner Loshthe function. 6931*8e3e3a7aSWarner LoshAny array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry 6932*8e3e3a7aSWarner Loshin which both <code>name</code> and <code>func</code> are <code>NULL</code>. 6933*8e3e3a7aSWarner Losh 6934*8e3e3a7aSWarner Losh 6935*8e3e3a7aSWarner Losh 6936*8e3e3a7aSWarner Losh 6937*8e3e3a7aSWarner Losh 6938*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p> 6939*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 6940*8e3e3a7aSWarner Losh<pre>void luaL_requiref (lua_State *L, const char *modname, 6941*8e3e3a7aSWarner Losh lua_CFunction openf, int glb);</pre> 6942*8e3e3a7aSWarner Losh 6943*8e3e3a7aSWarner Losh<p> 6944*8e3e3a7aSWarner LoshIf <code>modname</code> is not already present in <a href="#pdf-package.loaded"><code>package.loaded</code></a>, 6945*8e3e3a7aSWarner Loshcalls function <code>openf</code> with string <code>modname</code> as an argument 6946*8e3e3a7aSWarner Loshand sets the call result in <code>package.loaded[modname]</code>, 6947*8e3e3a7aSWarner Loshas if that function has been called through <a href="#pdf-require"><code>require</code></a>. 6948*8e3e3a7aSWarner Losh 6949*8e3e3a7aSWarner Losh 6950*8e3e3a7aSWarner Losh<p> 6951*8e3e3a7aSWarner LoshIf <code>glb</code> is true, 6952*8e3e3a7aSWarner Loshalso stores the module into global <code>modname</code>. 6953*8e3e3a7aSWarner Losh 6954*8e3e3a7aSWarner Losh 6955*8e3e3a7aSWarner Losh<p> 6956*8e3e3a7aSWarner LoshLeaves a copy of the module on the stack. 6957*8e3e3a7aSWarner Losh 6958*8e3e3a7aSWarner Losh 6959*8e3e3a7aSWarner Losh 6960*8e3e3a7aSWarner Losh 6961*8e3e3a7aSWarner Losh 6962*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p> 6963*8e3e3a7aSWarner Losh<span class="apii">[-nup, +0, <em>m</em>]</span> 6964*8e3e3a7aSWarner Losh<pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre> 6965*8e3e3a7aSWarner Losh 6966*8e3e3a7aSWarner Losh<p> 6967*8e3e3a7aSWarner LoshRegisters all functions in the array <code>l</code> 6968*8e3e3a7aSWarner Losh(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack 6969*8e3e3a7aSWarner Losh(below optional upvalues, see next). 6970*8e3e3a7aSWarner Losh 6971*8e3e3a7aSWarner Losh 6972*8e3e3a7aSWarner Losh<p> 6973*8e3e3a7aSWarner LoshWhen <code>nup</code> is not zero, 6974*8e3e3a7aSWarner Loshall functions are created sharing <code>nup</code> upvalues, 6975*8e3e3a7aSWarner Loshwhich must be previously pushed on the stack 6976*8e3e3a7aSWarner Loshon top of the library table. 6977*8e3e3a7aSWarner LoshThese values are popped from the stack after the registration. 6978*8e3e3a7aSWarner Losh 6979*8e3e3a7aSWarner Losh 6980*8e3e3a7aSWarner Losh 6981*8e3e3a7aSWarner Losh 6982*8e3e3a7aSWarner Losh 6983*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p> 6984*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 6985*8e3e3a7aSWarner Losh<pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre> 6986*8e3e3a7aSWarner Losh 6987*8e3e3a7aSWarner Losh<p> 6988*8e3e3a7aSWarner LoshSets the metatable of the object at the top of the stack 6989*8e3e3a7aSWarner Loshas the metatable associated with name <code>tname</code> 6990*8e3e3a7aSWarner Loshin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 6991*8e3e3a7aSWarner Losh 6992*8e3e3a7aSWarner Losh 6993*8e3e3a7aSWarner Losh 6994*8e3e3a7aSWarner Losh 6995*8e3e3a7aSWarner Losh 6996*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3> 6997*8e3e3a7aSWarner Losh<pre>typedef struct luaL_Stream { 6998*8e3e3a7aSWarner Losh FILE *f; 6999*8e3e3a7aSWarner Losh lua_CFunction closef; 7000*8e3e3a7aSWarner Losh} luaL_Stream;</pre> 7001*8e3e3a7aSWarner Losh 7002*8e3e3a7aSWarner Losh<p> 7003*8e3e3a7aSWarner LoshThe standard representation for file handles, 7004*8e3e3a7aSWarner Loshwhich is used by the standard I/O library. 7005*8e3e3a7aSWarner Losh 7006*8e3e3a7aSWarner Losh 7007*8e3e3a7aSWarner Losh<p> 7008*8e3e3a7aSWarner LoshA file handle is implemented as a full userdata, 7009*8e3e3a7aSWarner Loshwith a metatable called <code>LUA_FILEHANDLE</code> 7010*8e3e3a7aSWarner Losh(where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name). 7011*8e3e3a7aSWarner LoshThe metatable is created by the I/O library 7012*8e3e3a7aSWarner Losh(see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 7013*8e3e3a7aSWarner Losh 7014*8e3e3a7aSWarner Losh 7015*8e3e3a7aSWarner Losh<p> 7016*8e3e3a7aSWarner LoshThis userdata must start with the structure <code>luaL_Stream</code>; 7017*8e3e3a7aSWarner Loshit can contain other data after this initial structure. 7018*8e3e3a7aSWarner LoshField <code>f</code> points to the corresponding C stream 7019*8e3e3a7aSWarner Losh(or it can be <code>NULL</code> to indicate an incompletely created handle). 7020*8e3e3a7aSWarner LoshField <code>closef</code> points to a Lua function 7021*8e3e3a7aSWarner Loshthat will be called to close the stream 7022*8e3e3a7aSWarner Loshwhen the handle is closed or collected; 7023*8e3e3a7aSWarner Loshthis function receives the file handle as its sole argument and 7024*8e3e3a7aSWarner Loshmust return either <b>true</b> (in case of success) 7025*8e3e3a7aSWarner Loshor <b>nil</b> plus an error message (in case of error). 7026*8e3e3a7aSWarner LoshOnce Lua calls this field, 7027*8e3e3a7aSWarner Loshit changes the field value to <code>NULL</code> 7028*8e3e3a7aSWarner Loshto signal that the handle is closed. 7029*8e3e3a7aSWarner Losh 7030*8e3e3a7aSWarner Losh 7031*8e3e3a7aSWarner Losh 7032*8e3e3a7aSWarner Losh 7033*8e3e3a7aSWarner Losh 7034*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p> 7035*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span> 7036*8e3e3a7aSWarner Losh<pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre> 7037*8e3e3a7aSWarner Losh 7038*8e3e3a7aSWarner Losh<p> 7039*8e3e3a7aSWarner LoshThis function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>, 7040*8e3e3a7aSWarner Loshexcept that, when the test fails, 7041*8e3e3a7aSWarner Loshit returns <code>NULL</code> instead of raising an error. 7042*8e3e3a7aSWarner Losh 7043*8e3e3a7aSWarner Losh 7044*8e3e3a7aSWarner Losh 7045*8e3e3a7aSWarner Losh 7046*8e3e3a7aSWarner Losh 7047*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p> 7048*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 7049*8e3e3a7aSWarner Losh<pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre> 7050*8e3e3a7aSWarner Losh 7051*8e3e3a7aSWarner Losh<p> 7052*8e3e3a7aSWarner LoshConverts any Lua value at the given index to a C string 7053*8e3e3a7aSWarner Loshin a reasonable format. 7054*8e3e3a7aSWarner LoshThe resulting string is pushed onto the stack and also 7055*8e3e3a7aSWarner Loshreturned by the function. 7056*8e3e3a7aSWarner LoshIf <code>len</code> is not <code>NULL</code>, 7057*8e3e3a7aSWarner Loshthe function also sets <code>*len</code> with the string length. 7058*8e3e3a7aSWarner Losh 7059*8e3e3a7aSWarner Losh 7060*8e3e3a7aSWarner Losh<p> 7061*8e3e3a7aSWarner LoshIf the value has a metatable with a <code>__tostring</code> field, 7062*8e3e3a7aSWarner Loshthen <code>luaL_tolstring</code> calls the corresponding metamethod 7063*8e3e3a7aSWarner Loshwith the value as argument, 7064*8e3e3a7aSWarner Loshand uses the result of the call as its result. 7065*8e3e3a7aSWarner Losh 7066*8e3e3a7aSWarner Losh 7067*8e3e3a7aSWarner Losh 7068*8e3e3a7aSWarner Losh 7069*8e3e3a7aSWarner Losh 7070*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p> 7071*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 7072*8e3e3a7aSWarner Losh<pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, 7073*8e3e3a7aSWarner Losh int level);</pre> 7074*8e3e3a7aSWarner Losh 7075*8e3e3a7aSWarner Losh<p> 7076*8e3e3a7aSWarner LoshCreates and pushes a traceback of the stack <code>L1</code>. 7077*8e3e3a7aSWarner LoshIf <code>msg</code> is not <code>NULL</code> it is appended 7078*8e3e3a7aSWarner Loshat the beginning of the traceback. 7079*8e3e3a7aSWarner LoshThe <code>level</code> parameter tells at which level 7080*8e3e3a7aSWarner Loshto start the traceback. 7081*8e3e3a7aSWarner Losh 7082*8e3e3a7aSWarner Losh 7083*8e3e3a7aSWarner Losh 7084*8e3e3a7aSWarner Losh 7085*8e3e3a7aSWarner Losh 7086*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> 7087*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 7088*8e3e3a7aSWarner Losh<pre>const char *luaL_typename (lua_State *L, int index);</pre> 7089*8e3e3a7aSWarner Losh 7090*8e3e3a7aSWarner Losh<p> 7091*8e3e3a7aSWarner LoshReturns the name of the type of the value at the given index. 7092*8e3e3a7aSWarner Losh 7093*8e3e3a7aSWarner Losh 7094*8e3e3a7aSWarner Losh 7095*8e3e3a7aSWarner Losh 7096*8e3e3a7aSWarner Losh 7097*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> 7098*8e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 7099*8e3e3a7aSWarner Losh<pre>void luaL_unref (lua_State *L, int t, int ref);</pre> 7100*8e3e3a7aSWarner Losh 7101*8e3e3a7aSWarner Losh<p> 7102*8e3e3a7aSWarner LoshReleases reference <code>ref</code> from the table at index <code>t</code> 7103*8e3e3a7aSWarner Losh(see <a href="#luaL_ref"><code>luaL_ref</code></a>). 7104*8e3e3a7aSWarner LoshThe entry is removed from the table, 7105*8e3e3a7aSWarner Loshso that the referred object can be collected. 7106*8e3e3a7aSWarner LoshThe reference <code>ref</code> is also freed to be used again. 7107*8e3e3a7aSWarner Losh 7108*8e3e3a7aSWarner Losh 7109*8e3e3a7aSWarner Losh<p> 7110*8e3e3a7aSWarner 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>, 7111*8e3e3a7aSWarner Losh<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. 7112*8e3e3a7aSWarner Losh 7113*8e3e3a7aSWarner Losh 7114*8e3e3a7aSWarner Losh 7115*8e3e3a7aSWarner Losh 7116*8e3e3a7aSWarner Losh 7117*8e3e3a7aSWarner Losh<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> 7118*8e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 7119*8e3e3a7aSWarner Losh<pre>void luaL_where (lua_State *L, int lvl);</pre> 7120*8e3e3a7aSWarner Losh 7121*8e3e3a7aSWarner Losh<p> 7122*8e3e3a7aSWarner LoshPushes onto the stack a string identifying the current position 7123*8e3e3a7aSWarner Loshof the control at level <code>lvl</code> in the call stack. 7124*8e3e3a7aSWarner LoshTypically this string has the following format: 7125*8e3e3a7aSWarner Losh 7126*8e3e3a7aSWarner Losh<pre> 7127*8e3e3a7aSWarner Losh <em>chunkname</em>:<em>currentline</em>: 7128*8e3e3a7aSWarner Losh</pre><p> 7129*8e3e3a7aSWarner LoshLevel 0 is the running function, 7130*8e3e3a7aSWarner Loshlevel 1 is the function that called the running function, 7131*8e3e3a7aSWarner Loshetc. 7132*8e3e3a7aSWarner Losh 7133*8e3e3a7aSWarner Losh 7134*8e3e3a7aSWarner Losh<p> 7135*8e3e3a7aSWarner LoshThis function is used to build a prefix for error messages. 7136*8e3e3a7aSWarner Losh 7137*8e3e3a7aSWarner Losh 7138*8e3e3a7aSWarner Losh 7139*8e3e3a7aSWarner Losh 7140*8e3e3a7aSWarner Losh 7141*8e3e3a7aSWarner Losh 7142*8e3e3a7aSWarner Losh 7143*8e3e3a7aSWarner Losh<h1>6 – <a name="6">Standard Libraries</a></h1> 7144*8e3e3a7aSWarner Losh 7145*8e3e3a7aSWarner Losh<p> 7146*8e3e3a7aSWarner LoshThe standard Lua libraries provide useful functions 7147*8e3e3a7aSWarner Loshthat are implemented directly through the C API. 7148*8e3e3a7aSWarner LoshSome of these functions provide essential services to the language 7149*8e3e3a7aSWarner Losh(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); 7150*8e3e3a7aSWarner Loshothers provide access to "outside" services (e.g., I/O); 7151*8e3e3a7aSWarner Loshand others could be implemented in Lua itself, 7152*8e3e3a7aSWarner Loshbut are quite useful or have critical performance requirements that 7153*8e3e3a7aSWarner Loshdeserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). 7154*8e3e3a7aSWarner Losh 7155*8e3e3a7aSWarner Losh 7156*8e3e3a7aSWarner Losh<p> 7157*8e3e3a7aSWarner LoshAll libraries are implemented through the official C API 7158*8e3e3a7aSWarner Loshand are provided as separate C modules. 7159*8e3e3a7aSWarner LoshCurrently, Lua has the following standard libraries: 7160*8e3e3a7aSWarner Losh 7161*8e3e3a7aSWarner Losh<ul> 7162*8e3e3a7aSWarner Losh 7163*8e3e3a7aSWarner Losh<li>basic library (<a href="#6.1">§6.1</a>);</li> 7164*8e3e3a7aSWarner Losh 7165*8e3e3a7aSWarner Losh<li>coroutine library (<a href="#6.2">§6.2</a>);</li> 7166*8e3e3a7aSWarner Losh 7167*8e3e3a7aSWarner Losh<li>package library (<a href="#6.3">§6.3</a>);</li> 7168*8e3e3a7aSWarner Losh 7169*8e3e3a7aSWarner Losh<li>string manipulation (<a href="#6.4">§6.4</a>);</li> 7170*8e3e3a7aSWarner Losh 7171*8e3e3a7aSWarner Losh<li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li> 7172*8e3e3a7aSWarner Losh 7173*8e3e3a7aSWarner Losh<li>table manipulation (<a href="#6.6">§6.6</a>);</li> 7174*8e3e3a7aSWarner Losh 7175*8e3e3a7aSWarner Losh<li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li> 7176*8e3e3a7aSWarner Losh 7177*8e3e3a7aSWarner Losh<li>input and output (<a href="#6.8">§6.8</a>);</li> 7178*8e3e3a7aSWarner Losh 7179*8e3e3a7aSWarner Losh<li>operating system facilities (<a href="#6.9">§6.9</a>);</li> 7180*8e3e3a7aSWarner Losh 7181*8e3e3a7aSWarner Losh<li>debug facilities (<a href="#6.10">§6.10</a>).</li> 7182*8e3e3a7aSWarner Losh 7183*8e3e3a7aSWarner Losh</ul><p> 7184*8e3e3a7aSWarner LoshExcept for the basic and the package libraries, 7185*8e3e3a7aSWarner Losheach library provides all its functions as fields of a global table 7186*8e3e3a7aSWarner Loshor as methods of its objects. 7187*8e3e3a7aSWarner Losh 7188*8e3e3a7aSWarner Losh 7189*8e3e3a7aSWarner Losh<p> 7190*8e3e3a7aSWarner LoshTo have access to these libraries, 7191*8e3e3a7aSWarner Loshthe C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, 7192*8e3e3a7aSWarner Loshwhich opens all standard libraries. 7193*8e3e3a7aSWarner LoshAlternatively, 7194*8e3e3a7aSWarner Loshthe host program can open them individually by using 7195*8e3e3a7aSWarner Losh<a href="#luaL_requiref"><code>luaL_requiref</code></a> to call 7196*8e3e3a7aSWarner Losh<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), 7197*8e3e3a7aSWarner Losh<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), 7198*8e3e3a7aSWarner Losh<a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library), 7199*8e3e3a7aSWarner Losh<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), 7200*8e3e3a7aSWarner Losh<a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF8 library), 7201*8e3e3a7aSWarner Losh<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), 7202*8e3e3a7aSWarner Losh<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), 7203*8e3e3a7aSWarner Losh<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), 7204*8e3e3a7aSWarner Losh<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library), 7205*8e3e3a7aSWarner Loshand <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). 7206*8e3e3a7aSWarner LoshThese functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>. 7207*8e3e3a7aSWarner Losh 7208*8e3e3a7aSWarner Losh 7209*8e3e3a7aSWarner Losh 7210*8e3e3a7aSWarner Losh<h2>6.1 – <a name="6.1">Basic Functions</a></h2> 7211*8e3e3a7aSWarner Losh 7212*8e3e3a7aSWarner Losh<p> 7213*8e3e3a7aSWarner LoshThe basic library provides core functions to Lua. 7214*8e3e3a7aSWarner LoshIf you do not include this library in your application, 7215*8e3e3a7aSWarner Loshyou should check carefully whether you need to provide 7216*8e3e3a7aSWarner Loshimplementations for some of its facilities. 7217*8e3e3a7aSWarner Losh 7218*8e3e3a7aSWarner Losh 7219*8e3e3a7aSWarner Losh<p> 7220*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> 7221*8e3e3a7aSWarner Losh 7222*8e3e3a7aSWarner Losh 7223*8e3e3a7aSWarner Losh<p> 7224*8e3e3a7aSWarner LoshCalls <a href="#pdf-error"><code>error</code></a> if 7225*8e3e3a7aSWarner Loshthe value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); 7226*8e3e3a7aSWarner Loshotherwise, returns all its arguments. 7227*8e3e3a7aSWarner LoshIn case of error, 7228*8e3e3a7aSWarner Losh<code>message</code> is the error object; 7229*8e3e3a7aSWarner Loshwhen absent, it defaults to "<code>assertion failed!</code>" 7230*8e3e3a7aSWarner Losh 7231*8e3e3a7aSWarner Losh 7232*8e3e3a7aSWarner Losh 7233*8e3e3a7aSWarner Losh 7234*8e3e3a7aSWarner Losh<p> 7235*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3> 7236*8e3e3a7aSWarner Losh 7237*8e3e3a7aSWarner Losh 7238*8e3e3a7aSWarner Losh<p> 7239*8e3e3a7aSWarner LoshThis function is a generic interface to the garbage collector. 7240*8e3e3a7aSWarner LoshIt performs different functions according to its first argument, <code>opt</code>: 7241*8e3e3a7aSWarner Losh 7242*8e3e3a7aSWarner Losh<ul> 7243*8e3e3a7aSWarner Losh 7244*8e3e3a7aSWarner Losh<li><b>"<code>collect</code>": </b> 7245*8e3e3a7aSWarner Loshperforms a full garbage-collection cycle. 7246*8e3e3a7aSWarner LoshThis is the default option. 7247*8e3e3a7aSWarner Losh</li> 7248*8e3e3a7aSWarner Losh 7249*8e3e3a7aSWarner Losh<li><b>"<code>stop</code>": </b> 7250*8e3e3a7aSWarner Loshstops automatic execution of the garbage collector. 7251*8e3e3a7aSWarner LoshThe collector will run only when explicitly invoked, 7252*8e3e3a7aSWarner Loshuntil a call to restart it. 7253*8e3e3a7aSWarner Losh</li> 7254*8e3e3a7aSWarner Losh 7255*8e3e3a7aSWarner Losh<li><b>"<code>restart</code>": </b> 7256*8e3e3a7aSWarner Loshrestarts automatic execution of the garbage collector. 7257*8e3e3a7aSWarner Losh</li> 7258*8e3e3a7aSWarner Losh 7259*8e3e3a7aSWarner Losh<li><b>"<code>count</code>": </b> 7260*8e3e3a7aSWarner Loshreturns the total memory in use by Lua in Kbytes. 7261*8e3e3a7aSWarner LoshThe value has a fractional part, 7262*8e3e3a7aSWarner Loshso that it multiplied by 1024 7263*8e3e3a7aSWarner Loshgives the exact number of bytes in use by Lua 7264*8e3e3a7aSWarner Losh(except for overflows). 7265*8e3e3a7aSWarner Losh</li> 7266*8e3e3a7aSWarner Losh 7267*8e3e3a7aSWarner Losh<li><b>"<code>step</code>": </b> 7268*8e3e3a7aSWarner Loshperforms a garbage-collection step. 7269*8e3e3a7aSWarner LoshThe step "size" is controlled by <code>arg</code>. 7270*8e3e3a7aSWarner LoshWith a zero value, 7271*8e3e3a7aSWarner Loshthe collector will perform one basic (indivisible) step. 7272*8e3e3a7aSWarner LoshFor non-zero values, 7273*8e3e3a7aSWarner Loshthe collector will perform as if that amount of memory 7274*8e3e3a7aSWarner Losh(in KBytes) had been allocated by Lua. 7275*8e3e3a7aSWarner LoshReturns <b>true</b> if the step finished a collection cycle. 7276*8e3e3a7aSWarner Losh</li> 7277*8e3e3a7aSWarner Losh 7278*8e3e3a7aSWarner Losh<li><b>"<code>setpause</code>": </b> 7279*8e3e3a7aSWarner Loshsets <code>arg</code> as the new value for the <em>pause</em> of 7280*8e3e3a7aSWarner Loshthe collector (see <a href="#2.5">§2.5</a>). 7281*8e3e3a7aSWarner LoshReturns the previous value for <em>pause</em>. 7282*8e3e3a7aSWarner Losh</li> 7283*8e3e3a7aSWarner Losh 7284*8e3e3a7aSWarner Losh<li><b>"<code>setstepmul</code>": </b> 7285*8e3e3a7aSWarner Loshsets <code>arg</code> as the new value for the <em>step multiplier</em> of 7286*8e3e3a7aSWarner Loshthe collector (see <a href="#2.5">§2.5</a>). 7287*8e3e3a7aSWarner LoshReturns the previous value for <em>step</em>. 7288*8e3e3a7aSWarner Losh</li> 7289*8e3e3a7aSWarner Losh 7290*8e3e3a7aSWarner Losh<li><b>"<code>isrunning</code>": </b> 7291*8e3e3a7aSWarner Loshreturns a boolean that tells whether the collector is running 7292*8e3e3a7aSWarner Losh(i.e., not stopped). 7293*8e3e3a7aSWarner Losh</li> 7294*8e3e3a7aSWarner Losh 7295*8e3e3a7aSWarner Losh</ul> 7296*8e3e3a7aSWarner Losh 7297*8e3e3a7aSWarner Losh 7298*8e3e3a7aSWarner Losh 7299*8e3e3a7aSWarner Losh<p> 7300*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> 7301*8e3e3a7aSWarner LoshOpens the named file and executes its contents as a Lua chunk. 7302*8e3e3a7aSWarner LoshWhen called without arguments, 7303*8e3e3a7aSWarner Losh<code>dofile</code> executes the contents of the standard input (<code>stdin</code>). 7304*8e3e3a7aSWarner LoshReturns all values returned by the chunk. 7305*8e3e3a7aSWarner LoshIn case of errors, <code>dofile</code> propagates the error 7306*8e3e3a7aSWarner Loshto its caller (that is, <code>dofile</code> does not run in protected mode). 7307*8e3e3a7aSWarner Losh 7308*8e3e3a7aSWarner Losh 7309*8e3e3a7aSWarner Losh 7310*8e3e3a7aSWarner Losh 7311*8e3e3a7aSWarner Losh<p> 7312*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> 7313*8e3e3a7aSWarner LoshTerminates the last protected function called 7314*8e3e3a7aSWarner Loshand returns <code>message</code> as the error object. 7315*8e3e3a7aSWarner LoshFunction <code>error</code> never returns. 7316*8e3e3a7aSWarner Losh 7317*8e3e3a7aSWarner Losh 7318*8e3e3a7aSWarner Losh<p> 7319*8e3e3a7aSWarner LoshUsually, <code>error</code> adds some information about the error position 7320*8e3e3a7aSWarner Loshat the beginning of the message, if the message is a string. 7321*8e3e3a7aSWarner LoshThe <code>level</code> argument specifies how to get the error position. 7322*8e3e3a7aSWarner LoshWith level 1 (the default), the error position is where the 7323*8e3e3a7aSWarner Losh<code>error</code> function was called. 7324*8e3e3a7aSWarner LoshLevel 2 points the error to where the function 7325*8e3e3a7aSWarner Loshthat called <code>error</code> was called; and so on. 7326*8e3e3a7aSWarner LoshPassing a level 0 avoids the addition of error position information 7327*8e3e3a7aSWarner Loshto the message. 7328*8e3e3a7aSWarner Losh 7329*8e3e3a7aSWarner Losh 7330*8e3e3a7aSWarner Losh 7331*8e3e3a7aSWarner Losh 7332*8e3e3a7aSWarner Losh<p> 7333*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-_G"><code>_G</code></a></h3> 7334*8e3e3a7aSWarner LoshA global variable (not a function) that 7335*8e3e3a7aSWarner Loshholds the global environment (see <a href="#2.2">§2.2</a>). 7336*8e3e3a7aSWarner LoshLua itself does not use this variable; 7337*8e3e3a7aSWarner Loshchanging its value does not affect any environment, 7338*8e3e3a7aSWarner Loshnor vice versa. 7339*8e3e3a7aSWarner Losh 7340*8e3e3a7aSWarner Losh 7341*8e3e3a7aSWarner Losh 7342*8e3e3a7aSWarner Losh 7343*8e3e3a7aSWarner Losh<p> 7344*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> 7345*8e3e3a7aSWarner Losh 7346*8e3e3a7aSWarner Losh 7347*8e3e3a7aSWarner Losh<p> 7348*8e3e3a7aSWarner LoshIf <code>object</code> does not have a metatable, returns <b>nil</b>. 7349*8e3e3a7aSWarner LoshOtherwise, 7350*8e3e3a7aSWarner Loshif the object's metatable has a <code>__metatable</code> field, 7351*8e3e3a7aSWarner Loshreturns the associated value. 7352*8e3e3a7aSWarner LoshOtherwise, returns the metatable of the given object. 7353*8e3e3a7aSWarner Losh 7354*8e3e3a7aSWarner Losh 7355*8e3e3a7aSWarner Losh 7356*8e3e3a7aSWarner Losh 7357*8e3e3a7aSWarner Losh<p> 7358*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> 7359*8e3e3a7aSWarner Losh 7360*8e3e3a7aSWarner Losh 7361*8e3e3a7aSWarner Losh<p> 7362*8e3e3a7aSWarner LoshReturns three values (an iterator function, the table <code>t</code>, and 0) 7363*8e3e3a7aSWarner Loshso that the construction 7364*8e3e3a7aSWarner Losh 7365*8e3e3a7aSWarner Losh<pre> 7366*8e3e3a7aSWarner Losh for i,v in ipairs(t) do <em>body</em> end 7367*8e3e3a7aSWarner Losh</pre><p> 7368*8e3e3a7aSWarner Loshwill iterate over the key–value pairs 7369*8e3e3a7aSWarner Losh(<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., 7370*8e3e3a7aSWarner Loshup to the first nil value. 7371*8e3e3a7aSWarner Losh 7372*8e3e3a7aSWarner Losh 7373*8e3e3a7aSWarner Losh 7374*8e3e3a7aSWarner Losh 7375*8e3e3a7aSWarner Losh<p> 7376*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3> 7377*8e3e3a7aSWarner Losh 7378*8e3e3a7aSWarner Losh 7379*8e3e3a7aSWarner Losh<p> 7380*8e3e3a7aSWarner LoshLoads a chunk. 7381*8e3e3a7aSWarner Losh 7382*8e3e3a7aSWarner Losh 7383*8e3e3a7aSWarner Losh<p> 7384*8e3e3a7aSWarner LoshIf <code>chunk</code> is a string, the chunk is this string. 7385*8e3e3a7aSWarner LoshIf <code>chunk</code> is a function, 7386*8e3e3a7aSWarner Losh<code>load</code> calls it repeatedly to get the chunk pieces. 7387*8e3e3a7aSWarner LoshEach call to <code>chunk</code> must return a string that concatenates 7388*8e3e3a7aSWarner Loshwith previous results. 7389*8e3e3a7aSWarner LoshA return of an empty string, <b>nil</b>, or no value signals the end of the chunk. 7390*8e3e3a7aSWarner Losh 7391*8e3e3a7aSWarner Losh 7392*8e3e3a7aSWarner Losh<p> 7393*8e3e3a7aSWarner LoshIf there are no syntactic errors, 7394*8e3e3a7aSWarner Loshreturns the compiled chunk as a function; 7395*8e3e3a7aSWarner Loshotherwise, returns <b>nil</b> plus the error message. 7396*8e3e3a7aSWarner Losh 7397*8e3e3a7aSWarner Losh 7398*8e3e3a7aSWarner Losh<p> 7399*8e3e3a7aSWarner LoshIf the resulting function has upvalues, 7400*8e3e3a7aSWarner Loshthe first upvalue is set to the value of <code>env</code>, 7401*8e3e3a7aSWarner Loshif that parameter is given, 7402*8e3e3a7aSWarner Loshor to the value of the global environment. 7403*8e3e3a7aSWarner LoshOther upvalues are initialized with <b>nil</b>. 7404*8e3e3a7aSWarner Losh(When you load a main chunk, 7405*8e3e3a7aSWarner Loshthe resulting function will always have exactly one upvalue, 7406*8e3e3a7aSWarner Loshthe <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 7407*8e3e3a7aSWarner LoshHowever, 7408*8e3e3a7aSWarner Loshwhen you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>), 7409*8e3e3a7aSWarner Loshthe resulting function can have an arbitrary number of upvalues.) 7410*8e3e3a7aSWarner LoshAll upvalues are fresh, that is, 7411*8e3e3a7aSWarner Loshthey are not shared with any other function. 7412*8e3e3a7aSWarner Losh 7413*8e3e3a7aSWarner Losh 7414*8e3e3a7aSWarner Losh<p> 7415*8e3e3a7aSWarner Losh<code>chunkname</code> is used as the name of the chunk for error messages 7416*8e3e3a7aSWarner Loshand debug information (see <a href="#4.9">§4.9</a>). 7417*8e3e3a7aSWarner LoshWhen absent, 7418*8e3e3a7aSWarner Loshit defaults to <code>chunk</code>, if <code>chunk</code> is a string, 7419*8e3e3a7aSWarner Loshor to "<code>=(load)</code>" otherwise. 7420*8e3e3a7aSWarner Losh 7421*8e3e3a7aSWarner Losh 7422*8e3e3a7aSWarner Losh<p> 7423*8e3e3a7aSWarner LoshThe string <code>mode</code> controls whether the chunk can be text or binary 7424*8e3e3a7aSWarner Losh(that is, a precompiled chunk). 7425*8e3e3a7aSWarner LoshIt may be the string "<code>b</code>" (only binary chunks), 7426*8e3e3a7aSWarner Losh"<code>t</code>" (only text chunks), 7427*8e3e3a7aSWarner Loshor "<code>bt</code>" (both binary and text). 7428*8e3e3a7aSWarner LoshThe default is "<code>bt</code>". 7429*8e3e3a7aSWarner Losh 7430*8e3e3a7aSWarner Losh 7431*8e3e3a7aSWarner Losh<p> 7432*8e3e3a7aSWarner LoshLua does not check the consistency of binary chunks. 7433*8e3e3a7aSWarner LoshMaliciously crafted binary chunks can crash 7434*8e3e3a7aSWarner Loshthe interpreter. 7435*8e3e3a7aSWarner Losh 7436*8e3e3a7aSWarner Losh 7437*8e3e3a7aSWarner Losh 7438*8e3e3a7aSWarner Losh 7439*8e3e3a7aSWarner Losh<p> 7440*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3> 7441*8e3e3a7aSWarner Losh 7442*8e3e3a7aSWarner Losh 7443*8e3e3a7aSWarner Losh<p> 7444*8e3e3a7aSWarner LoshSimilar to <a href="#pdf-load"><code>load</code></a>, 7445*8e3e3a7aSWarner Loshbut gets the chunk from file <code>filename</code> 7446*8e3e3a7aSWarner Loshor from the standard input, 7447*8e3e3a7aSWarner Loshif no file name is given. 7448*8e3e3a7aSWarner Losh 7449*8e3e3a7aSWarner Losh 7450*8e3e3a7aSWarner Losh 7451*8e3e3a7aSWarner Losh 7452*8e3e3a7aSWarner Losh<p> 7453*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> 7454*8e3e3a7aSWarner Losh 7455*8e3e3a7aSWarner Losh 7456*8e3e3a7aSWarner Losh<p> 7457*8e3e3a7aSWarner LoshAllows a program to traverse all fields of a table. 7458*8e3e3a7aSWarner LoshIts first argument is a table and its second argument 7459*8e3e3a7aSWarner Loshis an index in this table. 7460*8e3e3a7aSWarner Losh<code>next</code> returns the next index of the table 7461*8e3e3a7aSWarner Loshand its associated value. 7462*8e3e3a7aSWarner LoshWhen called with <b>nil</b> as its second argument, 7463*8e3e3a7aSWarner Losh<code>next</code> returns an initial index 7464*8e3e3a7aSWarner Loshand its associated value. 7465*8e3e3a7aSWarner LoshWhen called with the last index, 7466*8e3e3a7aSWarner Loshor with <b>nil</b> in an empty table, 7467*8e3e3a7aSWarner Losh<code>next</code> returns <b>nil</b>. 7468*8e3e3a7aSWarner LoshIf the second argument is absent, then it is interpreted as <b>nil</b>. 7469*8e3e3a7aSWarner LoshIn particular, 7470*8e3e3a7aSWarner Loshyou can use <code>next(t)</code> to check whether a table is empty. 7471*8e3e3a7aSWarner Losh 7472*8e3e3a7aSWarner Losh 7473*8e3e3a7aSWarner Losh<p> 7474*8e3e3a7aSWarner LoshThe order in which the indices are enumerated is not specified, 7475*8e3e3a7aSWarner Losh<em>even for numeric indices</em>. 7476*8e3e3a7aSWarner Losh(To traverse a table in numerical order, 7477*8e3e3a7aSWarner Loshuse a numerical <b>for</b>.) 7478*8e3e3a7aSWarner Losh 7479*8e3e3a7aSWarner Losh 7480*8e3e3a7aSWarner Losh<p> 7481*8e3e3a7aSWarner LoshThe behavior of <code>next</code> is undefined if, 7482*8e3e3a7aSWarner Loshduring the traversal, 7483*8e3e3a7aSWarner Loshyou assign any value to a non-existent field in the table. 7484*8e3e3a7aSWarner LoshYou may however modify existing fields. 7485*8e3e3a7aSWarner LoshIn particular, you may clear existing fields. 7486*8e3e3a7aSWarner Losh 7487*8e3e3a7aSWarner Losh 7488*8e3e3a7aSWarner Losh 7489*8e3e3a7aSWarner Losh 7490*8e3e3a7aSWarner Losh<p> 7491*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> 7492*8e3e3a7aSWarner Losh 7493*8e3e3a7aSWarner Losh 7494*8e3e3a7aSWarner Losh<p> 7495*8e3e3a7aSWarner LoshIf <code>t</code> has a metamethod <code>__pairs</code>, 7496*8e3e3a7aSWarner Loshcalls it with <code>t</code> as argument and returns the first three 7497*8e3e3a7aSWarner Loshresults from the call. 7498*8e3e3a7aSWarner Losh 7499*8e3e3a7aSWarner Losh 7500*8e3e3a7aSWarner Losh<p> 7501*8e3e3a7aSWarner LoshOtherwise, 7502*8e3e3a7aSWarner Loshreturns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, 7503*8e3e3a7aSWarner Loshso that the construction 7504*8e3e3a7aSWarner Losh 7505*8e3e3a7aSWarner Losh<pre> 7506*8e3e3a7aSWarner Losh for k,v in pairs(t) do <em>body</em> end 7507*8e3e3a7aSWarner Losh</pre><p> 7508*8e3e3a7aSWarner Loshwill iterate over all key–value pairs of table <code>t</code>. 7509*8e3e3a7aSWarner Losh 7510*8e3e3a7aSWarner Losh 7511*8e3e3a7aSWarner Losh<p> 7512*8e3e3a7aSWarner LoshSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 7513*8e3e3a7aSWarner Loshthe table during its traversal. 7514*8e3e3a7aSWarner Losh 7515*8e3e3a7aSWarner Losh 7516*8e3e3a7aSWarner Losh 7517*8e3e3a7aSWarner Losh 7518*8e3e3a7aSWarner Losh<p> 7519*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3> 7520*8e3e3a7aSWarner Losh 7521*8e3e3a7aSWarner Losh 7522*8e3e3a7aSWarner Losh<p> 7523*8e3e3a7aSWarner LoshCalls function <code>f</code> with 7524*8e3e3a7aSWarner Loshthe given arguments in <em>protected mode</em>. 7525*8e3e3a7aSWarner LoshThis means that any error inside <code>f</code> is not propagated; 7526*8e3e3a7aSWarner Loshinstead, <code>pcall</code> catches the error 7527*8e3e3a7aSWarner Loshand returns a status code. 7528*8e3e3a7aSWarner LoshIts first result is the status code (a boolean), 7529*8e3e3a7aSWarner Loshwhich is true if the call succeeds without errors. 7530*8e3e3a7aSWarner LoshIn such case, <code>pcall</code> also returns all results from the call, 7531*8e3e3a7aSWarner Loshafter this first result. 7532*8e3e3a7aSWarner LoshIn case of any error, <code>pcall</code> returns <b>false</b> plus the error message. 7533*8e3e3a7aSWarner Losh 7534*8e3e3a7aSWarner Losh 7535*8e3e3a7aSWarner Losh 7536*8e3e3a7aSWarner Losh 7537*8e3e3a7aSWarner Losh<p> 7538*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> 7539*8e3e3a7aSWarner LoshReceives any number of arguments 7540*8e3e3a7aSWarner Loshand prints their values to <code>stdout</code>, 7541*8e3e3a7aSWarner Loshusing the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string. 7542*8e3e3a7aSWarner Losh<code>print</code> is not intended for formatted output, 7543*8e3e3a7aSWarner Loshbut only as a quick way to show a value, 7544*8e3e3a7aSWarner Loshfor instance for debugging. 7545*8e3e3a7aSWarner LoshFor complete control over the output, 7546*8e3e3a7aSWarner Loshuse <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. 7547*8e3e3a7aSWarner Losh 7548*8e3e3a7aSWarner Losh 7549*8e3e3a7aSWarner Losh 7550*8e3e3a7aSWarner Losh 7551*8e3e3a7aSWarner Losh<p> 7552*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> 7553*8e3e3a7aSWarner LoshChecks whether <code>v1</code> is equal to <code>v2</code>, 7554*8e3e3a7aSWarner Loshwithout invoking the <code>__eq</code> metamethod. 7555*8e3e3a7aSWarner LoshReturns a boolean. 7556*8e3e3a7aSWarner Losh 7557*8e3e3a7aSWarner Losh 7558*8e3e3a7aSWarner Losh 7559*8e3e3a7aSWarner Losh 7560*8e3e3a7aSWarner Losh<p> 7561*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> 7562*8e3e3a7aSWarner LoshGets the real value of <code>table[index]</code>, 7563*8e3e3a7aSWarner Loshwithout invoking the <code>__index</code> metamethod. 7564*8e3e3a7aSWarner Losh<code>table</code> must be a table; 7565*8e3e3a7aSWarner Losh<code>index</code> may be any value. 7566*8e3e3a7aSWarner Losh 7567*8e3e3a7aSWarner Losh 7568*8e3e3a7aSWarner Losh 7569*8e3e3a7aSWarner Losh 7570*8e3e3a7aSWarner Losh<p> 7571*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3> 7572*8e3e3a7aSWarner LoshReturns the length of the object <code>v</code>, 7573*8e3e3a7aSWarner Loshwhich must be a table or a string, 7574*8e3e3a7aSWarner Loshwithout invoking the <code>__len</code> metamethod. 7575*8e3e3a7aSWarner LoshReturns an integer. 7576*8e3e3a7aSWarner Losh 7577*8e3e3a7aSWarner Losh 7578*8e3e3a7aSWarner Losh 7579*8e3e3a7aSWarner Losh 7580*8e3e3a7aSWarner Losh<p> 7581*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> 7582*8e3e3a7aSWarner LoshSets the real value of <code>table[index]</code> to <code>value</code>, 7583*8e3e3a7aSWarner Loshwithout invoking the <code>__newindex</code> metamethod. 7584*8e3e3a7aSWarner Losh<code>table</code> must be a table, 7585*8e3e3a7aSWarner Losh<code>index</code> any value different from <b>nil</b> and NaN, 7586*8e3e3a7aSWarner Loshand <code>value</code> any Lua value. 7587*8e3e3a7aSWarner Losh 7588*8e3e3a7aSWarner Losh 7589*8e3e3a7aSWarner Losh<p> 7590*8e3e3a7aSWarner LoshThis function returns <code>table</code>. 7591*8e3e3a7aSWarner Losh 7592*8e3e3a7aSWarner Losh 7593*8e3e3a7aSWarner Losh 7594*8e3e3a7aSWarner Losh 7595*8e3e3a7aSWarner Losh<p> 7596*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> 7597*8e3e3a7aSWarner Losh 7598*8e3e3a7aSWarner Losh 7599*8e3e3a7aSWarner Losh<p> 7600*8e3e3a7aSWarner LoshIf <code>index</code> is a number, 7601*8e3e3a7aSWarner Loshreturns all arguments after argument number <code>index</code>; 7602*8e3e3a7aSWarner Losha negative number indexes from the end (-1 is the last argument). 7603*8e3e3a7aSWarner LoshOtherwise, <code>index</code> must be the string <code>"#"</code>, 7604*8e3e3a7aSWarner Loshand <code>select</code> returns the total number of extra arguments it received. 7605*8e3e3a7aSWarner Losh 7606*8e3e3a7aSWarner Losh 7607*8e3e3a7aSWarner Losh 7608*8e3e3a7aSWarner Losh 7609*8e3e3a7aSWarner Losh<p> 7610*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> 7611*8e3e3a7aSWarner Losh 7612*8e3e3a7aSWarner Losh 7613*8e3e3a7aSWarner Losh<p> 7614*8e3e3a7aSWarner LoshSets the metatable for the given table. 7615*8e3e3a7aSWarner Losh(To change the metatable of other types from Lua code, 7616*8e3e3a7aSWarner Loshyou must use the debug library (<a href="#6.10">§6.10</a>).) 7617*8e3e3a7aSWarner LoshIf <code>metatable</code> is <b>nil</b>, 7618*8e3e3a7aSWarner Loshremoves the metatable of the given table. 7619*8e3e3a7aSWarner LoshIf the original metatable has a <code>__metatable</code> field, 7620*8e3e3a7aSWarner Loshraises an error. 7621*8e3e3a7aSWarner Losh 7622*8e3e3a7aSWarner Losh 7623*8e3e3a7aSWarner Losh<p> 7624*8e3e3a7aSWarner LoshThis function returns <code>table</code>. 7625*8e3e3a7aSWarner Losh 7626*8e3e3a7aSWarner Losh 7627*8e3e3a7aSWarner Losh 7628*8e3e3a7aSWarner Losh 7629*8e3e3a7aSWarner Losh<p> 7630*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> 7631*8e3e3a7aSWarner Losh 7632*8e3e3a7aSWarner Losh 7633*8e3e3a7aSWarner Losh<p> 7634*8e3e3a7aSWarner LoshWhen called with no <code>base</code>, 7635*8e3e3a7aSWarner Losh<code>tonumber</code> tries to convert its argument to a number. 7636*8e3e3a7aSWarner LoshIf the argument is already a number or 7637*8e3e3a7aSWarner Losha string convertible to a number, 7638*8e3e3a7aSWarner Loshthen <code>tonumber</code> returns this number; 7639*8e3e3a7aSWarner Loshotherwise, it returns <b>nil</b>. 7640*8e3e3a7aSWarner Losh 7641*8e3e3a7aSWarner Losh 7642*8e3e3a7aSWarner Losh<p> 7643*8e3e3a7aSWarner LoshThe conversion of strings can result in integers or floats, 7644*8e3e3a7aSWarner Loshaccording to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 7645*8e3e3a7aSWarner Losh(The string may have leading and trailing spaces and a sign.) 7646*8e3e3a7aSWarner Losh 7647*8e3e3a7aSWarner Losh 7648*8e3e3a7aSWarner Losh<p> 7649*8e3e3a7aSWarner LoshWhen called with <code>base</code>, 7650*8e3e3a7aSWarner Loshthen <code>e</code> must be a string to be interpreted as 7651*8e3e3a7aSWarner Loshan integer numeral in that base. 7652*8e3e3a7aSWarner LoshThe base may be any integer between 2 and 36, inclusive. 7653*8e3e3a7aSWarner LoshIn bases above 10, the letter '<code>A</code>' (in either upper or lower case) 7654*8e3e3a7aSWarner Loshrepresents 10, '<code>B</code>' represents 11, and so forth, 7655*8e3e3a7aSWarner Loshwith '<code>Z</code>' representing 35. 7656*8e3e3a7aSWarner LoshIf the string <code>e</code> is not a valid numeral in the given base, 7657*8e3e3a7aSWarner Loshthe function returns <b>nil</b>. 7658*8e3e3a7aSWarner Losh 7659*8e3e3a7aSWarner Losh 7660*8e3e3a7aSWarner Losh 7661*8e3e3a7aSWarner Losh 7662*8e3e3a7aSWarner Losh<p> 7663*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3> 7664*8e3e3a7aSWarner LoshReceives a value of any type and 7665*8e3e3a7aSWarner Loshconverts it to a string in a human-readable format. 7666*8e3e3a7aSWarner Losh(For complete control of how numbers are converted, 7667*8e3e3a7aSWarner Loshuse <a href="#pdf-string.format"><code>string.format</code></a>.) 7668*8e3e3a7aSWarner Losh 7669*8e3e3a7aSWarner Losh 7670*8e3e3a7aSWarner Losh<p> 7671*8e3e3a7aSWarner LoshIf the metatable of <code>v</code> has a <code>__tostring</code> field, 7672*8e3e3a7aSWarner Loshthen <code>tostring</code> calls the corresponding value 7673*8e3e3a7aSWarner Loshwith <code>v</code> as argument, 7674*8e3e3a7aSWarner Loshand uses the result of the call as its result. 7675*8e3e3a7aSWarner Losh 7676*8e3e3a7aSWarner Losh 7677*8e3e3a7aSWarner Losh 7678*8e3e3a7aSWarner Losh 7679*8e3e3a7aSWarner Losh<p> 7680*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> 7681*8e3e3a7aSWarner LoshReturns the type of its only argument, coded as a string. 7682*8e3e3a7aSWarner LoshThe possible results of this function are 7683*8e3e3a7aSWarner Losh"<code>nil</code>" (a string, not the value <b>nil</b>), 7684*8e3e3a7aSWarner Losh"<code>number</code>", 7685*8e3e3a7aSWarner Losh"<code>string</code>", 7686*8e3e3a7aSWarner Losh"<code>boolean</code>", 7687*8e3e3a7aSWarner Losh"<code>table</code>", 7688*8e3e3a7aSWarner Losh"<code>function</code>", 7689*8e3e3a7aSWarner Losh"<code>thread</code>", 7690*8e3e3a7aSWarner Loshand "<code>userdata</code>". 7691*8e3e3a7aSWarner Losh 7692*8e3e3a7aSWarner Losh 7693*8e3e3a7aSWarner Losh 7694*8e3e3a7aSWarner Losh 7695*8e3e3a7aSWarner Losh<p> 7696*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> 7697*8e3e3a7aSWarner Losh 7698*8e3e3a7aSWarner Losh 7699*8e3e3a7aSWarner Losh<p> 7700*8e3e3a7aSWarner LoshA global variable (not a function) that 7701*8e3e3a7aSWarner Loshholds a string containing the running Lua version. 7702*8e3e3a7aSWarner LoshThe current value of this variable is "<code>Lua 5.3</code>". 7703*8e3e3a7aSWarner Losh 7704*8e3e3a7aSWarner Losh 7705*8e3e3a7aSWarner Losh 7706*8e3e3a7aSWarner Losh 7707*8e3e3a7aSWarner Losh<p> 7708*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3> 7709*8e3e3a7aSWarner Losh 7710*8e3e3a7aSWarner Losh 7711*8e3e3a7aSWarner Losh<p> 7712*8e3e3a7aSWarner LoshThis function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, 7713*8e3e3a7aSWarner Loshexcept that it sets a new message handler <code>msgh</code>. 7714*8e3e3a7aSWarner Losh 7715*8e3e3a7aSWarner Losh 7716*8e3e3a7aSWarner Losh 7717*8e3e3a7aSWarner Losh 7718*8e3e3a7aSWarner Losh 7719*8e3e3a7aSWarner Losh 7720*8e3e3a7aSWarner Losh 7721*8e3e3a7aSWarner Losh<h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2> 7722*8e3e3a7aSWarner Losh 7723*8e3e3a7aSWarner Losh<p> 7724*8e3e3a7aSWarner LoshThis library comprises the operations to manipulate coroutines, 7725*8e3e3a7aSWarner Loshwhich come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. 7726*8e3e3a7aSWarner LoshSee <a href="#2.6">§2.6</a> for a general description of coroutines. 7727*8e3e3a7aSWarner Losh 7728*8e3e3a7aSWarner Losh 7729*8e3e3a7aSWarner Losh<p> 7730*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> 7731*8e3e3a7aSWarner Losh 7732*8e3e3a7aSWarner Losh 7733*8e3e3a7aSWarner Losh<p> 7734*8e3e3a7aSWarner LoshCreates a new coroutine, with body <code>f</code>. 7735*8e3e3a7aSWarner Losh<code>f</code> must be a function. 7736*8e3e3a7aSWarner LoshReturns this new coroutine, 7737*8e3e3a7aSWarner Loshan object with type <code>"thread"</code>. 7738*8e3e3a7aSWarner Losh 7739*8e3e3a7aSWarner Losh 7740*8e3e3a7aSWarner Losh 7741*8e3e3a7aSWarner Losh 7742*8e3e3a7aSWarner Losh<p> 7743*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ()</code></a></h3> 7744*8e3e3a7aSWarner Losh 7745*8e3e3a7aSWarner Losh 7746*8e3e3a7aSWarner Losh<p> 7747*8e3e3a7aSWarner LoshReturns true when the running coroutine can yield. 7748*8e3e3a7aSWarner Losh 7749*8e3e3a7aSWarner Losh 7750*8e3e3a7aSWarner Losh<p> 7751*8e3e3a7aSWarner LoshA running coroutine is yieldable if it is not the main thread and 7752*8e3e3a7aSWarner Loshit is not inside a non-yieldable C function. 7753*8e3e3a7aSWarner Losh 7754*8e3e3a7aSWarner Losh 7755*8e3e3a7aSWarner Losh 7756*8e3e3a7aSWarner Losh 7757*8e3e3a7aSWarner Losh<p> 7758*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> 7759*8e3e3a7aSWarner Losh 7760*8e3e3a7aSWarner Losh 7761*8e3e3a7aSWarner Losh<p> 7762*8e3e3a7aSWarner LoshStarts or continues the execution of coroutine <code>co</code>. 7763*8e3e3a7aSWarner LoshThe first time you resume a coroutine, 7764*8e3e3a7aSWarner Loshit starts running its body. 7765*8e3e3a7aSWarner LoshThe values <code>val1</code>, ... are passed 7766*8e3e3a7aSWarner Loshas the arguments to the body function. 7767*8e3e3a7aSWarner LoshIf the coroutine has yielded, 7768*8e3e3a7aSWarner Losh<code>resume</code> restarts it; 7769*8e3e3a7aSWarner Loshthe values <code>val1</code>, ... are passed 7770*8e3e3a7aSWarner Loshas the results from the yield. 7771*8e3e3a7aSWarner Losh 7772*8e3e3a7aSWarner Losh 7773*8e3e3a7aSWarner Losh<p> 7774*8e3e3a7aSWarner LoshIf the coroutine runs without any errors, 7775*8e3e3a7aSWarner Losh<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> 7776*8e3e3a7aSWarner Losh(when the coroutine yields) or any values returned by the body function 7777*8e3e3a7aSWarner Losh(when the coroutine terminates). 7778*8e3e3a7aSWarner LoshIf there is any error, 7779*8e3e3a7aSWarner Losh<code>resume</code> returns <b>false</b> plus the error message. 7780*8e3e3a7aSWarner Losh 7781*8e3e3a7aSWarner Losh 7782*8e3e3a7aSWarner Losh 7783*8e3e3a7aSWarner Losh 7784*8e3e3a7aSWarner Losh<p> 7785*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> 7786*8e3e3a7aSWarner Losh 7787*8e3e3a7aSWarner Losh 7788*8e3e3a7aSWarner Losh<p> 7789*8e3e3a7aSWarner LoshReturns the running coroutine plus a boolean, 7790*8e3e3a7aSWarner Loshtrue when the running coroutine is the main one. 7791*8e3e3a7aSWarner Losh 7792*8e3e3a7aSWarner Losh 7793*8e3e3a7aSWarner Losh 7794*8e3e3a7aSWarner Losh 7795*8e3e3a7aSWarner Losh<p> 7796*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> 7797*8e3e3a7aSWarner Losh 7798*8e3e3a7aSWarner Losh 7799*8e3e3a7aSWarner Losh<p> 7800*8e3e3a7aSWarner LoshReturns the status of coroutine <code>co</code>, as a string: 7801*8e3e3a7aSWarner Losh<code>"running"</code>, 7802*8e3e3a7aSWarner Loshif the coroutine is running (that is, it called <code>status</code>); 7803*8e3e3a7aSWarner Losh<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, 7804*8e3e3a7aSWarner Loshor if it has not started running yet; 7805*8e3e3a7aSWarner Losh<code>"normal"</code> if the coroutine is active but not running 7806*8e3e3a7aSWarner Losh(that is, it has resumed another coroutine); 7807*8e3e3a7aSWarner Loshand <code>"dead"</code> if the coroutine has finished its body function, 7808*8e3e3a7aSWarner Loshor if it has stopped with an error. 7809*8e3e3a7aSWarner Losh 7810*8e3e3a7aSWarner Losh 7811*8e3e3a7aSWarner Losh 7812*8e3e3a7aSWarner Losh 7813*8e3e3a7aSWarner Losh<p> 7814*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> 7815*8e3e3a7aSWarner Losh 7816*8e3e3a7aSWarner Losh 7817*8e3e3a7aSWarner Losh<p> 7818*8e3e3a7aSWarner LoshCreates a new coroutine, with body <code>f</code>. 7819*8e3e3a7aSWarner Losh<code>f</code> must be a function. 7820*8e3e3a7aSWarner LoshReturns a function that resumes the coroutine each time it is called. 7821*8e3e3a7aSWarner LoshAny arguments passed to the function behave as the 7822*8e3e3a7aSWarner Loshextra arguments to <code>resume</code>. 7823*8e3e3a7aSWarner LoshReturns the same values returned by <code>resume</code>, 7824*8e3e3a7aSWarner Loshexcept the first boolean. 7825*8e3e3a7aSWarner LoshIn case of error, propagates the error. 7826*8e3e3a7aSWarner Losh 7827*8e3e3a7aSWarner Losh 7828*8e3e3a7aSWarner Losh 7829*8e3e3a7aSWarner Losh 7830*8e3e3a7aSWarner Losh<p> 7831*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> 7832*8e3e3a7aSWarner Losh 7833*8e3e3a7aSWarner Losh 7834*8e3e3a7aSWarner Losh<p> 7835*8e3e3a7aSWarner LoshSuspends the execution of the calling coroutine. 7836*8e3e3a7aSWarner LoshAny arguments to <code>yield</code> are passed as extra results to <code>resume</code>. 7837*8e3e3a7aSWarner Losh 7838*8e3e3a7aSWarner Losh 7839*8e3e3a7aSWarner Losh 7840*8e3e3a7aSWarner Losh 7841*8e3e3a7aSWarner Losh 7842*8e3e3a7aSWarner Losh 7843*8e3e3a7aSWarner Losh 7844*8e3e3a7aSWarner Losh<h2>6.3 – <a name="6.3">Modules</a></h2> 7845*8e3e3a7aSWarner Losh 7846*8e3e3a7aSWarner Losh<p> 7847*8e3e3a7aSWarner LoshThe package library provides basic 7848*8e3e3a7aSWarner Loshfacilities for loading modules in Lua. 7849*8e3e3a7aSWarner LoshIt exports one function directly in the global environment: 7850*8e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a>. 7851*8e3e3a7aSWarner LoshEverything else is exported in a table <a name="pdf-package"><code>package</code></a>. 7852*8e3e3a7aSWarner Losh 7853*8e3e3a7aSWarner Losh 7854*8e3e3a7aSWarner Losh<p> 7855*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> 7856*8e3e3a7aSWarner Losh 7857*8e3e3a7aSWarner Losh 7858*8e3e3a7aSWarner Losh<p> 7859*8e3e3a7aSWarner LoshLoads the given module. 7860*8e3e3a7aSWarner LoshThe function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table 7861*8e3e3a7aSWarner Loshto determine whether <code>modname</code> is already loaded. 7862*8e3e3a7aSWarner LoshIf it is, then <code>require</code> returns the value stored 7863*8e3e3a7aSWarner Loshat <code>package.loaded[modname]</code>. 7864*8e3e3a7aSWarner LoshOtherwise, it tries to find a <em>loader</em> for the module. 7865*8e3e3a7aSWarner Losh 7866*8e3e3a7aSWarner Losh 7867*8e3e3a7aSWarner Losh<p> 7868*8e3e3a7aSWarner LoshTo find a loader, 7869*8e3e3a7aSWarner Losh<code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence. 7870*8e3e3a7aSWarner LoshBy changing this sequence, 7871*8e3e3a7aSWarner Loshwe can change how <code>require</code> looks for a module. 7872*8e3e3a7aSWarner LoshThe following explanation is based on the default configuration 7873*8e3e3a7aSWarner Loshfor <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 7874*8e3e3a7aSWarner Losh 7875*8e3e3a7aSWarner Losh 7876*8e3e3a7aSWarner Losh<p> 7877*8e3e3a7aSWarner LoshFirst <code>require</code> queries <code>package.preload[modname]</code>. 7878*8e3e3a7aSWarner LoshIf it has a value, 7879*8e3e3a7aSWarner Loshthis value (which must be a function) is the loader. 7880*8e3e3a7aSWarner LoshOtherwise <code>require</code> searches for a Lua loader using the 7881*8e3e3a7aSWarner Loshpath stored in <a href="#pdf-package.path"><code>package.path</code></a>. 7882*8e3e3a7aSWarner LoshIf that also fails, it searches for a C loader using the 7883*8e3e3a7aSWarner Loshpath stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 7884*8e3e3a7aSWarner LoshIf that also fails, 7885*8e3e3a7aSWarner Loshit tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>). 7886*8e3e3a7aSWarner Losh 7887*8e3e3a7aSWarner Losh 7888*8e3e3a7aSWarner Losh<p> 7889*8e3e3a7aSWarner LoshOnce a loader is found, 7890*8e3e3a7aSWarner Losh<code>require</code> calls the loader with two arguments: 7891*8e3e3a7aSWarner Losh<code>modname</code> and an extra value dependent on how it got the loader. 7892*8e3e3a7aSWarner Losh(If the loader came from a file, 7893*8e3e3a7aSWarner Loshthis extra value is the file name.) 7894*8e3e3a7aSWarner LoshIf the loader returns any non-nil value, 7895*8e3e3a7aSWarner Losh<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. 7896*8e3e3a7aSWarner LoshIf the loader does not return a non-nil value and 7897*8e3e3a7aSWarner Loshhas not assigned any value to <code>package.loaded[modname]</code>, 7898*8e3e3a7aSWarner Loshthen <code>require</code> assigns <b>true</b> to this entry. 7899*8e3e3a7aSWarner LoshIn any case, <code>require</code> returns the 7900*8e3e3a7aSWarner Loshfinal value of <code>package.loaded[modname]</code>. 7901*8e3e3a7aSWarner Losh 7902*8e3e3a7aSWarner Losh 7903*8e3e3a7aSWarner Losh<p> 7904*8e3e3a7aSWarner LoshIf there is any error loading or running the module, 7905*8e3e3a7aSWarner Loshor if it cannot find any loader for the module, 7906*8e3e3a7aSWarner Loshthen <code>require</code> raises an error. 7907*8e3e3a7aSWarner Losh 7908*8e3e3a7aSWarner Losh 7909*8e3e3a7aSWarner Losh 7910*8e3e3a7aSWarner Losh 7911*8e3e3a7aSWarner Losh<p> 7912*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3> 7913*8e3e3a7aSWarner Losh 7914*8e3e3a7aSWarner Losh 7915*8e3e3a7aSWarner Losh<p> 7916*8e3e3a7aSWarner LoshA string describing some compile-time configurations for packages. 7917*8e3e3a7aSWarner LoshThis string is a sequence of lines: 7918*8e3e3a7aSWarner Losh 7919*8e3e3a7aSWarner Losh<ul> 7920*8e3e3a7aSWarner Losh 7921*8e3e3a7aSWarner Losh<li>The first line is the directory separator string. 7922*8e3e3a7aSWarner LoshDefault is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li> 7923*8e3e3a7aSWarner Losh 7924*8e3e3a7aSWarner Losh<li>The second line is the character that separates templates in a path. 7925*8e3e3a7aSWarner LoshDefault is '<code>;</code>'.</li> 7926*8e3e3a7aSWarner Losh 7927*8e3e3a7aSWarner Losh<li>The third line is the string that marks the 7928*8e3e3a7aSWarner Loshsubstitution points in a template. 7929*8e3e3a7aSWarner LoshDefault is '<code>?</code>'.</li> 7930*8e3e3a7aSWarner Losh 7931*8e3e3a7aSWarner Losh<li>The fourth line is a string that, in a path in Windows, 7932*8e3e3a7aSWarner Loshis replaced by the executable's directory. 7933*8e3e3a7aSWarner LoshDefault is '<code>!</code>'.</li> 7934*8e3e3a7aSWarner Losh 7935*8e3e3a7aSWarner Losh<li>The fifth line is a mark to ignore all text after it 7936*8e3e3a7aSWarner Loshwhen building the <code>luaopen_</code> function name. 7937*8e3e3a7aSWarner LoshDefault is '<code>-</code>'.</li> 7938*8e3e3a7aSWarner Losh 7939*8e3e3a7aSWarner Losh</ul> 7940*8e3e3a7aSWarner Losh 7941*8e3e3a7aSWarner Losh 7942*8e3e3a7aSWarner Losh 7943*8e3e3a7aSWarner Losh<p> 7944*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> 7945*8e3e3a7aSWarner Losh 7946*8e3e3a7aSWarner Losh 7947*8e3e3a7aSWarner Losh<p> 7948*8e3e3a7aSWarner LoshThe path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. 7949*8e3e3a7aSWarner Losh 7950*8e3e3a7aSWarner Losh 7951*8e3e3a7aSWarner Losh<p> 7952*8e3e3a7aSWarner LoshLua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way 7953*8e3e3a7aSWarner Loshit initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, 7954*8e3e3a7aSWarner Loshusing the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>, 7955*8e3e3a7aSWarner Loshor the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>, 7956*8e3e3a7aSWarner Loshor a default path defined in <code>luaconf.h</code>. 7957*8e3e3a7aSWarner Losh 7958*8e3e3a7aSWarner Losh 7959*8e3e3a7aSWarner Losh 7960*8e3e3a7aSWarner Losh 7961*8e3e3a7aSWarner Losh<p> 7962*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> 7963*8e3e3a7aSWarner Losh 7964*8e3e3a7aSWarner Losh 7965*8e3e3a7aSWarner Losh<p> 7966*8e3e3a7aSWarner LoshA table used by <a href="#pdf-require"><code>require</code></a> to control which 7967*8e3e3a7aSWarner Loshmodules are already loaded. 7968*8e3e3a7aSWarner LoshWhen you require a module <code>modname</code> and 7969*8e3e3a7aSWarner Losh<code>package.loaded[modname]</code> is not false, 7970*8e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a> simply returns the value stored there. 7971*8e3e3a7aSWarner Losh 7972*8e3e3a7aSWarner Losh 7973*8e3e3a7aSWarner Losh<p> 7974*8e3e3a7aSWarner LoshThis variable is only a reference to the real table; 7975*8e3e3a7aSWarner Loshassignments to this variable do not change the 7976*8e3e3a7aSWarner Loshtable used by <a href="#pdf-require"><code>require</code></a>. 7977*8e3e3a7aSWarner Losh 7978*8e3e3a7aSWarner Losh 7979*8e3e3a7aSWarner Losh 7980*8e3e3a7aSWarner Losh 7981*8e3e3a7aSWarner Losh<p> 7982*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> 7983*8e3e3a7aSWarner Losh 7984*8e3e3a7aSWarner Losh 7985*8e3e3a7aSWarner Losh<p> 7986*8e3e3a7aSWarner LoshDynamically links the host program with the C library <code>libname</code>. 7987*8e3e3a7aSWarner Losh 7988*8e3e3a7aSWarner Losh 7989*8e3e3a7aSWarner Losh<p> 7990*8e3e3a7aSWarner LoshIf <code>funcname</code> is "<code>*</code>", 7991*8e3e3a7aSWarner Loshthen it only links with the library, 7992*8e3e3a7aSWarner Loshmaking the symbols exported by the library 7993*8e3e3a7aSWarner Loshavailable to other dynamically linked libraries. 7994*8e3e3a7aSWarner LoshOtherwise, 7995*8e3e3a7aSWarner Loshit looks for a function <code>funcname</code> inside the library 7996*8e3e3a7aSWarner Loshand returns this function as a C function. 7997*8e3e3a7aSWarner LoshSo, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype 7998*8e3e3a7aSWarner Losh(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 7999*8e3e3a7aSWarner Losh 8000*8e3e3a7aSWarner Losh 8001*8e3e3a7aSWarner Losh<p> 8002*8e3e3a7aSWarner LoshThis is a low-level function. 8003*8e3e3a7aSWarner LoshIt completely bypasses the package and module system. 8004*8e3e3a7aSWarner LoshUnlike <a href="#pdf-require"><code>require</code></a>, 8005*8e3e3a7aSWarner Loshit does not perform any path searching and 8006*8e3e3a7aSWarner Loshdoes not automatically adds extensions. 8007*8e3e3a7aSWarner Losh<code>libname</code> must be the complete file name of the C library, 8008*8e3e3a7aSWarner Loshincluding if necessary a path and an extension. 8009*8e3e3a7aSWarner Losh<code>funcname</code> must be the exact name exported by the C library 8010*8e3e3a7aSWarner Losh(which may depend on the C compiler and linker used). 8011*8e3e3a7aSWarner Losh 8012*8e3e3a7aSWarner Losh 8013*8e3e3a7aSWarner Losh<p> 8014*8e3e3a7aSWarner LoshThis function is not supported by Standard C. 8015*8e3e3a7aSWarner LoshAs such, it is only available on some platforms 8016*8e3e3a7aSWarner Losh(Windows, Linux, Mac OS X, Solaris, BSD, 8017*8e3e3a7aSWarner Loshplus other Unix systems that support the <code>dlfcn</code> standard). 8018*8e3e3a7aSWarner Losh 8019*8e3e3a7aSWarner Losh 8020*8e3e3a7aSWarner Losh 8021*8e3e3a7aSWarner Losh 8022*8e3e3a7aSWarner Losh<p> 8023*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> 8024*8e3e3a7aSWarner Losh 8025*8e3e3a7aSWarner Losh 8026*8e3e3a7aSWarner Losh<p> 8027*8e3e3a7aSWarner LoshThe path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. 8028*8e3e3a7aSWarner Losh 8029*8e3e3a7aSWarner Losh 8030*8e3e3a7aSWarner Losh<p> 8031*8e3e3a7aSWarner LoshAt start-up, Lua initializes this variable with 8032*8e3e3a7aSWarner Loshthe value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or 8033*8e3e3a7aSWarner Loshthe environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or 8034*8e3e3a7aSWarner Loshwith a default path defined in <code>luaconf.h</code>, 8035*8e3e3a7aSWarner Loshif those environment variables are not defined. 8036*8e3e3a7aSWarner LoshAny "<code>;;</code>" in the value of the environment variable 8037*8e3e3a7aSWarner Loshis replaced by the default path. 8038*8e3e3a7aSWarner Losh 8039*8e3e3a7aSWarner Losh 8040*8e3e3a7aSWarner Losh 8041*8e3e3a7aSWarner Losh 8042*8e3e3a7aSWarner Losh<p> 8043*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> 8044*8e3e3a7aSWarner Losh 8045*8e3e3a7aSWarner Losh 8046*8e3e3a7aSWarner Losh<p> 8047*8e3e3a7aSWarner LoshA table to store loaders for specific modules 8048*8e3e3a7aSWarner Losh(see <a href="#pdf-require"><code>require</code></a>). 8049*8e3e3a7aSWarner Losh 8050*8e3e3a7aSWarner Losh 8051*8e3e3a7aSWarner Losh<p> 8052*8e3e3a7aSWarner LoshThis variable is only a reference to the real table; 8053*8e3e3a7aSWarner Loshassignments to this variable do not change the 8054*8e3e3a7aSWarner Loshtable used by <a href="#pdf-require"><code>require</code></a>. 8055*8e3e3a7aSWarner Losh 8056*8e3e3a7aSWarner Losh 8057*8e3e3a7aSWarner Losh 8058*8e3e3a7aSWarner Losh 8059*8e3e3a7aSWarner Losh<p> 8060*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3> 8061*8e3e3a7aSWarner Losh 8062*8e3e3a7aSWarner Losh 8063*8e3e3a7aSWarner Losh<p> 8064*8e3e3a7aSWarner LoshA table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules. 8065*8e3e3a7aSWarner Losh 8066*8e3e3a7aSWarner Losh 8067*8e3e3a7aSWarner Losh<p> 8068*8e3e3a7aSWarner LoshEach entry in this table is a <em>searcher function</em>. 8069*8e3e3a7aSWarner LoshWhen looking for a module, 8070*8e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, 8071*8e3e3a7aSWarner Loshwith the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its 8072*8e3e3a7aSWarner Loshsole parameter. 8073*8e3e3a7aSWarner LoshThe function can return another function (the module <em>loader</em>) 8074*8e3e3a7aSWarner Loshplus an extra value that will be passed to that loader, 8075*8e3e3a7aSWarner Loshor a string explaining why it did not find that module 8076*8e3e3a7aSWarner Losh(or <b>nil</b> if it has nothing to say). 8077*8e3e3a7aSWarner Losh 8078*8e3e3a7aSWarner Losh 8079*8e3e3a7aSWarner Losh<p> 8080*8e3e3a7aSWarner LoshLua initializes this table with four searcher functions. 8081*8e3e3a7aSWarner Losh 8082*8e3e3a7aSWarner Losh 8083*8e3e3a7aSWarner Losh<p> 8084*8e3e3a7aSWarner LoshThe first searcher simply looks for a loader in the 8085*8e3e3a7aSWarner Losh<a href="#pdf-package.preload"><code>package.preload</code></a> table. 8086*8e3e3a7aSWarner Losh 8087*8e3e3a7aSWarner Losh 8088*8e3e3a7aSWarner Losh<p> 8089*8e3e3a7aSWarner LoshThe second searcher looks for a loader as a Lua library, 8090*8e3e3a7aSWarner Loshusing the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. 8091*8e3e3a7aSWarner LoshThe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8092*8e3e3a7aSWarner Losh 8093*8e3e3a7aSWarner Losh 8094*8e3e3a7aSWarner Losh<p> 8095*8e3e3a7aSWarner LoshThe third searcher looks for a loader as a C library, 8096*8e3e3a7aSWarner Loshusing the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 8097*8e3e3a7aSWarner LoshAgain, 8098*8e3e3a7aSWarner Loshthe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8099*8e3e3a7aSWarner LoshFor instance, 8100*8e3e3a7aSWarner Loshif the C path is the string 8101*8e3e3a7aSWarner Losh 8102*8e3e3a7aSWarner Losh<pre> 8103*8e3e3a7aSWarner Losh "./?.so;./?.dll;/usr/local/?/init.so" 8104*8e3e3a7aSWarner Losh</pre><p> 8105*8e3e3a7aSWarner Loshthe searcher for module <code>foo</code> 8106*8e3e3a7aSWarner Loshwill try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, 8107*8e3e3a7aSWarner Loshand <code>/usr/local/foo/init.so</code>, in that order. 8108*8e3e3a7aSWarner LoshOnce it finds a C library, 8109*8e3e3a7aSWarner Loshthis searcher first uses a dynamic link facility to link the 8110*8e3e3a7aSWarner Loshapplication with the library. 8111*8e3e3a7aSWarner LoshThen it tries to find a C function inside the library to 8112*8e3e3a7aSWarner Loshbe used as the loader. 8113*8e3e3a7aSWarner LoshThe name of this C function is the string "<code>luaopen_</code>" 8114*8e3e3a7aSWarner Loshconcatenated with a copy of the module name where each dot 8115*8e3e3a7aSWarner Loshis replaced by an underscore. 8116*8e3e3a7aSWarner LoshMoreover, if the module name has a hyphen, 8117*8e3e3a7aSWarner Loshits suffix after (and including) the first hyphen is removed. 8118*8e3e3a7aSWarner LoshFor instance, if the module name is <code>a.b.c-v2.1</code>, 8119*8e3e3a7aSWarner Loshthe function name will be <code>luaopen_a_b_c</code>. 8120*8e3e3a7aSWarner Losh 8121*8e3e3a7aSWarner Losh 8122*8e3e3a7aSWarner Losh<p> 8123*8e3e3a7aSWarner LoshThe fourth searcher tries an <em>all-in-one loader</em>. 8124*8e3e3a7aSWarner LoshIt searches the C path for a library for 8125*8e3e3a7aSWarner Loshthe root name of the given module. 8126*8e3e3a7aSWarner LoshFor instance, when requiring <code>a.b.c</code>, 8127*8e3e3a7aSWarner Loshit will search for a C library for <code>a</code>. 8128*8e3e3a7aSWarner LoshIf found, it looks into it for an open function for 8129*8e3e3a7aSWarner Loshthe submodule; 8130*8e3e3a7aSWarner Loshin our example, that would be <code>luaopen_a_b_c</code>. 8131*8e3e3a7aSWarner LoshWith this facility, a package can pack several C submodules 8132*8e3e3a7aSWarner Loshinto one single library, 8133*8e3e3a7aSWarner Loshwith each submodule keeping its original open function. 8134*8e3e3a7aSWarner Losh 8135*8e3e3a7aSWarner Losh 8136*8e3e3a7aSWarner Losh<p> 8137*8e3e3a7aSWarner LoshAll searchers except the first one (preload) return as the extra value 8138*8e3e3a7aSWarner Loshthe file name where the module was found, 8139*8e3e3a7aSWarner Loshas returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8140*8e3e3a7aSWarner LoshThe first searcher returns no extra value. 8141*8e3e3a7aSWarner Losh 8142*8e3e3a7aSWarner Losh 8143*8e3e3a7aSWarner Losh 8144*8e3e3a7aSWarner Losh 8145*8e3e3a7aSWarner Losh<p> 8146*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3> 8147*8e3e3a7aSWarner Losh 8148*8e3e3a7aSWarner Losh 8149*8e3e3a7aSWarner Losh<p> 8150*8e3e3a7aSWarner LoshSearches for the given <code>name</code> in the given <code>path</code>. 8151*8e3e3a7aSWarner Losh 8152*8e3e3a7aSWarner Losh 8153*8e3e3a7aSWarner Losh<p> 8154*8e3e3a7aSWarner LoshA path is a string containing a sequence of 8155*8e3e3a7aSWarner Losh<em>templates</em> separated by semicolons. 8156*8e3e3a7aSWarner LoshFor each template, 8157*8e3e3a7aSWarner Loshthe function replaces each interrogation mark (if any) 8158*8e3e3a7aSWarner Loshin the template with a copy of <code>name</code> 8159*8e3e3a7aSWarner Loshwherein all occurrences of <code>sep</code> 8160*8e3e3a7aSWarner Losh(a dot, by default) 8161*8e3e3a7aSWarner Loshwere replaced by <code>rep</code> 8162*8e3e3a7aSWarner Losh(the system's directory separator, by default), 8163*8e3e3a7aSWarner Loshand then tries to open the resulting file name. 8164*8e3e3a7aSWarner Losh 8165*8e3e3a7aSWarner Losh 8166*8e3e3a7aSWarner Losh<p> 8167*8e3e3a7aSWarner LoshFor instance, if the path is the string 8168*8e3e3a7aSWarner Losh 8169*8e3e3a7aSWarner Losh<pre> 8170*8e3e3a7aSWarner Losh "./?.lua;./?.lc;/usr/local/?/init.lua" 8171*8e3e3a7aSWarner Losh</pre><p> 8172*8e3e3a7aSWarner Loshthe search for the name <code>foo.a</code> 8173*8e3e3a7aSWarner Loshwill try to open the files 8174*8e3e3a7aSWarner Losh<code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and 8175*8e3e3a7aSWarner Losh<code>/usr/local/foo/a/init.lua</code>, in that order. 8176*8e3e3a7aSWarner Losh 8177*8e3e3a7aSWarner Losh 8178*8e3e3a7aSWarner Losh<p> 8179*8e3e3a7aSWarner LoshReturns the resulting name of the first file that it can 8180*8e3e3a7aSWarner Loshopen in read mode (after closing the file), 8181*8e3e3a7aSWarner Loshor <b>nil</b> plus an error message if none succeeds. 8182*8e3e3a7aSWarner Losh(This error message lists all file names it tried to open.) 8183*8e3e3a7aSWarner Losh 8184*8e3e3a7aSWarner Losh 8185*8e3e3a7aSWarner Losh 8186*8e3e3a7aSWarner Losh 8187*8e3e3a7aSWarner Losh 8188*8e3e3a7aSWarner Losh 8189*8e3e3a7aSWarner Losh 8190*8e3e3a7aSWarner Losh<h2>6.4 – <a name="6.4">String Manipulation</a></h2> 8191*8e3e3a7aSWarner Losh 8192*8e3e3a7aSWarner Losh<p> 8193*8e3e3a7aSWarner LoshThis library provides generic functions for string manipulation, 8194*8e3e3a7aSWarner Loshsuch as finding and extracting substrings, and pattern matching. 8195*8e3e3a7aSWarner LoshWhen indexing a string in Lua, the first character is at position 1 8196*8e3e3a7aSWarner Losh(not at 0, as in C). 8197*8e3e3a7aSWarner LoshIndices are allowed to be negative and are interpreted as indexing backwards, 8198*8e3e3a7aSWarner Loshfrom the end of the string. 8199*8e3e3a7aSWarner LoshThus, the last character is at position -1, and so on. 8200*8e3e3a7aSWarner Losh 8201*8e3e3a7aSWarner Losh 8202*8e3e3a7aSWarner Losh<p> 8203*8e3e3a7aSWarner LoshThe string library provides all its functions inside the table 8204*8e3e3a7aSWarner Losh<a name="pdf-string"><code>string</code></a>. 8205*8e3e3a7aSWarner LoshIt also sets a metatable for strings 8206*8e3e3a7aSWarner Loshwhere the <code>__index</code> field points to the <code>string</code> table. 8207*8e3e3a7aSWarner LoshTherefore, you can use the string functions in object-oriented style. 8208*8e3e3a7aSWarner LoshFor instance, <code>string.byte(s,i)</code> 8209*8e3e3a7aSWarner Loshcan be written as <code>s:byte(i)</code>. 8210*8e3e3a7aSWarner Losh 8211*8e3e3a7aSWarner Losh 8212*8e3e3a7aSWarner Losh<p> 8213*8e3e3a7aSWarner LoshThe string library assumes one-byte character encodings. 8214*8e3e3a7aSWarner Losh 8215*8e3e3a7aSWarner Losh 8216*8e3e3a7aSWarner Losh<p> 8217*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> 8218*8e3e3a7aSWarner LoshReturns the internal numeric codes of the characters <code>s[i]</code>, 8219*8e3e3a7aSWarner Losh<code>s[i+1]</code>, ..., <code>s[j]</code>. 8220*8e3e3a7aSWarner LoshThe default value for <code>i</code> is 1; 8221*8e3e3a7aSWarner Loshthe default value for <code>j</code> is <code>i</code>. 8222*8e3e3a7aSWarner LoshThese indices are corrected 8223*8e3e3a7aSWarner Loshfollowing the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>. 8224*8e3e3a7aSWarner Losh 8225*8e3e3a7aSWarner Losh 8226*8e3e3a7aSWarner Losh<p> 8227*8e3e3a7aSWarner LoshNumeric codes are not necessarily portable across platforms. 8228*8e3e3a7aSWarner Losh 8229*8e3e3a7aSWarner Losh 8230*8e3e3a7aSWarner Losh 8231*8e3e3a7aSWarner Losh 8232*8e3e3a7aSWarner Losh<p> 8233*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> 8234*8e3e3a7aSWarner LoshReceives zero or more integers. 8235*8e3e3a7aSWarner LoshReturns a string with length equal to the number of arguments, 8236*8e3e3a7aSWarner Loshin which each character has the internal numeric code equal 8237*8e3e3a7aSWarner Loshto its corresponding argument. 8238*8e3e3a7aSWarner Losh 8239*8e3e3a7aSWarner Losh 8240*8e3e3a7aSWarner Losh<p> 8241*8e3e3a7aSWarner LoshNumeric codes are not necessarily portable across platforms. 8242*8e3e3a7aSWarner Losh 8243*8e3e3a7aSWarner Losh 8244*8e3e3a7aSWarner Losh 8245*8e3e3a7aSWarner Losh 8246*8e3e3a7aSWarner Losh<p> 8247*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3> 8248*8e3e3a7aSWarner Losh 8249*8e3e3a7aSWarner Losh 8250*8e3e3a7aSWarner Losh<p> 8251*8e3e3a7aSWarner LoshReturns a string containing a binary representation 8252*8e3e3a7aSWarner Losh(a <em>binary chunk</em>) 8253*8e3e3a7aSWarner Loshof the given function, 8254*8e3e3a7aSWarner Loshso that a later <a href="#pdf-load"><code>load</code></a> on this string returns 8255*8e3e3a7aSWarner Losha copy of the function (but with new upvalues). 8256*8e3e3a7aSWarner LoshIf <code>strip</code> is a true value, 8257*8e3e3a7aSWarner Loshthe binary representation may not include all debug information 8258*8e3e3a7aSWarner Loshabout the function, 8259*8e3e3a7aSWarner Loshto save space. 8260*8e3e3a7aSWarner Losh 8261*8e3e3a7aSWarner Losh 8262*8e3e3a7aSWarner Losh<p> 8263*8e3e3a7aSWarner LoshFunctions with upvalues have only their number of upvalues saved. 8264*8e3e3a7aSWarner LoshWhen (re)loaded, 8265*8e3e3a7aSWarner Loshthose upvalues receive fresh instances containing <b>nil</b>. 8266*8e3e3a7aSWarner Losh(You can use the debug library to serialize 8267*8e3e3a7aSWarner Loshand reload the upvalues of a function 8268*8e3e3a7aSWarner Loshin a way adequate to your needs.) 8269*8e3e3a7aSWarner Losh 8270*8e3e3a7aSWarner Losh 8271*8e3e3a7aSWarner Losh 8272*8e3e3a7aSWarner Losh 8273*8e3e3a7aSWarner Losh<p> 8274*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> 8275*8e3e3a7aSWarner Losh 8276*8e3e3a7aSWarner Losh 8277*8e3e3a7aSWarner Losh<p> 8278*8e3e3a7aSWarner LoshLooks for the first match of 8279*8e3e3a7aSWarner Losh<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 8280*8e3e3a7aSWarner LoshIf it finds a match, then <code>find</code> returns the indices of <code>s</code> 8281*8e3e3a7aSWarner Loshwhere this occurrence starts and ends; 8282*8e3e3a7aSWarner Loshotherwise, it returns <b>nil</b>. 8283*8e3e3a7aSWarner LoshA third, optional numeric argument <code>init</code> specifies 8284*8e3e3a7aSWarner Loshwhere to start the search; 8285*8e3e3a7aSWarner Loshits default value is 1 and can be negative. 8286*8e3e3a7aSWarner LoshA value of <b>true</b> as a fourth, optional argument <code>plain</code> 8287*8e3e3a7aSWarner Loshturns off the pattern matching facilities, 8288*8e3e3a7aSWarner Loshso the function does a plain "find substring" operation, 8289*8e3e3a7aSWarner Loshwith no characters in <code>pattern</code> being considered magic. 8290*8e3e3a7aSWarner LoshNote that if <code>plain</code> is given, then <code>init</code> must be given as well. 8291*8e3e3a7aSWarner Losh 8292*8e3e3a7aSWarner Losh 8293*8e3e3a7aSWarner Losh<p> 8294*8e3e3a7aSWarner LoshIf the pattern has captures, 8295*8e3e3a7aSWarner Loshthen in a successful match 8296*8e3e3a7aSWarner Loshthe captured values are also returned, 8297*8e3e3a7aSWarner Loshafter the two indices. 8298*8e3e3a7aSWarner Losh 8299*8e3e3a7aSWarner Losh 8300*8e3e3a7aSWarner Losh 8301*8e3e3a7aSWarner Losh 8302*8e3e3a7aSWarner Losh<p> 8303*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> 8304*8e3e3a7aSWarner Losh 8305*8e3e3a7aSWarner Losh 8306*8e3e3a7aSWarner Losh<p> 8307*8e3e3a7aSWarner LoshReturns a formatted version of its variable number of arguments 8308*8e3e3a7aSWarner Loshfollowing the description given in its first argument (which must be a string). 8309*8e3e3a7aSWarner LoshThe format string follows the same rules as the ISO C function <code>sprintf</code>. 8310*8e3e3a7aSWarner LoshThe only differences are that the options/modifiers 8311*8e3e3a7aSWarner Losh<code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>, 8312*8e3e3a7aSWarner Loshand <code>p</code> are not supported 8313*8e3e3a7aSWarner Loshand that there is an extra option, <code>q</code>. 8314*8e3e3a7aSWarner Losh 8315*8e3e3a7aSWarner Losh 8316*8e3e3a7aSWarner Losh<p> 8317*8e3e3a7aSWarner LoshThe <code>q</code> option formats a string between double quotes, 8318*8e3e3a7aSWarner Loshusing escape sequences when necessary to ensure that 8319*8e3e3a7aSWarner Loshit can safely be read back by the Lua interpreter. 8320*8e3e3a7aSWarner LoshFor instance, the call 8321*8e3e3a7aSWarner Losh 8322*8e3e3a7aSWarner Losh<pre> 8323*8e3e3a7aSWarner Losh string.format('%q', 'a string with "quotes" and \n new line') 8324*8e3e3a7aSWarner Losh</pre><p> 8325*8e3e3a7aSWarner Loshmay produce the string: 8326*8e3e3a7aSWarner Losh 8327*8e3e3a7aSWarner Losh<pre> 8328*8e3e3a7aSWarner Losh "a string with \"quotes\" and \ 8329*8e3e3a7aSWarner Losh new line" 8330*8e3e3a7aSWarner Losh</pre> 8331*8e3e3a7aSWarner Losh 8332*8e3e3a7aSWarner Losh<p> 8333*8e3e3a7aSWarner LoshOptions 8334*8e3e3a7aSWarner Losh<code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>, 8335*8e3e3a7aSWarner Losh<code>G</code>, and <code>g</code> all expect a number as argument. 8336*8e3e3a7aSWarner LoshOptions <code>c</code>, <code>d</code>, 8337*8e3e3a7aSWarner Losh<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> 8338*8e3e3a7aSWarner Loshexpect an integer. 8339*8e3e3a7aSWarner LoshWhen Lua is compiled with a C89 compiler, 8340*8e3e3a7aSWarner Loshoptions <code>A</code> and <code>a</code> (hexadecimal floats) 8341*8e3e3a7aSWarner Loshdo not support any modifier (flags, width, length). 8342*8e3e3a7aSWarner Losh 8343*8e3e3a7aSWarner Losh 8344*8e3e3a7aSWarner Losh<p> 8345*8e3e3a7aSWarner LoshOption <code>s</code> expects a string; 8346*8e3e3a7aSWarner Loshif its argument is not a string, 8347*8e3e3a7aSWarner Loshit is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 8348*8e3e3a7aSWarner LoshIf the option has any modifier (flags, width, length), 8349*8e3e3a7aSWarner Loshthe string argument should not contain embedded zeros. 8350*8e3e3a7aSWarner Losh 8351*8e3e3a7aSWarner Losh 8352*8e3e3a7aSWarner Losh 8353*8e3e3a7aSWarner Losh 8354*8e3e3a7aSWarner Losh<p> 8355*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3> 8356*8e3e3a7aSWarner LoshReturns an iterator function that, 8357*8e3e3a7aSWarner Losheach time it is called, 8358*8e3e3a7aSWarner Loshreturns the next captures from <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) 8359*8e3e3a7aSWarner Loshover the string <code>s</code>. 8360*8e3e3a7aSWarner LoshIf <code>pattern</code> specifies no captures, 8361*8e3e3a7aSWarner Loshthen the whole match is produced in each call. 8362*8e3e3a7aSWarner Losh 8363*8e3e3a7aSWarner Losh 8364*8e3e3a7aSWarner Losh<p> 8365*8e3e3a7aSWarner LoshAs an example, the following loop 8366*8e3e3a7aSWarner Loshwill iterate over all the words from string <code>s</code>, 8367*8e3e3a7aSWarner Loshprinting one per line: 8368*8e3e3a7aSWarner Losh 8369*8e3e3a7aSWarner Losh<pre> 8370*8e3e3a7aSWarner Losh s = "hello world from Lua" 8371*8e3e3a7aSWarner Losh for w in string.gmatch(s, "%a+") do 8372*8e3e3a7aSWarner Losh print(w) 8373*8e3e3a7aSWarner Losh end 8374*8e3e3a7aSWarner Losh</pre><p> 8375*8e3e3a7aSWarner LoshThe next example collects all pairs <code>key=value</code> from the 8376*8e3e3a7aSWarner Loshgiven string into a table: 8377*8e3e3a7aSWarner Losh 8378*8e3e3a7aSWarner Losh<pre> 8379*8e3e3a7aSWarner Losh t = {} 8380*8e3e3a7aSWarner Losh s = "from=world, to=Lua" 8381*8e3e3a7aSWarner Losh for k, v in string.gmatch(s, "(%w+)=(%w+)") do 8382*8e3e3a7aSWarner Losh t[k] = v 8383*8e3e3a7aSWarner Losh end 8384*8e3e3a7aSWarner Losh</pre> 8385*8e3e3a7aSWarner Losh 8386*8e3e3a7aSWarner Losh<p> 8387*8e3e3a7aSWarner LoshFor this function, a caret '<code>^</code>' at the start of a pattern does not 8388*8e3e3a7aSWarner Loshwork as an anchor, as this would prevent the iteration. 8389*8e3e3a7aSWarner Losh 8390*8e3e3a7aSWarner Losh 8391*8e3e3a7aSWarner Losh 8392*8e3e3a7aSWarner Losh 8393*8e3e3a7aSWarner Losh<p> 8394*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> 8395*8e3e3a7aSWarner LoshReturns a copy of <code>s</code> 8396*8e3e3a7aSWarner Loshin which all (or the first <code>n</code>, if given) 8397*8e3e3a7aSWarner Loshoccurrences of the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) have been 8398*8e3e3a7aSWarner Loshreplaced by a replacement string specified by <code>repl</code>, 8399*8e3e3a7aSWarner Loshwhich can be a string, a table, or a function. 8400*8e3e3a7aSWarner Losh<code>gsub</code> also returns, as its second value, 8401*8e3e3a7aSWarner Loshthe total number of matches that occurred. 8402*8e3e3a7aSWarner LoshThe name <code>gsub</code> comes from <em>Global SUBstitution</em>. 8403*8e3e3a7aSWarner Losh 8404*8e3e3a7aSWarner Losh 8405*8e3e3a7aSWarner Losh<p> 8406*8e3e3a7aSWarner LoshIf <code>repl</code> is a string, then its value is used for replacement. 8407*8e3e3a7aSWarner LoshThe character <code>%</code> works as an escape character: 8408*8e3e3a7aSWarner Loshany sequence in <code>repl</code> of the form <code>%<em>d</em></code>, 8409*8e3e3a7aSWarner Loshwith <em>d</em> between 1 and 9, 8410*8e3e3a7aSWarner Loshstands for the value of the <em>d</em>-th captured substring. 8411*8e3e3a7aSWarner LoshThe sequence <code>%0</code> stands for the whole match. 8412*8e3e3a7aSWarner LoshThe sequence <code>%%</code> stands for a single <code>%</code>. 8413*8e3e3a7aSWarner Losh 8414*8e3e3a7aSWarner Losh 8415*8e3e3a7aSWarner Losh<p> 8416*8e3e3a7aSWarner LoshIf <code>repl</code> is a table, then the table is queried for every match, 8417*8e3e3a7aSWarner Loshusing the first capture as the key. 8418*8e3e3a7aSWarner Losh 8419*8e3e3a7aSWarner Losh 8420*8e3e3a7aSWarner Losh<p> 8421*8e3e3a7aSWarner LoshIf <code>repl</code> is a function, then this function is called every time a 8422*8e3e3a7aSWarner Loshmatch occurs, with all captured substrings passed as arguments, 8423*8e3e3a7aSWarner Loshin order. 8424*8e3e3a7aSWarner Losh 8425*8e3e3a7aSWarner Losh 8426*8e3e3a7aSWarner Losh<p> 8427*8e3e3a7aSWarner LoshIn any case, 8428*8e3e3a7aSWarner Loshif the pattern specifies no captures, 8429*8e3e3a7aSWarner Loshthen it behaves as if the whole pattern was inside a capture. 8430*8e3e3a7aSWarner Losh 8431*8e3e3a7aSWarner Losh 8432*8e3e3a7aSWarner Losh<p> 8433*8e3e3a7aSWarner LoshIf the value returned by the table query or by the function call 8434*8e3e3a7aSWarner Loshis a string or a number, 8435*8e3e3a7aSWarner Loshthen it is used as the replacement string; 8436*8e3e3a7aSWarner Loshotherwise, if it is <b>false</b> or <b>nil</b>, 8437*8e3e3a7aSWarner Loshthen there is no replacement 8438*8e3e3a7aSWarner Losh(that is, the original match is kept in the string). 8439*8e3e3a7aSWarner Losh 8440*8e3e3a7aSWarner Losh 8441*8e3e3a7aSWarner Losh<p> 8442*8e3e3a7aSWarner LoshHere are some examples: 8443*8e3e3a7aSWarner Losh 8444*8e3e3a7aSWarner Losh<pre> 8445*8e3e3a7aSWarner Losh x = string.gsub("hello world", "(%w+)", "%1 %1") 8446*8e3e3a7aSWarner Losh --> x="hello hello world world" 8447*8e3e3a7aSWarner Losh 8448*8e3e3a7aSWarner Losh x = string.gsub("hello world", "%w+", "%0 %0", 1) 8449*8e3e3a7aSWarner Losh --> x="hello hello world" 8450*8e3e3a7aSWarner Losh 8451*8e3e3a7aSWarner Losh x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 8452*8e3e3a7aSWarner Losh --> x="world hello Lua from" 8453*8e3e3a7aSWarner Losh 8454*8e3e3a7aSWarner Losh x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) 8455*8e3e3a7aSWarner Losh --> x="home = /home/roberto, user = roberto" 8456*8e3e3a7aSWarner Losh 8457*8e3e3a7aSWarner Losh x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 8458*8e3e3a7aSWarner Losh return load(s)() 8459*8e3e3a7aSWarner Losh end) 8460*8e3e3a7aSWarner Losh --> x="4+5 = 9" 8461*8e3e3a7aSWarner Losh 8462*8e3e3a7aSWarner Losh local t = {name="lua", version="5.3"} 8463*8e3e3a7aSWarner Losh x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 8464*8e3e3a7aSWarner Losh --> x="lua-5.3.tar.gz" 8465*8e3e3a7aSWarner Losh</pre> 8466*8e3e3a7aSWarner Losh 8467*8e3e3a7aSWarner Losh 8468*8e3e3a7aSWarner Losh 8469*8e3e3a7aSWarner Losh<p> 8470*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> 8471*8e3e3a7aSWarner LoshReceives a string and returns its length. 8472*8e3e3a7aSWarner LoshThe empty string <code>""</code> has length 0. 8473*8e3e3a7aSWarner LoshEmbedded zeros are counted, 8474*8e3e3a7aSWarner Loshso <code>"a\000bc\000"</code> has length 5. 8475*8e3e3a7aSWarner Losh 8476*8e3e3a7aSWarner Losh 8477*8e3e3a7aSWarner Losh 8478*8e3e3a7aSWarner Losh 8479*8e3e3a7aSWarner Losh<p> 8480*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> 8481*8e3e3a7aSWarner LoshReceives a string and returns a copy of this string with all 8482*8e3e3a7aSWarner Loshuppercase letters changed to lowercase. 8483*8e3e3a7aSWarner LoshAll other characters are left unchanged. 8484*8e3e3a7aSWarner LoshThe definition of what an uppercase letter is depends on the current locale. 8485*8e3e3a7aSWarner Losh 8486*8e3e3a7aSWarner Losh 8487*8e3e3a7aSWarner Losh 8488*8e3e3a7aSWarner Losh 8489*8e3e3a7aSWarner Losh<p> 8490*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> 8491*8e3e3a7aSWarner LoshLooks for the first <em>match</em> of 8492*8e3e3a7aSWarner Losh<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 8493*8e3e3a7aSWarner LoshIf it finds one, then <code>match</code> returns 8494*8e3e3a7aSWarner Loshthe captures from the pattern; 8495*8e3e3a7aSWarner Loshotherwise it returns <b>nil</b>. 8496*8e3e3a7aSWarner LoshIf <code>pattern</code> specifies no captures, 8497*8e3e3a7aSWarner Loshthen the whole match is returned. 8498*8e3e3a7aSWarner LoshA third, optional numeric argument <code>init</code> specifies 8499*8e3e3a7aSWarner Loshwhere to start the search; 8500*8e3e3a7aSWarner Loshits default value is 1 and can be negative. 8501*8e3e3a7aSWarner Losh 8502*8e3e3a7aSWarner Losh 8503*8e3e3a7aSWarner Losh 8504*8e3e3a7aSWarner Losh 8505*8e3e3a7aSWarner Losh<p> 8506*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, ···)</code></a></h3> 8507*8e3e3a7aSWarner Losh 8508*8e3e3a7aSWarner Losh 8509*8e3e3a7aSWarner Losh<p> 8510*8e3e3a7aSWarner LoshReturns a binary string containing the values <code>v1</code>, <code>v2</code>, etc. 8511*8e3e3a7aSWarner Loshpacked (that is, serialized in binary form) 8512*8e3e3a7aSWarner Loshaccording to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 8513*8e3e3a7aSWarner Losh 8514*8e3e3a7aSWarner Losh 8515*8e3e3a7aSWarner Losh 8516*8e3e3a7aSWarner Losh 8517*8e3e3a7aSWarner Losh<p> 8518*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3> 8519*8e3e3a7aSWarner Losh 8520*8e3e3a7aSWarner Losh 8521*8e3e3a7aSWarner Losh<p> 8522*8e3e3a7aSWarner LoshReturns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a> 8523*8e3e3a7aSWarner Loshwith the given format. 8524*8e3e3a7aSWarner LoshThe format string cannot have the variable-length options 8525*8e3e3a7aSWarner Losh'<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">§6.4.2</a>). 8526*8e3e3a7aSWarner Losh 8527*8e3e3a7aSWarner Losh 8528*8e3e3a7aSWarner Losh 8529*8e3e3a7aSWarner Losh 8530*8e3e3a7aSWarner Losh<p> 8531*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3> 8532*8e3e3a7aSWarner LoshReturns a string that is the concatenation of <code>n</code> copies of 8533*8e3e3a7aSWarner Loshthe string <code>s</code> separated by the string <code>sep</code>. 8534*8e3e3a7aSWarner LoshThe default value for <code>sep</code> is the empty string 8535*8e3e3a7aSWarner Losh(that is, no separator). 8536*8e3e3a7aSWarner LoshReturns the empty string if <code>n</code> is not positive. 8537*8e3e3a7aSWarner Losh 8538*8e3e3a7aSWarner Losh 8539*8e3e3a7aSWarner Losh<p> 8540*8e3e3a7aSWarner Losh(Note that it is very easy to exhaust the memory of your machine 8541*8e3e3a7aSWarner Loshwith a single call to this function.) 8542*8e3e3a7aSWarner Losh 8543*8e3e3a7aSWarner Losh 8544*8e3e3a7aSWarner Losh 8545*8e3e3a7aSWarner Losh 8546*8e3e3a7aSWarner Losh<p> 8547*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> 8548*8e3e3a7aSWarner LoshReturns a string that is the string <code>s</code> reversed. 8549*8e3e3a7aSWarner Losh 8550*8e3e3a7aSWarner Losh 8551*8e3e3a7aSWarner Losh 8552*8e3e3a7aSWarner Losh 8553*8e3e3a7aSWarner Losh<p> 8554*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> 8555*8e3e3a7aSWarner LoshReturns the substring of <code>s</code> that 8556*8e3e3a7aSWarner Loshstarts at <code>i</code> and continues until <code>j</code>; 8557*8e3e3a7aSWarner Losh<code>i</code> and <code>j</code> can be negative. 8558*8e3e3a7aSWarner LoshIf <code>j</code> is absent, then it is assumed to be equal to -1 8559*8e3e3a7aSWarner Losh(which is the same as the string length). 8560*8e3e3a7aSWarner LoshIn particular, 8561*8e3e3a7aSWarner Loshthe call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 8562*8e3e3a7aSWarner Loshwith length <code>j</code>, 8563*8e3e3a7aSWarner Loshand <code>string.sub(s, -i)</code> (for a positive <code>i</code>) 8564*8e3e3a7aSWarner Loshreturns a suffix of <code>s</code> 8565*8e3e3a7aSWarner Loshwith length <code>i</code>. 8566*8e3e3a7aSWarner Losh 8567*8e3e3a7aSWarner Losh 8568*8e3e3a7aSWarner Losh<p> 8569*8e3e3a7aSWarner LoshIf, after the translation of negative indices, 8570*8e3e3a7aSWarner Losh<code>i</code> is less than 1, 8571*8e3e3a7aSWarner Loshit is corrected to 1. 8572*8e3e3a7aSWarner LoshIf <code>j</code> is greater than the string length, 8573*8e3e3a7aSWarner Loshit is corrected to that length. 8574*8e3e3a7aSWarner LoshIf, after these corrections, 8575*8e3e3a7aSWarner Losh<code>i</code> is greater than <code>j</code>, 8576*8e3e3a7aSWarner Loshthe function returns the empty string. 8577*8e3e3a7aSWarner Losh 8578*8e3e3a7aSWarner Losh 8579*8e3e3a7aSWarner Losh 8580*8e3e3a7aSWarner Losh 8581*8e3e3a7aSWarner Losh<p> 8582*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3> 8583*8e3e3a7aSWarner Losh 8584*8e3e3a7aSWarner Losh 8585*8e3e3a7aSWarner Losh<p> 8586*8e3e3a7aSWarner LoshReturns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>) 8587*8e3e3a7aSWarner Loshaccording to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 8588*8e3e3a7aSWarner LoshAn optional <code>pos</code> marks where 8589*8e3e3a7aSWarner Loshto start reading in <code>s</code> (default is 1). 8590*8e3e3a7aSWarner LoshAfter the read values, 8591*8e3e3a7aSWarner Loshthis function also returns the index of the first unread byte in <code>s</code>. 8592*8e3e3a7aSWarner Losh 8593*8e3e3a7aSWarner Losh 8594*8e3e3a7aSWarner Losh 8595*8e3e3a7aSWarner Losh 8596*8e3e3a7aSWarner Losh<p> 8597*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> 8598*8e3e3a7aSWarner LoshReceives a string and returns a copy of this string with all 8599*8e3e3a7aSWarner Loshlowercase letters changed to uppercase. 8600*8e3e3a7aSWarner LoshAll other characters are left unchanged. 8601*8e3e3a7aSWarner LoshThe definition of what a lowercase letter is depends on the current locale. 8602*8e3e3a7aSWarner Losh 8603*8e3e3a7aSWarner Losh 8604*8e3e3a7aSWarner Losh 8605*8e3e3a7aSWarner Losh 8606*8e3e3a7aSWarner Losh 8607*8e3e3a7aSWarner Losh<h3>6.4.1 – <a name="6.4.1">Patterns</a></h3> 8608*8e3e3a7aSWarner Losh 8609*8e3e3a7aSWarner Losh<p> 8610*8e3e3a7aSWarner LoshPatterns in Lua are described by regular strings, 8611*8e3e3a7aSWarner Loshwhich are interpreted as patterns by the pattern-matching functions 8612*8e3e3a7aSWarner Losh<a href="#pdf-string.find"><code>string.find</code></a>, 8613*8e3e3a7aSWarner Losh<a href="#pdf-string.gmatch"><code>string.gmatch</code></a>, 8614*8e3e3a7aSWarner Losh<a href="#pdf-string.gsub"><code>string.gsub</code></a>, 8615*8e3e3a7aSWarner Loshand <a href="#pdf-string.match"><code>string.match</code></a>. 8616*8e3e3a7aSWarner LoshThis section describes the syntax and the meaning 8617*8e3e3a7aSWarner Losh(that is, what they match) of these strings. 8618*8e3e3a7aSWarner Losh 8619*8e3e3a7aSWarner Losh 8620*8e3e3a7aSWarner Losh 8621*8e3e3a7aSWarner Losh<h4>Character Class:</h4><p> 8622*8e3e3a7aSWarner LoshA <em>character class</em> is used to represent a set of characters. 8623*8e3e3a7aSWarner LoshThe following combinations are allowed in describing a character class: 8624*8e3e3a7aSWarner Losh 8625*8e3e3a7aSWarner Losh<ul> 8626*8e3e3a7aSWarner Losh 8627*8e3e3a7aSWarner Losh<li><b><em>x</em>: </b> 8628*8e3e3a7aSWarner Losh(where <em>x</em> is not one of the <em>magic characters</em> 8629*8e3e3a7aSWarner Losh<code>^$()%.[]*+-?</code>) 8630*8e3e3a7aSWarner Loshrepresents the character <em>x</em> itself. 8631*8e3e3a7aSWarner Losh</li> 8632*8e3e3a7aSWarner Losh 8633*8e3e3a7aSWarner Losh<li><b><code>.</code>: </b> (a dot) represents all characters.</li> 8634*8e3e3a7aSWarner Losh 8635*8e3e3a7aSWarner Losh<li><b><code>%a</code>: </b> represents all letters.</li> 8636*8e3e3a7aSWarner Losh 8637*8e3e3a7aSWarner Losh<li><b><code>%c</code>: </b> represents all control characters.</li> 8638*8e3e3a7aSWarner Losh 8639*8e3e3a7aSWarner Losh<li><b><code>%d</code>: </b> represents all digits.</li> 8640*8e3e3a7aSWarner Losh 8641*8e3e3a7aSWarner Losh<li><b><code>%g</code>: </b> represents all printable characters except space.</li> 8642*8e3e3a7aSWarner Losh 8643*8e3e3a7aSWarner Losh<li><b><code>%l</code>: </b> represents all lowercase letters.</li> 8644*8e3e3a7aSWarner Losh 8645*8e3e3a7aSWarner Losh<li><b><code>%p</code>: </b> represents all punctuation characters.</li> 8646*8e3e3a7aSWarner Losh 8647*8e3e3a7aSWarner Losh<li><b><code>%s</code>: </b> represents all space characters.</li> 8648*8e3e3a7aSWarner Losh 8649*8e3e3a7aSWarner Losh<li><b><code>%u</code>: </b> represents all uppercase letters.</li> 8650*8e3e3a7aSWarner Losh 8651*8e3e3a7aSWarner Losh<li><b><code>%w</code>: </b> represents all alphanumeric characters.</li> 8652*8e3e3a7aSWarner Losh 8653*8e3e3a7aSWarner Losh<li><b><code>%x</code>: </b> represents all hexadecimal digits.</li> 8654*8e3e3a7aSWarner Losh 8655*8e3e3a7aSWarner Losh<li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character) 8656*8e3e3a7aSWarner Loshrepresents the character <em>x</em>. 8657*8e3e3a7aSWarner LoshThis is the standard way to escape the magic characters. 8658*8e3e3a7aSWarner LoshAny non-alphanumeric character 8659*8e3e3a7aSWarner Losh(including all punctuation characters, even the non-magical) 8660*8e3e3a7aSWarner Loshcan be preceded by a '<code>%</code>' 8661*8e3e3a7aSWarner Loshwhen used to represent itself in a pattern. 8662*8e3e3a7aSWarner Losh</li> 8663*8e3e3a7aSWarner Losh 8664*8e3e3a7aSWarner Losh<li><b><code>[<em>set</em>]</code>: </b> 8665*8e3e3a7aSWarner Loshrepresents the class which is the union of all 8666*8e3e3a7aSWarner Loshcharacters in <em>set</em>. 8667*8e3e3a7aSWarner LoshA range of characters can be specified by 8668*8e3e3a7aSWarner Loshseparating the end characters of the range, 8669*8e3e3a7aSWarner Loshin ascending order, with a '<code>-</code>'. 8670*8e3e3a7aSWarner LoshAll classes <code>%</code><em>x</em> described above can also be used as 8671*8e3e3a7aSWarner Loshcomponents in <em>set</em>. 8672*8e3e3a7aSWarner LoshAll other characters in <em>set</em> represent themselves. 8673*8e3e3a7aSWarner LoshFor example, <code>[%w_]</code> (or <code>[_%w]</code>) 8674*8e3e3a7aSWarner Loshrepresents all alphanumeric characters plus the underscore, 8675*8e3e3a7aSWarner Losh<code>[0-7]</code> represents the octal digits, 8676*8e3e3a7aSWarner Loshand <code>[0-7%l%-]</code> represents the octal digits plus 8677*8e3e3a7aSWarner Loshthe lowercase letters plus the '<code>-</code>' character. 8678*8e3e3a7aSWarner Losh 8679*8e3e3a7aSWarner Losh 8680*8e3e3a7aSWarner Losh<p> 8681*8e3e3a7aSWarner LoshYou can put a closing square bracket in a set 8682*8e3e3a7aSWarner Loshby positioning it as the first character in the set. 8683*8e3e3a7aSWarner LoshYou can put an hyphen in a set 8684*8e3e3a7aSWarner Loshby positioning it as the first or the last character in the set. 8685*8e3e3a7aSWarner Losh(You can also use an escape for both cases.) 8686*8e3e3a7aSWarner Losh 8687*8e3e3a7aSWarner Losh 8688*8e3e3a7aSWarner Losh<p> 8689*8e3e3a7aSWarner LoshThe interaction between ranges and classes is not defined. 8690*8e3e3a7aSWarner LoshTherefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> 8691*8e3e3a7aSWarner Loshhave no meaning. 8692*8e3e3a7aSWarner Losh</li> 8693*8e3e3a7aSWarner Losh 8694*8e3e3a7aSWarner Losh<li><b><code>[^<em>set</em>]</code>: </b> 8695*8e3e3a7aSWarner Loshrepresents the complement of <em>set</em>, 8696*8e3e3a7aSWarner Loshwhere <em>set</em> is interpreted as above. 8697*8e3e3a7aSWarner Losh</li> 8698*8e3e3a7aSWarner Losh 8699*8e3e3a7aSWarner Losh</ul><p> 8700*8e3e3a7aSWarner LoshFor all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), 8701*8e3e3a7aSWarner Loshthe corresponding uppercase letter represents the complement of the class. 8702*8e3e3a7aSWarner LoshFor instance, <code>%S</code> represents all non-space characters. 8703*8e3e3a7aSWarner Losh 8704*8e3e3a7aSWarner Losh 8705*8e3e3a7aSWarner Losh<p> 8706*8e3e3a7aSWarner LoshThe definitions of letter, space, and other character groups 8707*8e3e3a7aSWarner Loshdepend on the current locale. 8708*8e3e3a7aSWarner LoshIn particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. 8709*8e3e3a7aSWarner Losh 8710*8e3e3a7aSWarner Losh 8711*8e3e3a7aSWarner Losh 8712*8e3e3a7aSWarner Losh 8713*8e3e3a7aSWarner Losh 8714*8e3e3a7aSWarner Losh<h4>Pattern Item:</h4><p> 8715*8e3e3a7aSWarner LoshA <em>pattern item</em> can be 8716*8e3e3a7aSWarner Losh 8717*8e3e3a7aSWarner Losh<ul> 8718*8e3e3a7aSWarner Losh 8719*8e3e3a7aSWarner Losh<li> 8720*8e3e3a7aSWarner Losha single character class, 8721*8e3e3a7aSWarner Loshwhich matches any single character in the class; 8722*8e3e3a7aSWarner Losh</li> 8723*8e3e3a7aSWarner Losh 8724*8e3e3a7aSWarner Losh<li> 8725*8e3e3a7aSWarner Losha single character class followed by '<code>*</code>', 8726*8e3e3a7aSWarner Loshwhich matches zero or more repetitions of characters in the class. 8727*8e3e3a7aSWarner LoshThese repetition items will always match the longest possible sequence; 8728*8e3e3a7aSWarner Losh</li> 8729*8e3e3a7aSWarner Losh 8730*8e3e3a7aSWarner Losh<li> 8731*8e3e3a7aSWarner Losha single character class followed by '<code>+</code>', 8732*8e3e3a7aSWarner Loshwhich matches one or more repetitions of characters in the class. 8733*8e3e3a7aSWarner LoshThese repetition items will always match the longest possible sequence; 8734*8e3e3a7aSWarner Losh</li> 8735*8e3e3a7aSWarner Losh 8736*8e3e3a7aSWarner Losh<li> 8737*8e3e3a7aSWarner Losha single character class followed by '<code>-</code>', 8738*8e3e3a7aSWarner Loshwhich also matches zero or more repetitions of characters in the class. 8739*8e3e3a7aSWarner LoshUnlike '<code>*</code>', 8740*8e3e3a7aSWarner Loshthese repetition items will always match the shortest possible sequence; 8741*8e3e3a7aSWarner Losh</li> 8742*8e3e3a7aSWarner Losh 8743*8e3e3a7aSWarner Losh<li> 8744*8e3e3a7aSWarner Losha single character class followed by '<code>?</code>', 8745*8e3e3a7aSWarner Loshwhich matches zero or one occurrence of a character in the class. 8746*8e3e3a7aSWarner LoshIt always matches one occurrence if possible; 8747*8e3e3a7aSWarner Losh</li> 8748*8e3e3a7aSWarner Losh 8749*8e3e3a7aSWarner Losh<li> 8750*8e3e3a7aSWarner Losh<code>%<em>n</em></code>, for <em>n</em> between 1 and 9; 8751*8e3e3a7aSWarner Loshsuch item matches a substring equal to the <em>n</em>-th captured string 8752*8e3e3a7aSWarner Losh(see below); 8753*8e3e3a7aSWarner Losh</li> 8754*8e3e3a7aSWarner Losh 8755*8e3e3a7aSWarner Losh<li> 8756*8e3e3a7aSWarner Losh<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; 8757*8e3e3a7aSWarner Loshsuch item matches strings that start with <em>x</em>, end with <em>y</em>, 8758*8e3e3a7aSWarner Loshand where the <em>x</em> and <em>y</em> are <em>balanced</em>. 8759*8e3e3a7aSWarner LoshThis means that, if one reads the string from left to right, 8760*8e3e3a7aSWarner Loshcounting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, 8761*8e3e3a7aSWarner Loshthe ending <em>y</em> is the first <em>y</em> where the count reaches 0. 8762*8e3e3a7aSWarner LoshFor instance, the item <code>%b()</code> matches expressions with 8763*8e3e3a7aSWarner Loshbalanced parentheses. 8764*8e3e3a7aSWarner Losh</li> 8765*8e3e3a7aSWarner Losh 8766*8e3e3a7aSWarner Losh<li> 8767*8e3e3a7aSWarner Losh<code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>; 8768*8e3e3a7aSWarner Loshsuch item matches an empty string at any position such that 8769*8e3e3a7aSWarner Loshthe next character belongs to <em>set</em> 8770*8e3e3a7aSWarner Loshand the previous character does not belong to <em>set</em>. 8771*8e3e3a7aSWarner LoshThe set <em>set</em> is interpreted as previously described. 8772*8e3e3a7aSWarner LoshThe beginning and the end of the subject are handled as if 8773*8e3e3a7aSWarner Loshthey were the character '<code>\0</code>'. 8774*8e3e3a7aSWarner Losh</li> 8775*8e3e3a7aSWarner Losh 8776*8e3e3a7aSWarner Losh</ul> 8777*8e3e3a7aSWarner Losh 8778*8e3e3a7aSWarner Losh 8779*8e3e3a7aSWarner Losh 8780*8e3e3a7aSWarner Losh 8781*8e3e3a7aSWarner Losh<h4>Pattern:</h4><p> 8782*8e3e3a7aSWarner LoshA <em>pattern</em> is a sequence of pattern items. 8783*8e3e3a7aSWarner LoshA caret '<code>^</code>' at the beginning of a pattern anchors the match at the 8784*8e3e3a7aSWarner Loshbeginning of the subject string. 8785*8e3e3a7aSWarner LoshA '<code>$</code>' at the end of a pattern anchors the match at the 8786*8e3e3a7aSWarner Loshend of the subject string. 8787*8e3e3a7aSWarner LoshAt other positions, 8788*8e3e3a7aSWarner Losh'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. 8789*8e3e3a7aSWarner Losh 8790*8e3e3a7aSWarner Losh 8791*8e3e3a7aSWarner Losh 8792*8e3e3a7aSWarner Losh 8793*8e3e3a7aSWarner Losh 8794*8e3e3a7aSWarner Losh<h4>Captures:</h4><p> 8795*8e3e3a7aSWarner LoshA pattern can contain sub-patterns enclosed in parentheses; 8796*8e3e3a7aSWarner Loshthey describe <em>captures</em>. 8797*8e3e3a7aSWarner LoshWhen a match succeeds, the substrings of the subject string 8798*8e3e3a7aSWarner Loshthat match captures are stored (<em>captured</em>) for future use. 8799*8e3e3a7aSWarner LoshCaptures are numbered according to their left parentheses. 8800*8e3e3a7aSWarner LoshFor instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, 8801*8e3e3a7aSWarner Loshthe part of the string matching <code>"a*(.)%w(%s*)"</code> is 8802*8e3e3a7aSWarner Loshstored as the first capture (and therefore has number 1); 8803*8e3e3a7aSWarner Loshthe character matching "<code>.</code>" is captured with number 2, 8804*8e3e3a7aSWarner Loshand the part matching "<code>%s*</code>" has number 3. 8805*8e3e3a7aSWarner Losh 8806*8e3e3a7aSWarner Losh 8807*8e3e3a7aSWarner Losh<p> 8808*8e3e3a7aSWarner LoshAs a special case, the empty capture <code>()</code> captures 8809*8e3e3a7aSWarner Loshthe current string position (a number). 8810*8e3e3a7aSWarner LoshFor instance, if we apply the pattern <code>"()aa()"</code> on the 8811*8e3e3a7aSWarner Loshstring <code>"flaaap"</code>, there will be two captures: 3 and 5. 8812*8e3e3a7aSWarner Losh 8813*8e3e3a7aSWarner Losh 8814*8e3e3a7aSWarner Losh 8815*8e3e3a7aSWarner Losh 8816*8e3e3a7aSWarner Losh 8817*8e3e3a7aSWarner Losh 8818*8e3e3a7aSWarner Losh 8819*8e3e3a7aSWarner Losh<h3>6.4.2 – <a name="6.4.2">Format Strings for Pack and Unpack</a></h3> 8820*8e3e3a7aSWarner Losh 8821*8e3e3a7aSWarner Losh<p> 8822*8e3e3a7aSWarner LoshThe first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>, 8823*8e3e3a7aSWarner Losh<a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a> 8824*8e3e3a7aSWarner Loshis a format string, 8825*8e3e3a7aSWarner Loshwhich describes the layout of the structure being created or read. 8826*8e3e3a7aSWarner Losh 8827*8e3e3a7aSWarner Losh 8828*8e3e3a7aSWarner Losh<p> 8829*8e3e3a7aSWarner LoshA format string is a sequence of conversion options. 8830*8e3e3a7aSWarner LoshThe conversion options are as follows: 8831*8e3e3a7aSWarner Losh 8832*8e3e3a7aSWarner Losh<ul> 8833*8e3e3a7aSWarner Losh<li><b><code><</code>: </b>sets little endian</li> 8834*8e3e3a7aSWarner Losh<li><b><code>></code>: </b>sets big endian</li> 8835*8e3e3a7aSWarner Losh<li><b><code>=</code>: </b>sets native endian</li> 8836*8e3e3a7aSWarner Losh<li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code> 8837*8e3e3a7aSWarner Losh(default is native alignment)</li> 8838*8e3e3a7aSWarner Losh<li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li> 8839*8e3e3a7aSWarner Losh<li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li> 8840*8e3e3a7aSWarner Losh<li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li> 8841*8e3e3a7aSWarner Losh<li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li> 8842*8e3e3a7aSWarner Losh<li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li> 8843*8e3e3a7aSWarner Losh<li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li> 8844*8e3e3a7aSWarner Losh<li><b><code>j</code>: </b>a <code>lua_Integer</code></li> 8845*8e3e3a7aSWarner Losh<li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li> 8846*8e3e3a7aSWarner Losh<li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li> 8847*8e3e3a7aSWarner Losh<li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes 8848*8e3e3a7aSWarner Losh(default is native size)</li> 8849*8e3e3a7aSWarner Losh<li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes 8850*8e3e3a7aSWarner Losh(default is native size)</li> 8851*8e3e3a7aSWarner Losh<li><b><code>f</code>: </b>a <code>float</code> (native size)</li> 8852*8e3e3a7aSWarner Losh<li><b><code>d</code>: </b>a <code>double</code> (native size)</li> 8853*8e3e3a7aSWarner Losh<li><b><code>n</code>: </b>a <code>lua_Number</code></li> 8854*8e3e3a7aSWarner Losh<li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li> 8855*8e3e3a7aSWarner Losh<li><b><code>z</code>: </b>a zero-terminated string</li> 8856*8e3e3a7aSWarner Losh<li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length 8857*8e3e3a7aSWarner Loshcoded as an unsigned integer with <code>n</code> bytes 8858*8e3e3a7aSWarner Losh(default is a <code>size_t</code>)</li> 8859*8e3e3a7aSWarner Losh<li><b><code>x</code>: </b>one byte of padding</li> 8860*8e3e3a7aSWarner Losh<li><b><code>X<em>op</em></code>: </b>an empty item that aligns 8861*8e3e3a7aSWarner Loshaccording to option <code>op</code> 8862*8e3e3a7aSWarner Losh(which is otherwise ignored)</li> 8863*8e3e3a7aSWarner Losh<li><b>'<code> </code>': </b>(empty space) ignored</li> 8864*8e3e3a7aSWarner Losh</ul><p> 8865*8e3e3a7aSWarner Losh(A "<code>[<em>n</em>]</code>" means an optional integral numeral.) 8866*8e3e3a7aSWarner LoshExcept for padding, spaces, and configurations 8867*8e3e3a7aSWarner Losh(options "<code>xX <=>!</code>"), 8868*8e3e3a7aSWarner Losheach option corresponds to an argument (in <a href="#pdf-string.pack"><code>string.pack</code></a>) 8869*8e3e3a7aSWarner Loshor a result (in <a href="#pdf-string.unpack"><code>string.unpack</code></a>). 8870*8e3e3a7aSWarner Losh 8871*8e3e3a7aSWarner Losh 8872*8e3e3a7aSWarner Losh<p> 8873*8e3e3a7aSWarner 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>", 8874*8e3e3a7aSWarner Losh<code>n</code> can be any integer between 1 and 16. 8875*8e3e3a7aSWarner LoshAll integral options check overflows; 8876*8e3e3a7aSWarner Losh<a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size; 8877*8e3e3a7aSWarner Losh<a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer. 8878*8e3e3a7aSWarner Losh 8879*8e3e3a7aSWarner Losh 8880*8e3e3a7aSWarner Losh<p> 8881*8e3e3a7aSWarner LoshAny format string starts as if prefixed by "<code>!1=</code>", 8882*8e3e3a7aSWarner Loshthat is, 8883*8e3e3a7aSWarner Loshwith maximum alignment of 1 (no alignment) 8884*8e3e3a7aSWarner Loshand native endianness. 8885*8e3e3a7aSWarner Losh 8886*8e3e3a7aSWarner Losh 8887*8e3e3a7aSWarner Losh<p> 8888*8e3e3a7aSWarner LoshAlignment works as follows: 8889*8e3e3a7aSWarner LoshFor each option, 8890*8e3e3a7aSWarner Loshthe format gets extra padding until the data starts 8891*8e3e3a7aSWarner Loshat an offset that is a multiple of the minimum between the 8892*8e3e3a7aSWarner Loshoption size and the maximum alignment; 8893*8e3e3a7aSWarner Loshthis minimum must be a power of 2. 8894*8e3e3a7aSWarner LoshOptions "<code>c</code>" and "<code>z</code>" are not aligned; 8895*8e3e3a7aSWarner Loshoption "<code>s</code>" follows the alignment of its starting integer. 8896*8e3e3a7aSWarner Losh 8897*8e3e3a7aSWarner Losh 8898*8e3e3a7aSWarner Losh<p> 8899*8e3e3a7aSWarner LoshAll padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a> 8900*8e3e3a7aSWarner Losh(and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>). 8901*8e3e3a7aSWarner Losh 8902*8e3e3a7aSWarner Losh 8903*8e3e3a7aSWarner Losh 8904*8e3e3a7aSWarner Losh 8905*8e3e3a7aSWarner Losh 8906*8e3e3a7aSWarner Losh 8907*8e3e3a7aSWarner Losh 8908*8e3e3a7aSWarner Losh<h2>6.5 – <a name="6.5">UTF-8 Support</a></h2> 8909*8e3e3a7aSWarner Losh 8910*8e3e3a7aSWarner Losh<p> 8911*8e3e3a7aSWarner LoshThis library provides basic support for UTF-8 encoding. 8912*8e3e3a7aSWarner LoshIt provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>. 8913*8e3e3a7aSWarner LoshThis library does not provide any support for Unicode other 8914*8e3e3a7aSWarner Loshthan the handling of the encoding. 8915*8e3e3a7aSWarner LoshAny operation that needs the meaning of a character, 8916*8e3e3a7aSWarner Loshsuch as character classification, is outside its scope. 8917*8e3e3a7aSWarner Losh 8918*8e3e3a7aSWarner Losh 8919*8e3e3a7aSWarner Losh<p> 8920*8e3e3a7aSWarner LoshUnless stated otherwise, 8921*8e3e3a7aSWarner Loshall functions that expect a byte position as a parameter 8922*8e3e3a7aSWarner Loshassume that the given position is either the start of a byte sequence 8923*8e3e3a7aSWarner Loshor one plus the length of the subject string. 8924*8e3e3a7aSWarner LoshAs in the string library, 8925*8e3e3a7aSWarner Loshnegative indices count from the end of the string. 8926*8e3e3a7aSWarner Losh 8927*8e3e3a7aSWarner Losh 8928*8e3e3a7aSWarner Losh<p> 8929*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3> 8930*8e3e3a7aSWarner LoshReceives zero or more integers, 8931*8e3e3a7aSWarner Loshconverts each one to its corresponding UTF-8 byte sequence 8932*8e3e3a7aSWarner Loshand returns a string with the concatenation of all these sequences. 8933*8e3e3a7aSWarner Losh 8934*8e3e3a7aSWarner Losh 8935*8e3e3a7aSWarner Losh 8936*8e3e3a7aSWarner Losh 8937*8e3e3a7aSWarner Losh<p> 8938*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3> 8939*8e3e3a7aSWarner LoshThe pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>" 8940*8e3e3a7aSWarner Losh(see <a href="#6.4.1">§6.4.1</a>), 8941*8e3e3a7aSWarner Loshwhich matches exactly one UTF-8 byte sequence, 8942*8e3e3a7aSWarner Loshassuming that the subject is a valid UTF-8 string. 8943*8e3e3a7aSWarner Losh 8944*8e3e3a7aSWarner Losh 8945*8e3e3a7aSWarner Losh 8946*8e3e3a7aSWarner Losh 8947*8e3e3a7aSWarner Losh<p> 8948*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3> 8949*8e3e3a7aSWarner Losh 8950*8e3e3a7aSWarner Losh 8951*8e3e3a7aSWarner Losh<p> 8952*8e3e3a7aSWarner LoshReturns values so that the construction 8953*8e3e3a7aSWarner Losh 8954*8e3e3a7aSWarner Losh<pre> 8955*8e3e3a7aSWarner Losh for p, c in utf8.codes(s) do <em>body</em> end 8956*8e3e3a7aSWarner Losh</pre><p> 8957*8e3e3a7aSWarner Loshwill iterate over all characters in string <code>s</code>, 8958*8e3e3a7aSWarner Loshwith <code>p</code> being the position (in bytes) and <code>c</code> the code point 8959*8e3e3a7aSWarner Loshof each character. 8960*8e3e3a7aSWarner LoshIt raises an error if it meets any invalid byte sequence. 8961*8e3e3a7aSWarner Losh 8962*8e3e3a7aSWarner Losh 8963*8e3e3a7aSWarner Losh 8964*8e3e3a7aSWarner Losh 8965*8e3e3a7aSWarner Losh<p> 8966*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3> 8967*8e3e3a7aSWarner LoshReturns the codepoints (as integers) from all characters in <code>s</code> 8968*8e3e3a7aSWarner Loshthat start between byte position <code>i</code> and <code>j</code> (both included). 8969*8e3e3a7aSWarner LoshThe default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>. 8970*8e3e3a7aSWarner LoshIt raises an error if it meets any invalid byte sequence. 8971*8e3e3a7aSWarner Losh 8972*8e3e3a7aSWarner Losh 8973*8e3e3a7aSWarner Losh 8974*8e3e3a7aSWarner Losh 8975*8e3e3a7aSWarner Losh<p> 8976*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j]])</code></a></h3> 8977*8e3e3a7aSWarner LoshReturns the number of UTF-8 characters in string <code>s</code> 8978*8e3e3a7aSWarner Loshthat start between positions <code>i</code> and <code>j</code> (both inclusive). 8979*8e3e3a7aSWarner LoshThe default for <code>i</code> is 1 and for <code>j</code> is -1. 8980*8e3e3a7aSWarner LoshIf it finds any invalid byte sequence, 8981*8e3e3a7aSWarner Loshreturns a false value plus the position of the first invalid byte. 8982*8e3e3a7aSWarner Losh 8983*8e3e3a7aSWarner Losh 8984*8e3e3a7aSWarner Losh 8985*8e3e3a7aSWarner Losh 8986*8e3e3a7aSWarner Losh<p> 8987*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3> 8988*8e3e3a7aSWarner LoshReturns the position (in bytes) where the encoding of the 8989*8e3e3a7aSWarner Losh<code>n</code>-th character of <code>s</code> 8990*8e3e3a7aSWarner Losh(counting from position <code>i</code>) starts. 8991*8e3e3a7aSWarner LoshA negative <code>n</code> gets characters before position <code>i</code>. 8992*8e3e3a7aSWarner LoshThe default for <code>i</code> is 1 when <code>n</code> is non-negative 8993*8e3e3a7aSWarner Loshand <code>#s + 1</code> otherwise, 8994*8e3e3a7aSWarner Loshso that <code>utf8.offset(s, -n)</code> gets the offset of the 8995*8e3e3a7aSWarner Losh<code>n</code>-th character from the end of the string. 8996*8e3e3a7aSWarner LoshIf the specified character is neither in the subject 8997*8e3e3a7aSWarner Loshnor right after its end, 8998*8e3e3a7aSWarner Loshthe function returns <b>nil</b>. 8999*8e3e3a7aSWarner Losh 9000*8e3e3a7aSWarner Losh 9001*8e3e3a7aSWarner Losh<p> 9002*8e3e3a7aSWarner LoshAs a special case, 9003*8e3e3a7aSWarner Loshwhen <code>n</code> is 0 the function returns the start of the encoding 9004*8e3e3a7aSWarner Loshof the character that contains the <code>i</code>-th byte of <code>s</code>. 9005*8e3e3a7aSWarner Losh 9006*8e3e3a7aSWarner Losh 9007*8e3e3a7aSWarner Losh<p> 9008*8e3e3a7aSWarner LoshThis function assumes that <code>s</code> is a valid UTF-8 string. 9009*8e3e3a7aSWarner Losh 9010*8e3e3a7aSWarner Losh 9011*8e3e3a7aSWarner Losh 9012*8e3e3a7aSWarner Losh 9013*8e3e3a7aSWarner Losh 9014*8e3e3a7aSWarner Losh 9015*8e3e3a7aSWarner Losh 9016*8e3e3a7aSWarner Losh<h2>6.6 – <a name="6.6">Table Manipulation</a></h2> 9017*8e3e3a7aSWarner Losh 9018*8e3e3a7aSWarner Losh<p> 9019*8e3e3a7aSWarner LoshThis library provides generic functions for table manipulation. 9020*8e3e3a7aSWarner LoshIt provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. 9021*8e3e3a7aSWarner Losh 9022*8e3e3a7aSWarner Losh 9023*8e3e3a7aSWarner Losh<p> 9024*8e3e3a7aSWarner LoshRemember that, whenever an operation needs the length of a table, 9025*8e3e3a7aSWarner Loshall caveats about the length operator apply (see <a href="#3.4.7">§3.4.7</a>). 9026*8e3e3a7aSWarner LoshAll functions ignore non-numeric keys 9027*8e3e3a7aSWarner Loshin the tables given as arguments. 9028*8e3e3a7aSWarner Losh 9029*8e3e3a7aSWarner Losh 9030*8e3e3a7aSWarner Losh<p> 9031*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3> 9032*8e3e3a7aSWarner Losh 9033*8e3e3a7aSWarner Losh 9034*8e3e3a7aSWarner Losh<p> 9035*8e3e3a7aSWarner LoshGiven a list where all elements are strings or numbers, 9036*8e3e3a7aSWarner Loshreturns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>. 9037*8e3e3a7aSWarner LoshThe default value for <code>sep</code> is the empty string, 9038*8e3e3a7aSWarner Loshthe default for <code>i</code> is 1, 9039*8e3e3a7aSWarner Loshand the default for <code>j</code> is <code>#list</code>. 9040*8e3e3a7aSWarner LoshIf <code>i</code> is greater than <code>j</code>, returns the empty string. 9041*8e3e3a7aSWarner Losh 9042*8e3e3a7aSWarner Losh 9043*8e3e3a7aSWarner Losh 9044*8e3e3a7aSWarner Losh 9045*8e3e3a7aSWarner Losh<p> 9046*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3> 9047*8e3e3a7aSWarner Losh 9048*8e3e3a7aSWarner Losh 9049*8e3e3a7aSWarner Losh<p> 9050*8e3e3a7aSWarner LoshInserts element <code>value</code> at position <code>pos</code> in <code>list</code>, 9051*8e3e3a7aSWarner Loshshifting up the elements 9052*8e3e3a7aSWarner Losh<code>list[pos], list[pos+1], ···, list[#list]</code>. 9053*8e3e3a7aSWarner LoshThe default value for <code>pos</code> is <code>#list+1</code>, 9054*8e3e3a7aSWarner Loshso that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end 9055*8e3e3a7aSWarner Loshof list <code>t</code>. 9056*8e3e3a7aSWarner Losh 9057*8e3e3a7aSWarner Losh 9058*8e3e3a7aSWarner Losh 9059*8e3e3a7aSWarner Losh 9060*8e3e3a7aSWarner Losh<p> 9061*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3> 9062*8e3e3a7aSWarner Losh 9063*8e3e3a7aSWarner Losh 9064*8e3e3a7aSWarner Losh<p> 9065*8e3e3a7aSWarner LoshMoves elements from table <code>a1</code> to table <code>a2</code>, 9066*8e3e3a7aSWarner Loshperforming the equivalent to the following 9067*8e3e3a7aSWarner Loshmultiple assignment: 9068*8e3e3a7aSWarner Losh<code>a2[t],··· = a1[f],···,a1[e]</code>. 9069*8e3e3a7aSWarner LoshThe default for <code>a2</code> is <code>a1</code>. 9070*8e3e3a7aSWarner LoshThe destination range can overlap with the source range. 9071*8e3e3a7aSWarner LoshThe number of elements to be moved must fit in a Lua integer. 9072*8e3e3a7aSWarner Losh 9073*8e3e3a7aSWarner Losh 9074*8e3e3a7aSWarner Losh<p> 9075*8e3e3a7aSWarner LoshReturns the destination table <code>a2</code>. 9076*8e3e3a7aSWarner Losh 9077*8e3e3a7aSWarner Losh 9078*8e3e3a7aSWarner Losh 9079*8e3e3a7aSWarner Losh 9080*8e3e3a7aSWarner Losh<p> 9081*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3> 9082*8e3e3a7aSWarner Losh 9083*8e3e3a7aSWarner Losh 9084*8e3e3a7aSWarner Losh<p> 9085*8e3e3a7aSWarner LoshReturns a new table with all parameters stored into keys 1, 2, etc. 9086*8e3e3a7aSWarner Loshand with a field "<code>n</code>" with the total number of parameters. 9087*8e3e3a7aSWarner LoshNote that the resulting table may not be a sequence. 9088*8e3e3a7aSWarner Losh 9089*8e3e3a7aSWarner Losh 9090*8e3e3a7aSWarner Losh 9091*8e3e3a7aSWarner Losh 9092*8e3e3a7aSWarner Losh<p> 9093*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3> 9094*8e3e3a7aSWarner Losh 9095*8e3e3a7aSWarner Losh 9096*8e3e3a7aSWarner Losh<p> 9097*8e3e3a7aSWarner LoshRemoves from <code>list</code> the element at position <code>pos</code>, 9098*8e3e3a7aSWarner Loshreturning the value of the removed element. 9099*8e3e3a7aSWarner LoshWhen <code>pos</code> is an integer between 1 and <code>#list</code>, 9100*8e3e3a7aSWarner Loshit shifts down the elements 9101*8e3e3a7aSWarner Losh<code>list[pos+1], list[pos+2], ···, list[#list]</code> 9102*8e3e3a7aSWarner Loshand erases element <code>list[#list]</code>; 9103*8e3e3a7aSWarner LoshThe index <code>pos</code> can also be 0 when <code>#list</code> is 0, 9104*8e3e3a7aSWarner Loshor <code>#list + 1</code>; 9105*8e3e3a7aSWarner Loshin those cases, the function erases the element <code>list[pos]</code>. 9106*8e3e3a7aSWarner Losh 9107*8e3e3a7aSWarner Losh 9108*8e3e3a7aSWarner Losh<p> 9109*8e3e3a7aSWarner LoshThe default value for <code>pos</code> is <code>#list</code>, 9110*8e3e3a7aSWarner Loshso that a call <code>table.remove(l)</code> removes the last element 9111*8e3e3a7aSWarner Loshof list <code>l</code>. 9112*8e3e3a7aSWarner Losh 9113*8e3e3a7aSWarner Losh 9114*8e3e3a7aSWarner Losh 9115*8e3e3a7aSWarner Losh 9116*8e3e3a7aSWarner Losh<p> 9117*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3> 9118*8e3e3a7aSWarner Losh 9119*8e3e3a7aSWarner Losh 9120*8e3e3a7aSWarner Losh<p> 9121*8e3e3a7aSWarner LoshSorts list elements in a given order, <em>in-place</em>, 9122*8e3e3a7aSWarner Loshfrom <code>list[1]</code> to <code>list[#list]</code>. 9123*8e3e3a7aSWarner LoshIf <code>comp</code> is given, 9124*8e3e3a7aSWarner Loshthen it must be a function that receives two list elements 9125*8e3e3a7aSWarner Loshand returns true when the first element must come 9126*8e3e3a7aSWarner Loshbefore the second in the final order 9127*8e3e3a7aSWarner Losh(so that, after the sort, 9128*8e3e3a7aSWarner Losh<code>i < j</code> implies <code>not comp(list[j],list[i])</code>). 9129*8e3e3a7aSWarner LoshIf <code>comp</code> is not given, 9130*8e3e3a7aSWarner Loshthen the standard Lua operator <code><</code> is used instead. 9131*8e3e3a7aSWarner Losh 9132*8e3e3a7aSWarner Losh 9133*8e3e3a7aSWarner Losh<p> 9134*8e3e3a7aSWarner LoshNote that the <code>comp</code> function must define 9135*8e3e3a7aSWarner Losha strict partial order over the elements in the list; 9136*8e3e3a7aSWarner Loshthat is, it must be asymmetric and transitive. 9137*8e3e3a7aSWarner LoshOtherwise, no valid sort may be possible. 9138*8e3e3a7aSWarner Losh 9139*8e3e3a7aSWarner Losh 9140*8e3e3a7aSWarner Losh<p> 9141*8e3e3a7aSWarner LoshThe sort algorithm is not stable: 9142*8e3e3a7aSWarner Loshelements considered equal by the given order 9143*8e3e3a7aSWarner Loshmay have their relative positions changed by the sort. 9144*8e3e3a7aSWarner Losh 9145*8e3e3a7aSWarner Losh 9146*8e3e3a7aSWarner Losh 9147*8e3e3a7aSWarner Losh 9148*8e3e3a7aSWarner Losh<p> 9149*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3> 9150*8e3e3a7aSWarner Losh 9151*8e3e3a7aSWarner Losh 9152*8e3e3a7aSWarner Losh<p> 9153*8e3e3a7aSWarner LoshReturns the elements from the given list. 9154*8e3e3a7aSWarner LoshThis function is equivalent to 9155*8e3e3a7aSWarner Losh 9156*8e3e3a7aSWarner Losh<pre> 9157*8e3e3a7aSWarner Losh return list[i], list[i+1], ···, list[j] 9158*8e3e3a7aSWarner Losh</pre><p> 9159*8e3e3a7aSWarner LoshBy default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>. 9160*8e3e3a7aSWarner Losh 9161*8e3e3a7aSWarner Losh 9162*8e3e3a7aSWarner Losh 9163*8e3e3a7aSWarner Losh 9164*8e3e3a7aSWarner Losh 9165*8e3e3a7aSWarner Losh 9166*8e3e3a7aSWarner Losh 9167*8e3e3a7aSWarner Losh<h2>6.7 – <a name="6.7">Mathematical Functions</a></h2> 9168*8e3e3a7aSWarner Losh 9169*8e3e3a7aSWarner Losh<p> 9170*8e3e3a7aSWarner LoshThis library provides basic mathematical functions. 9171*8e3e3a7aSWarner LoshIt provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>. 9172*8e3e3a7aSWarner LoshFunctions with the annotation "<code>integer/float</code>" give 9173*8e3e3a7aSWarner Loshinteger results for integer arguments 9174*8e3e3a7aSWarner Loshand float results for float (or mixed) arguments. 9175*8e3e3a7aSWarner LoshRounding functions 9176*8e3e3a7aSWarner 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>) 9177*8e3e3a7aSWarner Loshreturn an integer when the result fits in the range of an integer, 9178*8e3e3a7aSWarner Loshor a float otherwise. 9179*8e3e3a7aSWarner Losh 9180*8e3e3a7aSWarner Losh 9181*8e3e3a7aSWarner Losh<p> 9182*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> 9183*8e3e3a7aSWarner Losh 9184*8e3e3a7aSWarner Losh 9185*8e3e3a7aSWarner Losh<p> 9186*8e3e3a7aSWarner LoshReturns the absolute value of <code>x</code>. (integer/float) 9187*8e3e3a7aSWarner Losh 9188*8e3e3a7aSWarner Losh 9189*8e3e3a7aSWarner Losh 9190*8e3e3a7aSWarner Losh 9191*8e3e3a7aSWarner Losh<p> 9192*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> 9193*8e3e3a7aSWarner Losh 9194*8e3e3a7aSWarner Losh 9195*8e3e3a7aSWarner Losh<p> 9196*8e3e3a7aSWarner LoshReturns the arc cosine of <code>x</code> (in radians). 9197*8e3e3a7aSWarner Losh 9198*8e3e3a7aSWarner Losh 9199*8e3e3a7aSWarner Losh 9200*8e3e3a7aSWarner Losh 9201*8e3e3a7aSWarner Losh<p> 9202*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> 9203*8e3e3a7aSWarner Losh 9204*8e3e3a7aSWarner Losh 9205*8e3e3a7aSWarner Losh<p> 9206*8e3e3a7aSWarner LoshReturns the arc sine of <code>x</code> (in radians). 9207*8e3e3a7aSWarner Losh 9208*8e3e3a7aSWarner Losh 9209*8e3e3a7aSWarner Losh 9210*8e3e3a7aSWarner Losh 9211*8e3e3a7aSWarner Losh<p> 9212*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3> 9213*8e3e3a7aSWarner Losh 9214*8e3e3a7aSWarner Losh 9215*8e3e3a7aSWarner Losh<p> 9216*8e3e3a7aSWarner Losh 9217*8e3e3a7aSWarner LoshReturns the arc tangent of <code>y/x</code> (in radians), 9218*8e3e3a7aSWarner Loshbut uses the signs of both parameters to find the 9219*8e3e3a7aSWarner Loshquadrant of the result. 9220*8e3e3a7aSWarner Losh(It also handles correctly the case of <code>x</code> being zero.) 9221*8e3e3a7aSWarner Losh 9222*8e3e3a7aSWarner Losh 9223*8e3e3a7aSWarner Losh<p> 9224*8e3e3a7aSWarner LoshThe default value for <code>x</code> is 1, 9225*8e3e3a7aSWarner Loshso that the call <code>math.atan(y)</code> 9226*8e3e3a7aSWarner Loshreturns the arc tangent of <code>y</code>. 9227*8e3e3a7aSWarner Losh 9228*8e3e3a7aSWarner Losh 9229*8e3e3a7aSWarner Losh 9230*8e3e3a7aSWarner Losh 9231*8e3e3a7aSWarner Losh<p> 9232*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> 9233*8e3e3a7aSWarner Losh 9234*8e3e3a7aSWarner Losh 9235*8e3e3a7aSWarner Losh<p> 9236*8e3e3a7aSWarner LoshReturns the smallest integral value larger than or equal to <code>x</code>. 9237*8e3e3a7aSWarner Losh 9238*8e3e3a7aSWarner Losh 9239*8e3e3a7aSWarner Losh 9240*8e3e3a7aSWarner Losh 9241*8e3e3a7aSWarner Losh<p> 9242*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> 9243*8e3e3a7aSWarner Losh 9244*8e3e3a7aSWarner Losh 9245*8e3e3a7aSWarner Losh<p> 9246*8e3e3a7aSWarner LoshReturns the cosine of <code>x</code> (assumed to be in radians). 9247*8e3e3a7aSWarner Losh 9248*8e3e3a7aSWarner Losh 9249*8e3e3a7aSWarner Losh 9250*8e3e3a7aSWarner Losh 9251*8e3e3a7aSWarner Losh<p> 9252*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> 9253*8e3e3a7aSWarner Losh 9254*8e3e3a7aSWarner Losh 9255*8e3e3a7aSWarner Losh<p> 9256*8e3e3a7aSWarner LoshConverts the angle <code>x</code> from radians to degrees. 9257*8e3e3a7aSWarner Losh 9258*8e3e3a7aSWarner Losh 9259*8e3e3a7aSWarner Losh 9260*8e3e3a7aSWarner Losh 9261*8e3e3a7aSWarner Losh<p> 9262*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> 9263*8e3e3a7aSWarner Losh 9264*8e3e3a7aSWarner Losh 9265*8e3e3a7aSWarner Losh<p> 9266*8e3e3a7aSWarner LoshReturns the value <em>e<sup>x</sup></em> 9267*8e3e3a7aSWarner Losh(where <code>e</code> is the base of natural logarithms). 9268*8e3e3a7aSWarner Losh 9269*8e3e3a7aSWarner Losh 9270*8e3e3a7aSWarner Losh 9271*8e3e3a7aSWarner Losh 9272*8e3e3a7aSWarner Losh<p> 9273*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> 9274*8e3e3a7aSWarner Losh 9275*8e3e3a7aSWarner Losh 9276*8e3e3a7aSWarner Losh<p> 9277*8e3e3a7aSWarner LoshReturns the largest integral value smaller than or equal to <code>x</code>. 9278*8e3e3a7aSWarner Losh 9279*8e3e3a7aSWarner Losh 9280*8e3e3a7aSWarner Losh 9281*8e3e3a7aSWarner Losh 9282*8e3e3a7aSWarner Losh<p> 9283*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> 9284*8e3e3a7aSWarner Losh 9285*8e3e3a7aSWarner Losh 9286*8e3e3a7aSWarner Losh<p> 9287*8e3e3a7aSWarner LoshReturns the remainder of the division of <code>x</code> by <code>y</code> 9288*8e3e3a7aSWarner Loshthat rounds the quotient towards zero. (integer/float) 9289*8e3e3a7aSWarner Losh 9290*8e3e3a7aSWarner Losh 9291*8e3e3a7aSWarner Losh 9292*8e3e3a7aSWarner Losh 9293*8e3e3a7aSWarner Losh<p> 9294*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> 9295*8e3e3a7aSWarner Losh 9296*8e3e3a7aSWarner Losh 9297*8e3e3a7aSWarner Losh<p> 9298*8e3e3a7aSWarner LoshThe float value <code>HUGE_VAL</code>, 9299*8e3e3a7aSWarner Losha value larger than any other numeric value. 9300*8e3e3a7aSWarner Losh 9301*8e3e3a7aSWarner Losh 9302*8e3e3a7aSWarner Losh 9303*8e3e3a7aSWarner Losh 9304*8e3e3a7aSWarner Losh<p> 9305*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3> 9306*8e3e3a7aSWarner Losh 9307*8e3e3a7aSWarner Losh 9308*8e3e3a7aSWarner Losh<p> 9309*8e3e3a7aSWarner LoshReturns the logarithm of <code>x</code> in the given base. 9310*8e3e3a7aSWarner LoshThe default for <code>base</code> is <em>e</em> 9311*8e3e3a7aSWarner Losh(so that the function returns the natural logarithm of <code>x</code>). 9312*8e3e3a7aSWarner Losh 9313*8e3e3a7aSWarner Losh 9314*8e3e3a7aSWarner Losh 9315*8e3e3a7aSWarner Losh 9316*8e3e3a7aSWarner Losh<p> 9317*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> 9318*8e3e3a7aSWarner Losh 9319*8e3e3a7aSWarner Losh 9320*8e3e3a7aSWarner Losh<p> 9321*8e3e3a7aSWarner LoshReturns the argument with the maximum value, 9322*8e3e3a7aSWarner Loshaccording to the Lua operator <code><</code>. (integer/float) 9323*8e3e3a7aSWarner Losh 9324*8e3e3a7aSWarner Losh 9325*8e3e3a7aSWarner Losh 9326*8e3e3a7aSWarner Losh 9327*8e3e3a7aSWarner Losh<p> 9328*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3> 9329*8e3e3a7aSWarner LoshAn integer with the maximum value for an integer. 9330*8e3e3a7aSWarner Losh 9331*8e3e3a7aSWarner Losh 9332*8e3e3a7aSWarner Losh 9333*8e3e3a7aSWarner Losh 9334*8e3e3a7aSWarner Losh<p> 9335*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> 9336*8e3e3a7aSWarner Losh 9337*8e3e3a7aSWarner Losh 9338*8e3e3a7aSWarner Losh<p> 9339*8e3e3a7aSWarner LoshReturns the argument with the minimum value, 9340*8e3e3a7aSWarner Loshaccording to the Lua operator <code><</code>. (integer/float) 9341*8e3e3a7aSWarner Losh 9342*8e3e3a7aSWarner Losh 9343*8e3e3a7aSWarner Losh 9344*8e3e3a7aSWarner Losh 9345*8e3e3a7aSWarner Losh<p> 9346*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3> 9347*8e3e3a7aSWarner LoshAn integer with the minimum value for an integer. 9348*8e3e3a7aSWarner Losh 9349*8e3e3a7aSWarner Losh 9350*8e3e3a7aSWarner Losh 9351*8e3e3a7aSWarner Losh 9352*8e3e3a7aSWarner Losh<p> 9353*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> 9354*8e3e3a7aSWarner Losh 9355*8e3e3a7aSWarner Losh 9356*8e3e3a7aSWarner Losh<p> 9357*8e3e3a7aSWarner LoshReturns the integral part of <code>x</code> and the fractional part of <code>x</code>. 9358*8e3e3a7aSWarner LoshIts second result is always a float. 9359*8e3e3a7aSWarner Losh 9360*8e3e3a7aSWarner Losh 9361*8e3e3a7aSWarner Losh 9362*8e3e3a7aSWarner Losh 9363*8e3e3a7aSWarner Losh<p> 9364*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> 9365*8e3e3a7aSWarner Losh 9366*8e3e3a7aSWarner Losh 9367*8e3e3a7aSWarner Losh<p> 9368*8e3e3a7aSWarner LoshThe value of <em>π</em>. 9369*8e3e3a7aSWarner Losh 9370*8e3e3a7aSWarner Losh 9371*8e3e3a7aSWarner Losh 9372*8e3e3a7aSWarner Losh 9373*8e3e3a7aSWarner Losh<p> 9374*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> 9375*8e3e3a7aSWarner Losh 9376*8e3e3a7aSWarner Losh 9377*8e3e3a7aSWarner Losh<p> 9378*8e3e3a7aSWarner LoshConverts the angle <code>x</code> from degrees to radians. 9379*8e3e3a7aSWarner Losh 9380*8e3e3a7aSWarner Losh 9381*8e3e3a7aSWarner Losh 9382*8e3e3a7aSWarner Losh 9383*8e3e3a7aSWarner Losh<p> 9384*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> 9385*8e3e3a7aSWarner Losh 9386*8e3e3a7aSWarner Losh 9387*8e3e3a7aSWarner Losh<p> 9388*8e3e3a7aSWarner LoshWhen called without arguments, 9389*8e3e3a7aSWarner Loshreturns a pseudo-random float with uniform distribution 9390*8e3e3a7aSWarner Loshin the range <em>[0,1)</em>. 9391*8e3e3a7aSWarner LoshWhen called with two integers <code>m</code> and <code>n</code>, 9392*8e3e3a7aSWarner Losh<code>math.random</code> returns a pseudo-random integer 9393*8e3e3a7aSWarner Loshwith uniform distribution in the range <em>[m, n]</em>. 9394*8e3e3a7aSWarner Losh(The value <em>n-m</em> cannot be negative and must fit in a Lua integer.) 9395*8e3e3a7aSWarner LoshThe call <code>math.random(n)</code> is equivalent to <code>math.random(1,n)</code>. 9396*8e3e3a7aSWarner Losh 9397*8e3e3a7aSWarner Losh 9398*8e3e3a7aSWarner Losh<p> 9399*8e3e3a7aSWarner LoshThis function is an interface to the underling 9400*8e3e3a7aSWarner Loshpseudo-random generator function provided by C. 9401*8e3e3a7aSWarner Losh 9402*8e3e3a7aSWarner Losh 9403*8e3e3a7aSWarner Losh 9404*8e3e3a7aSWarner Losh 9405*8e3e3a7aSWarner Losh<p> 9406*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3> 9407*8e3e3a7aSWarner Losh 9408*8e3e3a7aSWarner Losh 9409*8e3e3a7aSWarner Losh<p> 9410*8e3e3a7aSWarner LoshSets <code>x</code> as the "seed" 9411*8e3e3a7aSWarner Loshfor the pseudo-random generator: 9412*8e3e3a7aSWarner Loshequal seeds produce equal sequences of numbers. 9413*8e3e3a7aSWarner Losh 9414*8e3e3a7aSWarner Losh 9415*8e3e3a7aSWarner Losh 9416*8e3e3a7aSWarner Losh 9417*8e3e3a7aSWarner Losh<p> 9418*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> 9419*8e3e3a7aSWarner Losh 9420*8e3e3a7aSWarner Losh 9421*8e3e3a7aSWarner Losh<p> 9422*8e3e3a7aSWarner LoshReturns the sine of <code>x</code> (assumed to be in radians). 9423*8e3e3a7aSWarner Losh 9424*8e3e3a7aSWarner Losh 9425*8e3e3a7aSWarner Losh 9426*8e3e3a7aSWarner Losh 9427*8e3e3a7aSWarner Losh<p> 9428*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> 9429*8e3e3a7aSWarner Losh 9430*8e3e3a7aSWarner Losh 9431*8e3e3a7aSWarner Losh<p> 9432*8e3e3a7aSWarner LoshReturns the square root of <code>x</code>. 9433*8e3e3a7aSWarner Losh(You can also use the expression <code>x^0.5</code> to compute this value.) 9434*8e3e3a7aSWarner Losh 9435*8e3e3a7aSWarner Losh 9436*8e3e3a7aSWarner Losh 9437*8e3e3a7aSWarner Losh 9438*8e3e3a7aSWarner Losh<p> 9439*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> 9440*8e3e3a7aSWarner Losh 9441*8e3e3a7aSWarner Losh 9442*8e3e3a7aSWarner Losh<p> 9443*8e3e3a7aSWarner LoshReturns the tangent of <code>x</code> (assumed to be in radians). 9444*8e3e3a7aSWarner Losh 9445*8e3e3a7aSWarner Losh 9446*8e3e3a7aSWarner Losh 9447*8e3e3a7aSWarner Losh 9448*8e3e3a7aSWarner Losh<p> 9449*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3> 9450*8e3e3a7aSWarner Losh 9451*8e3e3a7aSWarner Losh 9452*8e3e3a7aSWarner Losh<p> 9453*8e3e3a7aSWarner LoshIf the value <code>x</code> is convertible to an integer, 9454*8e3e3a7aSWarner Loshreturns that integer. 9455*8e3e3a7aSWarner LoshOtherwise, returns <b>nil</b>. 9456*8e3e3a7aSWarner Losh 9457*8e3e3a7aSWarner Losh 9458*8e3e3a7aSWarner Losh 9459*8e3e3a7aSWarner Losh 9460*8e3e3a7aSWarner Losh<p> 9461*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3> 9462*8e3e3a7aSWarner Losh 9463*8e3e3a7aSWarner Losh 9464*8e3e3a7aSWarner Losh<p> 9465*8e3e3a7aSWarner LoshReturns "<code>integer</code>" if <code>x</code> is an integer, 9466*8e3e3a7aSWarner Losh"<code>float</code>" if it is a float, 9467*8e3e3a7aSWarner Loshor <b>nil</b> if <code>x</code> is not a number. 9468*8e3e3a7aSWarner Losh 9469*8e3e3a7aSWarner Losh 9470*8e3e3a7aSWarner Losh 9471*8e3e3a7aSWarner Losh 9472*8e3e3a7aSWarner Losh<p> 9473*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3> 9474*8e3e3a7aSWarner Losh 9475*8e3e3a7aSWarner Losh 9476*8e3e3a7aSWarner Losh<p> 9477*8e3e3a7aSWarner LoshReturns a boolean, 9478*8e3e3a7aSWarner Loshtrue if and only if integer <code>m</code> is below integer <code>n</code> when 9479*8e3e3a7aSWarner Loshthey are compared as unsigned integers. 9480*8e3e3a7aSWarner Losh 9481*8e3e3a7aSWarner Losh 9482*8e3e3a7aSWarner Losh 9483*8e3e3a7aSWarner Losh 9484*8e3e3a7aSWarner Losh 9485*8e3e3a7aSWarner Losh 9486*8e3e3a7aSWarner Losh 9487*8e3e3a7aSWarner Losh<h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2> 9488*8e3e3a7aSWarner Losh 9489*8e3e3a7aSWarner Losh<p> 9490*8e3e3a7aSWarner LoshThe I/O library provides two different styles for file manipulation. 9491*8e3e3a7aSWarner LoshThe first one uses implicit file handles; 9492*8e3e3a7aSWarner Loshthat is, there are operations to set a default input file and a 9493*8e3e3a7aSWarner Loshdefault output file, 9494*8e3e3a7aSWarner Loshand all input/output operations are over these default files. 9495*8e3e3a7aSWarner LoshThe second style uses explicit file handles. 9496*8e3e3a7aSWarner Losh 9497*8e3e3a7aSWarner Losh 9498*8e3e3a7aSWarner Losh<p> 9499*8e3e3a7aSWarner LoshWhen using implicit file handles, 9500*8e3e3a7aSWarner Loshall operations are supplied by table <a name="pdf-io"><code>io</code></a>. 9501*8e3e3a7aSWarner LoshWhen using explicit file handles, 9502*8e3e3a7aSWarner Loshthe operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle 9503*8e3e3a7aSWarner Loshand then all operations are supplied as methods of the file handle. 9504*8e3e3a7aSWarner Losh 9505*8e3e3a7aSWarner Losh 9506*8e3e3a7aSWarner Losh<p> 9507*8e3e3a7aSWarner LoshThe table <code>io</code> also provides 9508*8e3e3a7aSWarner Loshthree predefined file handles with their usual meanings from C: 9509*8e3e3a7aSWarner 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>. 9510*8e3e3a7aSWarner LoshThe I/O library never closes these files. 9511*8e3e3a7aSWarner Losh 9512*8e3e3a7aSWarner Losh 9513*8e3e3a7aSWarner Losh<p> 9514*8e3e3a7aSWarner LoshUnless otherwise stated, 9515*8e3e3a7aSWarner Loshall I/O functions return <b>nil</b> on failure 9516*8e3e3a7aSWarner Losh(plus an error message as a second result and 9517*8e3e3a7aSWarner Losha system-dependent error code as a third result) 9518*8e3e3a7aSWarner Loshand some value different from <b>nil</b> on success. 9519*8e3e3a7aSWarner LoshOn non-POSIX systems, 9520*8e3e3a7aSWarner Loshthe computation of the error message and error code 9521*8e3e3a7aSWarner Loshin case of errors 9522*8e3e3a7aSWarner Loshmay be not thread safe, 9523*8e3e3a7aSWarner Loshbecause they rely on the global C variable <code>errno</code>. 9524*8e3e3a7aSWarner Losh 9525*8e3e3a7aSWarner Losh 9526*8e3e3a7aSWarner Losh<p> 9527*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> 9528*8e3e3a7aSWarner Losh 9529*8e3e3a7aSWarner Losh 9530*8e3e3a7aSWarner Losh<p> 9531*8e3e3a7aSWarner LoshEquivalent to <code>file:close()</code>. 9532*8e3e3a7aSWarner LoshWithout a <code>file</code>, closes the default output file. 9533*8e3e3a7aSWarner Losh 9534*8e3e3a7aSWarner Losh 9535*8e3e3a7aSWarner Losh 9536*8e3e3a7aSWarner Losh 9537*8e3e3a7aSWarner Losh<p> 9538*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> 9539*8e3e3a7aSWarner Losh 9540*8e3e3a7aSWarner Losh 9541*8e3e3a7aSWarner Losh<p> 9542*8e3e3a7aSWarner LoshEquivalent to <code>io.output():flush()</code>. 9543*8e3e3a7aSWarner Losh 9544*8e3e3a7aSWarner Losh 9545*8e3e3a7aSWarner Losh 9546*8e3e3a7aSWarner Losh 9547*8e3e3a7aSWarner Losh<p> 9548*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> 9549*8e3e3a7aSWarner Losh 9550*8e3e3a7aSWarner Losh 9551*8e3e3a7aSWarner Losh<p> 9552*8e3e3a7aSWarner LoshWhen called with a file name, it opens the named file (in text mode), 9553*8e3e3a7aSWarner Loshand sets its handle as the default input file. 9554*8e3e3a7aSWarner LoshWhen called with a file handle, 9555*8e3e3a7aSWarner Loshit simply sets this file handle as the default input file. 9556*8e3e3a7aSWarner LoshWhen called without parameters, 9557*8e3e3a7aSWarner Loshit returns the current default input file. 9558*8e3e3a7aSWarner Losh 9559*8e3e3a7aSWarner Losh 9560*8e3e3a7aSWarner Losh<p> 9561*8e3e3a7aSWarner LoshIn case of errors this function raises the error, 9562*8e3e3a7aSWarner Loshinstead of returning an error code. 9563*8e3e3a7aSWarner Losh 9564*8e3e3a7aSWarner Losh 9565*8e3e3a7aSWarner Losh 9566*8e3e3a7aSWarner Losh 9567*8e3e3a7aSWarner Losh<p> 9568*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, ···])</code></a></h3> 9569*8e3e3a7aSWarner Losh 9570*8e3e3a7aSWarner Losh 9571*8e3e3a7aSWarner Losh<p> 9572*8e3e3a7aSWarner LoshOpens the given file name in read mode 9573*8e3e3a7aSWarner Loshand returns an iterator function that 9574*8e3e3a7aSWarner Loshworks like <code>file:lines(···)</code> over the opened file. 9575*8e3e3a7aSWarner LoshWhen the iterator function detects the end of file, 9576*8e3e3a7aSWarner Loshit returns no values (to finish the loop) and automatically closes the file. 9577*8e3e3a7aSWarner Losh 9578*8e3e3a7aSWarner Losh 9579*8e3e3a7aSWarner Losh<p> 9580*8e3e3a7aSWarner LoshThe call <code>io.lines()</code> (with no file name) is equivalent 9581*8e3e3a7aSWarner Loshto <code>io.input():lines("*l")</code>; 9582*8e3e3a7aSWarner Loshthat is, it iterates over the lines of the default input file. 9583*8e3e3a7aSWarner LoshIn this case it does not close the file when the loop ends. 9584*8e3e3a7aSWarner Losh 9585*8e3e3a7aSWarner Losh 9586*8e3e3a7aSWarner Losh<p> 9587*8e3e3a7aSWarner LoshIn case of errors this function raises the error, 9588*8e3e3a7aSWarner Loshinstead of returning an error code. 9589*8e3e3a7aSWarner Losh 9590*8e3e3a7aSWarner Losh 9591*8e3e3a7aSWarner Losh 9592*8e3e3a7aSWarner Losh 9593*8e3e3a7aSWarner Losh<p> 9594*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> 9595*8e3e3a7aSWarner Losh 9596*8e3e3a7aSWarner Losh 9597*8e3e3a7aSWarner Losh<p> 9598*8e3e3a7aSWarner LoshThis function opens a file, 9599*8e3e3a7aSWarner Loshin the mode specified in the string <code>mode</code>. 9600*8e3e3a7aSWarner LoshIn case of success, 9601*8e3e3a7aSWarner Loshit returns a new file handle. 9602*8e3e3a7aSWarner Losh 9603*8e3e3a7aSWarner Losh 9604*8e3e3a7aSWarner Losh<p> 9605*8e3e3a7aSWarner LoshThe <code>mode</code> string can be any of the following: 9606*8e3e3a7aSWarner Losh 9607*8e3e3a7aSWarner Losh<ul> 9608*8e3e3a7aSWarner Losh<li><b>"<code>r</code>": </b> read mode (the default);</li> 9609*8e3e3a7aSWarner Losh<li><b>"<code>w</code>": </b> write mode;</li> 9610*8e3e3a7aSWarner Losh<li><b>"<code>a</code>": </b> append mode;</li> 9611*8e3e3a7aSWarner Losh<li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li> 9612*8e3e3a7aSWarner Losh<li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li> 9613*8e3e3a7aSWarner Losh<li><b>"<code>a+</code>": </b> append update mode, previous data is preserved, 9614*8e3e3a7aSWarner Losh writing is only allowed at the end of file.</li> 9615*8e3e3a7aSWarner Losh</ul><p> 9616*8e3e3a7aSWarner LoshThe <code>mode</code> string can also have a '<code>b</code>' at the end, 9617*8e3e3a7aSWarner Loshwhich is needed in some systems to open the file in binary mode. 9618*8e3e3a7aSWarner Losh 9619*8e3e3a7aSWarner Losh 9620*8e3e3a7aSWarner Losh 9621*8e3e3a7aSWarner Losh 9622*8e3e3a7aSWarner Losh<p> 9623*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> 9624*8e3e3a7aSWarner Losh 9625*8e3e3a7aSWarner Losh 9626*8e3e3a7aSWarner Losh<p> 9627*8e3e3a7aSWarner LoshSimilar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. 9628*8e3e3a7aSWarner Losh 9629*8e3e3a7aSWarner Losh 9630*8e3e3a7aSWarner Losh 9631*8e3e3a7aSWarner Losh 9632*8e3e3a7aSWarner Losh<p> 9633*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> 9634*8e3e3a7aSWarner Losh 9635*8e3e3a7aSWarner Losh 9636*8e3e3a7aSWarner Losh<p> 9637*8e3e3a7aSWarner LoshThis function is system dependent and is not available 9638*8e3e3a7aSWarner Loshon all platforms. 9639*8e3e3a7aSWarner Losh 9640*8e3e3a7aSWarner Losh 9641*8e3e3a7aSWarner Losh<p> 9642*8e3e3a7aSWarner LoshStarts program <code>prog</code> in a separated process and returns 9643*8e3e3a7aSWarner Losha file handle that you can use to read data from this program 9644*8e3e3a7aSWarner Losh(if <code>mode</code> is <code>"r"</code>, the default) 9645*8e3e3a7aSWarner Loshor to write data to this program 9646*8e3e3a7aSWarner Losh(if <code>mode</code> is <code>"w"</code>). 9647*8e3e3a7aSWarner Losh 9648*8e3e3a7aSWarner Losh 9649*8e3e3a7aSWarner Losh 9650*8e3e3a7aSWarner Losh 9651*8e3e3a7aSWarner Losh<p> 9652*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> 9653*8e3e3a7aSWarner Losh 9654*8e3e3a7aSWarner Losh 9655*8e3e3a7aSWarner Losh<p> 9656*8e3e3a7aSWarner LoshEquivalent to <code>io.input():read(···)</code>. 9657*8e3e3a7aSWarner Losh 9658*8e3e3a7aSWarner Losh 9659*8e3e3a7aSWarner Losh 9660*8e3e3a7aSWarner Losh 9661*8e3e3a7aSWarner Losh<p> 9662*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> 9663*8e3e3a7aSWarner Losh 9664*8e3e3a7aSWarner Losh 9665*8e3e3a7aSWarner Losh<p> 9666*8e3e3a7aSWarner LoshIn case of success, 9667*8e3e3a7aSWarner Loshreturns a handle for a temporary file. 9668*8e3e3a7aSWarner LoshThis file is opened in update mode 9669*8e3e3a7aSWarner Loshand it is automatically removed when the program ends. 9670*8e3e3a7aSWarner Losh 9671*8e3e3a7aSWarner Losh 9672*8e3e3a7aSWarner Losh 9673*8e3e3a7aSWarner Losh 9674*8e3e3a7aSWarner Losh<p> 9675*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> 9676*8e3e3a7aSWarner Losh 9677*8e3e3a7aSWarner Losh 9678*8e3e3a7aSWarner Losh<p> 9679*8e3e3a7aSWarner LoshChecks whether <code>obj</code> is a valid file handle. 9680*8e3e3a7aSWarner LoshReturns the string <code>"file"</code> if <code>obj</code> is an open file handle, 9681*8e3e3a7aSWarner Losh<code>"closed file"</code> if <code>obj</code> is a closed file handle, 9682*8e3e3a7aSWarner Loshor <b>nil</b> if <code>obj</code> is not a file handle. 9683*8e3e3a7aSWarner Losh 9684*8e3e3a7aSWarner Losh 9685*8e3e3a7aSWarner Losh 9686*8e3e3a7aSWarner Losh 9687*8e3e3a7aSWarner Losh<p> 9688*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> 9689*8e3e3a7aSWarner Losh 9690*8e3e3a7aSWarner Losh 9691*8e3e3a7aSWarner Losh<p> 9692*8e3e3a7aSWarner LoshEquivalent to <code>io.output():write(···)</code>. 9693*8e3e3a7aSWarner Losh 9694*8e3e3a7aSWarner Losh 9695*8e3e3a7aSWarner Losh 9696*8e3e3a7aSWarner Losh 9697*8e3e3a7aSWarner Losh<p> 9698*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> 9699*8e3e3a7aSWarner Losh 9700*8e3e3a7aSWarner Losh 9701*8e3e3a7aSWarner Losh<p> 9702*8e3e3a7aSWarner LoshCloses <code>file</code>. 9703*8e3e3a7aSWarner LoshNote that files are automatically closed when 9704*8e3e3a7aSWarner Loshtheir handles are garbage collected, 9705*8e3e3a7aSWarner Loshbut that takes an unpredictable amount of time to happen. 9706*8e3e3a7aSWarner Losh 9707*8e3e3a7aSWarner Losh 9708*8e3e3a7aSWarner Losh<p> 9709*8e3e3a7aSWarner LoshWhen closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>, 9710*8e3e3a7aSWarner Losh<a href="#pdf-file:close"><code>file:close</code></a> returns the same values 9711*8e3e3a7aSWarner Loshreturned by <a href="#pdf-os.execute"><code>os.execute</code></a>. 9712*8e3e3a7aSWarner Losh 9713*8e3e3a7aSWarner Losh 9714*8e3e3a7aSWarner Losh 9715*8e3e3a7aSWarner Losh 9716*8e3e3a7aSWarner Losh<p> 9717*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> 9718*8e3e3a7aSWarner Losh 9719*8e3e3a7aSWarner Losh 9720*8e3e3a7aSWarner Losh<p> 9721*8e3e3a7aSWarner LoshSaves any written data to <code>file</code>. 9722*8e3e3a7aSWarner Losh 9723*8e3e3a7aSWarner Losh 9724*8e3e3a7aSWarner Losh 9725*8e3e3a7aSWarner Losh 9726*8e3e3a7aSWarner Losh<p> 9727*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3> 9728*8e3e3a7aSWarner Losh 9729*8e3e3a7aSWarner Losh 9730*8e3e3a7aSWarner Losh<p> 9731*8e3e3a7aSWarner LoshReturns an iterator function that, 9732*8e3e3a7aSWarner Losheach time it is called, 9733*8e3e3a7aSWarner Loshreads the file according to the given formats. 9734*8e3e3a7aSWarner LoshWhen no format is given, 9735*8e3e3a7aSWarner Loshuses "<code>l</code>" as a default. 9736*8e3e3a7aSWarner LoshAs an example, the construction 9737*8e3e3a7aSWarner Losh 9738*8e3e3a7aSWarner Losh<pre> 9739*8e3e3a7aSWarner Losh for c in file:lines(1) do <em>body</em> end 9740*8e3e3a7aSWarner Losh</pre><p> 9741*8e3e3a7aSWarner Loshwill iterate over all characters of the file, 9742*8e3e3a7aSWarner Loshstarting at the current position. 9743*8e3e3a7aSWarner LoshUnlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file 9744*8e3e3a7aSWarner Loshwhen the loop ends. 9745*8e3e3a7aSWarner Losh 9746*8e3e3a7aSWarner Losh 9747*8e3e3a7aSWarner Losh<p> 9748*8e3e3a7aSWarner LoshIn case of errors this function raises the error, 9749*8e3e3a7aSWarner Loshinstead of returning an error code. 9750*8e3e3a7aSWarner Losh 9751*8e3e3a7aSWarner Losh 9752*8e3e3a7aSWarner Losh 9753*8e3e3a7aSWarner Losh 9754*8e3e3a7aSWarner Losh<p> 9755*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> 9756*8e3e3a7aSWarner Losh 9757*8e3e3a7aSWarner Losh 9758*8e3e3a7aSWarner Losh<p> 9759*8e3e3a7aSWarner LoshReads the file <code>file</code>, 9760*8e3e3a7aSWarner Loshaccording to the given formats, which specify what to read. 9761*8e3e3a7aSWarner LoshFor each format, 9762*8e3e3a7aSWarner Loshthe function returns a string or a number with the characters read, 9763*8e3e3a7aSWarner Loshor <b>nil</b> if it cannot read data with the specified format. 9764*8e3e3a7aSWarner Losh(In this latter case, 9765*8e3e3a7aSWarner Loshthe function does not read subsequent formats.) 9766*8e3e3a7aSWarner LoshWhen called without formats, 9767*8e3e3a7aSWarner Loshit uses a default format that reads the next line 9768*8e3e3a7aSWarner Losh(see below). 9769*8e3e3a7aSWarner Losh 9770*8e3e3a7aSWarner Losh 9771*8e3e3a7aSWarner Losh<p> 9772*8e3e3a7aSWarner LoshThe available formats are 9773*8e3e3a7aSWarner Losh 9774*8e3e3a7aSWarner Losh<ul> 9775*8e3e3a7aSWarner Losh 9776*8e3e3a7aSWarner Losh<li><b>"<code>n</code>": </b> 9777*8e3e3a7aSWarner Loshreads a numeral and returns it as a float or an integer, 9778*8e3e3a7aSWarner Loshfollowing the lexical conventions of Lua. 9779*8e3e3a7aSWarner Losh(The numeral may have leading spaces and a sign.) 9780*8e3e3a7aSWarner LoshThis format always reads the longest input sequence that 9781*8e3e3a7aSWarner Loshis a valid prefix for a numeral; 9782*8e3e3a7aSWarner Loshif that prefix does not form a valid numeral 9783*8e3e3a7aSWarner Losh(e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"), 9784*8e3e3a7aSWarner Loshit is discarded and the function returns <b>nil</b>. 9785*8e3e3a7aSWarner Losh</li> 9786*8e3e3a7aSWarner Losh 9787*8e3e3a7aSWarner Losh<li><b>"<code>a</code>": </b> 9788*8e3e3a7aSWarner Loshreads the whole file, starting at the current position. 9789*8e3e3a7aSWarner LoshOn end of file, it returns the empty string. 9790*8e3e3a7aSWarner Losh</li> 9791*8e3e3a7aSWarner Losh 9792*8e3e3a7aSWarner Losh<li><b>"<code>l</code>": </b> 9793*8e3e3a7aSWarner Loshreads the next line skipping the end of line, 9794*8e3e3a7aSWarner Loshreturning <b>nil</b> on end of file. 9795*8e3e3a7aSWarner LoshThis is the default format. 9796*8e3e3a7aSWarner Losh</li> 9797*8e3e3a7aSWarner Losh 9798*8e3e3a7aSWarner Losh<li><b>"<code>L</code>": </b> 9799*8e3e3a7aSWarner Loshreads the next line keeping the end-of-line character (if present), 9800*8e3e3a7aSWarner Loshreturning <b>nil</b> on end of file. 9801*8e3e3a7aSWarner Losh</li> 9802*8e3e3a7aSWarner Losh 9803*8e3e3a7aSWarner Losh<li><b><em>number</em>: </b> 9804*8e3e3a7aSWarner Loshreads a string with up to this number of bytes, 9805*8e3e3a7aSWarner Loshreturning <b>nil</b> on end of file. 9806*8e3e3a7aSWarner LoshIf <code>number</code> is zero, 9807*8e3e3a7aSWarner Loshit reads nothing and returns an empty string, 9808*8e3e3a7aSWarner Loshor <b>nil</b> on end of file. 9809*8e3e3a7aSWarner Losh</li> 9810*8e3e3a7aSWarner Losh 9811*8e3e3a7aSWarner Losh</ul><p> 9812*8e3e3a7aSWarner LoshThe formats "<code>l</code>" and "<code>L</code>" should be used only for text files. 9813*8e3e3a7aSWarner Losh 9814*8e3e3a7aSWarner Losh 9815*8e3e3a7aSWarner Losh 9816*8e3e3a7aSWarner Losh 9817*8e3e3a7aSWarner Losh<p> 9818*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3> 9819*8e3e3a7aSWarner Losh 9820*8e3e3a7aSWarner Losh 9821*8e3e3a7aSWarner Losh<p> 9822*8e3e3a7aSWarner LoshSets and gets the file position, 9823*8e3e3a7aSWarner Loshmeasured from the beginning of the file, 9824*8e3e3a7aSWarner Loshto the position given by <code>offset</code> plus a base 9825*8e3e3a7aSWarner Loshspecified by the string <code>whence</code>, as follows: 9826*8e3e3a7aSWarner Losh 9827*8e3e3a7aSWarner Losh<ul> 9828*8e3e3a7aSWarner Losh<li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li> 9829*8e3e3a7aSWarner Losh<li><b>"<code>cur</code>": </b> base is current position;</li> 9830*8e3e3a7aSWarner Losh<li><b>"<code>end</code>": </b> base is end of file;</li> 9831*8e3e3a7aSWarner Losh</ul><p> 9832*8e3e3a7aSWarner LoshIn case of success, <code>seek</code> returns the final file position, 9833*8e3e3a7aSWarner Loshmeasured in bytes from the beginning of the file. 9834*8e3e3a7aSWarner LoshIf <code>seek</code> fails, it returns <b>nil</b>, 9835*8e3e3a7aSWarner Loshplus a string describing the error. 9836*8e3e3a7aSWarner Losh 9837*8e3e3a7aSWarner Losh 9838*8e3e3a7aSWarner Losh<p> 9839*8e3e3a7aSWarner LoshThe default value for <code>whence</code> is <code>"cur"</code>, 9840*8e3e3a7aSWarner Loshand for <code>offset</code> is 0. 9841*8e3e3a7aSWarner LoshTherefore, the call <code>file:seek()</code> returns the current 9842*8e3e3a7aSWarner Loshfile position, without changing it; 9843*8e3e3a7aSWarner Loshthe call <code>file:seek("set")</code> sets the position to the 9844*8e3e3a7aSWarner Loshbeginning of the file (and returns 0); 9845*8e3e3a7aSWarner Loshand the call <code>file:seek("end")</code> sets the position to the 9846*8e3e3a7aSWarner Loshend of the file, and returns its size. 9847*8e3e3a7aSWarner Losh 9848*8e3e3a7aSWarner Losh 9849*8e3e3a7aSWarner Losh 9850*8e3e3a7aSWarner Losh 9851*8e3e3a7aSWarner Losh<p> 9852*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> 9853*8e3e3a7aSWarner Losh 9854*8e3e3a7aSWarner Losh 9855*8e3e3a7aSWarner Losh<p> 9856*8e3e3a7aSWarner LoshSets the buffering mode for an output file. 9857*8e3e3a7aSWarner LoshThere are three available modes: 9858*8e3e3a7aSWarner Losh 9859*8e3e3a7aSWarner Losh<ul> 9860*8e3e3a7aSWarner Losh 9861*8e3e3a7aSWarner Losh<li><b>"<code>no</code>": </b> 9862*8e3e3a7aSWarner Loshno buffering; the result of any output operation appears immediately. 9863*8e3e3a7aSWarner Losh</li> 9864*8e3e3a7aSWarner Losh 9865*8e3e3a7aSWarner Losh<li><b>"<code>full</code>": </b> 9866*8e3e3a7aSWarner Loshfull buffering; output operation is performed only 9867*8e3e3a7aSWarner Loshwhen the buffer is full or when 9868*8e3e3a7aSWarner Loshyou explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>). 9869*8e3e3a7aSWarner Losh</li> 9870*8e3e3a7aSWarner Losh 9871*8e3e3a7aSWarner Losh<li><b>"<code>line</code>": </b> 9872*8e3e3a7aSWarner Loshline buffering; output is buffered until a newline is output 9873*8e3e3a7aSWarner Loshor there is any input from some special files 9874*8e3e3a7aSWarner Losh(such as a terminal device). 9875*8e3e3a7aSWarner Losh</li> 9876*8e3e3a7aSWarner Losh 9877*8e3e3a7aSWarner Losh</ul><p> 9878*8e3e3a7aSWarner LoshFor the last two cases, <code>size</code> 9879*8e3e3a7aSWarner Loshspecifies the size of the buffer, in bytes. 9880*8e3e3a7aSWarner LoshThe default is an appropriate size. 9881*8e3e3a7aSWarner Losh 9882*8e3e3a7aSWarner Losh 9883*8e3e3a7aSWarner Losh 9884*8e3e3a7aSWarner Losh 9885*8e3e3a7aSWarner Losh<p> 9886*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> 9887*8e3e3a7aSWarner Losh 9888*8e3e3a7aSWarner Losh 9889*8e3e3a7aSWarner Losh<p> 9890*8e3e3a7aSWarner LoshWrites the value of each of its arguments to <code>file</code>. 9891*8e3e3a7aSWarner LoshThe arguments must be strings or numbers. 9892*8e3e3a7aSWarner Losh 9893*8e3e3a7aSWarner Losh 9894*8e3e3a7aSWarner Losh<p> 9895*8e3e3a7aSWarner LoshIn case of success, this function returns <code>file</code>. 9896*8e3e3a7aSWarner LoshOtherwise it returns <b>nil</b> plus a string describing the error. 9897*8e3e3a7aSWarner Losh 9898*8e3e3a7aSWarner Losh 9899*8e3e3a7aSWarner Losh 9900*8e3e3a7aSWarner Losh 9901*8e3e3a7aSWarner Losh 9902*8e3e3a7aSWarner Losh 9903*8e3e3a7aSWarner Losh 9904*8e3e3a7aSWarner Losh<h2>6.9 – <a name="6.9">Operating System Facilities</a></h2> 9905*8e3e3a7aSWarner Losh 9906*8e3e3a7aSWarner Losh<p> 9907*8e3e3a7aSWarner LoshThis library is implemented through table <a name="pdf-os"><code>os</code></a>. 9908*8e3e3a7aSWarner Losh 9909*8e3e3a7aSWarner Losh 9910*8e3e3a7aSWarner Losh<p> 9911*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> 9912*8e3e3a7aSWarner Losh 9913*8e3e3a7aSWarner Losh 9914*8e3e3a7aSWarner Losh<p> 9915*8e3e3a7aSWarner LoshReturns an approximation of the amount in seconds of CPU time 9916*8e3e3a7aSWarner Loshused by the program. 9917*8e3e3a7aSWarner Losh 9918*8e3e3a7aSWarner Losh 9919*8e3e3a7aSWarner Losh 9920*8e3e3a7aSWarner Losh 9921*8e3e3a7aSWarner Losh<p> 9922*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> 9923*8e3e3a7aSWarner Losh 9924*8e3e3a7aSWarner Losh 9925*8e3e3a7aSWarner Losh<p> 9926*8e3e3a7aSWarner LoshReturns a string or a table containing date and time, 9927*8e3e3a7aSWarner Loshformatted according to the given string <code>format</code>. 9928*8e3e3a7aSWarner Losh 9929*8e3e3a7aSWarner Losh 9930*8e3e3a7aSWarner Losh<p> 9931*8e3e3a7aSWarner LoshIf the <code>time</code> argument is present, 9932*8e3e3a7aSWarner Loshthis is the time to be formatted 9933*8e3e3a7aSWarner Losh(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). 9934*8e3e3a7aSWarner LoshOtherwise, <code>date</code> formats the current time. 9935*8e3e3a7aSWarner Losh 9936*8e3e3a7aSWarner Losh 9937*8e3e3a7aSWarner Losh<p> 9938*8e3e3a7aSWarner LoshIf <code>format</code> starts with '<code>!</code>', 9939*8e3e3a7aSWarner Loshthen the date is formatted in Coordinated Universal Time. 9940*8e3e3a7aSWarner LoshAfter this optional character, 9941*8e3e3a7aSWarner Loshif <code>format</code> is the string "<code>*t</code>", 9942*8e3e3a7aSWarner Loshthen <code>date</code> returns a table with the following fields: 9943*8e3e3a7aSWarner Losh<code>year</code>, <code>month</code> (1–12), <code>day</code> (1–31), 9944*8e3e3a7aSWarner Losh<code>hour</code> (0–23), <code>min</code> (0–59), <code>sec</code> (0–61), 9945*8e3e3a7aSWarner Losh<code>wday</code> (weekday, 1–7, Sunday is 1), 9946*8e3e3a7aSWarner Losh<code>yday</code> (day of the year, 1–366), 9947*8e3e3a7aSWarner Loshand <code>isdst</code> (daylight saving flag, a boolean). 9948*8e3e3a7aSWarner LoshThis last field may be absent 9949*8e3e3a7aSWarner Loshif the information is not available. 9950*8e3e3a7aSWarner Losh 9951*8e3e3a7aSWarner Losh 9952*8e3e3a7aSWarner Losh<p> 9953*8e3e3a7aSWarner LoshIf <code>format</code> is not "<code>*t</code>", 9954*8e3e3a7aSWarner Loshthen <code>date</code> returns the date as a string, 9955*8e3e3a7aSWarner Loshformatted according to the same rules as the ISO C function <code>strftime</code>. 9956*8e3e3a7aSWarner Losh 9957*8e3e3a7aSWarner Losh 9958*8e3e3a7aSWarner Losh<p> 9959*8e3e3a7aSWarner LoshWhen called without arguments, 9960*8e3e3a7aSWarner Losh<code>date</code> returns a reasonable date and time representation that depends on 9961*8e3e3a7aSWarner Loshthe host system and on the current locale. 9962*8e3e3a7aSWarner Losh(More specifically, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>.) 9963*8e3e3a7aSWarner Losh 9964*8e3e3a7aSWarner Losh 9965*8e3e3a7aSWarner Losh<p> 9966*8e3e3a7aSWarner LoshOn non-POSIX systems, 9967*8e3e3a7aSWarner Loshthis function may be not thread safe 9968*8e3e3a7aSWarner Loshbecause of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>. 9969*8e3e3a7aSWarner Losh 9970*8e3e3a7aSWarner Losh 9971*8e3e3a7aSWarner Losh 9972*8e3e3a7aSWarner Losh 9973*8e3e3a7aSWarner Losh<p> 9974*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> 9975*8e3e3a7aSWarner Losh 9976*8e3e3a7aSWarner Losh 9977*8e3e3a7aSWarner Losh<p> 9978*8e3e3a7aSWarner LoshReturns the difference, in seconds, 9979*8e3e3a7aSWarner Loshfrom time <code>t1</code> to time <code>t2</code> 9980*8e3e3a7aSWarner Losh(where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>). 9981*8e3e3a7aSWarner LoshIn POSIX, Windows, and some other systems, 9982*8e3e3a7aSWarner Loshthis value is exactly <code>t2</code><em>-</em><code>t1</code>. 9983*8e3e3a7aSWarner Losh 9984*8e3e3a7aSWarner Losh 9985*8e3e3a7aSWarner Losh 9986*8e3e3a7aSWarner Losh 9987*8e3e3a7aSWarner Losh<p> 9988*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> 9989*8e3e3a7aSWarner Losh 9990*8e3e3a7aSWarner Losh 9991*8e3e3a7aSWarner Losh<p> 9992*8e3e3a7aSWarner LoshThis function is equivalent to the ISO C function <code>system</code>. 9993*8e3e3a7aSWarner LoshIt passes <code>command</code> to be executed by an operating system shell. 9994*8e3e3a7aSWarner LoshIts first result is <b>true</b> 9995*8e3e3a7aSWarner Loshif the command terminated successfully, 9996*8e3e3a7aSWarner Loshor <b>nil</b> otherwise. 9997*8e3e3a7aSWarner LoshAfter this first result 9998*8e3e3a7aSWarner Loshthe function returns a string plus a number, 9999*8e3e3a7aSWarner Loshas follows: 10000*8e3e3a7aSWarner Losh 10001*8e3e3a7aSWarner Losh<ul> 10002*8e3e3a7aSWarner Losh 10003*8e3e3a7aSWarner Losh<li><b>"<code>exit</code>": </b> 10004*8e3e3a7aSWarner Loshthe command terminated normally; 10005*8e3e3a7aSWarner Loshthe following number is the exit status of the command. 10006*8e3e3a7aSWarner Losh</li> 10007*8e3e3a7aSWarner Losh 10008*8e3e3a7aSWarner Losh<li><b>"<code>signal</code>": </b> 10009*8e3e3a7aSWarner Loshthe command was terminated by a signal; 10010*8e3e3a7aSWarner Loshthe following number is the signal that terminated the command. 10011*8e3e3a7aSWarner Losh</li> 10012*8e3e3a7aSWarner Losh 10013*8e3e3a7aSWarner Losh</ul> 10014*8e3e3a7aSWarner Losh 10015*8e3e3a7aSWarner Losh<p> 10016*8e3e3a7aSWarner LoshWhen called without a <code>command</code>, 10017*8e3e3a7aSWarner Losh<code>os.execute</code> returns a boolean that is true if a shell is available. 10018*8e3e3a7aSWarner Losh 10019*8e3e3a7aSWarner Losh 10020*8e3e3a7aSWarner Losh 10021*8e3e3a7aSWarner Losh 10022*8e3e3a7aSWarner Losh<p> 10023*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3> 10024*8e3e3a7aSWarner Losh 10025*8e3e3a7aSWarner Losh 10026*8e3e3a7aSWarner Losh<p> 10027*8e3e3a7aSWarner LoshCalls the ISO C function <code>exit</code> to terminate the host program. 10028*8e3e3a7aSWarner LoshIf <code>code</code> is <b>true</b>, 10029*8e3e3a7aSWarner Loshthe returned status is <code>EXIT_SUCCESS</code>; 10030*8e3e3a7aSWarner Loshif <code>code</code> is <b>false</b>, 10031*8e3e3a7aSWarner Loshthe returned status is <code>EXIT_FAILURE</code>; 10032*8e3e3a7aSWarner Loshif <code>code</code> is a number, 10033*8e3e3a7aSWarner Loshthe returned status is this number. 10034*8e3e3a7aSWarner LoshThe default value for <code>code</code> is <b>true</b>. 10035*8e3e3a7aSWarner Losh 10036*8e3e3a7aSWarner Losh 10037*8e3e3a7aSWarner Losh<p> 10038*8e3e3a7aSWarner LoshIf the optional second argument <code>close</code> is true, 10039*8e3e3a7aSWarner Loshcloses the Lua state before exiting. 10040*8e3e3a7aSWarner Losh 10041*8e3e3a7aSWarner Losh 10042*8e3e3a7aSWarner Losh 10043*8e3e3a7aSWarner Losh 10044*8e3e3a7aSWarner Losh<p> 10045*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> 10046*8e3e3a7aSWarner Losh 10047*8e3e3a7aSWarner Losh 10048*8e3e3a7aSWarner Losh<p> 10049*8e3e3a7aSWarner LoshReturns the value of the process environment variable <code>varname</code>, 10050*8e3e3a7aSWarner Loshor <b>nil</b> if the variable is not defined. 10051*8e3e3a7aSWarner Losh 10052*8e3e3a7aSWarner Losh 10053*8e3e3a7aSWarner Losh 10054*8e3e3a7aSWarner Losh 10055*8e3e3a7aSWarner Losh<p> 10056*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> 10057*8e3e3a7aSWarner Losh 10058*8e3e3a7aSWarner Losh 10059*8e3e3a7aSWarner Losh<p> 10060*8e3e3a7aSWarner LoshDeletes the file (or empty directory, on POSIX systems) 10061*8e3e3a7aSWarner Loshwith the given name. 10062*8e3e3a7aSWarner LoshIf this function fails, it returns <b>nil</b>, 10063*8e3e3a7aSWarner Loshplus a string describing the error and the error code. 10064*8e3e3a7aSWarner LoshOtherwise, it returns true. 10065*8e3e3a7aSWarner Losh 10066*8e3e3a7aSWarner Losh 10067*8e3e3a7aSWarner Losh 10068*8e3e3a7aSWarner Losh 10069*8e3e3a7aSWarner Losh<p> 10070*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> 10071*8e3e3a7aSWarner Losh 10072*8e3e3a7aSWarner Losh 10073*8e3e3a7aSWarner Losh<p> 10074*8e3e3a7aSWarner LoshRenames the file or directory named <code>oldname</code> to <code>newname</code>. 10075*8e3e3a7aSWarner LoshIf this function fails, it returns <b>nil</b>, 10076*8e3e3a7aSWarner Loshplus a string describing the error and the error code. 10077*8e3e3a7aSWarner LoshOtherwise, it returns true. 10078*8e3e3a7aSWarner Losh 10079*8e3e3a7aSWarner Losh 10080*8e3e3a7aSWarner Losh 10081*8e3e3a7aSWarner Losh 10082*8e3e3a7aSWarner Losh<p> 10083*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> 10084*8e3e3a7aSWarner Losh 10085*8e3e3a7aSWarner Losh 10086*8e3e3a7aSWarner Losh<p> 10087*8e3e3a7aSWarner LoshSets the current locale of the program. 10088*8e3e3a7aSWarner Losh<code>locale</code> is a system-dependent string specifying a locale; 10089*8e3e3a7aSWarner Losh<code>category</code> is an optional string describing which category to change: 10090*8e3e3a7aSWarner Losh<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, 10091*8e3e3a7aSWarner Losh<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; 10092*8e3e3a7aSWarner Loshthe default category is <code>"all"</code>. 10093*8e3e3a7aSWarner LoshThe function returns the name of the new locale, 10094*8e3e3a7aSWarner Loshor <b>nil</b> if the request cannot be honored. 10095*8e3e3a7aSWarner Losh 10096*8e3e3a7aSWarner Losh 10097*8e3e3a7aSWarner Losh<p> 10098*8e3e3a7aSWarner LoshIf <code>locale</code> is the empty string, 10099*8e3e3a7aSWarner Loshthe current locale is set to an implementation-defined native locale. 10100*8e3e3a7aSWarner LoshIf <code>locale</code> is the string "<code>C</code>", 10101*8e3e3a7aSWarner Loshthe current locale is set to the standard C locale. 10102*8e3e3a7aSWarner Losh 10103*8e3e3a7aSWarner Losh 10104*8e3e3a7aSWarner Losh<p> 10105*8e3e3a7aSWarner LoshWhen called with <b>nil</b> as the first argument, 10106*8e3e3a7aSWarner Loshthis function only returns the name of the current locale 10107*8e3e3a7aSWarner Loshfor the given category. 10108*8e3e3a7aSWarner Losh 10109*8e3e3a7aSWarner Losh 10110*8e3e3a7aSWarner Losh<p> 10111*8e3e3a7aSWarner LoshThis function may be not thread safe 10112*8e3e3a7aSWarner Loshbecause of its reliance on C function <code>setlocale</code>. 10113*8e3e3a7aSWarner Losh 10114*8e3e3a7aSWarner Losh 10115*8e3e3a7aSWarner Losh 10116*8e3e3a7aSWarner Losh 10117*8e3e3a7aSWarner Losh<p> 10118*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> 10119*8e3e3a7aSWarner Losh 10120*8e3e3a7aSWarner Losh 10121*8e3e3a7aSWarner Losh<p> 10122*8e3e3a7aSWarner LoshReturns the current time when called without arguments, 10123*8e3e3a7aSWarner Loshor a time representing the local date and time specified by the given table. 10124*8e3e3a7aSWarner LoshThis table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, 10125*8e3e3a7aSWarner Loshand may have fields 10126*8e3e3a7aSWarner Losh<code>hour</code> (default is 12), 10127*8e3e3a7aSWarner Losh<code>min</code> (default is 0), 10128*8e3e3a7aSWarner Losh<code>sec</code> (default is 0), 10129*8e3e3a7aSWarner Loshand <code>isdst</code> (default is <b>nil</b>). 10130*8e3e3a7aSWarner LoshOther fields are ignored. 10131*8e3e3a7aSWarner LoshFor a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function. 10132*8e3e3a7aSWarner Losh 10133*8e3e3a7aSWarner Losh 10134*8e3e3a7aSWarner Losh<p> 10135*8e3e3a7aSWarner LoshThe values in these fields do not need to be inside their valid ranges. 10136*8e3e3a7aSWarner LoshFor instance, if <code>sec</code> is -10, 10137*8e3e3a7aSWarner Loshit means -10 seconds from the time specified by the other fields; 10138*8e3e3a7aSWarner Loshif <code>hour</code> is 1000, 10139*8e3e3a7aSWarner Loshit means +1000 hours from the time specified by the other fields. 10140*8e3e3a7aSWarner Losh 10141*8e3e3a7aSWarner Losh 10142*8e3e3a7aSWarner Losh<p> 10143*8e3e3a7aSWarner LoshThe returned value is a number, whose meaning depends on your system. 10144*8e3e3a7aSWarner LoshIn POSIX, Windows, and some other systems, 10145*8e3e3a7aSWarner Loshthis number counts the number 10146*8e3e3a7aSWarner Loshof seconds since some given start time (the "epoch"). 10147*8e3e3a7aSWarner LoshIn other systems, the meaning is not specified, 10148*8e3e3a7aSWarner Loshand the number returned by <code>time</code> can be used only as an argument to 10149*8e3e3a7aSWarner Losh<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. 10150*8e3e3a7aSWarner Losh 10151*8e3e3a7aSWarner Losh 10152*8e3e3a7aSWarner Losh 10153*8e3e3a7aSWarner Losh 10154*8e3e3a7aSWarner Losh<p> 10155*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> 10156*8e3e3a7aSWarner Losh 10157*8e3e3a7aSWarner Losh 10158*8e3e3a7aSWarner Losh<p> 10159*8e3e3a7aSWarner LoshReturns a string with a file name that can 10160*8e3e3a7aSWarner Loshbe used for a temporary file. 10161*8e3e3a7aSWarner LoshThe file must be explicitly opened before its use 10162*8e3e3a7aSWarner Loshand explicitly removed when no longer needed. 10163*8e3e3a7aSWarner Losh 10164*8e3e3a7aSWarner Losh 10165*8e3e3a7aSWarner Losh<p> 10166*8e3e3a7aSWarner LoshOn POSIX systems, 10167*8e3e3a7aSWarner Loshthis function also creates a file with that name, 10168*8e3e3a7aSWarner Loshto avoid security risks. 10169*8e3e3a7aSWarner Losh(Someone else might create the file with wrong permissions 10170*8e3e3a7aSWarner Loshin the time between getting the name and creating the file.) 10171*8e3e3a7aSWarner LoshYou still have to open the file to use it 10172*8e3e3a7aSWarner Loshand to remove it (even if you do not use it). 10173*8e3e3a7aSWarner Losh 10174*8e3e3a7aSWarner Losh 10175*8e3e3a7aSWarner Losh<p> 10176*8e3e3a7aSWarner LoshWhen possible, 10177*8e3e3a7aSWarner Loshyou may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, 10178*8e3e3a7aSWarner Loshwhich automatically removes the file when the program ends. 10179*8e3e3a7aSWarner Losh 10180*8e3e3a7aSWarner Losh 10181*8e3e3a7aSWarner Losh 10182*8e3e3a7aSWarner Losh 10183*8e3e3a7aSWarner Losh 10184*8e3e3a7aSWarner Losh 10185*8e3e3a7aSWarner Losh 10186*8e3e3a7aSWarner Losh<h2>6.10 – <a name="6.10">The Debug Library</a></h2> 10187*8e3e3a7aSWarner Losh 10188*8e3e3a7aSWarner Losh<p> 10189*8e3e3a7aSWarner LoshThis library provides 10190*8e3e3a7aSWarner Loshthe functionality of the debug interface (<a href="#4.9">§4.9</a>) to Lua programs. 10191*8e3e3a7aSWarner LoshYou should exert care when using this library. 10192*8e3e3a7aSWarner LoshSeveral of its functions 10193*8e3e3a7aSWarner Loshviolate basic assumptions about Lua code 10194*8e3e3a7aSWarner Losh(e.g., that variables local to a function 10195*8e3e3a7aSWarner Loshcannot be accessed from outside; 10196*8e3e3a7aSWarner Loshthat userdata metatables cannot be changed by Lua code; 10197*8e3e3a7aSWarner Loshthat Lua programs do not crash) 10198*8e3e3a7aSWarner Loshand therefore can compromise otherwise secure code. 10199*8e3e3a7aSWarner LoshMoreover, some functions in this library may be slow. 10200*8e3e3a7aSWarner Losh 10201*8e3e3a7aSWarner Losh 10202*8e3e3a7aSWarner Losh<p> 10203*8e3e3a7aSWarner LoshAll functions in this library are provided 10204*8e3e3a7aSWarner Loshinside the <a name="pdf-debug"><code>debug</code></a> table. 10205*8e3e3a7aSWarner LoshAll functions that operate over a thread 10206*8e3e3a7aSWarner Loshhave an optional first argument which is the 10207*8e3e3a7aSWarner Loshthread to operate over. 10208*8e3e3a7aSWarner LoshThe default is always the current thread. 10209*8e3e3a7aSWarner Losh 10210*8e3e3a7aSWarner Losh 10211*8e3e3a7aSWarner Losh<p> 10212*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> 10213*8e3e3a7aSWarner Losh 10214*8e3e3a7aSWarner Losh 10215*8e3e3a7aSWarner Losh<p> 10216*8e3e3a7aSWarner LoshEnters an interactive mode with the user, 10217*8e3e3a7aSWarner Loshrunning each string that the user enters. 10218*8e3e3a7aSWarner LoshUsing simple commands and other debug facilities, 10219*8e3e3a7aSWarner Loshthe user can inspect global and local variables, 10220*8e3e3a7aSWarner Loshchange their values, evaluate expressions, and so on. 10221*8e3e3a7aSWarner LoshA line containing only the word <code>cont</code> finishes this function, 10222*8e3e3a7aSWarner Loshso that the caller continues its execution. 10223*8e3e3a7aSWarner Losh 10224*8e3e3a7aSWarner Losh 10225*8e3e3a7aSWarner Losh<p> 10226*8e3e3a7aSWarner LoshNote that commands for <code>debug.debug</code> are not lexically nested 10227*8e3e3a7aSWarner Loshwithin any function and so have no direct access to local variables. 10228*8e3e3a7aSWarner Losh 10229*8e3e3a7aSWarner Losh 10230*8e3e3a7aSWarner Losh 10231*8e3e3a7aSWarner Losh 10232*8e3e3a7aSWarner Losh<p> 10233*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> 10234*8e3e3a7aSWarner Losh 10235*8e3e3a7aSWarner Losh 10236*8e3e3a7aSWarner Losh<p> 10237*8e3e3a7aSWarner LoshReturns the current hook settings of the thread, as three values: 10238*8e3e3a7aSWarner Loshthe current hook function, the current hook mask, 10239*8e3e3a7aSWarner Loshand the current hook count 10240*8e3e3a7aSWarner Losh(as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). 10241*8e3e3a7aSWarner Losh 10242*8e3e3a7aSWarner Losh 10243*8e3e3a7aSWarner Losh 10244*8e3e3a7aSWarner Losh 10245*8e3e3a7aSWarner Losh<p> 10246*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> 10247*8e3e3a7aSWarner Losh 10248*8e3e3a7aSWarner Losh 10249*8e3e3a7aSWarner Losh<p> 10250*8e3e3a7aSWarner LoshReturns a table with information about a function. 10251*8e3e3a7aSWarner LoshYou can give the function directly 10252*8e3e3a7aSWarner Loshor you can give a number as the value of <code>f</code>, 10253*8e3e3a7aSWarner Loshwhich means the function running at level <code>f</code> of the call stack 10254*8e3e3a7aSWarner Loshof the given thread: 10255*8e3e3a7aSWarner Loshlevel 0 is the current function (<code>getinfo</code> itself); 10256*8e3e3a7aSWarner Loshlevel 1 is the function that called <code>getinfo</code> 10257*8e3e3a7aSWarner Losh(except for tail calls, which do not count on the stack); 10258*8e3e3a7aSWarner Loshand so on. 10259*8e3e3a7aSWarner LoshIf <code>f</code> is a number larger than the number of active functions, 10260*8e3e3a7aSWarner Loshthen <code>getinfo</code> returns <b>nil</b>. 10261*8e3e3a7aSWarner Losh 10262*8e3e3a7aSWarner Losh 10263*8e3e3a7aSWarner Losh<p> 10264*8e3e3a7aSWarner LoshThe returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, 10265*8e3e3a7aSWarner Loshwith the string <code>what</code> describing which fields to fill in. 10266*8e3e3a7aSWarner LoshThe default for <code>what</code> is to get all information available, 10267*8e3e3a7aSWarner Loshexcept the table of valid lines. 10268*8e3e3a7aSWarner LoshIf present, 10269*8e3e3a7aSWarner Loshthe option '<code>f</code>' 10270*8e3e3a7aSWarner Loshadds a field named <code>func</code> with the function itself. 10271*8e3e3a7aSWarner LoshIf present, 10272*8e3e3a7aSWarner Loshthe option '<code>L</code>' 10273*8e3e3a7aSWarner Loshadds a field named <code>activelines</code> with the table of 10274*8e3e3a7aSWarner Loshvalid lines. 10275*8e3e3a7aSWarner Losh 10276*8e3e3a7aSWarner Losh 10277*8e3e3a7aSWarner Losh<p> 10278*8e3e3a7aSWarner LoshFor instance, the expression <code>debug.getinfo(1,"n").name</code> returns 10279*8e3e3a7aSWarner Losha name for the current function, 10280*8e3e3a7aSWarner Loshif a reasonable name can be found, 10281*8e3e3a7aSWarner Loshand the expression <code>debug.getinfo(print)</code> 10282*8e3e3a7aSWarner Loshreturns a table with all available information 10283*8e3e3a7aSWarner Loshabout the <a href="#pdf-print"><code>print</code></a> function. 10284*8e3e3a7aSWarner Losh 10285*8e3e3a7aSWarner Losh 10286*8e3e3a7aSWarner Losh 10287*8e3e3a7aSWarner Losh 10288*8e3e3a7aSWarner Losh<p> 10289*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3> 10290*8e3e3a7aSWarner Losh 10291*8e3e3a7aSWarner Losh 10292*8e3e3a7aSWarner Losh<p> 10293*8e3e3a7aSWarner LoshThis function returns the name and the value of the local variable 10294*8e3e3a7aSWarner Loshwith index <code>local</code> of the function at level <code>f</code> of the stack. 10295*8e3e3a7aSWarner LoshThis function accesses not only explicit local variables, 10296*8e3e3a7aSWarner Loshbut also parameters, temporaries, etc. 10297*8e3e3a7aSWarner Losh 10298*8e3e3a7aSWarner Losh 10299*8e3e3a7aSWarner Losh<p> 10300*8e3e3a7aSWarner LoshThe first parameter or local variable has index 1, and so on, 10301*8e3e3a7aSWarner Loshfollowing the order that they are declared in the code, 10302*8e3e3a7aSWarner Loshcounting only the variables that are active 10303*8e3e3a7aSWarner Loshin the current scope of the function. 10304*8e3e3a7aSWarner LoshNegative indices refer to vararg parameters; 10305*8e3e3a7aSWarner Losh-1 is the first vararg parameter. 10306*8e3e3a7aSWarner LoshThe function returns <b>nil</b> if there is no variable with the given index, 10307*8e3e3a7aSWarner Loshand raises an error when called with a level out of range. 10308*8e3e3a7aSWarner Losh(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) 10309*8e3e3a7aSWarner Losh 10310*8e3e3a7aSWarner Losh 10311*8e3e3a7aSWarner Losh<p> 10312*8e3e3a7aSWarner LoshVariable names starting with '<code>(</code>' (open parenthesis) 10313*8e3e3a7aSWarner Loshrepresent variables with no known names 10314*8e3e3a7aSWarner Losh(internal variables such as loop control variables, 10315*8e3e3a7aSWarner Loshand variables from chunks saved without debug information). 10316*8e3e3a7aSWarner Losh 10317*8e3e3a7aSWarner Losh 10318*8e3e3a7aSWarner Losh<p> 10319*8e3e3a7aSWarner LoshThe parameter <code>f</code> may also be a function. 10320*8e3e3a7aSWarner LoshIn that case, <code>getlocal</code> returns only the name of function parameters. 10321*8e3e3a7aSWarner Losh 10322*8e3e3a7aSWarner Losh 10323*8e3e3a7aSWarner Losh 10324*8e3e3a7aSWarner Losh 10325*8e3e3a7aSWarner Losh<p> 10326*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3> 10327*8e3e3a7aSWarner Losh 10328*8e3e3a7aSWarner Losh 10329*8e3e3a7aSWarner Losh<p> 10330*8e3e3a7aSWarner LoshReturns the metatable of the given <code>value</code> 10331*8e3e3a7aSWarner Loshor <b>nil</b> if it does not have a metatable. 10332*8e3e3a7aSWarner Losh 10333*8e3e3a7aSWarner Losh 10334*8e3e3a7aSWarner Losh 10335*8e3e3a7aSWarner Losh 10336*8e3e3a7aSWarner Losh<p> 10337*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> 10338*8e3e3a7aSWarner Losh 10339*8e3e3a7aSWarner Losh 10340*8e3e3a7aSWarner Losh<p> 10341*8e3e3a7aSWarner LoshReturns the registry table (see <a href="#4.5">§4.5</a>). 10342*8e3e3a7aSWarner Losh 10343*8e3e3a7aSWarner Losh 10344*8e3e3a7aSWarner Losh 10345*8e3e3a7aSWarner Losh 10346*8e3e3a7aSWarner Losh<p> 10347*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3> 10348*8e3e3a7aSWarner Losh 10349*8e3e3a7aSWarner Losh 10350*8e3e3a7aSWarner Losh<p> 10351*8e3e3a7aSWarner LoshThis function returns the name and the value of the upvalue 10352*8e3e3a7aSWarner Loshwith index <code>up</code> of the function <code>f</code>. 10353*8e3e3a7aSWarner LoshThe function returns <b>nil</b> if there is no upvalue with the given index. 10354*8e3e3a7aSWarner Losh 10355*8e3e3a7aSWarner Losh 10356*8e3e3a7aSWarner Losh<p> 10357*8e3e3a7aSWarner LoshVariable names starting with '<code>(</code>' (open parenthesis) 10358*8e3e3a7aSWarner Loshrepresent variables with no known names 10359*8e3e3a7aSWarner Losh(variables from chunks saved without debug information). 10360*8e3e3a7aSWarner Losh 10361*8e3e3a7aSWarner Losh 10362*8e3e3a7aSWarner Losh 10363*8e3e3a7aSWarner Losh 10364*8e3e3a7aSWarner Losh<p> 10365*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3> 10366*8e3e3a7aSWarner Losh 10367*8e3e3a7aSWarner Losh 10368*8e3e3a7aSWarner Losh<p> 10369*8e3e3a7aSWarner LoshReturns the Lua value associated to <code>u</code>. 10370*8e3e3a7aSWarner LoshIf <code>u</code> is not a full userdata, 10371*8e3e3a7aSWarner Loshreturns <b>nil</b>. 10372*8e3e3a7aSWarner Losh 10373*8e3e3a7aSWarner Losh 10374*8e3e3a7aSWarner Losh 10375*8e3e3a7aSWarner Losh 10376*8e3e3a7aSWarner Losh<p> 10377*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> 10378*8e3e3a7aSWarner Losh 10379*8e3e3a7aSWarner Losh 10380*8e3e3a7aSWarner Losh<p> 10381*8e3e3a7aSWarner LoshSets the given function as a hook. 10382*8e3e3a7aSWarner LoshThe string <code>mask</code> and the number <code>count</code> describe 10383*8e3e3a7aSWarner Loshwhen the hook will be called. 10384*8e3e3a7aSWarner LoshThe string mask may have any combination of the following characters, 10385*8e3e3a7aSWarner Loshwith the given meaning: 10386*8e3e3a7aSWarner Losh 10387*8e3e3a7aSWarner Losh<ul> 10388*8e3e3a7aSWarner Losh<li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li> 10389*8e3e3a7aSWarner Losh<li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li> 10390*8e3e3a7aSWarner Losh<li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li> 10391*8e3e3a7aSWarner Losh</ul><p> 10392*8e3e3a7aSWarner LoshMoreover, 10393*8e3e3a7aSWarner Loshwith a <code>count</code> different from zero, 10394*8e3e3a7aSWarner Loshthe hook is called also after every <code>count</code> instructions. 10395*8e3e3a7aSWarner Losh 10396*8e3e3a7aSWarner Losh 10397*8e3e3a7aSWarner Losh<p> 10398*8e3e3a7aSWarner LoshWhen called without arguments, 10399*8e3e3a7aSWarner Losh<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. 10400*8e3e3a7aSWarner Losh 10401*8e3e3a7aSWarner Losh 10402*8e3e3a7aSWarner Losh<p> 10403*8e3e3a7aSWarner LoshWhen the hook is called, its first parameter is a string 10404*8e3e3a7aSWarner Loshdescribing the event that has triggered its call: 10405*8e3e3a7aSWarner Losh<code>"call"</code> (or <code>"tail call"</code>), 10406*8e3e3a7aSWarner Losh<code>"return"</code>, 10407*8e3e3a7aSWarner Losh<code>"line"</code>, and <code>"count"</code>. 10408*8e3e3a7aSWarner LoshFor line events, 10409*8e3e3a7aSWarner Loshthe hook also gets the new line number as its second parameter. 10410*8e3e3a7aSWarner LoshInside a hook, 10411*8e3e3a7aSWarner Loshyou can call <code>getinfo</code> with level 2 to get more information about 10412*8e3e3a7aSWarner Loshthe running function 10413*8e3e3a7aSWarner Losh(level 0 is the <code>getinfo</code> function, 10414*8e3e3a7aSWarner Loshand level 1 is the hook function). 10415*8e3e3a7aSWarner Losh 10416*8e3e3a7aSWarner Losh 10417*8e3e3a7aSWarner Losh 10418*8e3e3a7aSWarner Losh 10419*8e3e3a7aSWarner Losh<p> 10420*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> 10421*8e3e3a7aSWarner Losh 10422*8e3e3a7aSWarner Losh 10423*8e3e3a7aSWarner Losh<p> 10424*8e3e3a7aSWarner LoshThis function assigns the value <code>value</code> to the local variable 10425*8e3e3a7aSWarner Loshwith index <code>local</code> of the function at level <code>level</code> of the stack. 10426*8e3e3a7aSWarner LoshThe function returns <b>nil</b> if there is no local 10427*8e3e3a7aSWarner Loshvariable with the given index, 10428*8e3e3a7aSWarner Loshand raises an error when called with a <code>level</code> out of range. 10429*8e3e3a7aSWarner Losh(You can call <code>getinfo</code> to check whether the level is valid.) 10430*8e3e3a7aSWarner LoshOtherwise, it returns the name of the local variable. 10431*8e3e3a7aSWarner Losh 10432*8e3e3a7aSWarner Losh 10433*8e3e3a7aSWarner Losh<p> 10434*8e3e3a7aSWarner LoshSee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about 10435*8e3e3a7aSWarner Loshvariable indices and names. 10436*8e3e3a7aSWarner Losh 10437*8e3e3a7aSWarner Losh 10438*8e3e3a7aSWarner Losh 10439*8e3e3a7aSWarner Losh 10440*8e3e3a7aSWarner Losh<p> 10441*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> 10442*8e3e3a7aSWarner Losh 10443*8e3e3a7aSWarner Losh 10444*8e3e3a7aSWarner Losh<p> 10445*8e3e3a7aSWarner LoshSets the metatable for the given <code>value</code> to the given <code>table</code> 10446*8e3e3a7aSWarner Losh(which can be <b>nil</b>). 10447*8e3e3a7aSWarner LoshReturns <code>value</code>. 10448*8e3e3a7aSWarner Losh 10449*8e3e3a7aSWarner Losh 10450*8e3e3a7aSWarner Losh 10451*8e3e3a7aSWarner Losh 10452*8e3e3a7aSWarner Losh<p> 10453*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> 10454*8e3e3a7aSWarner Losh 10455*8e3e3a7aSWarner Losh 10456*8e3e3a7aSWarner Losh<p> 10457*8e3e3a7aSWarner LoshThis function assigns the value <code>value</code> to the upvalue 10458*8e3e3a7aSWarner Loshwith index <code>up</code> of the function <code>f</code>. 10459*8e3e3a7aSWarner LoshThe function returns <b>nil</b> if there is no upvalue 10460*8e3e3a7aSWarner Loshwith the given index. 10461*8e3e3a7aSWarner LoshOtherwise, it returns the name of the upvalue. 10462*8e3e3a7aSWarner Losh 10463*8e3e3a7aSWarner Losh 10464*8e3e3a7aSWarner Losh 10465*8e3e3a7aSWarner Losh 10466*8e3e3a7aSWarner Losh<p> 10467*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3> 10468*8e3e3a7aSWarner Losh 10469*8e3e3a7aSWarner Losh 10470*8e3e3a7aSWarner Losh<p> 10471*8e3e3a7aSWarner LoshSets the given <code>value</code> as 10472*8e3e3a7aSWarner Loshthe Lua value associated to the given <code>udata</code>. 10473*8e3e3a7aSWarner Losh<code>udata</code> must be a full userdata. 10474*8e3e3a7aSWarner Losh 10475*8e3e3a7aSWarner Losh 10476*8e3e3a7aSWarner Losh<p> 10477*8e3e3a7aSWarner LoshReturns <code>udata</code>. 10478*8e3e3a7aSWarner Losh 10479*8e3e3a7aSWarner Losh 10480*8e3e3a7aSWarner Losh 10481*8e3e3a7aSWarner Losh 10482*8e3e3a7aSWarner Losh<p> 10483*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> 10484*8e3e3a7aSWarner Losh 10485*8e3e3a7aSWarner Losh 10486*8e3e3a7aSWarner Losh<p> 10487*8e3e3a7aSWarner LoshIf <code>message</code> is present but is neither a string nor <b>nil</b>, 10488*8e3e3a7aSWarner Loshthis function returns <code>message</code> without further processing. 10489*8e3e3a7aSWarner LoshOtherwise, 10490*8e3e3a7aSWarner Loshit returns a string with a traceback of the call stack. 10491*8e3e3a7aSWarner LoshThe optional <code>message</code> string is appended 10492*8e3e3a7aSWarner Loshat the beginning of the traceback. 10493*8e3e3a7aSWarner LoshAn optional <code>level</code> number tells at which level 10494*8e3e3a7aSWarner Loshto start the traceback 10495*8e3e3a7aSWarner Losh(default is 1, the function calling <code>traceback</code>). 10496*8e3e3a7aSWarner Losh 10497*8e3e3a7aSWarner Losh 10498*8e3e3a7aSWarner Losh 10499*8e3e3a7aSWarner Losh 10500*8e3e3a7aSWarner Losh<p> 10501*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3> 10502*8e3e3a7aSWarner Losh 10503*8e3e3a7aSWarner Losh 10504*8e3e3a7aSWarner Losh<p> 10505*8e3e3a7aSWarner LoshReturns a unique identifier (as a light userdata) 10506*8e3e3a7aSWarner Loshfor the upvalue numbered <code>n</code> 10507*8e3e3a7aSWarner Loshfrom the given function. 10508*8e3e3a7aSWarner Losh 10509*8e3e3a7aSWarner Losh 10510*8e3e3a7aSWarner Losh<p> 10511*8e3e3a7aSWarner LoshThese unique identifiers allow a program to check whether different 10512*8e3e3a7aSWarner Loshclosures share upvalues. 10513*8e3e3a7aSWarner LoshLua closures that share an upvalue 10514*8e3e3a7aSWarner Losh(that is, that access a same external local variable) 10515*8e3e3a7aSWarner Loshwill return identical ids for those upvalue indices. 10516*8e3e3a7aSWarner Losh 10517*8e3e3a7aSWarner Losh 10518*8e3e3a7aSWarner Losh 10519*8e3e3a7aSWarner Losh 10520*8e3e3a7aSWarner Losh<p> 10521*8e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3> 10522*8e3e3a7aSWarner Losh 10523*8e3e3a7aSWarner Losh 10524*8e3e3a7aSWarner Losh<p> 10525*8e3e3a7aSWarner LoshMake the <code>n1</code>-th upvalue of the Lua closure <code>f1</code> 10526*8e3e3a7aSWarner Loshrefer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>. 10527*8e3e3a7aSWarner Losh 10528*8e3e3a7aSWarner Losh 10529*8e3e3a7aSWarner Losh 10530*8e3e3a7aSWarner Losh 10531*8e3e3a7aSWarner Losh 10532*8e3e3a7aSWarner Losh 10533*8e3e3a7aSWarner Losh 10534*8e3e3a7aSWarner Losh<h1>7 – <a name="7">Lua Standalone</a></h1> 10535*8e3e3a7aSWarner Losh 10536*8e3e3a7aSWarner Losh<p> 10537*8e3e3a7aSWarner LoshAlthough Lua has been designed as an extension language, 10538*8e3e3a7aSWarner Loshto be embedded in a host C program, 10539*8e3e3a7aSWarner Loshit is also frequently used as a standalone language. 10540*8e3e3a7aSWarner LoshAn interpreter for Lua as a standalone language, 10541*8e3e3a7aSWarner Loshcalled simply <code>lua</code>, 10542*8e3e3a7aSWarner Loshis provided with the standard distribution. 10543*8e3e3a7aSWarner LoshThe standalone interpreter includes 10544*8e3e3a7aSWarner Loshall standard libraries, including the debug library. 10545*8e3e3a7aSWarner LoshIts usage is: 10546*8e3e3a7aSWarner Losh 10547*8e3e3a7aSWarner Losh<pre> 10548*8e3e3a7aSWarner Losh lua [options] [script [args]] 10549*8e3e3a7aSWarner Losh</pre><p> 10550*8e3e3a7aSWarner LoshThe options are: 10551*8e3e3a7aSWarner Losh 10552*8e3e3a7aSWarner Losh<ul> 10553*8e3e3a7aSWarner Losh<li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li> 10554*8e3e3a7aSWarner Losh<li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li> 10555*8e3e3a7aSWarner Losh<li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li> 10556*8e3e3a7aSWarner Losh<li><b><code>-v</code>: </b> prints version information;</li> 10557*8e3e3a7aSWarner Losh<li><b><code>-E</code>: </b> ignores environment variables;</li> 10558*8e3e3a7aSWarner Losh<li><b><code>--</code>: </b> stops handling options;</li> 10559*8e3e3a7aSWarner Losh<li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li> 10560*8e3e3a7aSWarner Losh</ul><p> 10561*8e3e3a7aSWarner LoshAfter handling its options, <code>lua</code> runs the given <em>script</em>. 10562*8e3e3a7aSWarner LoshWhen called without arguments, 10563*8e3e3a7aSWarner Losh<code>lua</code> behaves as <code>lua -v -i</code> 10564*8e3e3a7aSWarner Loshwhen the standard input (<code>stdin</code>) is a terminal, 10565*8e3e3a7aSWarner Loshand as <code>lua -</code> otherwise. 10566*8e3e3a7aSWarner Losh 10567*8e3e3a7aSWarner Losh 10568*8e3e3a7aSWarner Losh<p> 10569*8e3e3a7aSWarner LoshWhen called without option <code>-E</code>, 10570*8e3e3a7aSWarner Loshthe interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a> 10571*8e3e3a7aSWarner Losh(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined) 10572*8e3e3a7aSWarner Loshbefore running any argument. 10573*8e3e3a7aSWarner LoshIf the variable content has the format <code>@<em>filename</em></code>, 10574*8e3e3a7aSWarner Loshthen <code>lua</code> executes the file. 10575*8e3e3a7aSWarner LoshOtherwise, <code>lua</code> executes the string itself. 10576*8e3e3a7aSWarner Losh 10577*8e3e3a7aSWarner Losh 10578*8e3e3a7aSWarner Losh<p> 10579*8e3e3a7aSWarner LoshWhen called with option <code>-E</code>, 10580*8e3e3a7aSWarner Loshbesides ignoring <code>LUA_INIT</code>, 10581*8e3e3a7aSWarner LoshLua also ignores 10582*8e3e3a7aSWarner Loshthe values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>, 10583*8e3e3a7aSWarner Loshsetting the values of 10584*8e3e3a7aSWarner Losh<a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a> 10585*8e3e3a7aSWarner Loshwith the default paths defined in <code>luaconf.h</code>. 10586*8e3e3a7aSWarner Losh 10587*8e3e3a7aSWarner Losh 10588*8e3e3a7aSWarner Losh<p> 10589*8e3e3a7aSWarner LoshAll options are handled in order, except <code>-i</code> and <code>-E</code>. 10590*8e3e3a7aSWarner LoshFor instance, an invocation like 10591*8e3e3a7aSWarner Losh 10592*8e3e3a7aSWarner Losh<pre> 10593*8e3e3a7aSWarner Losh $ lua -e'a=1' -e 'print(a)' script.lua 10594*8e3e3a7aSWarner Losh</pre><p> 10595*8e3e3a7aSWarner Loshwill first set <code>a</code> to 1, then print the value of <code>a</code>, 10596*8e3e3a7aSWarner Loshand finally run the file <code>script.lua</code> with no arguments. 10597*8e3e3a7aSWarner Losh(Here <code>$</code> is the shell prompt. Your prompt may be different.) 10598*8e3e3a7aSWarner Losh 10599*8e3e3a7aSWarner Losh 10600*8e3e3a7aSWarner Losh<p> 10601*8e3e3a7aSWarner LoshBefore running any code, 10602*8e3e3a7aSWarner Losh<code>lua</code> collects all command-line arguments 10603*8e3e3a7aSWarner Loshin a global table called <code>arg</code>. 10604*8e3e3a7aSWarner LoshThe script name goes to index 0, 10605*8e3e3a7aSWarner Loshthe first argument after the script name goes to index 1, 10606*8e3e3a7aSWarner Loshand so on. 10607*8e3e3a7aSWarner LoshAny arguments before the script name 10608*8e3e3a7aSWarner Losh(that is, the interpreter name plus its options) 10609*8e3e3a7aSWarner Loshgo to negative indices. 10610*8e3e3a7aSWarner LoshFor instance, in the call 10611*8e3e3a7aSWarner Losh 10612*8e3e3a7aSWarner Losh<pre> 10613*8e3e3a7aSWarner Losh $ lua -la b.lua t1 t2 10614*8e3e3a7aSWarner Losh</pre><p> 10615*8e3e3a7aSWarner Loshthe table is like this: 10616*8e3e3a7aSWarner Losh 10617*8e3e3a7aSWarner Losh<pre> 10618*8e3e3a7aSWarner Losh arg = { [-2] = "lua", [-1] = "-la", 10619*8e3e3a7aSWarner Losh [0] = "b.lua", 10620*8e3e3a7aSWarner Losh [1] = "t1", [2] = "t2" } 10621*8e3e3a7aSWarner Losh</pre><p> 10622*8e3e3a7aSWarner LoshIf there is no script in the call, 10623*8e3e3a7aSWarner Loshthe interpreter name goes to index 0, 10624*8e3e3a7aSWarner Loshfollowed by the other arguments. 10625*8e3e3a7aSWarner LoshFor instance, the call 10626*8e3e3a7aSWarner Losh 10627*8e3e3a7aSWarner Losh<pre> 10628*8e3e3a7aSWarner Losh $ lua -e "print(arg[1])" 10629*8e3e3a7aSWarner Losh</pre><p> 10630*8e3e3a7aSWarner Loshwill print "<code>-e</code>". 10631*8e3e3a7aSWarner LoshIf there is a script, 10632*8e3e3a7aSWarner Loshthe script is called with parameters 10633*8e3e3a7aSWarner Losh<code>arg[1]</code>, ···, <code>arg[#arg]</code>. 10634*8e3e3a7aSWarner Losh(Like all chunks in Lua, 10635*8e3e3a7aSWarner Loshthe script is compiled as a vararg function.) 10636*8e3e3a7aSWarner Losh 10637*8e3e3a7aSWarner Losh 10638*8e3e3a7aSWarner Losh<p> 10639*8e3e3a7aSWarner LoshIn interactive mode, 10640*8e3e3a7aSWarner LoshLua repeatedly prompts and waits for a line. 10641*8e3e3a7aSWarner LoshAfter reading a line, 10642*8e3e3a7aSWarner LoshLua first try to interpret the line as an expression. 10643*8e3e3a7aSWarner LoshIf it succeeds, it prints its value. 10644*8e3e3a7aSWarner LoshOtherwise, it interprets the line as a statement. 10645*8e3e3a7aSWarner LoshIf you write an incomplete statement, 10646*8e3e3a7aSWarner Loshthe interpreter waits for its completion 10647*8e3e3a7aSWarner Loshby issuing a different prompt. 10648*8e3e3a7aSWarner Losh 10649*8e3e3a7aSWarner Losh 10650*8e3e3a7aSWarner Losh<p> 10651*8e3e3a7aSWarner LoshIf the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, 10652*8e3e3a7aSWarner Loshthen its value is used as the prompt. 10653*8e3e3a7aSWarner LoshSimilarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, 10654*8e3e3a7aSWarner Loshits value is used as the secondary prompt 10655*8e3e3a7aSWarner Losh(issued during incomplete statements). 10656*8e3e3a7aSWarner Losh 10657*8e3e3a7aSWarner Losh 10658*8e3e3a7aSWarner Losh<p> 10659*8e3e3a7aSWarner LoshIn case of unprotected errors in the script, 10660*8e3e3a7aSWarner Loshthe interpreter reports the error to the standard error stream. 10661*8e3e3a7aSWarner LoshIf the error object is not a string but 10662*8e3e3a7aSWarner Loshhas a metamethod <code>__tostring</code>, 10663*8e3e3a7aSWarner Loshthe interpreter calls this metamethod to produce the final message. 10664*8e3e3a7aSWarner LoshOtherwise, the interpreter converts the error object to a string 10665*8e3e3a7aSWarner Loshand adds a stack traceback to it. 10666*8e3e3a7aSWarner Losh 10667*8e3e3a7aSWarner Losh 10668*8e3e3a7aSWarner Losh<p> 10669*8e3e3a7aSWarner LoshWhen finishing normally, 10670*8e3e3a7aSWarner Loshthe interpreter closes its main Lua state 10671*8e3e3a7aSWarner Losh(see <a href="#lua_close"><code>lua_close</code></a>). 10672*8e3e3a7aSWarner LoshThe script can avoid this step by 10673*8e3e3a7aSWarner Loshcalling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate. 10674*8e3e3a7aSWarner Losh 10675*8e3e3a7aSWarner Losh 10676*8e3e3a7aSWarner Losh<p> 10677*8e3e3a7aSWarner LoshTo allow the use of Lua as a 10678*8e3e3a7aSWarner Loshscript interpreter in Unix systems, 10679*8e3e3a7aSWarner Loshthe standalone interpreter skips 10680*8e3e3a7aSWarner Loshthe first line of a chunk if it starts with <code>#</code>. 10681*8e3e3a7aSWarner LoshTherefore, Lua scripts can be made into executable programs 10682*8e3e3a7aSWarner Loshby using <code>chmod +x</code> and the <code>#!</code> form, 10683*8e3e3a7aSWarner Loshas in 10684*8e3e3a7aSWarner Losh 10685*8e3e3a7aSWarner Losh<pre> 10686*8e3e3a7aSWarner Losh #!/usr/local/bin/lua 10687*8e3e3a7aSWarner Losh</pre><p> 10688*8e3e3a7aSWarner Losh(Of course, 10689*8e3e3a7aSWarner Loshthe location of the Lua interpreter may be different in your machine. 10690*8e3e3a7aSWarner LoshIf <code>lua</code> is in your <code>PATH</code>, 10691*8e3e3a7aSWarner Loshthen 10692*8e3e3a7aSWarner Losh 10693*8e3e3a7aSWarner Losh<pre> 10694*8e3e3a7aSWarner Losh #!/usr/bin/env lua 10695*8e3e3a7aSWarner Losh</pre><p> 10696*8e3e3a7aSWarner Loshis a more portable solution.) 10697*8e3e3a7aSWarner Losh 10698*8e3e3a7aSWarner Losh 10699*8e3e3a7aSWarner Losh 10700*8e3e3a7aSWarner Losh<h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> 10701*8e3e3a7aSWarner Losh 10702*8e3e3a7aSWarner Losh<p> 10703*8e3e3a7aSWarner LoshHere we list the incompatibilities that you may find when moving a program 10704*8e3e3a7aSWarner Loshfrom Lua 5.2 to Lua 5.3. 10705*8e3e3a7aSWarner LoshYou can avoid some incompatibilities by compiling Lua with 10706*8e3e3a7aSWarner Loshappropriate options (see file <code>luaconf.h</code>). 10707*8e3e3a7aSWarner LoshHowever, 10708*8e3e3a7aSWarner Loshall these compatibility options will be removed in the future. 10709*8e3e3a7aSWarner Losh 10710*8e3e3a7aSWarner Losh 10711*8e3e3a7aSWarner Losh<p> 10712*8e3e3a7aSWarner LoshLua versions can always change the C API in ways that 10713*8e3e3a7aSWarner Loshdo not imply source-code changes in a program, 10714*8e3e3a7aSWarner Loshsuch as the numeric values for constants 10715*8e3e3a7aSWarner Loshor the implementation of functions as macros. 10716*8e3e3a7aSWarner LoshTherefore, 10717*8e3e3a7aSWarner Loshyou should not assume that binaries are compatible between 10718*8e3e3a7aSWarner Loshdifferent Lua versions. 10719*8e3e3a7aSWarner LoshAlways recompile clients of the Lua API when 10720*8e3e3a7aSWarner Loshusing a new version. 10721*8e3e3a7aSWarner Losh 10722*8e3e3a7aSWarner Losh 10723*8e3e3a7aSWarner Losh<p> 10724*8e3e3a7aSWarner LoshSimilarly, Lua versions can always change the internal representation 10725*8e3e3a7aSWarner Loshof precompiled chunks; 10726*8e3e3a7aSWarner Loshprecompiled chunks are not compatible between different Lua versions. 10727*8e3e3a7aSWarner Losh 10728*8e3e3a7aSWarner Losh 10729*8e3e3a7aSWarner Losh<p> 10730*8e3e3a7aSWarner LoshThe standard paths in the official distribution may 10731*8e3e3a7aSWarner Loshchange between versions. 10732*8e3e3a7aSWarner Losh 10733*8e3e3a7aSWarner Losh 10734*8e3e3a7aSWarner Losh 10735*8e3e3a7aSWarner Losh<h2>8.1 – <a name="8.1">Changes in the Language</a></h2> 10736*8e3e3a7aSWarner Losh<ul> 10737*8e3e3a7aSWarner Losh 10738*8e3e3a7aSWarner Losh<li> 10739*8e3e3a7aSWarner LoshThe main difference between Lua 5.2 and Lua 5.3 is the 10740*8e3e3a7aSWarner Loshintroduction of an integer subtype for numbers. 10741*8e3e3a7aSWarner LoshAlthough this change should not affect "normal" computations, 10742*8e3e3a7aSWarner Loshsome computations 10743*8e3e3a7aSWarner Losh(mainly those that involve some kind of overflow) 10744*8e3e3a7aSWarner Loshcan give different results. 10745*8e3e3a7aSWarner Losh 10746*8e3e3a7aSWarner Losh 10747*8e3e3a7aSWarner Losh<p> 10748*8e3e3a7aSWarner LoshYou can fix these differences by forcing a number to be a float 10749*8e3e3a7aSWarner Losh(in Lua 5.2 all numbers were float), 10750*8e3e3a7aSWarner Loshin particular writing constants with an ending <code>.0</code> 10751*8e3e3a7aSWarner Loshor using <code>x = x + 0.0</code> to convert a variable. 10752*8e3e3a7aSWarner Losh(This recommendation is only for a quick fix 10753*8e3e3a7aSWarner Loshfor an occasional incompatibility; 10754*8e3e3a7aSWarner Loshit is not a general guideline for good programming. 10755*8e3e3a7aSWarner LoshFor good programming, 10756*8e3e3a7aSWarner Loshuse floats where you need floats 10757*8e3e3a7aSWarner Loshand integers where you need integers.) 10758*8e3e3a7aSWarner Losh</li> 10759*8e3e3a7aSWarner Losh 10760*8e3e3a7aSWarner Losh<li> 10761*8e3e3a7aSWarner LoshThe conversion of a float to a string now adds a <code>.0</code> suffix 10762*8e3e3a7aSWarner Loshto the result if it looks like an integer. 10763*8e3e3a7aSWarner Losh(For instance, the float 2.0 will be printed as <code>2.0</code>, 10764*8e3e3a7aSWarner Loshnot as <code>2</code>.) 10765*8e3e3a7aSWarner LoshYou should always use an explicit format 10766*8e3e3a7aSWarner Loshwhen you need a specific format for numbers. 10767*8e3e3a7aSWarner Losh 10768*8e3e3a7aSWarner Losh 10769*8e3e3a7aSWarner Losh<p> 10770*8e3e3a7aSWarner Losh(Formally this is not an incompatibility, 10771*8e3e3a7aSWarner Loshbecause Lua does not specify how numbers are formatted as strings, 10772*8e3e3a7aSWarner Loshbut some programs assumed a specific format.) 10773*8e3e3a7aSWarner Losh</li> 10774*8e3e3a7aSWarner Losh 10775*8e3e3a7aSWarner Losh<li> 10776*8e3e3a7aSWarner LoshThe generational mode for the garbage collector was removed. 10777*8e3e3a7aSWarner Losh(It was an experimental feature in Lua 5.2.) 10778*8e3e3a7aSWarner Losh</li> 10779*8e3e3a7aSWarner Losh 10780*8e3e3a7aSWarner Losh</ul> 10781*8e3e3a7aSWarner Losh 10782*8e3e3a7aSWarner Losh 10783*8e3e3a7aSWarner Losh 10784*8e3e3a7aSWarner Losh 10785*8e3e3a7aSWarner Losh<h2>8.2 – <a name="8.2">Changes in the Libraries</a></h2> 10786*8e3e3a7aSWarner Losh<ul> 10787*8e3e3a7aSWarner Losh 10788*8e3e3a7aSWarner Losh<li> 10789*8e3e3a7aSWarner LoshThe <code>bit32</code> library has been deprecated. 10790*8e3e3a7aSWarner LoshIt is easy to require a compatible external library or, 10791*8e3e3a7aSWarner Loshbetter yet, to replace its functions with appropriate bitwise operations. 10792*8e3e3a7aSWarner Losh(Keep in mind that <code>bit32</code> operates on 32-bit integers, 10793*8e3e3a7aSWarner Loshwhile the bitwise operators in Lua 5.3 operate on Lua integers, 10794*8e3e3a7aSWarner Loshwhich by default have 64 bits.) 10795*8e3e3a7aSWarner Losh</li> 10796*8e3e3a7aSWarner Losh 10797*8e3e3a7aSWarner Losh<li> 10798*8e3e3a7aSWarner LoshThe Table library now respects metamethods 10799*8e3e3a7aSWarner Loshfor setting and getting elements. 10800*8e3e3a7aSWarner Losh</li> 10801*8e3e3a7aSWarner Losh 10802*8e3e3a7aSWarner Losh<li> 10803*8e3e3a7aSWarner LoshThe <a href="#pdf-ipairs"><code>ipairs</code></a> iterator now respects metamethods and 10804*8e3e3a7aSWarner Loshits <code>__ipairs</code> metamethod has been deprecated. 10805*8e3e3a7aSWarner Losh</li> 10806*8e3e3a7aSWarner Losh 10807*8e3e3a7aSWarner Losh<li> 10808*8e3e3a7aSWarner LoshOption names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore. 10809*8e3e3a7aSWarner LoshFor compatibility, Lua will continue to accept (and ignore) this character. 10810*8e3e3a7aSWarner Losh</li> 10811*8e3e3a7aSWarner Losh 10812*8e3e3a7aSWarner Losh<li> 10813*8e3e3a7aSWarner LoshThe following functions were deprecated in the mathematical library: 10814*8e3e3a7aSWarner Losh<code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>, 10815*8e3e3a7aSWarner Losh<code>frexp</code>, and <code>ldexp</code>. 10816*8e3e3a7aSWarner LoshYou can replace <code>math.pow(x,y)</code> with <code>x^y</code>; 10817*8e3e3a7aSWarner Loshyou can replace <code>math.atan2</code> with <code>math.atan</code>, 10818*8e3e3a7aSWarner Loshwhich now accepts one or two parameters; 10819*8e3e3a7aSWarner Loshyou can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>. 10820*8e3e3a7aSWarner LoshFor the other operations, 10821*8e3e3a7aSWarner Loshyou can either use an external library or 10822*8e3e3a7aSWarner Loshimplement them in Lua. 10823*8e3e3a7aSWarner Losh</li> 10824*8e3e3a7aSWarner Losh 10825*8e3e3a7aSWarner Losh<li> 10826*8e3e3a7aSWarner LoshThe searcher for C loaders used by <a href="#pdf-require"><code>require</code></a> 10827*8e3e3a7aSWarner Loshchanged the way it handles versioned names. 10828*8e3e3a7aSWarner LoshNow, the version should come after the module name 10829*8e3e3a7aSWarner Losh(as is usual in most other tools). 10830*8e3e3a7aSWarner LoshFor compatibility, that searcher still tries the old format 10831*8e3e3a7aSWarner Loshif it cannot find an open function according to the new style. 10832*8e3e3a7aSWarner Losh(Lua 5.2 already worked that way, 10833*8e3e3a7aSWarner Loshbut it did not document the change.) 10834*8e3e3a7aSWarner Losh</li> 10835*8e3e3a7aSWarner Losh 10836*8e3e3a7aSWarner Losh<li> 10837*8e3e3a7aSWarner LoshThe call <code>collectgarbage("count")</code> now returns only one result. 10838*8e3e3a7aSWarner Losh(You can compute that second result from the fractional part 10839*8e3e3a7aSWarner Loshof the first result.) 10840*8e3e3a7aSWarner Losh</li> 10841*8e3e3a7aSWarner Losh 10842*8e3e3a7aSWarner Losh</ul> 10843*8e3e3a7aSWarner Losh 10844*8e3e3a7aSWarner Losh 10845*8e3e3a7aSWarner Losh 10846*8e3e3a7aSWarner Losh 10847*8e3e3a7aSWarner Losh<h2>8.3 – <a name="8.3">Changes in the API</a></h2> 10848*8e3e3a7aSWarner Losh 10849*8e3e3a7aSWarner Losh 10850*8e3e3a7aSWarner Losh<ul> 10851*8e3e3a7aSWarner Losh 10852*8e3e3a7aSWarner Losh<li> 10853*8e3e3a7aSWarner LoshContinuation functions now receive as parameters what they needed 10854*8e3e3a7aSWarner Loshto get through <code>lua_getctx</code>, 10855*8e3e3a7aSWarner Loshso <code>lua_getctx</code> has been removed. 10856*8e3e3a7aSWarner LoshAdapt your code accordingly. 10857*8e3e3a7aSWarner Losh</li> 10858*8e3e3a7aSWarner Losh 10859*8e3e3a7aSWarner Losh<li> 10860*8e3e3a7aSWarner LoshFunction <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>. 10861*8e3e3a7aSWarner LoshUse 0 as the value of this parameter to get the old behavior. 10862*8e3e3a7aSWarner Losh</li> 10863*8e3e3a7aSWarner Losh 10864*8e3e3a7aSWarner Losh<li> 10865*8e3e3a7aSWarner LoshFunctions to inject/project unsigned integers 10866*8e3e3a7aSWarner Losh(<code>lua_pushunsigned</code>, <code>lua_tounsigned</code>, <code>lua_tounsignedx</code>, 10867*8e3e3a7aSWarner Losh<code>luaL_checkunsigned</code>, <code>luaL_optunsigned</code>) 10868*8e3e3a7aSWarner Loshwere deprecated. 10869*8e3e3a7aSWarner LoshUse their signed equivalents with a type cast. 10870*8e3e3a7aSWarner Losh</li> 10871*8e3e3a7aSWarner Losh 10872*8e3e3a7aSWarner Losh<li> 10873*8e3e3a7aSWarner LoshMacros to project non-default integer types 10874*8e3e3a7aSWarner Losh(<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>) 10875*8e3e3a7aSWarner Loshwere deprecated. 10876*8e3e3a7aSWarner LoshUse their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast 10877*8e3e3a7aSWarner Losh(or, when possible, use <a href="#lua_Integer"><code>lua_Integer</code></a> in your code). 10878*8e3e3a7aSWarner Losh</li> 10879*8e3e3a7aSWarner Losh 10880*8e3e3a7aSWarner Losh</ul> 10881*8e3e3a7aSWarner Losh 10882*8e3e3a7aSWarner Losh 10883*8e3e3a7aSWarner Losh 10884*8e3e3a7aSWarner Losh 10885*8e3e3a7aSWarner Losh<h1>9 – <a name="9">The Complete Syntax of Lua</a></h1> 10886*8e3e3a7aSWarner Losh 10887*8e3e3a7aSWarner Losh<p> 10888*8e3e3a7aSWarner LoshHere is the complete syntax of Lua in extended BNF. 10889*8e3e3a7aSWarner LoshAs usual in extended BNF, 10890*8e3e3a7aSWarner Losh{A} means 0 or more As, 10891*8e3e3a7aSWarner Loshand [A] means an optional A. 10892*8e3e3a7aSWarner Losh(For operator precedences, see <a href="#3.4.8">§3.4.8</a>; 10893*8e3e3a7aSWarner Loshfor a description of the terminals 10894*8e3e3a7aSWarner LoshName, Numeral, 10895*8e3e3a7aSWarner Loshand LiteralString, see <a href="#3.1">§3.1</a>.) 10896*8e3e3a7aSWarner Losh 10897*8e3e3a7aSWarner Losh 10898*8e3e3a7aSWarner Losh 10899*8e3e3a7aSWarner Losh 10900*8e3e3a7aSWarner Losh<pre> 10901*8e3e3a7aSWarner Losh 10902*8e3e3a7aSWarner Losh chunk ::= block 10903*8e3e3a7aSWarner Losh 10904*8e3e3a7aSWarner Losh block ::= {stat} [retstat] 10905*8e3e3a7aSWarner Losh 10906*8e3e3a7aSWarner Losh stat ::= ‘<b>;</b>’ | 10907*8e3e3a7aSWarner Losh varlist ‘<b>=</b>’ explist | 10908*8e3e3a7aSWarner Losh functioncall | 10909*8e3e3a7aSWarner Losh label | 10910*8e3e3a7aSWarner Losh <b>break</b> | 10911*8e3e3a7aSWarner Losh <b>goto</b> Name | 10912*8e3e3a7aSWarner Losh <b>do</b> block <b>end</b> | 10913*8e3e3a7aSWarner Losh <b>while</b> exp <b>do</b> block <b>end</b> | 10914*8e3e3a7aSWarner Losh <b>repeat</b> block <b>until</b> exp | 10915*8e3e3a7aSWarner Losh <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 10916*8e3e3a7aSWarner Losh <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> | 10917*8e3e3a7aSWarner Losh <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 10918*8e3e3a7aSWarner Losh <b>function</b> funcname funcbody | 10919*8e3e3a7aSWarner Losh <b>local</b> <b>function</b> Name funcbody | 10920*8e3e3a7aSWarner Losh <b>local</b> namelist [‘<b>=</b>’ explist] 10921*8e3e3a7aSWarner Losh 10922*8e3e3a7aSWarner Losh retstat ::= <b>return</b> [explist] [‘<b>;</b>’] 10923*8e3e3a7aSWarner Losh 10924*8e3e3a7aSWarner Losh label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 10925*8e3e3a7aSWarner Losh 10926*8e3e3a7aSWarner Losh funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 10927*8e3e3a7aSWarner Losh 10928*8e3e3a7aSWarner Losh varlist ::= var {‘<b>,</b>’ var} 10929*8e3e3a7aSWarner Losh 10930*8e3e3a7aSWarner Losh var ::= Name | prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | prefixexp ‘<b>.</b>’ Name 10931*8e3e3a7aSWarner Losh 10932*8e3e3a7aSWarner Losh namelist ::= Name {‘<b>,</b>’ Name} 10933*8e3e3a7aSWarner Losh 10934*8e3e3a7aSWarner Losh explist ::= exp {‘<b>,</b>’ exp} 10935*8e3e3a7aSWarner Losh 10936*8e3e3a7aSWarner Losh exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | ‘<b>...</b>’ | functiondef | 10937*8e3e3a7aSWarner Losh prefixexp | tableconstructor | exp binop exp | unop exp 10938*8e3e3a7aSWarner Losh 10939*8e3e3a7aSWarner Losh prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 10940*8e3e3a7aSWarner Losh 10941*8e3e3a7aSWarner Losh functioncall ::= prefixexp args | prefixexp ‘<b>:</b>’ Name args 10942*8e3e3a7aSWarner Losh 10943*8e3e3a7aSWarner Losh args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | tableconstructor | LiteralString 10944*8e3e3a7aSWarner Losh 10945*8e3e3a7aSWarner Losh functiondef ::= <b>function</b> funcbody 10946*8e3e3a7aSWarner Losh 10947*8e3e3a7aSWarner Losh funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 10948*8e3e3a7aSWarner Losh 10949*8e3e3a7aSWarner Losh parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 10950*8e3e3a7aSWarner Losh 10951*8e3e3a7aSWarner Losh tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 10952*8e3e3a7aSWarner Losh 10953*8e3e3a7aSWarner Losh fieldlist ::= field {fieldsep field} [fieldsep] 10954*8e3e3a7aSWarner Losh 10955*8e3e3a7aSWarner Losh field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 10956*8e3e3a7aSWarner Losh 10957*8e3e3a7aSWarner Losh fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 10958*8e3e3a7aSWarner Losh 10959*8e3e3a7aSWarner Losh binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</b>’ | ‘<b>//</b>’ | ‘<b>^</b>’ | ‘<b>%</b>’ | 10960*8e3e3a7aSWarner Losh ‘<b>&</b>’ | ‘<b>~</b>’ | ‘<b>|</b>’ | ‘<b>>></b>’ | ‘<b><<</b>’ | ‘<b>..</b>’ | 10961*8e3e3a7aSWarner Losh ‘<b><</b>’ | ‘<b><=</b>’ | ‘<b>></b>’ | ‘<b>>=</b>’ | ‘<b>==</b>’ | ‘<b>~=</b>’ | 10962*8e3e3a7aSWarner Losh <b>and</b> | <b>or</b> 10963*8e3e3a7aSWarner Losh 10964*8e3e3a7aSWarner Losh unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’ | ‘<b>~</b>’ 10965*8e3e3a7aSWarner Losh 10966*8e3e3a7aSWarner Losh</pre> 10967*8e3e3a7aSWarner Losh 10968*8e3e3a7aSWarner Losh<p> 10969*8e3e3a7aSWarner Losh 10970*8e3e3a7aSWarner Losh 10971*8e3e3a7aSWarner Losh 10972*8e3e3a7aSWarner Losh 10973*8e3e3a7aSWarner Losh 10974*8e3e3a7aSWarner Losh 10975*8e3e3a7aSWarner Losh 10976*8e3e3a7aSWarner Losh<P CLASS="footer"> 10977*8e3e3a7aSWarner LoshLast update: 10978*8e3e3a7aSWarner LoshMon Jan 9 13:30:53 BRST 2017 10979*8e3e3a7aSWarner Losh</P> 10980*8e3e3a7aSWarner Losh<!-- 10981*8e3e3a7aSWarner LoshLast change: revised for Lua 5.3.4 10982*8e3e3a7aSWarner Losh--> 10983*8e3e3a7aSWarner Losh 10984*8e3e3a7aSWarner Losh</body></html> 10985*8e3e3a7aSWarner Losh 10986
