18e3e3a7aSWarner Losh<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 28e3e3a7aSWarner Losh<HTML> 38e3e3a7aSWarner Losh<HEAD> 40495ed39SKyle Evans<TITLE>Lua 5.4 Reference Manual</TITLE> 58e3e3a7aSWarner Losh<LINK REL="stylesheet" TYPE="text/css" HREF="lua.css"> 68e3e3a7aSWarner Losh<LINK REL="stylesheet" TYPE="text/css" HREF="manual.css"> 78e3e3a7aSWarner Losh<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> 88e3e3a7aSWarner Losh</HEAD> 98e3e3a7aSWarner Losh 108e3e3a7aSWarner Losh<BODY> 118e3e3a7aSWarner Losh 128e3e3a7aSWarner Losh<H1> 138e3e3a7aSWarner Losh<A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A> 140495ed39SKyle EvansLua 5.4 Reference Manual 158e3e3a7aSWarner Losh</H1> 168e3e3a7aSWarner Losh 178e3e3a7aSWarner Losh<P> 188e3e3a7aSWarner Loshby Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes 198e3e3a7aSWarner Losh 208e3e3a7aSWarner Losh<P> 218e3e3a7aSWarner Losh<SMALL> 22*a9490b81SWarner LoshCopyright © 2020–2023 Lua.org, PUC-Rio. 238e3e3a7aSWarner LoshFreely available under the terms of the 248e3e3a7aSWarner Losh<a href="http://www.lua.org/license.html">Lua license</a>. 258e3e3a7aSWarner Losh</SMALL> 268e3e3a7aSWarner Losh 278e3e3a7aSWarner Losh<DIV CLASS="menubar"> 288e3e3a7aSWarner Losh<A HREF="contents.html#contents">contents</A> 298e3e3a7aSWarner Losh· 308e3e3a7aSWarner Losh<A HREF="contents.html#index">index</A> 318e3e3a7aSWarner Losh· 328e3e3a7aSWarner Losh<A HREF="http://www.lua.org/manual/">other versions</A> 338e3e3a7aSWarner Losh</DIV> 348e3e3a7aSWarner Losh 358e3e3a7aSWarner Losh<!-- ====================================================================== --> 368e3e3a7aSWarner Losh<p> 378e3e3a7aSWarner Losh 380495ed39SKyle Evans<!-- $Id: manual.of $ --> 398e3e3a7aSWarner Losh 408e3e3a7aSWarner Losh 418e3e3a7aSWarner Losh 428e3e3a7aSWarner Losh 438e3e3a7aSWarner Losh<h1>1 – <a name="1">Introduction</a></h1> 448e3e3a7aSWarner Losh 458e3e3a7aSWarner Losh<p> 468e3e3a7aSWarner LoshLua is a powerful, efficient, lightweight, embeddable scripting language. 478e3e3a7aSWarner LoshIt supports procedural programming, 488e3e3a7aSWarner Loshobject-oriented programming, functional programming, 498e3e3a7aSWarner Loshdata-driven programming, and data description. 508e3e3a7aSWarner Losh 518e3e3a7aSWarner Losh 528e3e3a7aSWarner Losh<p> 538e3e3a7aSWarner LoshLua combines simple procedural syntax with powerful data description 548e3e3a7aSWarner Loshconstructs based on associative arrays and extensible semantics. 558e3e3a7aSWarner LoshLua is dynamically typed, 568e3e3a7aSWarner Loshruns by interpreting bytecode with a register-based 578e3e3a7aSWarner Loshvirtual machine, 588e3e3a7aSWarner Loshand has automatic memory management with 590495ed39SKyle Evansa generational garbage collection, 608e3e3a7aSWarner Loshmaking it ideal for configuration, scripting, 618e3e3a7aSWarner Loshand rapid prototyping. 628e3e3a7aSWarner Losh 638e3e3a7aSWarner Losh 648e3e3a7aSWarner Losh<p> 658e3e3a7aSWarner LoshLua is implemented as a library, written in <em>clean C</em>, 66*a9490b81SWarner Loshthe common subset of standard C and C++. 678e3e3a7aSWarner LoshThe Lua distribution includes a host program called <code>lua</code>, 688e3e3a7aSWarner Loshwhich uses the Lua library to offer a complete, 698e3e3a7aSWarner Loshstandalone Lua interpreter, 708e3e3a7aSWarner Loshfor interactive or batch use. 718e3e3a7aSWarner LoshLua is intended to be used both as a powerful, lightweight, 728e3e3a7aSWarner Loshembeddable scripting language for any program that needs one, 738e3e3a7aSWarner Loshand as a powerful but lightweight and efficient stand-alone language. 748e3e3a7aSWarner Losh 758e3e3a7aSWarner Losh 768e3e3a7aSWarner Losh<p> 778e3e3a7aSWarner LoshAs an extension language, Lua has no notion of a "main" program: 788e3e3a7aSWarner Loshit works <em>embedded</em> in a host client, 798e3e3a7aSWarner Loshcalled the <em>embedding program</em> or simply the <em>host</em>. 808e3e3a7aSWarner Losh(Frequently, this host is the stand-alone <code>lua</code> program.) 818e3e3a7aSWarner LoshThe host program can invoke functions to execute a piece of Lua code, 828e3e3a7aSWarner Loshcan write and read Lua variables, 838e3e3a7aSWarner Loshand can register C functions to be called by Lua code. 848e3e3a7aSWarner LoshThrough the use of C functions, Lua can be augmented to cope with 858e3e3a7aSWarner Losha wide range of different domains, 868e3e3a7aSWarner Loshthus creating customized programming languages sharing a syntactical framework. 878e3e3a7aSWarner Losh 888e3e3a7aSWarner Losh 898e3e3a7aSWarner Losh<p> 908e3e3a7aSWarner LoshLua is free software, 918e3e3a7aSWarner Loshand is provided as usual with no guarantees, 928e3e3a7aSWarner Loshas stated in its license. 938e3e3a7aSWarner LoshThe implementation described in this manual is available 948e3e3a7aSWarner Loshat Lua's official web site, <code>www.lua.org</code>. 958e3e3a7aSWarner Losh 968e3e3a7aSWarner Losh 978e3e3a7aSWarner Losh<p> 988e3e3a7aSWarner LoshLike any other reference manual, 998e3e3a7aSWarner Loshthis document is dry in places. 1008e3e3a7aSWarner LoshFor a discussion of the decisions behind the design of Lua, 1018e3e3a7aSWarner Loshsee the technical papers available at Lua's web site. 1028e3e3a7aSWarner LoshFor a detailed introduction to programming in Lua, 1038e3e3a7aSWarner Loshsee Roberto's book, <em>Programming in Lua</em>. 1048e3e3a7aSWarner Losh 1058e3e3a7aSWarner Losh 1068e3e3a7aSWarner Losh 1078e3e3a7aSWarner Losh<h1>2 – <a name="2">Basic Concepts</a></h1> 1088e3e3a7aSWarner Losh 1090495ed39SKyle Evans 1100495ed39SKyle Evans 1118e3e3a7aSWarner Losh<p> 1128e3e3a7aSWarner LoshThis section describes the basic concepts of the language. 1138e3e3a7aSWarner Losh 1148e3e3a7aSWarner Losh 1158e3e3a7aSWarner Losh 1160495ed39SKyle Evans 1170495ed39SKyle Evans 1188e3e3a7aSWarner Losh<h2>2.1 – <a name="2.1">Values and Types</a></h2> 1198e3e3a7aSWarner Losh 1208e3e3a7aSWarner Losh<p> 1210495ed39SKyle EvansLua is a dynamically typed language. 1228e3e3a7aSWarner LoshThis means that 1238e3e3a7aSWarner Loshvariables do not have types; only values do. 1248e3e3a7aSWarner LoshThere are no type definitions in the language. 1258e3e3a7aSWarner LoshAll values carry their own type. 1268e3e3a7aSWarner Losh 1278e3e3a7aSWarner Losh 1288e3e3a7aSWarner Losh<p> 1290495ed39SKyle EvansAll values in Lua are first-class values. 1308e3e3a7aSWarner LoshThis means that all values can be stored in variables, 1318e3e3a7aSWarner Loshpassed as arguments to other functions, and returned as results. 1328e3e3a7aSWarner Losh 1338e3e3a7aSWarner Losh 1348e3e3a7aSWarner Losh<p> 1358e3e3a7aSWarner LoshThere are eight basic types in Lua: 1368e3e3a7aSWarner Losh<em>nil</em>, <em>boolean</em>, <em>number</em>, 1378e3e3a7aSWarner Losh<em>string</em>, <em>function</em>, <em>userdata</em>, 1388e3e3a7aSWarner Losh<em>thread</em>, and <em>table</em>. 1398e3e3a7aSWarner LoshThe type <em>nil</em> has one single value, <b>nil</b>, 1408e3e3a7aSWarner Loshwhose main property is to be different from any other value; 1410495ed39SKyle Evansit often represents the absence of a useful value. 1428e3e3a7aSWarner LoshThe type <em>boolean</em> has two values, <b>false</b> and <b>true</b>. 1438e3e3a7aSWarner LoshBoth <b>nil</b> and <b>false</b> make a condition false; 1440495ed39SKyle Evansthey are collectively called <em>false values</em>. 1450495ed39SKyle EvansAny other value makes a condition true. 1468c784bb8SWarner LoshDespite its name, 1478c784bb8SWarner Losh<b>false</b> is frequently used as an alternative to <b>nil</b>, 1488c784bb8SWarner Loshwith the key difference that <b>false</b> behaves 1498c784bb8SWarner Loshlike a regular value in a table, 1508c784bb8SWarner Loshwhile a <b>nil</b> in a table represents an absent key. 1518e3e3a7aSWarner Losh 1528e3e3a7aSWarner Losh 1538e3e3a7aSWarner Losh<p> 1540495ed39SKyle EvansThe type <em>number</em> represents both 1550495ed39SKyle Evansinteger numbers and real (floating-point) numbers, 1560495ed39SKyle Evansusing two subtypes: <em>integer</em> and <em>float</em>. 1578e3e3a7aSWarner LoshStandard Lua uses 64-bit integers and double-precision (64-bit) floats, 1588e3e3a7aSWarner Loshbut you can also compile Lua so that it 1598e3e3a7aSWarner Loshuses 32-bit integers and/or single-precision (32-bit) floats. 1608e3e3a7aSWarner LoshThe option with 32 bits for both integers and floats 1618e3e3a7aSWarner Loshis particularly attractive 1628e3e3a7aSWarner Loshfor small machines and embedded systems. 1638e3e3a7aSWarner Losh(See macro <code>LUA_32BITS</code> in file <code>luaconf.h</code>.) 1648e3e3a7aSWarner Losh 1658e3e3a7aSWarner Losh 1668e3e3a7aSWarner Losh<p> 1670495ed39SKyle EvansUnless stated otherwise, 1680495ed39SKyle Evansany overflow when manipulating integer values <em>wrap around</em>, 1690495ed39SKyle Evansaccording to the usual rules of two-complement arithmetic. 1700495ed39SKyle Evans(In other words, 1710495ed39SKyle Evansthe actual result is the unique representable integer 1720495ed39SKyle Evansthat is equal modulo <em>2<sup>n</sup></em> to the mathematical result, 1730495ed39SKyle Evanswhere <em>n</em> is the number of bits of the integer type.) 1740495ed39SKyle Evans 1750495ed39SKyle Evans 1760495ed39SKyle Evans<p> 1770495ed39SKyle EvansLua has explicit rules about when each subtype is used, 1780495ed39SKyle Evansbut it also converts between them automatically as needed (see <a href="#3.4.3">§3.4.3</a>). 1790495ed39SKyle EvansTherefore, 1800495ed39SKyle Evansthe programmer may choose to mostly ignore the difference 1810495ed39SKyle Evansbetween integers and floats 1820495ed39SKyle Evansor to assume complete control over the representation of each number. 1830495ed39SKyle Evans 1840495ed39SKyle Evans 1850495ed39SKyle Evans<p> 1860495ed39SKyle EvansThe type <em>string</em> represents immutable sequences of bytes. 1870495ed39SKyle Evans 1880495ed39SKyle EvansLua is 8-bit clean: 1890495ed39SKyle Evansstrings can contain any 8-bit value, 1900495ed39SKyle Evansincluding embedded zeros ('<code>\0</code>'). 1910495ed39SKyle EvansLua is also encoding-agnostic; 1920495ed39SKyle Evansit makes no assumptions about the contents of a string. 1930495ed39SKyle EvansThe length of any string in Lua must fit in a Lua integer. 1940495ed39SKyle Evans 1950495ed39SKyle Evans 1960495ed39SKyle Evans<p> 1978e3e3a7aSWarner LoshLua can call (and manipulate) functions written in Lua and 1988e3e3a7aSWarner Loshfunctions written in C (see <a href="#3.4.10">§3.4.10</a>). 1998e3e3a7aSWarner LoshBoth are represented by the type <em>function</em>. 2008e3e3a7aSWarner Losh 2018e3e3a7aSWarner Losh 2028e3e3a7aSWarner Losh<p> 2038e3e3a7aSWarner LoshThe type <em>userdata</em> is provided to allow arbitrary C data to 2048e3e3a7aSWarner Loshbe stored in Lua variables. 2058e3e3a7aSWarner LoshA userdata value represents a block of raw memory. 2068e3e3a7aSWarner LoshThere are two kinds of userdata: 2078e3e3a7aSWarner Losh<em>full userdata</em>, 2088e3e3a7aSWarner Loshwhich is an object with a block of memory managed by Lua, 2098e3e3a7aSWarner Loshand <em>light userdata</em>, 2108e3e3a7aSWarner Loshwhich is simply a C pointer value. 2118e3e3a7aSWarner LoshUserdata has no predefined operations in Lua, 2128e3e3a7aSWarner Loshexcept assignment and identity test. 2138e3e3a7aSWarner LoshBy using <em>metatables</em>, 2148e3e3a7aSWarner Loshthe programmer can define operations for full userdata values 2158e3e3a7aSWarner Losh(see <a href="#2.4">§2.4</a>). 2168e3e3a7aSWarner LoshUserdata values cannot be created or modified in Lua, 2178e3e3a7aSWarner Loshonly through the C API. 2180495ed39SKyle EvansThis guarantees the integrity of data owned by 2190495ed39SKyle Evansthe host program and C libraries. 2208e3e3a7aSWarner Losh 2218e3e3a7aSWarner Losh 2228e3e3a7aSWarner Losh<p> 2238e3e3a7aSWarner LoshThe type <em>thread</em> represents independent threads of execution 2248e3e3a7aSWarner Loshand it is used to implement coroutines (see <a href="#2.6">§2.6</a>). 2258e3e3a7aSWarner LoshLua threads are not related to operating-system threads. 2268e3e3a7aSWarner LoshLua supports coroutines on all systems, 2278e3e3a7aSWarner Losheven those that do not support threads natively. 2288e3e3a7aSWarner Losh 2298e3e3a7aSWarner Losh 2308e3e3a7aSWarner Losh<p> 2318e3e3a7aSWarner LoshThe type <em>table</em> implements associative arrays, 232e112e9d2SKyle Evansthat is, arrays that can have as indices not only numbers, 233e112e9d2SKyle Evansbut any Lua value except <b>nil</b> and NaN. 2340495ed39SKyle Evans(<em>Not a Number</em> is a special floating-point value 2350495ed39SKyle Evansused by the IEEE 754 standard to represent 2360495ed39SKyle Evansundefined numerical results, such as <code>0/0</code>.) 2378e3e3a7aSWarner LoshTables can be <em>heterogeneous</em>; 2388e3e3a7aSWarner Loshthat is, they can contain values of all types (except <b>nil</b>). 2390495ed39SKyle EvansAny key associated to the value <b>nil</b> is not considered part of the table. 2408e3e3a7aSWarner LoshConversely, any key that is not part of a table has 2418e3e3a7aSWarner Loshan associated value <b>nil</b>. 2428e3e3a7aSWarner Losh 2438e3e3a7aSWarner Losh 2448e3e3a7aSWarner Losh<p> 2458e3e3a7aSWarner LoshTables are the sole data-structuring mechanism in Lua; 2468e3e3a7aSWarner Loshthey can be used to represent ordinary arrays, lists, 2478e3e3a7aSWarner Loshsymbol tables, sets, records, graphs, trees, etc. 2488e3e3a7aSWarner LoshTo represent records, Lua uses the field name as an index. 2498e3e3a7aSWarner LoshThe language supports this representation by 2508e3e3a7aSWarner Loshproviding <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. 2518e3e3a7aSWarner LoshThere are several convenient ways to create tables in Lua 2528e3e3a7aSWarner Losh(see <a href="#3.4.9">§3.4.9</a>). 2538e3e3a7aSWarner Losh 2548e3e3a7aSWarner Losh 2558e3e3a7aSWarner Losh<p> 2568e3e3a7aSWarner LoshLike indices, 2578e3e3a7aSWarner Loshthe values of table fields can be of any type. 2588e3e3a7aSWarner LoshIn particular, 2598e3e3a7aSWarner Loshbecause functions are first-class values, 2608e3e3a7aSWarner Loshtable fields can contain functions. 2618e3e3a7aSWarner LoshThus tables can also carry <em>methods</em> (see <a href="#3.4.11">§3.4.11</a>). 2628e3e3a7aSWarner Losh 2638e3e3a7aSWarner Losh 2648e3e3a7aSWarner Losh<p> 2658e3e3a7aSWarner LoshThe indexing of tables follows 2668e3e3a7aSWarner Loshthe definition of raw equality in the language. 2678e3e3a7aSWarner LoshThe expressions <code>a[i]</code> and <code>a[j]</code> 2688e3e3a7aSWarner Loshdenote the same table element 2698e3e3a7aSWarner Loshif and only if <code>i</code> and <code>j</code> are raw equal 2708e3e3a7aSWarner Losh(that is, equal without metamethods). 2718e3e3a7aSWarner LoshIn particular, floats with integral values 2728e3e3a7aSWarner Loshare equal to their respective integers 2738e3e3a7aSWarner Losh(e.g., <code>1.0 == 1</code>). 2748e3e3a7aSWarner LoshTo avoid ambiguities, 2750495ed39SKyle Evansany float used as a key that is equal to an integer 2760495ed39SKyle Evansis converted to that integer. 2778e3e3a7aSWarner LoshFor instance, if you write <code>a[2.0] = true</code>, 2780495ed39SKyle Evansthe actual key inserted into the table will be the integer <code>2</code>. 2798e3e3a7aSWarner Losh 2808e3e3a7aSWarner Losh 2818e3e3a7aSWarner Losh<p> 2828e3e3a7aSWarner LoshTables, functions, threads, and (full) userdata values are <em>objects</em>: 2838e3e3a7aSWarner Loshvariables do not actually <em>contain</em> these values, 2848e3e3a7aSWarner Loshonly <em>references</em> to them. 2858e3e3a7aSWarner LoshAssignment, parameter passing, and function returns 2868e3e3a7aSWarner Loshalways manipulate references to such values; 2878e3e3a7aSWarner Loshthese operations do not imply any kind of copy. 2888e3e3a7aSWarner Losh 2898e3e3a7aSWarner Losh 2908e3e3a7aSWarner Losh<p> 2918e3e3a7aSWarner LoshThe library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type 2920495ed39SKyle Evansof a given value (see <a href="#pdf-type"><code>type</code></a>). 2938e3e3a7aSWarner Losh 2948e3e3a7aSWarner Losh 2958e3e3a7aSWarner Losh 2968e3e3a7aSWarner Losh 2978e3e3a7aSWarner Losh 2988e3e3a7aSWarner Losh<h2>2.2 – <a name="2.2">Environments and the Global Environment</a></h2> 2998e3e3a7aSWarner Losh 3008e3e3a7aSWarner Losh<p> 3010495ed39SKyle EvansAs we will discuss further in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>, 3028e3e3a7aSWarner Loshany reference to a free name 3038e3e3a7aSWarner Losh(that is, a name not bound to any declaration) <code>var</code> 3048e3e3a7aSWarner Loshis syntactically translated to <code>_ENV.var</code>. 3058e3e3a7aSWarner LoshMoreover, every chunk is compiled in the scope of 3068e3e3a7aSWarner Loshan external local variable named <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>), 3078e3e3a7aSWarner Loshso <code>_ENV</code> itself is never a free name in a chunk. 3088e3e3a7aSWarner Losh 3098e3e3a7aSWarner Losh 3108e3e3a7aSWarner Losh<p> 3118e3e3a7aSWarner LoshDespite the existence of this external <code>_ENV</code> variable and 3128e3e3a7aSWarner Loshthe translation of free names, 3138e3e3a7aSWarner Losh<code>_ENV</code> is a completely regular name. 3148e3e3a7aSWarner LoshIn particular, 3158e3e3a7aSWarner Loshyou can define new variables and parameters with that name. 3168e3e3a7aSWarner LoshEach reference to a free name uses the <code>_ENV</code> that is 3178e3e3a7aSWarner Loshvisible at that point in the program, 3188e3e3a7aSWarner Loshfollowing the usual visibility rules of Lua (see <a href="#3.5">§3.5</a>). 3198e3e3a7aSWarner Losh 3208e3e3a7aSWarner Losh 3218e3e3a7aSWarner Losh<p> 3228e3e3a7aSWarner LoshAny table used as the value of <code>_ENV</code> is called an <em>environment</em>. 3238e3e3a7aSWarner Losh 3248e3e3a7aSWarner Losh 3258e3e3a7aSWarner Losh<p> 3268e3e3a7aSWarner LoshLua keeps a distinguished environment called the <em>global environment</em>. 3270495ed39SKyle EvansThis value is kept at a special index in the C registry (see <a href="#4.3">§4.3</a>). 3288e3e3a7aSWarner LoshIn Lua, the global variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value. 3290495ed39SKyle Evans(<a href="#pdf-_G"><code>_G</code></a> is never used internally, 3300495ed39SKyle Evansso changing its value will affect only your own code.) 3318e3e3a7aSWarner Losh 3328e3e3a7aSWarner Losh 3338e3e3a7aSWarner Losh<p> 3348e3e3a7aSWarner LoshWhen Lua loads a chunk, 3350495ed39SKyle Evansthe default value for its <code>_ENV</code> variable 3368e3e3a7aSWarner Loshis the global environment (see <a href="#pdf-load"><code>load</code></a>). 3378e3e3a7aSWarner LoshTherefore, by default, 3388e3e3a7aSWarner Loshfree names in Lua code refer to entries in the global environment 3390495ed39SKyle Evansand, therefore, they are also called <em>global variables</em>. 3408e3e3a7aSWarner LoshMoreover, all standard libraries are loaded in the global environment 3418e3e3a7aSWarner Loshand some functions there operate on that environment. 3428e3e3a7aSWarner LoshYou can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>) 3438e3e3a7aSWarner Loshto load a chunk with a different environment. 3448e3e3a7aSWarner Losh(In C, you have to load the chunk and then change the value 3450495ed39SKyle Evansof its first upvalue; see <a href="#lua_setupvalue"><code>lua_setupvalue</code></a>.) 3468e3e3a7aSWarner Losh 3478e3e3a7aSWarner Losh 3488e3e3a7aSWarner Losh 3498e3e3a7aSWarner Losh 3508e3e3a7aSWarner Losh 3518e3e3a7aSWarner Losh<h2>2.3 – <a name="2.3">Error Handling</a></h2> 3528e3e3a7aSWarner Losh 3538e3e3a7aSWarner Losh<p> 3540495ed39SKyle EvansSeveral operations in Lua can <em>raise</em> an error. 3550495ed39SKyle EvansAn error interrupts the normal flow of the program, 3560495ed39SKyle Evanswhich can continue by <em>catching</em> the error. 3578e3e3a7aSWarner Losh 3588e3e3a7aSWarner Losh 3598e3e3a7aSWarner Losh<p> 3600495ed39SKyle EvansLua code can explicitly raise an error by calling the 3618e3e3a7aSWarner Losh<a href="#pdf-error"><code>error</code></a> function. 3620495ed39SKyle Evans(This function never returns.) 3630495ed39SKyle Evans 3640495ed39SKyle Evans 3650495ed39SKyle Evans<p> 3660495ed39SKyle EvansTo catch errors in Lua, 3670495ed39SKyle Evansyou can do a <em>protected call</em>, 3680495ed39SKyle Evansusing <a href="#pdf-pcall"><code>pcall</code></a> (or <a href="#pdf-xpcall"><code>xpcall</code></a>). 3690495ed39SKyle EvansThe function <a href="#pdf-pcall"><code>pcall</code></a> calls a given function in <em>protected mode</em>. 3700495ed39SKyle EvansAny error while running the function stops its execution, 3710495ed39SKyle Evansand control returns immediately to <code>pcall</code>, 3720495ed39SKyle Evanswhich returns a status code. 3730495ed39SKyle Evans 3740495ed39SKyle Evans 3750495ed39SKyle Evans<p> 3760495ed39SKyle EvansBecause Lua is an embedded extension language, 3770495ed39SKyle EvansLua code starts running by a call 3780495ed39SKyle Evansfrom C code in the host program. 3790495ed39SKyle Evans(When you use Lua standalone, 3800495ed39SKyle Evansthe <code>lua</code> application is the host program.) 3810495ed39SKyle EvansUsually, this call is protected; 3820495ed39SKyle Evansso, when an otherwise unprotected error occurs during 3830495ed39SKyle Evansthe compilation or execution of a Lua chunk, 3840495ed39SKyle Evanscontrol returns to the host, 3850495ed39SKyle Evanswhich can take appropriate measures, 3860495ed39SKyle Evanssuch as printing an error message. 3878e3e3a7aSWarner Losh 3888e3e3a7aSWarner Losh 3898e3e3a7aSWarner Losh<p> 3908e3e3a7aSWarner LoshWhenever there is an error, 3910495ed39SKyle Evansan <em>error object</em> 3928e3e3a7aSWarner Loshis propagated with information about the error. 3938e3e3a7aSWarner LoshLua itself only generates errors whose error object is a string, 3948e3e3a7aSWarner Loshbut programs may generate errors with 3958e3e3a7aSWarner Loshany value as the error object. 3968e3e3a7aSWarner LoshIt is up to the Lua program or its host to handle such error objects. 3970495ed39SKyle EvansFor historical reasons, 3980495ed39SKyle Evansan error object is often called an <em>error message</em>, 3990495ed39SKyle Evanseven though it does not have to be a string. 4008e3e3a7aSWarner Losh 4018e3e3a7aSWarner Losh 4028e3e3a7aSWarner Losh<p> 4030495ed39SKyle EvansWhen you use <a href="#pdf-xpcall"><code>xpcall</code></a> (or <a href="#lua_pcall"><code>lua_pcall</code></a>, in C) 4048e3e3a7aSWarner Loshyou may give a <em>message handler</em> 4058e3e3a7aSWarner Loshto be called in case of errors. 4068e3e3a7aSWarner LoshThis function is called with the original error object 4078e3e3a7aSWarner Loshand returns a new error object. 4088e3e3a7aSWarner LoshIt is called before the error unwinds the stack, 4098e3e3a7aSWarner Loshso that it can gather more information about the error, 4108e3e3a7aSWarner Loshfor instance by inspecting the stack and creating a stack traceback. 4118e3e3a7aSWarner LoshThis message handler is still protected by the protected call; 4128e3e3a7aSWarner Loshso, an error inside the message handler 4138e3e3a7aSWarner Loshwill call the message handler again. 4148e3e3a7aSWarner LoshIf this loop goes on for too long, 4158e3e3a7aSWarner LoshLua breaks it and returns an appropriate message. 4160495ed39SKyle EvansThe message handler is called only for regular runtime errors. 4178e3e3a7aSWarner LoshIt is not called for memory-allocation errors 4180495ed39SKyle Evansnor for errors while running finalizers or other message handlers. 4190495ed39SKyle Evans 4200495ed39SKyle Evans 4210495ed39SKyle Evans<p> 4220495ed39SKyle EvansLua also offers a system of <em>warnings</em> (see <a href="#pdf-warn"><code>warn</code></a>). 4230495ed39SKyle EvansUnlike errors, warnings do not interfere 4240495ed39SKyle Evansin any way with program execution. 4250495ed39SKyle EvansThey typically only generate a message to the user, 4260495ed39SKyle Evansalthough this behavior can be adapted from C (see <a href="#lua_setwarnf"><code>lua_setwarnf</code></a>). 4278e3e3a7aSWarner Losh 4288e3e3a7aSWarner Losh 4298e3e3a7aSWarner Losh 4308e3e3a7aSWarner Losh 4318e3e3a7aSWarner Losh 4328e3e3a7aSWarner Losh<h2>2.4 – <a name="2.4">Metatables and Metamethods</a></h2> 4338e3e3a7aSWarner Losh 4348e3e3a7aSWarner Losh<p> 4358e3e3a7aSWarner LoshEvery value in Lua can have a <em>metatable</em>. 4368e3e3a7aSWarner LoshThis <em>metatable</em> is an ordinary Lua table 4378e3e3a7aSWarner Loshthat defines the behavior of the original value 4380495ed39SKyle Evansunder certain events. 4398e3e3a7aSWarner LoshYou can change several aspects of the behavior 4400495ed39SKyle Evansof a value by setting specific fields in its metatable. 4418e3e3a7aSWarner LoshFor instance, when a non-numeric value is the operand of an addition, 4428c784bb8SWarner LoshLua checks for a function in the field <code>__add</code> of the value's metatable. 4438e3e3a7aSWarner LoshIf it finds one, 4448e3e3a7aSWarner LoshLua calls this function to perform the addition. 4458e3e3a7aSWarner Losh 4468e3e3a7aSWarner Losh 4478e3e3a7aSWarner Losh<p> 4488e3e3a7aSWarner LoshThe key for each event in a metatable is a string 4498e3e3a7aSWarner Loshwith the event name prefixed by two underscores; 4500495ed39SKyle Evansthe corresponding value is called a <em>metavalue</em>. 4510495ed39SKyle EvansFor most events, the metavalue must be a function, 4520495ed39SKyle Evanswhich is then called a <em>metamethod</em>. 4530495ed39SKyle EvansIn the previous example, the key is the string "<code>__add</code>" 4548e3e3a7aSWarner Loshand the metamethod is the function that performs the addition. 455e112e9d2SKyle EvansUnless stated otherwise, 4560495ed39SKyle Evansa metamethod may in fact be any callable value, 4570495ed39SKyle Evanswhich is either a function or a value with a <code>__call</code> metamethod. 4588e3e3a7aSWarner Losh 4598e3e3a7aSWarner Losh 4608e3e3a7aSWarner Losh<p> 4618e3e3a7aSWarner LoshYou can query the metatable of any value 4628e3e3a7aSWarner Loshusing the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function. 4638e3e3a7aSWarner LoshLua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>). 4648e3e3a7aSWarner Losh 4658e3e3a7aSWarner Losh 4668e3e3a7aSWarner Losh<p> 4678e3e3a7aSWarner LoshYou can replace the metatable of tables 4688e3e3a7aSWarner Loshusing the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function. 4690495ed39SKyle EvansYou cannot change the metatable of other types from Lua code, 4700495ed39SKyle Evansexcept by using the debug library (<a href="#6.10">§6.10</a>). 4718e3e3a7aSWarner Losh 4728e3e3a7aSWarner Losh 4738e3e3a7aSWarner Losh<p> 4740495ed39SKyle EvansTables and full userdata have individual metatables, 4750495ed39SKyle Evansalthough multiple tables and userdata can share their metatables. 4768e3e3a7aSWarner LoshValues of all other types share one single metatable per type; 4778e3e3a7aSWarner Loshthat is, there is one single metatable for all numbers, 4788e3e3a7aSWarner Loshone for all strings, etc. 4798e3e3a7aSWarner LoshBy default, a value has no metatable, 4808e3e3a7aSWarner Loshbut the string library sets a metatable for the string type (see <a href="#6.4">§6.4</a>). 4818e3e3a7aSWarner Losh 4828e3e3a7aSWarner Losh 4838e3e3a7aSWarner Losh<p> 4840495ed39SKyle EvansA detailed list of operations controlled by metatables is given next. 4850495ed39SKyle EvansEach event is identified by its corresponding key. 4860495ed39SKyle EvansBy convention, all metatable keys used by Lua are composed by 4870495ed39SKyle Evanstwo underscores followed by lowercase Latin letters. 4888e3e3a7aSWarner Losh 4898e3e3a7aSWarner Losh 4908e3e3a7aSWarner Losh 4918e3e3a7aSWarner Losh<ul> 4928e3e3a7aSWarner Losh 4938e3e3a7aSWarner Losh<li><b><code>__add</code>: </b> 4948e3e3a7aSWarner Loshthe addition (<code>+</code>) operation. 4950495ed39SKyle EvansIf any operand for an addition is not a number, 4968e3e3a7aSWarner LoshLua will try to call a metamethod. 4970495ed39SKyle EvansIt starts by checking the first operand (even if it is a number); 4980495ed39SKyle Evansif that operand does not define a metamethod for <code>__add</code>, 4998e3e3a7aSWarner Loshthen Lua will check the second operand. 5008e3e3a7aSWarner LoshIf Lua can find a metamethod, 5018e3e3a7aSWarner Loshit calls the metamethod with the two operands as arguments, 5028e3e3a7aSWarner Loshand the result of the call 5038e3e3a7aSWarner Losh(adjusted to one value) 5048e3e3a7aSWarner Loshis the result of the operation. 5050495ed39SKyle EvansOtherwise, if no metamethod is found, 5060495ed39SKyle EvansLua raises an error. 5078e3e3a7aSWarner Losh</li> 5088e3e3a7aSWarner Losh 5098e3e3a7aSWarner Losh<li><b><code>__sub</code>: </b> 5108e3e3a7aSWarner Loshthe subtraction (<code>-</code>) operation. 5118e3e3a7aSWarner LoshBehavior similar to the addition operation. 5128e3e3a7aSWarner Losh</li> 5138e3e3a7aSWarner Losh 5148e3e3a7aSWarner Losh<li><b><code>__mul</code>: </b> 5158e3e3a7aSWarner Loshthe multiplication (<code>*</code>) operation. 5168e3e3a7aSWarner LoshBehavior similar to the addition operation. 5178e3e3a7aSWarner Losh</li> 5188e3e3a7aSWarner Losh 5198e3e3a7aSWarner Losh<li><b><code>__div</code>: </b> 5208e3e3a7aSWarner Loshthe division (<code>/</code>) operation. 5218e3e3a7aSWarner LoshBehavior similar to the addition operation. 5228e3e3a7aSWarner Losh</li> 5238e3e3a7aSWarner Losh 5248e3e3a7aSWarner Losh<li><b><code>__mod</code>: </b> 5258e3e3a7aSWarner Loshthe modulo (<code>%</code>) operation. 5268e3e3a7aSWarner LoshBehavior similar to the addition operation. 5278e3e3a7aSWarner Losh</li> 5288e3e3a7aSWarner Losh 5298e3e3a7aSWarner Losh<li><b><code>__pow</code>: </b> 5308e3e3a7aSWarner Loshthe exponentiation (<code>^</code>) operation. 5318e3e3a7aSWarner LoshBehavior similar to the addition operation. 5328e3e3a7aSWarner Losh</li> 5338e3e3a7aSWarner Losh 5348e3e3a7aSWarner Losh<li><b><code>__unm</code>: </b> 5358e3e3a7aSWarner Loshthe negation (unary <code>-</code>) operation. 5368e3e3a7aSWarner LoshBehavior similar to the addition operation. 5378e3e3a7aSWarner Losh</li> 5388e3e3a7aSWarner Losh 5398e3e3a7aSWarner Losh<li><b><code>__idiv</code>: </b> 5408e3e3a7aSWarner Loshthe floor division (<code>//</code>) operation. 5418e3e3a7aSWarner LoshBehavior similar to the addition operation. 5428e3e3a7aSWarner Losh</li> 5438e3e3a7aSWarner Losh 5448e3e3a7aSWarner Losh<li><b><code>__band</code>: </b> 5458e3e3a7aSWarner Loshthe bitwise AND (<code>&</code>) operation. 5468e3e3a7aSWarner LoshBehavior similar to the addition operation, 5478e3e3a7aSWarner Loshexcept that Lua will try a metamethod 5488e3e3a7aSWarner Loshif any operand is neither an integer 5490495ed39SKyle Evansnor a float coercible to an integer (see <a href="#3.4.3">§3.4.3</a>). 5508e3e3a7aSWarner Losh</li> 5518e3e3a7aSWarner Losh 5528e3e3a7aSWarner Losh<li><b><code>__bor</code>: </b> 5538e3e3a7aSWarner Loshthe bitwise OR (<code>|</code>) operation. 5548e3e3a7aSWarner LoshBehavior similar to the bitwise AND operation. 5558e3e3a7aSWarner Losh</li> 5568e3e3a7aSWarner Losh 5578e3e3a7aSWarner Losh<li><b><code>__bxor</code>: </b> 5588e3e3a7aSWarner Loshthe bitwise exclusive OR (binary <code>~</code>) operation. 5598e3e3a7aSWarner LoshBehavior similar to the bitwise AND operation. 5608e3e3a7aSWarner Losh</li> 5618e3e3a7aSWarner Losh 5628e3e3a7aSWarner Losh<li><b><code>__bnot</code>: </b> 5638e3e3a7aSWarner Loshthe bitwise NOT (unary <code>~</code>) operation. 5648e3e3a7aSWarner LoshBehavior similar to the bitwise AND operation. 5658e3e3a7aSWarner Losh</li> 5668e3e3a7aSWarner Losh 5678e3e3a7aSWarner Losh<li><b><code>__shl</code>: </b> 5688e3e3a7aSWarner Loshthe bitwise left shift (<code><<</code>) operation. 5698e3e3a7aSWarner LoshBehavior similar to the bitwise AND operation. 5708e3e3a7aSWarner Losh</li> 5718e3e3a7aSWarner Losh 5728e3e3a7aSWarner Losh<li><b><code>__shr</code>: </b> 5738e3e3a7aSWarner Loshthe bitwise right shift (<code>>></code>) operation. 5748e3e3a7aSWarner LoshBehavior similar to the bitwise AND operation. 5758e3e3a7aSWarner Losh</li> 5768e3e3a7aSWarner Losh 5778e3e3a7aSWarner Losh<li><b><code>__concat</code>: </b> 5788e3e3a7aSWarner Loshthe concatenation (<code>..</code>) operation. 5798e3e3a7aSWarner LoshBehavior similar to the addition operation, 5808e3e3a7aSWarner Loshexcept that Lua will try a metamethod 5818e3e3a7aSWarner Loshif any operand is neither a string nor a number 5828e3e3a7aSWarner Losh(which is always coercible to a string). 5838e3e3a7aSWarner Losh</li> 5848e3e3a7aSWarner Losh 5858e3e3a7aSWarner Losh<li><b><code>__len</code>: </b> 5868e3e3a7aSWarner Loshthe length (<code>#</code>) operation. 5878e3e3a7aSWarner LoshIf the object is not a string, 5888e3e3a7aSWarner LoshLua will try its metamethod. 5898e3e3a7aSWarner LoshIf there is a metamethod, 5908e3e3a7aSWarner LoshLua calls it with the object as argument, 5918e3e3a7aSWarner Loshand the result of the call 5928e3e3a7aSWarner Losh(always adjusted to one value) 5938e3e3a7aSWarner Loshis the result of the operation. 5948e3e3a7aSWarner LoshIf there is no metamethod but the object is a table, 5958e3e3a7aSWarner Loshthen Lua uses the table length operation (see <a href="#3.4.7">§3.4.7</a>). 5968e3e3a7aSWarner LoshOtherwise, Lua raises an error. 5978e3e3a7aSWarner Losh</li> 5988e3e3a7aSWarner Losh 5998e3e3a7aSWarner Losh<li><b><code>__eq</code>: </b> 6008e3e3a7aSWarner Loshthe equal (<code>==</code>) operation. 6018e3e3a7aSWarner LoshBehavior similar to the addition operation, 6028e3e3a7aSWarner Loshexcept that Lua will try a metamethod only when the values 6038e3e3a7aSWarner Loshbeing compared are either both tables or both full userdata 6048e3e3a7aSWarner Loshand they are not primitively equal. 6058e3e3a7aSWarner LoshThe result of the call is always converted to a boolean. 6068e3e3a7aSWarner Losh</li> 6078e3e3a7aSWarner Losh 6088e3e3a7aSWarner Losh<li><b><code>__lt</code>: </b> 6098e3e3a7aSWarner Loshthe less than (<code><</code>) operation. 6108e3e3a7aSWarner LoshBehavior similar to the addition operation, 6118e3e3a7aSWarner Loshexcept that Lua will try a metamethod only when the values 6128e3e3a7aSWarner Loshbeing compared are neither both numbers nor both strings. 6130495ed39SKyle EvansMoreover, the result of the call is always converted to a boolean. 6148e3e3a7aSWarner Losh</li> 6158e3e3a7aSWarner Losh 6168e3e3a7aSWarner Losh<li><b><code>__le</code>: </b> 6178e3e3a7aSWarner Loshthe less equal (<code><=</code>) operation. 6180495ed39SKyle EvansBehavior similar to the less than operation. 6198e3e3a7aSWarner Losh</li> 6208e3e3a7aSWarner Losh 6218e3e3a7aSWarner Losh<li><b><code>__index</code>: </b> 622e112e9d2SKyle EvansThe indexing access operation <code>table[key]</code>. 6238e3e3a7aSWarner LoshThis event happens when <code>table</code> is not a table or 6248e3e3a7aSWarner Loshwhen <code>key</code> is not present in <code>table</code>. 6250495ed39SKyle EvansThe metavalue is looked up in the metatable of <code>table</code>. 6268e3e3a7aSWarner Losh 6278e3e3a7aSWarner Losh 6288e3e3a7aSWarner Losh<p> 6290495ed39SKyle EvansThe metavalue for this event can be either a function, a table, 6300495ed39SKyle Evansor any value with an <code>__index</code> metavalue. 6318e3e3a7aSWarner LoshIf it is a function, 6328e3e3a7aSWarner Loshit is called with <code>table</code> and <code>key</code> as arguments, 6338e3e3a7aSWarner Loshand the result of the call 6348e3e3a7aSWarner Losh(adjusted to one value) 6358e3e3a7aSWarner Loshis the result of the operation. 6360495ed39SKyle EvansOtherwise, 6370495ed39SKyle Evansthe final result is the result of indexing this metavalue with <code>key</code>. 6380495ed39SKyle EvansThis indexing is regular, not raw, 6390495ed39SKyle Evansand therefore can trigger another <code>__index</code> metavalue. 6408e3e3a7aSWarner Losh</li> 6418e3e3a7aSWarner Losh 6428e3e3a7aSWarner Losh<li><b><code>__newindex</code>: </b> 6438e3e3a7aSWarner LoshThe indexing assignment <code>table[key] = value</code>. 6448e3e3a7aSWarner LoshLike the index event, 6458e3e3a7aSWarner Loshthis event happens when <code>table</code> is not a table or 6468e3e3a7aSWarner Loshwhen <code>key</code> is not present in <code>table</code>. 6470495ed39SKyle EvansThe metavalue is looked up in the metatable of <code>table</code>. 6488e3e3a7aSWarner Losh 6498e3e3a7aSWarner Losh 6508e3e3a7aSWarner Losh<p> 6518e3e3a7aSWarner LoshLike with indexing, 6520495ed39SKyle Evansthe metavalue for this event can be either a function, a table, 6530495ed39SKyle Evansor any value with an <code>__newindex</code> metavalue. 6548e3e3a7aSWarner LoshIf it is a function, 6558e3e3a7aSWarner Loshit is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments. 6560495ed39SKyle EvansOtherwise, 6570495ed39SKyle EvansLua repeats the indexing assignment over this metavalue 6580495ed39SKyle Evanswith the same key and value. 6590495ed39SKyle EvansThis assignment is regular, not raw, 6600495ed39SKyle Evansand therefore can trigger another <code>__newindex</code> metavalue. 6618e3e3a7aSWarner Losh 6628e3e3a7aSWarner Losh 6638e3e3a7aSWarner Losh<p> 6640495ed39SKyle EvansWhenever a <code>__newindex</code> metavalue is invoked, 6658e3e3a7aSWarner LoshLua does not perform the primitive assignment. 6660495ed39SKyle EvansIf needed, 6678e3e3a7aSWarner Loshthe metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a> 6680495ed39SKyle Evansto do the assignment. 6698e3e3a7aSWarner Losh</li> 6708e3e3a7aSWarner Losh 6718e3e3a7aSWarner Losh<li><b><code>__call</code>: </b> 6728e3e3a7aSWarner LoshThe call operation <code>func(args)</code>. 6738e3e3a7aSWarner LoshThis event happens when Lua tries to call a non-function value 6748e3e3a7aSWarner Losh(that is, <code>func</code> is not a function). 6758e3e3a7aSWarner LoshThe metamethod is looked up in <code>func</code>. 6768e3e3a7aSWarner LoshIf present, 6778e3e3a7aSWarner Loshthe metamethod is called with <code>func</code> as its first argument, 6788e3e3a7aSWarner Loshfollowed by the arguments of the original call (<code>args</code>). 6798e3e3a7aSWarner LoshAll results of the call 6800495ed39SKyle Evansare the results of the operation. 6810495ed39SKyle EvansThis is the only metamethod that allows multiple results. 6828e3e3a7aSWarner Losh</li> 6838e3e3a7aSWarner Losh 6848e3e3a7aSWarner Losh</ul> 6858e3e3a7aSWarner Losh 6868e3e3a7aSWarner Losh<p> 6870495ed39SKyle EvansIn addition to the previous list, 6880495ed39SKyle Evansthe interpreter also respects the following keys in metatables: 6890495ed39SKyle Evans<code>__gc</code> (see <a href="#2.5.3">§2.5.3</a>), 6900495ed39SKyle Evans<code>__close</code> (see <a href="#3.3.8">§3.3.8</a>), 6910495ed39SKyle Evans<code>__mode</code> (see <a href="#2.5.4">§2.5.4</a>), 6920495ed39SKyle Evansand <code>__name</code>. 6930495ed39SKyle Evans(The entry <code>__name</code>, 6940495ed39SKyle Evanswhen it contains a string, 6950495ed39SKyle Evansmay be used by <a href="#pdf-tostring"><code>tostring</code></a> and in error messages.) 6960495ed39SKyle Evans 6970495ed39SKyle Evans 6980495ed39SKyle Evans<p> 6990495ed39SKyle EvansFor the unary operators (negation, length, and bitwise NOT), 7000495ed39SKyle Evansthe metamethod is computed and called with a dummy second operand, 7010495ed39SKyle Evansequal to the first one. 7020495ed39SKyle EvansThis extra operand is only to simplify Lua's internals 7030495ed39SKyle Evans(by making these operators behave like a binary operation) 7040495ed39SKyle Evansand may be removed in future versions. 7050495ed39SKyle EvansFor most uses this extra operand is irrelevant. 7068e3e3a7aSWarner Losh 7078e3e3a7aSWarner Losh 7088e3e3a7aSWarner Losh<p> 7098e3e3a7aSWarner LoshBecause metatables are regular tables, 7108e3e3a7aSWarner Loshthey can contain arbitrary fields, 7118e3e3a7aSWarner Loshnot only the event names defined above. 7128e3e3a7aSWarner LoshSome functions in the standard library 7138e3e3a7aSWarner Losh(e.g., <a href="#pdf-tostring"><code>tostring</code></a>) 7148e3e3a7aSWarner Loshuse other fields in metatables for their own purposes. 7158e3e3a7aSWarner Losh 7168e3e3a7aSWarner Losh 7170495ed39SKyle Evans<p> 7180495ed39SKyle EvansIt is a good practice to add all needed metamethods to a table 7190495ed39SKyle Evansbefore setting it as a metatable of some object. 7200495ed39SKyle EvansIn particular, the <code>__gc</code> metamethod works only when this order 7210495ed39SKyle Evansis followed (see <a href="#2.5.3">§2.5.3</a>). 7220495ed39SKyle EvansIt is also a good practice to set the metatable of an object 7230495ed39SKyle Evansright after its creation. 7240495ed39SKyle Evans 7250495ed39SKyle Evans 7268e3e3a7aSWarner Losh 7278e3e3a7aSWarner Losh 7288e3e3a7aSWarner Losh 7298e3e3a7aSWarner Losh<h2>2.5 – <a name="2.5">Garbage Collection</a></h2> 7308e3e3a7aSWarner Losh 7310495ed39SKyle Evans 7320495ed39SKyle Evans 7338e3e3a7aSWarner Losh<p> 7348e3e3a7aSWarner LoshLua performs automatic memory management. 7358e3e3a7aSWarner LoshThis means that 7368e3e3a7aSWarner Loshyou do not have to worry about allocating memory for new objects 7378e3e3a7aSWarner Loshor freeing it when the objects are no longer needed. 7388e3e3a7aSWarner LoshLua manages memory automatically by running 7390495ed39SKyle Evansa <em>garbage collector</em> to collect all <em>dead</em> objects. 7408e3e3a7aSWarner LoshAll memory used by Lua is subject to automatic management: 7418e3e3a7aSWarner Loshstrings, tables, userdata, functions, threads, internal structures, etc. 7428e3e3a7aSWarner Losh 7438e3e3a7aSWarner Losh 7448e3e3a7aSWarner Losh<p> 7450495ed39SKyle EvansAn object is considered <em>dead</em> 7460495ed39SKyle Evansas soon as the collector can be sure the object 7470495ed39SKyle Evanswill not be accessed again in the normal execution of the program. 7480495ed39SKyle Evans("Normal execution" here excludes finalizers, 7490495ed39SKyle Evanswhich can resurrect dead objects (see <a href="#2.5.3">§2.5.3</a>), 7500495ed39SKyle Evansand excludes also operations using the debug library.) 7510495ed39SKyle EvansNote that the time when the collector can be sure that an object 7520495ed39SKyle Evansis dead may not coincide with the programmer's expectations. 7530495ed39SKyle EvansThe only guarantees are that Lua will not collect an object 7540495ed39SKyle Evansthat may still be accessed in the normal execution of the program, 7550495ed39SKyle Evansand it will eventually collect an object 7560495ed39SKyle Evansthat is inaccessible from Lua. 7570495ed39SKyle Evans(Here, 7580495ed39SKyle Evans<em>inaccessible from Lua</em> means that neither a variable nor 7590495ed39SKyle Evansanother live object refer to the object.) 7600495ed39SKyle EvansBecause Lua has no knowledge about C code, 7610495ed39SKyle Evansit never collects objects accessible through the registry (see <a href="#4.3">§4.3</a>), 7620495ed39SKyle Evanswhich includes the global environment (see <a href="#2.2">§2.2</a>). 7630495ed39SKyle Evans 7640495ed39SKyle Evans 7650495ed39SKyle Evans<p> 7660495ed39SKyle EvansThe garbage collector (GC) in Lua can work in two modes: 7670495ed39SKyle Evansincremental and generational. 7680495ed39SKyle Evans 7690495ed39SKyle Evans 7700495ed39SKyle Evans<p> 7710495ed39SKyle EvansThe default GC mode with the default parameters 7720495ed39SKyle Evansare adequate for most uses. 7730495ed39SKyle EvansHowever, programs that waste a large proportion of their time 7740495ed39SKyle Evansallocating and freeing memory can benefit from other settings. 7750495ed39SKyle EvansKeep in mind that the GC behavior is non-portable 7760495ed39SKyle Evansboth across platforms and across different Lua releases; 7770495ed39SKyle Evanstherefore, optimal settings are also non-portable. 7780495ed39SKyle Evans 7790495ed39SKyle Evans 7800495ed39SKyle Evans<p> 7810495ed39SKyle EvansYou can change the GC mode and parameters by calling 7820495ed39SKyle Evans<a href="#lua_gc"><code>lua_gc</code></a> in C 7830495ed39SKyle Evansor <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. 7840495ed39SKyle EvansYou can also use these functions to control 7850495ed39SKyle Evansthe collector directly (e.g., to stop and restart it). 7860495ed39SKyle Evans 7870495ed39SKyle Evans 7880495ed39SKyle Evans 7890495ed39SKyle Evans 7900495ed39SKyle Evans 7910495ed39SKyle Evans<h3>2.5.1 – <a name="2.5.1">Incremental Garbage Collection</a></h3> 7920495ed39SKyle Evans 7930495ed39SKyle Evans<p> 7940495ed39SKyle EvansIn incremental mode, 7950495ed39SKyle Evanseach GC cycle performs a mark-and-sweep collection in small steps 7960495ed39SKyle Evansinterleaved with the program's execution. 7970495ed39SKyle EvansIn this mode, 7980495ed39SKyle Evansthe collector uses three numbers to control its garbage-collection cycles: 7990495ed39SKyle Evansthe <em>garbage-collector pause</em>, 8000495ed39SKyle Evansthe <em>garbage-collector step multiplier</em>, 8010495ed39SKyle Evansand the <em>garbage-collector step size</em>. 8028e3e3a7aSWarner Losh 8038e3e3a7aSWarner Losh 8048e3e3a7aSWarner Losh<p> 8058e3e3a7aSWarner LoshThe garbage-collector pause 8068e3e3a7aSWarner Loshcontrols how long the collector waits before starting a new cycle. 8070495ed39SKyle EvansThe collector starts a new cycle when the use of memory 8080495ed39SKyle Evanshits <em>n%</em> of the use after the previous collection. 8098e3e3a7aSWarner LoshLarger values make the collector less aggressive. 8100495ed39SKyle EvansValues equal to or less than 100 mean the collector will not wait to 8118e3e3a7aSWarner Loshstart a new cycle. 8128e3e3a7aSWarner LoshA value of 200 means that the collector waits for the total memory in use 8138e3e3a7aSWarner Loshto double before starting a new cycle. 8140495ed39SKyle EvansThe default value is 200; the maximum value is 1000. 8158e3e3a7aSWarner Losh 8168e3e3a7aSWarner Losh 8178e3e3a7aSWarner Losh<p> 8188e3e3a7aSWarner LoshThe garbage-collector step multiplier 8190495ed39SKyle Evanscontrols the speed of the collector relative to 8200495ed39SKyle Evansmemory allocation, 8210495ed39SKyle Evansthat is, 8220495ed39SKyle Evanshow many elements it marks or sweeps for each 8230495ed39SKyle Evanskilobyte of memory allocated. 8248e3e3a7aSWarner LoshLarger values make the collector more aggressive but also increase 8258e3e3a7aSWarner Loshthe size of each incremental step. 8260495ed39SKyle EvansYou should not use values less than 100, 8278e3e3a7aSWarner Loshbecause they make the collector too slow and 8288e3e3a7aSWarner Loshcan result in the collector never finishing a cycle. 8290495ed39SKyle EvansThe default value is 100; the maximum value is 1000. 8308e3e3a7aSWarner Losh 8318e3e3a7aSWarner Losh 8328e3e3a7aSWarner Losh<p> 8330495ed39SKyle EvansThe garbage-collector step size controls the 8340495ed39SKyle Evanssize of each incremental step, 8350495ed39SKyle Evansspecifically how many bytes the interpreter allocates 8360495ed39SKyle Evansbefore performing a step. 8370495ed39SKyle EvansThis parameter is logarithmic: 8380495ed39SKyle EvansA value of <em>n</em> means the interpreter will allocate <em>2<sup>n</sup></em> 8390495ed39SKyle Evansbytes between steps and perform equivalent work during the step. 8400495ed39SKyle EvansA large value (e.g., 60) makes the collector a stop-the-world 8410495ed39SKyle Evans(non-incremental) collector. 8420495ed39SKyle EvansThe default value is 13, 8430495ed39SKyle Evanswhich means steps of approximately 8 Kbytes. 8440495ed39SKyle Evans 8450495ed39SKyle Evans 8460495ed39SKyle Evans 8470495ed39SKyle Evans 8480495ed39SKyle Evans 8490495ed39SKyle Evans<h3>2.5.2 – <a name="2.5.2">Generational Garbage Collection</a></h3> 8500495ed39SKyle Evans 8510495ed39SKyle Evans<p> 8520495ed39SKyle EvansIn generational mode, 8530495ed39SKyle Evansthe collector does frequent <em>minor</em> collections, 8540495ed39SKyle Evanswhich traverses only objects recently created. 8550495ed39SKyle EvansIf after a minor collection the use of memory is still above a limit, 8560495ed39SKyle Evansthe collector does a stop-the-world <em>major</em> collection, 8570495ed39SKyle Evanswhich traverses all objects. 8580495ed39SKyle EvansThe generational mode uses two parameters: 8590495ed39SKyle Evansthe <em>minor multiplier</em> and the <em>the major multiplier</em>. 8608e3e3a7aSWarner Losh 8618e3e3a7aSWarner Losh 8628e3e3a7aSWarner Losh<p> 8630495ed39SKyle EvansThe minor multiplier controls the frequency of minor collections. 8640495ed39SKyle EvansFor a minor multiplier <em>x</em>, 8650495ed39SKyle Evansa new minor collection will be done when memory 8660495ed39SKyle Evansgrows <em>x%</em> larger than the memory in use after the previous major 8670495ed39SKyle Evanscollection. 8680495ed39SKyle EvansFor instance, for a multiplier of 20, 8690495ed39SKyle Evansthe collector will do a minor collection when the use of memory 8700495ed39SKyle Evansgets 20% larger than the use after the previous major collection. 8710495ed39SKyle EvansThe default value is 20; the maximum value is 200. 8720495ed39SKyle Evans 8730495ed39SKyle Evans 8740495ed39SKyle Evans<p> 8750495ed39SKyle EvansThe major multiplier controls the frequency of major collections. 8760495ed39SKyle EvansFor a major multiplier <em>x</em>, 8770495ed39SKyle Evansa new major collection will be done when memory 8780495ed39SKyle Evansgrows <em>x%</em> larger than the memory in use after the previous major 8790495ed39SKyle Evanscollection. 8800495ed39SKyle EvansFor instance, for a multiplier of 100, 8810495ed39SKyle Evansthe collector will do a major collection when the use of memory 8820495ed39SKyle Evansgets larger than twice the use after the previous collection. 8830495ed39SKyle EvansThe default value is 100; the maximum value is 1000. 8848e3e3a7aSWarner Losh 8858e3e3a7aSWarner Losh 8868e3e3a7aSWarner Losh 8870495ed39SKyle Evans 8880495ed39SKyle Evans 8890495ed39SKyle Evans<h3>2.5.3 – <a name="2.5.3">Garbage-Collection Metamethods</a></h3> 8908e3e3a7aSWarner Losh 8918e3e3a7aSWarner Losh<p> 8928e3e3a7aSWarner LoshYou can set garbage-collector metamethods for tables 8938e3e3a7aSWarner Loshand, using the C API, 8948e3e3a7aSWarner Loshfor full userdata (see <a href="#2.4">§2.4</a>). 8950495ed39SKyle EvansThese metamethods, called <em>finalizers</em>, 8960495ed39SKyle Evansare called when the garbage collector detects that the 8970495ed39SKyle Evanscorresponding table or userdata is dead. 8988e3e3a7aSWarner LoshFinalizers allow you to coordinate Lua's garbage collection 8990495ed39SKyle Evanswith external resource management such as closing files, 9000495ed39SKyle Evansnetwork or database connections, 9010495ed39SKyle Evansor freeing your own memory. 9028e3e3a7aSWarner Losh 9038e3e3a7aSWarner Losh 9048e3e3a7aSWarner Losh<p> 9058e3e3a7aSWarner LoshFor an object (table or userdata) to be finalized when collected, 9068e3e3a7aSWarner Loshyou must <em>mark</em> it for finalization. 9078e3e3a7aSWarner Losh 9088e3e3a7aSWarner LoshYou mark an object for finalization when you set its metatable 9098c784bb8SWarner Loshand the metatable has a <code>__gc</code> metamethod. 9108e3e3a7aSWarner LoshNote that if you set a metatable without a <code>__gc</code> field 9118e3e3a7aSWarner Loshand later create that field in the metatable, 9128e3e3a7aSWarner Loshthe object will not be marked for finalization. 9138e3e3a7aSWarner Losh 9148e3e3a7aSWarner Losh 9158e3e3a7aSWarner Losh<p> 9160495ed39SKyle EvansWhen a marked object becomes dead, 9178e3e3a7aSWarner Loshit is not collected immediately by the garbage collector. 9188e3e3a7aSWarner LoshInstead, Lua puts it in a list. 9198e3e3a7aSWarner LoshAfter the collection, 9208e3e3a7aSWarner LoshLua goes through that list. 9218e3e3a7aSWarner LoshFor each object in the list, 9228e3e3a7aSWarner Loshit checks the object's <code>__gc</code> metamethod: 9230495ed39SKyle EvansIf it is present, 9240495ed39SKyle EvansLua calls it with the object as its single argument. 9258e3e3a7aSWarner Losh 9268e3e3a7aSWarner Losh 9278e3e3a7aSWarner Losh<p> 9288e3e3a7aSWarner LoshAt the end of each garbage-collection cycle, 9290495ed39SKyle Evansthe finalizers are called in 9308e3e3a7aSWarner Loshthe reverse order that the objects were marked for finalization, 9318e3e3a7aSWarner Loshamong those collected in that cycle; 9328e3e3a7aSWarner Loshthat is, the first finalizer to be called is the one associated 9338e3e3a7aSWarner Loshwith the object marked last in the program. 9348e3e3a7aSWarner LoshThe execution of each finalizer may occur at any point during 9358e3e3a7aSWarner Loshthe execution of the regular code. 9368e3e3a7aSWarner Losh 9378e3e3a7aSWarner Losh 9388e3e3a7aSWarner Losh<p> 9398e3e3a7aSWarner LoshBecause the object being collected must still be used by the finalizer, 9408e3e3a7aSWarner Loshthat object (and other objects accessible only through it) 9418e3e3a7aSWarner Loshmust be <em>resurrected</em> by Lua. 9428e3e3a7aSWarner LoshUsually, this resurrection is transient, 9438e3e3a7aSWarner Loshand the object memory is freed in the next garbage-collection cycle. 9448e3e3a7aSWarner LoshHowever, if the finalizer stores the object in some global place 9458e3e3a7aSWarner Losh(e.g., a global variable), 9468e3e3a7aSWarner Loshthen the resurrection is permanent. 9478e3e3a7aSWarner LoshMoreover, if the finalizer marks a finalizing object for finalization again, 9488e3e3a7aSWarner Loshits finalizer will be called again in the next cycle where the 9490495ed39SKyle Evansobject is dead. 9508e3e3a7aSWarner LoshIn any case, 9518e3e3a7aSWarner Loshthe object memory is freed only in a GC cycle where 9520495ed39SKyle Evansthe object is dead and not marked for finalization. 9538e3e3a7aSWarner Losh 9548e3e3a7aSWarner Losh 9558e3e3a7aSWarner Losh<p> 9568e3e3a7aSWarner LoshWhen you close a state (see <a href="#lua_close"><code>lua_close</code></a>), 9578e3e3a7aSWarner LoshLua calls the finalizers of all objects marked for finalization, 9588e3e3a7aSWarner Loshfollowing the reverse order that they were marked. 9598e3e3a7aSWarner LoshIf any finalizer marks objects for collection during that phase, 9608e3e3a7aSWarner Loshthese marks have no effect. 9618e3e3a7aSWarner Losh 9628e3e3a7aSWarner Losh 9630495ed39SKyle Evans<p> 9648c784bb8SWarner LoshFinalizers cannot yield nor run the garbage collector. 9658c784bb8SWarner LoshBecause they can run in unpredictable times, 9660495ed39SKyle Evansit is good practice to restrict each finalizer 9670495ed39SKyle Evansto the minimum necessary to properly release 9680495ed39SKyle Evansits associated resource. 9690495ed39SKyle Evans 9700495ed39SKyle Evans 9710495ed39SKyle Evans<p> 9720495ed39SKyle EvansAny error while running a finalizer generates a warning; 9730495ed39SKyle Evansthe error is not propagated. 9748e3e3a7aSWarner Losh 9758e3e3a7aSWarner Losh 9768e3e3a7aSWarner Losh 9770495ed39SKyle Evans 9780495ed39SKyle Evans 9790495ed39SKyle Evans<h3>2.5.4 – <a name="2.5.4">Weak Tables</a></h3> 9808e3e3a7aSWarner Losh 9818e3e3a7aSWarner Losh<p> 9828e3e3a7aSWarner LoshA <em>weak table</em> is a table whose elements are 9838e3e3a7aSWarner Losh<em>weak references</em>. 9848e3e3a7aSWarner LoshA weak reference is ignored by the garbage collector. 9858e3e3a7aSWarner LoshIn other words, 9868e3e3a7aSWarner Loshif the only references to an object are weak references, 9878e3e3a7aSWarner Loshthen the garbage collector will collect that object. 9888e3e3a7aSWarner Losh 9898e3e3a7aSWarner Losh 9908e3e3a7aSWarner Losh<p> 9918e3e3a7aSWarner LoshA weak table can have weak keys, weak values, or both. 9928e3e3a7aSWarner LoshA table with weak values allows the collection of its values, 9938e3e3a7aSWarner Loshbut prevents the collection of its keys. 9948e3e3a7aSWarner LoshA table with both weak keys and weak values allows the collection of 9958e3e3a7aSWarner Loshboth keys and values. 9968e3e3a7aSWarner LoshIn any case, if either the key or the value is collected, 9978e3e3a7aSWarner Loshthe whole pair is removed from the table. 9988e3e3a7aSWarner LoshThe weakness of a table is controlled by the 9998e3e3a7aSWarner Losh<code>__mode</code> field of its metatable. 10000495ed39SKyle EvansThis metavalue, if present, must be one of the following strings: 10010495ed39SKyle Evans"<code>k</code>", for a table with weak keys; 10020495ed39SKyle Evans"<code>v</code>", for a table with weak values; 10030495ed39SKyle Evansor "<code>kv</code>", for a table with both weak keys and values. 10048e3e3a7aSWarner Losh 10058e3e3a7aSWarner Losh 10068e3e3a7aSWarner Losh<p> 10078e3e3a7aSWarner LoshA table with weak keys and strong values 10088e3e3a7aSWarner Loshis also called an <em>ephemeron table</em>. 10098e3e3a7aSWarner LoshIn an ephemeron table, 10108e3e3a7aSWarner Losha value is considered reachable only if its key is reachable. 10118e3e3a7aSWarner LoshIn particular, 10128e3e3a7aSWarner Loshif the only reference to a key comes through its value, 10138e3e3a7aSWarner Loshthe pair is removed. 10148e3e3a7aSWarner Losh 10158e3e3a7aSWarner Losh 10168e3e3a7aSWarner Losh<p> 10178e3e3a7aSWarner LoshAny change in the weakness of a table may take effect only 10188e3e3a7aSWarner Loshat the next collect cycle. 10198e3e3a7aSWarner LoshIn particular, if you change the weakness to a stronger mode, 10208e3e3a7aSWarner LoshLua may still collect some items from that table 10218e3e3a7aSWarner Loshbefore the change takes effect. 10228e3e3a7aSWarner Losh 10238e3e3a7aSWarner Losh 10248e3e3a7aSWarner Losh<p> 10258e3e3a7aSWarner LoshOnly objects that have an explicit construction 10268e3e3a7aSWarner Loshare removed from weak tables. 10278e3e3a7aSWarner LoshValues, such as numbers and light C functions, 10288e3e3a7aSWarner Loshare not subject to garbage collection, 10298e3e3a7aSWarner Loshand therefore are not removed from weak tables 10308e3e3a7aSWarner Losh(unless their associated values are collected). 10318e3e3a7aSWarner LoshAlthough strings are subject to garbage collection, 10320495ed39SKyle Evansthey do not have an explicit construction and 10330495ed39SKyle Evanstheir equality is by value; 10340495ed39SKyle Evansthey behave more like values than like objects. 10350495ed39SKyle EvansTherefore, they are not removed from weak tables. 10368e3e3a7aSWarner Losh 10378e3e3a7aSWarner Losh 10388e3e3a7aSWarner Losh<p> 10398e3e3a7aSWarner LoshResurrected objects 10408e3e3a7aSWarner Losh(that is, objects being finalized 10418e3e3a7aSWarner Loshand objects accessible only through objects being finalized) 10428e3e3a7aSWarner Loshhave a special behavior in weak tables. 10438e3e3a7aSWarner LoshThey are removed from weak values before running their finalizers, 10448e3e3a7aSWarner Loshbut are removed from weak keys only in the next collection 10458e3e3a7aSWarner Loshafter running their finalizers, when such objects are actually freed. 10468e3e3a7aSWarner LoshThis behavior allows the finalizer to access properties 10478e3e3a7aSWarner Loshassociated with the object through weak tables. 10488e3e3a7aSWarner Losh 10498e3e3a7aSWarner Losh 10508e3e3a7aSWarner Losh<p> 10518e3e3a7aSWarner LoshIf a weak table is among the resurrected objects in a collection cycle, 10528e3e3a7aSWarner Loshit may not be properly cleared until the next cycle. 10538e3e3a7aSWarner Losh 10548e3e3a7aSWarner Losh 10558e3e3a7aSWarner Losh 10568e3e3a7aSWarner Losh 10578e3e3a7aSWarner Losh 10588e3e3a7aSWarner Losh 10598e3e3a7aSWarner Losh 10608e3e3a7aSWarner Losh<h2>2.6 – <a name="2.6">Coroutines</a></h2> 10618e3e3a7aSWarner Losh 10628e3e3a7aSWarner Losh<p> 10638e3e3a7aSWarner LoshLua supports coroutines, 10648e3e3a7aSWarner Loshalso called <em>collaborative multithreading</em>. 10658e3e3a7aSWarner LoshA coroutine in Lua represents an independent thread of execution. 10668e3e3a7aSWarner LoshUnlike threads in multithread systems, however, 10678e3e3a7aSWarner Losha coroutine only suspends its execution by explicitly calling 10688e3e3a7aSWarner Losha yield function. 10698e3e3a7aSWarner Losh 10708e3e3a7aSWarner Losh 10718e3e3a7aSWarner Losh<p> 10728e3e3a7aSWarner LoshYou create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>. 10738e3e3a7aSWarner LoshIts sole argument is a function 10748e3e3a7aSWarner Loshthat is the main function of the coroutine. 10758e3e3a7aSWarner LoshThe <code>create</code> function only creates a new coroutine and 10768e3e3a7aSWarner Loshreturns a handle to it (an object of type <em>thread</em>); 10778e3e3a7aSWarner Loshit does not start the coroutine. 10788e3e3a7aSWarner Losh 10798e3e3a7aSWarner Losh 10808e3e3a7aSWarner Losh<p> 10818e3e3a7aSWarner LoshYou execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 10828e3e3a7aSWarner LoshWhen you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 10838e3e3a7aSWarner Loshpassing as its first argument 10848e3e3a7aSWarner Losha thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 10858e3e3a7aSWarner Loshthe coroutine starts its execution by 10868e3e3a7aSWarner Loshcalling its main function. 10878e3e3a7aSWarner LoshExtra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed 10888e3e3a7aSWarner Loshas arguments to that function. 10898e3e3a7aSWarner LoshAfter the coroutine starts running, 10908e3e3a7aSWarner Loshit runs until it terminates or <em>yields</em>. 10918e3e3a7aSWarner Losh 10928e3e3a7aSWarner Losh 10938e3e3a7aSWarner Losh<p> 10948e3e3a7aSWarner LoshA coroutine can terminate its execution in two ways: 10958e3e3a7aSWarner Loshnormally, when its main function returns 10968e3e3a7aSWarner Losh(explicitly or implicitly, after the last instruction); 10978e3e3a7aSWarner Loshand abnormally, if there is an unprotected error. 10988e3e3a7aSWarner LoshIn case of normal termination, 10998e3e3a7aSWarner Losh<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>, 11008e3e3a7aSWarner Loshplus any values returned by the coroutine main function. 11018e3e3a7aSWarner LoshIn case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b> 11020495ed39SKyle Evansplus the error object. 11030495ed39SKyle EvansIn this case, the coroutine does not unwind its stack, 11040495ed39SKyle Evansso that it is possible to inspect it after the error 11050495ed39SKyle Evanswith the debug API. 11068e3e3a7aSWarner Losh 11078e3e3a7aSWarner Losh 11088e3e3a7aSWarner Losh<p> 11098e3e3a7aSWarner LoshA coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 11108e3e3a7aSWarner LoshWhen a coroutine yields, 11118e3e3a7aSWarner Loshthe corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately, 11128e3e3a7aSWarner Losheven if the yield happens inside nested function calls 11138e3e3a7aSWarner Losh(that is, not in the main function, 11148e3e3a7aSWarner Loshbut in a function directly or indirectly called by the main function). 11158e3e3a7aSWarner LoshIn the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>, 11168e3e3a7aSWarner Loshplus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 11178e3e3a7aSWarner LoshThe next time you resume the same coroutine, 11188e3e3a7aSWarner Loshit continues its execution from the point where it yielded, 11198e3e3a7aSWarner Loshwith the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra 11208e3e3a7aSWarner Losharguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 11218e3e3a7aSWarner Losh 11228e3e3a7aSWarner Losh 11238e3e3a7aSWarner Losh<p> 11248e3e3a7aSWarner LoshLike <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 11258e3e3a7aSWarner Loshthe <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine, 11268e3e3a7aSWarner Loshbut instead of returning the coroutine itself, 11278e3e3a7aSWarner Loshit returns a function that, when called, resumes the coroutine. 11288e3e3a7aSWarner LoshAny arguments passed to this function 11298e3e3a7aSWarner Loshgo as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 11308e3e3a7aSWarner 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>, 11318e3e3a7aSWarner Loshexcept the first one (the boolean error code). 11328e3e3a7aSWarner LoshUnlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 11330495ed39SKyle Evansthe function created by <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> 11340495ed39SKyle Evanspropagates any error to the caller. 11350495ed39SKyle EvansIn this case, 11360495ed39SKyle Evansthe function also closes the coroutine (see <a href="#pdf-coroutine.close"><code>coroutine.close</code></a>). 11378e3e3a7aSWarner Losh 11388e3e3a7aSWarner Losh 11398e3e3a7aSWarner Losh<p> 11408e3e3a7aSWarner LoshAs an example of how coroutines work, 11418e3e3a7aSWarner Loshconsider the following code: 11428e3e3a7aSWarner Losh 11438e3e3a7aSWarner Losh<pre> 11448e3e3a7aSWarner Losh function foo (a) 11458e3e3a7aSWarner Losh print("foo", a) 11468e3e3a7aSWarner Losh return coroutine.yield(2*a) 11478e3e3a7aSWarner Losh end 11488e3e3a7aSWarner Losh 11498e3e3a7aSWarner Losh co = coroutine.create(function (a,b) 11508e3e3a7aSWarner Losh print("co-body", a, b) 11518e3e3a7aSWarner Losh local r = foo(a+1) 11528e3e3a7aSWarner Losh print("co-body", r) 11538e3e3a7aSWarner Losh local r, s = coroutine.yield(a+b, a-b) 11548e3e3a7aSWarner Losh print("co-body", r, s) 11558e3e3a7aSWarner Losh return b, "end" 11568e3e3a7aSWarner Losh end) 11578e3e3a7aSWarner Losh 11588e3e3a7aSWarner Losh print("main", coroutine.resume(co, 1, 10)) 11598e3e3a7aSWarner Losh print("main", coroutine.resume(co, "r")) 11608e3e3a7aSWarner Losh print("main", coroutine.resume(co, "x", "y")) 11618e3e3a7aSWarner Losh print("main", coroutine.resume(co, "x", "y")) 11628e3e3a7aSWarner Losh</pre><p> 11638e3e3a7aSWarner LoshWhen you run it, it produces the following output: 11648e3e3a7aSWarner Losh 11658e3e3a7aSWarner Losh<pre> 11668e3e3a7aSWarner Losh co-body 1 10 11678e3e3a7aSWarner Losh foo 2 11688e3e3a7aSWarner Losh main true 4 11698e3e3a7aSWarner Losh co-body r 11708e3e3a7aSWarner Losh main true 11 -9 11718e3e3a7aSWarner Losh co-body x y 11728e3e3a7aSWarner Losh main true 10 end 11738e3e3a7aSWarner Losh main false cannot resume dead coroutine 11748e3e3a7aSWarner Losh</pre> 11758e3e3a7aSWarner Losh 11768e3e3a7aSWarner Losh<p> 11778e3e3a7aSWarner LoshYou can also create and manipulate coroutines through the C API: 11788e3e3a7aSWarner Loshsee functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>, 11798e3e3a7aSWarner Loshand <a href="#lua_yield"><code>lua_yield</code></a>. 11808e3e3a7aSWarner Losh 11818e3e3a7aSWarner Losh 11828e3e3a7aSWarner Losh 11838e3e3a7aSWarner Losh 11848e3e3a7aSWarner Losh 11858e3e3a7aSWarner Losh<h1>3 – <a name="3">The Language</a></h1> 11868e3e3a7aSWarner Losh 11870495ed39SKyle Evans 11880495ed39SKyle Evans 11898e3e3a7aSWarner Losh<p> 11908e3e3a7aSWarner LoshThis section describes the lexis, the syntax, and the semantics of Lua. 11918e3e3a7aSWarner LoshIn other words, 11928e3e3a7aSWarner Loshthis section describes 11938e3e3a7aSWarner Loshwhich tokens are valid, 11948e3e3a7aSWarner Loshhow they can be combined, 11958e3e3a7aSWarner Loshand what their combinations mean. 11968e3e3a7aSWarner Losh 11978e3e3a7aSWarner Losh 11988e3e3a7aSWarner Losh<p> 11998e3e3a7aSWarner LoshLanguage constructs will be explained using the usual extended BNF notation, 12008e3e3a7aSWarner Loshin which 12018e3e3a7aSWarner Losh{<em>a</em>} means 0 or more <em>a</em>'s, and 12028e3e3a7aSWarner Losh[<em>a</em>] means an optional <em>a</em>. 12038e3e3a7aSWarner LoshNon-terminals are shown like non-terminal, 12048e3e3a7aSWarner Loshkeywords are shown like <b>kword</b>, 12058e3e3a7aSWarner Loshand other terminal symbols are shown like ‘<b>=</b>’. 12068e3e3a7aSWarner LoshThe complete syntax of Lua can be found in <a href="#9">§9</a> 12078e3e3a7aSWarner Loshat the end of this manual. 12088e3e3a7aSWarner Losh 12098e3e3a7aSWarner Losh 12108e3e3a7aSWarner Losh 12110495ed39SKyle Evans 12120495ed39SKyle Evans 12138e3e3a7aSWarner Losh<h2>3.1 – <a name="3.1">Lexical Conventions</a></h2> 12148e3e3a7aSWarner Losh 12158e3e3a7aSWarner Losh<p> 12168e3e3a7aSWarner LoshLua is a free-form language. 12170495ed39SKyle EvansIt ignores spaces and comments between lexical elements (tokens), 12180495ed39SKyle Evansexcept as delimiters between two tokens. 12190495ed39SKyle EvansIn source code, 12200495ed39SKyle EvansLua recognizes as spaces the standard ASCII whitespace 12210495ed39SKyle Evanscharacters space, form feed, newline, 12220495ed39SKyle Evanscarriage return, horizontal tab, and vertical tab. 12238e3e3a7aSWarner Losh 12248e3e3a7aSWarner Losh 12258e3e3a7aSWarner Losh<p> 12268e3e3a7aSWarner Losh<em>Names</em> 12278e3e3a7aSWarner Losh(also called <em>identifiers</em>) 12280495ed39SKyle Evansin Lua can be any string of Latin letters, 12290495ed39SKyle EvansArabic-Indic digits, and underscores, 12308e3e3a7aSWarner Loshnot beginning with a digit and 12318e3e3a7aSWarner Loshnot being a reserved word. 12328e3e3a7aSWarner LoshIdentifiers are used to name variables, table fields, and labels. 12338e3e3a7aSWarner Losh 12348e3e3a7aSWarner Losh 12358e3e3a7aSWarner Losh<p> 12368e3e3a7aSWarner LoshThe following <em>keywords</em> are reserved 12378e3e3a7aSWarner Loshand cannot be used as names: 12388e3e3a7aSWarner Losh 12398e3e3a7aSWarner Losh 12408e3e3a7aSWarner Losh<pre> 12418e3e3a7aSWarner Losh and break do else elseif end 12428e3e3a7aSWarner Losh false for function goto if in 12438e3e3a7aSWarner Losh local nil not or repeat return 12448e3e3a7aSWarner Losh then true until while 12458e3e3a7aSWarner Losh</pre> 12468e3e3a7aSWarner Losh 12478e3e3a7aSWarner Losh<p> 12488e3e3a7aSWarner LoshLua is a case-sensitive language: 12498e3e3a7aSWarner Losh<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> 12508e3e3a7aSWarner Loshare two different, valid names. 12518e3e3a7aSWarner LoshAs a convention, 12528e3e3a7aSWarner Loshprograms should avoid creating 12538e3e3a7aSWarner Loshnames that start with an underscore followed by 12548e3e3a7aSWarner Loshone or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>). 12558e3e3a7aSWarner Losh 12568e3e3a7aSWarner Losh 12578e3e3a7aSWarner Losh<p> 12588e3e3a7aSWarner LoshThe following strings denote other tokens: 12598e3e3a7aSWarner Losh 12608e3e3a7aSWarner Losh<pre> 12618e3e3a7aSWarner Losh + - * / % ^ # 12628e3e3a7aSWarner Losh & ~ | << >> // 12638e3e3a7aSWarner Losh == ~= <= >= < > = 12648e3e3a7aSWarner Losh ( ) { } [ ] :: 12658e3e3a7aSWarner Losh ; : , . .. ... 12668e3e3a7aSWarner Losh</pre> 12678e3e3a7aSWarner Losh 12688e3e3a7aSWarner Losh<p> 12698e3e3a7aSWarner LoshA <em>short literal string</em> 12708e3e3a7aSWarner Loshcan be delimited by matching single or double quotes, 12718e3e3a7aSWarner Loshand can contain the following C-like escape sequences: 12728e3e3a7aSWarner Losh'<code>\a</code>' (bell), 12738e3e3a7aSWarner Losh'<code>\b</code>' (backspace), 12748e3e3a7aSWarner Losh'<code>\f</code>' (form feed), 12758e3e3a7aSWarner Losh'<code>\n</code>' (newline), 12768e3e3a7aSWarner Losh'<code>\r</code>' (carriage return), 12778e3e3a7aSWarner Losh'<code>\t</code>' (horizontal tab), 12788e3e3a7aSWarner Losh'<code>\v</code>' (vertical tab), 12798e3e3a7aSWarner Losh'<code>\\</code>' (backslash), 12808e3e3a7aSWarner Losh'<code>\"</code>' (quotation mark [double quote]), 12818e3e3a7aSWarner Loshand '<code>\'</code>' (apostrophe [single quote]). 12828e3e3a7aSWarner LoshA backslash followed by a line break 12838e3e3a7aSWarner Loshresults in a newline in the string. 12848e3e3a7aSWarner LoshThe escape sequence '<code>\z</code>' skips the following span 12850495ed39SKyle Evansof whitespace characters, 12868e3e3a7aSWarner Loshincluding line breaks; 12878e3e3a7aSWarner Loshit is particularly useful to break and indent a long literal string 12888e3e3a7aSWarner Loshinto multiple lines without adding the newlines and spaces 12898e3e3a7aSWarner Loshinto the string contents. 12908e3e3a7aSWarner LoshA short literal string cannot contain unescaped line breaks 12918e3e3a7aSWarner Loshnor escapes not forming a valid escape sequence. 12928e3e3a7aSWarner Losh 12938e3e3a7aSWarner Losh 12948e3e3a7aSWarner Losh<p> 12950495ed39SKyle EvansWe can specify any byte in a short literal string, 12960495ed39SKyle Evansincluding embedded zeros, 12970495ed39SKyle Evansby its numeric value. 12988e3e3a7aSWarner LoshThis can be done 12998e3e3a7aSWarner Loshwith the escape sequence <code>\x<em>XX</em></code>, 13008e3e3a7aSWarner Loshwhere <em>XX</em> is a sequence of exactly two hexadecimal digits, 13018e3e3a7aSWarner Loshor with the escape sequence <code>\<em>ddd</em></code>, 13028e3e3a7aSWarner Loshwhere <em>ddd</em> is a sequence of up to three decimal digits. 13038e3e3a7aSWarner Losh(Note that if a decimal escape sequence is to be followed by a digit, 13048e3e3a7aSWarner Loshit must be expressed using exactly three digits.) 13058e3e3a7aSWarner Losh 13068e3e3a7aSWarner Losh 13078e3e3a7aSWarner Losh<p> 13088e3e3a7aSWarner LoshThe UTF-8 encoding of a Unicode character 13098e3e3a7aSWarner Loshcan be inserted in a literal string with 13108e3e3a7aSWarner Loshthe escape sequence <code>\u{<em>XXX</em>}</code> 13110495ed39SKyle Evans(with mandatory enclosing braces), 13128e3e3a7aSWarner Loshwhere <em>XXX</em> is a sequence of one or more hexadecimal digits 13138e3e3a7aSWarner Loshrepresenting the character code point. 13140495ed39SKyle EvansThis code point can be any value less than <em>2<sup>31</sup></em>. 13150495ed39SKyle Evans(Lua uses the original UTF-8 specification here, 13160495ed39SKyle Evanswhich is not restricted to valid Unicode code points.) 13178e3e3a7aSWarner Losh 13188e3e3a7aSWarner Losh 13198e3e3a7aSWarner Losh<p> 13208e3e3a7aSWarner LoshLiteral strings can also be defined using a long format 13218e3e3a7aSWarner Loshenclosed by <em>long brackets</em>. 13228e3e3a7aSWarner LoshWe define an <em>opening long bracket of level <em>n</em></em> as an opening 13238e3e3a7aSWarner Loshsquare bracket followed by <em>n</em> equal signs followed by another 13248e3e3a7aSWarner Loshopening square bracket. 13258e3e3a7aSWarner LoshSo, an opening long bracket of level 0 is written as <code>[[</code>, 13268e3e3a7aSWarner Loshan opening long bracket of level 1 is written as <code>[=[</code>, 13278e3e3a7aSWarner Loshand so on. 13288e3e3a7aSWarner LoshA <em>closing long bracket</em> is defined similarly; 13298e3e3a7aSWarner Loshfor instance, 13308e3e3a7aSWarner Losha closing long bracket of level 4 is written as <code>]====]</code>. 13318e3e3a7aSWarner LoshA <em>long literal</em> starts with an opening long bracket of any level and 13328e3e3a7aSWarner Loshends at the first closing long bracket of the same level. 13338e3e3a7aSWarner LoshIt can contain any text except a closing bracket of the same level. 13348e3e3a7aSWarner LoshLiterals in this bracketed form can run for several lines, 13358e3e3a7aSWarner Loshdo not interpret any escape sequences, 13368e3e3a7aSWarner Loshand ignore long brackets of any other level. 13378e3e3a7aSWarner LoshAny kind of end-of-line sequence 13388e3e3a7aSWarner Losh(carriage return, newline, carriage return followed by newline, 13398e3e3a7aSWarner Loshor newline followed by carriage return) 13408e3e3a7aSWarner Loshis converted to a simple newline. 13410495ed39SKyle EvansWhen the opening long bracket is immediately followed by a newline, 13420495ed39SKyle Evansthe newline is not included in the string. 13438e3e3a7aSWarner Losh 13448e3e3a7aSWarner Losh 13458e3e3a7aSWarner Losh<p> 13468e3e3a7aSWarner LoshAs an example, in a system using ASCII 13478e3e3a7aSWarner Losh(in which '<code>a</code>' is coded as 97, 13488e3e3a7aSWarner Loshnewline is coded as 10, and '<code>1</code>' is coded as 49), 13498e3e3a7aSWarner Loshthe five literal strings below denote the same string: 13508e3e3a7aSWarner Losh 13518e3e3a7aSWarner Losh<pre> 13528e3e3a7aSWarner Losh a = 'alo\n123"' 13538e3e3a7aSWarner Losh a = "alo\n123\"" 13548e3e3a7aSWarner Losh a = '\97lo\10\04923"' 13558e3e3a7aSWarner Losh a = [[alo 13568e3e3a7aSWarner Losh 123"]] 13578e3e3a7aSWarner Losh a = [==[ 13588e3e3a7aSWarner Losh alo 13598e3e3a7aSWarner Losh 123"]==] 13608e3e3a7aSWarner Losh</pre> 13618e3e3a7aSWarner Losh 13628e3e3a7aSWarner Losh<p> 13638e3e3a7aSWarner LoshAny byte in a literal string not 13648e3e3a7aSWarner Loshexplicitly affected by the previous rules represents itself. 13658e3e3a7aSWarner LoshHowever, Lua opens files for parsing in text mode, 13660495ed39SKyle Evansand the system's file functions may have problems with 13678e3e3a7aSWarner Loshsome control characters. 13688e3e3a7aSWarner LoshSo, it is safer to represent 13690495ed39SKyle Evansbinary data as a quoted literal with 13708e3e3a7aSWarner Loshexplicit escape sequences for the non-text characters. 13718e3e3a7aSWarner Losh 13728e3e3a7aSWarner Losh 13738e3e3a7aSWarner Losh<p> 13748e3e3a7aSWarner LoshA <em>numeric constant</em> (or <em>numeral</em>) 13758e3e3a7aSWarner Loshcan be written with an optional fractional part 13768e3e3a7aSWarner Loshand an optional decimal exponent, 13778e3e3a7aSWarner Loshmarked by a letter '<code>e</code>' or '<code>E</code>'. 13788e3e3a7aSWarner LoshLua also accepts hexadecimal constants, 13798e3e3a7aSWarner Loshwhich start with <code>0x</code> or <code>0X</code>. 13808e3e3a7aSWarner LoshHexadecimal constants also accept an optional fractional part 13818e3e3a7aSWarner Loshplus an optional binary exponent, 1382*a9490b81SWarner Loshmarked by a letter '<code>p</code>' or '<code>P</code>' and written in decimal. 1383*a9490b81SWarner Losh(For instance, <code>0x1.fp10</code> denotes 1984, 1384*a9490b81SWarner Loshwhich is <em>0x1f / 16</em> multiplied by <em>2<sup>10</sup></em>.) 13850495ed39SKyle Evans 13860495ed39SKyle Evans 13870495ed39SKyle Evans<p> 13888e3e3a7aSWarner LoshA numeric constant with a radix point or an exponent 13898e3e3a7aSWarner Loshdenotes a float; 13908e3e3a7aSWarner Loshotherwise, 13910495ed39SKyle Evansif its value fits in an integer or it is a hexadecimal constant, 13920495ed39SKyle Evansit denotes an integer; 13930495ed39SKyle Evansotherwise (that is, a decimal integer numeral that overflows), 13940495ed39SKyle Evansit denotes a float. 13950495ed39SKyle EvansHexadecimal numerals with neither a radix point nor an exponent 13960495ed39SKyle Evansalways denote an integer value; 13970495ed39SKyle Evansif the value overflows, it <em>wraps around</em> 13980495ed39SKyle Evansto fit into a valid integer. 13990495ed39SKyle Evans 14000495ed39SKyle Evans 14010495ed39SKyle Evans<p> 14028e3e3a7aSWarner LoshExamples of valid integer constants are 14038e3e3a7aSWarner Losh 14048e3e3a7aSWarner Losh<pre> 14058e3e3a7aSWarner Losh 3 345 0xff 0xBEBADA 14068e3e3a7aSWarner Losh</pre><p> 14078e3e3a7aSWarner LoshExamples of valid float constants are 14088e3e3a7aSWarner Losh 14098e3e3a7aSWarner Losh<pre> 14108e3e3a7aSWarner Losh 3.0 3.1416 314.16e-2 0.31416E1 34e1 14118e3e3a7aSWarner Losh 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 14128e3e3a7aSWarner Losh</pre> 14138e3e3a7aSWarner Losh 14148e3e3a7aSWarner Losh<p> 14158e3e3a7aSWarner LoshA <em>comment</em> starts with a double hyphen (<code>--</code>) 14168e3e3a7aSWarner Loshanywhere outside a string. 14178e3e3a7aSWarner LoshIf the text immediately after <code>--</code> is not an opening long bracket, 14188e3e3a7aSWarner Loshthe comment is a <em>short comment</em>, 14198e3e3a7aSWarner Loshwhich runs until the end of the line. 14208e3e3a7aSWarner LoshOtherwise, it is a <em>long comment</em>, 14218e3e3a7aSWarner Loshwhich runs until the corresponding closing long bracket. 14228e3e3a7aSWarner Losh 14238e3e3a7aSWarner Losh 14248e3e3a7aSWarner Losh 14258e3e3a7aSWarner Losh 14268e3e3a7aSWarner Losh 14278e3e3a7aSWarner Losh<h2>3.2 – <a name="3.2">Variables</a></h2> 14288e3e3a7aSWarner Losh 14298e3e3a7aSWarner Losh<p> 14308e3e3a7aSWarner LoshVariables are places that store values. 14318e3e3a7aSWarner LoshThere are three kinds of variables in Lua: 14328e3e3a7aSWarner Loshglobal variables, local variables, and table fields. 14338e3e3a7aSWarner Losh 14348e3e3a7aSWarner Losh 14358e3e3a7aSWarner Losh<p> 14368e3e3a7aSWarner LoshA single name can denote a global variable or a local variable 14378e3e3a7aSWarner Losh(or a function's formal parameter, 14388e3e3a7aSWarner Loshwhich is a particular kind of local variable): 14398e3e3a7aSWarner Losh 14408e3e3a7aSWarner Losh<pre> 14418e3e3a7aSWarner Losh var ::= Name 14428e3e3a7aSWarner Losh</pre><p> 14430495ed39SKyle EvansName denotes identifiers (see <a href="#3.1">§3.1</a>). 14448e3e3a7aSWarner Losh 14458e3e3a7aSWarner Losh 14468e3e3a7aSWarner Losh<p> 14478e3e3a7aSWarner LoshAny variable name is assumed to be global unless explicitly declared 14488e3e3a7aSWarner Loshas a local (see <a href="#3.3.7">§3.3.7</a>). 14498e3e3a7aSWarner LoshLocal variables are <em>lexically scoped</em>: 14508e3e3a7aSWarner Loshlocal variables can be freely accessed by functions 14518e3e3a7aSWarner Loshdefined inside their scope (see <a href="#3.5">§3.5</a>). 14528e3e3a7aSWarner Losh 14538e3e3a7aSWarner Losh 14548e3e3a7aSWarner Losh<p> 14558e3e3a7aSWarner LoshBefore the first assignment to a variable, its value is <b>nil</b>. 14568e3e3a7aSWarner Losh 14578e3e3a7aSWarner Losh 14588e3e3a7aSWarner Losh<p> 14598e3e3a7aSWarner LoshSquare brackets are used to index a table: 14608e3e3a7aSWarner Losh 14618e3e3a7aSWarner Losh<pre> 14628e3e3a7aSWarner Losh var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ 14638e3e3a7aSWarner Losh</pre><p> 1464e112e9d2SKyle EvansThe meaning of accesses to table fields can be changed via metatables 1465e112e9d2SKyle Evans(see <a href="#2.4">§2.4</a>). 14668e3e3a7aSWarner Losh 14678e3e3a7aSWarner Losh 14688e3e3a7aSWarner Losh<p> 14698e3e3a7aSWarner LoshThe syntax <code>var.Name</code> is just syntactic sugar for 14708e3e3a7aSWarner Losh<code>var["Name"]</code>: 14718e3e3a7aSWarner Losh 14728e3e3a7aSWarner Losh<pre> 14738e3e3a7aSWarner Losh var ::= prefixexp ‘<b>.</b>’ Name 14748e3e3a7aSWarner Losh</pre> 14758e3e3a7aSWarner Losh 14768e3e3a7aSWarner Losh<p> 14778e3e3a7aSWarner LoshAn access to a global variable <code>x</code> 14788e3e3a7aSWarner Loshis equivalent to <code>_ENV.x</code>. 14798e3e3a7aSWarner LoshDue to the way that chunks are compiled, 14800495ed39SKyle Evansthe variable <code>_ENV</code> itself is never global (see <a href="#2.2">§2.2</a>). 14818e3e3a7aSWarner Losh 14828e3e3a7aSWarner Losh 14838e3e3a7aSWarner Losh 14848e3e3a7aSWarner Losh 14858e3e3a7aSWarner Losh 14868e3e3a7aSWarner Losh<h2>3.3 – <a name="3.3">Statements</a></h2> 14878e3e3a7aSWarner Losh 14880495ed39SKyle Evans 14890495ed39SKyle Evans 14908e3e3a7aSWarner Losh<p> 14918e3e3a7aSWarner LoshLua supports an almost conventional set of statements, 14920495ed39SKyle Evanssimilar to those in other conventional languages. 14938e3e3a7aSWarner LoshThis set includes 14940495ed39SKyle Evansblocks, assignments, control structures, function calls, 14958e3e3a7aSWarner Loshand variable declarations. 14968e3e3a7aSWarner Losh 14978e3e3a7aSWarner Losh 14988e3e3a7aSWarner Losh 14990495ed39SKyle Evans 15000495ed39SKyle Evans 15018e3e3a7aSWarner Losh<h3>3.3.1 – <a name="3.3.1">Blocks</a></h3> 15028e3e3a7aSWarner Losh 15038e3e3a7aSWarner Losh<p> 15048e3e3a7aSWarner LoshA block is a list of statements, 15058e3e3a7aSWarner Loshwhich are executed sequentially: 15068e3e3a7aSWarner Losh 15078e3e3a7aSWarner Losh<pre> 15088e3e3a7aSWarner Losh block ::= {stat} 15098e3e3a7aSWarner Losh</pre><p> 15108e3e3a7aSWarner LoshLua has <em>empty statements</em> 15118e3e3a7aSWarner Loshthat allow you to separate statements with semicolons, 15128e3e3a7aSWarner Loshstart a block with a semicolon 15138e3e3a7aSWarner Loshor write two semicolons in sequence: 15148e3e3a7aSWarner Losh 15158e3e3a7aSWarner Losh<pre> 15168e3e3a7aSWarner Losh stat ::= ‘<b>;</b>’ 15178e3e3a7aSWarner Losh</pre> 15188e3e3a7aSWarner Losh 15198e3e3a7aSWarner Losh<p> 15200495ed39SKyle EvansBoth function calls and assignments 15218e3e3a7aSWarner Loshcan start with an open parenthesis. 15228e3e3a7aSWarner LoshThis possibility leads to an ambiguity in Lua's grammar. 15238e3e3a7aSWarner LoshConsider the following fragment: 15248e3e3a7aSWarner Losh 15258e3e3a7aSWarner Losh<pre> 15268e3e3a7aSWarner Losh a = b + c 15278e3e3a7aSWarner Losh (print or io.write)('done') 15288e3e3a7aSWarner Losh</pre><p> 15290495ed39SKyle EvansThe grammar could see this fragment in two ways: 15308e3e3a7aSWarner Losh 15318e3e3a7aSWarner Losh<pre> 15328e3e3a7aSWarner Losh a = b + c(print or io.write)('done') 15338e3e3a7aSWarner Losh 15348e3e3a7aSWarner Losh a = b + c; (print or io.write)('done') 15358e3e3a7aSWarner Losh</pre><p> 15368e3e3a7aSWarner LoshThe current parser always sees such constructions 15378e3e3a7aSWarner Loshin the first way, 15388e3e3a7aSWarner Loshinterpreting the open parenthesis 15398e3e3a7aSWarner Loshas the start of the arguments to a call. 15408e3e3a7aSWarner LoshTo avoid this ambiguity, 15418e3e3a7aSWarner Loshit is a good practice to always precede with a semicolon 15428e3e3a7aSWarner Loshstatements that start with a parenthesis: 15438e3e3a7aSWarner Losh 15448e3e3a7aSWarner Losh<pre> 15458e3e3a7aSWarner Losh ;(print or io.write)('done') 15468e3e3a7aSWarner Losh</pre> 15478e3e3a7aSWarner Losh 15488e3e3a7aSWarner Losh<p> 15498e3e3a7aSWarner LoshA block can be explicitly delimited to produce a single statement: 15508e3e3a7aSWarner Losh 15518e3e3a7aSWarner Losh<pre> 15528e3e3a7aSWarner Losh stat ::= <b>do</b> block <b>end</b> 15538e3e3a7aSWarner Losh</pre><p> 15548e3e3a7aSWarner LoshExplicit blocks are useful 15558e3e3a7aSWarner Loshto control the scope of variable declarations. 15568e3e3a7aSWarner LoshExplicit blocks are also sometimes used to 15578e3e3a7aSWarner Loshadd a <b>return</b> statement in the middle 15588e3e3a7aSWarner Loshof another block (see <a href="#3.3.4">§3.3.4</a>). 15598e3e3a7aSWarner Losh 15608e3e3a7aSWarner Losh 15618e3e3a7aSWarner Losh 15628e3e3a7aSWarner Losh 15638e3e3a7aSWarner Losh 15648e3e3a7aSWarner Losh<h3>3.3.2 – <a name="3.3.2">Chunks</a></h3> 15658e3e3a7aSWarner Losh 15668e3e3a7aSWarner Losh<p> 15678e3e3a7aSWarner LoshThe unit of compilation of Lua is called a <em>chunk</em>. 15688e3e3a7aSWarner LoshSyntactically, 15698e3e3a7aSWarner Losha chunk is simply a block: 15708e3e3a7aSWarner Losh 15718e3e3a7aSWarner Losh<pre> 15728e3e3a7aSWarner Losh chunk ::= block 15738e3e3a7aSWarner Losh</pre> 15748e3e3a7aSWarner Losh 15758e3e3a7aSWarner Losh<p> 15768e3e3a7aSWarner LoshLua handles a chunk as the body of an anonymous function 15778e3e3a7aSWarner Loshwith a variable number of arguments 15788e3e3a7aSWarner Losh(see <a href="#3.4.11">§3.4.11</a>). 15798e3e3a7aSWarner LoshAs such, chunks can define local variables, 15808e3e3a7aSWarner Loshreceive arguments, and return values. 15818e3e3a7aSWarner LoshMoreover, such anonymous function is compiled as in the 15828e3e3a7aSWarner Loshscope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>). 15830495ed39SKyle EvansThe resulting function always has <code>_ENV</code> as its only external variable, 15848e3e3a7aSWarner Losheven if it does not use that variable. 15858e3e3a7aSWarner Losh 15868e3e3a7aSWarner Losh 15878e3e3a7aSWarner Losh<p> 15888e3e3a7aSWarner LoshA chunk can be stored in a file or in a string inside the host program. 15898e3e3a7aSWarner LoshTo execute a chunk, 15908e3e3a7aSWarner LoshLua first <em>loads</em> it, 15918e3e3a7aSWarner Loshprecompiling the chunk's code into instructions for a virtual machine, 15928e3e3a7aSWarner Loshand then Lua executes the compiled code 15938e3e3a7aSWarner Loshwith an interpreter for the virtual machine. 15948e3e3a7aSWarner Losh 15958e3e3a7aSWarner Losh 15968e3e3a7aSWarner Losh<p> 15978e3e3a7aSWarner LoshChunks can also be precompiled into binary form; 15980495ed39SKyle Evanssee the program <code>luac</code> and the function <a href="#pdf-string.dump"><code>string.dump</code></a> for details. 15998e3e3a7aSWarner LoshPrograms in source and compiled forms are interchangeable; 16008e3e3a7aSWarner LoshLua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>). 16018e3e3a7aSWarner Losh 16028e3e3a7aSWarner Losh 16038e3e3a7aSWarner Losh 16048e3e3a7aSWarner Losh 16058e3e3a7aSWarner Losh 16068e3e3a7aSWarner Losh<h3>3.3.3 – <a name="3.3.3">Assignment</a></h3> 16078e3e3a7aSWarner Losh 16088e3e3a7aSWarner Losh<p> 16098e3e3a7aSWarner LoshLua allows multiple assignments. 16108e3e3a7aSWarner LoshTherefore, the syntax for assignment 16118e3e3a7aSWarner Loshdefines a list of variables on the left side 16128e3e3a7aSWarner Loshand a list of expressions on the right side. 16138e3e3a7aSWarner LoshThe elements in both lists are separated by commas: 16148e3e3a7aSWarner Losh 16158e3e3a7aSWarner Losh<pre> 16168e3e3a7aSWarner Losh stat ::= varlist ‘<b>=</b>’ explist 16178e3e3a7aSWarner Losh varlist ::= var {‘<b>,</b>’ var} 16188e3e3a7aSWarner Losh explist ::= exp {‘<b>,</b>’ exp} 16198e3e3a7aSWarner Losh</pre><p> 16208e3e3a7aSWarner LoshExpressions are discussed in <a href="#3.4">§3.4</a>. 16218e3e3a7aSWarner Losh 16228e3e3a7aSWarner Losh 16238e3e3a7aSWarner Losh<p> 16248e3e3a7aSWarner LoshBefore the assignment, 16258e3e3a7aSWarner Loshthe list of values is <em>adjusted</em> to the length of 1626*a9490b81SWarner Loshthe list of variables (see <a href="#3.4.12">§3.4.12</a>). 16278e3e3a7aSWarner Losh 16288e3e3a7aSWarner Losh 16298e3e3a7aSWarner Losh<p> 16308c784bb8SWarner LoshIf a variable is both assigned and read 16318c784bb8SWarner Loshinside a multiple assignment, 1632*a9490b81SWarner LoshLua ensures that all reads get the value of the variable 16338c784bb8SWarner Loshbefore the assignment. 16348e3e3a7aSWarner LoshThus the code 16358e3e3a7aSWarner Losh 16368e3e3a7aSWarner Losh<pre> 16378e3e3a7aSWarner Losh i = 3 16388e3e3a7aSWarner Losh i, a[i] = i+1, 20 16398e3e3a7aSWarner Losh</pre><p> 16408e3e3a7aSWarner Loshsets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 16418e3e3a7aSWarner Loshbecause the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 16428e3e3a7aSWarner Loshbefore it is assigned 4. 16438e3e3a7aSWarner LoshSimilarly, the line 16448e3e3a7aSWarner Losh 16458e3e3a7aSWarner Losh<pre> 16468e3e3a7aSWarner Losh x, y = y, x 16478e3e3a7aSWarner Losh</pre><p> 16488e3e3a7aSWarner Loshexchanges the values of <code>x</code> and <code>y</code>, 16498e3e3a7aSWarner Loshand 16508e3e3a7aSWarner Losh 16518e3e3a7aSWarner Losh<pre> 16528e3e3a7aSWarner Losh x, y, z = y, z, x 16538e3e3a7aSWarner Losh</pre><p> 16548e3e3a7aSWarner Loshcyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 16558e3e3a7aSWarner Losh 16568e3e3a7aSWarner Losh 16578e3e3a7aSWarner Losh<p> 16588c784bb8SWarner LoshNote that this guarantee covers only accesses 16598c784bb8SWarner Loshsyntactically inside the assignment statement. 16608c784bb8SWarner LoshIf a function or a metamethod called during the assignment 16618c784bb8SWarner Loshchanges the value of a variable, 16628c784bb8SWarner LoshLua gives no guarantees about the order of that access. 16638c784bb8SWarner Losh 16648c784bb8SWarner Losh 16658c784bb8SWarner Losh<p> 16668e3e3a7aSWarner LoshAn assignment to a global name <code>x = val</code> 16678e3e3a7aSWarner Loshis equivalent to the assignment 16688e3e3a7aSWarner Losh<code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>). 16698e3e3a7aSWarner Losh 16708e3e3a7aSWarner Losh 1671e112e9d2SKyle Evans<p> 1672e112e9d2SKyle EvansThe meaning of assignments to table fields and 1673e112e9d2SKyle Evansglobal variables (which are actually table fields, too) 1674e112e9d2SKyle Evanscan be changed via metatables (see <a href="#2.4">§2.4</a>). 1675e112e9d2SKyle Evans 1676e112e9d2SKyle Evans 16778e3e3a7aSWarner Losh 16788e3e3a7aSWarner Losh 16798e3e3a7aSWarner Losh 16808e3e3a7aSWarner Losh<h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p> 16818e3e3a7aSWarner LoshThe control structures 16828e3e3a7aSWarner Losh<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 16838e3e3a7aSWarner Loshfamiliar syntax: 16848e3e3a7aSWarner Losh 16858e3e3a7aSWarner Losh 16868e3e3a7aSWarner Losh 16878e3e3a7aSWarner Losh 16888e3e3a7aSWarner Losh<pre> 16898e3e3a7aSWarner Losh stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 16908e3e3a7aSWarner Losh stat ::= <b>repeat</b> block <b>until</b> exp 16918e3e3a7aSWarner 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> 16928e3e3a7aSWarner Losh</pre><p> 16938e3e3a7aSWarner LoshLua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>). 16948e3e3a7aSWarner Losh 16958e3e3a7aSWarner Losh 16968e3e3a7aSWarner Losh<p> 16978e3e3a7aSWarner LoshThe condition expression of a 16988e3e3a7aSWarner Loshcontrol structure can return any value. 16990495ed39SKyle EvansBoth <b>false</b> and <b>nil</b> test false. 17000495ed39SKyle EvansAll values different from <b>nil</b> and <b>false</b> test true. 17010495ed39SKyle EvansIn particular, the number 0 and the empty string also test true. 17028e3e3a7aSWarner Losh 17038e3e3a7aSWarner Losh 17048e3e3a7aSWarner Losh<p> 17058e3e3a7aSWarner LoshIn the <b>repeat</b>–<b>until</b> loop, 17068e3e3a7aSWarner Loshthe inner block does not end at the <b>until</b> keyword, 17078e3e3a7aSWarner Loshbut only after the condition. 17088e3e3a7aSWarner LoshSo, the condition can refer to local variables 17098e3e3a7aSWarner Loshdeclared inside the loop block. 17108e3e3a7aSWarner Losh 17118e3e3a7aSWarner Losh 17128e3e3a7aSWarner Losh<p> 17138e3e3a7aSWarner LoshThe <b>goto</b> statement transfers the program control to a label. 17148e3e3a7aSWarner LoshFor syntactical reasons, 17158e3e3a7aSWarner Loshlabels in Lua are considered statements too: 17168e3e3a7aSWarner Losh 17178e3e3a7aSWarner Losh 17188e3e3a7aSWarner Losh 17198e3e3a7aSWarner Losh<pre> 17208e3e3a7aSWarner Losh stat ::= <b>goto</b> Name 17218e3e3a7aSWarner Losh stat ::= label 17228e3e3a7aSWarner Losh label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 17238e3e3a7aSWarner Losh</pre> 17248e3e3a7aSWarner Losh 17258e3e3a7aSWarner Losh<p> 17268e3e3a7aSWarner LoshA label is visible in the entire block where it is defined, 17270495ed39SKyle Evansexcept inside nested functions. 17288e3e3a7aSWarner LoshA goto may jump to any visible label as long as it does not 17298e3e3a7aSWarner Loshenter into the scope of a local variable. 17300495ed39SKyle EvansA label should not be declared 17310495ed39SKyle Evanswhere a label with the same name is visible, 17320495ed39SKyle Evanseven if this other label has been declared in an enclosing block. 17338e3e3a7aSWarner Losh 17348e3e3a7aSWarner Losh 17358e3e3a7aSWarner Losh<p> 17368e3e3a7aSWarner LoshThe <b>break</b> statement terminates the execution of a 17378e3e3a7aSWarner Losh<b>while</b>, <b>repeat</b>, or <b>for</b> loop, 17388e3e3a7aSWarner Loshskipping to the next statement after the loop: 17398e3e3a7aSWarner Losh 17408e3e3a7aSWarner Losh 17418e3e3a7aSWarner Losh<pre> 17428e3e3a7aSWarner Losh stat ::= <b>break</b> 17438e3e3a7aSWarner Losh</pre><p> 17448e3e3a7aSWarner LoshA <b>break</b> ends the innermost enclosing loop. 17458e3e3a7aSWarner Losh 17468e3e3a7aSWarner Losh 17478e3e3a7aSWarner Losh<p> 17488e3e3a7aSWarner LoshThe <b>return</b> statement is used to return values 17498e3e3a7aSWarner Loshfrom a function or a chunk 17500495ed39SKyle Evans(which is handled as an anonymous function). 17518e3e3a7aSWarner Losh 17528e3e3a7aSWarner LoshFunctions can return more than one value, 17538e3e3a7aSWarner Loshso the syntax for the <b>return</b> statement is 17548e3e3a7aSWarner Losh 17558e3e3a7aSWarner Losh<pre> 17568e3e3a7aSWarner Losh stat ::= <b>return</b> [explist] [‘<b>;</b>’] 17578e3e3a7aSWarner Losh</pre> 17588e3e3a7aSWarner Losh 17598e3e3a7aSWarner Losh<p> 17608e3e3a7aSWarner LoshThe <b>return</b> statement can only be written 17618e3e3a7aSWarner Loshas the last statement of a block. 17620495ed39SKyle EvansIf it is necessary to <b>return</b> in the middle of a block, 17638e3e3a7aSWarner Loshthen an explicit inner block can be used, 17648e3e3a7aSWarner Loshas in the idiom <code>do return end</code>, 17658e3e3a7aSWarner Loshbecause now <b>return</b> is the last statement in its (inner) block. 17668e3e3a7aSWarner Losh 17678e3e3a7aSWarner Losh 17688e3e3a7aSWarner Losh 17698e3e3a7aSWarner Losh 17708e3e3a7aSWarner Losh 17718e3e3a7aSWarner Losh<h3>3.3.5 – <a name="3.3.5">For Statement</a></h3> 17728e3e3a7aSWarner Losh 17738e3e3a7aSWarner Losh<p> 17748e3e3a7aSWarner Losh 17758e3e3a7aSWarner LoshThe <b>for</b> statement has two forms: 17768e3e3a7aSWarner Loshone numerical and one generic. 17778e3e3a7aSWarner Losh 17788e3e3a7aSWarner Losh 17790495ed39SKyle Evans 17800495ed39SKyle Evans<h4>The numerical <b>for</b> loop</h4> 17810495ed39SKyle Evans 17828e3e3a7aSWarner Losh<p> 17838e3e3a7aSWarner LoshThe numerical <b>for</b> loop repeats a block of code while a 17840495ed39SKyle Evanscontrol variable goes through an arithmetic progression. 17858e3e3a7aSWarner LoshIt has the following syntax: 17868e3e3a7aSWarner Losh 17878e3e3a7aSWarner Losh<pre> 17888e3e3a7aSWarner Losh stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> 17898e3e3a7aSWarner Losh</pre><p> 17900495ed39SKyle EvansThe given identifier (Name) defines the control variable, 17910495ed39SKyle Evanswhich is a new variable local to the loop body (<em>block</em>). 17928e3e3a7aSWarner Losh 17938e3e3a7aSWarner Losh 17948e3e3a7aSWarner Losh<p> 17950495ed39SKyle EvansThe loop starts by evaluating once the three control expressions. 17960495ed39SKyle EvansTheir values are called respectively 17970495ed39SKyle Evansthe <em>initial value</em>, the <em>limit</em>, and the <em>step</em>. 17980495ed39SKyle EvansIf the step is absent, it defaults to 1. 17998e3e3a7aSWarner Losh 18008e3e3a7aSWarner Losh 18010495ed39SKyle Evans<p> 18020495ed39SKyle EvansIf both the initial value and the step are integers, 18030495ed39SKyle Evansthe loop is done with integers; 18040495ed39SKyle Evansnote that the limit may not be an integer. 18050495ed39SKyle EvansOtherwise, the three values are converted to 18060495ed39SKyle Evansfloats and the loop is done with floats. 18070495ed39SKyle EvansBeware of floating-point accuracy in this case. 18088e3e3a7aSWarner Losh 18098e3e3a7aSWarner Losh 18100495ed39SKyle Evans<p> 18110495ed39SKyle EvansAfter that initialization, 18120495ed39SKyle Evansthe loop body is repeated with the value of the control variable 18130495ed39SKyle Evansgoing through an arithmetic progression, 18140495ed39SKyle Evansstarting at the initial value, 18150495ed39SKyle Evanswith a common difference given by the step. 18160495ed39SKyle EvansA negative step makes a decreasing sequence; 18170495ed39SKyle Evansa step equal to zero raises an error. 18180495ed39SKyle EvansThe loop continues while the value is less than 18190495ed39SKyle Evansor equal to the limit 18200495ed39SKyle Evans(greater than or equal to for a negative step). 18210495ed39SKyle EvansIf the initial value is already greater than the limit 18220495ed39SKyle Evans(or less than, if the step is negative), 18230495ed39SKyle Evansthe body is not executed. 18248e3e3a7aSWarner Losh 18258e3e3a7aSWarner Losh 18260495ed39SKyle Evans<p> 18270495ed39SKyle EvansFor integer loops, 18280495ed39SKyle Evansthe control variable never wraps around; 18290495ed39SKyle Evansinstead, the loop ends in case of an overflow. 18300495ed39SKyle Evans 18310495ed39SKyle Evans 18320495ed39SKyle Evans<p> 18330495ed39SKyle EvansYou should not change the value of the control variable 18340495ed39SKyle Evansduring the loop. 18358e3e3a7aSWarner LoshIf you need its value after the loop, 18368e3e3a7aSWarner Loshassign it to another variable before exiting the loop. 18378e3e3a7aSWarner Losh 18380495ed39SKyle Evans 18390495ed39SKyle Evans 18400495ed39SKyle Evans 18410495ed39SKyle Evans 18420495ed39SKyle Evans<h4>The generic <b>for</b> loop</h4> 18438e3e3a7aSWarner Losh 18448e3e3a7aSWarner Losh<p> 18458e3e3a7aSWarner LoshThe generic <b>for</b> statement works over functions, 18468e3e3a7aSWarner Loshcalled <em>iterators</em>. 18478e3e3a7aSWarner LoshOn each iteration, the iterator function is called to produce a new value, 18488e3e3a7aSWarner Loshstopping when this new value is <b>nil</b>. 18498e3e3a7aSWarner LoshThe generic <b>for</b> loop has the following syntax: 18508e3e3a7aSWarner Losh 18518e3e3a7aSWarner Losh<pre> 18528e3e3a7aSWarner Losh stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> 18538e3e3a7aSWarner Losh namelist ::= Name {‘<b>,</b>’ Name} 18548e3e3a7aSWarner Losh</pre><p> 18558e3e3a7aSWarner LoshA <b>for</b> statement like 18568e3e3a7aSWarner Losh 18578e3e3a7aSWarner Losh<pre> 18580495ed39SKyle Evans for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>body</em> end 18598e3e3a7aSWarner Losh</pre><p> 18600495ed39SKyle Evansworks as follows. 18618e3e3a7aSWarner Losh 18628e3e3a7aSWarner Losh 18630495ed39SKyle Evans<p> 18640495ed39SKyle EvansThe names <em>var_i</em> declare loop variables local to the loop body. 18650495ed39SKyle EvansThe first of these variables is the <em>control variable</em>. 18668e3e3a7aSWarner Losh 18670495ed39SKyle Evans 18680495ed39SKyle Evans<p> 18690495ed39SKyle EvansThe loop starts by evaluating <em>explist</em> 18700495ed39SKyle Evansto produce four values: 18710495ed39SKyle Evansan <em>iterator function</em>, 18728e3e3a7aSWarner Losha <em>state</em>, 18730495ed39SKyle Evansan initial value for the control variable, 18740495ed39SKyle Evansand a <em>closing value</em>. 18758e3e3a7aSWarner Losh 18768e3e3a7aSWarner Losh 18770495ed39SKyle Evans<p> 18780495ed39SKyle EvansThen, at each iteration, 18790495ed39SKyle EvansLua calls the iterator function with two arguments: 18800495ed39SKyle Evansthe state and the control variable. 18810495ed39SKyle EvansThe results from this call are then assigned to the loop variables, 18820495ed39SKyle Evansfollowing the rules of multiple assignments (see <a href="#3.3.3">§3.3.3</a>). 18830495ed39SKyle EvansIf the control variable becomes <b>nil</b>, 18840495ed39SKyle Evansthe loop terminates. 18850495ed39SKyle EvansOtherwise, the body is executed and the loop goes 18860495ed39SKyle Evansto the next iteration. 18878e3e3a7aSWarner Losh 18888e3e3a7aSWarner Losh 18890495ed39SKyle Evans<p> 18900495ed39SKyle EvansThe closing value behaves like a 18910495ed39SKyle Evansto-be-closed variable (see <a href="#3.3.8">§3.3.8</a>), 18920495ed39SKyle Evanswhich can be used to release resources when the loop ends. 18930495ed39SKyle EvansOtherwise, it does not interfere with the loop. 18940495ed39SKyle Evans 18950495ed39SKyle Evans 18960495ed39SKyle Evans<p> 18970495ed39SKyle EvansYou should not change the value of the control variable 18980495ed39SKyle Evansduring the loop. 18990495ed39SKyle Evans 19000495ed39SKyle Evans 19010495ed39SKyle Evans 19028e3e3a7aSWarner Losh 19038e3e3a7aSWarner Losh 19048e3e3a7aSWarner Losh 19058e3e3a7aSWarner Losh 19068e3e3a7aSWarner Losh<h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p> 19078e3e3a7aSWarner LoshTo allow possible side-effects, 19088e3e3a7aSWarner Loshfunction calls can be executed as statements: 19098e3e3a7aSWarner Losh 19108e3e3a7aSWarner Losh<pre> 19118e3e3a7aSWarner Losh stat ::= functioncall 19128e3e3a7aSWarner Losh</pre><p> 19138e3e3a7aSWarner LoshIn this case, all returned values are thrown away. 19148e3e3a7aSWarner LoshFunction calls are explained in <a href="#3.4.10">§3.4.10</a>. 19158e3e3a7aSWarner Losh 19168e3e3a7aSWarner Losh 19178e3e3a7aSWarner Losh 19188e3e3a7aSWarner Losh 19198e3e3a7aSWarner Losh 19208e3e3a7aSWarner Losh<h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p> 19218e3e3a7aSWarner LoshLocal variables can be declared anywhere inside a block. 19220495ed39SKyle EvansThe declaration can include an initialization: 19238e3e3a7aSWarner Losh 19248e3e3a7aSWarner Losh<pre> 19250495ed39SKyle Evans stat ::= <b>local</b> attnamelist [‘<b>=</b>’ explist] 19260495ed39SKyle Evans attnamelist ::= Name attrib {‘<b>,</b>’ Name attrib} 19278e3e3a7aSWarner Losh</pre><p> 19288e3e3a7aSWarner LoshIf present, an initial assignment has the same semantics 19298e3e3a7aSWarner Loshof a multiple assignment (see <a href="#3.3.3">§3.3.3</a>). 19308e3e3a7aSWarner LoshOtherwise, all variables are initialized with <b>nil</b>. 19318e3e3a7aSWarner Losh 19328e3e3a7aSWarner Losh 19338e3e3a7aSWarner Losh<p> 19340495ed39SKyle EvansEach variable name may be postfixed by an attribute 19350495ed39SKyle Evans(a name between angle brackets): 19360495ed39SKyle Evans 19370495ed39SKyle Evans<pre> 19380495ed39SKyle Evans attrib ::= [‘<b><</b>’ Name ‘<b>></b>’] 19390495ed39SKyle Evans</pre><p> 19400495ed39SKyle EvansThere are two possible attributes: 19410495ed39SKyle Evans<code>const</code>, which declares a constant variable, 19420495ed39SKyle Evansthat is, a variable that cannot be assigned to 19430495ed39SKyle Evansafter its initialization; 19440495ed39SKyle Evansand <code>close</code>, which declares a to-be-closed variable (see <a href="#3.3.8">§3.3.8</a>). 19450495ed39SKyle EvansA list of variables can contain at most one to-be-closed variable. 19460495ed39SKyle Evans 19470495ed39SKyle Evans 19480495ed39SKyle Evans<p> 19498e3e3a7aSWarner LoshA chunk is also a block (see <a href="#3.3.2">§3.3.2</a>), 19508e3e3a7aSWarner Loshand so local variables can be declared in a chunk outside any explicit block. 19518e3e3a7aSWarner Losh 19528e3e3a7aSWarner Losh 19538e3e3a7aSWarner Losh<p> 19548e3e3a7aSWarner LoshThe visibility rules for local variables are explained in <a href="#3.5">§3.5</a>. 19558e3e3a7aSWarner Losh 19568e3e3a7aSWarner Losh 19578e3e3a7aSWarner Losh 19588e3e3a7aSWarner Losh 19598e3e3a7aSWarner Losh 19600495ed39SKyle Evans<h3>3.3.8 – <a name="3.3.8">To-be-closed Variables</a></h3> 19610495ed39SKyle Evans 19620495ed39SKyle Evans<p> 19630495ed39SKyle EvansA to-be-closed variable behaves like a constant local variable, 19640495ed39SKyle Evansexcept that its value is <em>closed</em> whenever the variable 19650495ed39SKyle Evansgoes out of scope, including normal block termination, 19660495ed39SKyle Evansexiting its block by <b>break</b>/<b>goto</b>/<b>return</b>, 19670495ed39SKyle Evansor exiting by an error. 19680495ed39SKyle Evans 19690495ed39SKyle Evans 19700495ed39SKyle Evans<p> 19710495ed39SKyle EvansHere, to <em>close</em> a value means 19720495ed39SKyle Evansto call its <code>__close</code> metamethod. 19730495ed39SKyle EvansWhen calling the metamethod, 19740495ed39SKyle Evansthe value itself is passed as the first argument 19750495ed39SKyle Evansand the error object that caused the exit (if any) 19760495ed39SKyle Evansis passed as a second argument; 19770495ed39SKyle Evansif there was no error, the second argument is <b>nil</b>. 19780495ed39SKyle Evans 19790495ed39SKyle Evans 19800495ed39SKyle Evans<p> 19810495ed39SKyle EvansThe value assigned to a to-be-closed variable 19820495ed39SKyle Evansmust have a <code>__close</code> metamethod 19830495ed39SKyle Evansor be a false value. 19840495ed39SKyle Evans(<b>nil</b> and <b>false</b> are ignored as to-be-closed values.) 19850495ed39SKyle Evans 19860495ed39SKyle Evans 19870495ed39SKyle Evans<p> 19880495ed39SKyle EvansIf several to-be-closed variables go out of scope at the same event, 19890495ed39SKyle Evansthey are closed in the reverse order that they were declared. 19900495ed39SKyle Evans 19910495ed39SKyle Evans 19920495ed39SKyle Evans<p> 19930495ed39SKyle EvansIf there is any error while running a closing method, 19940495ed39SKyle Evansthat error is handled like an error in the regular code 19950495ed39SKyle Evanswhere the variable was defined. 19960495ed39SKyle EvansAfter an error, 19970495ed39SKyle Evansthe other pending closing methods will still be called. 19980495ed39SKyle Evans 19990495ed39SKyle Evans 20000495ed39SKyle Evans<p> 20010495ed39SKyle EvansIf a coroutine yields and is never resumed again, 20020495ed39SKyle Evanssome variables may never go out of scope, 20030495ed39SKyle Evansand therefore they will never be closed. 20040495ed39SKyle Evans(These variables are the ones created inside the coroutine 20050495ed39SKyle Evansand in scope at the point where the coroutine yielded.) 20060495ed39SKyle EvansSimilarly, if a coroutine ends with an error, 20070495ed39SKyle Evansit does not unwind its stack, 20080495ed39SKyle Evansso it does not close any variable. 20090495ed39SKyle EvansIn both cases, 20100495ed39SKyle Evansyou can either use finalizers 20110495ed39SKyle Evansor call <a href="#pdf-coroutine.close"><code>coroutine.close</code></a> to close the variables. 20120495ed39SKyle EvansHowever, if the coroutine was created 20130495ed39SKyle Evansthrough <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a>, 20140495ed39SKyle Evansthen its corresponding function will close the coroutine 20150495ed39SKyle Evansin case of errors. 20160495ed39SKyle Evans 20170495ed39SKyle Evans 20180495ed39SKyle Evans 20190495ed39SKyle Evans 20200495ed39SKyle Evans 20218e3e3a7aSWarner Losh 20228e3e3a7aSWarner Losh 20238e3e3a7aSWarner Losh<h2>3.4 – <a name="3.4">Expressions</a></h2> 20248e3e3a7aSWarner Losh 20250495ed39SKyle Evans 20260495ed39SKyle Evans 20278e3e3a7aSWarner Losh<p> 20288e3e3a7aSWarner LoshThe basic expressions in Lua are the following: 20298e3e3a7aSWarner Losh 20308e3e3a7aSWarner Losh<pre> 20318e3e3a7aSWarner Losh exp ::= prefixexp 20328e3e3a7aSWarner Losh exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 20338e3e3a7aSWarner Losh exp ::= Numeral 20348e3e3a7aSWarner Losh exp ::= LiteralString 20358e3e3a7aSWarner Losh exp ::= functiondef 20368e3e3a7aSWarner Losh exp ::= tableconstructor 20378e3e3a7aSWarner Losh exp ::= ‘<b>...</b>’ 20388e3e3a7aSWarner Losh exp ::= exp binop exp 20398e3e3a7aSWarner Losh exp ::= unop exp 20408e3e3a7aSWarner Losh prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 20418e3e3a7aSWarner Losh</pre> 20428e3e3a7aSWarner Losh 20438e3e3a7aSWarner Losh<p> 20448e3e3a7aSWarner LoshNumerals and literal strings are explained in <a href="#3.1">§3.1</a>; 20458e3e3a7aSWarner Loshvariables are explained in <a href="#3.2">§3.2</a>; 20468e3e3a7aSWarner Loshfunction definitions are explained in <a href="#3.4.11">§3.4.11</a>; 20478e3e3a7aSWarner Loshfunction calls are explained in <a href="#3.4.10">§3.4.10</a>; 20488e3e3a7aSWarner Loshtable constructors are explained in <a href="#3.4.9">§3.4.9</a>. 20498e3e3a7aSWarner LoshVararg expressions, 20508e3e3a7aSWarner Loshdenoted by three dots ('<code>...</code>'), can only be used when 2051*a9490b81SWarner Loshdirectly inside a variadic function; 20528e3e3a7aSWarner Loshthey are explained in <a href="#3.4.11">§3.4.11</a>. 20538e3e3a7aSWarner Losh 20548e3e3a7aSWarner Losh 20558e3e3a7aSWarner Losh<p> 20568e3e3a7aSWarner LoshBinary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), 20578e3e3a7aSWarner Loshbitwise operators (see <a href="#3.4.2">§3.4.2</a>), 20588e3e3a7aSWarner Loshrelational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>), 20598e3e3a7aSWarner Loshand the concatenation operator (see <a href="#3.4.6">§3.4.6</a>). 20608e3e3a7aSWarner LoshUnary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), 20618e3e3a7aSWarner Loshthe unary bitwise NOT (see <a href="#3.4.2">§3.4.2</a>), 20628e3e3a7aSWarner Loshthe unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), 20638e3e3a7aSWarner Loshand the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). 20648e3e3a7aSWarner Losh 20658e3e3a7aSWarner Losh 20668e3e3a7aSWarner Losh 20670495ed39SKyle Evans 20680495ed39SKyle Evans 20698e3e3a7aSWarner Losh<h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p> 20708e3e3a7aSWarner LoshLua supports the following arithmetic operators: 20718e3e3a7aSWarner Losh 20728e3e3a7aSWarner Losh<ul> 20738e3e3a7aSWarner Losh<li><b><code>+</code>: </b>addition</li> 20748e3e3a7aSWarner Losh<li><b><code>-</code>: </b>subtraction</li> 20758e3e3a7aSWarner Losh<li><b><code>*</code>: </b>multiplication</li> 20768e3e3a7aSWarner Losh<li><b><code>/</code>: </b>float division</li> 20778e3e3a7aSWarner Losh<li><b><code>//</code>: </b>floor division</li> 20788e3e3a7aSWarner Losh<li><b><code>%</code>: </b>modulo</li> 20798e3e3a7aSWarner Losh<li><b><code>^</code>: </b>exponentiation</li> 20808e3e3a7aSWarner Losh<li><b><code>-</code>: </b>unary minus</li> 20818e3e3a7aSWarner Losh</ul> 20828e3e3a7aSWarner Losh 20838e3e3a7aSWarner Losh<p> 20848e3e3a7aSWarner LoshWith the exception of exponentiation and float division, 20858e3e3a7aSWarner Loshthe arithmetic operators work as follows: 20868e3e3a7aSWarner LoshIf both operands are integers, 20878e3e3a7aSWarner Loshthe operation is performed over integers and the result is an integer. 20880495ed39SKyle EvansOtherwise, if both operands are numbers, 20898e3e3a7aSWarner Loshthen they are converted to floats, 20900495ed39SKyle Evansthe operation is performed following the machine's rules 20918e3e3a7aSWarner Loshfor floating-point arithmetic 20928e3e3a7aSWarner Losh(usually the IEEE 754 standard), 20938e3e3a7aSWarner Loshand the result is a float. 20940495ed39SKyle Evans(The string library coerces strings to numbers in 20950495ed39SKyle Evansarithmetic operations; see <a href="#3.4.3">§3.4.3</a> for details.) 20968e3e3a7aSWarner Losh 20978e3e3a7aSWarner Losh 20988e3e3a7aSWarner Losh<p> 20998e3e3a7aSWarner LoshExponentiation and float division (<code>/</code>) 21008e3e3a7aSWarner Loshalways convert their operands to floats 21018e3e3a7aSWarner Loshand the result is always a float. 21028e3e3a7aSWarner LoshExponentiation uses the ISO C function <code>pow</code>, 21038e3e3a7aSWarner Loshso that it works for non-integer exponents too. 21048e3e3a7aSWarner Losh 21058e3e3a7aSWarner Losh 21068e3e3a7aSWarner Losh<p> 21078e3e3a7aSWarner LoshFloor division (<code>//</code>) is a division 21088e3e3a7aSWarner Loshthat rounds the quotient towards minus infinity, 21090495ed39SKyle Evansresulting in the floor of the division of its operands. 21108e3e3a7aSWarner Losh 21118e3e3a7aSWarner Losh 21128e3e3a7aSWarner Losh<p> 21138e3e3a7aSWarner LoshModulo is defined as the remainder of a division 21148e3e3a7aSWarner Loshthat rounds the quotient towards minus infinity (floor division). 21158e3e3a7aSWarner Losh 21168e3e3a7aSWarner Losh 21178e3e3a7aSWarner Losh<p> 21188e3e3a7aSWarner LoshIn case of overflows in integer arithmetic, 21190495ed39SKyle Evansall operations <em>wrap around</em>. 21208e3e3a7aSWarner Losh 21218e3e3a7aSWarner Losh 21228e3e3a7aSWarner Losh 21238e3e3a7aSWarner Losh<h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p> 21248e3e3a7aSWarner LoshLua supports the following bitwise operators: 21258e3e3a7aSWarner Losh 21268e3e3a7aSWarner Losh<ul> 21278e3e3a7aSWarner Losh<li><b><code>&</code>: </b>bitwise AND</li> 21288e3e3a7aSWarner Losh<li><b><code>|</code>: </b>bitwise OR</li> 21298e3e3a7aSWarner Losh<li><b><code>~</code>: </b>bitwise exclusive OR</li> 21308e3e3a7aSWarner Losh<li><b><code>>></code>: </b>right shift</li> 21318e3e3a7aSWarner Losh<li><b><code><<</code>: </b>left shift</li> 21328e3e3a7aSWarner Losh<li><b><code>~</code>: </b>unary bitwise NOT</li> 21338e3e3a7aSWarner Losh</ul> 21348e3e3a7aSWarner Losh 21358e3e3a7aSWarner Losh<p> 21368e3e3a7aSWarner LoshAll bitwise operations convert its operands to integers 21378e3e3a7aSWarner Losh(see <a href="#3.4.3">§3.4.3</a>), 21388e3e3a7aSWarner Loshoperate on all bits of those integers, 21398e3e3a7aSWarner Loshand result in an integer. 21408e3e3a7aSWarner Losh 21418e3e3a7aSWarner Losh 21428e3e3a7aSWarner Losh<p> 21438e3e3a7aSWarner LoshBoth right and left shifts fill the vacant bits with zeros. 21448e3e3a7aSWarner LoshNegative displacements shift to the other direction; 21458e3e3a7aSWarner Loshdisplacements with absolute values equal to or higher than 21468e3e3a7aSWarner Loshthe number of bits in an integer 21478e3e3a7aSWarner Loshresult in zero (as all bits are shifted out). 21488e3e3a7aSWarner Losh 21498e3e3a7aSWarner Losh 21508e3e3a7aSWarner Losh 21518e3e3a7aSWarner Losh 21528e3e3a7aSWarner Losh 21538e3e3a7aSWarner Losh<h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p> 21548e3e3a7aSWarner LoshLua provides some automatic conversions between some 21558e3e3a7aSWarner Loshtypes and representations at run time. 21568e3e3a7aSWarner LoshBitwise operators always convert float operands to integers. 21578e3e3a7aSWarner LoshExponentiation and float division 21588e3e3a7aSWarner Loshalways convert integer operands to floats. 21598e3e3a7aSWarner LoshAll other arithmetic operations applied to mixed numbers 21600495ed39SKyle Evans(integers and floats) convert the integer operand to a float. 21618e3e3a7aSWarner LoshThe C API also converts both integers to floats and 21628e3e3a7aSWarner Loshfloats to integers, as needed. 21638e3e3a7aSWarner LoshMoreover, string concatenation accepts numbers as arguments, 21648e3e3a7aSWarner Loshbesides strings. 21658e3e3a7aSWarner Losh 21668e3e3a7aSWarner Losh 21678e3e3a7aSWarner Losh<p> 21688e3e3a7aSWarner LoshIn a conversion from integer to float, 21698e3e3a7aSWarner Loshif the integer value has an exact representation as a float, 21708e3e3a7aSWarner Loshthat is the result. 21718e3e3a7aSWarner LoshOtherwise, 21728e3e3a7aSWarner Loshthe conversion gets the nearest higher or 21738e3e3a7aSWarner Loshthe nearest lower representable value. 21748e3e3a7aSWarner LoshThis kind of conversion never fails. 21758e3e3a7aSWarner Losh 21768e3e3a7aSWarner Losh 21778e3e3a7aSWarner Losh<p> 21788e3e3a7aSWarner LoshThe conversion from float to integer 21798e3e3a7aSWarner Loshchecks whether the float has an exact representation as an integer 21808e3e3a7aSWarner Losh(that is, the float has an integral value and 21818e3e3a7aSWarner Loshit is in the range of integer representation). 21828e3e3a7aSWarner LoshIf it does, that representation is the result. 21838e3e3a7aSWarner LoshOtherwise, the conversion fails. 21848e3e3a7aSWarner Losh 21858e3e3a7aSWarner Losh 21868e3e3a7aSWarner Losh<p> 21870495ed39SKyle EvansSeveral places in Lua coerce strings to numbers when necessary. 21880495ed39SKyle EvansIn particular, 21890495ed39SKyle Evansthe string library sets metamethods that try to coerce 21900495ed39SKyle Evansstrings to numbers in all arithmetic operations. 21910495ed39SKyle EvansIf the conversion fails, 21920495ed39SKyle Evansthe library calls the metamethod of the other operand 21930495ed39SKyle Evans(if present) or it raises an error. 21940495ed39SKyle EvansNote that bitwise operators do not do this coercion. 21958e3e3a7aSWarner Losh 21968e3e3a7aSWarner Losh 21978e3e3a7aSWarner Losh<p> 2198*a9490b81SWarner LoshIt is always a good practice not to rely on the 2199*a9490b81SWarner Loshimplicit coercions from strings to numbers, 2200*a9490b81SWarner Loshas they are not always applied; 22010495ed39SKyle Evansin particular, <code>"1"==1</code> is false and <code>"1"<1</code> raises an error 22020495ed39SKyle Evans(see <a href="#3.4.4">§3.4.4</a>). 22030495ed39SKyle EvansThese coercions exist mainly for compatibility and may be removed 22040495ed39SKyle Evansin future versions of the language. 22050495ed39SKyle Evans 22060495ed39SKyle Evans 22070495ed39SKyle Evans<p> 22080495ed39SKyle EvansA string is converted to an integer or a float 22090495ed39SKyle Evansfollowing its syntax and the rules of the Lua lexer. 22100495ed39SKyle EvansThe string may have also leading and trailing whitespaces and a sign. 22118e3e3a7aSWarner LoshAll conversions from strings to numbers 22128e3e3a7aSWarner Loshaccept both a dot and the current locale mark 22138e3e3a7aSWarner Loshas the radix character. 22148e3e3a7aSWarner Losh(The Lua lexer, however, accepts only a dot.) 22150495ed39SKyle EvansIf the string is not a valid numeral, 22160495ed39SKyle Evansthe conversion fails. 22170495ed39SKyle EvansIf necessary, the result of this first step is then converted 22180495ed39SKyle Evansto a specific number subtype following the previous rules 22190495ed39SKyle Evansfor conversions between floats and integers. 22208e3e3a7aSWarner Losh 22218e3e3a7aSWarner Losh 22228e3e3a7aSWarner Losh<p> 22238e3e3a7aSWarner LoshThe conversion from numbers to strings uses a 22248e3e3a7aSWarner Loshnon-specified human-readable format. 22250495ed39SKyle EvansTo convert numbers to strings in any specific way, 22260495ed39SKyle Evansuse the function <a href="#pdf-string.format"><code>string.format</code></a>. 22278e3e3a7aSWarner Losh 22288e3e3a7aSWarner Losh 22298e3e3a7aSWarner Losh 22308e3e3a7aSWarner Losh 22318e3e3a7aSWarner Losh 22328e3e3a7aSWarner Losh<h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p> 22338e3e3a7aSWarner LoshLua supports the following relational operators: 22348e3e3a7aSWarner Losh 22358e3e3a7aSWarner Losh<ul> 22368e3e3a7aSWarner Losh<li><b><code>==</code>: </b>equality</li> 22378e3e3a7aSWarner Losh<li><b><code>~=</code>: </b>inequality</li> 22388e3e3a7aSWarner Losh<li><b><code><</code>: </b>less than</li> 22398e3e3a7aSWarner Losh<li><b><code>></code>: </b>greater than</li> 22408e3e3a7aSWarner Losh<li><b><code><=</code>: </b>less or equal</li> 22418e3e3a7aSWarner Losh<li><b><code>>=</code>: </b>greater or equal</li> 22428e3e3a7aSWarner Losh</ul><p> 22438e3e3a7aSWarner LoshThese operators always result in <b>false</b> or <b>true</b>. 22448e3e3a7aSWarner Losh 22458e3e3a7aSWarner Losh 22468e3e3a7aSWarner Losh<p> 22478e3e3a7aSWarner LoshEquality (<code>==</code>) first compares the type of its operands. 22488e3e3a7aSWarner LoshIf the types are different, then the result is <b>false</b>. 22498e3e3a7aSWarner LoshOtherwise, the values of the operands are compared. 22500495ed39SKyle EvansStrings are equal if they have the same byte content. 22518e3e3a7aSWarner LoshNumbers are equal if they denote the same mathematical value. 22528e3e3a7aSWarner Losh 22538e3e3a7aSWarner Losh 22548e3e3a7aSWarner Losh<p> 22558e3e3a7aSWarner LoshTables, userdata, and threads 22568e3e3a7aSWarner Loshare compared by reference: 22578e3e3a7aSWarner Loshtwo objects are considered equal only if they are the same object. 22588e3e3a7aSWarner LoshEvery time you create a new object 22590495ed39SKyle Evans(a table, a userdata, or a thread), 22608e3e3a7aSWarner Loshthis new object is different from any previously existing object. 22610495ed39SKyle EvansA function is always equal to itself. 22620495ed39SKyle EvansFunctions with any detectable difference 22638e3e3a7aSWarner Losh(different behavior, different definition) are always different. 22640495ed39SKyle EvansFunctions created at different times but with no detectable differences 2265e112e9d2SKyle Evansmay be classified as equal or not 2266e112e9d2SKyle Evans(depending on internal caching details). 22678e3e3a7aSWarner Losh 22688e3e3a7aSWarner Losh 22698e3e3a7aSWarner Losh<p> 22708e3e3a7aSWarner LoshYou can change the way that Lua compares tables and userdata 22710495ed39SKyle Evansby using the <code>__eq</code> metamethod (see <a href="#2.4">§2.4</a>). 22728e3e3a7aSWarner Losh 22738e3e3a7aSWarner Losh 22748e3e3a7aSWarner Losh<p> 22758e3e3a7aSWarner LoshEquality comparisons do not convert strings to numbers 22768e3e3a7aSWarner Loshor vice versa. 22778e3e3a7aSWarner LoshThus, <code>"0"==0</code> evaluates to <b>false</b>, 22788e3e3a7aSWarner Loshand <code>t[0]</code> and <code>t["0"]</code> denote different 22798e3e3a7aSWarner Loshentries in a table. 22808e3e3a7aSWarner Losh 22818e3e3a7aSWarner Losh 22828e3e3a7aSWarner Losh<p> 22838e3e3a7aSWarner LoshThe operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 22848e3e3a7aSWarner Losh 22858e3e3a7aSWarner Losh 22868e3e3a7aSWarner Losh<p> 22878e3e3a7aSWarner LoshThe order operators work as follows. 22888e3e3a7aSWarner LoshIf both arguments are numbers, 22890495ed39SKyle Evansthen they are compared according to their mathematical values, 22900495ed39SKyle Evansregardless of their subtypes. 22918e3e3a7aSWarner LoshOtherwise, if both arguments are strings, 22928e3e3a7aSWarner Loshthen their values are compared according to the current locale. 22930495ed39SKyle EvansOtherwise, Lua tries to call the <code>__lt</code> or the <code>__le</code> 22948e3e3a7aSWarner Loshmetamethod (see <a href="#2.4">§2.4</a>). 22958e3e3a7aSWarner LoshA comparison <code>a > b</code> is translated to <code>b < a</code> 22968e3e3a7aSWarner Loshand <code>a >= b</code> is translated to <code>b <= a</code>. 22978e3e3a7aSWarner Losh 22988e3e3a7aSWarner Losh 22998e3e3a7aSWarner Losh<p> 23008e3e3a7aSWarner LoshFollowing the IEEE 754 standard, 23010495ed39SKyle Evansthe special value NaN is considered neither less than, 23020495ed39SKyle Evansnor equal to, nor greater than any value, including itself. 23038e3e3a7aSWarner Losh 23048e3e3a7aSWarner Losh 23058e3e3a7aSWarner Losh 23068e3e3a7aSWarner Losh 23078e3e3a7aSWarner Losh 23088e3e3a7aSWarner Losh<h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p> 23098e3e3a7aSWarner LoshThe logical operators in Lua are 23108e3e3a7aSWarner Losh<b>and</b>, <b>or</b>, and <b>not</b>. 23118e3e3a7aSWarner LoshLike the control structures (see <a href="#3.3.4">§3.3.4</a>), 23128e3e3a7aSWarner Loshall logical operators consider both <b>false</b> and <b>nil</b> as false 23138e3e3a7aSWarner Loshand anything else as true. 23148e3e3a7aSWarner Losh 23158e3e3a7aSWarner Losh 23168e3e3a7aSWarner Losh<p> 23178e3e3a7aSWarner LoshThe negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 23188e3e3a7aSWarner LoshThe conjunction operator <b>and</b> returns its first argument 23198e3e3a7aSWarner Loshif this value is <b>false</b> or <b>nil</b>; 23208e3e3a7aSWarner Loshotherwise, <b>and</b> returns its second argument. 23218e3e3a7aSWarner LoshThe disjunction operator <b>or</b> returns its first argument 23228e3e3a7aSWarner Loshif this value is different from <b>nil</b> and <b>false</b>; 23238e3e3a7aSWarner Loshotherwise, <b>or</b> returns its second argument. 23248e3e3a7aSWarner LoshBoth <b>and</b> and <b>or</b> use short-circuit evaluation; 23258e3e3a7aSWarner Loshthat is, 23268e3e3a7aSWarner Loshthe second operand is evaluated only if necessary. 23278e3e3a7aSWarner LoshHere are some examples: 23288e3e3a7aSWarner Losh 23298e3e3a7aSWarner Losh<pre> 23308e3e3a7aSWarner Losh 10 or 20 --> 10 23318e3e3a7aSWarner Losh 10 or error() --> 10 23328e3e3a7aSWarner Losh nil or "a" --> "a" 23338e3e3a7aSWarner Losh nil and 10 --> nil 23348e3e3a7aSWarner Losh false and error() --> false 23358e3e3a7aSWarner Losh false and nil --> false 23368e3e3a7aSWarner Losh false or nil --> nil 23378e3e3a7aSWarner Losh 10 and 20 --> 20 23380495ed39SKyle Evans</pre> 23398e3e3a7aSWarner Losh 23408e3e3a7aSWarner Losh 23418e3e3a7aSWarner Losh 23428e3e3a7aSWarner Losh 23438e3e3a7aSWarner Losh<h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p> 23448e3e3a7aSWarner LoshThe string concatenation operator in Lua is 23458e3e3a7aSWarner Loshdenoted by two dots ('<code>..</code>'). 23460495ed39SKyle EvansIf both operands are strings or numbers, 23470495ed39SKyle Evansthen the numbers are converted to strings 23480495ed39SKyle Evansin a non-specified format (see <a href="#3.4.3">§3.4.3</a>). 23498e3e3a7aSWarner LoshOtherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). 23508e3e3a7aSWarner Losh 23518e3e3a7aSWarner Losh 23528e3e3a7aSWarner Losh 23538e3e3a7aSWarner Losh 23548e3e3a7aSWarner Losh 23558e3e3a7aSWarner Losh<h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3> 23568e3e3a7aSWarner Losh 23578e3e3a7aSWarner Losh<p> 23588e3e3a7aSWarner LoshThe length operator is denoted by the unary prefix operator <code>#</code>. 23598e3e3a7aSWarner Losh 23608e3e3a7aSWarner Losh 23618e3e3a7aSWarner Losh<p> 23620495ed39SKyle EvansThe length of a string is its number of bytes. 23630495ed39SKyle Evans(That is the usual meaning of string length when each 23640495ed39SKyle Evanscharacter is one byte.) 23658e3e3a7aSWarner Losh 23668e3e3a7aSWarner Losh 23678e3e3a7aSWarner Losh<p> 23688e3e3a7aSWarner LoshThe length operator applied on a table 23698e3e3a7aSWarner Loshreturns a border in that table. 23708c784bb8SWarner LoshA <em>border</em> in a table <code>t</code> is any non-negative integer 23718e3e3a7aSWarner Loshthat satisfies the following condition: 23728e3e3a7aSWarner Losh 23738e3e3a7aSWarner Losh<pre> 23748c784bb8SWarner Losh (border == 0 or t[border] ~= nil) and 23758c784bb8SWarner Losh (t[border + 1] == nil or border == math.maxinteger) 23768e3e3a7aSWarner Losh</pre><p> 23778e3e3a7aSWarner LoshIn words, 23788c784bb8SWarner Losha border is any positive integer index present in the table 23798c784bb8SWarner Loshthat is followed by an absent index, 23808c784bb8SWarner Loshplus two limit cases: 23818c784bb8SWarner Loshzero, when index 1 is absent; 23828c784bb8SWarner Loshand the maximum value for an integer, when that index is present. 23838c784bb8SWarner LoshNote that keys that are not positive integers 23848c784bb8SWarner Loshdo not interfere with borders. 23858e3e3a7aSWarner Losh 23868e3e3a7aSWarner Losh 23878e3e3a7aSWarner Losh<p> 23888e3e3a7aSWarner LoshA table with exactly one border is called a <em>sequence</em>. 23898e3e3a7aSWarner LoshFor instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence, 23908e3e3a7aSWarner Loshas it has only one border (5). 23918e3e3a7aSWarner LoshThe table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5), 23928e3e3a7aSWarner Loshand therefore it is not a sequence. 23930495ed39SKyle Evans(The <b>nil</b> at index 4 is called a <em>hole</em>.) 23948e3e3a7aSWarner LoshThe table <code>{nil, 20, 30, nil, nil, 60, nil}</code> 23958c784bb8SWarner Loshhas three borders (0, 3, and 6), 23968e3e3a7aSWarner Loshso it is not a sequence, too. 23978e3e3a7aSWarner LoshThe table <code>{}</code> is a sequence with border 0. 23988e3e3a7aSWarner Losh 23998e3e3a7aSWarner Losh 24008e3e3a7aSWarner Losh<p> 24018e3e3a7aSWarner LoshWhen <code>t</code> is a sequence, 24028e3e3a7aSWarner Losh<code>#t</code> returns its only border, 24038e3e3a7aSWarner Loshwhich corresponds to the intuitive notion of the length of the sequence. 24048e3e3a7aSWarner LoshWhen <code>t</code> is not a sequence, 24058e3e3a7aSWarner Losh<code>#t</code> can return any of its borders. 24068e3e3a7aSWarner Losh(The exact one depends on details of 24078e3e3a7aSWarner Loshthe internal representation of the table, 24088e3e3a7aSWarner Loshwhich in turn can depend on how the table was populated and 24098e3e3a7aSWarner Loshthe memory addresses of its non-numeric keys.) 24108e3e3a7aSWarner Losh 24118e3e3a7aSWarner Losh 24128e3e3a7aSWarner Losh<p> 24138e3e3a7aSWarner LoshThe computation of the length of a table 24148e3e3a7aSWarner Loshhas a guaranteed worst time of <em>O(log n)</em>, 24158c784bb8SWarner Loshwhere <em>n</em> is the largest integer key in the table. 24168e3e3a7aSWarner Losh 24178e3e3a7aSWarner Losh 24188e3e3a7aSWarner Losh<p> 24198e3e3a7aSWarner LoshA program can modify the behavior of the length operator for 24208e3e3a7aSWarner Loshany value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>). 24218e3e3a7aSWarner Losh 24228e3e3a7aSWarner Losh 24238e3e3a7aSWarner Losh 24248e3e3a7aSWarner Losh 24258e3e3a7aSWarner Losh 24268e3e3a7aSWarner Losh<h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p> 24278e3e3a7aSWarner LoshOperator precedence in Lua follows the table below, 24288e3e3a7aSWarner Loshfrom lower to higher priority: 24298e3e3a7aSWarner Losh 24308e3e3a7aSWarner Losh<pre> 24318e3e3a7aSWarner Losh or 24328e3e3a7aSWarner Losh and 24338e3e3a7aSWarner Losh < > <= >= ~= == 24348e3e3a7aSWarner Losh | 24358e3e3a7aSWarner Losh ~ 24368e3e3a7aSWarner Losh & 24378e3e3a7aSWarner Losh << >> 24388e3e3a7aSWarner Losh .. 24398e3e3a7aSWarner Losh + - 24408e3e3a7aSWarner Losh * / // % 24418e3e3a7aSWarner Losh unary operators (not # - ~) 24428e3e3a7aSWarner Losh ^ 24438e3e3a7aSWarner Losh</pre><p> 24448e3e3a7aSWarner LoshAs usual, 24458e3e3a7aSWarner Loshyou can use parentheses to change the precedences of an expression. 24468e3e3a7aSWarner LoshThe concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 24478e3e3a7aSWarner Loshoperators are right associative. 24488e3e3a7aSWarner LoshAll other binary operators are left associative. 24498e3e3a7aSWarner Losh 24508e3e3a7aSWarner Losh 24518e3e3a7aSWarner Losh 24528e3e3a7aSWarner Losh 24538e3e3a7aSWarner Losh 24548e3e3a7aSWarner Losh<h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p> 24558e3e3a7aSWarner LoshTable constructors are expressions that create tables. 24568e3e3a7aSWarner LoshEvery time a constructor is evaluated, a new table is created. 24578e3e3a7aSWarner LoshA constructor can be used to create an empty table 24588e3e3a7aSWarner Loshor to create a table and initialize some of its fields. 24598e3e3a7aSWarner LoshThe general syntax for constructors is 24608e3e3a7aSWarner Losh 24618e3e3a7aSWarner Losh<pre> 24628e3e3a7aSWarner Losh tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 24638e3e3a7aSWarner Losh fieldlist ::= field {fieldsep field} [fieldsep] 24648e3e3a7aSWarner Losh field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 24658e3e3a7aSWarner Losh fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 24668e3e3a7aSWarner Losh</pre> 24678e3e3a7aSWarner Losh 24688e3e3a7aSWarner Losh<p> 24698e3e3a7aSWarner LoshEach field of the form <code>[exp1] = exp2</code> adds to the new table an entry 24708e3e3a7aSWarner Loshwith key <code>exp1</code> and value <code>exp2</code>. 24718e3e3a7aSWarner LoshA field of the form <code>name = exp</code> is equivalent to 24728e3e3a7aSWarner Losh<code>["name"] = exp</code>. 24730495ed39SKyle EvansFields of the form <code>exp</code> are equivalent to 24748e3e3a7aSWarner Losh<code>[i] = exp</code>, where <code>i</code> are consecutive integers 24750495ed39SKyle Evansstarting with 1; 24760495ed39SKyle Evansfields in the other formats do not affect this counting. 24778e3e3a7aSWarner LoshFor example, 24788e3e3a7aSWarner Losh 24798e3e3a7aSWarner Losh<pre> 24808e3e3a7aSWarner Losh a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 24818e3e3a7aSWarner Losh</pre><p> 24828e3e3a7aSWarner Loshis equivalent to 24838e3e3a7aSWarner Losh 24848e3e3a7aSWarner Losh<pre> 24858e3e3a7aSWarner Losh do 24868e3e3a7aSWarner Losh local t = {} 24878e3e3a7aSWarner Losh t[f(1)] = g 24888e3e3a7aSWarner Losh t[1] = "x" -- 1st exp 24898e3e3a7aSWarner Losh t[2] = "y" -- 2nd exp 24908e3e3a7aSWarner Losh t.x = 1 -- t["x"] = 1 24918e3e3a7aSWarner Losh t[3] = f(x) -- 3rd exp 24928e3e3a7aSWarner Losh t[30] = 23 24938e3e3a7aSWarner Losh t[4] = 45 -- 4th exp 24948e3e3a7aSWarner Losh a = t 24958e3e3a7aSWarner Losh end 24968e3e3a7aSWarner Losh</pre> 24978e3e3a7aSWarner Losh 24988e3e3a7aSWarner Losh<p> 24998e3e3a7aSWarner LoshThe order of the assignments in a constructor is undefined. 25008e3e3a7aSWarner Losh(This order would be relevant only when there are repeated keys.) 25018e3e3a7aSWarner Losh 25028e3e3a7aSWarner Losh 25038e3e3a7aSWarner Losh<p> 25048e3e3a7aSWarner LoshIf the last field in the list has the form <code>exp</code> 2505*a9490b81SWarner Loshand the expression is a multires expression, 25068e3e3a7aSWarner Loshthen all values returned by this expression enter the list consecutively 2507*a9490b81SWarner Losh(see <a href="#3.4.12">§3.4.12</a>). 25088e3e3a7aSWarner Losh 25098e3e3a7aSWarner Losh 25108e3e3a7aSWarner Losh<p> 25118e3e3a7aSWarner LoshThe field list can have an optional trailing separator, 25128e3e3a7aSWarner Loshas a convenience for machine-generated code. 25138e3e3a7aSWarner Losh 25148e3e3a7aSWarner Losh 25158e3e3a7aSWarner Losh 25168e3e3a7aSWarner Losh 25178e3e3a7aSWarner Losh 25188e3e3a7aSWarner Losh<h3>3.4.10 – <a name="3.4.10">Function Calls</a></h3><p> 25198e3e3a7aSWarner LoshA function call in Lua has the following syntax: 25208e3e3a7aSWarner Losh 25218e3e3a7aSWarner Losh<pre> 25228e3e3a7aSWarner Losh functioncall ::= prefixexp args 25238e3e3a7aSWarner Losh</pre><p> 25248e3e3a7aSWarner LoshIn a function call, 25258e3e3a7aSWarner Loshfirst prefixexp and args are evaluated. 25268e3e3a7aSWarner LoshIf the value of prefixexp has type <em>function</em>, 25278e3e3a7aSWarner Loshthen this function is called 25288e3e3a7aSWarner Loshwith the given arguments. 25290495ed39SKyle EvansOtherwise, if present, 25300495ed39SKyle Evansthe prefixexp <code>__call</code> metamethod is called: 25310495ed39SKyle Evansits first argument is the value of prefixexp, 25328e3e3a7aSWarner Loshfollowed by the original call arguments 25338e3e3a7aSWarner Losh(see <a href="#2.4">§2.4</a>). 25348e3e3a7aSWarner Losh 25358e3e3a7aSWarner Losh 25368e3e3a7aSWarner Losh<p> 25378e3e3a7aSWarner LoshThe form 25388e3e3a7aSWarner Losh 25398e3e3a7aSWarner Losh<pre> 25408e3e3a7aSWarner Losh functioncall ::= prefixexp ‘<b>:</b>’ Name args 25418e3e3a7aSWarner Losh</pre><p> 25420495ed39SKyle Evanscan be used to emulate methods. 25438e3e3a7aSWarner LoshA call <code>v:name(<em>args</em>)</code> 25448e3e3a7aSWarner Loshis syntactic sugar for <code>v.name(v,<em>args</em>)</code>, 25458e3e3a7aSWarner Loshexcept that <code>v</code> is evaluated only once. 25468e3e3a7aSWarner Losh 25478e3e3a7aSWarner Losh 25488e3e3a7aSWarner Losh<p> 25498e3e3a7aSWarner LoshArguments have the following syntax: 25508e3e3a7aSWarner Losh 25518e3e3a7aSWarner Losh<pre> 25528e3e3a7aSWarner Losh args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ 25538e3e3a7aSWarner Losh args ::= tableconstructor 25548e3e3a7aSWarner Losh args ::= LiteralString 25558e3e3a7aSWarner Losh</pre><p> 25568e3e3a7aSWarner LoshAll argument expressions are evaluated before the call. 25578e3e3a7aSWarner LoshA call of the form <code>f{<em>fields</em>}</code> is 25588e3e3a7aSWarner Loshsyntactic sugar for <code>f({<em>fields</em>})</code>; 25598e3e3a7aSWarner Loshthat is, the argument list is a single new table. 25608e3e3a7aSWarner LoshA call of the form <code>f'<em>string</em>'</code> 25618e3e3a7aSWarner Losh(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 25628e3e3a7aSWarner Loshis syntactic sugar for <code>f('<em>string</em>')</code>; 25638e3e3a7aSWarner Loshthat is, the argument list is a single literal string. 25648e3e3a7aSWarner Losh 25658e3e3a7aSWarner Losh 25668e3e3a7aSWarner Losh<p> 25670495ed39SKyle EvansA call of the form <code>return <em>functioncall</em></code> not in the 25680495ed39SKyle Evansscope of a to-be-closed variable is called a <em>tail call</em>. 25698e3e3a7aSWarner LoshLua implements <em>proper tail calls</em> 25708e3e3a7aSWarner Losh(or <em>proper tail recursion</em>): 2571*a9490b81SWarner LoshIn a tail call, 25728e3e3a7aSWarner Loshthe called function reuses the stack entry of the calling function. 25738e3e3a7aSWarner LoshTherefore, there is no limit on the number of nested tail calls that 25748e3e3a7aSWarner Losha program can execute. 25758e3e3a7aSWarner LoshHowever, a tail call erases any debug information about the 25768e3e3a7aSWarner Loshcalling function. 25778e3e3a7aSWarner LoshNote that a tail call only happens with a particular syntax, 25780495ed39SKyle Evanswhere the <b>return</b> has one single function call as argument, 25790495ed39SKyle Evansand it is outside the scope of any to-be-closed variable. 25800495ed39SKyle EvansThis syntax makes the calling function return exactly 25810495ed39SKyle Evansthe returns of the called function, 25820495ed39SKyle Evanswithout any intervening action. 25838e3e3a7aSWarner LoshSo, none of the following examples are tail calls: 25848e3e3a7aSWarner Losh 25858e3e3a7aSWarner Losh<pre> 25868e3e3a7aSWarner Losh return (f(x)) -- results adjusted to 1 25870495ed39SKyle Evans return 2 * f(x) -- result multiplied by 2 25888e3e3a7aSWarner Losh return x, f(x) -- additional results 25898e3e3a7aSWarner Losh f(x); return -- results discarded 25908e3e3a7aSWarner Losh return x or f(x) -- results adjusted to 1 25918e3e3a7aSWarner Losh</pre> 25928e3e3a7aSWarner Losh 25938e3e3a7aSWarner Losh 25948e3e3a7aSWarner Losh 25958e3e3a7aSWarner Losh 25968e3e3a7aSWarner Losh<h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3> 25978e3e3a7aSWarner Losh 25988e3e3a7aSWarner Losh<p> 25998e3e3a7aSWarner LoshThe syntax for function definition is 26008e3e3a7aSWarner Losh 26018e3e3a7aSWarner Losh<pre> 26028e3e3a7aSWarner Losh functiondef ::= <b>function</b> funcbody 26038e3e3a7aSWarner Losh funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 26048e3e3a7aSWarner Losh</pre> 26058e3e3a7aSWarner Losh 26068e3e3a7aSWarner Losh<p> 26078e3e3a7aSWarner LoshThe following syntactic sugar simplifies function definitions: 26088e3e3a7aSWarner Losh 26098e3e3a7aSWarner Losh<pre> 26108e3e3a7aSWarner Losh stat ::= <b>function</b> funcname funcbody 26118e3e3a7aSWarner Losh stat ::= <b>local</b> <b>function</b> Name funcbody 26128e3e3a7aSWarner Losh funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 26138e3e3a7aSWarner Losh</pre><p> 26148e3e3a7aSWarner LoshThe statement 26158e3e3a7aSWarner Losh 26168e3e3a7aSWarner Losh<pre> 26178e3e3a7aSWarner Losh function f () <em>body</em> end 26188e3e3a7aSWarner Losh</pre><p> 26198e3e3a7aSWarner Loshtranslates to 26208e3e3a7aSWarner Losh 26218e3e3a7aSWarner Losh<pre> 26228e3e3a7aSWarner Losh f = function () <em>body</em> end 26238e3e3a7aSWarner Losh</pre><p> 26248e3e3a7aSWarner LoshThe statement 26258e3e3a7aSWarner Losh 26268e3e3a7aSWarner Losh<pre> 26278e3e3a7aSWarner Losh function t.a.b.c.f () <em>body</em> end 26288e3e3a7aSWarner Losh</pre><p> 26298e3e3a7aSWarner Loshtranslates to 26308e3e3a7aSWarner Losh 26318e3e3a7aSWarner Losh<pre> 26328e3e3a7aSWarner Losh t.a.b.c.f = function () <em>body</em> end 26338e3e3a7aSWarner Losh</pre><p> 26348e3e3a7aSWarner LoshThe statement 26358e3e3a7aSWarner Losh 26368e3e3a7aSWarner Losh<pre> 26378e3e3a7aSWarner Losh local function f () <em>body</em> end 26388e3e3a7aSWarner Losh</pre><p> 26398e3e3a7aSWarner Loshtranslates to 26408e3e3a7aSWarner Losh 26418e3e3a7aSWarner Losh<pre> 26428e3e3a7aSWarner Losh local f; f = function () <em>body</em> end 26438e3e3a7aSWarner Losh</pre><p> 26448e3e3a7aSWarner Loshnot to 26458e3e3a7aSWarner Losh 26468e3e3a7aSWarner Losh<pre> 26478e3e3a7aSWarner Losh local f = function () <em>body</em> end 26488e3e3a7aSWarner Losh</pre><p> 26498e3e3a7aSWarner Losh(This only makes a difference when the body of the function 26508e3e3a7aSWarner Loshcontains references to <code>f</code>.) 26518e3e3a7aSWarner Losh 26528e3e3a7aSWarner Losh 26538e3e3a7aSWarner Losh<p> 26548e3e3a7aSWarner LoshA function definition is an executable expression, 26558e3e3a7aSWarner Loshwhose value has type <em>function</em>. 26568e3e3a7aSWarner LoshWhen Lua precompiles a chunk, 26570495ed39SKyle Evansall its function bodies are precompiled too, 26580495ed39SKyle Evansbut they are not created yet. 26598e3e3a7aSWarner LoshThen, whenever Lua executes the function definition, 26608e3e3a7aSWarner Loshthe function is <em>instantiated</em> (or <em>closed</em>). 26610495ed39SKyle EvansThis function instance, or <em>closure</em>, 26628e3e3a7aSWarner Loshis the final value of the expression. 26638e3e3a7aSWarner Losh 26648e3e3a7aSWarner Losh 26658e3e3a7aSWarner Losh<p> 26668e3e3a7aSWarner LoshParameters act as local variables that are 26678e3e3a7aSWarner Loshinitialized with the argument values: 26688e3e3a7aSWarner Losh 26698e3e3a7aSWarner Losh<pre> 26708e3e3a7aSWarner Losh parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 26718e3e3a7aSWarner Losh</pre><p> 26720495ed39SKyle EvansWhen a Lua function is called, 26730495ed39SKyle Evansit adjusts its list of arguments to 2674*a9490b81SWarner Loshthe length of its list of parameters (see <a href="#3.4.12">§3.4.12</a>), 2675*a9490b81SWarner Loshunless the function is a <em>variadic function</em>, 26768e3e3a7aSWarner Loshwhich is indicated by three dots ('<code>...</code>') 26778e3e3a7aSWarner Loshat the end of its parameter list. 2678*a9490b81SWarner LoshA variadic function does not adjust its argument list; 26798e3e3a7aSWarner Loshinstead, it collects all extra arguments and supplies them 26808e3e3a7aSWarner Loshto the function through a <em>vararg expression</em>, 26818e3e3a7aSWarner Loshwhich is also written as three dots. 26828e3e3a7aSWarner LoshThe value of this expression is a list of all actual extra arguments, 2683*a9490b81SWarner Loshsimilar to a function with multiple results (see <a href="#3.4.12">§3.4.12</a>). 26848e3e3a7aSWarner Losh 26858e3e3a7aSWarner Losh 26868e3e3a7aSWarner Losh<p> 26878e3e3a7aSWarner LoshAs an example, consider the following definitions: 26888e3e3a7aSWarner Losh 26898e3e3a7aSWarner Losh<pre> 26908e3e3a7aSWarner Losh function f(a, b) end 26918e3e3a7aSWarner Losh function g(a, b, ...) end 26928e3e3a7aSWarner Losh function r() return 1,2,3 end 26938e3e3a7aSWarner Losh</pre><p> 26948e3e3a7aSWarner LoshThen, we have the following mapping from arguments to parameters and 26958e3e3a7aSWarner Loshto the vararg expression: 26968e3e3a7aSWarner Losh 26978e3e3a7aSWarner Losh<pre> 26988e3e3a7aSWarner Losh CALL PARAMETERS 26998e3e3a7aSWarner Losh 27008e3e3a7aSWarner Losh f(3) a=3, b=nil 27018e3e3a7aSWarner Losh f(3, 4) a=3, b=4 27028e3e3a7aSWarner Losh f(3, 4, 5) a=3, b=4 27038e3e3a7aSWarner Losh f(r(), 10) a=1, b=10 27048e3e3a7aSWarner Losh f(r()) a=1, b=2 27058e3e3a7aSWarner Losh 27068e3e3a7aSWarner Losh g(3) a=3, b=nil, ... --> (nothing) 27078e3e3a7aSWarner Losh g(3, 4) a=3, b=4, ... --> (nothing) 27088e3e3a7aSWarner Losh g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 27098e3e3a7aSWarner Losh g(5, r()) a=5, b=1, ... --> 2 3 27108e3e3a7aSWarner Losh</pre> 27118e3e3a7aSWarner Losh 27128e3e3a7aSWarner Losh<p> 27138e3e3a7aSWarner LoshResults are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>). 27148e3e3a7aSWarner LoshIf control reaches the end of a function 27158e3e3a7aSWarner Loshwithout encountering a <b>return</b> statement, 27168e3e3a7aSWarner Loshthen the function returns with no results. 27178e3e3a7aSWarner Losh 27188e3e3a7aSWarner Losh 27198e3e3a7aSWarner Losh<p> 27208e3e3a7aSWarner Losh 27218e3e3a7aSWarner LoshThere is a system-dependent limit on the number of values 27228e3e3a7aSWarner Loshthat a function may return. 27230495ed39SKyle EvansThis limit is guaranteed to be greater than 1000. 27248e3e3a7aSWarner Losh 27258e3e3a7aSWarner Losh 27268e3e3a7aSWarner Losh<p> 27278e3e3a7aSWarner LoshThe <em>colon</em> syntax 27280495ed39SKyle Evansis used to emulate <em>methods</em>, 27290495ed39SKyle Evansadding an implicit extra parameter <code>self</code> to the function. 27308e3e3a7aSWarner LoshThus, the statement 27318e3e3a7aSWarner Losh 27328e3e3a7aSWarner Losh<pre> 27338e3e3a7aSWarner Losh function t.a.b.c:f (<em>params</em>) <em>body</em> end 27348e3e3a7aSWarner Losh</pre><p> 27358e3e3a7aSWarner Loshis syntactic sugar for 27368e3e3a7aSWarner Losh 27378e3e3a7aSWarner Losh<pre> 27388e3e3a7aSWarner Losh t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end 27398e3e3a7aSWarner Losh</pre> 27408e3e3a7aSWarner Losh 27418e3e3a7aSWarner Losh 27428e3e3a7aSWarner Losh 27438e3e3a7aSWarner Losh 2744*a9490b81SWarner Losh<h3>3.4.12 – <a name="3.4.12">Lists of expressions, multiple results, 2745*a9490b81SWarner Loshand adjustment</a></h3> 2746*a9490b81SWarner Losh 2747*a9490b81SWarner Losh<p> 2748*a9490b81SWarner LoshBoth function calls and vararg expressions can result in multiple values. 2749*a9490b81SWarner LoshThese expressions are called <em>multires expressions</em>. 2750*a9490b81SWarner Losh 2751*a9490b81SWarner Losh 2752*a9490b81SWarner Losh<p> 2753*a9490b81SWarner LoshWhen a multires expression is used as the last element 2754*a9490b81SWarner Loshof a list of expressions, 2755*a9490b81SWarner Loshall results from the expression are added to the 2756*a9490b81SWarner Loshlist of values produced by the list of expressions. 2757*a9490b81SWarner LoshNote that a single expression 2758*a9490b81SWarner Loshin a place that expects a list of expressions 2759*a9490b81SWarner Loshis the last expression in that (singleton) list. 2760*a9490b81SWarner Losh 2761*a9490b81SWarner Losh 2762*a9490b81SWarner Losh<p> 2763*a9490b81SWarner LoshThese are the places where Lua expects a list of expressions: 2764*a9490b81SWarner Losh 2765*a9490b81SWarner Losh<ul> 2766*a9490b81SWarner Losh 2767*a9490b81SWarner Losh<li>A <b>return</b> statement, 2768*a9490b81SWarner Loshfor instance <code>return e1, e2, e3</code> (see <a href="#3.3.4">§3.3.4</a>).</li> 2769*a9490b81SWarner Losh 2770*a9490b81SWarner Losh<li>A table constructor, 2771*a9490b81SWarner Loshfor instance <code>{e1, e2, e3}</code> (see <a href="#3.4.9">§3.4.9</a>).</li> 2772*a9490b81SWarner Losh 2773*a9490b81SWarner Losh<li>The arguments of a function call, 2774*a9490b81SWarner Loshfor instance <code>foo(e1, e2, e3)</code> (see <a href="#3.4.10">§3.4.10</a>).</li> 2775*a9490b81SWarner Losh 2776*a9490b81SWarner Losh<li>A multiple assignment, 2777*a9490b81SWarner Loshfor instance <code>a , b, c = e1, e2, e3</code> (see <a href="#3.3.3">§3.3.3</a>).</li> 2778*a9490b81SWarner Losh 2779*a9490b81SWarner Losh<li>A local declaration, 2780*a9490b81SWarner Loshfor instance <code>local a , b, c = e1, e2, e3</code> (see <a href="#3.3.7">§3.3.7</a>).</li> 2781*a9490b81SWarner Losh 2782*a9490b81SWarner Losh<li>The initial values in a generic <b>for</b> loop, 2783*a9490b81SWarner Loshfor instance <code>for k in e1, e2, e3 do ... end</code> (see <a href="#3.3.5">§3.3.5</a>).</li> 2784*a9490b81SWarner Losh 2785*a9490b81SWarner Losh</ul><p> 2786*a9490b81SWarner LoshIn the last four cases, 2787*a9490b81SWarner Loshthe list of values from the list of expressions 2788*a9490b81SWarner Loshmust be <em>adjusted</em> to a specific length: 2789*a9490b81SWarner Loshthe number of parameters in a call to a non-variadic function 2790*a9490b81SWarner Losh(see <a href="#3.4.11">§3.4.11</a>), 2791*a9490b81SWarner Loshthe number of variables in a multiple assignment or 2792*a9490b81SWarner Losha local declaration, 2793*a9490b81SWarner Loshand exactly four values for a generic <b>for</b> loop. 2794*a9490b81SWarner LoshThe <em>adjustment</em> follows these rules: 2795*a9490b81SWarner LoshIf there are more values than needed, 2796*a9490b81SWarner Loshthe extra values are thrown away; 2797*a9490b81SWarner Loshif there are fewer values than needed, 2798*a9490b81SWarner Loshthe list is extended with <b>nil</b>'s. 2799*a9490b81SWarner LoshWhen the list of expressions ends with a multires expression, 2800*a9490b81SWarner Loshall results from that expression enter the list of values 2801*a9490b81SWarner Loshbefore the adjustment. 2802*a9490b81SWarner Losh 2803*a9490b81SWarner Losh 2804*a9490b81SWarner Losh<p> 2805*a9490b81SWarner LoshWhen a multires expression is used 2806*a9490b81SWarner Loshin a list of expressions without being the last element, 2807*a9490b81SWarner Loshor in a place where the syntax expects a single expression, 2808*a9490b81SWarner LoshLua adjusts the result list of that expression to one element. 2809*a9490b81SWarner LoshAs a particular case, 2810*a9490b81SWarner Loshthe syntax expects a single expression inside a parenthesized expression; 2811*a9490b81SWarner Loshtherefore, adding parentheses around a multires expression 2812*a9490b81SWarner Loshforces it to produce exactly one result. 2813*a9490b81SWarner Losh 2814*a9490b81SWarner Losh 2815*a9490b81SWarner Losh<p> 2816*a9490b81SWarner LoshWe seldom need to use a vararg expression in a place 2817*a9490b81SWarner Loshwhere the syntax expects a single expression. 2818*a9490b81SWarner Losh(Usually it is simpler to add a regular parameter before 2819*a9490b81SWarner Loshthe variadic part and use that parameter.) 2820*a9490b81SWarner LoshWhen there is such a need, 2821*a9490b81SWarner Loshwe recommend assigning the vararg expression 2822*a9490b81SWarner Loshto a single variable and using that variable 2823*a9490b81SWarner Loshin its place. 2824*a9490b81SWarner Losh 2825*a9490b81SWarner Losh 2826*a9490b81SWarner Losh<p> 2827*a9490b81SWarner LoshHere are some examples of uses of mutlres expressions. 2828*a9490b81SWarner LoshIn all cases, when the construction needs 2829*a9490b81SWarner Losh"the n-th result" and there is no such result, 2830*a9490b81SWarner Loshit uses a <b>nil</b>. 2831*a9490b81SWarner Losh 2832*a9490b81SWarner Losh<pre> 2833*a9490b81SWarner Losh print(x, f()) -- prints x and all results from f(). 2834*a9490b81SWarner Losh print(x, (f())) -- prints x and the first result from f(). 2835*a9490b81SWarner Losh print(f(), x) -- prints the first result from f() and x. 2836*a9490b81SWarner Losh print(1 + f()) -- prints 1 added to the first result from f(). 2837*a9490b81SWarner Losh local x = ... -- x gets the first vararg argument. 2838*a9490b81SWarner Losh x,y = ... -- x gets the first vararg argument, 2839*a9490b81SWarner Losh -- y gets the second vararg argument. 2840*a9490b81SWarner Losh x,y,z = w, f() -- x gets w, y gets the first result from f(), 2841*a9490b81SWarner Losh -- z gets the second result from f(). 2842*a9490b81SWarner Losh x,y,z = f() -- x gets the first result from f(), 2843*a9490b81SWarner Losh -- y gets the second result from f(), 2844*a9490b81SWarner Losh -- z gets the third result from f(). 2845*a9490b81SWarner Losh x,y,z = f(), g() -- x gets the first result from f(), 2846*a9490b81SWarner Losh -- y gets the first result from g(), 2847*a9490b81SWarner Losh -- z gets the second result from g(). 2848*a9490b81SWarner Losh x,y,z = (f()) -- x gets the first result from f(), y and z get nil. 2849*a9490b81SWarner Losh return f() -- returns all results from f(). 2850*a9490b81SWarner Losh return x, ... -- returns x and all received vararg arguments. 2851*a9490b81SWarner Losh return x,y,f() -- returns x, y, and all results from f(). 2852*a9490b81SWarner Losh {f()} -- creates a list with all results from f(). 2853*a9490b81SWarner Losh {...} -- creates a list with all vararg arguments. 2854*a9490b81SWarner Losh {f(), 5} -- creates a list with the first result from f() and 5. 2855*a9490b81SWarner Losh</pre> 2856*a9490b81SWarner Losh 2857*a9490b81SWarner Losh 2858*a9490b81SWarner Losh 2859*a9490b81SWarner Losh 28608e3e3a7aSWarner Losh 28618e3e3a7aSWarner Losh 28628e3e3a7aSWarner Losh<h2>3.5 – <a name="3.5">Visibility Rules</a></h2> 28638e3e3a7aSWarner Losh 28648e3e3a7aSWarner Losh<p> 28658e3e3a7aSWarner Losh 28668e3e3a7aSWarner LoshLua is a lexically scoped language. 28678e3e3a7aSWarner LoshThe scope of a local variable begins at the first statement after 28688e3e3a7aSWarner Loshits declaration and lasts until the last non-void statement 28698e3e3a7aSWarner Loshof the innermost block that includes the declaration. 2870*a9490b81SWarner Losh(<em>Void statements</em> are labels and empty statements.) 28718e3e3a7aSWarner LoshConsider the following example: 28728e3e3a7aSWarner Losh 28738e3e3a7aSWarner Losh<pre> 28748e3e3a7aSWarner Losh x = 10 -- global variable 28758e3e3a7aSWarner Losh do -- new block 28768e3e3a7aSWarner Losh local x = x -- new 'x', with value 10 28778e3e3a7aSWarner Losh print(x) --> 10 28788e3e3a7aSWarner Losh x = x+1 28798e3e3a7aSWarner Losh do -- another block 28808e3e3a7aSWarner Losh local x = x+1 -- another 'x' 28818e3e3a7aSWarner Losh print(x) --> 12 28828e3e3a7aSWarner Losh end 28838e3e3a7aSWarner Losh print(x) --> 11 28848e3e3a7aSWarner Losh end 28858e3e3a7aSWarner Losh print(x) --> 10 (the global one) 28868e3e3a7aSWarner Losh</pre> 28878e3e3a7aSWarner Losh 28888e3e3a7aSWarner Losh<p> 28898e3e3a7aSWarner LoshNotice that, in a declaration like <code>local x = x</code>, 28908e3e3a7aSWarner Loshthe new <code>x</code> being declared is not in scope yet, 28918e3e3a7aSWarner Loshand so the second <code>x</code> refers to the outside variable. 28928e3e3a7aSWarner Losh 28938e3e3a7aSWarner Losh 28948e3e3a7aSWarner Losh<p> 28958e3e3a7aSWarner LoshBecause of the lexical scoping rules, 28968e3e3a7aSWarner Loshlocal variables can be freely accessed by functions 28978e3e3a7aSWarner Loshdefined inside their scope. 28980495ed39SKyle EvansA local variable used by an inner function is called an <em>upvalue</em> 28990495ed39SKyle Evans(or <em>external local variable</em>, or simply <em>external variable</em>) 29008e3e3a7aSWarner Loshinside the inner function. 29018e3e3a7aSWarner Losh 29028e3e3a7aSWarner Losh 29038e3e3a7aSWarner Losh<p> 29048e3e3a7aSWarner LoshNotice that each execution of a <b>local</b> statement 29058e3e3a7aSWarner Loshdefines new local variables. 29068e3e3a7aSWarner LoshConsider the following example: 29078e3e3a7aSWarner Losh 29088e3e3a7aSWarner Losh<pre> 29098e3e3a7aSWarner Losh a = {} 29108e3e3a7aSWarner Losh local x = 20 29118e3e3a7aSWarner Losh for i = 1, 10 do 29128e3e3a7aSWarner Losh local y = 0 29138e3e3a7aSWarner Losh a[i] = function () y = y + 1; return x + y end 29148e3e3a7aSWarner Losh end 29158e3e3a7aSWarner Losh</pre><p> 29168e3e3a7aSWarner LoshThe loop creates ten closures 29178e3e3a7aSWarner Losh(that is, ten instances of the anonymous function). 29188e3e3a7aSWarner LoshEach of these closures uses a different <code>y</code> variable, 29198e3e3a7aSWarner Loshwhile all of them share the same <code>x</code>. 29208e3e3a7aSWarner Losh 29218e3e3a7aSWarner Losh 29228e3e3a7aSWarner Losh 29238e3e3a7aSWarner Losh 29248e3e3a7aSWarner Losh 29258e3e3a7aSWarner Losh<h1>4 – <a name="4">The Application Program Interface</a></h1> 29268e3e3a7aSWarner Losh 29270495ed39SKyle Evans 29280495ed39SKyle Evans 29298e3e3a7aSWarner Losh<p> 29308e3e3a7aSWarner Losh 29318e3e3a7aSWarner LoshThis section describes the C API for Lua, that is, 29328e3e3a7aSWarner Loshthe set of C functions available to the host program to communicate 29338e3e3a7aSWarner Loshwith Lua. 29348e3e3a7aSWarner LoshAll API functions and related types and constants 29358e3e3a7aSWarner Loshare declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. 29368e3e3a7aSWarner Losh 29378e3e3a7aSWarner Losh 29388e3e3a7aSWarner Losh<p> 29398e3e3a7aSWarner LoshEven when we use the term "function", 29408e3e3a7aSWarner Loshany facility in the API may be provided as a macro instead. 29418e3e3a7aSWarner LoshExcept where stated otherwise, 29428e3e3a7aSWarner Loshall such macros use each of their arguments exactly once 29438e3e3a7aSWarner Losh(except for the first argument, which is always a Lua state), 29448e3e3a7aSWarner Loshand so do not generate any hidden side-effects. 29458e3e3a7aSWarner Losh 29468e3e3a7aSWarner Losh 29478e3e3a7aSWarner Losh<p> 29488e3e3a7aSWarner LoshAs in most C libraries, 29490495ed39SKyle Evansthe Lua API functions do not check their arguments 29500495ed39SKyle Evansfor validity or consistency. 29518e3e3a7aSWarner LoshHowever, you can change this behavior by compiling Lua 29528e3e3a7aSWarner Loshwith the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined. 29538e3e3a7aSWarner Losh 29548e3e3a7aSWarner Losh 29558e3e3a7aSWarner Losh<p> 29568e3e3a7aSWarner LoshThe Lua library is fully reentrant: 29578e3e3a7aSWarner Loshit has no global variables. 29588e3e3a7aSWarner LoshIt keeps all information it needs in a dynamic structure, 29598e3e3a7aSWarner Loshcalled the <em>Lua state</em>. 29608e3e3a7aSWarner Losh 29618e3e3a7aSWarner Losh 29628e3e3a7aSWarner Losh<p> 29638e3e3a7aSWarner LoshEach Lua state has one or more threads, 29648e3e3a7aSWarner Loshwhich correspond to independent, cooperative lines of execution. 29658e3e3a7aSWarner LoshThe type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread. 29668e3e3a7aSWarner Losh(Indirectly, through the thread, it also refers to the 29678e3e3a7aSWarner LoshLua state associated to the thread.) 29688e3e3a7aSWarner Losh 29698e3e3a7aSWarner Losh 29708e3e3a7aSWarner Losh<p> 29718e3e3a7aSWarner LoshA pointer to a thread must be passed as the first argument to 29728e3e3a7aSWarner Loshevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 29738e3e3a7aSWarner Loshwhich creates a Lua state from scratch and returns a pointer 29748e3e3a7aSWarner Loshto the <em>main thread</em> in the new state. 29758e3e3a7aSWarner Losh 29768e3e3a7aSWarner Losh 29778e3e3a7aSWarner Losh 29780495ed39SKyle Evans 29790495ed39SKyle Evans 29808e3e3a7aSWarner Losh<h2>4.1 – <a name="4.1">The Stack</a></h2> 29818e3e3a7aSWarner Losh 29820495ed39SKyle Evans 29830495ed39SKyle Evans 29848e3e3a7aSWarner Losh<p> 29858e3e3a7aSWarner LoshLua uses a <em>virtual stack</em> to pass values to and from C. 29868e3e3a7aSWarner LoshEach element in this stack represents a Lua value 29878e3e3a7aSWarner Losh(<b>nil</b>, number, string, etc.). 29888e3e3a7aSWarner LoshFunctions in the API can access this stack through the 29898e3e3a7aSWarner LoshLua state parameter that they receive. 29908e3e3a7aSWarner Losh 29918e3e3a7aSWarner Losh 29928e3e3a7aSWarner Losh<p> 29938e3e3a7aSWarner LoshWhenever Lua calls C, the called function gets a new stack, 29948e3e3a7aSWarner Loshwhich is independent of previous stacks and of stacks of 29958e3e3a7aSWarner LoshC functions that are still active. 29968e3e3a7aSWarner LoshThis stack initially contains any arguments to the C function 29978e3e3a7aSWarner Loshand it is where the C function can store temporary 29988e3e3a7aSWarner LoshLua values and must push its results 29998e3e3a7aSWarner Loshto be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 30008e3e3a7aSWarner Losh 30018e3e3a7aSWarner Losh 30028e3e3a7aSWarner Losh<p> 30038e3e3a7aSWarner LoshFor convenience, 30048e3e3a7aSWarner Loshmost query operations in the API do not follow a strict stack discipline. 30058e3e3a7aSWarner LoshInstead, they can refer to any element in the stack 30068e3e3a7aSWarner Loshby using an <em>index</em>: 30070495ed39SKyle EvansA positive index represents an absolute stack position, 30080495ed39SKyle Evansstarting at 1 as the bottom of the stack; 30098e3e3a7aSWarner Losha negative index represents an offset relative to the top of the stack. 30108e3e3a7aSWarner LoshMore specifically, if the stack has <em>n</em> elements, 30118e3e3a7aSWarner Loshthen index 1 represents the first element 30128e3e3a7aSWarner Losh(that is, the element that was pushed onto the stack first) 30138e3e3a7aSWarner Loshand 30148e3e3a7aSWarner Loshindex <em>n</em> represents the last element; 30158e3e3a7aSWarner Loshindex -1 also represents the last element 30168e3e3a7aSWarner Losh(that is, the element at the top) 30178e3e3a7aSWarner Loshand index <em>-n</em> represents the first element. 30188e3e3a7aSWarner Losh 30198e3e3a7aSWarner Losh 30208e3e3a7aSWarner Losh 30218e3e3a7aSWarner Losh 30228e3e3a7aSWarner Losh 30230495ed39SKyle Evans<h3>4.1.1 – <a name="4.1.1">Stack Size</a></h3> 30248e3e3a7aSWarner Losh 30258e3e3a7aSWarner Losh<p> 30268e3e3a7aSWarner LoshWhen you interact with the Lua API, 30278e3e3a7aSWarner Loshyou are responsible for ensuring consistency. 30288e3e3a7aSWarner LoshIn particular, 30298e3e3a7aSWarner Losh<em>you are responsible for controlling stack overflow</em>. 30300495ed39SKyle EvansWhen you call any API function, 30310495ed39SKyle Evansyou must ensure the stack has enough room to accommodate the results. 30320495ed39SKyle Evans 30330495ed39SKyle Evans 30340495ed39SKyle Evans<p> 30350495ed39SKyle EvansThere is one exception to the above rule: 30360495ed39SKyle EvansWhen you call a Lua function 30370495ed39SKyle Evanswithout a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>), 30380495ed39SKyle EvansLua ensures that the stack has enough space for all results. 30390495ed39SKyle EvansHowever, it does not ensure any extra space. 30400495ed39SKyle EvansSo, before pushing anything on the stack after such a call 30410495ed39SKyle Evansyou should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>. 30428e3e3a7aSWarner Losh 30438e3e3a7aSWarner Losh 30448e3e3a7aSWarner Losh<p> 30458e3e3a7aSWarner LoshWhenever Lua calls C, 30468e3e3a7aSWarner Loshit ensures that the stack has space for 30470495ed39SKyle Evansat least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra elements; 30480495ed39SKyle Evansthat is, you can safely push up to <code>LUA_MINSTACK</code> values into it. 30498e3e3a7aSWarner Losh<code>LUA_MINSTACK</code> is defined as 20, 30508e3e3a7aSWarner Loshso that usually you do not have to worry about stack space 30518e3e3a7aSWarner Loshunless your code has loops pushing elements onto the stack. 30520495ed39SKyle EvansWhenever necessary, 30530495ed39SKyle Evansyou can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> 30540495ed39SKyle Evansto ensure that the stack has enough space for pushing new elements. 30558e3e3a7aSWarner Losh 30568e3e3a7aSWarner Losh 30578e3e3a7aSWarner Losh 30588e3e3a7aSWarner Losh 30598e3e3a7aSWarner Losh 30600495ed39SKyle Evans<h3>4.1.2 – <a name="4.1.2">Valid and Acceptable Indices</a></h3> 30618e3e3a7aSWarner Losh 30628e3e3a7aSWarner Losh<p> 30638e3e3a7aSWarner LoshAny function in the API that receives stack indices 30648e3e3a7aSWarner Loshworks only with <em>valid indices</em> or <em>acceptable indices</em>. 30658e3e3a7aSWarner Losh 30668e3e3a7aSWarner Losh 30678e3e3a7aSWarner Losh<p> 30688e3e3a7aSWarner LoshA <em>valid index</em> is an index that refers to a 30698e3e3a7aSWarner Loshposition that stores a modifiable Lua value. 30708e3e3a7aSWarner LoshIt comprises stack indices between 1 and the stack top 30718e3e3a7aSWarner Losh(<code>1 ≤ abs(index) ≤ top</code>) 30728e3e3a7aSWarner Losh 30738e3e3a7aSWarner Loshplus <em>pseudo-indices</em>, 30748e3e3a7aSWarner Loshwhich represent some positions that are accessible to C code 30758e3e3a7aSWarner Loshbut that are not in the stack. 30760495ed39SKyle EvansPseudo-indices are used to access the registry (see <a href="#4.3">§4.3</a>) 30770495ed39SKyle Evansand the upvalues of a C function (see <a href="#4.2">§4.2</a>). 30788e3e3a7aSWarner Losh 30798e3e3a7aSWarner Losh 30808e3e3a7aSWarner Losh<p> 30818e3e3a7aSWarner LoshFunctions that do not need a specific mutable position, 30828e3e3a7aSWarner Loshbut only a value (e.g., query functions), 30838e3e3a7aSWarner Loshcan be called with acceptable indices. 30848e3e3a7aSWarner LoshAn <em>acceptable index</em> can be any valid index, 30858e3e3a7aSWarner Loshbut it also can be any positive index after the stack top 30868e3e3a7aSWarner Loshwithin the space allocated for the stack, 30878e3e3a7aSWarner Loshthat is, indices up to the stack size. 30888e3e3a7aSWarner Losh(Note that 0 is never an acceptable index.) 30890495ed39SKyle EvansIndices to upvalues (see <a href="#4.2">§4.2</a>) greater than the real number 30900495ed39SKyle Evansof upvalues in the current C function are also acceptable (but invalid). 30918e3e3a7aSWarner LoshExcept when noted otherwise, 30928e3e3a7aSWarner Loshfunctions in the API work with acceptable indices. 30938e3e3a7aSWarner Losh 30948e3e3a7aSWarner Losh 30958e3e3a7aSWarner Losh<p> 30968e3e3a7aSWarner LoshAcceptable indices serve to avoid extra tests 30978e3e3a7aSWarner Loshagainst the stack top when querying the stack. 30988e3e3a7aSWarner LoshFor instance, a C function can query its third argument 30990495ed39SKyle Evanswithout the need to check whether there is a third argument, 31008e3e3a7aSWarner Loshthat is, without the need to check whether 3 is a valid index. 31018e3e3a7aSWarner Losh 31028e3e3a7aSWarner Losh 31038e3e3a7aSWarner Losh<p> 31048e3e3a7aSWarner LoshFor functions that can be called with acceptable indices, 31058e3e3a7aSWarner Loshany non-valid index is treated as if it 31068e3e3a7aSWarner Loshcontains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>, 31078e3e3a7aSWarner Loshwhich behaves like a nil value. 31088e3e3a7aSWarner Losh 31098e3e3a7aSWarner Losh 31108e3e3a7aSWarner Losh 31118e3e3a7aSWarner Losh 31128e3e3a7aSWarner Losh 31130495ed39SKyle Evans<h3>4.1.3 – <a name="4.1.3">Pointers to strings</a></h3> 31140495ed39SKyle Evans 31150495ed39SKyle Evans<p> 31160495ed39SKyle EvansSeveral functions in the API return pointers (<code>const char*</code>) 31170495ed39SKyle Evansto Lua strings in the stack. 31180495ed39SKyle Evans(See <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>, 31190495ed39SKyle Evans<a href="#lua_pushstring"><code>lua_pushstring</code></a>, and <a href="#lua_tolstring"><code>lua_tolstring</code></a>. 31200495ed39SKyle EvansSee also <a href="#luaL_checklstring"><code>luaL_checklstring</code></a>, <a href="#luaL_checkstring"><code>luaL_checkstring</code></a>, 31210495ed39SKyle Evansand <a href="#luaL_tolstring"><code>luaL_tolstring</code></a> in the auxiliary library.) 31220495ed39SKyle Evans 31230495ed39SKyle Evans 31240495ed39SKyle Evans<p> 31250495ed39SKyle EvansIn general, 31260495ed39SKyle EvansLua's garbage collection can free or move internal memory 31270495ed39SKyle Evansand then invalidate pointers to internal strings. 31280495ed39SKyle EvansTo allow a safe use of these pointers, 3129*a9490b81SWarner Loshthe API guarantees that any pointer to a string in a stack index 31300495ed39SKyle Evansis valid while the string value at that index is not removed from the stack. 31310495ed39SKyle Evans(It can be moved to another index, though.) 31320495ed39SKyle EvansWhen the index is a pseudo-index (referring to an upvalue), 31330495ed39SKyle Evansthe pointer is valid while the corresponding call is active and 31340495ed39SKyle Evansthe corresponding upvalue is not modified. 31350495ed39SKyle Evans 31360495ed39SKyle Evans 31370495ed39SKyle Evans<p> 31380495ed39SKyle EvansSome functions in the debug interface 31390495ed39SKyle Evansalso return pointers to strings, 31400495ed39SKyle Evansnamely <a href="#lua_getlocal"><code>lua_getlocal</code></a>, <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, 31410495ed39SKyle Evans<a href="#lua_setlocal"><code>lua_setlocal</code></a>, and <a href="#lua_setupvalue"><code>lua_setupvalue</code></a>. 31420495ed39SKyle EvansFor these functions, the pointer is guaranteed to 31430495ed39SKyle Evansbe valid while the caller function is active and 31440495ed39SKyle Evansthe given closure (if one was given) is in the stack. 31450495ed39SKyle Evans 31460495ed39SKyle Evans 31470495ed39SKyle Evans<p> 31480495ed39SKyle EvansExcept for these guarantees, 31490495ed39SKyle Evansthe garbage collector is free to invalidate 31500495ed39SKyle Evansany pointer to internal strings. 31510495ed39SKyle Evans 31520495ed39SKyle Evans 31530495ed39SKyle Evans 31540495ed39SKyle Evans 31550495ed39SKyle Evans 31560495ed39SKyle Evans 31570495ed39SKyle Evans 31580495ed39SKyle Evans<h2>4.2 – <a name="4.2">C Closures</a></h2> 31598e3e3a7aSWarner Losh 31608e3e3a7aSWarner Losh<p> 31618e3e3a7aSWarner LoshWhen a C function is created, 31628e3e3a7aSWarner Loshit is possible to associate some values with it, 31638e3e3a7aSWarner Loshthus creating a <em>C closure</em> 31648e3e3a7aSWarner Losh(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>); 31658e3e3a7aSWarner Loshthese values are called <em>upvalues</em> and are 31668e3e3a7aSWarner Loshaccessible to the function whenever it is called. 31678e3e3a7aSWarner Losh 31688e3e3a7aSWarner Losh 31698e3e3a7aSWarner Losh<p> 31708e3e3a7aSWarner LoshWhenever a C function is called, 31718e3e3a7aSWarner Loshits upvalues are located at specific pseudo-indices. 31728e3e3a7aSWarner LoshThese pseudo-indices are produced by the macro 31738e3e3a7aSWarner Losh<a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>. 31748e3e3a7aSWarner LoshThe first upvalue associated with a function is at index 31758e3e3a7aSWarner Losh<code>lua_upvalueindex(1)</code>, and so on. 31768e3e3a7aSWarner LoshAny access to <code>lua_upvalueindex(<em>n</em>)</code>, 31778e3e3a7aSWarner Loshwhere <em>n</em> is greater than the number of upvalues of the 31788e3e3a7aSWarner Loshcurrent function 31798e3e3a7aSWarner Losh(but not greater than 256, 31808e3e3a7aSWarner Loshwhich is one plus the maximum number of upvalues in a closure), 31818e3e3a7aSWarner Loshproduces an acceptable but invalid index. 31828e3e3a7aSWarner Losh 31838e3e3a7aSWarner Losh 31840495ed39SKyle Evans<p> 31850495ed39SKyle EvansA C closure can also change the values 31860495ed39SKyle Evansof its corresponding upvalues. 31878e3e3a7aSWarner Losh 31888e3e3a7aSWarner Losh 31898e3e3a7aSWarner Losh 31900495ed39SKyle Evans 31910495ed39SKyle Evans 31920495ed39SKyle Evans<h2>4.3 – <a name="4.3">Registry</a></h2> 31938e3e3a7aSWarner Losh 31948e3e3a7aSWarner Losh<p> 31958e3e3a7aSWarner LoshLua provides a <em>registry</em>, 31968e3e3a7aSWarner Losha predefined table that can be used by any C code to 31978e3e3a7aSWarner Loshstore whatever Lua values it needs to store. 31980495ed39SKyle EvansThe registry table is always accessible at pseudo-index 31998e3e3a7aSWarner Losh<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. 32008e3e3a7aSWarner LoshAny C library can store data into this table, 32018e3e3a7aSWarner Loshbut it must take care to choose keys 32028e3e3a7aSWarner Loshthat are different from those used 32038e3e3a7aSWarner Loshby other libraries, to avoid collisions. 32048e3e3a7aSWarner LoshTypically, you should use as key a string containing your library name, 32058e3e3a7aSWarner Loshor a light userdata with the address of a C object in your code, 32068e3e3a7aSWarner Loshor any Lua object created by your code. 32078e3e3a7aSWarner LoshAs with variable names, 32088e3e3a7aSWarner Loshstring keys starting with an underscore followed by 32098e3e3a7aSWarner Loshuppercase letters are reserved for Lua. 32108e3e3a7aSWarner Losh 32118e3e3a7aSWarner Losh 32128e3e3a7aSWarner Losh<p> 32138e3e3a7aSWarner LoshThe integer keys in the registry are used 32148e3e3a7aSWarner Loshby the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>) 32158e3e3a7aSWarner Loshand by some predefined values. 32160495ed39SKyle EvansTherefore, integer keys in the registry 32170495ed39SKyle Evansmust not be used for other purposes. 32188e3e3a7aSWarner Losh 32198e3e3a7aSWarner Losh 32208e3e3a7aSWarner Losh<p> 32218e3e3a7aSWarner LoshWhen you create a new Lua state, 32228e3e3a7aSWarner Loshits registry comes with some predefined values. 32238e3e3a7aSWarner LoshThese predefined values are indexed with integer keys 32248e3e3a7aSWarner Loshdefined as constants in <code>lua.h</code>. 32258e3e3a7aSWarner LoshThe following constants are defined: 32268e3e3a7aSWarner Losh 32278e3e3a7aSWarner Losh<ul> 32288e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has 32298e3e3a7aSWarner Loshthe main thread of the state. 32308e3e3a7aSWarner Losh(The main thread is the one created together with the state.) 32318e3e3a7aSWarner Losh</li> 32328e3e3a7aSWarner Losh 32338e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has 32348e3e3a7aSWarner Loshthe global environment. 32358e3e3a7aSWarner Losh</li> 32368e3e3a7aSWarner Losh</ul> 32378e3e3a7aSWarner Losh 32388e3e3a7aSWarner Losh 32398e3e3a7aSWarner Losh 32408e3e3a7aSWarner Losh 32410495ed39SKyle Evans<h2>4.4 – <a name="4.4">Error Handling in C</a></h2> 32420495ed39SKyle Evans 32430495ed39SKyle Evans 32448e3e3a7aSWarner Losh 32458e3e3a7aSWarner Losh<p> 32468e3e3a7aSWarner LoshInternally, Lua uses the C <code>longjmp</code> facility to handle errors. 32478e3e3a7aSWarner Losh(Lua will use exceptions if you compile it as C++; 32488e3e3a7aSWarner Loshsearch for <code>LUAI_THROW</code> in the source code for details.) 32490495ed39SKyle EvansWhen Lua faces any error, 32500495ed39SKyle Evanssuch as a memory allocation error or a type error, 32518e3e3a7aSWarner Loshit <em>raises</em> an error; 32528e3e3a7aSWarner Loshthat is, it does a long jump. 32538e3e3a7aSWarner LoshA <em>protected environment</em> uses <code>setjmp</code> 32548e3e3a7aSWarner Loshto set a recovery point; 32558e3e3a7aSWarner Loshany error jumps to the most recent active recovery point. 32568e3e3a7aSWarner Losh 32578e3e3a7aSWarner Losh 32588e3e3a7aSWarner Losh<p> 32590495ed39SKyle EvansInside a C function you can raise an error explicitly 32600495ed39SKyle Evansby calling <a href="#lua_error"><code>lua_error</code></a>. 32618e3e3a7aSWarner Losh 32628e3e3a7aSWarner Losh 32638e3e3a7aSWarner Losh<p> 32648e3e3a7aSWarner LoshMost functions in the API can raise an error, 32658e3e3a7aSWarner Loshfor instance due to a memory allocation error. 32668e3e3a7aSWarner LoshThe documentation for each function indicates whether 32678e3e3a7aSWarner Loshit can raise errors. 32688e3e3a7aSWarner Losh 32698e3e3a7aSWarner Losh 32708e3e3a7aSWarner Losh<p> 32718e3e3a7aSWarner LoshIf an error happens outside any protected environment, 32728e3e3a7aSWarner LoshLua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) 32738e3e3a7aSWarner Loshand then calls <code>abort</code>, 32748e3e3a7aSWarner Loshthus exiting the host application. 32758e3e3a7aSWarner LoshYour panic function can avoid this exit by 32768e3e3a7aSWarner Loshnever returning 32778e3e3a7aSWarner Losh(e.g., doing a long jump to your own recovery point outside Lua). 32788e3e3a7aSWarner Losh 32798e3e3a7aSWarner Losh 32808e3e3a7aSWarner Losh<p> 32818e3e3a7aSWarner LoshThe panic function, 32828e3e3a7aSWarner Loshas its name implies, 32838e3e3a7aSWarner Loshis a mechanism of last resort. 32848e3e3a7aSWarner LoshPrograms should avoid it. 32858e3e3a7aSWarner LoshAs a general rule, 32868e3e3a7aSWarner Loshwhen a C function is called by Lua with a Lua state, 32878e3e3a7aSWarner Loshit can do whatever it wants on that Lua state, 32888e3e3a7aSWarner Loshas it should be already protected. 32898e3e3a7aSWarner LoshHowever, 32908e3e3a7aSWarner Loshwhen C code operates on other Lua states 32910495ed39SKyle Evans(e.g., a Lua-state argument to the function, 32928e3e3a7aSWarner Losha Lua state stored in the registry, or 32938e3e3a7aSWarner Loshthe result of <a href="#lua_newthread"><code>lua_newthread</code></a>), 32948e3e3a7aSWarner Loshit should use them only in API calls that cannot raise errors. 32958e3e3a7aSWarner Losh 32968e3e3a7aSWarner Losh 32978e3e3a7aSWarner Losh<p> 32988e3e3a7aSWarner LoshThe panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>); 32990495ed39SKyle Evansin particular, the error object is on the top of the stack. 33008e3e3a7aSWarner LoshHowever, there is no guarantee about stack space. 33018e3e3a7aSWarner LoshTo push anything on the stack, 33020495ed39SKyle Evansthe panic function must first check the available space (see <a href="#4.1.1">§4.1.1</a>). 33038e3e3a7aSWarner Losh 33048e3e3a7aSWarner Losh 33058e3e3a7aSWarner Losh 33068e3e3a7aSWarner Losh 33078e3e3a7aSWarner Losh 33080495ed39SKyle Evans<h3>4.4.1 – <a name="4.4.1">Status Codes</a></h3> 33090495ed39SKyle Evans 33100495ed39SKyle Evans<p> 33110495ed39SKyle EvansSeveral functions that report errors in the API use the following 33120495ed39SKyle Evansstatus codes to indicate different kinds of errors or other conditions: 33130495ed39SKyle Evans 33140495ed39SKyle Evans<ul> 33150495ed39SKyle Evans 33160495ed39SKyle Evans<li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> no errors.</li> 33170495ed39SKyle Evans 33180495ed39SKyle Evans<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b> a runtime error.</li> 33190495ed39SKyle Evans 33200495ed39SKyle Evans<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 33210495ed39SKyle Evansmemory allocation error. 33220495ed39SKyle EvansFor such errors, Lua does not call the message handler. 33230495ed39SKyle Evans</li> 33240495ed39SKyle Evans 33250495ed39SKyle Evans<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b> error while running the message handler.</li> 33260495ed39SKyle Evans 33270495ed39SKyle Evans<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> syntax error during precompilation.</li> 33280495ed39SKyle Evans 33290495ed39SKyle Evans<li><b><a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a>: </b> the thread (coroutine) yields.</li> 33300495ed39SKyle Evans 33310495ed39SKyle Evans<li><b><a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>: </b> a file-related error; 33320495ed39SKyle Evanse.g., it cannot open or read the file.</li> 33330495ed39SKyle Evans 33340495ed39SKyle Evans</ul><p> 33350495ed39SKyle EvansThese constants are defined in the header file <code>lua.h</code>. 33360495ed39SKyle Evans 33370495ed39SKyle Evans 33380495ed39SKyle Evans 33390495ed39SKyle Evans 33400495ed39SKyle Evans 33410495ed39SKyle Evans 33420495ed39SKyle Evans 33430495ed39SKyle Evans<h2>4.5 – <a name="4.5">Handling Yields in C</a></h2> 33448e3e3a7aSWarner Losh 33458e3e3a7aSWarner Losh<p> 33468e3e3a7aSWarner LoshInternally, Lua uses the C <code>longjmp</code> facility to yield a coroutine. 33478e3e3a7aSWarner LoshTherefore, if a C function <code>foo</code> calls an API function 33488e3e3a7aSWarner Loshand this API function yields 33498e3e3a7aSWarner Losh(directly or indirectly by calling another function that yields), 33508e3e3a7aSWarner LoshLua cannot return to <code>foo</code> any more, 33510495ed39SKyle Evansbecause the <code>longjmp</code> removes its frame from the C stack. 33528e3e3a7aSWarner Losh 33538e3e3a7aSWarner Losh 33548e3e3a7aSWarner Losh<p> 33558e3e3a7aSWarner LoshTo avoid this kind of problem, 33568e3e3a7aSWarner LoshLua raises an error whenever it tries to yield across an API call, 33578e3e3a7aSWarner Loshexcept for three functions: 33588e3e3a7aSWarner 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>. 33598e3e3a7aSWarner LoshAll those functions receive a <em>continuation function</em> 33608e3e3a7aSWarner Losh(as a parameter named <code>k</code>) to continue execution after a yield. 33618e3e3a7aSWarner Losh 33628e3e3a7aSWarner Losh 33638e3e3a7aSWarner Losh<p> 33648e3e3a7aSWarner LoshWe need to set some terminology to explain continuations. 33658e3e3a7aSWarner LoshWe have a C function called from Lua which we will call 33668e3e3a7aSWarner Loshthe <em>original function</em>. 33678e3e3a7aSWarner LoshThis original function then calls one of those three functions in the C API, 33688e3e3a7aSWarner Loshwhich we will call the <em>callee function</em>, 33698e3e3a7aSWarner Loshthat then yields the current thread. 33700495ed39SKyle EvansThis can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 33718e3e3a7aSWarner 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> 33720495ed39SKyle Evansand the function called by them yields. 33738e3e3a7aSWarner Losh 33748e3e3a7aSWarner Losh 33758e3e3a7aSWarner Losh<p> 33768e3e3a7aSWarner LoshSuppose the running thread yields while executing the callee function. 33778e3e3a7aSWarner LoshAfter the thread resumes, 33788e3e3a7aSWarner Loshit eventually will finish running the callee function. 33798e3e3a7aSWarner LoshHowever, 33808e3e3a7aSWarner Loshthe callee function cannot return to the original function, 33810495ed39SKyle Evansbecause its frame in the C stack was destroyed by the yield. 33828e3e3a7aSWarner LoshInstead, Lua calls a <em>continuation function</em>, 33838e3e3a7aSWarner Loshwhich was given as an argument to the callee function. 33848e3e3a7aSWarner LoshAs the name implies, 33858e3e3a7aSWarner Loshthe continuation function should continue the task 33868e3e3a7aSWarner Loshof the original function. 33878e3e3a7aSWarner Losh 33888e3e3a7aSWarner Losh 33898e3e3a7aSWarner Losh<p> 33908e3e3a7aSWarner LoshAs an illustration, consider the following function: 33918e3e3a7aSWarner Losh 33928e3e3a7aSWarner Losh<pre> 33938e3e3a7aSWarner Losh int original_function (lua_State *L) { 33948e3e3a7aSWarner Losh ... /* code 1 */ 33958e3e3a7aSWarner Losh status = lua_pcall(L, n, m, h); /* calls Lua */ 33968e3e3a7aSWarner Losh ... /* code 2 */ 33978e3e3a7aSWarner Losh } 33988e3e3a7aSWarner Losh</pre><p> 33998e3e3a7aSWarner LoshNow we want to allow 34008e3e3a7aSWarner Loshthe Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield. 34018e3e3a7aSWarner LoshFirst, we can rewrite our function like here: 34028e3e3a7aSWarner Losh 34038e3e3a7aSWarner Losh<pre> 34048e3e3a7aSWarner Losh int k (lua_State *L, int status, lua_KContext ctx) { 34058e3e3a7aSWarner Losh ... /* code 2 */ 34068e3e3a7aSWarner Losh } 34078e3e3a7aSWarner Losh 34088e3e3a7aSWarner Losh int original_function (lua_State *L) { 34098e3e3a7aSWarner Losh ... /* code 1 */ 34108e3e3a7aSWarner Losh return k(L, lua_pcall(L, n, m, h), ctx); 34118e3e3a7aSWarner Losh } 34128e3e3a7aSWarner Losh</pre><p> 34138e3e3a7aSWarner LoshIn the above code, 34148e3e3a7aSWarner Loshthe new function <code>k</code> is a 34158e3e3a7aSWarner Losh<em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>), 34168e3e3a7aSWarner Loshwhich should do all the work that the original function 34178e3e3a7aSWarner Loshwas doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>. 34188e3e3a7aSWarner LoshNow, we must inform Lua that it must call <code>k</code> if the Lua code 34198e3e3a7aSWarner Loshbeing executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way 34208e3e3a7aSWarner Losh(errors or yielding), 34218e3e3a7aSWarner Loshso we rewrite the code as here, 34228e3e3a7aSWarner Loshreplacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>: 34238e3e3a7aSWarner Losh 34248e3e3a7aSWarner Losh<pre> 34258e3e3a7aSWarner Losh int original_function (lua_State *L) { 34268e3e3a7aSWarner Losh ... /* code 1 */ 34278e3e3a7aSWarner Losh return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1); 34288e3e3a7aSWarner Losh } 34298e3e3a7aSWarner Losh</pre><p> 34308e3e3a7aSWarner LoshNote the external, explicit call to the continuation: 34318e3e3a7aSWarner LoshLua will call the continuation only if needed, that is, 34328e3e3a7aSWarner Loshin case of errors or resuming after a yield. 34338e3e3a7aSWarner LoshIf the called function returns normally without ever yielding, 34348e3e3a7aSWarner Losh<a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally. 34358e3e3a7aSWarner Losh(Of course, instead of calling the continuation in that case, 34368e3e3a7aSWarner Loshyou can do the equivalent work directly inside the original function.) 34378e3e3a7aSWarner Losh 34388e3e3a7aSWarner Losh 34398e3e3a7aSWarner Losh<p> 34408e3e3a7aSWarner LoshBesides the Lua state, 34418e3e3a7aSWarner Loshthe continuation function has two other parameters: 34420495ed39SKyle Evansthe final status of the call and the context value (<code>ctx</code>) that 34438e3e3a7aSWarner Loshwas passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>. 34440495ed39SKyle EvansLua does not use this context value; 34458e3e3a7aSWarner Loshit only passes this value from the original function to the 34460495ed39SKyle Evanscontinuation function. 34478e3e3a7aSWarner LoshFor <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 34488e3e3a7aSWarner Loshthe status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 34498e3e3a7aSWarner Loshexcept that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield 34508e3e3a7aSWarner Losh(instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>). 34518e3e3a7aSWarner LoshFor <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>, 34528e3e3a7aSWarner Loshthe status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation. 34538e3e3a7aSWarner Losh(For these two functions, 34548e3e3a7aSWarner LoshLua will not call the continuation in case of errors, 34558e3e3a7aSWarner Loshbecause they do not handle errors.) 34568e3e3a7aSWarner LoshSimilarly, when using <a href="#lua_callk"><code>lua_callk</code></a>, 34578e3e3a7aSWarner Loshyou should call the continuation function 34588e3e3a7aSWarner Loshwith <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status. 34598e3e3a7aSWarner Losh(For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling 34608e3e3a7aSWarner Loshdirectly the continuation function, 34618e3e3a7aSWarner Loshbecause <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.) 34628e3e3a7aSWarner Losh 34638e3e3a7aSWarner Losh 34648e3e3a7aSWarner Losh<p> 34658e3e3a7aSWarner LoshLua treats the continuation function as if it were the original function. 34668e3e3a7aSWarner LoshThe continuation function receives the same Lua stack 34678e3e3a7aSWarner Loshfrom the original function, 34688e3e3a7aSWarner Loshin the same state it would be if the callee function had returned. 34698e3e3a7aSWarner Losh(For instance, 34708e3e3a7aSWarner Loshafter a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are 34718e3e3a7aSWarner Loshremoved from the stack and replaced by the results from the call.) 34728e3e3a7aSWarner LoshIt also has the same upvalues. 34738e3e3a7aSWarner LoshWhatever it returns is handled by Lua as if it were the return 34748e3e3a7aSWarner Loshof the original function. 34758e3e3a7aSWarner Losh 34768e3e3a7aSWarner Losh 34778e3e3a7aSWarner Losh 34788e3e3a7aSWarner Losh 34798e3e3a7aSWarner Losh 34800495ed39SKyle Evans<h2>4.6 – <a name="4.6">Functions and Types</a></h2> 34818e3e3a7aSWarner Losh 34828e3e3a7aSWarner Losh<p> 34838e3e3a7aSWarner LoshHere we list all functions and types from the C API in 34848e3e3a7aSWarner Loshalphabetical order. 34858e3e3a7aSWarner LoshEach function has an indicator like this: 34868e3e3a7aSWarner Losh<span class="apii">[-o, +p, <em>x</em>]</span> 34878e3e3a7aSWarner Losh 34888e3e3a7aSWarner Losh 34898e3e3a7aSWarner Losh<p> 34908e3e3a7aSWarner LoshThe first field, <code>o</code>, 34918e3e3a7aSWarner Loshis how many elements the function pops from the stack. 34928e3e3a7aSWarner LoshThe second field, <code>p</code>, 34938e3e3a7aSWarner Loshis how many elements the function pushes onto the stack. 34948e3e3a7aSWarner Losh(Any function always pushes its results after popping its arguments.) 34958e3e3a7aSWarner LoshA field in the form <code>x|y</code> means the function can push (or pop) 34968e3e3a7aSWarner Losh<code>x</code> or <code>y</code> elements, 34978e3e3a7aSWarner Loshdepending on the situation; 34988e3e3a7aSWarner Loshan interrogation mark '<code>?</code>' means that 34998e3e3a7aSWarner Loshwe cannot know how many elements the function pops/pushes 35000495ed39SKyle Evansby looking only at its arguments. 35010495ed39SKyle Evans(For instance, they may depend on what is in the stack.) 35028e3e3a7aSWarner LoshThe third field, <code>x</code>, 35038e3e3a7aSWarner Loshtells whether the function may raise errors: 35048e3e3a7aSWarner Losh'<code>-</code>' means the function never raises any error; 35050495ed39SKyle Evans'<code>m</code>' means the function may raise only out-of-memory errors; 35060495ed39SKyle Evans'<code>v</code>' means the function may raise the errors explained in the text; 35070495ed39SKyle Evans'<code>e</code>' means the function can run arbitrary Lua code, 35080495ed39SKyle Evanseither directly or through metamethods, 35090495ed39SKyle Evansand therefore may raise any errors. 35108e3e3a7aSWarner Losh 35118e3e3a7aSWarner Losh 35128e3e3a7aSWarner Losh 35138e3e3a7aSWarner Losh<hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p> 35148e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 35158e3e3a7aSWarner Losh<pre>int lua_absindex (lua_State *L, int idx);</pre> 35168e3e3a7aSWarner Losh 35178e3e3a7aSWarner Losh<p> 35188e3e3a7aSWarner LoshConverts the acceptable index <code>idx</code> 35198e3e3a7aSWarner Loshinto an equivalent absolute index 35200495ed39SKyle Evans(that is, one that does not depend on the stack size). 35218e3e3a7aSWarner Losh 35228e3e3a7aSWarner Losh 35238e3e3a7aSWarner Losh 35248e3e3a7aSWarner Losh 35258e3e3a7aSWarner Losh 35268e3e3a7aSWarner Losh<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> 35278e3e3a7aSWarner Losh<pre>typedef void * (*lua_Alloc) (void *ud, 35288e3e3a7aSWarner Losh void *ptr, 35298e3e3a7aSWarner Losh size_t osize, 35308e3e3a7aSWarner Losh size_t nsize);</pre> 35318e3e3a7aSWarner Losh 35328e3e3a7aSWarner Losh<p> 35338e3e3a7aSWarner LoshThe type of the memory-allocation function used by Lua states. 35348e3e3a7aSWarner LoshThe allocator function must provide a 35358e3e3a7aSWarner Loshfunctionality similar to <code>realloc</code>, 35368e3e3a7aSWarner Loshbut not exactly the same. 35378e3e3a7aSWarner LoshIts arguments are 35388e3e3a7aSWarner Losh<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; 35398e3e3a7aSWarner Losh<code>ptr</code>, a pointer to the block being allocated/reallocated/freed; 35408e3e3a7aSWarner Losh<code>osize</code>, the original size of the block or some code about what 35418e3e3a7aSWarner Loshis being allocated; 35428e3e3a7aSWarner Loshand <code>nsize</code>, the new size of the block. 35438e3e3a7aSWarner Losh 35448e3e3a7aSWarner Losh 35458e3e3a7aSWarner Losh<p> 35468e3e3a7aSWarner LoshWhen <code>ptr</code> is not <code>NULL</code>, 35478e3e3a7aSWarner Losh<code>osize</code> is the size of the block pointed by <code>ptr</code>, 35488e3e3a7aSWarner Loshthat is, the size given when it was allocated or reallocated. 35498e3e3a7aSWarner Losh 35508e3e3a7aSWarner Losh 35518e3e3a7aSWarner Losh<p> 35528e3e3a7aSWarner LoshWhen <code>ptr</code> is <code>NULL</code>, 35538e3e3a7aSWarner Losh<code>osize</code> encodes the kind of object that Lua is allocating. 35548e3e3a7aSWarner Losh<code>osize</code> is any of 35558e3e3a7aSWarner 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>, 35568e3e3a7aSWarner 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) 35578e3e3a7aSWarner LoshLua is creating a new object of that type. 35588e3e3a7aSWarner LoshWhen <code>osize</code> is some other value, 35598e3e3a7aSWarner LoshLua is allocating memory for something else. 35608e3e3a7aSWarner Losh 35618e3e3a7aSWarner Losh 35628e3e3a7aSWarner Losh<p> 35638e3e3a7aSWarner LoshLua assumes the following behavior from the allocator function: 35648e3e3a7aSWarner Losh 35658e3e3a7aSWarner Losh 35668e3e3a7aSWarner Losh<p> 35678e3e3a7aSWarner LoshWhen <code>nsize</code> is zero, 35688e3e3a7aSWarner Loshthe allocator must behave like <code>free</code> 35690495ed39SKyle Evansand then return <code>NULL</code>. 35708e3e3a7aSWarner Losh 35718e3e3a7aSWarner Losh 35728e3e3a7aSWarner Losh<p> 35738e3e3a7aSWarner LoshWhen <code>nsize</code> is not zero, 35748e3e3a7aSWarner Loshthe allocator must behave like <code>realloc</code>. 35750495ed39SKyle EvansIn particular, the allocator returns <code>NULL</code> 35768e3e3a7aSWarner Loshif and only if it cannot fulfill the request. 35778e3e3a7aSWarner Losh 35788e3e3a7aSWarner Losh 35798e3e3a7aSWarner Losh<p> 35808e3e3a7aSWarner LoshHere is a simple implementation for the allocator function. 35818e3e3a7aSWarner LoshIt is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. 35828e3e3a7aSWarner Losh 35838e3e3a7aSWarner Losh<pre> 35848e3e3a7aSWarner Losh static void *l_alloc (void *ud, void *ptr, size_t osize, 35858e3e3a7aSWarner Losh size_t nsize) { 35868e3e3a7aSWarner Losh (void)ud; (void)osize; /* not used */ 35878e3e3a7aSWarner Losh if (nsize == 0) { 35888e3e3a7aSWarner Losh free(ptr); 35898e3e3a7aSWarner Losh return NULL; 35908e3e3a7aSWarner Losh } 35918e3e3a7aSWarner Losh else 35928e3e3a7aSWarner Losh return realloc(ptr, nsize); 35938e3e3a7aSWarner Losh } 35948e3e3a7aSWarner Losh</pre><p> 3595*a9490b81SWarner LoshNote that ISO C ensures 35968e3e3a7aSWarner Loshthat <code>free(NULL)</code> has no effect and that 35978e3e3a7aSWarner Losh<code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>. 35988e3e3a7aSWarner Losh 35998e3e3a7aSWarner Losh 36008e3e3a7aSWarner Losh 36018e3e3a7aSWarner Losh 36028e3e3a7aSWarner Losh 36038e3e3a7aSWarner Losh<hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p> 36048e3e3a7aSWarner Losh<span class="apii">[-(2|1), +1, <em>e</em>]</span> 36058e3e3a7aSWarner Losh<pre>void lua_arith (lua_State *L, int op);</pre> 36068e3e3a7aSWarner Losh 36078e3e3a7aSWarner Losh<p> 36088e3e3a7aSWarner LoshPerforms an arithmetic or bitwise operation over the two values 36098e3e3a7aSWarner Losh(or one, in the case of negations) 36108e3e3a7aSWarner Loshat the top of the stack, 36110495ed39SKyle Evanswith the value on the top being the second operand, 36128e3e3a7aSWarner Loshpops these values, and pushes the result of the operation. 36138e3e3a7aSWarner LoshThe function follows the semantics of the corresponding Lua operator 36148e3e3a7aSWarner Losh(that is, it may call metamethods). 36158e3e3a7aSWarner Losh 36168e3e3a7aSWarner Losh 36178e3e3a7aSWarner Losh<p> 36188e3e3a7aSWarner LoshThe value of <code>op</code> must be one of the following constants: 36198e3e3a7aSWarner Losh 36208e3e3a7aSWarner Losh<ul> 36218e3e3a7aSWarner Losh 36228e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li> 36238e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li> 36248e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li> 36258e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li> 36268e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li> 36278e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li> 36288e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li> 36298e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li> 36308e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li> 36318e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&</code>)</li> 36328e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li> 36338e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li> 36348e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li> 36358e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li> 36368e3e3a7aSWarner Losh 36378e3e3a7aSWarner Losh</ul> 36388e3e3a7aSWarner Losh 36398e3e3a7aSWarner Losh 36408e3e3a7aSWarner Losh 36418e3e3a7aSWarner Losh 36428e3e3a7aSWarner Losh<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> 36438e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 36448e3e3a7aSWarner Losh<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> 36458e3e3a7aSWarner Losh 36468e3e3a7aSWarner Losh<p> 36470495ed39SKyle EvansSets a new panic function and returns the old one (see <a href="#4.4">§4.4</a>). 36488e3e3a7aSWarner Losh 36498e3e3a7aSWarner Losh 36508e3e3a7aSWarner Losh 36518e3e3a7aSWarner Losh 36528e3e3a7aSWarner Losh 36538e3e3a7aSWarner Losh<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> 36548e3e3a7aSWarner Losh<span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span> 36558e3e3a7aSWarner Losh<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> 36568e3e3a7aSWarner Losh 36578e3e3a7aSWarner Losh<p> 36588e3e3a7aSWarner LoshCalls a function. 36590495ed39SKyle EvansLike regular Lua calls, 36600495ed39SKyle Evans<code>lua_call</code> respects the <code>__call</code> metamethod. 36610495ed39SKyle EvansSo, here the word "function" 36620495ed39SKyle Evansmeans any callable value. 36638e3e3a7aSWarner Losh 36648e3e3a7aSWarner Losh 36658e3e3a7aSWarner Losh<p> 36660495ed39SKyle EvansTo do a call you must use the following protocol: 36678e3e3a7aSWarner Loshfirst, the function to be called is pushed onto the stack; 36680495ed39SKyle Evansthen, the arguments to the call are pushed 36698e3e3a7aSWarner Loshin direct order; 36708e3e3a7aSWarner Loshthat is, the first argument is pushed first. 36718e3e3a7aSWarner LoshFinally you call <a href="#lua_call"><code>lua_call</code></a>; 36728e3e3a7aSWarner Losh<code>nargs</code> is the number of arguments that you pushed onto the stack. 36730495ed39SKyle EvansWhen the function returns, 36740495ed39SKyle Evansall arguments and the function value are popped 36750495ed39SKyle Evansand the call results are pushed onto the stack. 36768e3e3a7aSWarner LoshThe number of results is adjusted to <code>nresults</code>, 36778e3e3a7aSWarner Loshunless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. 36788e3e3a7aSWarner LoshIn this case, all results from the function are pushed; 36798e3e3a7aSWarner LoshLua takes care that the returned values fit into the stack space, 36808e3e3a7aSWarner Loshbut it does not ensure any extra space in the stack. 36818e3e3a7aSWarner LoshThe function results are pushed onto the stack in direct order 36828e3e3a7aSWarner Losh(the first result is pushed first), 36838e3e3a7aSWarner Loshso that after the call the last result is on the top of the stack. 36848e3e3a7aSWarner Losh 36858e3e3a7aSWarner Losh 36868e3e3a7aSWarner Losh<p> 36870495ed39SKyle EvansAny error while calling and running the function is propagated upwards 36888e3e3a7aSWarner Losh(with a <code>longjmp</code>). 36898e3e3a7aSWarner Losh 36908e3e3a7aSWarner Losh 36918e3e3a7aSWarner Losh<p> 36928e3e3a7aSWarner LoshThe following example shows how the host program can do the 36938e3e3a7aSWarner Loshequivalent to this Lua code: 36948e3e3a7aSWarner Losh 36958e3e3a7aSWarner Losh<pre> 36968e3e3a7aSWarner Losh a = f("how", t.x, 14) 36978e3e3a7aSWarner Losh</pre><p> 36988e3e3a7aSWarner LoshHere it is in C: 36998e3e3a7aSWarner Losh 37008e3e3a7aSWarner Losh<pre> 37018e3e3a7aSWarner Losh lua_getglobal(L, "f"); /* function to be called */ 37028e3e3a7aSWarner Losh lua_pushliteral(L, "how"); /* 1st argument */ 37038e3e3a7aSWarner Losh lua_getglobal(L, "t"); /* table to be indexed */ 37048e3e3a7aSWarner Losh lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 37058e3e3a7aSWarner Losh lua_remove(L, -2); /* remove 't' from the stack */ 37068e3e3a7aSWarner Losh lua_pushinteger(L, 14); /* 3rd argument */ 37078e3e3a7aSWarner Losh lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ 37088e3e3a7aSWarner Losh lua_setglobal(L, "a"); /* set global 'a' */ 37098e3e3a7aSWarner Losh</pre><p> 37108e3e3a7aSWarner LoshNote that the code above is <em>balanced</em>: 37118e3e3a7aSWarner Loshat its end, the stack is back to its original configuration. 37128e3e3a7aSWarner LoshThis is considered good programming practice. 37138e3e3a7aSWarner Losh 37148e3e3a7aSWarner Losh 37158e3e3a7aSWarner Losh 37168e3e3a7aSWarner Losh 37178e3e3a7aSWarner Losh 37188e3e3a7aSWarner Losh<hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p> 37198e3e3a7aSWarner Losh<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> 37208e3e3a7aSWarner Losh<pre>void lua_callk (lua_State *L, 37218e3e3a7aSWarner Losh int nargs, 37228e3e3a7aSWarner Losh int nresults, 37238e3e3a7aSWarner Losh lua_KContext ctx, 37248e3e3a7aSWarner Losh lua_KFunction k);</pre> 37258e3e3a7aSWarner Losh 37268e3e3a7aSWarner Losh<p> 37278e3e3a7aSWarner LoshThis function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>, 37280495ed39SKyle Evansbut allows the called function to yield (see <a href="#4.5">§4.5</a>). 37298e3e3a7aSWarner Losh 37308e3e3a7aSWarner Losh 37318e3e3a7aSWarner Losh 37328e3e3a7aSWarner Losh 37338e3e3a7aSWarner Losh 37348e3e3a7aSWarner Losh<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> 37358e3e3a7aSWarner Losh<pre>typedef int (*lua_CFunction) (lua_State *L);</pre> 37368e3e3a7aSWarner Losh 37378e3e3a7aSWarner Losh<p> 37388e3e3a7aSWarner LoshType for C functions. 37398e3e3a7aSWarner Losh 37408e3e3a7aSWarner Losh 37418e3e3a7aSWarner Losh<p> 37428e3e3a7aSWarner LoshIn order to communicate properly with Lua, 37438e3e3a7aSWarner Losha C function must use the following protocol, 37448e3e3a7aSWarner Loshwhich defines the way parameters and results are passed: 37458e3e3a7aSWarner Losha C function receives its arguments from Lua in its stack 37468e3e3a7aSWarner Loshin direct order (the first argument is pushed first). 37478e3e3a7aSWarner LoshSo, when the function starts, 37488e3e3a7aSWarner Losh<code>lua_gettop(L)</code> returns the number of arguments received by the function. 37498e3e3a7aSWarner LoshThe first argument (if any) is at index 1 37508e3e3a7aSWarner Loshand its last argument is at index <code>lua_gettop(L)</code>. 37518e3e3a7aSWarner LoshTo return values to Lua, a C function just pushes them onto the stack, 37528e3e3a7aSWarner Loshin direct order (the first result is pushed first), 37530495ed39SKyle Evansand returns in C the number of results. 37548e3e3a7aSWarner LoshAny other value in the stack below the results will be properly 37558e3e3a7aSWarner Loshdiscarded by Lua. 37568e3e3a7aSWarner LoshLike a Lua function, a C function called by Lua can also return 37578e3e3a7aSWarner Loshmany results. 37588e3e3a7aSWarner Losh 37598e3e3a7aSWarner Losh 37608e3e3a7aSWarner Losh<p> 37618e3e3a7aSWarner LoshAs an example, the following function receives a variable number 37628e3e3a7aSWarner Loshof numeric arguments and returns their average and their sum: 37638e3e3a7aSWarner Losh 37648e3e3a7aSWarner Losh<pre> 37658e3e3a7aSWarner Losh static int foo (lua_State *L) { 37668e3e3a7aSWarner Losh int n = lua_gettop(L); /* number of arguments */ 37678e3e3a7aSWarner Losh lua_Number sum = 0.0; 37688e3e3a7aSWarner Losh int i; 37698e3e3a7aSWarner Losh for (i = 1; i <= n; i++) { 37708e3e3a7aSWarner Losh if (!lua_isnumber(L, i)) { 37718e3e3a7aSWarner Losh lua_pushliteral(L, "incorrect argument"); 37728e3e3a7aSWarner Losh lua_error(L); 37738e3e3a7aSWarner Losh } 37748e3e3a7aSWarner Losh sum += lua_tonumber(L, i); 37758e3e3a7aSWarner Losh } 37768e3e3a7aSWarner Losh lua_pushnumber(L, sum/n); /* first result */ 37778e3e3a7aSWarner Losh lua_pushnumber(L, sum); /* second result */ 37788e3e3a7aSWarner Losh return 2; /* number of results */ 37798e3e3a7aSWarner Losh } 37808e3e3a7aSWarner Losh</pre> 37818e3e3a7aSWarner Losh 37828e3e3a7aSWarner Losh 37838e3e3a7aSWarner Losh 37848e3e3a7aSWarner Losh 37858e3e3a7aSWarner Losh<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> 37868e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 37878e3e3a7aSWarner Losh<pre>int lua_checkstack (lua_State *L, int n);</pre> 37888e3e3a7aSWarner Losh 37898e3e3a7aSWarner Losh<p> 37900495ed39SKyle EvansEnsures that the stack has space for at least <code>n</code> extra elements, 37910495ed39SKyle Evansthat is, that you can safely push up to <code>n</code> values into it. 37928e3e3a7aSWarner LoshIt returns false if it cannot fulfill the request, 37938e3e3a7aSWarner Losheither because it would cause the stack 37940495ed39SKyle Evansto be greater than a fixed maximum size 37958e3e3a7aSWarner Losh(typically at least several thousand elements) or 37968e3e3a7aSWarner Loshbecause it cannot allocate memory for the extra space. 37978e3e3a7aSWarner LoshThis function never shrinks the stack; 37980495ed39SKyle Evansif the stack already has space for the extra elements, 37998e3e3a7aSWarner Loshit is left unchanged. 38008e3e3a7aSWarner Losh 38018e3e3a7aSWarner Losh 38028e3e3a7aSWarner Losh 38038e3e3a7aSWarner Losh 38048e3e3a7aSWarner Losh 38058e3e3a7aSWarner Losh<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> 38068e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 38078e3e3a7aSWarner Losh<pre>void lua_close (lua_State *L);</pre> 38088e3e3a7aSWarner Losh 38098e3e3a7aSWarner Losh<p> 38100495ed39SKyle EvansClose all active to-be-closed variables in the main thread, 38110495ed39SKyle Evansrelease all objects in the given Lua state 38120495ed39SKyle Evans(calling the corresponding garbage-collection metamethods, if any), 38138e3e3a7aSWarner Loshand frees all dynamic memory used by this state. 38140495ed39SKyle Evans 38150495ed39SKyle Evans 38160495ed39SKyle Evans<p> 38170495ed39SKyle EvansOn several platforms, you may not need to call this function, 38188e3e3a7aSWarner Loshbecause all resources are naturally released when the host program ends. 38198e3e3a7aSWarner LoshOn the other hand, long-running programs that create multiple states, 38208e3e3a7aSWarner Loshsuch as daemons or web servers, 38218e3e3a7aSWarner Loshwill probably need to close states as soon as they are not needed. 38228e3e3a7aSWarner Losh 38238e3e3a7aSWarner Losh 38248e3e3a7aSWarner Losh 38258e3e3a7aSWarner Losh 38268e3e3a7aSWarner Losh 38278c784bb8SWarner Losh<hr><h3><a name="lua_closeslot"><code>lua_closeslot</code></a></h3><p> 38288c784bb8SWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 38298c784bb8SWarner Losh<pre>void lua_closeslot (lua_State *L, int index);</pre> 38308c784bb8SWarner Losh 38318c784bb8SWarner Losh<p> 38328c784bb8SWarner LoshClose the to-be-closed slot at the given index and set its value to <b>nil</b>. 38338c784bb8SWarner LoshThe index must be the last index previously marked to be closed 38348c784bb8SWarner Losh(see <a href="#lua_toclose"><code>lua_toclose</code></a>) that is still active (that is, not closed yet). 38358c784bb8SWarner Losh 38368c784bb8SWarner Losh 38378c784bb8SWarner Losh<p> 38388c784bb8SWarner LoshA <code>__close</code> metamethod cannot yield 38398c784bb8SWarner Loshwhen called through this function. 38408c784bb8SWarner Losh 38418c784bb8SWarner Losh 38428c784bb8SWarner Losh<p> 3843*a9490b81SWarner Losh(This function was introduced in release 5.4.3.) 3844*a9490b81SWarner Losh 3845*a9490b81SWarner Losh 3846*a9490b81SWarner Losh 3847*a9490b81SWarner Losh 3848*a9490b81SWarner Losh 3849*a9490b81SWarner Losh<hr><h3><a name="lua_closethread"><code>lua_closethread</code></a></h3><p> 3850*a9490b81SWarner Losh<span class="apii">[-0, +?, –]</span> 3851*a9490b81SWarner Losh<pre>int lua_closethread (lua_State *L, lua_State *from);</pre> 3852*a9490b81SWarner Losh 3853*a9490b81SWarner Losh<p> 3854*a9490b81SWarner LoshResets a thread, cleaning its call stack and closing all pending 3855*a9490b81SWarner Loshto-be-closed variables. 3856*a9490b81SWarner LoshReturns a status code: 3857*a9490b81SWarner Losh<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for no errors in the thread 3858*a9490b81SWarner Losh(either the original error that stopped the thread or 3859*a9490b81SWarner Losherrors in closing methods), 3860*a9490b81SWarner Loshor an error status otherwise. 3861*a9490b81SWarner LoshIn case of error, 3862*a9490b81SWarner Loshleaves the error object on the top of the stack. 3863*a9490b81SWarner Losh 3864*a9490b81SWarner Losh 3865*a9490b81SWarner Losh<p> 3866*a9490b81SWarner LoshThe parameter <code>from</code> represents the coroutine that is resetting <code>L</code>. 3867*a9490b81SWarner LoshIf there is no such coroutine, 3868*a9490b81SWarner Loshthis parameter can be <code>NULL</code>. 3869*a9490b81SWarner Losh 3870*a9490b81SWarner Losh 3871*a9490b81SWarner Losh<p> 3872*a9490b81SWarner Losh(This function was introduced in release 5.4.6.) 38738c784bb8SWarner Losh 38748c784bb8SWarner Losh 38758c784bb8SWarner Losh 38768c784bb8SWarner Losh 38778c784bb8SWarner Losh 38788e3e3a7aSWarner Losh<hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p> 38798e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 38808e3e3a7aSWarner Losh<pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre> 38818e3e3a7aSWarner Losh 38828e3e3a7aSWarner Losh<p> 38838e3e3a7aSWarner LoshCompares two Lua values. 38848e3e3a7aSWarner LoshReturns 1 if the value at index <code>index1</code> satisfies <code>op</code> 38858e3e3a7aSWarner Loshwhen compared with the value at index <code>index2</code>, 38868e3e3a7aSWarner Loshfollowing the semantics of the corresponding Lua operator 38878e3e3a7aSWarner Losh(that is, it may call metamethods). 38888e3e3a7aSWarner LoshOtherwise returns 0. 38898e3e3a7aSWarner LoshAlso returns 0 if any of the indices is not valid. 38908e3e3a7aSWarner Losh 38918e3e3a7aSWarner Losh 38928e3e3a7aSWarner Losh<p> 38938e3e3a7aSWarner LoshThe value of <code>op</code> must be one of the following constants: 38948e3e3a7aSWarner Losh 38958e3e3a7aSWarner Losh<ul> 38968e3e3a7aSWarner Losh 38978e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li> 38988e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li> 38998e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li> 39008e3e3a7aSWarner Losh 39018e3e3a7aSWarner Losh</ul> 39028e3e3a7aSWarner Losh 39038e3e3a7aSWarner Losh 39048e3e3a7aSWarner Losh 39058e3e3a7aSWarner Losh 39068e3e3a7aSWarner Losh<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> 39078e3e3a7aSWarner Losh<span class="apii">[-n, +1, <em>e</em>]</span> 39088e3e3a7aSWarner Losh<pre>void lua_concat (lua_State *L, int n);</pre> 39098e3e3a7aSWarner Losh 39108e3e3a7aSWarner Losh<p> 39118e3e3a7aSWarner LoshConcatenates the <code>n</code> values at the top of the stack, 39120495ed39SKyle Evanspops them, and leaves the result on the top. 39138e3e3a7aSWarner LoshIf <code>n</code> is 1, the result is the single value on the stack 39148e3e3a7aSWarner Losh(that is, the function does nothing); 39158e3e3a7aSWarner Loshif <code>n</code> is 0, the result is the empty string. 39168e3e3a7aSWarner LoshConcatenation is performed following the usual semantics of Lua 39178e3e3a7aSWarner Losh(see <a href="#3.4.6">§3.4.6</a>). 39188e3e3a7aSWarner Losh 39198e3e3a7aSWarner Losh 39208e3e3a7aSWarner Losh 39218e3e3a7aSWarner Losh 39228e3e3a7aSWarner Losh 39238e3e3a7aSWarner Losh<hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p> 39248e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 39258e3e3a7aSWarner Losh<pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre> 39268e3e3a7aSWarner Losh 39278e3e3a7aSWarner Losh<p> 39288e3e3a7aSWarner LoshCopies the element at index <code>fromidx</code> 39298e3e3a7aSWarner Loshinto the valid index <code>toidx</code>, 39308e3e3a7aSWarner Loshreplacing the value at that position. 39318e3e3a7aSWarner LoshValues at other positions are not affected. 39328e3e3a7aSWarner Losh 39338e3e3a7aSWarner Losh 39348e3e3a7aSWarner Losh 39358e3e3a7aSWarner Losh 39368e3e3a7aSWarner Losh 39378e3e3a7aSWarner Losh<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> 39388e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 39398e3e3a7aSWarner Losh<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> 39408e3e3a7aSWarner Losh 39418e3e3a7aSWarner Losh<p> 39428e3e3a7aSWarner LoshCreates a new empty table and pushes it onto the stack. 39438e3e3a7aSWarner LoshParameter <code>narr</code> is a hint for how many elements the table 39448e3e3a7aSWarner Loshwill have as a sequence; 39458e3e3a7aSWarner Loshparameter <code>nrec</code> is a hint for how many other elements 39468e3e3a7aSWarner Loshthe table will have. 39478e3e3a7aSWarner LoshLua may use these hints to preallocate memory for the new table. 39480495ed39SKyle EvansThis preallocation may help performance when you know in advance 39498e3e3a7aSWarner Loshhow many elements the table will have. 39508e3e3a7aSWarner LoshOtherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. 39518e3e3a7aSWarner Losh 39528e3e3a7aSWarner Losh 39538e3e3a7aSWarner Losh 39548e3e3a7aSWarner Losh 39558e3e3a7aSWarner Losh 39568e3e3a7aSWarner Losh<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> 39578e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 39588e3e3a7aSWarner Losh<pre>int lua_dump (lua_State *L, 39598e3e3a7aSWarner Losh lua_Writer writer, 39608e3e3a7aSWarner Losh void *data, 39618e3e3a7aSWarner Losh int strip);</pre> 39628e3e3a7aSWarner Losh 39638e3e3a7aSWarner Losh<p> 39648e3e3a7aSWarner LoshDumps a function as a binary chunk. 39658e3e3a7aSWarner LoshReceives a Lua function on the top of the stack 39668e3e3a7aSWarner Loshand produces a binary chunk that, 39678e3e3a7aSWarner Loshif loaded again, 39688e3e3a7aSWarner Loshresults in a function equivalent to the one dumped. 39698e3e3a7aSWarner LoshAs it produces parts of the chunk, 39708e3e3a7aSWarner 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>) 39718e3e3a7aSWarner Loshwith the given <code>data</code> 39728e3e3a7aSWarner Loshto write them. 39738e3e3a7aSWarner Losh 39748e3e3a7aSWarner Losh 39758e3e3a7aSWarner Losh<p> 39768e3e3a7aSWarner LoshIf <code>strip</code> is true, 39778e3e3a7aSWarner Loshthe binary representation may not include all debug information 39788e3e3a7aSWarner Loshabout the function, 39798e3e3a7aSWarner Loshto save space. 39808e3e3a7aSWarner Losh 39818e3e3a7aSWarner Losh 39828e3e3a7aSWarner Losh<p> 39838e3e3a7aSWarner LoshThe value returned is the error code returned by the last 39848e3e3a7aSWarner Loshcall to the writer; 39858e3e3a7aSWarner Losh0 means no errors. 39868e3e3a7aSWarner Losh 39878e3e3a7aSWarner Losh 39888e3e3a7aSWarner Losh<p> 39898e3e3a7aSWarner LoshThis function does not pop the Lua function from the stack. 39908e3e3a7aSWarner Losh 39918e3e3a7aSWarner Losh 39928e3e3a7aSWarner Losh 39938e3e3a7aSWarner Losh 39948e3e3a7aSWarner Losh 39958e3e3a7aSWarner Losh<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> 39968e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>v</em>]</span> 39978e3e3a7aSWarner Losh<pre>int lua_error (lua_State *L);</pre> 39988e3e3a7aSWarner Losh 39998e3e3a7aSWarner Losh<p> 40000495ed39SKyle EvansRaises a Lua error, 40010495ed39SKyle Evansusing the value on the top of the stack as the error object. 40028e3e3a7aSWarner LoshThis function does a long jump, 40038e3e3a7aSWarner Loshand therefore never returns 40048e3e3a7aSWarner Losh(see <a href="#luaL_error"><code>luaL_error</code></a>). 40058e3e3a7aSWarner Losh 40068e3e3a7aSWarner Losh 40078e3e3a7aSWarner Losh 40088e3e3a7aSWarner Losh 40098e3e3a7aSWarner Losh 40108e3e3a7aSWarner Losh<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> 40110495ed39SKyle Evans<span class="apii">[-0, +0, –]</span> 40120495ed39SKyle Evans<pre>int lua_gc (lua_State *L, int what, ...);</pre> 40138e3e3a7aSWarner Losh 40148e3e3a7aSWarner Losh<p> 40158e3e3a7aSWarner LoshControls the garbage collector. 40168e3e3a7aSWarner Losh 40178e3e3a7aSWarner Losh 40188e3e3a7aSWarner Losh<p> 40198e3e3a7aSWarner LoshThis function performs several tasks, 40200495ed39SKyle Evansaccording to the value of the parameter <code>what</code>. 40210495ed39SKyle EvansFor options that need extra arguments, 40220495ed39SKyle Evansthey are listed after the option. 40238e3e3a7aSWarner Losh 40248e3e3a7aSWarner Losh<ul> 40258e3e3a7aSWarner Losh 40260495ed39SKyle Evans<li><b><code>LUA_GCCOLLECT</code>: </b> 40270495ed39SKyle EvansPerforms a full garbage-collection cycle. 40280495ed39SKyle Evans</li> 40290495ed39SKyle Evans 40308e3e3a7aSWarner Losh<li><b><code>LUA_GCSTOP</code>: </b> 40310495ed39SKyle EvansStops the garbage collector. 40328e3e3a7aSWarner Losh</li> 40338e3e3a7aSWarner Losh 40348e3e3a7aSWarner Losh<li><b><code>LUA_GCRESTART</code>: </b> 40350495ed39SKyle EvansRestarts the garbage collector. 40368e3e3a7aSWarner Losh</li> 40378e3e3a7aSWarner Losh 40388e3e3a7aSWarner Losh<li><b><code>LUA_GCCOUNT</code>: </b> 40390495ed39SKyle EvansReturns the current amount of memory (in Kbytes) in use by Lua. 40408e3e3a7aSWarner Losh</li> 40418e3e3a7aSWarner Losh 40428e3e3a7aSWarner Losh<li><b><code>LUA_GCCOUNTB</code>: </b> 40430495ed39SKyle EvansReturns the remainder of dividing the current amount of bytes of 40448e3e3a7aSWarner Loshmemory in use by Lua by 1024. 40458e3e3a7aSWarner Losh</li> 40468e3e3a7aSWarner Losh 40470495ed39SKyle Evans<li><b><code>LUA_GCSTEP</code> <code>(int stepsize)</code>: </b> 40480495ed39SKyle EvansPerforms an incremental step of garbage collection, 40490495ed39SKyle Evanscorresponding to the allocation of <code>stepsize</code> Kbytes. 40508e3e3a7aSWarner Losh</li> 40518e3e3a7aSWarner Losh 40528e3e3a7aSWarner Losh<li><b><code>LUA_GCISRUNNING</code>: </b> 40530495ed39SKyle EvansReturns a boolean that tells whether the collector is running 40548e3e3a7aSWarner Losh(i.e., not stopped). 40558e3e3a7aSWarner Losh</li> 40568e3e3a7aSWarner Losh 40570495ed39SKyle Evans<li><b><code>LUA_GCINC</code> (int pause, int stepmul, stepsize): </b> 40580495ed39SKyle EvansChanges the collector to incremental mode 40590495ed39SKyle Evanswith the given parameters (see <a href="#2.5.1">§2.5.1</a>). 40600495ed39SKyle EvansReturns the previous mode (<code>LUA_GCGEN</code> or <code>LUA_GCINC</code>). 40610495ed39SKyle Evans</li> 40628e3e3a7aSWarner Losh 40630495ed39SKyle Evans<li><b><code>LUA_GCGEN</code> (int minormul, int majormul): </b> 40640495ed39SKyle EvansChanges the collector to generational mode 40650495ed39SKyle Evanswith the given parameters (see <a href="#2.5.2">§2.5.2</a>). 40660495ed39SKyle EvansReturns the previous mode (<code>LUA_GCGEN</code> or <code>LUA_GCINC</code>). 40670495ed39SKyle Evans</li> 40680495ed39SKyle Evans 40690495ed39SKyle Evans</ul><p> 40708e3e3a7aSWarner LoshFor more details about these options, 40718e3e3a7aSWarner Loshsee <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>. 40728e3e3a7aSWarner Losh 40738e3e3a7aSWarner Losh 40748c784bb8SWarner Losh<p> 40758c784bb8SWarner LoshThis function should not be called by a finalizer. 40768c784bb8SWarner Losh 40778c784bb8SWarner Losh 40788e3e3a7aSWarner Losh 40798e3e3a7aSWarner Losh 40808e3e3a7aSWarner Losh 40818e3e3a7aSWarner Losh<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> 40828e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 40838e3e3a7aSWarner Losh<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> 40848e3e3a7aSWarner Losh 40858e3e3a7aSWarner Losh<p> 40868e3e3a7aSWarner LoshReturns the memory-allocation function of a given state. 40878e3e3a7aSWarner LoshIf <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the 40888e3e3a7aSWarner Loshopaque pointer given when the memory-allocator function was set. 40898e3e3a7aSWarner Losh 40908e3e3a7aSWarner Losh 40918e3e3a7aSWarner Losh 40928e3e3a7aSWarner Losh 40938e3e3a7aSWarner Losh 40948e3e3a7aSWarner Losh<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> 40958e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 40968e3e3a7aSWarner Losh<pre>int lua_getfield (lua_State *L, int index, const char *k);</pre> 40978e3e3a7aSWarner Losh 40988e3e3a7aSWarner Losh<p> 40998e3e3a7aSWarner LoshPushes onto the stack the value <code>t[k]</code>, 41008e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index. 41018e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 41028e3e3a7aSWarner Loshfor the "index" event (see <a href="#2.4">§2.4</a>). 41038e3e3a7aSWarner Losh 41048e3e3a7aSWarner Losh 41058e3e3a7aSWarner Losh<p> 41068e3e3a7aSWarner LoshReturns the type of the pushed value. 41078e3e3a7aSWarner Losh 41088e3e3a7aSWarner Losh 41098e3e3a7aSWarner Losh 41108e3e3a7aSWarner Losh 41118e3e3a7aSWarner Losh 41128e3e3a7aSWarner Losh<hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p> 41138e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 41148e3e3a7aSWarner Losh<pre>void *lua_getextraspace (lua_State *L);</pre> 41158e3e3a7aSWarner Losh 41168e3e3a7aSWarner Losh<p> 41178e3e3a7aSWarner LoshReturns a pointer to a raw memory area associated with the 41188e3e3a7aSWarner Loshgiven Lua state. 41198e3e3a7aSWarner LoshThe application can use this area for any purpose; 41208e3e3a7aSWarner LoshLua does not use it for anything. 41218e3e3a7aSWarner Losh 41228e3e3a7aSWarner Losh 41238e3e3a7aSWarner Losh<p> 41248e3e3a7aSWarner LoshEach new thread has this area initialized with a copy 41258e3e3a7aSWarner Loshof the area of the main thread. 41268e3e3a7aSWarner Losh 41278e3e3a7aSWarner Losh 41288e3e3a7aSWarner Losh<p> 41298e3e3a7aSWarner LoshBy default, this area has the size of a pointer to void, 41308e3e3a7aSWarner Loshbut you can recompile Lua with a different size for this area. 41318e3e3a7aSWarner Losh(See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.) 41328e3e3a7aSWarner Losh 41338e3e3a7aSWarner Losh 41348e3e3a7aSWarner Losh 41358e3e3a7aSWarner Losh 41368e3e3a7aSWarner Losh 41378e3e3a7aSWarner Losh<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> 41388e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 41398e3e3a7aSWarner Losh<pre>int lua_getglobal (lua_State *L, const char *name);</pre> 41408e3e3a7aSWarner Losh 41418e3e3a7aSWarner Losh<p> 41428e3e3a7aSWarner LoshPushes onto the stack the value of the global <code>name</code>. 41438e3e3a7aSWarner LoshReturns the type of that value. 41448e3e3a7aSWarner Losh 41458e3e3a7aSWarner Losh 41468e3e3a7aSWarner Losh 41478e3e3a7aSWarner Losh 41488e3e3a7aSWarner Losh 41498e3e3a7aSWarner Losh<hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p> 41508e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 41518e3e3a7aSWarner Losh<pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre> 41528e3e3a7aSWarner Losh 41538e3e3a7aSWarner Losh<p> 41548e3e3a7aSWarner LoshPushes onto the stack the value <code>t[i]</code>, 41558e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index. 41568e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 41578e3e3a7aSWarner Loshfor the "index" event (see <a href="#2.4">§2.4</a>). 41588e3e3a7aSWarner Losh 41598e3e3a7aSWarner Losh 41608e3e3a7aSWarner Losh<p> 41618e3e3a7aSWarner LoshReturns the type of the pushed value. 41628e3e3a7aSWarner Losh 41638e3e3a7aSWarner Losh 41648e3e3a7aSWarner Losh 41658e3e3a7aSWarner Losh 41668e3e3a7aSWarner Losh 41678e3e3a7aSWarner Losh<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> 41688e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), –]</span> 41698e3e3a7aSWarner Losh<pre>int lua_getmetatable (lua_State *L, int index);</pre> 41708e3e3a7aSWarner Losh 41718e3e3a7aSWarner Losh<p> 41728e3e3a7aSWarner LoshIf the value at the given index has a metatable, 41738e3e3a7aSWarner Loshthe function pushes that metatable onto the stack and returns 1. 41748e3e3a7aSWarner LoshOtherwise, 41758e3e3a7aSWarner Loshthe function returns 0 and pushes nothing on the stack. 41768e3e3a7aSWarner Losh 41778e3e3a7aSWarner Losh 41788e3e3a7aSWarner Losh 41798e3e3a7aSWarner Losh 41808e3e3a7aSWarner Losh 41818e3e3a7aSWarner Losh<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> 41828e3e3a7aSWarner Losh<span class="apii">[-1, +1, <em>e</em>]</span> 41838e3e3a7aSWarner Losh<pre>int lua_gettable (lua_State *L, int index);</pre> 41848e3e3a7aSWarner Losh 41858e3e3a7aSWarner Losh<p> 41868e3e3a7aSWarner LoshPushes onto the stack the value <code>t[k]</code>, 41878e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index 41880495ed39SKyle Evansand <code>k</code> is the value on the top of the stack. 41898e3e3a7aSWarner Losh 41908e3e3a7aSWarner Losh 41918e3e3a7aSWarner Losh<p> 41928e3e3a7aSWarner LoshThis function pops the key from the stack, 41938e3e3a7aSWarner Loshpushing the resulting value in its place. 41948e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 41958e3e3a7aSWarner Loshfor the "index" event (see <a href="#2.4">§2.4</a>). 41968e3e3a7aSWarner Losh 41978e3e3a7aSWarner Losh 41988e3e3a7aSWarner Losh<p> 41998e3e3a7aSWarner LoshReturns the type of the pushed value. 42008e3e3a7aSWarner Losh 42018e3e3a7aSWarner Losh 42028e3e3a7aSWarner Losh 42038e3e3a7aSWarner Losh 42048e3e3a7aSWarner Losh 42058e3e3a7aSWarner Losh<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> 42068e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 42078e3e3a7aSWarner Losh<pre>int lua_gettop (lua_State *L);</pre> 42088e3e3a7aSWarner Losh 42098e3e3a7aSWarner Losh<p> 42108e3e3a7aSWarner LoshReturns the index of the top element in the stack. 42118e3e3a7aSWarner LoshBecause indices start at 1, 42128e3e3a7aSWarner Loshthis result is equal to the number of elements in the stack; 42138e3e3a7aSWarner Loshin particular, 0 means an empty stack. 42148e3e3a7aSWarner Losh 42158e3e3a7aSWarner Losh 42168e3e3a7aSWarner Losh 42178e3e3a7aSWarner Losh 42188e3e3a7aSWarner Losh 42190495ed39SKyle Evans<hr><h3><a name="lua_getiuservalue"><code>lua_getiuservalue</code></a></h3><p> 42208e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 42210495ed39SKyle Evans<pre>int lua_getiuservalue (lua_State *L, int index, int n);</pre> 42228e3e3a7aSWarner Losh 42238e3e3a7aSWarner Losh<p> 42240495ed39SKyle EvansPushes onto the stack the <code>n</code>-th user value associated with the 42250495ed39SKyle Evansfull userdata at the given index and 42260495ed39SKyle Evansreturns the type of the pushed value. 42278e3e3a7aSWarner Losh 42288e3e3a7aSWarner Losh 42298e3e3a7aSWarner Losh<p> 42300495ed39SKyle EvansIf the userdata does not have that value, 42310495ed39SKyle Evanspushes <b>nil</b> and returns <a href="#pdf-LUA_TNONE"><code>LUA_TNONE</code></a>. 42328e3e3a7aSWarner Losh 42338e3e3a7aSWarner Losh 42348e3e3a7aSWarner Losh 42358e3e3a7aSWarner Losh 42368e3e3a7aSWarner Losh 42378e3e3a7aSWarner Losh<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> 42388e3e3a7aSWarner Losh<span class="apii">[-1, +1, –]</span> 42398e3e3a7aSWarner Losh<pre>void lua_insert (lua_State *L, int index);</pre> 42408e3e3a7aSWarner Losh 42418e3e3a7aSWarner Losh<p> 42428e3e3a7aSWarner LoshMoves the top element into the given valid index, 42438e3e3a7aSWarner Loshshifting up the elements above this index to open space. 42448e3e3a7aSWarner LoshThis function cannot be called with a pseudo-index, 42458e3e3a7aSWarner Loshbecause a pseudo-index is not an actual stack position. 42468e3e3a7aSWarner Losh 42478e3e3a7aSWarner Losh 42488e3e3a7aSWarner Losh 42498e3e3a7aSWarner Losh 42508e3e3a7aSWarner Losh 42518e3e3a7aSWarner Losh<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> 42528e3e3a7aSWarner Losh<pre>typedef ... lua_Integer;</pre> 42538e3e3a7aSWarner Losh 42548e3e3a7aSWarner Losh<p> 42558e3e3a7aSWarner LoshThe type of integers in Lua. 42568e3e3a7aSWarner Losh 42578e3e3a7aSWarner Losh 42588e3e3a7aSWarner Losh<p> 42598e3e3a7aSWarner LoshBy default this type is <code>long long</code>, 42608e3e3a7aSWarner Losh(usually a 64-bit two-complement integer), 42618e3e3a7aSWarner Loshbut that can be changed to <code>long</code> or <code>int</code> 42628e3e3a7aSWarner Losh(usually a 32-bit two-complement integer). 42638e3e3a7aSWarner Losh(See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.) 42648e3e3a7aSWarner Losh 42658e3e3a7aSWarner Losh 42668e3e3a7aSWarner Losh<p> 42678e3e3a7aSWarner LoshLua also defines the constants 42688e3e3a7aSWarner Losh<a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>, 42698e3e3a7aSWarner Loshwith the minimum and the maximum values that fit in this type. 42708e3e3a7aSWarner Losh 42718e3e3a7aSWarner Losh 42728e3e3a7aSWarner Losh 42738e3e3a7aSWarner Losh 42748e3e3a7aSWarner Losh 42758e3e3a7aSWarner Losh<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> 42768e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 42778e3e3a7aSWarner Losh<pre>int lua_isboolean (lua_State *L, int index);</pre> 42788e3e3a7aSWarner Losh 42798e3e3a7aSWarner Losh<p> 42808e3e3a7aSWarner LoshReturns 1 if the value at the given index is a boolean, 42818e3e3a7aSWarner Loshand 0 otherwise. 42828e3e3a7aSWarner Losh 42838e3e3a7aSWarner Losh 42848e3e3a7aSWarner Losh 42858e3e3a7aSWarner Losh 42868e3e3a7aSWarner Losh 42878e3e3a7aSWarner Losh<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> 42888e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 42898e3e3a7aSWarner Losh<pre>int lua_iscfunction (lua_State *L, int index);</pre> 42908e3e3a7aSWarner Losh 42918e3e3a7aSWarner Losh<p> 42928e3e3a7aSWarner LoshReturns 1 if the value at the given index is a C function, 42938e3e3a7aSWarner Loshand 0 otherwise. 42948e3e3a7aSWarner Losh 42958e3e3a7aSWarner Losh 42968e3e3a7aSWarner Losh 42978e3e3a7aSWarner Losh 42988e3e3a7aSWarner Losh 42998e3e3a7aSWarner Losh<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> 43008e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 43018e3e3a7aSWarner Losh<pre>int lua_isfunction (lua_State *L, int index);</pre> 43028e3e3a7aSWarner Losh 43038e3e3a7aSWarner Losh<p> 43048e3e3a7aSWarner LoshReturns 1 if the value at the given index is a function 43058e3e3a7aSWarner Losh(either C or Lua), and 0 otherwise. 43068e3e3a7aSWarner Losh 43078e3e3a7aSWarner Losh 43088e3e3a7aSWarner Losh 43098e3e3a7aSWarner Losh 43108e3e3a7aSWarner Losh 43118e3e3a7aSWarner Losh<hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p> 43128e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 43138e3e3a7aSWarner Losh<pre>int lua_isinteger (lua_State *L, int index);</pre> 43148e3e3a7aSWarner Losh 43158e3e3a7aSWarner Losh<p> 43168e3e3a7aSWarner LoshReturns 1 if the value at the given index is an integer 43178e3e3a7aSWarner Losh(that is, the value is a number and is represented as an integer), 43188e3e3a7aSWarner Loshand 0 otherwise. 43198e3e3a7aSWarner Losh 43208e3e3a7aSWarner Losh 43218e3e3a7aSWarner Losh 43228e3e3a7aSWarner Losh 43238e3e3a7aSWarner Losh 43248e3e3a7aSWarner Losh<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> 43258e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 43268e3e3a7aSWarner Losh<pre>int lua_islightuserdata (lua_State *L, int index);</pre> 43278e3e3a7aSWarner Losh 43288e3e3a7aSWarner Losh<p> 43298e3e3a7aSWarner LoshReturns 1 if the value at the given index is a light userdata, 43308e3e3a7aSWarner Loshand 0 otherwise. 43318e3e3a7aSWarner Losh 43328e3e3a7aSWarner Losh 43338e3e3a7aSWarner Losh 43348e3e3a7aSWarner Losh 43358e3e3a7aSWarner Losh 43368e3e3a7aSWarner Losh<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> 43378e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 43388e3e3a7aSWarner Losh<pre>int lua_isnil (lua_State *L, int index);</pre> 43398e3e3a7aSWarner Losh 43408e3e3a7aSWarner Losh<p> 43418e3e3a7aSWarner LoshReturns 1 if the value at the given index is <b>nil</b>, 43428e3e3a7aSWarner Loshand 0 otherwise. 43438e3e3a7aSWarner Losh 43448e3e3a7aSWarner Losh 43458e3e3a7aSWarner Losh 43468e3e3a7aSWarner Losh 43478e3e3a7aSWarner Losh 43488e3e3a7aSWarner Losh<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> 43498e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 43508e3e3a7aSWarner Losh<pre>int lua_isnone (lua_State *L, int index);</pre> 43518e3e3a7aSWarner Losh 43528e3e3a7aSWarner Losh<p> 43538e3e3a7aSWarner LoshReturns 1 if the given index is not valid, 43548e3e3a7aSWarner Loshand 0 otherwise. 43558e3e3a7aSWarner Losh 43568e3e3a7aSWarner Losh 43578e3e3a7aSWarner Losh 43588e3e3a7aSWarner Losh 43598e3e3a7aSWarner Losh 43608e3e3a7aSWarner Losh<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> 43618e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 43628e3e3a7aSWarner Losh<pre>int lua_isnoneornil (lua_State *L, int index);</pre> 43638e3e3a7aSWarner Losh 43648e3e3a7aSWarner Losh<p> 43658e3e3a7aSWarner LoshReturns 1 if the given index is not valid 43668e3e3a7aSWarner Loshor if the value at this index is <b>nil</b>, 43678e3e3a7aSWarner Loshand 0 otherwise. 43688e3e3a7aSWarner Losh 43698e3e3a7aSWarner Losh 43708e3e3a7aSWarner Losh 43718e3e3a7aSWarner Losh 43728e3e3a7aSWarner Losh 43738e3e3a7aSWarner Losh<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> 43748e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 43758e3e3a7aSWarner Losh<pre>int lua_isnumber (lua_State *L, int index);</pre> 43768e3e3a7aSWarner Losh 43778e3e3a7aSWarner Losh<p> 43788e3e3a7aSWarner LoshReturns 1 if the value at the given index is a number 43798e3e3a7aSWarner Loshor a string convertible to a number, 43808e3e3a7aSWarner Loshand 0 otherwise. 43818e3e3a7aSWarner Losh 43828e3e3a7aSWarner Losh 43838e3e3a7aSWarner Losh 43848e3e3a7aSWarner Losh 43858e3e3a7aSWarner Losh 43868e3e3a7aSWarner Losh<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> 43878e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 43888e3e3a7aSWarner Losh<pre>int lua_isstring (lua_State *L, int index);</pre> 43898e3e3a7aSWarner Losh 43908e3e3a7aSWarner Losh<p> 43918e3e3a7aSWarner LoshReturns 1 if the value at the given index is a string 43928e3e3a7aSWarner Loshor a number (which is always convertible to a string), 43938e3e3a7aSWarner Loshand 0 otherwise. 43948e3e3a7aSWarner Losh 43958e3e3a7aSWarner Losh 43968e3e3a7aSWarner Losh 43978e3e3a7aSWarner Losh 43988e3e3a7aSWarner Losh 43998e3e3a7aSWarner Losh<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> 44008e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 44018e3e3a7aSWarner Losh<pre>int lua_istable (lua_State *L, int index);</pre> 44028e3e3a7aSWarner Losh 44038e3e3a7aSWarner Losh<p> 44048e3e3a7aSWarner LoshReturns 1 if the value at the given index is a table, 44058e3e3a7aSWarner Loshand 0 otherwise. 44068e3e3a7aSWarner Losh 44078e3e3a7aSWarner Losh 44088e3e3a7aSWarner Losh 44098e3e3a7aSWarner Losh 44108e3e3a7aSWarner Losh 44118e3e3a7aSWarner Losh<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> 44128e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 44138e3e3a7aSWarner Losh<pre>int lua_isthread (lua_State *L, int index);</pre> 44148e3e3a7aSWarner Losh 44158e3e3a7aSWarner Losh<p> 44168e3e3a7aSWarner LoshReturns 1 if the value at the given index is a thread, 44178e3e3a7aSWarner Loshand 0 otherwise. 44188e3e3a7aSWarner Losh 44198e3e3a7aSWarner Losh 44208e3e3a7aSWarner Losh 44218e3e3a7aSWarner Losh 44228e3e3a7aSWarner Losh 44238e3e3a7aSWarner Losh<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> 44248e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 44258e3e3a7aSWarner Losh<pre>int lua_isuserdata (lua_State *L, int index);</pre> 44268e3e3a7aSWarner Losh 44278e3e3a7aSWarner Losh<p> 44288e3e3a7aSWarner LoshReturns 1 if the value at the given index is a userdata 44298e3e3a7aSWarner Losh(either full or light), and 0 otherwise. 44308e3e3a7aSWarner Losh 44318e3e3a7aSWarner Losh 44328e3e3a7aSWarner Losh 44338e3e3a7aSWarner Losh 44348e3e3a7aSWarner Losh 44358e3e3a7aSWarner Losh<hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p> 44368e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 44378e3e3a7aSWarner Losh<pre>int lua_isyieldable (lua_State *L);</pre> 44388e3e3a7aSWarner Losh 44398e3e3a7aSWarner Losh<p> 44408e3e3a7aSWarner LoshReturns 1 if the given coroutine can yield, 44418e3e3a7aSWarner Loshand 0 otherwise. 44428e3e3a7aSWarner Losh 44438e3e3a7aSWarner Losh 44448e3e3a7aSWarner Losh 44458e3e3a7aSWarner Losh 44468e3e3a7aSWarner Losh 44478e3e3a7aSWarner Losh<hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3> 44488e3e3a7aSWarner Losh<pre>typedef ... lua_KContext;</pre> 44498e3e3a7aSWarner Losh 44508e3e3a7aSWarner Losh<p> 44518e3e3a7aSWarner LoshThe type for continuation-function contexts. 44528e3e3a7aSWarner LoshIt must be a numeric type. 44538e3e3a7aSWarner LoshThis type is defined as <code>intptr_t</code> 44548e3e3a7aSWarner Loshwhen <code>intptr_t</code> is available, 44558e3e3a7aSWarner Loshso that it can store pointers too. 44568e3e3a7aSWarner LoshOtherwise, it is defined as <code>ptrdiff_t</code>. 44578e3e3a7aSWarner Losh 44588e3e3a7aSWarner Losh 44598e3e3a7aSWarner Losh 44608e3e3a7aSWarner Losh 44618e3e3a7aSWarner Losh 44628e3e3a7aSWarner Losh<hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3> 44638e3e3a7aSWarner Losh<pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre> 44648e3e3a7aSWarner Losh 44658e3e3a7aSWarner Losh<p> 44660495ed39SKyle EvansType for continuation functions (see <a href="#4.5">§4.5</a>). 44678e3e3a7aSWarner Losh 44688e3e3a7aSWarner Losh 44698e3e3a7aSWarner Losh 44708e3e3a7aSWarner Losh 44718e3e3a7aSWarner Losh 44728e3e3a7aSWarner Losh<hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p> 44738e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 44748e3e3a7aSWarner Losh<pre>void lua_len (lua_State *L, int index);</pre> 44758e3e3a7aSWarner Losh 44768e3e3a7aSWarner Losh<p> 44778e3e3a7aSWarner LoshReturns the length of the value at the given index. 44788e3e3a7aSWarner LoshIt is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>) and 44798e3e3a7aSWarner Loshmay trigger a metamethod for the "length" event (see <a href="#2.4">§2.4</a>). 44808e3e3a7aSWarner LoshThe result is pushed on the stack. 44818e3e3a7aSWarner Losh 44828e3e3a7aSWarner Losh 44838e3e3a7aSWarner Losh 44848e3e3a7aSWarner Losh 44858e3e3a7aSWarner Losh 44868e3e3a7aSWarner Losh<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> 44878e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 44888e3e3a7aSWarner Losh<pre>int lua_load (lua_State *L, 44898e3e3a7aSWarner Losh lua_Reader reader, 44908e3e3a7aSWarner Losh void *data, 44918e3e3a7aSWarner Losh const char *chunkname, 44928e3e3a7aSWarner Losh const char *mode);</pre> 44938e3e3a7aSWarner Losh 44948e3e3a7aSWarner Losh<p> 44958e3e3a7aSWarner LoshLoads a Lua chunk without running it. 44968e3e3a7aSWarner LoshIf there are no errors, 44978e3e3a7aSWarner Losh<code>lua_load</code> pushes the compiled chunk as a Lua 44988e3e3a7aSWarner Loshfunction on top of the stack. 44998e3e3a7aSWarner LoshOtherwise, it pushes an error message. 45008e3e3a7aSWarner Losh 45018e3e3a7aSWarner Losh 45028e3e3a7aSWarner Losh<p> 45038e3e3a7aSWarner LoshThe <code>lua_load</code> function uses a user-supplied <code>reader</code> function 45048e3e3a7aSWarner Loshto read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). 45058e3e3a7aSWarner LoshThe <code>data</code> argument is an opaque value passed to the reader function. 45068e3e3a7aSWarner Losh 45078e3e3a7aSWarner Losh 45088e3e3a7aSWarner Losh<p> 45098e3e3a7aSWarner LoshThe <code>chunkname</code> argument gives a name to the chunk, 45100495ed39SKyle Evanswhich is used for error messages and in debug information (see <a href="#4.7">§4.7</a>). 45118e3e3a7aSWarner Losh 45128e3e3a7aSWarner Losh 45138e3e3a7aSWarner Losh<p> 45148e3e3a7aSWarner Losh<code>lua_load</code> automatically detects whether the chunk is text or binary 45158e3e3a7aSWarner Loshand loads it accordingly (see program <code>luac</code>). 45168e3e3a7aSWarner LoshThe string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>, 45178e3e3a7aSWarner Loshwith the addition that 45188e3e3a7aSWarner Losha <code>NULL</code> value is equivalent to the string "<code>bt</code>". 45198e3e3a7aSWarner Losh 45208e3e3a7aSWarner Losh 45218e3e3a7aSWarner Losh<p> 45228e3e3a7aSWarner Losh<code>lua_load</code> uses the stack internally, 45238e3e3a7aSWarner Loshso the reader function must always leave the stack 45248e3e3a7aSWarner Loshunmodified when returning. 45258e3e3a7aSWarner Losh 45268e3e3a7aSWarner Losh 45278e3e3a7aSWarner Losh<p> 45280495ed39SKyle Evans<code>lua_load</code> can return 45290495ed39SKyle Evans<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>, <a href="#pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>, or <a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>. 45300495ed39SKyle EvansThe function may also return other values corresponding to 45310495ed39SKyle Evanserrors raised by the read function (see <a href="#4.4.1">§4.4.1</a>). 45320495ed39SKyle Evans 45330495ed39SKyle Evans 45340495ed39SKyle Evans<p> 45358e3e3a7aSWarner LoshIf the resulting function has upvalues, 45368e3e3a7aSWarner Loshits first upvalue is set to the value of the global environment 45370495ed39SKyle Evansstored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.3">§4.3</a>). 45388e3e3a7aSWarner LoshWhen loading main chunks, 45398e3e3a7aSWarner Loshthis upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 45408e3e3a7aSWarner LoshOther upvalues are initialized with <b>nil</b>. 45418e3e3a7aSWarner Losh 45428e3e3a7aSWarner Losh 45438e3e3a7aSWarner Losh 45448e3e3a7aSWarner Losh 45458e3e3a7aSWarner Losh 45468e3e3a7aSWarner Losh<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> 45478e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 45488e3e3a7aSWarner Losh<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> 45498e3e3a7aSWarner Losh 45508e3e3a7aSWarner Losh<p> 45510495ed39SKyle EvansCreates a new independent state and returns its main thread. 45520495ed39SKyle EvansReturns <code>NULL</code> if it cannot create the state 45538e3e3a7aSWarner Losh(due to lack of memory). 45548e3e3a7aSWarner LoshThe argument <code>f</code> is the allocator function; 45550495ed39SKyle EvansLua will do all memory allocation for this state 45568e3e3a7aSWarner Loshthrough this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>). 45578e3e3a7aSWarner LoshThe second argument, <code>ud</code>, is an opaque pointer that Lua 45588e3e3a7aSWarner Loshpasses to the allocator in every call. 45598e3e3a7aSWarner Losh 45608e3e3a7aSWarner Losh 45618e3e3a7aSWarner Losh 45628e3e3a7aSWarner Losh 45638e3e3a7aSWarner Losh 45648e3e3a7aSWarner Losh<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> 45658e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 45668e3e3a7aSWarner Losh<pre>void lua_newtable (lua_State *L);</pre> 45678e3e3a7aSWarner Losh 45688e3e3a7aSWarner Losh<p> 45698e3e3a7aSWarner LoshCreates a new empty table and pushes it onto the stack. 45708e3e3a7aSWarner LoshIt is equivalent to <code>lua_createtable(L, 0, 0)</code>. 45718e3e3a7aSWarner Losh 45728e3e3a7aSWarner Losh 45738e3e3a7aSWarner Losh 45748e3e3a7aSWarner Losh 45758e3e3a7aSWarner Losh 45768e3e3a7aSWarner Losh<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> 45778e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 45788e3e3a7aSWarner Losh<pre>lua_State *lua_newthread (lua_State *L);</pre> 45798e3e3a7aSWarner Losh 45808e3e3a7aSWarner Losh<p> 45818e3e3a7aSWarner LoshCreates a new thread, pushes it on the stack, 45828e3e3a7aSWarner Loshand returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. 45838e3e3a7aSWarner LoshThe new thread returned by this function shares with the original thread 45848e3e3a7aSWarner Loshits global environment, 45858e3e3a7aSWarner Loshbut has an independent execution stack. 45868e3e3a7aSWarner Losh 45878e3e3a7aSWarner Losh 45888e3e3a7aSWarner Losh<p> 45898e3e3a7aSWarner LoshThreads are subject to garbage collection, 45908e3e3a7aSWarner Loshlike any Lua object. 45918e3e3a7aSWarner Losh 45928e3e3a7aSWarner Losh 45938e3e3a7aSWarner Losh 45948e3e3a7aSWarner Losh 45958e3e3a7aSWarner Losh 45960495ed39SKyle Evans<hr><h3><a name="lua_newuserdatauv"><code>lua_newuserdatauv</code></a></h3><p> 45978e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 45980495ed39SKyle Evans<pre>void *lua_newuserdatauv (lua_State *L, size_t size, int nuvalue);</pre> 45998e3e3a7aSWarner Losh 46008e3e3a7aSWarner Losh<p> 46010495ed39SKyle EvansThis function creates and pushes on the stack a new full userdata, 46020495ed39SKyle Evanswith <code>nuvalue</code> associated Lua values, called <code>user values</code>, 46030495ed39SKyle Evansplus an associated block of raw memory with <code>size</code> bytes. 46040495ed39SKyle Evans(The user values can be set and read with the functions 46050495ed39SKyle Evans<a href="#lua_setiuservalue"><code>lua_setiuservalue</code></a> and <a href="#lua_getiuservalue"><code>lua_getiuservalue</code></a>.) 46060495ed39SKyle Evans 46070495ed39SKyle Evans 46080495ed39SKyle Evans<p> 46090495ed39SKyle EvansThe function returns the address of the block of memory. 46100495ed39SKyle EvansLua ensures that this address is valid as long as 46110495ed39SKyle Evansthe corresponding userdata is alive (see <a href="#2.5">§2.5</a>). 46120495ed39SKyle EvansMoreover, if the userdata is marked for finalization (see <a href="#2.5.3">§2.5.3</a>), 46130495ed39SKyle Evansits address is valid at least until the call to its finalizer. 46148e3e3a7aSWarner Losh 46158e3e3a7aSWarner Losh 46168e3e3a7aSWarner Losh 46178e3e3a7aSWarner Losh 46188e3e3a7aSWarner Losh 46198e3e3a7aSWarner Losh<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> 46200495ed39SKyle Evans<span class="apii">[-1, +(2|0), <em>v</em>]</span> 46218e3e3a7aSWarner Losh<pre>int lua_next (lua_State *L, int index);</pre> 46228e3e3a7aSWarner Losh 46238e3e3a7aSWarner Losh<p> 46248e3e3a7aSWarner LoshPops a key from the stack, 46250495ed39SKyle Evansand pushes a key–value pair from the table at the given index, 46260495ed39SKyle Evansthe "next" pair after the given key. 46278e3e3a7aSWarner LoshIf there are no more elements in the table, 4628*a9490b81SWarner Loshthen <a href="#lua_next"><code>lua_next</code></a> returns 0 and pushes nothing. 46298e3e3a7aSWarner Losh 46308e3e3a7aSWarner Losh 46318e3e3a7aSWarner Losh<p> 46320495ed39SKyle EvansA typical table traversal looks like this: 46338e3e3a7aSWarner Losh 46348e3e3a7aSWarner Losh<pre> 46358e3e3a7aSWarner Losh /* table is in the stack at index 't' */ 46368e3e3a7aSWarner Losh lua_pushnil(L); /* first key */ 46378e3e3a7aSWarner Losh while (lua_next(L, t) != 0) { 46388e3e3a7aSWarner Losh /* uses 'key' (at index -2) and 'value' (at index -1) */ 46398e3e3a7aSWarner Losh printf("%s - %s\n", 46408e3e3a7aSWarner Losh lua_typename(L, lua_type(L, -2)), 46418e3e3a7aSWarner Losh lua_typename(L, lua_type(L, -1))); 46428e3e3a7aSWarner Losh /* removes 'value'; keeps 'key' for next iteration */ 46438e3e3a7aSWarner Losh lua_pop(L, 1); 46448e3e3a7aSWarner Losh } 46458e3e3a7aSWarner Losh</pre> 46468e3e3a7aSWarner Losh 46478e3e3a7aSWarner Losh<p> 46488e3e3a7aSWarner LoshWhile traversing a table, 46490495ed39SKyle Evansavoid calling <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, 46508e3e3a7aSWarner Loshunless you know that the key is actually a string. 46518e3e3a7aSWarner LoshRecall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change 46528e3e3a7aSWarner Loshthe value at the given index; 46538e3e3a7aSWarner Loshthis confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. 46548e3e3a7aSWarner Losh 46558e3e3a7aSWarner Losh 46568e3e3a7aSWarner Losh<p> 46570495ed39SKyle EvansThis function may raise an error if the given key 46580495ed39SKyle Evansis neither <b>nil</b> nor present in the table. 46598e3e3a7aSWarner LoshSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 46608e3e3a7aSWarner Loshthe table during its traversal. 46618e3e3a7aSWarner Losh 46628e3e3a7aSWarner Losh 46638e3e3a7aSWarner Losh 46648e3e3a7aSWarner Losh 46658e3e3a7aSWarner Losh 46668e3e3a7aSWarner Losh<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> 46678e3e3a7aSWarner Losh<pre>typedef ... lua_Number;</pre> 46688e3e3a7aSWarner Losh 46698e3e3a7aSWarner Losh<p> 46708e3e3a7aSWarner LoshThe type of floats in Lua. 46718e3e3a7aSWarner Losh 46728e3e3a7aSWarner Losh 46738e3e3a7aSWarner Losh<p> 46748e3e3a7aSWarner LoshBy default this type is double, 46758e3e3a7aSWarner Loshbut that can be changed to a single float or a long double. 46768e3e3a7aSWarner Losh(See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.) 46778e3e3a7aSWarner Losh 46788e3e3a7aSWarner Losh 46798e3e3a7aSWarner Losh 46808e3e3a7aSWarner Losh 46818e3e3a7aSWarner Losh 46828e3e3a7aSWarner Losh<hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3> 46838e3e3a7aSWarner Losh<pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre> 46848e3e3a7aSWarner Losh 46858e3e3a7aSWarner Losh<p> 46860495ed39SKyle EvansTries to convert a Lua float to a Lua integer; 46870495ed39SKyle Evansthe float <code>n</code> must have an integral value. 46888e3e3a7aSWarner LoshIf that value is within the range of Lua integers, 46898e3e3a7aSWarner Loshit is converted to an integer and assigned to <code>*p</code>. 46908e3e3a7aSWarner LoshThe macro results in a boolean indicating whether the 46918e3e3a7aSWarner Loshconversion was successful. 46928e3e3a7aSWarner Losh(Note that this range test can be tricky to do 46930495ed39SKyle Evanscorrectly without this macro, due to rounding.) 46948e3e3a7aSWarner Losh 46958e3e3a7aSWarner Losh 46968e3e3a7aSWarner Losh<p> 46978e3e3a7aSWarner LoshThis macro may evaluate its arguments more than once. 46988e3e3a7aSWarner Losh 46998e3e3a7aSWarner Losh 47008e3e3a7aSWarner Losh 47018e3e3a7aSWarner Losh 47028e3e3a7aSWarner Losh 47038e3e3a7aSWarner Losh<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> 47048e3e3a7aSWarner Losh<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 47058e3e3a7aSWarner Losh<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre> 47068e3e3a7aSWarner Losh 47078e3e3a7aSWarner Losh<p> 47080495ed39SKyle EvansCalls a function (or a callable object) in protected mode. 47098e3e3a7aSWarner Losh 47108e3e3a7aSWarner Losh 47118e3e3a7aSWarner Losh<p> 47128e3e3a7aSWarner LoshBoth <code>nargs</code> and <code>nresults</code> have the same meaning as 47138e3e3a7aSWarner Loshin <a href="#lua_call"><code>lua_call</code></a>. 47148e3e3a7aSWarner LoshIf there are no errors during the call, 47158e3e3a7aSWarner Losh<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. 47168e3e3a7aSWarner LoshHowever, if there is any error, 47178e3e3a7aSWarner Losh<a href="#lua_pcall"><code>lua_pcall</code></a> catches it, 47188e3e3a7aSWarner Loshpushes a single value on the stack (the error object), 47198e3e3a7aSWarner Loshand returns an error code. 47208e3e3a7aSWarner LoshLike <a href="#lua_call"><code>lua_call</code></a>, 47218e3e3a7aSWarner Losh<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function 47228e3e3a7aSWarner Loshand its arguments from the stack. 47238e3e3a7aSWarner Losh 47248e3e3a7aSWarner Losh 47258e3e3a7aSWarner Losh<p> 47268e3e3a7aSWarner LoshIf <code>msgh</code> is 0, 47278e3e3a7aSWarner Loshthen the error object returned on the stack 47288e3e3a7aSWarner Loshis exactly the original error object. 47298e3e3a7aSWarner LoshOtherwise, <code>msgh</code> is the stack index of a 47308e3e3a7aSWarner Losh<em>message handler</em>. 47318e3e3a7aSWarner Losh(This index cannot be a pseudo-index.) 47328e3e3a7aSWarner LoshIn case of runtime errors, 47330495ed39SKyle Evansthis handler will be called with the error object 47348e3e3a7aSWarner Loshand its return value will be the object 47358e3e3a7aSWarner Loshreturned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. 47368e3e3a7aSWarner Losh 47378e3e3a7aSWarner Losh 47388e3e3a7aSWarner Losh<p> 47398e3e3a7aSWarner LoshTypically, the message handler is used to add more debug 47408e3e3a7aSWarner Loshinformation to the error object, such as a stack traceback. 47418e3e3a7aSWarner LoshSuch information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, 47428e3e3a7aSWarner Loshsince by then the stack has unwound. 47438e3e3a7aSWarner Losh 47448e3e3a7aSWarner Losh 47458e3e3a7aSWarner Losh<p> 47460495ed39SKyle EvansThe <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following status codes: 47470495ed39SKyle Evans<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>, <a href="#pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>, <a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>, or <a href="#pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>. 47488e3e3a7aSWarner Losh 47498e3e3a7aSWarner Losh 47508e3e3a7aSWarner Losh 47518e3e3a7aSWarner Losh 47528e3e3a7aSWarner Losh 47538e3e3a7aSWarner Losh<hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p> 47548e3e3a7aSWarner Losh<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 47558e3e3a7aSWarner Losh<pre>int lua_pcallk (lua_State *L, 47568e3e3a7aSWarner Losh int nargs, 47578e3e3a7aSWarner Losh int nresults, 47588e3e3a7aSWarner Losh int msgh, 47598e3e3a7aSWarner Losh lua_KContext ctx, 47608e3e3a7aSWarner Losh lua_KFunction k);</pre> 47618e3e3a7aSWarner Losh 47628e3e3a7aSWarner Losh<p> 47638e3e3a7aSWarner LoshThis function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>, 47640495ed39SKyle Evansexcept that it allows the called function to yield (see <a href="#4.5">§4.5</a>). 47658e3e3a7aSWarner Losh 47668e3e3a7aSWarner Losh 47678e3e3a7aSWarner Losh 47688e3e3a7aSWarner Losh 47698e3e3a7aSWarner Losh 47708e3e3a7aSWarner Losh<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> 47710495ed39SKyle Evans<span class="apii">[-n, +0, <em>e</em>]</span> 47728e3e3a7aSWarner Losh<pre>void lua_pop (lua_State *L, int n);</pre> 47738e3e3a7aSWarner Losh 47748e3e3a7aSWarner Losh<p> 47758e3e3a7aSWarner LoshPops <code>n</code> elements from the stack. 47768c784bb8SWarner LoshIt is implemented as a macro over <a href="#lua_settop"><code>lua_settop</code></a>. 47770495ed39SKyle Evans 47780495ed39SKyle Evans 47798e3e3a7aSWarner Losh 47808e3e3a7aSWarner Losh 47818e3e3a7aSWarner Losh 47828e3e3a7aSWarner Losh<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> 47838e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 47848e3e3a7aSWarner Losh<pre>void lua_pushboolean (lua_State *L, int b);</pre> 47858e3e3a7aSWarner Losh 47868e3e3a7aSWarner Losh<p> 47878e3e3a7aSWarner LoshPushes a boolean value with value <code>b</code> onto the stack. 47888e3e3a7aSWarner Losh 47898e3e3a7aSWarner Losh 47908e3e3a7aSWarner Losh 47918e3e3a7aSWarner Losh 47928e3e3a7aSWarner Losh 47938e3e3a7aSWarner Losh<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> 47948e3e3a7aSWarner Losh<span class="apii">[-n, +1, <em>m</em>]</span> 47958e3e3a7aSWarner Losh<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> 47968e3e3a7aSWarner Losh 47978e3e3a7aSWarner Losh<p> 47988e3e3a7aSWarner LoshPushes a new C closure onto the stack. 47990495ed39SKyle EvansThis function receives a pointer to a C function 48000495ed39SKyle Evansand pushes onto the stack a Lua value of type <code>function</code> that, 48010495ed39SKyle Evanswhen called, invokes the corresponding C function. 48020495ed39SKyle EvansThe parameter <code>n</code> tells how many upvalues this function will have 48030495ed39SKyle Evans(see <a href="#4.2">§4.2</a>). 48040495ed39SKyle Evans 48050495ed39SKyle Evans 48060495ed39SKyle Evans<p> 48070495ed39SKyle EvansAny function to be callable by Lua must 48080495ed39SKyle Evansfollow the correct protocol to receive its parameters 48090495ed39SKyle Evansand return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 48108e3e3a7aSWarner Losh 48118e3e3a7aSWarner Losh 48128e3e3a7aSWarner Losh<p> 48138e3e3a7aSWarner LoshWhen a C function is created, 48148e3e3a7aSWarner Loshit is possible to associate some values with it, 48150495ed39SKyle Evansthe so called upvalues; 48160495ed39SKyle Evansthese upvalues are then accessible to the function whenever it is called. 48170495ed39SKyle EvansThis association is called a C closure (see <a href="#4.2">§4.2</a>). 48180495ed39SKyle EvansTo create a C closure, 48190495ed39SKyle Evansfirst the initial values for its upvalues must be pushed onto the stack. 48200495ed39SKyle Evans(When there are multiple upvalues, the first value is pushed first.) 48218e3e3a7aSWarner LoshThen <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 48228e3e3a7aSWarner Loshis called to create and push the C function onto the stack, 48238e3e3a7aSWarner Loshwith the argument <code>n</code> telling how many values will be 48248e3e3a7aSWarner Loshassociated with the function. 48258e3e3a7aSWarner Losh<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. 48268e3e3a7aSWarner Losh 48278e3e3a7aSWarner Losh 48288e3e3a7aSWarner Losh<p> 48298e3e3a7aSWarner LoshThe maximum value for <code>n</code> is 255. 48308e3e3a7aSWarner Losh 48318e3e3a7aSWarner Losh 48328e3e3a7aSWarner Losh<p> 48338e3e3a7aSWarner LoshWhen <code>n</code> is zero, 48348e3e3a7aSWarner Loshthis function creates a <em>light C function</em>, 48358e3e3a7aSWarner Loshwhich is just a pointer to the C function. 48368e3e3a7aSWarner LoshIn that case, it never raises a memory error. 48378e3e3a7aSWarner Losh 48388e3e3a7aSWarner Losh 48398e3e3a7aSWarner Losh 48408e3e3a7aSWarner Losh 48418e3e3a7aSWarner Losh 48428e3e3a7aSWarner Losh<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> 48438e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 48448e3e3a7aSWarner Losh<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> 48458e3e3a7aSWarner Losh 48468e3e3a7aSWarner Losh<p> 48478e3e3a7aSWarner LoshPushes a C function onto the stack. 48480495ed39SKyle EvansThis function is equivalent to <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> with no upvalues. 48498e3e3a7aSWarner Losh 48508e3e3a7aSWarner Losh 48518e3e3a7aSWarner Losh 48528e3e3a7aSWarner Losh 48538e3e3a7aSWarner Losh 48548e3e3a7aSWarner Losh<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> 48550495ed39SKyle Evans<span class="apii">[-0, +1, <em>v</em>]</span> 48568e3e3a7aSWarner Losh<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> 48578e3e3a7aSWarner Losh 48588e3e3a7aSWarner Losh<p> 48598e3e3a7aSWarner LoshPushes onto the stack a formatted string 48600495ed39SKyle Evansand returns a pointer to this string (see <a href="#4.1.3">§4.1.3</a>). 48618e3e3a7aSWarner LoshIt is similar to the ISO C function <code>sprintf</code>, 48620495ed39SKyle Evansbut has two important differences. 48630495ed39SKyle EvansFirst, 48640495ed39SKyle Evansyou do not have to allocate space for the result; 48658e3e3a7aSWarner Loshthe result is a Lua string and Lua takes care of memory allocation 48668e3e3a7aSWarner Losh(and deallocation, through garbage collection). 48670495ed39SKyle EvansSecond, 48680495ed39SKyle Evansthe conversion specifiers are quite restricted. 48698e3e3a7aSWarner LoshThere are no flags, widths, or precisions. 48708e3e3a7aSWarner LoshThe conversion specifiers can only be 48718e3e3a7aSWarner Losh'<code>%%</code>' (inserts the character '<code>%</code>'), 48728e3e3a7aSWarner Losh'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), 48738e3e3a7aSWarner Losh'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), 48748e3e3a7aSWarner Losh'<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>), 48750495ed39SKyle Evans'<code>%p</code>' (inserts a pointer), 48768e3e3a7aSWarner Losh'<code>%d</code>' (inserts an <code>int</code>), 48778e3e3a7aSWarner Losh'<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and 48788e3e3a7aSWarner Losh'<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence). 48798e3e3a7aSWarner Losh 48808e3e3a7aSWarner Losh 48818e3e3a7aSWarner Losh<p> 48820495ed39SKyle EvansThis function may raise errors due to memory overflow 48830495ed39SKyle Evansor an invalid conversion specifier. 48848e3e3a7aSWarner Losh 48858e3e3a7aSWarner Losh 48868e3e3a7aSWarner Losh 48878e3e3a7aSWarner Losh 48888e3e3a7aSWarner Losh 48898e3e3a7aSWarner Losh<hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p> 48908e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 48918e3e3a7aSWarner Losh<pre>void lua_pushglobaltable (lua_State *L);</pre> 48928e3e3a7aSWarner Losh 48938e3e3a7aSWarner Losh<p> 48948e3e3a7aSWarner LoshPushes the global environment onto the stack. 48958e3e3a7aSWarner Losh 48968e3e3a7aSWarner Losh 48978e3e3a7aSWarner Losh 48988e3e3a7aSWarner Losh 48998e3e3a7aSWarner Losh 49008e3e3a7aSWarner Losh<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> 49018e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 49028e3e3a7aSWarner Losh<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> 49038e3e3a7aSWarner Losh 49048e3e3a7aSWarner Losh<p> 49058e3e3a7aSWarner LoshPushes an integer with value <code>n</code> onto the stack. 49068e3e3a7aSWarner Losh 49078e3e3a7aSWarner Losh 49088e3e3a7aSWarner Losh 49098e3e3a7aSWarner Losh 49108e3e3a7aSWarner Losh 49118e3e3a7aSWarner Losh<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> 49128e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 49138e3e3a7aSWarner Losh<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> 49148e3e3a7aSWarner Losh 49158e3e3a7aSWarner Losh<p> 49168e3e3a7aSWarner LoshPushes a light userdata onto the stack. 49178e3e3a7aSWarner Losh 49188e3e3a7aSWarner Losh 49198e3e3a7aSWarner Losh<p> 49208e3e3a7aSWarner LoshUserdata represent C values in Lua. 49218e3e3a7aSWarner LoshA <em>light userdata</em> represents a pointer, a <code>void*</code>. 49228e3e3a7aSWarner LoshIt is a value (like a number): 49238e3e3a7aSWarner Loshyou do not create it, it has no individual metatable, 49248e3e3a7aSWarner Loshand it is not collected (as it was never created). 49258e3e3a7aSWarner LoshA light userdata is equal to "any" 49268e3e3a7aSWarner Loshlight userdata with the same C address. 49278e3e3a7aSWarner Losh 49288e3e3a7aSWarner Losh 49298e3e3a7aSWarner Losh 49308e3e3a7aSWarner Losh 49318e3e3a7aSWarner Losh 49328e3e3a7aSWarner Losh<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> 49338e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 49348e3e3a7aSWarner Losh<pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre> 49358e3e3a7aSWarner Losh 49368e3e3a7aSWarner Losh<p> 49378e3e3a7aSWarner LoshThis macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>, 49388e3e3a7aSWarner Loshbut should be used only when <code>s</code> is a literal string. 49390495ed39SKyle Evans(Lua may optimize this case.) 49408e3e3a7aSWarner Losh 49418e3e3a7aSWarner Losh 49428e3e3a7aSWarner Losh 49438e3e3a7aSWarner Losh 49448e3e3a7aSWarner Losh 49458e3e3a7aSWarner Losh<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> 49468e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 49478e3e3a7aSWarner Losh<pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> 49488e3e3a7aSWarner Losh 49498e3e3a7aSWarner Losh<p> 49508e3e3a7aSWarner LoshPushes the string pointed to by <code>s</code> with size <code>len</code> 49518e3e3a7aSWarner Loshonto the stack. 49520495ed39SKyle EvansLua will make or reuse an internal copy of the given string, 49538e3e3a7aSWarner Loshso the memory at <code>s</code> can be freed or reused immediately after 49548e3e3a7aSWarner Loshthe function returns. 49558e3e3a7aSWarner LoshThe string can contain any binary data, 49568e3e3a7aSWarner Loshincluding embedded zeros. 49578e3e3a7aSWarner Losh 49588e3e3a7aSWarner Losh 49598e3e3a7aSWarner Losh<p> 49600495ed39SKyle EvansReturns a pointer to the internal copy of the string (see <a href="#4.1.3">§4.1.3</a>). 49618e3e3a7aSWarner Losh 49628e3e3a7aSWarner Losh 49638e3e3a7aSWarner Losh 49648e3e3a7aSWarner Losh 49658e3e3a7aSWarner Losh 49668e3e3a7aSWarner Losh<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> 49678e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 49688e3e3a7aSWarner Losh<pre>void lua_pushnil (lua_State *L);</pre> 49698e3e3a7aSWarner Losh 49708e3e3a7aSWarner Losh<p> 49718e3e3a7aSWarner LoshPushes a nil value onto the stack. 49728e3e3a7aSWarner Losh 49738e3e3a7aSWarner Losh 49748e3e3a7aSWarner Losh 49758e3e3a7aSWarner Losh 49768e3e3a7aSWarner Losh 49778e3e3a7aSWarner Losh<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> 49788e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 49798e3e3a7aSWarner Losh<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> 49808e3e3a7aSWarner Losh 49818e3e3a7aSWarner Losh<p> 49828e3e3a7aSWarner LoshPushes a float with value <code>n</code> onto the stack. 49838e3e3a7aSWarner Losh 49848e3e3a7aSWarner Losh 49858e3e3a7aSWarner Losh 49868e3e3a7aSWarner Losh 49878e3e3a7aSWarner Losh 49888e3e3a7aSWarner Losh<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> 49898e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 49908e3e3a7aSWarner Losh<pre>const char *lua_pushstring (lua_State *L, const char *s);</pre> 49918e3e3a7aSWarner Losh 49928e3e3a7aSWarner Losh<p> 49938e3e3a7aSWarner LoshPushes the zero-terminated string pointed to by <code>s</code> 49948e3e3a7aSWarner Loshonto the stack. 49950495ed39SKyle EvansLua will make or reuse an internal copy of the given string, 49968e3e3a7aSWarner Loshso the memory at <code>s</code> can be freed or reused immediately after 49978e3e3a7aSWarner Loshthe function returns. 49988e3e3a7aSWarner Losh 49998e3e3a7aSWarner Losh 50008e3e3a7aSWarner Losh<p> 50010495ed39SKyle EvansReturns a pointer to the internal copy of the string (see <a href="#4.1.3">§4.1.3</a>). 50028e3e3a7aSWarner Losh 50038e3e3a7aSWarner Losh 50048e3e3a7aSWarner Losh<p> 50058e3e3a7aSWarner LoshIf <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>. 50068e3e3a7aSWarner Losh 50078e3e3a7aSWarner Losh 50088e3e3a7aSWarner Losh 50098e3e3a7aSWarner Losh 50108e3e3a7aSWarner Losh 50118e3e3a7aSWarner Losh<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> 50128e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 50138e3e3a7aSWarner Losh<pre>int lua_pushthread (lua_State *L);</pre> 50148e3e3a7aSWarner Losh 50158e3e3a7aSWarner Losh<p> 50168e3e3a7aSWarner LoshPushes the thread represented by <code>L</code> onto the stack. 50178e3e3a7aSWarner LoshReturns 1 if this thread is the main thread of its state. 50188e3e3a7aSWarner Losh 50198e3e3a7aSWarner Losh 50208e3e3a7aSWarner Losh 50218e3e3a7aSWarner Losh 50228e3e3a7aSWarner Losh 50238e3e3a7aSWarner Losh<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> 50248e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 50258e3e3a7aSWarner Losh<pre>void lua_pushvalue (lua_State *L, int index);</pre> 50268e3e3a7aSWarner Losh 50278e3e3a7aSWarner Losh<p> 50288e3e3a7aSWarner LoshPushes a copy of the element at the given index 50298e3e3a7aSWarner Loshonto the stack. 50308e3e3a7aSWarner Losh 50318e3e3a7aSWarner Losh 50328e3e3a7aSWarner Losh 50338e3e3a7aSWarner Losh 50348e3e3a7aSWarner Losh 50358e3e3a7aSWarner Losh<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> 50360495ed39SKyle Evans<span class="apii">[-0, +1, <em>v</em>]</span> 50378e3e3a7aSWarner Losh<pre>const char *lua_pushvfstring (lua_State *L, 50388e3e3a7aSWarner Losh const char *fmt, 50398e3e3a7aSWarner Losh va_list argp);</pre> 50408e3e3a7aSWarner Losh 50418e3e3a7aSWarner Losh<p> 50428e3e3a7aSWarner LoshEquivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> 50438e3e3a7aSWarner Loshinstead of a variable number of arguments. 50448e3e3a7aSWarner Losh 50458e3e3a7aSWarner Losh 50468e3e3a7aSWarner Losh 50478e3e3a7aSWarner Losh 50488e3e3a7aSWarner Losh 50498e3e3a7aSWarner Losh<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> 50508e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 50518e3e3a7aSWarner Losh<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> 50528e3e3a7aSWarner Losh 50538e3e3a7aSWarner Losh<p> 50548e3e3a7aSWarner LoshReturns 1 if the two values in indices <code>index1</code> and 50558e3e3a7aSWarner Losh<code>index2</code> are primitively equal 50560495ed39SKyle Evans(that is, equal without calling the <code>__eq</code> metamethod). 50578e3e3a7aSWarner LoshOtherwise returns 0. 50588e3e3a7aSWarner LoshAlso returns 0 if any of the indices are not valid. 50598e3e3a7aSWarner Losh 50608e3e3a7aSWarner Losh 50618e3e3a7aSWarner Losh 50628e3e3a7aSWarner Losh 50638e3e3a7aSWarner Losh 50648e3e3a7aSWarner Losh<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> 50658e3e3a7aSWarner Losh<span class="apii">[-1, +1, –]</span> 50668e3e3a7aSWarner Losh<pre>int lua_rawget (lua_State *L, int index);</pre> 50678e3e3a7aSWarner Losh 50688e3e3a7aSWarner Losh<p> 50698e3e3a7aSWarner LoshSimilar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access 50708e3e3a7aSWarner Losh(i.e., without metamethods). 5071*a9490b81SWarner LoshThe value at <code>index</code> must be a table. 50728e3e3a7aSWarner Losh 50738e3e3a7aSWarner Losh 50748e3e3a7aSWarner Losh 50758e3e3a7aSWarner Losh 50768e3e3a7aSWarner Losh 50778e3e3a7aSWarner Losh<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> 50788e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 50798e3e3a7aSWarner Losh<pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre> 50808e3e3a7aSWarner Losh 50818e3e3a7aSWarner Losh<p> 50828e3e3a7aSWarner LoshPushes onto the stack the value <code>t[n]</code>, 50838e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index. 50848e3e3a7aSWarner LoshThe access is raw, 50850495ed39SKyle Evansthat is, it does not use the <code>__index</code> metavalue. 50868e3e3a7aSWarner Losh 50878e3e3a7aSWarner Losh 50888e3e3a7aSWarner Losh<p> 50898e3e3a7aSWarner LoshReturns the type of the pushed value. 50908e3e3a7aSWarner Losh 50918e3e3a7aSWarner Losh 50928e3e3a7aSWarner Losh 50938e3e3a7aSWarner Losh 50948e3e3a7aSWarner Losh 50958e3e3a7aSWarner Losh<hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p> 50968e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 50978e3e3a7aSWarner Losh<pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre> 50988e3e3a7aSWarner Losh 50998e3e3a7aSWarner Losh<p> 51008e3e3a7aSWarner LoshPushes onto the stack the value <code>t[k]</code>, 51018e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index and 51028e3e3a7aSWarner Losh<code>k</code> is the pointer <code>p</code> represented as a light userdata. 51038e3e3a7aSWarner LoshThe access is raw; 51040495ed39SKyle Evansthat is, it does not use the <code>__index</code> metavalue. 51058e3e3a7aSWarner Losh 51068e3e3a7aSWarner Losh 51078e3e3a7aSWarner Losh<p> 51088e3e3a7aSWarner LoshReturns the type of the pushed value. 51098e3e3a7aSWarner Losh 51108e3e3a7aSWarner Losh 51118e3e3a7aSWarner Losh 51128e3e3a7aSWarner Losh 51138e3e3a7aSWarner Losh 51148e3e3a7aSWarner Losh<hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p> 51158e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 51160495ed39SKyle Evans<pre>lua_Unsigned lua_rawlen (lua_State *L, int index);</pre> 51178e3e3a7aSWarner Losh 51188e3e3a7aSWarner Losh<p> 51198e3e3a7aSWarner LoshReturns the raw "length" of the value at the given index: 51208e3e3a7aSWarner Loshfor strings, this is the string length; 51218e3e3a7aSWarner Loshfor tables, this is the result of the length operator ('<code>#</code>') 51228e3e3a7aSWarner Loshwith no metamethods; 51238e3e3a7aSWarner Loshfor userdata, this is the size of the block of memory allocated 51240495ed39SKyle Evansfor the userdata. 51250495ed39SKyle EvansFor other values, this call returns 0. 51268e3e3a7aSWarner Losh 51278e3e3a7aSWarner Losh 51288e3e3a7aSWarner Losh 51298e3e3a7aSWarner Losh 51308e3e3a7aSWarner Losh 51318e3e3a7aSWarner Losh<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> 51328e3e3a7aSWarner Losh<span class="apii">[-2, +0, <em>m</em>]</span> 51338e3e3a7aSWarner Losh<pre>void lua_rawset (lua_State *L, int index);</pre> 51348e3e3a7aSWarner Losh 51358e3e3a7aSWarner Losh<p> 51368e3e3a7aSWarner LoshSimilar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment 51378e3e3a7aSWarner Losh(i.e., without metamethods). 5138*a9490b81SWarner LoshThe value at <code>index</code> must be a table. 51398e3e3a7aSWarner Losh 51408e3e3a7aSWarner Losh 51418e3e3a7aSWarner Losh 51428e3e3a7aSWarner Losh 51438e3e3a7aSWarner Losh 51448e3e3a7aSWarner Losh<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> 51458e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span> 51468e3e3a7aSWarner Losh<pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre> 51478e3e3a7aSWarner Losh 51488e3e3a7aSWarner Losh<p> 51498e3e3a7aSWarner LoshDoes the equivalent of <code>t[i] = v</code>, 51508e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index 51510495ed39SKyle Evansand <code>v</code> is the value on the top of the stack. 51528e3e3a7aSWarner Losh 51538e3e3a7aSWarner Losh 51548e3e3a7aSWarner Losh<p> 51558e3e3a7aSWarner LoshThis function pops the value from the stack. 51568e3e3a7aSWarner LoshThe assignment is raw, 51570495ed39SKyle Evansthat is, it does not use the <code>__newindex</code> metavalue. 51588e3e3a7aSWarner Losh 51598e3e3a7aSWarner Losh 51608e3e3a7aSWarner Losh 51618e3e3a7aSWarner Losh 51628e3e3a7aSWarner Losh 51638e3e3a7aSWarner Losh<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p> 51648e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span> 51658e3e3a7aSWarner Losh<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre> 51668e3e3a7aSWarner Losh 51678e3e3a7aSWarner Losh<p> 51688e3e3a7aSWarner LoshDoes the equivalent of <code>t[p] = v</code>, 51698e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index, 51708e3e3a7aSWarner Losh<code>p</code> is encoded as a light userdata, 51710495ed39SKyle Evansand <code>v</code> is the value on the top of the stack. 51728e3e3a7aSWarner Losh 51738e3e3a7aSWarner Losh 51748e3e3a7aSWarner Losh<p> 51758e3e3a7aSWarner LoshThis function pops the value from the stack. 51768e3e3a7aSWarner LoshThe assignment is raw, 51770495ed39SKyle Evansthat is, it does not use the <code>__newindex</code> metavalue. 51788e3e3a7aSWarner Losh 51798e3e3a7aSWarner Losh 51808e3e3a7aSWarner Losh 51818e3e3a7aSWarner Losh 51828e3e3a7aSWarner Losh 51838e3e3a7aSWarner Losh<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> 51848e3e3a7aSWarner Losh<pre>typedef const char * (*lua_Reader) (lua_State *L, 51858e3e3a7aSWarner Losh void *data, 51868e3e3a7aSWarner Losh size_t *size);</pre> 51878e3e3a7aSWarner Losh 51888e3e3a7aSWarner Losh<p> 51898e3e3a7aSWarner LoshThe reader function used by <a href="#lua_load"><code>lua_load</code></a>. 51900495ed39SKyle EvansEvery time <a href="#lua_load"><code>lua_load</code></a> needs another piece of the chunk, 51910495ed39SKyle Evansit calls the reader, 51928e3e3a7aSWarner Loshpassing along its <code>data</code> parameter. 51938e3e3a7aSWarner LoshThe reader must return a pointer to a block of memory 51948e3e3a7aSWarner Loshwith a new piece of the chunk 51958e3e3a7aSWarner Loshand set <code>size</code> to the block size. 51968e3e3a7aSWarner LoshThe block must exist until the reader function is called again. 51978e3e3a7aSWarner LoshTo signal the end of the chunk, 51988e3e3a7aSWarner Loshthe reader must return <code>NULL</code> or set <code>size</code> to zero. 51998e3e3a7aSWarner LoshThe reader function may return pieces of any size greater than zero. 52008e3e3a7aSWarner Losh 52018e3e3a7aSWarner Losh 52028e3e3a7aSWarner Losh 52038e3e3a7aSWarner Losh 52048e3e3a7aSWarner Losh 52058e3e3a7aSWarner Losh<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> 52068e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 52078e3e3a7aSWarner Losh<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre> 52088e3e3a7aSWarner Losh 52098e3e3a7aSWarner Losh<p> 52108e3e3a7aSWarner LoshSets the C function <code>f</code> as the new value of global <code>name</code>. 52118e3e3a7aSWarner LoshIt is defined as a macro: 52128e3e3a7aSWarner Losh 52138e3e3a7aSWarner Losh<pre> 52148e3e3a7aSWarner Losh #define lua_register(L,n,f) \ 52158e3e3a7aSWarner Losh (lua_pushcfunction(L, f), lua_setglobal(L, n)) 52168e3e3a7aSWarner Losh</pre> 52178e3e3a7aSWarner Losh 52188e3e3a7aSWarner Losh 52198e3e3a7aSWarner Losh 52208e3e3a7aSWarner Losh 52218e3e3a7aSWarner Losh<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> 52228e3e3a7aSWarner Losh<span class="apii">[-1, +0, –]</span> 52238e3e3a7aSWarner Losh<pre>void lua_remove (lua_State *L, int index);</pre> 52248e3e3a7aSWarner Losh 52258e3e3a7aSWarner Losh<p> 52268e3e3a7aSWarner LoshRemoves the element at the given valid index, 52278e3e3a7aSWarner Loshshifting down the elements above this index to fill the gap. 52288e3e3a7aSWarner LoshThis function cannot be called with a pseudo-index, 52298e3e3a7aSWarner Loshbecause a pseudo-index is not an actual stack position. 52308e3e3a7aSWarner Losh 52318e3e3a7aSWarner Losh 52328e3e3a7aSWarner Losh 52338e3e3a7aSWarner Losh 52348e3e3a7aSWarner Losh 52358e3e3a7aSWarner Losh<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> 52368e3e3a7aSWarner Losh<span class="apii">[-1, +0, –]</span> 52378e3e3a7aSWarner Losh<pre>void lua_replace (lua_State *L, int index);</pre> 52388e3e3a7aSWarner Losh 52398e3e3a7aSWarner Losh<p> 52408e3e3a7aSWarner LoshMoves the top element into the given valid index 52418e3e3a7aSWarner Loshwithout shifting any element 52428e3e3a7aSWarner Losh(therefore replacing the value at that given index), 52438e3e3a7aSWarner Loshand then pops the top element. 52448e3e3a7aSWarner Losh 52458e3e3a7aSWarner Losh 52468e3e3a7aSWarner Losh 52478e3e3a7aSWarner Losh 52488e3e3a7aSWarner Losh 52490495ed39SKyle Evans<hr><h3><a name="lua_resetthread"><code>lua_resetthread</code></a></h3><p> 52500495ed39SKyle Evans<span class="apii">[-0, +?, –]</span> 52510495ed39SKyle Evans<pre>int lua_resetthread (lua_State *L);</pre> 52520495ed39SKyle Evans 52530495ed39SKyle Evans<p> 5254*a9490b81SWarner LoshThis function is deprecated; 5255*a9490b81SWarner Loshit is equivalent to <a href="#lua_closethread"><code>lua_closethread</code></a> with 5256*a9490b81SWarner Losh<code>from</code> being <code>NULL</code>. 52570495ed39SKyle Evans 52580495ed39SKyle Evans 52590495ed39SKyle Evans 52600495ed39SKyle Evans 52610495ed39SKyle Evans 52628e3e3a7aSWarner Losh<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> 52638e3e3a7aSWarner Losh<span class="apii">[-?, +?, –]</span> 52640495ed39SKyle Evans<pre>int lua_resume (lua_State *L, lua_State *from, int nargs, 52650495ed39SKyle Evans int *nresults);</pre> 52668e3e3a7aSWarner Losh 52678e3e3a7aSWarner Losh<p> 52688e3e3a7aSWarner LoshStarts and resumes a coroutine in the given thread <code>L</code>. 52698e3e3a7aSWarner Losh 52708e3e3a7aSWarner Losh 52718e3e3a7aSWarner Losh<p> 52728e3e3a7aSWarner LoshTo start a coroutine, 52730495ed39SKyle Evansyou push the main function plus any arguments 52740495ed39SKyle Evansonto the empty stack of the thread. 52758e3e3a7aSWarner Loshthen you call <a href="#lua_resume"><code>lua_resume</code></a>, 52768e3e3a7aSWarner Loshwith <code>nargs</code> being the number of arguments. 52778e3e3a7aSWarner LoshThis call returns when the coroutine suspends or finishes its execution. 52780495ed39SKyle EvansWhen it returns, 52790495ed39SKyle Evans<code>*nresults</code> is updated and 52800495ed39SKyle Evansthe top of the stack contains 52810495ed39SKyle Evansthe <code>*nresults</code> values passed to <a href="#lua_yield"><code>lua_yield</code></a> 52820495ed39SKyle Evansor returned by the body function. 52838e3e3a7aSWarner Losh<a href="#lua_resume"><code>lua_resume</code></a> returns 52848e3e3a7aSWarner Losh<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, 52858e3e3a7aSWarner Losh<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution 52868e3e3a7aSWarner Loshwithout errors, 52870495ed39SKyle Evansor an error code in case of errors (see <a href="#4.4.1">§4.4.1</a>). 52888e3e3a7aSWarner LoshIn case of errors, 52890495ed39SKyle Evansthe error object is on the top of the stack. 52908e3e3a7aSWarner Losh 52918e3e3a7aSWarner Losh 52928e3e3a7aSWarner Losh<p> 52938e3e3a7aSWarner LoshTo resume a coroutine, 52940495ed39SKyle Evansyou remove the <code>*nresults</code> yielded values from its stack, 52950495ed39SKyle Evanspush the values to be passed as results from <code>yield</code>, 52968e3e3a7aSWarner Loshand then call <a href="#lua_resume"><code>lua_resume</code></a>. 52978e3e3a7aSWarner Losh 52988e3e3a7aSWarner Losh 52998e3e3a7aSWarner Losh<p> 53008e3e3a7aSWarner LoshThe parameter <code>from</code> represents the coroutine that is resuming <code>L</code>. 53018e3e3a7aSWarner LoshIf there is no such coroutine, 53028e3e3a7aSWarner Loshthis parameter can be <code>NULL</code>. 53038e3e3a7aSWarner Losh 53048e3e3a7aSWarner Losh 53058e3e3a7aSWarner Losh 53068e3e3a7aSWarner Losh 53078e3e3a7aSWarner Losh 53088e3e3a7aSWarner Losh<hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p> 53098e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 53108e3e3a7aSWarner Losh<pre>void lua_rotate (lua_State *L, int idx, int n);</pre> 53118e3e3a7aSWarner Losh 53128e3e3a7aSWarner Losh<p> 53138e3e3a7aSWarner LoshRotates the stack elements between the valid index <code>idx</code> 53148e3e3a7aSWarner Loshand the top of the stack. 53158e3e3a7aSWarner LoshThe elements are rotated <code>n</code> positions in the direction of the top, 53168e3e3a7aSWarner Loshfor a positive <code>n</code>, 53178e3e3a7aSWarner Loshor <code>-n</code> positions in the direction of the bottom, 53188e3e3a7aSWarner Loshfor a negative <code>n</code>. 53198e3e3a7aSWarner LoshThe absolute value of <code>n</code> must not be greater than the size 53208e3e3a7aSWarner Loshof the slice being rotated. 53218e3e3a7aSWarner LoshThis function cannot be called with a pseudo-index, 53228e3e3a7aSWarner Loshbecause a pseudo-index is not an actual stack position. 53238e3e3a7aSWarner Losh 53248e3e3a7aSWarner Losh 53258e3e3a7aSWarner Losh 53268e3e3a7aSWarner Losh 53278e3e3a7aSWarner Losh 53288e3e3a7aSWarner Losh<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> 53298e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 53308e3e3a7aSWarner Losh<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> 53318e3e3a7aSWarner Losh 53328e3e3a7aSWarner Losh<p> 53338e3e3a7aSWarner LoshChanges the allocator function of a given state to <code>f</code> 53348e3e3a7aSWarner Loshwith user data <code>ud</code>. 53358e3e3a7aSWarner Losh 53368e3e3a7aSWarner Losh 53378e3e3a7aSWarner Losh 53388e3e3a7aSWarner Losh 53398e3e3a7aSWarner Losh 53408e3e3a7aSWarner Losh<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> 53418e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>e</em>]</span> 53428e3e3a7aSWarner Losh<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> 53438e3e3a7aSWarner Losh 53448e3e3a7aSWarner Losh<p> 53458e3e3a7aSWarner LoshDoes the equivalent to <code>t[k] = v</code>, 53468e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index 53470495ed39SKyle Evansand <code>v</code> is the value on the top of the stack. 53488e3e3a7aSWarner Losh 53498e3e3a7aSWarner Losh 53508e3e3a7aSWarner Losh<p> 53518e3e3a7aSWarner LoshThis function pops the value from the stack. 53528e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 53538e3e3a7aSWarner Loshfor the "newindex" event (see <a href="#2.4">§2.4</a>). 53548e3e3a7aSWarner Losh 53558e3e3a7aSWarner Losh 53568e3e3a7aSWarner Losh 53578e3e3a7aSWarner Losh 53588e3e3a7aSWarner Losh 53598e3e3a7aSWarner Losh<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> 53608e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>e</em>]</span> 53618e3e3a7aSWarner Losh<pre>void lua_setglobal (lua_State *L, const char *name);</pre> 53628e3e3a7aSWarner Losh 53638e3e3a7aSWarner Losh<p> 53648e3e3a7aSWarner LoshPops a value from the stack and 53658e3e3a7aSWarner Loshsets it as the new value of global <code>name</code>. 53668e3e3a7aSWarner Losh 53678e3e3a7aSWarner Losh 53688e3e3a7aSWarner Losh 53698e3e3a7aSWarner Losh 53708e3e3a7aSWarner Losh 53718e3e3a7aSWarner Losh<hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p> 53728e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>e</em>]</span> 53738e3e3a7aSWarner Losh<pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre> 53748e3e3a7aSWarner Losh 53758e3e3a7aSWarner Losh<p> 53768e3e3a7aSWarner LoshDoes the equivalent to <code>t[n] = v</code>, 53778e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index 53780495ed39SKyle Evansand <code>v</code> is the value on the top of the stack. 53798e3e3a7aSWarner Losh 53808e3e3a7aSWarner Losh 53818e3e3a7aSWarner Losh<p> 53828e3e3a7aSWarner LoshThis function pops the value from the stack. 53838e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 53848e3e3a7aSWarner Loshfor the "newindex" event (see <a href="#2.4">§2.4</a>). 53858e3e3a7aSWarner Losh 53868e3e3a7aSWarner Losh 53878e3e3a7aSWarner Losh 53888e3e3a7aSWarner Losh 53898e3e3a7aSWarner Losh 53900495ed39SKyle Evans<hr><h3><a name="lua_setiuservalue"><code>lua_setiuservalue</code></a></h3><p> 53918e3e3a7aSWarner Losh<span class="apii">[-1, +0, –]</span> 53920495ed39SKyle Evans<pre>int lua_setiuservalue (lua_State *L, int index, int n);</pre> 53938e3e3a7aSWarner Losh 53948e3e3a7aSWarner Losh<p> 53950495ed39SKyle EvansPops a value from the stack and sets it as 53960495ed39SKyle Evansthe new <code>n</code>-th user value associated to the 53970495ed39SKyle Evansfull userdata at the given index. 53980495ed39SKyle EvansReturns 0 if the userdata does not have that value. 53990495ed39SKyle Evans 54000495ed39SKyle Evans 54010495ed39SKyle Evans 54020495ed39SKyle Evans 54030495ed39SKyle Evans 54040495ed39SKyle Evans<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> 54050495ed39SKyle Evans<span class="apii">[-1, +0, –]</span> 54060495ed39SKyle Evans<pre>int lua_setmetatable (lua_State *L, int index);</pre> 54070495ed39SKyle Evans 54080495ed39SKyle Evans<p> 54090495ed39SKyle EvansPops a table or <b>nil</b> from the stack and 54100495ed39SKyle Evanssets that value as the new metatable for the value at the given index. 54110495ed39SKyle Evans(<b>nil</b> means no metatable.) 54120495ed39SKyle Evans 54130495ed39SKyle Evans 54140495ed39SKyle Evans<p> 54150495ed39SKyle Evans(For historical reasons, this function returns an <code>int</code>, 54160495ed39SKyle Evanswhich now is always 1.) 54178e3e3a7aSWarner Losh 54188e3e3a7aSWarner Losh 54198e3e3a7aSWarner Losh 54208e3e3a7aSWarner Losh 54218e3e3a7aSWarner Losh 54228e3e3a7aSWarner Losh<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> 54238e3e3a7aSWarner Losh<span class="apii">[-2, +0, <em>e</em>]</span> 54248e3e3a7aSWarner Losh<pre>void lua_settable (lua_State *L, int index);</pre> 54258e3e3a7aSWarner Losh 54268e3e3a7aSWarner Losh<p> 54278e3e3a7aSWarner LoshDoes the equivalent to <code>t[k] = v</code>, 54288e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index, 54290495ed39SKyle Evans<code>v</code> is the value on the top of the stack, 54308e3e3a7aSWarner Loshand <code>k</code> is the value just below the top. 54318e3e3a7aSWarner Losh 54328e3e3a7aSWarner Losh 54338e3e3a7aSWarner Losh<p> 54348e3e3a7aSWarner LoshThis function pops both the key and the value from the stack. 54358e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 54368e3e3a7aSWarner Loshfor the "newindex" event (see <a href="#2.4">§2.4</a>). 54378e3e3a7aSWarner Losh 54388e3e3a7aSWarner Losh 54398e3e3a7aSWarner Losh 54408e3e3a7aSWarner Losh 54418e3e3a7aSWarner Losh 54428e3e3a7aSWarner Losh<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> 54430495ed39SKyle Evans<span class="apii">[-?, +?, <em>e</em>]</span> 54448e3e3a7aSWarner Losh<pre>void lua_settop (lua_State *L, int index);</pre> 54458e3e3a7aSWarner Losh 54468e3e3a7aSWarner Losh<p> 54478e3e3a7aSWarner LoshAccepts any index, or 0, 54488e3e3a7aSWarner Loshand sets the stack top to this index. 54490495ed39SKyle EvansIf the new top is greater than the old one, 54508e3e3a7aSWarner Loshthen the new elements are filled with <b>nil</b>. 54518e3e3a7aSWarner LoshIf <code>index</code> is 0, then all stack elements are removed. 54528e3e3a7aSWarner Losh 54538e3e3a7aSWarner Losh 54540495ed39SKyle Evans<p> 54550495ed39SKyle EvansThis function can run arbitrary code when removing an index 54560495ed39SKyle Evansmarked as to-be-closed from the stack. 54578e3e3a7aSWarner Losh 54588e3e3a7aSWarner Losh 54598e3e3a7aSWarner Losh 54600495ed39SKyle Evans 54610495ed39SKyle Evans 54620495ed39SKyle Evans<hr><h3><a name="lua_setwarnf"><code>lua_setwarnf</code></a></h3><p> 54630495ed39SKyle Evans<span class="apii">[-0, +0, –]</span> 54640495ed39SKyle Evans<pre>void lua_setwarnf (lua_State *L, lua_WarnFunction f, void *ud);</pre> 54658e3e3a7aSWarner Losh 54668e3e3a7aSWarner Losh<p> 54670495ed39SKyle EvansSets the warning function to be used by Lua to emit warnings 54680495ed39SKyle Evans(see <a href="#lua_WarnFunction"><code>lua_WarnFunction</code></a>). 54690495ed39SKyle EvansThe <code>ud</code> parameter sets the value <code>ud</code> passed to 54700495ed39SKyle Evansthe warning function. 54718e3e3a7aSWarner Losh 54728e3e3a7aSWarner Losh 54738e3e3a7aSWarner Losh 54748e3e3a7aSWarner Losh 54758e3e3a7aSWarner Losh 54768e3e3a7aSWarner Losh<hr><h3><a name="lua_State"><code>lua_State</code></a></h3> 54778e3e3a7aSWarner Losh<pre>typedef struct lua_State lua_State;</pre> 54788e3e3a7aSWarner Losh 54798e3e3a7aSWarner Losh<p> 54808e3e3a7aSWarner LoshAn opaque structure that points to a thread and indirectly 54818e3e3a7aSWarner Losh(through the thread) to the whole state of a Lua interpreter. 54828e3e3a7aSWarner LoshThe Lua library is fully reentrant: 54838e3e3a7aSWarner Loshit has no global variables. 54848e3e3a7aSWarner LoshAll information about a state is accessible through this structure. 54858e3e3a7aSWarner Losh 54868e3e3a7aSWarner Losh 54878e3e3a7aSWarner Losh<p> 54888e3e3a7aSWarner LoshA pointer to this structure must be passed as the first argument to 54898e3e3a7aSWarner Loshevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 54908e3e3a7aSWarner Loshwhich creates a Lua state from scratch. 54918e3e3a7aSWarner Losh 54928e3e3a7aSWarner Losh 54938e3e3a7aSWarner Losh 54948e3e3a7aSWarner Losh 54958e3e3a7aSWarner Losh 54968e3e3a7aSWarner Losh<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> 54978e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 54988e3e3a7aSWarner Losh<pre>int lua_status (lua_State *L);</pre> 54998e3e3a7aSWarner Losh 55008e3e3a7aSWarner Losh<p> 55018e3e3a7aSWarner LoshReturns the status of the thread <code>L</code>. 55028e3e3a7aSWarner Losh 55038e3e3a7aSWarner Losh 55048e3e3a7aSWarner Losh<p> 55050495ed39SKyle EvansThe status can be <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for a normal thread, 55068e3e3a7aSWarner Loshan error code if the thread finished the execution 55078e3e3a7aSWarner Loshof a <a href="#lua_resume"><code>lua_resume</code></a> with an error, 55080495ed39SKyle Evansor <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. 55098e3e3a7aSWarner Losh 55108e3e3a7aSWarner Losh 55118e3e3a7aSWarner Losh<p> 55120495ed39SKyle EvansYou can call functions only in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>. 55138e3e3a7aSWarner LoshYou can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> 55148e3e3a7aSWarner Losh(to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> 55158e3e3a7aSWarner Losh(to resume a coroutine). 55168e3e3a7aSWarner Losh 55178e3e3a7aSWarner Losh 55188e3e3a7aSWarner Losh 55198e3e3a7aSWarner Losh 55208e3e3a7aSWarner Losh 55218e3e3a7aSWarner Losh<hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p> 55228e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 55238e3e3a7aSWarner Losh<pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre> 55248e3e3a7aSWarner Losh 55258e3e3a7aSWarner Losh<p> 55268e3e3a7aSWarner LoshConverts the zero-terminated string <code>s</code> to a number, 55278e3e3a7aSWarner Loshpushes that number into the stack, 55288e3e3a7aSWarner Loshand returns the total size of the string, 55298e3e3a7aSWarner Loshthat is, its length plus one. 55308e3e3a7aSWarner LoshThe conversion can result in an integer or a float, 55318e3e3a7aSWarner Loshaccording to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 55320495ed39SKyle EvansThe string may have leading and trailing whitespaces and a sign. 55338e3e3a7aSWarner LoshIf the string is not a valid numeral, 55348e3e3a7aSWarner Loshreturns 0 and pushes nothing. 55358e3e3a7aSWarner Losh(Note that the result can be used as a boolean, 55368e3e3a7aSWarner Loshtrue if the conversion succeeds.) 55378e3e3a7aSWarner Losh 55388e3e3a7aSWarner Losh 55398e3e3a7aSWarner Losh 55408e3e3a7aSWarner Losh 55418e3e3a7aSWarner Losh 55428e3e3a7aSWarner Losh<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> 55438e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 55448e3e3a7aSWarner Losh<pre>int lua_toboolean (lua_State *L, int index);</pre> 55458e3e3a7aSWarner Losh 55468e3e3a7aSWarner Losh<p> 55478e3e3a7aSWarner LoshConverts the Lua value at the given index to a C boolean 55488e3e3a7aSWarner Loshvalue (0 or 1). 55498e3e3a7aSWarner LoshLike all tests in Lua, 55508e3e3a7aSWarner Losh<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value 55518e3e3a7aSWarner Loshdifferent from <b>false</b> and <b>nil</b>; 55528e3e3a7aSWarner Loshotherwise it returns false. 55538e3e3a7aSWarner Losh(If you want to accept only actual boolean values, 55548e3e3a7aSWarner Loshuse <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) 55558e3e3a7aSWarner Losh 55568e3e3a7aSWarner Losh 55578e3e3a7aSWarner Losh 55588e3e3a7aSWarner Losh 55598e3e3a7aSWarner Losh 55608e3e3a7aSWarner Losh<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> 55618e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 55628e3e3a7aSWarner Losh<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> 55638e3e3a7aSWarner Losh 55648e3e3a7aSWarner Losh<p> 55658e3e3a7aSWarner LoshConverts a value at the given index to a C function. 55668e3e3a7aSWarner LoshThat value must be a C function; 55678e3e3a7aSWarner Loshotherwise, returns <code>NULL</code>. 55688e3e3a7aSWarner Losh 55698e3e3a7aSWarner Losh 55708e3e3a7aSWarner Losh 55718e3e3a7aSWarner Losh 55728e3e3a7aSWarner Losh 55730495ed39SKyle Evans<hr><h3><a name="lua_toclose"><code>lua_toclose</code></a></h3><p> 55740495ed39SKyle Evans<span class="apii">[-0, +0, <em>m</em>]</span> 55750495ed39SKyle Evans<pre>void lua_toclose (lua_State *L, int index);</pre> 55760495ed39SKyle Evans 55770495ed39SKyle Evans<p> 55780495ed39SKyle EvansMarks the given index in the stack as a 55798c784bb8SWarner Loshto-be-closed slot (see <a href="#3.3.8">§3.3.8</a>). 55800495ed39SKyle EvansLike a to-be-closed variable in Lua, 55818c784bb8SWarner Loshthe value at that slot in the stack will be closed 55820495ed39SKyle Evanswhen it goes out of scope. 55830495ed39SKyle EvansHere, in the context of a C function, 55840495ed39SKyle Evansto go out of scope means that the running function returns to Lua, 55858c784bb8SWarner Loshor there is an error, 55868c784bb8SWarner Loshor the slot is removed from the stack through 55878c784bb8SWarner Losh<a href="#lua_settop"><code>lua_settop</code></a> or <a href="#lua_pop"><code>lua_pop</code></a>, 55888c784bb8SWarner Loshor there is a call to <a href="#lua_closeslot"><code>lua_closeslot</code></a>. 55898c784bb8SWarner LoshA slot marked as to-be-closed should not be removed from the stack 55908c784bb8SWarner Loshby any other function in the API except <a href="#lua_settop"><code>lua_settop</code></a> or <a href="#lua_pop"><code>lua_pop</code></a>, 55918c784bb8SWarner Loshunless previously deactivated by <a href="#lua_closeslot"><code>lua_closeslot</code></a>. 55920495ed39SKyle Evans 55930495ed39SKyle Evans 55940495ed39SKyle Evans<p> 55950495ed39SKyle EvansThis function should not be called for an index 55968c784bb8SWarner Loshthat is equal to or below an active to-be-closed slot. 55970495ed39SKyle Evans 55980495ed39SKyle Evans 55990495ed39SKyle Evans<p> 56000495ed39SKyle EvansNote that, both in case of errors and of a regular return, 56010495ed39SKyle Evansby the time the <code>__close</code> metamethod runs, 56020495ed39SKyle Evansthe C stack was already unwound, 56030495ed39SKyle Evansso that any automatic C variable declared in the calling function 56048c784bb8SWarner Losh(e.g., a buffer) will be out of scope. 56050495ed39SKyle Evans 56060495ed39SKyle Evans 56070495ed39SKyle Evans 56080495ed39SKyle Evans 56090495ed39SKyle Evans 56108e3e3a7aSWarner Losh<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> 56118e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 56128e3e3a7aSWarner Losh<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> 56138e3e3a7aSWarner Losh 56148e3e3a7aSWarner Losh<p> 56158e3e3a7aSWarner LoshEquivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 56168e3e3a7aSWarner Losh 56178e3e3a7aSWarner Losh 56188e3e3a7aSWarner Losh 56198e3e3a7aSWarner Losh 56208e3e3a7aSWarner Losh 56218e3e3a7aSWarner Losh<hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p> 56228e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 56238e3e3a7aSWarner Losh<pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre> 56248e3e3a7aSWarner Losh 56258e3e3a7aSWarner Losh<p> 56268e3e3a7aSWarner LoshConverts the Lua value at the given index 56278e3e3a7aSWarner Loshto the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. 56288e3e3a7aSWarner LoshThe Lua value must be an integer, 56298e3e3a7aSWarner Loshor a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>); 56308e3e3a7aSWarner Loshotherwise, <code>lua_tointegerx</code> returns 0. 56318e3e3a7aSWarner Losh 56328e3e3a7aSWarner Losh 56338e3e3a7aSWarner Losh<p> 56348e3e3a7aSWarner LoshIf <code>isnum</code> is not <code>NULL</code>, 56358e3e3a7aSWarner Loshits referent is assigned a boolean value that 56368e3e3a7aSWarner Loshindicates whether the operation succeeded. 56378e3e3a7aSWarner Losh 56388e3e3a7aSWarner Losh 56398e3e3a7aSWarner Losh 56408e3e3a7aSWarner Losh 56418e3e3a7aSWarner Losh 56428e3e3a7aSWarner Losh<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> 56438e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span> 56448e3e3a7aSWarner Losh<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> 56458e3e3a7aSWarner Losh 56468e3e3a7aSWarner Losh<p> 56478e3e3a7aSWarner LoshConverts the Lua value at the given index to a C string. 56488e3e3a7aSWarner LoshIf <code>len</code> is not <code>NULL</code>, 56498e3e3a7aSWarner Loshit sets <code>*len</code> with the string length. 56508e3e3a7aSWarner LoshThe Lua value must be a string or a number; 56518e3e3a7aSWarner Loshotherwise, the function returns <code>NULL</code>. 56528e3e3a7aSWarner LoshIf the value is a number, 56538e3e3a7aSWarner Loshthen <code>lua_tolstring</code> also 56548e3e3a7aSWarner Losh<em>changes the actual value in the stack to a string</em>. 56558e3e3a7aSWarner Losh(This change confuses <a href="#lua_next"><code>lua_next</code></a> 56568e3e3a7aSWarner Loshwhen <code>lua_tolstring</code> is applied to keys during a table traversal.) 56578e3e3a7aSWarner Losh 56588e3e3a7aSWarner Losh 56598e3e3a7aSWarner Losh<p> 56608e3e3a7aSWarner Losh<code>lua_tolstring</code> returns a pointer 56610495ed39SKyle Evansto a string inside the Lua state (see <a href="#4.1.3">§4.1.3</a>). 56628e3e3a7aSWarner LoshThis string always has a zero ('<code>\0</code>') 56638e3e3a7aSWarner Loshafter its last character (as in C), 56648e3e3a7aSWarner Loshbut can contain other zeros in its body. 56658e3e3a7aSWarner Losh 56668e3e3a7aSWarner Losh 56678e3e3a7aSWarner Losh 56688e3e3a7aSWarner Losh 56698e3e3a7aSWarner Losh 56708e3e3a7aSWarner Losh<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> 56718e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 56728e3e3a7aSWarner Losh<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> 56738e3e3a7aSWarner Losh 56748e3e3a7aSWarner Losh<p> 56758e3e3a7aSWarner LoshEquivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 56768e3e3a7aSWarner Losh 56778e3e3a7aSWarner Losh 56788e3e3a7aSWarner Losh 56798e3e3a7aSWarner Losh 56808e3e3a7aSWarner Losh 56818e3e3a7aSWarner Losh<hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p> 56828e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 56838e3e3a7aSWarner Losh<pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre> 56848e3e3a7aSWarner Losh 56858e3e3a7aSWarner Losh<p> 56868e3e3a7aSWarner LoshConverts the Lua value at the given index 56878e3e3a7aSWarner Loshto the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). 56888e3e3a7aSWarner LoshThe Lua value must be a number or a string convertible to a number 56898e3e3a7aSWarner Losh(see <a href="#3.4.3">§3.4.3</a>); 56908e3e3a7aSWarner Loshotherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0. 56918e3e3a7aSWarner Losh 56928e3e3a7aSWarner Losh 56938e3e3a7aSWarner Losh<p> 56948e3e3a7aSWarner LoshIf <code>isnum</code> is not <code>NULL</code>, 56958e3e3a7aSWarner Loshits referent is assigned a boolean value that 56968e3e3a7aSWarner Loshindicates whether the operation succeeded. 56978e3e3a7aSWarner Losh 56988e3e3a7aSWarner Losh 56998e3e3a7aSWarner Losh 57008e3e3a7aSWarner Losh 57018e3e3a7aSWarner Losh 57028e3e3a7aSWarner Losh<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> 57038e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 57048e3e3a7aSWarner Losh<pre>const void *lua_topointer (lua_State *L, int index);</pre> 57058e3e3a7aSWarner Losh 57068e3e3a7aSWarner Losh<p> 57078e3e3a7aSWarner LoshConverts the value at the given index to a generic 57088e3e3a7aSWarner LoshC pointer (<code>void*</code>). 57090495ed39SKyle EvansThe value can be a userdata, a table, a thread, a string, or a function; 57108e3e3a7aSWarner Loshotherwise, <code>lua_topointer</code> returns <code>NULL</code>. 57118e3e3a7aSWarner LoshDifferent objects will give different pointers. 57128e3e3a7aSWarner LoshThere is no way to convert the pointer back to its original value. 57138e3e3a7aSWarner Losh 57148e3e3a7aSWarner Losh 57158e3e3a7aSWarner Losh<p> 57168e3e3a7aSWarner LoshTypically this function is used only for hashing and debug information. 57178e3e3a7aSWarner Losh 57188e3e3a7aSWarner Losh 57198e3e3a7aSWarner Losh 57208e3e3a7aSWarner Losh 57218e3e3a7aSWarner Losh 57228e3e3a7aSWarner Losh<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> 57238e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span> 57248e3e3a7aSWarner Losh<pre>const char *lua_tostring (lua_State *L, int index);</pre> 57258e3e3a7aSWarner Losh 57268e3e3a7aSWarner Losh<p> 57278e3e3a7aSWarner LoshEquivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. 57288e3e3a7aSWarner Losh 57298e3e3a7aSWarner Losh 57308e3e3a7aSWarner Losh 57318e3e3a7aSWarner Losh 57328e3e3a7aSWarner Losh 57338e3e3a7aSWarner Losh<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> 57348e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 57358e3e3a7aSWarner Losh<pre>lua_State *lua_tothread (lua_State *L, int index);</pre> 57368e3e3a7aSWarner Losh 57378e3e3a7aSWarner Losh<p> 57388e3e3a7aSWarner LoshConverts the value at the given index to a Lua thread 57398e3e3a7aSWarner Losh(represented as <code>lua_State*</code>). 57408e3e3a7aSWarner LoshThis value must be a thread; 57418e3e3a7aSWarner Loshotherwise, the function returns <code>NULL</code>. 57428e3e3a7aSWarner Losh 57438e3e3a7aSWarner Losh 57448e3e3a7aSWarner Losh 57458e3e3a7aSWarner Losh 57468e3e3a7aSWarner Losh 57478e3e3a7aSWarner Losh<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> 57488e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 57498e3e3a7aSWarner Losh<pre>void *lua_touserdata (lua_State *L, int index);</pre> 57508e3e3a7aSWarner Losh 57518e3e3a7aSWarner Losh<p> 57528e3e3a7aSWarner LoshIf the value at the given index is a full userdata, 57530495ed39SKyle Evansreturns its memory-block address. 57548e3e3a7aSWarner LoshIf the value is a light userdata, 57550495ed39SKyle Evansreturns its value (a pointer). 57568e3e3a7aSWarner LoshOtherwise, returns <code>NULL</code>. 57578e3e3a7aSWarner Losh 57588e3e3a7aSWarner Losh 57598e3e3a7aSWarner Losh 57608e3e3a7aSWarner Losh 57618e3e3a7aSWarner Losh 57628e3e3a7aSWarner Losh<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> 57638e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 57648e3e3a7aSWarner Losh<pre>int lua_type (lua_State *L, int index);</pre> 57658e3e3a7aSWarner Losh 57668e3e3a7aSWarner Losh<p> 57678e3e3a7aSWarner LoshReturns the type of the value in the given valid index, 57680495ed39SKyle Evansor <code>LUA_TNONE</code> for a non-valid but acceptable index. 57698e3e3a7aSWarner LoshThe types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants 57708e3e3a7aSWarner Loshdefined in <code>lua.h</code>: 57710495ed39SKyle Evans<a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a>, 57728e3e3a7aSWarner Losh<a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>, 57738e3e3a7aSWarner Losh<a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>, 57748e3e3a7aSWarner Losh<a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, 57758e3e3a7aSWarner Losh<a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, 57768e3e3a7aSWarner Losh<a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, 57778e3e3a7aSWarner Losh<a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, 57788e3e3a7aSWarner Losh<a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>, 57798e3e3a7aSWarner Loshand 57808e3e3a7aSWarner Losh<a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>. 57818e3e3a7aSWarner Losh 57828e3e3a7aSWarner Losh 57838e3e3a7aSWarner Losh 57848e3e3a7aSWarner Losh 57858e3e3a7aSWarner Losh 57868e3e3a7aSWarner Losh<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> 57878e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 57888e3e3a7aSWarner Losh<pre>const char *lua_typename (lua_State *L, int tp);</pre> 57898e3e3a7aSWarner Losh 57908e3e3a7aSWarner Losh<p> 57918e3e3a7aSWarner LoshReturns the name of the type encoded by the value <code>tp</code>, 57928e3e3a7aSWarner Loshwhich must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. 57938e3e3a7aSWarner Losh 57948e3e3a7aSWarner Losh 57958e3e3a7aSWarner Losh 57968e3e3a7aSWarner Losh 57978e3e3a7aSWarner Losh 57988e3e3a7aSWarner Losh<hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3> 57998e3e3a7aSWarner Losh<pre>typedef ... lua_Unsigned;</pre> 58008e3e3a7aSWarner Losh 58018e3e3a7aSWarner Losh<p> 58028e3e3a7aSWarner LoshThe unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>. 58038e3e3a7aSWarner Losh 58048e3e3a7aSWarner Losh 58058e3e3a7aSWarner Losh 58068e3e3a7aSWarner Losh 58078e3e3a7aSWarner Losh 58088e3e3a7aSWarner Losh<hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p> 58098e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 58108e3e3a7aSWarner Losh<pre>int lua_upvalueindex (int i);</pre> 58118e3e3a7aSWarner Losh 58128e3e3a7aSWarner Losh<p> 58138e3e3a7aSWarner LoshReturns the pseudo-index that represents the <code>i</code>-th upvalue of 58140495ed39SKyle Evansthe running function (see <a href="#4.2">§4.2</a>). 58150495ed39SKyle Evans<code>i</code> must be in the range <em>[1,256]</em>. 58168e3e3a7aSWarner Losh 58178e3e3a7aSWarner Losh 58188e3e3a7aSWarner Losh 58198e3e3a7aSWarner Losh 58208e3e3a7aSWarner Losh 58218e3e3a7aSWarner Losh<hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p> 58228e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 58230495ed39SKyle Evans<pre>lua_Number lua_version (lua_State *L);</pre> 58248e3e3a7aSWarner Losh 58258e3e3a7aSWarner Losh<p> 58260495ed39SKyle EvansReturns the version number of this core. 58270495ed39SKyle Evans 58280495ed39SKyle Evans 58290495ed39SKyle Evans 58300495ed39SKyle Evans 58310495ed39SKyle Evans 58320495ed39SKyle Evans<hr><h3><a name="lua_WarnFunction"><code>lua_WarnFunction</code></a></h3> 58330495ed39SKyle Evans<pre>typedef void (*lua_WarnFunction) (void *ud, const char *msg, int tocont);</pre> 58340495ed39SKyle Evans 58350495ed39SKyle Evans<p> 58360495ed39SKyle EvansThe type of warning functions, called by Lua to emit warnings. 58370495ed39SKyle EvansThe first parameter is an opaque pointer 58380495ed39SKyle Evansset by <a href="#lua_setwarnf"><code>lua_setwarnf</code></a>. 58390495ed39SKyle EvansThe second parameter is the warning message. 58400495ed39SKyle EvansThe third parameter is a boolean that 58410495ed39SKyle Evansindicates whether the message is 58420495ed39SKyle Evansto be continued by the message in the next call. 58430495ed39SKyle Evans 58440495ed39SKyle Evans 58450495ed39SKyle Evans<p> 58460495ed39SKyle EvansSee <a href="#pdf-warn"><code>warn</code></a> for more details about warnings. 58470495ed39SKyle Evans 58480495ed39SKyle Evans 58490495ed39SKyle Evans 58500495ed39SKyle Evans 58510495ed39SKyle Evans 58520495ed39SKyle Evans<hr><h3><a name="lua_warning"><code>lua_warning</code></a></h3><p> 58530495ed39SKyle Evans<span class="apii">[-0, +0, –]</span> 58540495ed39SKyle Evans<pre>void lua_warning (lua_State *L, const char *msg, int tocont);</pre> 58550495ed39SKyle Evans 58560495ed39SKyle Evans<p> 58570495ed39SKyle EvansEmits a warning with the given message. 58580495ed39SKyle EvansA message in a call with <code>tocont</code> true should be 58590495ed39SKyle Evanscontinued in another call to this function. 58600495ed39SKyle Evans 58610495ed39SKyle Evans 58620495ed39SKyle Evans<p> 58630495ed39SKyle EvansSee <a href="#pdf-warn"><code>warn</code></a> for more details about warnings. 58648e3e3a7aSWarner Losh 58658e3e3a7aSWarner Losh 58668e3e3a7aSWarner Losh 58678e3e3a7aSWarner Losh 58688e3e3a7aSWarner Losh 58698e3e3a7aSWarner Losh<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> 58708e3e3a7aSWarner Losh<pre>typedef int (*lua_Writer) (lua_State *L, 58718e3e3a7aSWarner Losh const void* p, 58728e3e3a7aSWarner Losh size_t sz, 58738e3e3a7aSWarner Losh void* ud);</pre> 58748e3e3a7aSWarner Losh 58758e3e3a7aSWarner Losh<p> 58768e3e3a7aSWarner LoshThe type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. 58770495ed39SKyle EvansEvery time <a href="#lua_dump"><code>lua_dump</code></a> produces another piece of chunk, 58780495ed39SKyle Evansit calls the writer, 58798e3e3a7aSWarner Loshpassing along the buffer to be written (<code>p</code>), 58808e3e3a7aSWarner Loshits size (<code>sz</code>), 58810495ed39SKyle Evansand the <code>ud</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. 58828e3e3a7aSWarner Losh 58838e3e3a7aSWarner Losh 58848e3e3a7aSWarner Losh<p> 58858e3e3a7aSWarner LoshThe writer returns an error code: 58868e3e3a7aSWarner Losh0 means no errors; 58878e3e3a7aSWarner Loshany other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from 58888e3e3a7aSWarner Loshcalling the writer again. 58898e3e3a7aSWarner Losh 58908e3e3a7aSWarner Losh 58918e3e3a7aSWarner Losh 58928e3e3a7aSWarner Losh 58938e3e3a7aSWarner Losh 58948e3e3a7aSWarner Losh<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> 58958e3e3a7aSWarner Losh<span class="apii">[-?, +?, –]</span> 58968e3e3a7aSWarner Losh<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> 58978e3e3a7aSWarner Losh 58988e3e3a7aSWarner Losh<p> 58998e3e3a7aSWarner LoshExchange values between different threads of the same state. 59008e3e3a7aSWarner Losh 59018e3e3a7aSWarner Losh 59028e3e3a7aSWarner Losh<p> 59038e3e3a7aSWarner LoshThis function pops <code>n</code> values from the stack <code>from</code>, 59048e3e3a7aSWarner Loshand pushes them onto the stack <code>to</code>. 59058e3e3a7aSWarner Losh 59068e3e3a7aSWarner Losh 59078e3e3a7aSWarner Losh 59088e3e3a7aSWarner Losh 59098e3e3a7aSWarner Losh 59108e3e3a7aSWarner Losh<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> 59110495ed39SKyle Evans<span class="apii">[-?, +?, <em>v</em>]</span> 59128e3e3a7aSWarner Losh<pre>int lua_yield (lua_State *L, int nresults);</pre> 59138e3e3a7aSWarner Losh 59148e3e3a7aSWarner Losh<p> 59158e3e3a7aSWarner LoshThis function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 59160495ed39SKyle Evansbut it has no continuation (see <a href="#4.5">§4.5</a>). 59178e3e3a7aSWarner LoshTherefore, when the thread resumes, 59188e3e3a7aSWarner Loshit continues the function that called 59198e3e3a7aSWarner Loshthe function calling <code>lua_yield</code>. 59200495ed39SKyle EvansTo avoid surprises, 59210495ed39SKyle Evansthis function should be called only in a tail call. 59228e3e3a7aSWarner Losh 59238e3e3a7aSWarner Losh 59248e3e3a7aSWarner Losh 59258e3e3a7aSWarner Losh 59268e3e3a7aSWarner Losh 59278e3e3a7aSWarner Losh<hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p> 59280495ed39SKyle Evans<span class="apii">[-?, +?, <em>v</em>]</span> 59298e3e3a7aSWarner Losh<pre>int lua_yieldk (lua_State *L, 59308e3e3a7aSWarner Losh int nresults, 59318e3e3a7aSWarner Losh lua_KContext ctx, 59328e3e3a7aSWarner Losh lua_KFunction k);</pre> 59338e3e3a7aSWarner Losh 59348e3e3a7aSWarner Losh<p> 59358e3e3a7aSWarner LoshYields a coroutine (thread). 59368e3e3a7aSWarner Losh 59378e3e3a7aSWarner Losh 59388e3e3a7aSWarner Losh<p> 59398e3e3a7aSWarner LoshWhen a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 59408e3e3a7aSWarner Loshthe running coroutine suspends its execution, 59418e3e3a7aSWarner Loshand the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. 59428e3e3a7aSWarner LoshThe parameter <code>nresults</code> is the number of values from the stack 59438e3e3a7aSWarner Loshthat will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. 59448e3e3a7aSWarner Losh 59458e3e3a7aSWarner Losh 59468e3e3a7aSWarner Losh<p> 59478e3e3a7aSWarner LoshWhen the coroutine is resumed again, 59488e3e3a7aSWarner LoshLua calls the given continuation function <code>k</code> to continue 59490495ed39SKyle Evansthe execution of the C function that yielded (see <a href="#4.5">§4.5</a>). 59508e3e3a7aSWarner LoshThis continuation function receives the same stack 59518e3e3a7aSWarner Loshfrom the previous function, 59528e3e3a7aSWarner Loshwith the <code>n</code> results removed and 59538e3e3a7aSWarner Loshreplaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>. 59548e3e3a7aSWarner LoshMoreover, 59558e3e3a7aSWarner Loshthe continuation function receives the value <code>ctx</code> 59568e3e3a7aSWarner Loshthat was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>. 59578e3e3a7aSWarner Losh 59588e3e3a7aSWarner Losh 59598e3e3a7aSWarner Losh<p> 59608e3e3a7aSWarner LoshUsually, this function does not return; 59618e3e3a7aSWarner Loshwhen the coroutine eventually resumes, 59628e3e3a7aSWarner Loshit continues executing the continuation function. 59638e3e3a7aSWarner LoshHowever, there is one special case, 59648e3e3a7aSWarner Loshwhich is when this function is called 59650495ed39SKyle Evansfrom inside a line or a count hook (see <a href="#4.7">§4.7</a>). 59668e3e3a7aSWarner LoshIn that case, <code>lua_yieldk</code> should be called with no continuation 59678e3e3a7aSWarner Losh(probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results, 59688e3e3a7aSWarner Loshand the hook should return immediately after the call. 59698e3e3a7aSWarner LoshLua will yield and, 59708e3e3a7aSWarner Loshwhen the coroutine resumes again, 59718e3e3a7aSWarner Loshit will continue the normal execution 59728e3e3a7aSWarner Loshof the (Lua) function that triggered the hook. 59738e3e3a7aSWarner Losh 59748e3e3a7aSWarner Losh 59758e3e3a7aSWarner Losh<p> 59768e3e3a7aSWarner LoshThis function can raise an error if it is called from a thread 59770495ed39SKyle Evanswith a pending C call with no continuation function 59780495ed39SKyle Evans(what is called a <em>C-call boundary</em>), 59798e3e3a7aSWarner Loshor it is called from a thread that is not running inside a resume 59800495ed39SKyle Evans(typically the main thread). 59818e3e3a7aSWarner Losh 59828e3e3a7aSWarner Losh 59838e3e3a7aSWarner Losh 59848e3e3a7aSWarner Losh 59858e3e3a7aSWarner Losh 59868e3e3a7aSWarner Losh 59878e3e3a7aSWarner Losh 59880495ed39SKyle Evans<h2>4.7 – <a name="4.7">The Debug Interface</a></h2> 59898e3e3a7aSWarner Losh 59908e3e3a7aSWarner Losh<p> 59918e3e3a7aSWarner LoshLua has no built-in debugging facilities. 59928e3e3a7aSWarner LoshInstead, it offers a special interface 59938e3e3a7aSWarner Loshby means of functions and <em>hooks</em>. 59948e3e3a7aSWarner LoshThis interface allows the construction of different 59958e3e3a7aSWarner Loshkinds of debuggers, profilers, and other tools 59968e3e3a7aSWarner Loshthat need "inside information" from the interpreter. 59978e3e3a7aSWarner Losh 59988e3e3a7aSWarner Losh 59998e3e3a7aSWarner Losh 60008e3e3a7aSWarner Losh<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> 60018e3e3a7aSWarner Losh<pre>typedef struct lua_Debug { 60028e3e3a7aSWarner Losh int event; 60038e3e3a7aSWarner Losh const char *name; /* (n) */ 60048e3e3a7aSWarner Losh const char *namewhat; /* (n) */ 60058e3e3a7aSWarner Losh const char *what; /* (S) */ 60068e3e3a7aSWarner Losh const char *source; /* (S) */ 60070495ed39SKyle Evans size_t srclen; /* (S) */ 60088e3e3a7aSWarner Losh int currentline; /* (l) */ 60098e3e3a7aSWarner Losh int linedefined; /* (S) */ 60108e3e3a7aSWarner Losh int lastlinedefined; /* (S) */ 60118e3e3a7aSWarner Losh unsigned char nups; /* (u) number of upvalues */ 60128e3e3a7aSWarner Losh unsigned char nparams; /* (u) number of parameters */ 60138e3e3a7aSWarner Losh char isvararg; /* (u) */ 60148e3e3a7aSWarner Losh char istailcall; /* (t) */ 60150495ed39SKyle Evans unsigned short ftransfer; /* (r) index of first value transferred */ 60160495ed39SKyle Evans unsigned short ntransfer; /* (r) number of transferred values */ 60178e3e3a7aSWarner Losh char short_src[LUA_IDSIZE]; /* (S) */ 60188e3e3a7aSWarner Losh /* private part */ 60198e3e3a7aSWarner Losh <em>other fields</em> 60208e3e3a7aSWarner Losh} lua_Debug;</pre> 60218e3e3a7aSWarner Losh 60228e3e3a7aSWarner Losh<p> 60238e3e3a7aSWarner LoshA structure used to carry different pieces of 60248e3e3a7aSWarner Loshinformation about a function or an activation record. 60258e3e3a7aSWarner Losh<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part 60268e3e3a7aSWarner Loshof this structure, for later use. 60278e3e3a7aSWarner LoshTo fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, 60288c784bb8SWarner Loshyou must call <a href="#lua_getinfo"><code>lua_getinfo</code></a> with an appropriate parameter. 60298c784bb8SWarner Losh(Specifically, to get a field, 60308c784bb8SWarner Loshyou must add the letter between parentheses in the field's comment 60318c784bb8SWarner Loshto the parameter <code>what</code> of <a href="#lua_getinfo"><code>lua_getinfo</code></a>.) 60328e3e3a7aSWarner Losh 60338e3e3a7aSWarner Losh 60348e3e3a7aSWarner Losh<p> 60358e3e3a7aSWarner LoshThe fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: 60368e3e3a7aSWarner Losh 60378e3e3a7aSWarner Losh<ul> 60388e3e3a7aSWarner Losh 60398e3e3a7aSWarner Losh<li><b><code>source</code>: </b> 60400495ed39SKyle Evansthe source of the chunk that created the function. 60418e3e3a7aSWarner LoshIf <code>source</code> starts with a '<code>@</code>', 60428e3e3a7aSWarner Loshit means that the function was defined in a file where 60438e3e3a7aSWarner Loshthe file name follows the '<code>@</code>'. 60448e3e3a7aSWarner LoshIf <code>source</code> starts with a '<code>=</code>', 60450495ed39SKyle Evansthe remainder of its contents describes the source in a user-dependent manner. 60468e3e3a7aSWarner LoshOtherwise, 60478e3e3a7aSWarner Loshthe function was defined in a string where 60488e3e3a7aSWarner Losh<code>source</code> is that string. 60498e3e3a7aSWarner Losh</li> 60508e3e3a7aSWarner Losh 60510495ed39SKyle Evans<li><b><code>srclen</code>: </b> 60520495ed39SKyle EvansThe length of the string <code>source</code>. 60530495ed39SKyle Evans</li> 60540495ed39SKyle Evans 60558e3e3a7aSWarner Losh<li><b><code>short_src</code>: </b> 60568e3e3a7aSWarner Losha "printable" version of <code>source</code>, to be used in error messages. 60578e3e3a7aSWarner Losh</li> 60588e3e3a7aSWarner Losh 60598e3e3a7aSWarner Losh<li><b><code>linedefined</code>: </b> 60608e3e3a7aSWarner Loshthe line number where the definition of the function starts. 60618e3e3a7aSWarner Losh</li> 60628e3e3a7aSWarner Losh 60638e3e3a7aSWarner Losh<li><b><code>lastlinedefined</code>: </b> 60648e3e3a7aSWarner Loshthe line number where the definition of the function ends. 60658e3e3a7aSWarner Losh</li> 60668e3e3a7aSWarner Losh 60678e3e3a7aSWarner Losh<li><b><code>what</code>: </b> 60688e3e3a7aSWarner Loshthe string <code>"Lua"</code> if the function is a Lua function, 60698e3e3a7aSWarner Losh<code>"C"</code> if it is a C function, 60708e3e3a7aSWarner Losh<code>"main"</code> if it is the main part of a chunk. 60718e3e3a7aSWarner Losh</li> 60728e3e3a7aSWarner Losh 60738e3e3a7aSWarner Losh<li><b><code>currentline</code>: </b> 60748e3e3a7aSWarner Loshthe current line where the given function is executing. 60758e3e3a7aSWarner LoshWhen no line information is available, 60768e3e3a7aSWarner Losh<code>currentline</code> is set to -1. 60778e3e3a7aSWarner Losh</li> 60788e3e3a7aSWarner Losh 60798e3e3a7aSWarner Losh<li><b><code>name</code>: </b> 60808e3e3a7aSWarner Losha reasonable name for the given function. 60818e3e3a7aSWarner LoshBecause functions in Lua are first-class values, 60828e3e3a7aSWarner Loshthey do not have a fixed name: 60838e3e3a7aSWarner Loshsome functions can be the value of multiple global variables, 60848e3e3a7aSWarner Loshwhile others can be stored only in a table field. 60858e3e3a7aSWarner LoshThe <code>lua_getinfo</code> function checks how the function was 60868e3e3a7aSWarner Loshcalled to find a suitable name. 60878e3e3a7aSWarner LoshIf it cannot find a name, 60888e3e3a7aSWarner Loshthen <code>name</code> is set to <code>NULL</code>. 60898e3e3a7aSWarner Losh</li> 60908e3e3a7aSWarner Losh 60918e3e3a7aSWarner Losh<li><b><code>namewhat</code>: </b> 60928e3e3a7aSWarner Loshexplains the <code>name</code> field. 60938e3e3a7aSWarner LoshThe value of <code>namewhat</code> can be 60948e3e3a7aSWarner Losh<code>"global"</code>, <code>"local"</code>, <code>"method"</code>, 60958e3e3a7aSWarner Losh<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), 60968e3e3a7aSWarner Loshaccording to how the function was called. 60978e3e3a7aSWarner Losh(Lua uses the empty string when no other option seems to apply.) 60988e3e3a7aSWarner Losh</li> 60998e3e3a7aSWarner Losh 61008e3e3a7aSWarner Losh<li><b><code>istailcall</code>: </b> 61018e3e3a7aSWarner Loshtrue if this function invocation was called by a tail call. 61028e3e3a7aSWarner LoshIn this case, the caller of this level is not in the stack. 61038e3e3a7aSWarner Losh</li> 61048e3e3a7aSWarner Losh 61058e3e3a7aSWarner Losh<li><b><code>nups</code>: </b> 61068e3e3a7aSWarner Loshthe number of upvalues of the function. 61078e3e3a7aSWarner Losh</li> 61088e3e3a7aSWarner Losh 61098e3e3a7aSWarner Losh<li><b><code>nparams</code>: </b> 61100495ed39SKyle Evansthe number of parameters of the function 61118e3e3a7aSWarner Losh(always 0 for C functions). 61128e3e3a7aSWarner Losh</li> 61138e3e3a7aSWarner Losh 61148e3e3a7aSWarner Losh<li><b><code>isvararg</code>: </b> 6115*a9490b81SWarner Loshtrue if the function is a variadic function 61168e3e3a7aSWarner Losh(always true for C functions). 61178e3e3a7aSWarner Losh</li> 61188e3e3a7aSWarner Losh 61190495ed39SKyle Evans<li><b><code>ftransfer</code>: </b> 61200495ed39SKyle Evansthe index in the stack of the first value being "transferred", 61210495ed39SKyle Evansthat is, parameters in a call or return values in a return. 61220495ed39SKyle Evans(The other values are in consecutive indices.) 61230495ed39SKyle EvansUsing this index, you can access and modify these values 61240495ed39SKyle Evansthrough <a href="#lua_getlocal"><code>lua_getlocal</code></a> and <a href="#lua_setlocal"><code>lua_setlocal</code></a>. 61250495ed39SKyle EvansThis field is only meaningful during a 61260495ed39SKyle Evanscall hook, denoting the first parameter, 61270495ed39SKyle Evansor a return hook, denoting the first value being returned. 61280495ed39SKyle Evans(For call hooks, this value is always 1.) 61290495ed39SKyle Evans</li> 61300495ed39SKyle Evans 61310495ed39SKyle Evans<li><b><code>ntransfer</code>: </b> 61320495ed39SKyle EvansThe number of values being transferred (see previous item). 61330495ed39SKyle Evans(For calls of Lua functions, 61340495ed39SKyle Evansthis value is always equal to <code>nparams</code>.) 61350495ed39SKyle Evans</li> 61360495ed39SKyle Evans 61378e3e3a7aSWarner Losh</ul> 61388e3e3a7aSWarner Losh 61398e3e3a7aSWarner Losh 61408e3e3a7aSWarner Losh 61418e3e3a7aSWarner Losh 61428e3e3a7aSWarner Losh<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> 61438e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 61448e3e3a7aSWarner Losh<pre>lua_Hook lua_gethook (lua_State *L);</pre> 61458e3e3a7aSWarner Losh 61468e3e3a7aSWarner Losh<p> 61478e3e3a7aSWarner LoshReturns the current hook function. 61488e3e3a7aSWarner Losh 61498e3e3a7aSWarner Losh 61508e3e3a7aSWarner Losh 61518e3e3a7aSWarner Losh 61528e3e3a7aSWarner Losh 61538e3e3a7aSWarner Losh<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> 61548e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 61558e3e3a7aSWarner Losh<pre>int lua_gethookcount (lua_State *L);</pre> 61568e3e3a7aSWarner Losh 61578e3e3a7aSWarner Losh<p> 61588e3e3a7aSWarner LoshReturns the current hook count. 61598e3e3a7aSWarner Losh 61608e3e3a7aSWarner Losh 61618e3e3a7aSWarner Losh 61628e3e3a7aSWarner Losh 61638e3e3a7aSWarner Losh 61648e3e3a7aSWarner Losh<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> 61658e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 61668e3e3a7aSWarner Losh<pre>int lua_gethookmask (lua_State *L);</pre> 61678e3e3a7aSWarner Losh 61688e3e3a7aSWarner Losh<p> 61698e3e3a7aSWarner LoshReturns the current hook mask. 61708e3e3a7aSWarner Losh 61718e3e3a7aSWarner Losh 61728e3e3a7aSWarner Losh 61738e3e3a7aSWarner Losh 61748e3e3a7aSWarner Losh 61758e3e3a7aSWarner Losh<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> 61760495ed39SKyle Evans<span class="apii">[-(0|1), +(0|1|2), <em>m</em>]</span> 61778e3e3a7aSWarner Losh<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> 61788e3e3a7aSWarner Losh 61798e3e3a7aSWarner Losh<p> 61808e3e3a7aSWarner LoshGets information about a specific function or function invocation. 61818e3e3a7aSWarner Losh 61828e3e3a7aSWarner Losh 61838e3e3a7aSWarner Losh<p> 61848e3e3a7aSWarner LoshTo get information about a function invocation, 61858e3e3a7aSWarner Loshthe parameter <code>ar</code> must be a valid activation record that was 61868e3e3a7aSWarner Loshfilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 61878e3e3a7aSWarner Loshgiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 61888e3e3a7aSWarner Losh 61898e3e3a7aSWarner Losh 61908e3e3a7aSWarner Losh<p> 6191e112e9d2SKyle EvansTo get information about a function, you push it onto the stack 61928e3e3a7aSWarner Loshand start the <code>what</code> string with the character '<code>></code>'. 61938e3e3a7aSWarner Losh(In that case, 61948e3e3a7aSWarner Losh<code>lua_getinfo</code> pops the function from the top of the stack.) 61958e3e3a7aSWarner LoshFor instance, to know in which line a function <code>f</code> was defined, 61968e3e3a7aSWarner Loshyou can write the following code: 61978e3e3a7aSWarner Losh 61988e3e3a7aSWarner Losh<pre> 61998e3e3a7aSWarner Losh lua_Debug ar; 62008e3e3a7aSWarner Losh lua_getglobal(L, "f"); /* get global 'f' */ 62018e3e3a7aSWarner Losh lua_getinfo(L, ">S", &ar); 62028e3e3a7aSWarner Losh printf("%d\n", ar.linedefined); 62038e3e3a7aSWarner Losh</pre> 62048e3e3a7aSWarner Losh 62058e3e3a7aSWarner Losh<p> 62068e3e3a7aSWarner LoshEach character in the string <code>what</code> 62078e3e3a7aSWarner Loshselects some fields of the structure <code>ar</code> to be filled or 62088c784bb8SWarner Losha value to be pushed on the stack. 62098c784bb8SWarner Losh(These characters are also documented in the declaration of 62108c784bb8SWarner Loshthe structure <a href="#lua_Debug"><code>lua_Debug</code></a>, 62118c784bb8SWarner Loshbetween parentheses in the comments following each field.) 62128e3e3a7aSWarner Losh 62138e3e3a7aSWarner Losh<ul> 62148e3e3a7aSWarner Losh 62158c784bb8SWarner Losh<li><b>'<code>f</code>': </b> 62168c784bb8SWarner Loshpushes onto the stack the function that is 62178c784bb8SWarner Loshrunning at the given level; 62188c784bb8SWarner Losh</li> 62198c784bb8SWarner Losh 62208c784bb8SWarner Losh<li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>; 62218c784bb8SWarner Losh</li> 62228c784bb8SWarner Losh 62238c784bb8SWarner Losh<li><b>'<code>n</code>': </b> fills in the fields <code>name</code> and <code>namewhat</code>; 62248c784bb8SWarner Losh</li> 62258c784bb8SWarner Losh 62268c784bb8SWarner Losh<li><b>'<code>r</code>': </b> fills in the fields <code>ftransfer</code> and <code>ntransfer</code>; 62278e3e3a7aSWarner Losh</li> 62288e3e3a7aSWarner Losh 62298e3e3a7aSWarner Losh<li><b>'<code>S</code>': </b> 62308e3e3a7aSWarner Loshfills in the fields <code>source</code>, <code>short_src</code>, 62318e3e3a7aSWarner Losh<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; 62328e3e3a7aSWarner Losh</li> 62338e3e3a7aSWarner Losh 62348e3e3a7aSWarner Losh<li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>; 62358e3e3a7aSWarner Losh</li> 62368e3e3a7aSWarner Losh 62378e3e3a7aSWarner Losh<li><b>'<code>u</code>': </b> fills in the fields 62388e3e3a7aSWarner Losh<code>nups</code>, <code>nparams</code>, and <code>isvararg</code>; 62398e3e3a7aSWarner Losh</li> 62408e3e3a7aSWarner Losh 62418e3e3a7aSWarner Losh<li><b>'<code>L</code>': </b> 62428c784bb8SWarner Loshpushes onto the stack a table whose indices are 62438c784bb8SWarner Loshthe lines on the function with some associated code, 62448c784bb8SWarner Loshthat is, the lines where you can put a break point. 62458c784bb8SWarner Losh(Lines with no code include empty lines and comments.) 62468e3e3a7aSWarner LoshIf this option is given together with option '<code>f</code>', 62478e3e3a7aSWarner Loshits table is pushed after the function. 62480495ed39SKyle EvansThis is the only option that can raise a memory error. 62498e3e3a7aSWarner Losh</li> 62508e3e3a7aSWarner Losh 62518e3e3a7aSWarner Losh</ul> 62528e3e3a7aSWarner Losh 62538e3e3a7aSWarner Losh<p> 62540495ed39SKyle EvansThis function returns 0 to signal an invalid option in <code>what</code>; 62550495ed39SKyle Evanseven then the valid options are handled correctly. 62568e3e3a7aSWarner Losh 62578e3e3a7aSWarner Losh 62588e3e3a7aSWarner Losh 62598e3e3a7aSWarner Losh 62608e3e3a7aSWarner Losh 62618e3e3a7aSWarner Losh<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> 62628e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), –]</span> 62638e3e3a7aSWarner Losh<pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 62648e3e3a7aSWarner Losh 62658e3e3a7aSWarner Losh<p> 62660495ed39SKyle EvansGets information about a local variable or a temporary value 62670495ed39SKyle Evansof a given activation record or a given function. 62688e3e3a7aSWarner Losh 62698e3e3a7aSWarner Losh 62708e3e3a7aSWarner Losh<p> 62718e3e3a7aSWarner LoshIn the first case, 62728e3e3a7aSWarner Loshthe parameter <code>ar</code> must be a valid activation record that was 62738e3e3a7aSWarner Loshfilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 62748e3e3a7aSWarner Loshgiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 62758e3e3a7aSWarner LoshThe index <code>n</code> selects which local variable to inspect; 62768e3e3a7aSWarner Loshsee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices 62778e3e3a7aSWarner Loshand names. 62788e3e3a7aSWarner Losh 62798e3e3a7aSWarner Losh 62808e3e3a7aSWarner Losh<p> 62818e3e3a7aSWarner Losh<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack 62828e3e3a7aSWarner Loshand returns its name. 62838e3e3a7aSWarner Losh 62848e3e3a7aSWarner Losh 62858e3e3a7aSWarner Losh<p> 62868e3e3a7aSWarner LoshIn the second case, <code>ar</code> must be <code>NULL</code> and the function 62870495ed39SKyle Evansto be inspected must be on the top of the stack. 62888e3e3a7aSWarner LoshIn this case, only parameters of Lua functions are visible 62898e3e3a7aSWarner Losh(as there is no information about what variables are active) 62908e3e3a7aSWarner Loshand no values are pushed onto the stack. 62918e3e3a7aSWarner Losh 62928e3e3a7aSWarner Losh 62938e3e3a7aSWarner Losh<p> 62948e3e3a7aSWarner LoshReturns <code>NULL</code> (and pushes nothing) 62958e3e3a7aSWarner Loshwhen the index is greater than 62968e3e3a7aSWarner Loshthe number of active local variables. 62978e3e3a7aSWarner Losh 62988e3e3a7aSWarner Losh 62998e3e3a7aSWarner Losh 63008e3e3a7aSWarner Losh 63018e3e3a7aSWarner Losh 63028e3e3a7aSWarner Losh<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> 63038e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 63048e3e3a7aSWarner Losh<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> 63058e3e3a7aSWarner Losh 63068e3e3a7aSWarner Losh<p> 63078e3e3a7aSWarner LoshGets information about the interpreter runtime stack. 63088e3e3a7aSWarner Losh 63098e3e3a7aSWarner Losh 63108e3e3a7aSWarner Losh<p> 63118e3e3a7aSWarner LoshThis function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with 63128e3e3a7aSWarner Loshan identification of the <em>activation record</em> 63138e3e3a7aSWarner Loshof the function executing at a given level. 63148e3e3a7aSWarner LoshLevel 0 is the current running function, 63158e3e3a7aSWarner Loshwhereas level <em>n+1</em> is the function that has called level <em>n</em> 63160495ed39SKyle Evans(except for tail calls, which do not count in the stack). 63170495ed39SKyle EvansWhen called with a level greater than the stack depth, 63180495ed39SKyle Evans<a href="#lua_getstack"><code>lua_getstack</code></a> returns 0; 63190495ed39SKyle Evansotherwise it returns 1. 63208e3e3a7aSWarner Losh 63218e3e3a7aSWarner Losh 63228e3e3a7aSWarner Losh 63238e3e3a7aSWarner Losh 63248e3e3a7aSWarner Losh 63258e3e3a7aSWarner Losh<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> 63268e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), –]</span> 63278e3e3a7aSWarner Losh<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> 63288e3e3a7aSWarner Losh 63298e3e3a7aSWarner Losh<p> 63308e3e3a7aSWarner LoshGets information about the <code>n</code>-th upvalue 63318e3e3a7aSWarner Loshof the closure at index <code>funcindex</code>. 63328e3e3a7aSWarner LoshIt pushes the upvalue's value onto the stack 63338e3e3a7aSWarner Loshand returns its name. 63348e3e3a7aSWarner LoshReturns <code>NULL</code> (and pushes nothing) 63358e3e3a7aSWarner Loshwhen the index <code>n</code> is greater than the number of upvalues. 63368e3e3a7aSWarner Losh 63378e3e3a7aSWarner Losh 63388e3e3a7aSWarner Losh<p> 63390495ed39SKyle EvansSee <a href="#pdf-debug.getupvalue"><code>debug.getupvalue</code></a> for more information about upvalues. 63408e3e3a7aSWarner Losh 63418e3e3a7aSWarner Losh 63428e3e3a7aSWarner Losh 63438e3e3a7aSWarner Losh 63448e3e3a7aSWarner Losh 63458e3e3a7aSWarner Losh<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> 63468e3e3a7aSWarner Losh<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> 63478e3e3a7aSWarner Losh 63488e3e3a7aSWarner Losh<p> 63498e3e3a7aSWarner LoshType for debugging hook functions. 63508e3e3a7aSWarner Losh 63518e3e3a7aSWarner Losh 63528e3e3a7aSWarner Losh<p> 63538e3e3a7aSWarner LoshWhenever a hook is called, its <code>ar</code> argument has its field 63548e3e3a7aSWarner Losh<code>event</code> set to the specific event that triggered the hook. 63558e3e3a7aSWarner LoshLua identifies these events with the following constants: 63568e3e3a7aSWarner Losh<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, 63578e3e3a7aSWarner Losh<a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, 63588e3e3a7aSWarner Loshand <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. 63598e3e3a7aSWarner LoshMoreover, for line events, the field <code>currentline</code> is also set. 63608e3e3a7aSWarner LoshTo get the value of any other field in <code>ar</code>, 63618e3e3a7aSWarner Loshthe hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 63628e3e3a7aSWarner Losh 63638e3e3a7aSWarner Losh 63648e3e3a7aSWarner Losh<p> 63658e3e3a7aSWarner LoshFor call events, <code>event</code> can be <code>LUA_HOOKCALL</code>, 63668e3e3a7aSWarner Loshthe normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call; 63678e3e3a7aSWarner Loshin this case, there will be no corresponding return event. 63688e3e3a7aSWarner Losh 63698e3e3a7aSWarner Losh 63708e3e3a7aSWarner Losh<p> 63718e3e3a7aSWarner LoshWhile Lua is running a hook, it disables other calls to hooks. 63728e3e3a7aSWarner LoshTherefore, if a hook calls back Lua to execute a function or a chunk, 63738e3e3a7aSWarner Loshthis execution occurs without any calls to hooks. 63748e3e3a7aSWarner Losh 63758e3e3a7aSWarner Losh 63768e3e3a7aSWarner Losh<p> 63778e3e3a7aSWarner LoshHook functions cannot have continuations, 63788e3e3a7aSWarner Loshthat is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 63798e3e3a7aSWarner 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>. 63808e3e3a7aSWarner Losh 63818e3e3a7aSWarner Losh 63828e3e3a7aSWarner Losh<p> 63838e3e3a7aSWarner LoshHook functions can yield under the following conditions: 63848e3e3a7aSWarner LoshOnly count and line events can yield; 63858e3e3a7aSWarner Loshto yield, a hook function must finish its execution 63868e3e3a7aSWarner Loshcalling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero 63878e3e3a7aSWarner Losh(that is, with no values). 63888e3e3a7aSWarner Losh 63898e3e3a7aSWarner Losh 63908e3e3a7aSWarner Losh 63918e3e3a7aSWarner Losh 63928e3e3a7aSWarner Losh 63938e3e3a7aSWarner Losh<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> 63948e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 63958e3e3a7aSWarner Losh<pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> 63968e3e3a7aSWarner Losh 63978e3e3a7aSWarner Losh<p> 63988e3e3a7aSWarner LoshSets the debugging hook function. 63998e3e3a7aSWarner Losh 64008e3e3a7aSWarner Losh 64018e3e3a7aSWarner Losh<p> 64028e3e3a7aSWarner LoshArgument <code>f</code> is the hook function. 64038e3e3a7aSWarner Losh<code>mask</code> specifies on which events the hook will be called: 64048e3e3a7aSWarner Loshit is formed by a bitwise OR of the constants 64058e3e3a7aSWarner Losh<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, 64068e3e3a7aSWarner Losh<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, 64078e3e3a7aSWarner Losh<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, 64088e3e3a7aSWarner Loshand <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. 64098e3e3a7aSWarner LoshThe <code>count</code> argument is only meaningful when the mask 64108e3e3a7aSWarner Loshincludes <code>LUA_MASKCOUNT</code>. 64118e3e3a7aSWarner LoshFor each event, the hook is called as explained below: 64128e3e3a7aSWarner Losh 64138e3e3a7aSWarner Losh<ul> 64148e3e3a7aSWarner Losh 64158e3e3a7aSWarner Losh<li><b>The call hook: </b> is called when the interpreter calls a function. 64160495ed39SKyle EvansThe hook is called just after Lua enters the new function. 64178e3e3a7aSWarner Losh</li> 64188e3e3a7aSWarner Losh 64198e3e3a7aSWarner Losh<li><b>The return hook: </b> is called when the interpreter returns from a function. 64208e3e3a7aSWarner LoshThe hook is called just before Lua leaves the function. 64218e3e3a7aSWarner Losh</li> 64228e3e3a7aSWarner Losh 64238e3e3a7aSWarner Losh<li><b>The line hook: </b> is called when the interpreter is about to 64248e3e3a7aSWarner Loshstart the execution of a new line of code, 64258e3e3a7aSWarner Loshor when it jumps back in the code (even to the same line). 64260495ed39SKyle EvansThis event only happens while Lua is executing a Lua function. 64278e3e3a7aSWarner Losh</li> 64288e3e3a7aSWarner Losh 64298e3e3a7aSWarner Losh<li><b>The count hook: </b> is called after the interpreter executes every 64308e3e3a7aSWarner Losh<code>count</code> instructions. 64310495ed39SKyle EvansThis event only happens while Lua is executing a Lua function. 64328e3e3a7aSWarner Losh</li> 64338e3e3a7aSWarner Losh 64348e3e3a7aSWarner Losh</ul> 64358e3e3a7aSWarner Losh 64368e3e3a7aSWarner Losh<p> 64370495ed39SKyle EvansHooks are disabled by setting <code>mask</code> to zero. 64388e3e3a7aSWarner Losh 64398e3e3a7aSWarner Losh 64408e3e3a7aSWarner Losh 64418e3e3a7aSWarner Losh 64428e3e3a7aSWarner Losh 64438e3e3a7aSWarner Losh<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> 64448e3e3a7aSWarner Losh<span class="apii">[-(0|1), +0, –]</span> 64458e3e3a7aSWarner Losh<pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 64468e3e3a7aSWarner Losh 64478e3e3a7aSWarner Losh<p> 64488e3e3a7aSWarner LoshSets the value of a local variable of a given activation record. 64490495ed39SKyle EvansIt assigns the value on the top of the stack 64508e3e3a7aSWarner Loshto the variable and returns its name. 64518e3e3a7aSWarner LoshIt also pops the value from the stack. 64528e3e3a7aSWarner Losh 64538e3e3a7aSWarner Losh 64548e3e3a7aSWarner Losh<p> 64558e3e3a7aSWarner LoshReturns <code>NULL</code> (and pops nothing) 64568e3e3a7aSWarner Loshwhen the index is greater than 64578e3e3a7aSWarner Loshthe number of active local variables. 64588e3e3a7aSWarner Losh 64598e3e3a7aSWarner Losh 64608e3e3a7aSWarner Losh<p> 64610495ed39SKyle EvansParameters <code>ar</code> and <code>n</code> are as in the function <a href="#lua_getlocal"><code>lua_getlocal</code></a>. 64628e3e3a7aSWarner Losh 64638e3e3a7aSWarner Losh 64648e3e3a7aSWarner Losh 64658e3e3a7aSWarner Losh 64668e3e3a7aSWarner Losh 64678e3e3a7aSWarner Losh<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> 64688e3e3a7aSWarner Losh<span class="apii">[-(0|1), +0, –]</span> 64698e3e3a7aSWarner Losh<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> 64708e3e3a7aSWarner Losh 64718e3e3a7aSWarner Losh<p> 64728e3e3a7aSWarner LoshSets the value of a closure's upvalue. 64730495ed39SKyle EvansIt assigns the value on the top of the stack 64748e3e3a7aSWarner Loshto the upvalue and returns its name. 64758e3e3a7aSWarner LoshIt also pops the value from the stack. 64768e3e3a7aSWarner Losh 64778e3e3a7aSWarner Losh 64788e3e3a7aSWarner Losh<p> 64798e3e3a7aSWarner LoshReturns <code>NULL</code> (and pops nothing) 64808e3e3a7aSWarner Loshwhen the index <code>n</code> is greater than the number of upvalues. 64818e3e3a7aSWarner Losh 64828e3e3a7aSWarner Losh 64838e3e3a7aSWarner Losh<p> 64840495ed39SKyle EvansParameters <code>funcindex</code> and <code>n</code> are as in 64850495ed39SKyle Evansthe function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>. 64868e3e3a7aSWarner Losh 64878e3e3a7aSWarner Losh 64888e3e3a7aSWarner Losh 64898e3e3a7aSWarner Losh 64908e3e3a7aSWarner Losh 64918e3e3a7aSWarner Losh<hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p> 64928e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 64938e3e3a7aSWarner Losh<pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre> 64948e3e3a7aSWarner Losh 64958e3e3a7aSWarner Losh<p> 64968e3e3a7aSWarner LoshReturns a unique identifier for the upvalue numbered <code>n</code> 64978e3e3a7aSWarner Loshfrom the closure at index <code>funcindex</code>. 64988e3e3a7aSWarner Losh 64998e3e3a7aSWarner Losh 65008e3e3a7aSWarner Losh<p> 65018e3e3a7aSWarner LoshThese unique identifiers allow a program to check whether different 65028e3e3a7aSWarner Loshclosures share upvalues. 65038e3e3a7aSWarner LoshLua closures that share an upvalue 65048e3e3a7aSWarner Losh(that is, that access a same external local variable) 65058e3e3a7aSWarner Loshwill return identical ids for those upvalue indices. 65068e3e3a7aSWarner Losh 65078e3e3a7aSWarner Losh 65088e3e3a7aSWarner Losh<p> 65090495ed39SKyle EvansParameters <code>funcindex</code> and <code>n</code> are as in 65100495ed39SKyle Evansthe function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, 65118e3e3a7aSWarner Loshbut <code>n</code> cannot be greater than the number of upvalues. 65128e3e3a7aSWarner Losh 65138e3e3a7aSWarner Losh 65148e3e3a7aSWarner Losh 65158e3e3a7aSWarner Losh 65168e3e3a7aSWarner Losh 65178e3e3a7aSWarner Losh<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p> 65188e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 65198e3e3a7aSWarner Losh<pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1, 65208e3e3a7aSWarner Losh int funcindex2, int n2);</pre> 65218e3e3a7aSWarner Losh 65228e3e3a7aSWarner Losh<p> 65238e3e3a7aSWarner LoshMake the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code> 65248e3e3a7aSWarner Loshrefer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>. 65258e3e3a7aSWarner Losh 65268e3e3a7aSWarner Losh 65278e3e3a7aSWarner Losh 65288e3e3a7aSWarner Losh 65298e3e3a7aSWarner Losh 65308e3e3a7aSWarner Losh 65318e3e3a7aSWarner Losh 65328e3e3a7aSWarner Losh<h1>5 – <a name="5">The Auxiliary Library</a></h1> 65338e3e3a7aSWarner Losh 65340495ed39SKyle Evans 65350495ed39SKyle Evans 65368e3e3a7aSWarner Losh<p> 65378e3e3a7aSWarner Losh 65388e3e3a7aSWarner LoshThe <em>auxiliary library</em> provides several convenient functions 65398e3e3a7aSWarner Loshto interface C with Lua. 65408e3e3a7aSWarner LoshWhile the basic API provides the primitive functions for all 65418e3e3a7aSWarner Loshinteractions between C and Lua, 65428e3e3a7aSWarner Loshthe auxiliary library provides higher-level functions for some 65438e3e3a7aSWarner Loshcommon tasks. 65448e3e3a7aSWarner Losh 65458e3e3a7aSWarner Losh 65468e3e3a7aSWarner Losh<p> 65478e3e3a7aSWarner LoshAll functions and types from the auxiliary library 65488e3e3a7aSWarner Loshare defined in header file <code>lauxlib.h</code> and 65498e3e3a7aSWarner Loshhave a prefix <code>luaL_</code>. 65508e3e3a7aSWarner Losh 65518e3e3a7aSWarner Losh 65528e3e3a7aSWarner Losh<p> 65538e3e3a7aSWarner LoshAll functions in the auxiliary library are built on 65548e3e3a7aSWarner Loshtop of the basic API, 65558e3e3a7aSWarner Loshand so they provide nothing that cannot be done with that API. 65568e3e3a7aSWarner LoshNevertheless, the use of the auxiliary library ensures 65578e3e3a7aSWarner Loshmore consistency to your code. 65588e3e3a7aSWarner Losh 65598e3e3a7aSWarner Losh 65608e3e3a7aSWarner Losh<p> 65618e3e3a7aSWarner LoshSeveral functions in the auxiliary library use internally some 65628e3e3a7aSWarner Loshextra stack slots. 65638e3e3a7aSWarner LoshWhen a function in the auxiliary library uses less than five slots, 65648e3e3a7aSWarner Loshit does not check the stack size; 65658e3e3a7aSWarner Loshit simply assumes that there are enough slots. 65668e3e3a7aSWarner Losh 65678e3e3a7aSWarner Losh 65688e3e3a7aSWarner Losh<p> 65698e3e3a7aSWarner LoshSeveral functions in the auxiliary library are used to 65708e3e3a7aSWarner Loshcheck C function arguments. 65718e3e3a7aSWarner LoshBecause the error message is formatted for arguments 65728e3e3a7aSWarner Losh(e.g., "<code>bad argument #1</code>"), 65738e3e3a7aSWarner Loshyou should not use these functions for other stack values. 65748e3e3a7aSWarner Losh 65758e3e3a7aSWarner Losh 65768e3e3a7aSWarner Losh<p> 65778e3e3a7aSWarner LoshFunctions called <code>luaL_check*</code> 65788e3e3a7aSWarner Loshalways raise an error if the check is not satisfied. 65798e3e3a7aSWarner Losh 65808e3e3a7aSWarner Losh 65818e3e3a7aSWarner Losh 65820495ed39SKyle Evans 65830495ed39SKyle Evans 65848e3e3a7aSWarner Losh<h2>5.1 – <a name="5.1">Functions and Types</a></h2> 65858e3e3a7aSWarner Losh 65868e3e3a7aSWarner Losh<p> 65878e3e3a7aSWarner LoshHere we list all functions and types from the auxiliary library 65888e3e3a7aSWarner Loshin alphabetical order. 65898e3e3a7aSWarner Losh 65908e3e3a7aSWarner Losh 65918e3e3a7aSWarner Losh 65928e3e3a7aSWarner Losh<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> 65938e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 65948e3e3a7aSWarner Losh<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> 65958e3e3a7aSWarner Losh 65968e3e3a7aSWarner Losh<p> 65978e3e3a7aSWarner LoshAdds the byte <code>c</code> to the buffer <code>B</code> 65988e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 65998e3e3a7aSWarner Losh 66008e3e3a7aSWarner Losh 66018e3e3a7aSWarner Losh 66028e3e3a7aSWarner Losh 66038e3e3a7aSWarner Losh 66040495ed39SKyle Evans<hr><h3><a name="luaL_addgsub"><code>luaL_addgsub</code></a></h3><p> 66058c784bb8SWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 66060495ed39SKyle Evans<pre>const void luaL_addgsub (luaL_Buffer *B, const char *s, 66070495ed39SKyle Evans const char *p, const char *r);</pre> 66080495ed39SKyle Evans 66090495ed39SKyle Evans<p> 66100495ed39SKyle EvansAdds a copy of the string <code>s</code> to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>), 66110495ed39SKyle Evansreplacing any occurrence of the string <code>p</code> 66120495ed39SKyle Evanswith the string <code>r</code>. 66130495ed39SKyle Evans 66140495ed39SKyle Evans 66150495ed39SKyle Evans 66160495ed39SKyle Evans 66170495ed39SKyle Evans 66188e3e3a7aSWarner Losh<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> 66198e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 66208e3e3a7aSWarner Losh<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> 66218e3e3a7aSWarner Losh 66228e3e3a7aSWarner Losh<p> 66238e3e3a7aSWarner LoshAdds the string pointed to by <code>s</code> with length <code>l</code> to 66248e3e3a7aSWarner Loshthe buffer <code>B</code> 66258e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 66268e3e3a7aSWarner LoshThe string can contain embedded zeros. 66278e3e3a7aSWarner Losh 66288e3e3a7aSWarner Losh 66298e3e3a7aSWarner Losh 66308e3e3a7aSWarner Losh 66318e3e3a7aSWarner Losh 66328e3e3a7aSWarner Losh<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> 66338e3e3a7aSWarner Losh<span class="apii">[-?, +?, –]</span> 66348e3e3a7aSWarner Losh<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> 66358e3e3a7aSWarner Losh 66368e3e3a7aSWarner Losh<p> 66370495ed39SKyle EvansAdds to the buffer <code>B</code> 66388e3e3a7aSWarner Losha string of length <code>n</code> previously copied to the 66398e3e3a7aSWarner Loshbuffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). 66408e3e3a7aSWarner Losh 66418e3e3a7aSWarner Losh 66428e3e3a7aSWarner Losh 66438e3e3a7aSWarner Losh 66448e3e3a7aSWarner Losh 66458e3e3a7aSWarner Losh<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> 66468e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 66478e3e3a7aSWarner Losh<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> 66488e3e3a7aSWarner Losh 66498e3e3a7aSWarner Losh<p> 66508e3e3a7aSWarner LoshAdds the zero-terminated string pointed to by <code>s</code> 66518e3e3a7aSWarner Loshto the buffer <code>B</code> 66528e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 66538e3e3a7aSWarner Losh 66548e3e3a7aSWarner Losh 66558e3e3a7aSWarner Losh 66568e3e3a7aSWarner Losh 66578e3e3a7aSWarner Losh 66588e3e3a7aSWarner Losh<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> 66598c784bb8SWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 66608e3e3a7aSWarner Losh<pre>void luaL_addvalue (luaL_Buffer *B);</pre> 66618e3e3a7aSWarner Losh 66628e3e3a7aSWarner Losh<p> 66630495ed39SKyle EvansAdds the value on the top of the stack 66648e3e3a7aSWarner Loshto the buffer <code>B</code> 66658e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 66668e3e3a7aSWarner LoshPops the value. 66678e3e3a7aSWarner Losh 66688e3e3a7aSWarner Losh 66698e3e3a7aSWarner Losh<p> 66708e3e3a7aSWarner LoshThis is the only function on string buffers that can (and must) 66718e3e3a7aSWarner Loshbe called with an extra element on the stack, 66728e3e3a7aSWarner Loshwhich is the value to be added to the buffer. 66738e3e3a7aSWarner Losh 66748e3e3a7aSWarner Losh 66758e3e3a7aSWarner Losh 66768e3e3a7aSWarner Losh 66778e3e3a7aSWarner Losh 66788e3e3a7aSWarner Losh<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> 66798e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 66808e3e3a7aSWarner Losh<pre>void luaL_argcheck (lua_State *L, 66818e3e3a7aSWarner Losh int cond, 66828e3e3a7aSWarner Losh int arg, 66838e3e3a7aSWarner Losh const char *extramsg);</pre> 66848e3e3a7aSWarner Losh 66858e3e3a7aSWarner Losh<p> 66868e3e3a7aSWarner LoshChecks whether <code>cond</code> is true. 66878e3e3a7aSWarner LoshIf it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>). 66888e3e3a7aSWarner Losh 66898e3e3a7aSWarner Losh 66908e3e3a7aSWarner Losh 66918e3e3a7aSWarner Losh 66928e3e3a7aSWarner Losh 66938e3e3a7aSWarner Losh<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> 66948e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 66958e3e3a7aSWarner Losh<pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre> 66968e3e3a7aSWarner Losh 66978e3e3a7aSWarner Losh<p> 66988e3e3a7aSWarner LoshRaises an error reporting a problem with argument <code>arg</code> 66998e3e3a7aSWarner Loshof the C function that called it, 67008e3e3a7aSWarner Loshusing a standard message 67018e3e3a7aSWarner Loshthat includes <code>extramsg</code> as a comment: 67028e3e3a7aSWarner Losh 67038e3e3a7aSWarner Losh<pre> 67048e3e3a7aSWarner Losh bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>) 67058e3e3a7aSWarner Losh</pre><p> 67068e3e3a7aSWarner LoshThis function never returns. 67078e3e3a7aSWarner Losh 67088e3e3a7aSWarner Losh 67098e3e3a7aSWarner Losh 67108e3e3a7aSWarner Losh 67118e3e3a7aSWarner Losh 67120495ed39SKyle Evans<hr><h3><a name="luaL_argexpected"><code>luaL_argexpected</code></a></h3><p> 67130495ed39SKyle Evans<span class="apii">[-0, +0, <em>v</em>]</span> 67140495ed39SKyle Evans<pre>void luaL_argexpected (lua_State *L, 67150495ed39SKyle Evans int cond, 67160495ed39SKyle Evans int arg, 67170495ed39SKyle Evans const char *tname);</pre> 67180495ed39SKyle Evans 67190495ed39SKyle Evans<p> 67200495ed39SKyle EvansChecks whether <code>cond</code> is true. 67210495ed39SKyle EvansIf it is not, raises an error about the type of the argument <code>arg</code> 67220495ed39SKyle Evanswith a standard message (see <a href="#luaL_typeerror"><code>luaL_typeerror</code></a>). 67230495ed39SKyle Evans 67240495ed39SKyle Evans 67250495ed39SKyle Evans 67260495ed39SKyle Evans 67270495ed39SKyle Evans 67288e3e3a7aSWarner Losh<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> 67298e3e3a7aSWarner Losh<pre>typedef struct luaL_Buffer luaL_Buffer;</pre> 67308e3e3a7aSWarner Losh 67318e3e3a7aSWarner Losh<p> 67328e3e3a7aSWarner LoshType for a <em>string buffer</em>. 67338e3e3a7aSWarner Losh 67348e3e3a7aSWarner Losh 67358e3e3a7aSWarner Losh<p> 67368e3e3a7aSWarner LoshA string buffer allows C code to build Lua strings piecemeal. 67378e3e3a7aSWarner LoshIts pattern of use is as follows: 67388e3e3a7aSWarner Losh 67398e3e3a7aSWarner Losh<ul> 67408e3e3a7aSWarner Losh 67418e3e3a7aSWarner Losh<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 67428e3e3a7aSWarner Losh 67438e3e3a7aSWarner Losh<li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> 67448e3e3a7aSWarner Losh 67458e3e3a7aSWarner Losh<li> 67468e3e3a7aSWarner LoshThen add string pieces to the buffer calling any of 67478e3e3a7aSWarner Loshthe <code>luaL_add*</code> functions. 67488e3e3a7aSWarner Losh</li> 67498e3e3a7aSWarner Losh 67508e3e3a7aSWarner Losh<li> 67518e3e3a7aSWarner LoshFinish by calling <code>luaL_pushresult(&b)</code>. 67528e3e3a7aSWarner LoshThis call leaves the final string on the top of the stack. 67538e3e3a7aSWarner Losh</li> 67548e3e3a7aSWarner Losh 67558e3e3a7aSWarner Losh</ul> 67568e3e3a7aSWarner Losh 67578e3e3a7aSWarner Losh<p> 67580495ed39SKyle EvansIf you know beforehand the maximum size of the resulting string, 67598e3e3a7aSWarner Loshyou can use the buffer like this: 67608e3e3a7aSWarner Losh 67618e3e3a7aSWarner Losh<ul> 67628e3e3a7aSWarner Losh 67638e3e3a7aSWarner Losh<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 67648e3e3a7aSWarner Losh 67658e3e3a7aSWarner Losh<li>Then initialize it and preallocate a space of 67668e3e3a7aSWarner Loshsize <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li> 67678e3e3a7aSWarner Losh 67680495ed39SKyle Evans<li>Then produce the string into that space.</li> 67698e3e3a7aSWarner Losh 67708e3e3a7aSWarner Losh<li> 67718e3e3a7aSWarner LoshFinish by calling <code>luaL_pushresultsize(&b, sz)</code>, 67728e3e3a7aSWarner Loshwhere <code>sz</code> is the total size of the resulting string 67730495ed39SKyle Evanscopied into that space (which may be less than or 67740495ed39SKyle Evansequal to the preallocated size). 67758e3e3a7aSWarner Losh</li> 67768e3e3a7aSWarner Losh 67778e3e3a7aSWarner Losh</ul> 67788e3e3a7aSWarner Losh 67798e3e3a7aSWarner Losh<p> 67808e3e3a7aSWarner LoshDuring its normal operation, 67818e3e3a7aSWarner Losha string buffer uses a variable number of stack slots. 67828e3e3a7aSWarner LoshSo, while using a buffer, you cannot assume that you know where 67838e3e3a7aSWarner Loshthe top of the stack is. 67848e3e3a7aSWarner LoshYou can use the stack between successive calls to buffer operations 67858e3e3a7aSWarner Loshas long as that use is balanced; 67868e3e3a7aSWarner Loshthat is, 67878e3e3a7aSWarner Loshwhen you call a buffer operation, 67888e3e3a7aSWarner Loshthe stack is at the same level 67898e3e3a7aSWarner Loshit was immediately after the previous buffer operation. 67908e3e3a7aSWarner Losh(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) 67910495ed39SKyle EvansAfter calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>, 67920495ed39SKyle Evansthe stack is back to its level when the buffer was initialized, 67938e3e3a7aSWarner Loshplus the final string on its top. 67948e3e3a7aSWarner Losh 67958e3e3a7aSWarner Losh 67968e3e3a7aSWarner Losh 67978e3e3a7aSWarner Losh 67988e3e3a7aSWarner Losh 67990495ed39SKyle Evans<hr><h3><a name="luaL_buffaddr"><code>luaL_buffaddr</code></a></h3><p> 68000495ed39SKyle Evans<span class="apii">[-0, +0, –]</span> 68010495ed39SKyle Evans<pre>char *luaL_buffaddr (luaL_Buffer *B);</pre> 68020495ed39SKyle Evans 68030495ed39SKyle Evans<p> 68040495ed39SKyle EvansReturns the address of the current content of buffer <code>B</code> 68050495ed39SKyle Evans(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 68060495ed39SKyle EvansNote that any addition to the buffer may invalidate this address. 68070495ed39SKyle Evans 68080495ed39SKyle Evans 68090495ed39SKyle Evans 68100495ed39SKyle Evans 68110495ed39SKyle Evans 68128e3e3a7aSWarner Losh<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> 68138c784bb8SWarner Losh<span class="apii">[-0, +?, –]</span> 68148e3e3a7aSWarner Losh<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> 68158e3e3a7aSWarner Losh 68168e3e3a7aSWarner Losh<p> 68170495ed39SKyle EvansInitializes a buffer <code>B</code> 68180495ed39SKyle Evans(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 68198e3e3a7aSWarner LoshThis function does not allocate any space; 68200495ed39SKyle Evansthe buffer must be declared as a variable. 68210495ed39SKyle Evans 68220495ed39SKyle Evans 68230495ed39SKyle Evans 68240495ed39SKyle Evans 68250495ed39SKyle Evans 68260495ed39SKyle Evans<hr><h3><a name="luaL_bufflen"><code>luaL_bufflen</code></a></h3><p> 68270495ed39SKyle Evans<span class="apii">[-0, +0, –]</span> 68280495ed39SKyle Evans<pre>size_t luaL_bufflen (luaL_Buffer *B);</pre> 68290495ed39SKyle Evans 68300495ed39SKyle Evans<p> 68310495ed39SKyle EvansReturns the length of the current content of buffer <code>B</code> 68328e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 68338e3e3a7aSWarner Losh 68348e3e3a7aSWarner Losh 68358e3e3a7aSWarner Losh 68368e3e3a7aSWarner Losh 68378e3e3a7aSWarner Losh 68388e3e3a7aSWarner Losh<hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p> 68398e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 68408e3e3a7aSWarner Losh<pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre> 68418e3e3a7aSWarner Losh 68428e3e3a7aSWarner Losh<p> 68438e3e3a7aSWarner LoshEquivalent to the sequence 68448e3e3a7aSWarner Losh<a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>. 68458e3e3a7aSWarner Losh 68468e3e3a7aSWarner Losh 68478e3e3a7aSWarner Losh 68488e3e3a7aSWarner Losh 68498e3e3a7aSWarner Losh 68500495ed39SKyle Evans<hr><h3><a name="luaL_buffsub"><code>luaL_buffsub</code></a></h3><p> 68518c784bb8SWarner Losh<span class="apii">[-?, +?, –]</span> 68520495ed39SKyle Evans<pre>void luaL_buffsub (luaL_Buffer *B, int n);</pre> 68530495ed39SKyle Evans 68540495ed39SKyle Evans<p> 6855*a9490b81SWarner LoshRemoves <code>n</code> bytes from the buffer <code>B</code> 68560495ed39SKyle Evans(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 68570495ed39SKyle EvansThe buffer must have at least that many bytes. 68580495ed39SKyle Evans 68590495ed39SKyle Evans 68600495ed39SKyle Evans 68610495ed39SKyle Evans 68620495ed39SKyle Evans 68638e3e3a7aSWarner Losh<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> 68648e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), <em>e</em>]</span> 68658e3e3a7aSWarner Losh<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> 68668e3e3a7aSWarner Losh 68678e3e3a7aSWarner Losh<p> 68688e3e3a7aSWarner LoshCalls a metamethod. 68698e3e3a7aSWarner Losh 68708e3e3a7aSWarner Losh 68718e3e3a7aSWarner Losh<p> 68728e3e3a7aSWarner LoshIf the object at index <code>obj</code> has a metatable and this 68738e3e3a7aSWarner Loshmetatable has a field <code>e</code>, 68748e3e3a7aSWarner Loshthis function calls this field passing the object as its only argument. 68758e3e3a7aSWarner LoshIn this case this function returns true and pushes onto the 68768e3e3a7aSWarner Loshstack the value returned by the call. 68778e3e3a7aSWarner LoshIf there is no metatable or no metamethod, 68780495ed39SKyle Evansthis function returns false without pushing any value on the stack. 68798e3e3a7aSWarner Losh 68808e3e3a7aSWarner Losh 68818e3e3a7aSWarner Losh 68828e3e3a7aSWarner Losh 68838e3e3a7aSWarner Losh 68848e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> 68858e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 68868e3e3a7aSWarner Losh<pre>void luaL_checkany (lua_State *L, int arg);</pre> 68878e3e3a7aSWarner Losh 68888e3e3a7aSWarner Losh<p> 68898e3e3a7aSWarner LoshChecks whether the function has an argument 68908e3e3a7aSWarner Loshof any type (including <b>nil</b>) at position <code>arg</code>. 68918e3e3a7aSWarner Losh 68928e3e3a7aSWarner Losh 68938e3e3a7aSWarner Losh 68948e3e3a7aSWarner Losh 68958e3e3a7aSWarner Losh 68968e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> 68978e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 68988e3e3a7aSWarner Losh<pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre> 68998e3e3a7aSWarner Losh 69008e3e3a7aSWarner Losh<p> 69018e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is an integer 69028e3e3a7aSWarner Losh(or can be converted to an integer) 69030495ed39SKyle Evansand returns this integer. 69048e3e3a7aSWarner Losh 69058e3e3a7aSWarner Losh 69068e3e3a7aSWarner Losh 69078e3e3a7aSWarner Losh 69088e3e3a7aSWarner Losh 69098e3e3a7aSWarner Losh<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> 69108e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 69118e3e3a7aSWarner Losh<pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre> 69128e3e3a7aSWarner Losh 69138e3e3a7aSWarner Losh<p> 69148e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string 69158e3e3a7aSWarner Loshand returns this string; 69160495ed39SKyle Evansif <code>l</code> is not <code>NULL</code> fills its referent 69178e3e3a7aSWarner Loshwith the string's length. 69188e3e3a7aSWarner Losh 69198e3e3a7aSWarner Losh 69208e3e3a7aSWarner Losh<p> 69218e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 69228e3e3a7aSWarner Loshso all conversions and caveats of that function apply here. 69238e3e3a7aSWarner Losh 69248e3e3a7aSWarner Losh 69258e3e3a7aSWarner Losh 69268e3e3a7aSWarner Losh 69278e3e3a7aSWarner Losh 69288e3e3a7aSWarner Losh<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> 69298e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 69308e3e3a7aSWarner Losh<pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre> 69318e3e3a7aSWarner Losh 69328e3e3a7aSWarner Losh<p> 69338e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a number 69340495ed39SKyle Evansand returns this number converted to a <code>lua_Number</code>. 69358e3e3a7aSWarner Losh 69368e3e3a7aSWarner Losh 69378e3e3a7aSWarner Losh 69388e3e3a7aSWarner Losh 69398e3e3a7aSWarner Losh 69408e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> 69418e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 69428e3e3a7aSWarner Losh<pre>int luaL_checkoption (lua_State *L, 69438e3e3a7aSWarner Losh int arg, 69448e3e3a7aSWarner Losh const char *def, 69458e3e3a7aSWarner Losh const char *const lst[]);</pre> 69468e3e3a7aSWarner Losh 69478e3e3a7aSWarner Losh<p> 69488e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string and 69498e3e3a7aSWarner Loshsearches for this string in the array <code>lst</code> 69508e3e3a7aSWarner Losh(which must be NULL-terminated). 69518e3e3a7aSWarner LoshReturns the index in the array where the string was found. 69528e3e3a7aSWarner LoshRaises an error if the argument is not a string or 69538e3e3a7aSWarner Loshif the string cannot be found. 69548e3e3a7aSWarner Losh 69558e3e3a7aSWarner Losh 69568e3e3a7aSWarner Losh<p> 69578e3e3a7aSWarner LoshIf <code>def</code> is not <code>NULL</code>, 69588e3e3a7aSWarner Loshthe function uses <code>def</code> as a default value when 69598e3e3a7aSWarner Loshthere is no argument <code>arg</code> or when this argument is <b>nil</b>. 69608e3e3a7aSWarner Losh 69618e3e3a7aSWarner Losh 69628e3e3a7aSWarner Losh<p> 69638e3e3a7aSWarner LoshThis is a useful function for mapping strings to C enums. 69648e3e3a7aSWarner Losh(The usual convention in Lua libraries is 69658e3e3a7aSWarner Loshto use strings instead of numbers to select options.) 69668e3e3a7aSWarner Losh 69678e3e3a7aSWarner Losh 69688e3e3a7aSWarner Losh 69698e3e3a7aSWarner Losh 69708e3e3a7aSWarner Losh 69718e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> 69728e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 69738e3e3a7aSWarner Losh<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> 69748e3e3a7aSWarner Losh 69758e3e3a7aSWarner Losh<p> 69768e3e3a7aSWarner LoshGrows the stack size to <code>top + sz</code> elements, 69778e3e3a7aSWarner Loshraising an error if the stack cannot grow to that size. 69788e3e3a7aSWarner Losh<code>msg</code> is an additional text to go into the error message 69798e3e3a7aSWarner Losh(or <code>NULL</code> for no additional text). 69808e3e3a7aSWarner Losh 69818e3e3a7aSWarner Losh 69828e3e3a7aSWarner Losh 69838e3e3a7aSWarner Losh 69848e3e3a7aSWarner Losh 69858e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> 69868e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 69878e3e3a7aSWarner Losh<pre>const char *luaL_checkstring (lua_State *L, int arg);</pre> 69888e3e3a7aSWarner Losh 69898e3e3a7aSWarner Losh<p> 69908e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string 69918e3e3a7aSWarner Loshand returns this string. 69928e3e3a7aSWarner Losh 69938e3e3a7aSWarner Losh 69948e3e3a7aSWarner Losh<p> 69958e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 69968e3e3a7aSWarner Loshso all conversions and caveats of that function apply here. 69978e3e3a7aSWarner Losh 69988e3e3a7aSWarner Losh 69998e3e3a7aSWarner Losh 70008e3e3a7aSWarner Losh 70018e3e3a7aSWarner Losh 70028e3e3a7aSWarner Losh<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> 70038e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 70048e3e3a7aSWarner Losh<pre>void luaL_checktype (lua_State *L, int arg, int t);</pre> 70058e3e3a7aSWarner Losh 70068e3e3a7aSWarner Losh<p> 70078e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> has type <code>t</code>. 70088e3e3a7aSWarner LoshSee <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. 70098e3e3a7aSWarner Losh 70108e3e3a7aSWarner Losh 70118e3e3a7aSWarner Losh 70128e3e3a7aSWarner Losh 70138e3e3a7aSWarner Losh 70148e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> 70158e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 70168e3e3a7aSWarner Losh<pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre> 70178e3e3a7aSWarner Losh 70188e3e3a7aSWarner Losh<p> 70198e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a userdata 70208e3e3a7aSWarner Loshof the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and 70210495ed39SKyle Evansreturns the userdata's memory-block address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>). 70228e3e3a7aSWarner Losh 70238e3e3a7aSWarner Losh 70248e3e3a7aSWarner Losh 70258e3e3a7aSWarner Losh 70268e3e3a7aSWarner Losh 70278e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p> 70288e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 70298e3e3a7aSWarner Losh<pre>void luaL_checkversion (lua_State *L);</pre> 70308e3e3a7aSWarner Losh 70318e3e3a7aSWarner Losh<p> 70320495ed39SKyle EvansChecks whether the code making the call and the Lua library being called 70330495ed39SKyle Evansare using the same version of Lua and the same numeric types. 70348e3e3a7aSWarner Losh 70358e3e3a7aSWarner Losh 70368e3e3a7aSWarner Losh 70378e3e3a7aSWarner Losh 70388e3e3a7aSWarner Losh 70398e3e3a7aSWarner Losh<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> 70400495ed39SKyle Evans<span class="apii">[-0, +?, <em>m</em>]</span> 70418e3e3a7aSWarner Losh<pre>int luaL_dofile (lua_State *L, const char *filename);</pre> 70428e3e3a7aSWarner Losh 70438e3e3a7aSWarner Losh<p> 70448e3e3a7aSWarner LoshLoads and runs the given file. 70458e3e3a7aSWarner LoshIt is defined as the following macro: 70468e3e3a7aSWarner Losh 70478e3e3a7aSWarner Losh<pre> 70488e3e3a7aSWarner Losh (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) 70498e3e3a7aSWarner Losh</pre><p> 7050*a9490b81SWarner LoshIt returns 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) if there are no errors, 7051*a9490b81SWarner Loshor 1 in case of errors. 70528e3e3a7aSWarner Losh 70538e3e3a7aSWarner Losh 70548e3e3a7aSWarner Losh 70558e3e3a7aSWarner Losh 70568e3e3a7aSWarner Losh 70578e3e3a7aSWarner Losh<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> 70588e3e3a7aSWarner Losh<span class="apii">[-0, +?, –]</span> 70598e3e3a7aSWarner Losh<pre>int luaL_dostring (lua_State *L, const char *str);</pre> 70608e3e3a7aSWarner Losh 70618e3e3a7aSWarner Losh<p> 70628e3e3a7aSWarner LoshLoads and runs the given string. 70638e3e3a7aSWarner LoshIt is defined as the following macro: 70648e3e3a7aSWarner Losh 70658e3e3a7aSWarner Losh<pre> 70668e3e3a7aSWarner Losh (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) 70678e3e3a7aSWarner Losh</pre><p> 7068*a9490b81SWarner LoshIt returns 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) if there are no errors, 7069*a9490b81SWarner Loshor 1 in case of errors. 70708e3e3a7aSWarner Losh 70718e3e3a7aSWarner Losh 70728e3e3a7aSWarner Losh 70738e3e3a7aSWarner Losh 70748e3e3a7aSWarner Losh 70758e3e3a7aSWarner Losh<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> 70768e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 70778e3e3a7aSWarner Losh<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> 70788e3e3a7aSWarner Losh 70798e3e3a7aSWarner Losh<p> 70808e3e3a7aSWarner LoshRaises an error. 70818e3e3a7aSWarner LoshThe error message format is given by <code>fmt</code> 70828e3e3a7aSWarner Loshplus any extra arguments, 70838e3e3a7aSWarner Loshfollowing the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. 70848e3e3a7aSWarner LoshIt also adds at the beginning of the message the file name and 70858e3e3a7aSWarner Loshthe line number where the error occurred, 70868e3e3a7aSWarner Loshif this information is available. 70878e3e3a7aSWarner Losh 70888e3e3a7aSWarner Losh 70898e3e3a7aSWarner Losh<p> 70908e3e3a7aSWarner LoshThis function never returns, 70918e3e3a7aSWarner Loshbut it is an idiom to use it in C functions 70928e3e3a7aSWarner Loshas <code>return luaL_error(<em>args</em>)</code>. 70938e3e3a7aSWarner Losh 70948e3e3a7aSWarner Losh 70958e3e3a7aSWarner Losh 70968e3e3a7aSWarner Losh 70978e3e3a7aSWarner Losh 70988e3e3a7aSWarner Losh<hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p> 70998e3e3a7aSWarner Losh<span class="apii">[-0, +3, <em>m</em>]</span> 71008e3e3a7aSWarner Losh<pre>int luaL_execresult (lua_State *L, int stat);</pre> 71018e3e3a7aSWarner Losh 71028e3e3a7aSWarner Losh<p> 71038e3e3a7aSWarner LoshThis function produces the return values for 71048e3e3a7aSWarner Loshprocess-related functions in the standard library 71058e3e3a7aSWarner Losh(<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>). 71068e3e3a7aSWarner Losh 71078e3e3a7aSWarner Losh 71088e3e3a7aSWarner Losh 71098e3e3a7aSWarner Losh 71108e3e3a7aSWarner Losh 71118e3e3a7aSWarner Losh<hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p> 71128e3e3a7aSWarner Losh<span class="apii">[-0, +(1|3), <em>m</em>]</span> 71138e3e3a7aSWarner Losh<pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre> 71148e3e3a7aSWarner Losh 71158e3e3a7aSWarner Losh<p> 71168e3e3a7aSWarner LoshThis function produces the return values for 71178e3e3a7aSWarner Loshfile-related functions in the standard library 71188e3e3a7aSWarner 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.). 71198e3e3a7aSWarner Losh 71208e3e3a7aSWarner Losh 71218e3e3a7aSWarner Losh 71228e3e3a7aSWarner Losh 71238e3e3a7aSWarner Losh 71248e3e3a7aSWarner Losh<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> 71258e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), <em>m</em>]</span> 71268e3e3a7aSWarner Losh<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> 71278e3e3a7aSWarner Losh 71288e3e3a7aSWarner Losh<p> 71298e3e3a7aSWarner LoshPushes onto the stack the field <code>e</code> from the metatable 7130e112e9d2SKyle Evansof the object at index <code>obj</code> and returns the type of the pushed value. 71318e3e3a7aSWarner LoshIf the object does not have a metatable, 71328e3e3a7aSWarner Loshor if the metatable does not have this field, 71338e3e3a7aSWarner Loshpushes nothing and returns <code>LUA_TNIL</code>. 71348e3e3a7aSWarner Losh 71358e3e3a7aSWarner Losh 71368e3e3a7aSWarner Losh 71378e3e3a7aSWarner Losh 71388e3e3a7aSWarner Losh 71398e3e3a7aSWarner Losh<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> 71408e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 71418e3e3a7aSWarner Losh<pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre> 71428e3e3a7aSWarner Losh 71438e3e3a7aSWarner Losh<p> 71440495ed39SKyle EvansPushes onto the stack the metatable associated with the name <code>tname</code> 71450495ed39SKyle Evansin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>), 71460495ed39SKyle Evansor <b>nil</b> if there is no metatable associated with that name. 71478e3e3a7aSWarner LoshReturns the type of the pushed value. 71488e3e3a7aSWarner Losh 71498e3e3a7aSWarner Losh 71508e3e3a7aSWarner Losh 71518e3e3a7aSWarner Losh 71528e3e3a7aSWarner Losh 71538e3e3a7aSWarner Losh<hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p> 71548e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 71558e3e3a7aSWarner Losh<pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre> 71568e3e3a7aSWarner Losh 71578e3e3a7aSWarner Losh<p> 71588e3e3a7aSWarner LoshEnsures that the value <code>t[fname]</code>, 71598e3e3a7aSWarner Loshwhere <code>t</code> is the value at index <code>idx</code>, 71608e3e3a7aSWarner Loshis a table, 71618e3e3a7aSWarner Loshand pushes that table onto the stack. 71628e3e3a7aSWarner LoshReturns true if it finds a previous table there 71638e3e3a7aSWarner Loshand false if it creates a new table. 71648e3e3a7aSWarner Losh 71658e3e3a7aSWarner Losh 71668e3e3a7aSWarner Losh 71678e3e3a7aSWarner Losh 71688e3e3a7aSWarner Losh 71698e3e3a7aSWarner Losh<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> 71708e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 71718e3e3a7aSWarner Losh<pre>const char *luaL_gsub (lua_State *L, 71728e3e3a7aSWarner Losh const char *s, 71738e3e3a7aSWarner Losh const char *p, 71748e3e3a7aSWarner Losh const char *r);</pre> 71758e3e3a7aSWarner Losh 71768e3e3a7aSWarner Losh<p> 71770495ed39SKyle EvansCreates a copy of string <code>s</code>, 71780495ed39SKyle Evansreplacing any occurrence of the string <code>p</code> 71798e3e3a7aSWarner Loshwith the string <code>r</code>. 71808e3e3a7aSWarner LoshPushes the resulting string on the stack and returns it. 71818e3e3a7aSWarner Losh 71828e3e3a7aSWarner Losh 71838e3e3a7aSWarner Losh 71848e3e3a7aSWarner Losh 71858e3e3a7aSWarner Losh 71868e3e3a7aSWarner Losh<hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p> 71878e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 71888e3e3a7aSWarner Losh<pre>lua_Integer luaL_len (lua_State *L, int index);</pre> 71898e3e3a7aSWarner Losh 71908e3e3a7aSWarner Losh<p> 71918e3e3a7aSWarner LoshReturns the "length" of the value at the given index 71928e3e3a7aSWarner Loshas a number; 71938e3e3a7aSWarner Loshit is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). 71948e3e3a7aSWarner LoshRaises an error if the result of the operation is not an integer. 71950495ed39SKyle Evans(This case can only happen through metamethods.) 71968e3e3a7aSWarner Losh 71978e3e3a7aSWarner Losh 71988e3e3a7aSWarner Losh 71998e3e3a7aSWarner Losh 72008e3e3a7aSWarner Losh 72018e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> 72028e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 72038e3e3a7aSWarner Losh<pre>int luaL_loadbuffer (lua_State *L, 72048e3e3a7aSWarner Losh const char *buff, 72058e3e3a7aSWarner Losh size_t sz, 72068e3e3a7aSWarner Losh const char *name);</pre> 72078e3e3a7aSWarner Losh 72088e3e3a7aSWarner Losh<p> 72098e3e3a7aSWarner LoshEquivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>. 72108e3e3a7aSWarner Losh 72118e3e3a7aSWarner Losh 72128e3e3a7aSWarner Losh 72138e3e3a7aSWarner Losh 72148e3e3a7aSWarner Losh 72158e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p> 72168e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 72178e3e3a7aSWarner Losh<pre>int luaL_loadbufferx (lua_State *L, 72188e3e3a7aSWarner Losh const char *buff, 72198e3e3a7aSWarner Losh size_t sz, 72208e3e3a7aSWarner Losh const char *name, 72218e3e3a7aSWarner Losh const char *mode);</pre> 72228e3e3a7aSWarner Losh 72238e3e3a7aSWarner Losh<p> 72248e3e3a7aSWarner LoshLoads a buffer as a Lua chunk. 72258e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the 72268e3e3a7aSWarner Loshbuffer pointed to by <code>buff</code> with size <code>sz</code>. 72278e3e3a7aSWarner Losh 72288e3e3a7aSWarner Losh 72298e3e3a7aSWarner Losh<p> 72308e3e3a7aSWarner LoshThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 72318e3e3a7aSWarner Losh<code>name</code> is the chunk name, 72328e3e3a7aSWarner Loshused for debug information and error messages. 72330495ed39SKyle EvansThe string <code>mode</code> works as in the function <a href="#lua_load"><code>lua_load</code></a>. 72348e3e3a7aSWarner Losh 72358e3e3a7aSWarner Losh 72368e3e3a7aSWarner Losh 72378e3e3a7aSWarner Losh 72388e3e3a7aSWarner Losh 72398e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> 72408e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 72418e3e3a7aSWarner Losh<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> 72428e3e3a7aSWarner Losh 72438e3e3a7aSWarner Losh<p> 72448e3e3a7aSWarner LoshEquivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>. 72458e3e3a7aSWarner Losh 72468e3e3a7aSWarner Losh 72478e3e3a7aSWarner Losh 72488e3e3a7aSWarner Losh 72498e3e3a7aSWarner Losh 72508e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p> 72518e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 72528e3e3a7aSWarner Losh<pre>int luaL_loadfilex (lua_State *L, const char *filename, 72538e3e3a7aSWarner Losh const char *mode);</pre> 72548e3e3a7aSWarner Losh 72558e3e3a7aSWarner Losh<p> 72568e3e3a7aSWarner LoshLoads a file as a Lua chunk. 72578e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file 72588e3e3a7aSWarner Loshnamed <code>filename</code>. 72598e3e3a7aSWarner LoshIf <code>filename</code> is <code>NULL</code>, 72608e3e3a7aSWarner Loshthen it loads from the standard input. 72618e3e3a7aSWarner LoshThe first line in the file is ignored if it starts with a <code>#</code>. 72628e3e3a7aSWarner Losh 72638e3e3a7aSWarner Losh 72648e3e3a7aSWarner Losh<p> 72650495ed39SKyle EvansThe string <code>mode</code> works as in the function <a href="#lua_load"><code>lua_load</code></a>. 72668e3e3a7aSWarner Losh 72678e3e3a7aSWarner Losh 72688e3e3a7aSWarner Losh<p> 72690495ed39SKyle EvansThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a> 72700495ed39SKyle Evansor <a href="#pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> for file-related errors. 72718e3e3a7aSWarner Losh 72728e3e3a7aSWarner Losh 72738e3e3a7aSWarner Losh<p> 72748e3e3a7aSWarner LoshAs <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 72758e3e3a7aSWarner Loshit does not run it. 72768e3e3a7aSWarner Losh 72778e3e3a7aSWarner Losh 72788e3e3a7aSWarner Losh 72798e3e3a7aSWarner Losh 72808e3e3a7aSWarner Losh 72818e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> 72828e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 72838e3e3a7aSWarner Losh<pre>int luaL_loadstring (lua_State *L, const char *s);</pre> 72848e3e3a7aSWarner Losh 72858e3e3a7aSWarner Losh<p> 72868e3e3a7aSWarner LoshLoads a string as a Lua chunk. 72878e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in 72888e3e3a7aSWarner Loshthe zero-terminated string <code>s</code>. 72898e3e3a7aSWarner Losh 72908e3e3a7aSWarner Losh 72918e3e3a7aSWarner Losh<p> 72928e3e3a7aSWarner LoshThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 72938e3e3a7aSWarner Losh 72948e3e3a7aSWarner Losh 72958e3e3a7aSWarner Losh<p> 72968e3e3a7aSWarner LoshAlso as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 72978e3e3a7aSWarner Loshit does not run it. 72988e3e3a7aSWarner Losh 72998e3e3a7aSWarner Losh 73008e3e3a7aSWarner Losh 73018e3e3a7aSWarner Losh 73028e3e3a7aSWarner Losh 73038e3e3a7aSWarner Losh<hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p> 73048e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 73058e3e3a7aSWarner Losh<pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre> 73068e3e3a7aSWarner Losh 73078e3e3a7aSWarner Losh<p> 73088e3e3a7aSWarner LoshCreates a new table and registers there 73090495ed39SKyle Evansthe functions in the list <code>l</code>. 73108e3e3a7aSWarner Losh 73118e3e3a7aSWarner Losh 73128e3e3a7aSWarner Losh<p> 73138e3e3a7aSWarner LoshIt is implemented as the following macro: 73148e3e3a7aSWarner Losh 73158e3e3a7aSWarner Losh<pre> 73168e3e3a7aSWarner Losh (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0)) 73178e3e3a7aSWarner Losh</pre><p> 73188e3e3a7aSWarner LoshThe array <code>l</code> must be the actual array, 73198e3e3a7aSWarner Loshnot a pointer to it. 73208e3e3a7aSWarner Losh 73218e3e3a7aSWarner Losh 73228e3e3a7aSWarner Losh 73238e3e3a7aSWarner Losh 73248e3e3a7aSWarner Losh 73258e3e3a7aSWarner Losh<hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p> 73268e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 73278e3e3a7aSWarner Losh<pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre> 73288e3e3a7aSWarner Losh 73298e3e3a7aSWarner Losh<p> 73308e3e3a7aSWarner LoshCreates a new table with a size optimized 73318e3e3a7aSWarner Loshto store all entries in the array <code>l</code> 73328e3e3a7aSWarner Losh(but does not actually store them). 73338e3e3a7aSWarner LoshIt is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> 73348e3e3a7aSWarner Losh(see <a href="#luaL_newlib"><code>luaL_newlib</code></a>). 73358e3e3a7aSWarner Losh 73368e3e3a7aSWarner Losh 73378e3e3a7aSWarner Losh<p> 73388e3e3a7aSWarner LoshIt is implemented as a macro. 73398e3e3a7aSWarner LoshThe array <code>l</code> must be the actual array, 73408e3e3a7aSWarner Loshnot a pointer to it. 73418e3e3a7aSWarner Losh 73428e3e3a7aSWarner Losh 73438e3e3a7aSWarner Losh 73448e3e3a7aSWarner Losh 73458e3e3a7aSWarner Losh 73468e3e3a7aSWarner Losh<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> 73478e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 73488e3e3a7aSWarner Losh<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> 73498e3e3a7aSWarner Losh 73508e3e3a7aSWarner Losh<p> 73518e3e3a7aSWarner LoshIf the registry already has the key <code>tname</code>, 73528e3e3a7aSWarner Loshreturns 0. 73538e3e3a7aSWarner LoshOtherwise, 73548e3e3a7aSWarner Loshcreates a new table to be used as a metatable for userdata, 73558e3e3a7aSWarner Loshadds to this new table the pair <code>__name = tname</code>, 73568e3e3a7aSWarner Loshadds to the registry the pair <code>[tname] = new table</code>, 73578e3e3a7aSWarner Loshand returns 1. 73588e3e3a7aSWarner Losh 73598e3e3a7aSWarner Losh 73608e3e3a7aSWarner Losh<p> 73610495ed39SKyle EvansIn both cases, 73620495ed39SKyle Evansthe function pushes onto the stack the final value associated 73638e3e3a7aSWarner Loshwith <code>tname</code> in the registry. 73648e3e3a7aSWarner Losh 73658e3e3a7aSWarner Losh 73668e3e3a7aSWarner Losh 73678e3e3a7aSWarner Losh 73688e3e3a7aSWarner Losh 73698e3e3a7aSWarner Losh<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> 73708e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 73718e3e3a7aSWarner Losh<pre>lua_State *luaL_newstate (void);</pre> 73728e3e3a7aSWarner Losh 73738e3e3a7aSWarner Losh<p> 73748e3e3a7aSWarner LoshCreates a new Lua state. 73758e3e3a7aSWarner LoshIt calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an 7376*a9490b81SWarner Loshallocator based on the ISO C allocation functions 73770495ed39SKyle Evansand then sets a warning function and a panic function (see <a href="#4.4">§4.4</a>) 73780495ed39SKyle Evansthat print messages to the standard error output. 73798e3e3a7aSWarner Losh 73808e3e3a7aSWarner Losh 73818e3e3a7aSWarner Losh<p> 73828e3e3a7aSWarner LoshReturns the new state, 73838e3e3a7aSWarner Loshor <code>NULL</code> if there is a memory allocation error. 73848e3e3a7aSWarner Losh 73858e3e3a7aSWarner Losh 73868e3e3a7aSWarner Losh 73878e3e3a7aSWarner Losh 73888e3e3a7aSWarner Losh 73898e3e3a7aSWarner Losh<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> 73908e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 73918e3e3a7aSWarner Losh<pre>void luaL_openlibs (lua_State *L);</pre> 73928e3e3a7aSWarner Losh 73938e3e3a7aSWarner Losh<p> 73948e3e3a7aSWarner LoshOpens all standard Lua libraries into the given state. 73958e3e3a7aSWarner Losh 73968e3e3a7aSWarner Losh 73978e3e3a7aSWarner Losh 73988e3e3a7aSWarner Losh 73998e3e3a7aSWarner Losh 74008e3e3a7aSWarner Losh<hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p> 74010495ed39SKyle Evans<span class="apii">[-0, +0, –]</span> 74028e3e3a7aSWarner Losh<pre>T luaL_opt (L, func, arg, dflt);</pre> 74038e3e3a7aSWarner Losh 74048e3e3a7aSWarner Losh<p> 74058e3e3a7aSWarner LoshThis macro is defined as follows: 74068e3e3a7aSWarner Losh 74078e3e3a7aSWarner Losh<pre> 74088e3e3a7aSWarner Losh (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg))) 74098e3e3a7aSWarner Losh</pre><p> 74108e3e3a7aSWarner LoshIn words, if the argument <code>arg</code> is nil or absent, 74118e3e3a7aSWarner Loshthe macro results in the default <code>dflt</code>. 74128e3e3a7aSWarner LoshOtherwise, it results in the result of calling <code>func</code> 74138e3e3a7aSWarner Loshwith the state <code>L</code> and the argument index <code>arg</code> as 7414e112e9d2SKyle Evansarguments. 74158e3e3a7aSWarner LoshNote that it evaluates the expression <code>dflt</code> only if needed. 74168e3e3a7aSWarner Losh 74178e3e3a7aSWarner Losh 74188e3e3a7aSWarner Losh 74198e3e3a7aSWarner Losh 74208e3e3a7aSWarner Losh 74218e3e3a7aSWarner Losh<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> 74228e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 74238e3e3a7aSWarner Losh<pre>lua_Integer luaL_optinteger (lua_State *L, 74248e3e3a7aSWarner Losh int arg, 74258e3e3a7aSWarner Losh lua_Integer d);</pre> 74268e3e3a7aSWarner Losh 74278e3e3a7aSWarner Losh<p> 74288e3e3a7aSWarner LoshIf the function argument <code>arg</code> is an integer 74290495ed39SKyle Evans(or it is convertible to an integer), 74308e3e3a7aSWarner Loshreturns this integer. 74318e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>, 74328e3e3a7aSWarner Loshreturns <code>d</code>. 74338e3e3a7aSWarner LoshOtherwise, raises an error. 74348e3e3a7aSWarner Losh 74358e3e3a7aSWarner Losh 74368e3e3a7aSWarner Losh 74378e3e3a7aSWarner Losh 74388e3e3a7aSWarner Losh 74398e3e3a7aSWarner Losh<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> 74408e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 74418e3e3a7aSWarner Losh<pre>const char *luaL_optlstring (lua_State *L, 74428e3e3a7aSWarner Losh int arg, 74438e3e3a7aSWarner Losh const char *d, 74448e3e3a7aSWarner Losh size_t *l);</pre> 74458e3e3a7aSWarner Losh 74468e3e3a7aSWarner Losh<p> 74478e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a string, 74488e3e3a7aSWarner Loshreturns this string. 74498e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>, 74508e3e3a7aSWarner Loshreturns <code>d</code>. 74518e3e3a7aSWarner LoshOtherwise, raises an error. 74528e3e3a7aSWarner Losh 74538e3e3a7aSWarner Losh 74548e3e3a7aSWarner Losh<p> 74558e3e3a7aSWarner LoshIf <code>l</code> is not <code>NULL</code>, 74560495ed39SKyle Evansfills its referent with the result's length. 74578e3e3a7aSWarner LoshIf the result is <code>NULL</code> 74588e3e3a7aSWarner Losh(only possible when returning <code>d</code> and <code>d == NULL</code>), 74598e3e3a7aSWarner Loshits length is considered zero. 74608e3e3a7aSWarner Losh 74618e3e3a7aSWarner Losh 74628e3e3a7aSWarner Losh<p> 74638e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 74648e3e3a7aSWarner Loshso all conversions and caveats of that function apply here. 74658e3e3a7aSWarner Losh 74668e3e3a7aSWarner Losh 74678e3e3a7aSWarner Losh 74688e3e3a7aSWarner Losh 74698e3e3a7aSWarner Losh 74708e3e3a7aSWarner Losh<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> 74718e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 74728e3e3a7aSWarner Losh<pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre> 74738e3e3a7aSWarner Losh 74748e3e3a7aSWarner Losh<p> 74758e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a number, 74760495ed39SKyle Evansreturns this number as a <code>lua_Number</code>. 74778e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>, 74788e3e3a7aSWarner Loshreturns <code>d</code>. 74798e3e3a7aSWarner LoshOtherwise, raises an error. 74808e3e3a7aSWarner Losh 74818e3e3a7aSWarner Losh 74828e3e3a7aSWarner Losh 74838e3e3a7aSWarner Losh 74848e3e3a7aSWarner Losh 74858e3e3a7aSWarner Losh<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> 74868e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 74878e3e3a7aSWarner Losh<pre>const char *luaL_optstring (lua_State *L, 74888e3e3a7aSWarner Losh int arg, 74898e3e3a7aSWarner Losh const char *d);</pre> 74908e3e3a7aSWarner Losh 74918e3e3a7aSWarner Losh<p> 74928e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a string, 74938e3e3a7aSWarner Loshreturns this string. 74948e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>, 74958e3e3a7aSWarner Loshreturns <code>d</code>. 74968e3e3a7aSWarner LoshOtherwise, raises an error. 74978e3e3a7aSWarner Losh 74988e3e3a7aSWarner Losh 74998e3e3a7aSWarner Losh 75008e3e3a7aSWarner Losh 75018e3e3a7aSWarner Losh 75028e3e3a7aSWarner Losh<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> 75038e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 75048e3e3a7aSWarner Losh<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> 75058e3e3a7aSWarner Losh 75068e3e3a7aSWarner Losh<p> 75078e3e3a7aSWarner LoshEquivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a> 75088e3e3a7aSWarner Loshwith the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>. 75098e3e3a7aSWarner Losh 75108e3e3a7aSWarner Losh 75118e3e3a7aSWarner Losh 75128e3e3a7aSWarner Losh 75138e3e3a7aSWarner Losh 75148e3e3a7aSWarner Losh<hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p> 75158e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 75168e3e3a7aSWarner Losh<pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre> 75178e3e3a7aSWarner Losh 75188e3e3a7aSWarner Losh<p> 75198e3e3a7aSWarner LoshReturns an address to a space of size <code>sz</code> 75208e3e3a7aSWarner Loshwhere you can copy a string to be added to buffer <code>B</code> 75218e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 75228e3e3a7aSWarner LoshAfter copying the string into this space you must call 75238e3e3a7aSWarner Losh<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add 75248e3e3a7aSWarner Loshit to the buffer. 75258e3e3a7aSWarner Losh 75268e3e3a7aSWarner Losh 75278e3e3a7aSWarner Losh 75288e3e3a7aSWarner Losh 75298e3e3a7aSWarner Losh 75300495ed39SKyle Evans<hr><h3><a name="luaL_pushfail"><code>luaL_pushfail</code></a></h3><p> 75310495ed39SKyle Evans<span class="apii">[-0, +1, –]</span> 75320495ed39SKyle Evans<pre>void luaL_pushfail (lua_State *L);</pre> 75330495ed39SKyle Evans 75340495ed39SKyle Evans<p> 75350495ed39SKyle EvansPushes the <b>fail</b> value onto the stack (see <a href="#6">§6</a>). 75360495ed39SKyle Evans 75370495ed39SKyle Evans 75380495ed39SKyle Evans 75390495ed39SKyle Evans 75400495ed39SKyle Evans 75418e3e3a7aSWarner Losh<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> 75428e3e3a7aSWarner Losh<span class="apii">[-?, +1, <em>m</em>]</span> 75438e3e3a7aSWarner Losh<pre>void luaL_pushresult (luaL_Buffer *B);</pre> 75448e3e3a7aSWarner Losh 75458e3e3a7aSWarner Losh<p> 75468e3e3a7aSWarner LoshFinishes the use of buffer <code>B</code> leaving the final string on 75478e3e3a7aSWarner Loshthe top of the stack. 75488e3e3a7aSWarner Losh 75498e3e3a7aSWarner Losh 75508e3e3a7aSWarner Losh 75518e3e3a7aSWarner Losh 75528e3e3a7aSWarner Losh 75538e3e3a7aSWarner Losh<hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p> 75548e3e3a7aSWarner Losh<span class="apii">[-?, +1, <em>m</em>]</span> 75558e3e3a7aSWarner Losh<pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre> 75568e3e3a7aSWarner Losh 75578e3e3a7aSWarner Losh<p> 75588e3e3a7aSWarner LoshEquivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>. 75598e3e3a7aSWarner Losh 75608e3e3a7aSWarner Losh 75618e3e3a7aSWarner Losh 75628e3e3a7aSWarner Losh 75638e3e3a7aSWarner Losh 75648e3e3a7aSWarner Losh<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> 75658e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span> 75668e3e3a7aSWarner Losh<pre>int luaL_ref (lua_State *L, int t);</pre> 75678e3e3a7aSWarner Losh 75688e3e3a7aSWarner Losh<p> 75698e3e3a7aSWarner LoshCreates and returns a <em>reference</em>, 75708e3e3a7aSWarner Loshin the table at index <code>t</code>, 75710495ed39SKyle Evansfor the object on the top of the stack (and pops the object). 75728e3e3a7aSWarner Losh 75738e3e3a7aSWarner Losh 75748e3e3a7aSWarner Losh<p> 75758e3e3a7aSWarner LoshA reference is a unique integer key. 75760495ed39SKyle EvansAs long as you do not manually add integer keys into the table <code>t</code>, 75778e3e3a7aSWarner Losh<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. 75780495ed39SKyle EvansYou can retrieve an object referred by the reference <code>r</code> 75798e3e3a7aSWarner Loshby calling <code>lua_rawgeti(L, t, r)</code>. 75800495ed39SKyle EvansThe function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference. 75818e3e3a7aSWarner Losh 75828e3e3a7aSWarner Losh 75838e3e3a7aSWarner Losh<p> 75840495ed39SKyle EvansIf the object on the top of the stack is <b>nil</b>, 75858e3e3a7aSWarner Losh<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>. 75868e3e3a7aSWarner LoshThe constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different 75878e3e3a7aSWarner Loshfrom any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. 75888e3e3a7aSWarner Losh 75898e3e3a7aSWarner Losh 75908e3e3a7aSWarner Losh 75918e3e3a7aSWarner Losh 75928e3e3a7aSWarner Losh 75938e3e3a7aSWarner Losh<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> 75948e3e3a7aSWarner Losh<pre>typedef struct luaL_Reg { 75958e3e3a7aSWarner Losh const char *name; 75968e3e3a7aSWarner Losh lua_CFunction func; 75978e3e3a7aSWarner Losh} luaL_Reg;</pre> 75988e3e3a7aSWarner Losh 75998e3e3a7aSWarner Losh<p> 76008e3e3a7aSWarner LoshType for arrays of functions to be registered by 76018e3e3a7aSWarner Losh<a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>. 76028e3e3a7aSWarner Losh<code>name</code> is the function name and <code>func</code> is a pointer to 76038e3e3a7aSWarner Loshthe function. 76048e3e3a7aSWarner LoshAny array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry 76058e3e3a7aSWarner Loshin which both <code>name</code> and <code>func</code> are <code>NULL</code>. 76068e3e3a7aSWarner Losh 76078e3e3a7aSWarner Losh 76088e3e3a7aSWarner Losh 76098e3e3a7aSWarner Losh 76108e3e3a7aSWarner Losh 76118e3e3a7aSWarner Losh<hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p> 76128e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 76138e3e3a7aSWarner Losh<pre>void luaL_requiref (lua_State *L, const char *modname, 76148e3e3a7aSWarner Losh lua_CFunction openf, int glb);</pre> 76158e3e3a7aSWarner Losh 76168e3e3a7aSWarner Losh<p> 76170495ed39SKyle EvansIf <code>package.loaded[modname]</code> is not true, 76180495ed39SKyle Evanscalls the function <code>openf</code> with the string <code>modname</code> as an argument 76190495ed39SKyle Evansand sets the call result to <code>package.loaded[modname]</code>, 76208e3e3a7aSWarner Loshas if that function has been called through <a href="#pdf-require"><code>require</code></a>. 76218e3e3a7aSWarner Losh 76228e3e3a7aSWarner Losh 76238e3e3a7aSWarner Losh<p> 76248e3e3a7aSWarner LoshIf <code>glb</code> is true, 76250495ed39SKyle Evansalso stores the module into the global <code>modname</code>. 76268e3e3a7aSWarner Losh 76278e3e3a7aSWarner Losh 76288e3e3a7aSWarner Losh<p> 76298e3e3a7aSWarner LoshLeaves a copy of the module on the stack. 76308e3e3a7aSWarner Losh 76318e3e3a7aSWarner Losh 76328e3e3a7aSWarner Losh 76338e3e3a7aSWarner Losh 76348e3e3a7aSWarner Losh 76358e3e3a7aSWarner Losh<hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p> 76368e3e3a7aSWarner Losh<span class="apii">[-nup, +0, <em>m</em>]</span> 76378e3e3a7aSWarner Losh<pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre> 76388e3e3a7aSWarner Losh 76398e3e3a7aSWarner Losh<p> 76408e3e3a7aSWarner LoshRegisters all functions in the array <code>l</code> 76418e3e3a7aSWarner Losh(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack 76428e3e3a7aSWarner Losh(below optional upvalues, see next). 76438e3e3a7aSWarner Losh 76448e3e3a7aSWarner Losh 76458e3e3a7aSWarner Losh<p> 76468e3e3a7aSWarner LoshWhen <code>nup</code> is not zero, 76470495ed39SKyle Evansall functions are created with <code>nup</code> upvalues, 76480495ed39SKyle Evansinitialized with copies of the <code>nup</code> values 76490495ed39SKyle Evanspreviously pushed on the stack 76508e3e3a7aSWarner Loshon top of the library table. 76518e3e3a7aSWarner LoshThese values are popped from the stack after the registration. 76528e3e3a7aSWarner Losh 76538e3e3a7aSWarner Losh 76548c784bb8SWarner Losh<p> 76558c784bb8SWarner LoshA function with a <code>NULL</code> value represents a placeholder, 76568c784bb8SWarner Loshwhich is filled with <b>false</b>. 76578c784bb8SWarner Losh 76588c784bb8SWarner Losh 76598e3e3a7aSWarner Losh 76608e3e3a7aSWarner Losh 76618e3e3a7aSWarner Losh 76628e3e3a7aSWarner Losh<hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p> 76638e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 76648e3e3a7aSWarner Losh<pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre> 76658e3e3a7aSWarner Losh 76668e3e3a7aSWarner Losh<p> 76670495ed39SKyle EvansSets the metatable of the object on the top of the stack 76688e3e3a7aSWarner Loshas the metatable associated with name <code>tname</code> 76698e3e3a7aSWarner Loshin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 76708e3e3a7aSWarner Losh 76718e3e3a7aSWarner Losh 76728e3e3a7aSWarner Losh 76738e3e3a7aSWarner Losh 76748e3e3a7aSWarner Losh 76758e3e3a7aSWarner Losh<hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3> 76768e3e3a7aSWarner Losh<pre>typedef struct luaL_Stream { 76778e3e3a7aSWarner Losh FILE *f; 76788e3e3a7aSWarner Losh lua_CFunction closef; 76798e3e3a7aSWarner Losh} luaL_Stream;</pre> 76808e3e3a7aSWarner Losh 76818e3e3a7aSWarner Losh<p> 76820495ed39SKyle EvansThe standard representation for file handles 76830495ed39SKyle Evansused by the standard I/O library. 76848e3e3a7aSWarner Losh 76858e3e3a7aSWarner Losh 76868e3e3a7aSWarner Losh<p> 76878e3e3a7aSWarner LoshA file handle is implemented as a full userdata, 76888e3e3a7aSWarner Loshwith a metatable called <code>LUA_FILEHANDLE</code> 76898e3e3a7aSWarner Losh(where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name). 76908e3e3a7aSWarner LoshThe metatable is created by the I/O library 76918e3e3a7aSWarner Losh(see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 76928e3e3a7aSWarner Losh 76938e3e3a7aSWarner Losh 76948e3e3a7aSWarner Losh<p> 76958e3e3a7aSWarner LoshThis userdata must start with the structure <code>luaL_Stream</code>; 76968e3e3a7aSWarner Loshit can contain other data after this initial structure. 76970495ed39SKyle EvansThe field <code>f</code> points to the corresponding C stream 76988e3e3a7aSWarner Losh(or it can be <code>NULL</code> to indicate an incompletely created handle). 76990495ed39SKyle EvansThe field <code>closef</code> points to a Lua function 77008e3e3a7aSWarner Loshthat will be called to close the stream 77018e3e3a7aSWarner Loshwhen the handle is closed or collected; 77028e3e3a7aSWarner Loshthis function receives the file handle as its sole argument and 77030495ed39SKyle Evansmust return either a true value, in case of success, 77040495ed39SKyle Evansor a false value plus an error message, in case of error. 77058e3e3a7aSWarner LoshOnce Lua calls this field, 77068e3e3a7aSWarner Loshit changes the field value to <code>NULL</code> 77078e3e3a7aSWarner Loshto signal that the handle is closed. 77088e3e3a7aSWarner Losh 77098e3e3a7aSWarner Losh 77108e3e3a7aSWarner Losh 77118e3e3a7aSWarner Losh 77128e3e3a7aSWarner Losh 77138e3e3a7aSWarner Losh<hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p> 77148e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span> 77158e3e3a7aSWarner Losh<pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre> 77168e3e3a7aSWarner Losh 77178e3e3a7aSWarner Losh<p> 77188e3e3a7aSWarner LoshThis function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>, 77198e3e3a7aSWarner Loshexcept that, when the test fails, 77208e3e3a7aSWarner Loshit returns <code>NULL</code> instead of raising an error. 77218e3e3a7aSWarner Losh 77228e3e3a7aSWarner Losh 77238e3e3a7aSWarner Losh 77248e3e3a7aSWarner Losh 77258e3e3a7aSWarner Losh 77268e3e3a7aSWarner Losh<hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p> 77278e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 77288e3e3a7aSWarner Losh<pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre> 77298e3e3a7aSWarner Losh 77308e3e3a7aSWarner Losh<p> 77318e3e3a7aSWarner LoshConverts any Lua value at the given index to a C string 77328e3e3a7aSWarner Loshin a reasonable format. 77338e3e3a7aSWarner LoshThe resulting string is pushed onto the stack and also 77340495ed39SKyle Evansreturned by the function (see <a href="#4.1.3">§4.1.3</a>). 77358e3e3a7aSWarner LoshIf <code>len</code> is not <code>NULL</code>, 77368e3e3a7aSWarner Loshthe function also sets <code>*len</code> with the string length. 77378e3e3a7aSWarner Losh 77388e3e3a7aSWarner Losh 77398e3e3a7aSWarner Losh<p> 77408e3e3a7aSWarner LoshIf the value has a metatable with a <code>__tostring</code> field, 77418e3e3a7aSWarner Loshthen <code>luaL_tolstring</code> calls the corresponding metamethod 77428e3e3a7aSWarner Loshwith the value as argument, 77438e3e3a7aSWarner Loshand uses the result of the call as its result. 77448e3e3a7aSWarner Losh 77458e3e3a7aSWarner Losh 77468e3e3a7aSWarner Losh 77478e3e3a7aSWarner Losh 77488e3e3a7aSWarner Losh 77498e3e3a7aSWarner Losh<hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p> 77508e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 77518e3e3a7aSWarner Losh<pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, 77528e3e3a7aSWarner Losh int level);</pre> 77538e3e3a7aSWarner Losh 77548e3e3a7aSWarner Losh<p> 77558e3e3a7aSWarner LoshCreates and pushes a traceback of the stack <code>L1</code>. 77560495ed39SKyle EvansIf <code>msg</code> is not <code>NULL</code>, it is appended 77578e3e3a7aSWarner Loshat the beginning of the traceback. 77588e3e3a7aSWarner LoshThe <code>level</code> parameter tells at which level 77598e3e3a7aSWarner Loshto start the traceback. 77608e3e3a7aSWarner Losh 77618e3e3a7aSWarner Losh 77628e3e3a7aSWarner Losh 77638e3e3a7aSWarner Losh 77648e3e3a7aSWarner Losh 77650495ed39SKyle Evans<hr><h3><a name="luaL_typeerror"><code>luaL_typeerror</code></a></h3><p> 77660495ed39SKyle Evans<span class="apii">[-0, +0, <em>v</em>]</span> 7767*a9490b81SWarner Losh<pre>int luaL_typeerror (lua_State *L, int arg, const char *tname);</pre> 77680495ed39SKyle Evans 77690495ed39SKyle Evans<p> 77700495ed39SKyle EvansRaises a type error for the argument <code>arg</code> 77710495ed39SKyle Evansof the C function that called it, 77720495ed39SKyle Evansusing a standard message; 77730495ed39SKyle Evans<code>tname</code> is a "name" for the expected type. 77740495ed39SKyle EvansThis function never returns. 77750495ed39SKyle Evans 77760495ed39SKyle Evans 77770495ed39SKyle Evans 77780495ed39SKyle Evans 77790495ed39SKyle Evans 77808e3e3a7aSWarner Losh<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> 77818e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 77828e3e3a7aSWarner Losh<pre>const char *luaL_typename (lua_State *L, int index);</pre> 77838e3e3a7aSWarner Losh 77848e3e3a7aSWarner Losh<p> 77858e3e3a7aSWarner LoshReturns the name of the type of the value at the given index. 77868e3e3a7aSWarner Losh 77878e3e3a7aSWarner Losh 77888e3e3a7aSWarner Losh 77898e3e3a7aSWarner Losh 77908e3e3a7aSWarner Losh 77918e3e3a7aSWarner Losh<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> 77928e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 77938e3e3a7aSWarner Losh<pre>void luaL_unref (lua_State *L, int t, int ref);</pre> 77948e3e3a7aSWarner Losh 77958e3e3a7aSWarner Losh<p> 77960495ed39SKyle EvansReleases the reference <code>ref</code> from the table at index <code>t</code> 77978e3e3a7aSWarner Losh(see <a href="#luaL_ref"><code>luaL_ref</code></a>). 77988e3e3a7aSWarner LoshThe entry is removed from the table, 77998e3e3a7aSWarner Loshso that the referred object can be collected. 78008e3e3a7aSWarner LoshThe reference <code>ref</code> is also freed to be used again. 78018e3e3a7aSWarner Losh 78028e3e3a7aSWarner Losh 78038e3e3a7aSWarner Losh<p> 78048e3e3a7aSWarner 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>, 78058e3e3a7aSWarner Losh<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. 78068e3e3a7aSWarner Losh 78078e3e3a7aSWarner Losh 78088e3e3a7aSWarner Losh 78098e3e3a7aSWarner Losh 78108e3e3a7aSWarner Losh 78118e3e3a7aSWarner Losh<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> 78128e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 78138e3e3a7aSWarner Losh<pre>void luaL_where (lua_State *L, int lvl);</pre> 78148e3e3a7aSWarner Losh 78158e3e3a7aSWarner Losh<p> 78168e3e3a7aSWarner LoshPushes onto the stack a string identifying the current position 78178e3e3a7aSWarner Loshof the control at level <code>lvl</code> in the call stack. 78188e3e3a7aSWarner LoshTypically this string has the following format: 78198e3e3a7aSWarner Losh 78208e3e3a7aSWarner Losh<pre> 78218e3e3a7aSWarner Losh <em>chunkname</em>:<em>currentline</em>: 78228e3e3a7aSWarner Losh</pre><p> 78238e3e3a7aSWarner LoshLevel 0 is the running function, 78248e3e3a7aSWarner Loshlevel 1 is the function that called the running function, 78258e3e3a7aSWarner Loshetc. 78268e3e3a7aSWarner Losh 78278e3e3a7aSWarner Losh 78288e3e3a7aSWarner Losh<p> 78298e3e3a7aSWarner LoshThis function is used to build a prefix for error messages. 78308e3e3a7aSWarner Losh 78318e3e3a7aSWarner Losh 78328e3e3a7aSWarner Losh 78338e3e3a7aSWarner Losh 78348e3e3a7aSWarner Losh 78358e3e3a7aSWarner Losh 78368e3e3a7aSWarner Losh 78370495ed39SKyle Evans<h1>6 – <a name="6">The Standard Libraries</a></h1> 78380495ed39SKyle Evans 78390495ed39SKyle Evans 78408e3e3a7aSWarner Losh 78418e3e3a7aSWarner Losh<p> 78428e3e3a7aSWarner LoshThe standard Lua libraries provide useful functions 78430495ed39SKyle Evansthat are implemented in C through the C API. 78448e3e3a7aSWarner LoshSome of these functions provide essential services to the language 78458e3e3a7aSWarner Losh(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); 78460495ed39SKyle Evansothers provide access to outside services (e.g., I/O); 78478e3e3a7aSWarner Loshand others could be implemented in Lua itself, 78480495ed39SKyle Evansbut that for different reasons 78498e3e3a7aSWarner Loshdeserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). 78508e3e3a7aSWarner Losh 78518e3e3a7aSWarner Losh 78528e3e3a7aSWarner Losh<p> 78538e3e3a7aSWarner LoshAll libraries are implemented through the official C API 78548e3e3a7aSWarner Loshand are provided as separate C modules. 78550495ed39SKyle EvansUnless otherwise noted, 78560495ed39SKyle Evansthese library functions do not adjust its number of arguments 78570495ed39SKyle Evansto its expected parameters. 78580495ed39SKyle EvansFor instance, a function documented as <code>foo(arg)</code> 78590495ed39SKyle Evansshould not be called without an argument. 78600495ed39SKyle Evans 78610495ed39SKyle Evans 78620495ed39SKyle Evans<p> 78630495ed39SKyle EvansThe notation <b>fail</b> means a false value representing 78640495ed39SKyle Evanssome kind of failure. 78650495ed39SKyle Evans(Currently, <b>fail</b> is equal to <b>nil</b>, 78660495ed39SKyle Evansbut that may change in future versions. 78670495ed39SKyle EvansThe recommendation is to always test the success of these functions 78680495ed39SKyle Evanswith <code>(not status)</code>, instead of <code>(status == nil)</code>.) 78690495ed39SKyle Evans 78700495ed39SKyle Evans 78710495ed39SKyle Evans<p> 78728e3e3a7aSWarner LoshCurrently, Lua has the following standard libraries: 78738e3e3a7aSWarner Losh 78748e3e3a7aSWarner Losh<ul> 78758e3e3a7aSWarner Losh 78768e3e3a7aSWarner Losh<li>basic library (<a href="#6.1">§6.1</a>);</li> 78778e3e3a7aSWarner Losh 78788e3e3a7aSWarner Losh<li>coroutine library (<a href="#6.2">§6.2</a>);</li> 78798e3e3a7aSWarner Losh 78808e3e3a7aSWarner Losh<li>package library (<a href="#6.3">§6.3</a>);</li> 78818e3e3a7aSWarner Losh 78828e3e3a7aSWarner Losh<li>string manipulation (<a href="#6.4">§6.4</a>);</li> 78838e3e3a7aSWarner Losh 78848e3e3a7aSWarner Losh<li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li> 78858e3e3a7aSWarner Losh 78868e3e3a7aSWarner Losh<li>table manipulation (<a href="#6.6">§6.6</a>);</li> 78878e3e3a7aSWarner Losh 78888e3e3a7aSWarner Losh<li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li> 78898e3e3a7aSWarner Losh 78908e3e3a7aSWarner Losh<li>input and output (<a href="#6.8">§6.8</a>);</li> 78918e3e3a7aSWarner Losh 78928e3e3a7aSWarner Losh<li>operating system facilities (<a href="#6.9">§6.9</a>);</li> 78938e3e3a7aSWarner Losh 78948e3e3a7aSWarner Losh<li>debug facilities (<a href="#6.10">§6.10</a>).</li> 78958e3e3a7aSWarner Losh 78968e3e3a7aSWarner Losh</ul><p> 78978e3e3a7aSWarner LoshExcept for the basic and the package libraries, 78988e3e3a7aSWarner Losheach library provides all its functions as fields of a global table 78998e3e3a7aSWarner Loshor as methods of its objects. 79008e3e3a7aSWarner Losh 79018e3e3a7aSWarner Losh 79028e3e3a7aSWarner Losh<p> 79038e3e3a7aSWarner LoshTo have access to these libraries, 79048e3e3a7aSWarner Loshthe C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, 79058e3e3a7aSWarner Loshwhich opens all standard libraries. 79068e3e3a7aSWarner LoshAlternatively, 79078e3e3a7aSWarner Loshthe host program can open them individually by using 79088e3e3a7aSWarner Losh<a href="#luaL_requiref"><code>luaL_requiref</code></a> to call 79098e3e3a7aSWarner Losh<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), 79108e3e3a7aSWarner Losh<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), 79118e3e3a7aSWarner Losh<a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library), 79128e3e3a7aSWarner Losh<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), 79130495ed39SKyle Evans<a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF-8 library), 79148e3e3a7aSWarner Losh<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), 79158e3e3a7aSWarner Losh<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), 79168e3e3a7aSWarner Losh<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), 79178e3e3a7aSWarner Losh<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library), 79188e3e3a7aSWarner Loshand <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). 79198e3e3a7aSWarner LoshThese functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>. 79208e3e3a7aSWarner Losh 79218e3e3a7aSWarner Losh 79228e3e3a7aSWarner Losh 79230495ed39SKyle Evans 79240495ed39SKyle Evans 79258e3e3a7aSWarner Losh<h2>6.1 – <a name="6.1">Basic Functions</a></h2> 79268e3e3a7aSWarner Losh 79278e3e3a7aSWarner Losh<p> 79288e3e3a7aSWarner LoshThe basic library provides core functions to Lua. 79298e3e3a7aSWarner LoshIf you do not include this library in your application, 79308e3e3a7aSWarner Loshyou should check carefully whether you need to provide 79318e3e3a7aSWarner Loshimplementations for some of its facilities. 79328e3e3a7aSWarner Losh 79338e3e3a7aSWarner Losh 79348e3e3a7aSWarner Losh<p> 79358e3e3a7aSWarner Losh<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> 79368e3e3a7aSWarner Losh 79378e3e3a7aSWarner Losh 79388e3e3a7aSWarner Losh<p> 79390495ed39SKyle EvansRaises an error if 79408e3e3a7aSWarner Loshthe value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); 79418e3e3a7aSWarner Loshotherwise, returns all its arguments. 79428e3e3a7aSWarner LoshIn case of error, 79438e3e3a7aSWarner Losh<code>message</code> is the error object; 79448e3e3a7aSWarner Loshwhen absent, it defaults to "<code>assertion failed!</code>" 79458e3e3a7aSWarner Losh 79468e3e3a7aSWarner Losh 79478e3e3a7aSWarner Losh 79488e3e3a7aSWarner Losh 79498e3e3a7aSWarner Losh<p> 79508e3e3a7aSWarner Losh<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3> 79518e3e3a7aSWarner Losh 79528e3e3a7aSWarner Losh 79538e3e3a7aSWarner Losh<p> 79548e3e3a7aSWarner LoshThis function is a generic interface to the garbage collector. 79558e3e3a7aSWarner LoshIt performs different functions according to its first argument, <code>opt</code>: 79568e3e3a7aSWarner Losh 79578e3e3a7aSWarner Losh<ul> 79588e3e3a7aSWarner Losh 79598e3e3a7aSWarner Losh<li><b>"<code>collect</code>": </b> 79600495ed39SKyle EvansPerforms a full garbage-collection cycle. 79618e3e3a7aSWarner LoshThis is the default option. 79628e3e3a7aSWarner Losh</li> 79638e3e3a7aSWarner Losh 79648e3e3a7aSWarner Losh<li><b>"<code>stop</code>": </b> 79650495ed39SKyle EvansStops automatic execution of the garbage collector. 79668e3e3a7aSWarner LoshThe collector will run only when explicitly invoked, 79678e3e3a7aSWarner Loshuntil a call to restart it. 79688e3e3a7aSWarner Losh</li> 79698e3e3a7aSWarner Losh 79708e3e3a7aSWarner Losh<li><b>"<code>restart</code>": </b> 79710495ed39SKyle EvansRestarts automatic execution of the garbage collector. 79728e3e3a7aSWarner Losh</li> 79738e3e3a7aSWarner Losh 79748e3e3a7aSWarner Losh<li><b>"<code>count</code>": </b> 79750495ed39SKyle EvansReturns the total memory in use by Lua in Kbytes. 79768e3e3a7aSWarner LoshThe value has a fractional part, 79778e3e3a7aSWarner Loshso that it multiplied by 1024 79780495ed39SKyle Evansgives the exact number of bytes in use by Lua. 79798e3e3a7aSWarner Losh</li> 79808e3e3a7aSWarner Losh 79818e3e3a7aSWarner Losh<li><b>"<code>step</code>": </b> 79820495ed39SKyle EvansPerforms a garbage-collection step. 79838e3e3a7aSWarner LoshThe step "size" is controlled by <code>arg</code>. 79848e3e3a7aSWarner LoshWith a zero value, 79858e3e3a7aSWarner Loshthe collector will perform one basic (indivisible) step. 79868e3e3a7aSWarner LoshFor non-zero values, 79878e3e3a7aSWarner Loshthe collector will perform as if that amount of memory 79880495ed39SKyle Evans(in Kbytes) had been allocated by Lua. 79898e3e3a7aSWarner LoshReturns <b>true</b> if the step finished a collection cycle. 79908e3e3a7aSWarner Losh</li> 79918e3e3a7aSWarner Losh 79928e3e3a7aSWarner Losh<li><b>"<code>isrunning</code>": </b> 79930495ed39SKyle EvansReturns a boolean that tells whether the collector is running 79948e3e3a7aSWarner Losh(i.e., not stopped). 79958e3e3a7aSWarner Losh</li> 79968e3e3a7aSWarner Losh 79970495ed39SKyle Evans<li><b>"<code>incremental</code>": </b> 79980495ed39SKyle EvansChange the collector mode to incremental. 79990495ed39SKyle EvansThis option can be followed by three numbers: 80000495ed39SKyle Evansthe garbage-collector pause, 80010495ed39SKyle Evansthe step multiplier, 80020495ed39SKyle Evansand the step size (see <a href="#2.5.1">§2.5.1</a>). 80030495ed39SKyle EvansA zero means to not change that value. 80040495ed39SKyle Evans</li> 80050495ed39SKyle Evans 80060495ed39SKyle Evans<li><b>"<code>generational</code>": </b> 80070495ed39SKyle EvansChange the collector mode to generational. 80080495ed39SKyle EvansThis option can be followed by two numbers: 80090495ed39SKyle Evansthe garbage-collector minor multiplier 80100495ed39SKyle Evansand the major multiplier (see <a href="#2.5.2">§2.5.2</a>). 80110495ed39SKyle EvansA zero means to not change that value. 80120495ed39SKyle Evans</li> 80130495ed39SKyle Evans 80140495ed39SKyle Evans</ul><p> 80150495ed39SKyle EvansSee <a href="#2.5">§2.5</a> for more details about garbage collection 80160495ed39SKyle Evansand some of these options. 80170495ed39SKyle Evans 80188e3e3a7aSWarner Losh 80198c784bb8SWarner Losh<p> 80208c784bb8SWarner LoshThis function should not be called by a finalizer. 80218c784bb8SWarner Losh 80228c784bb8SWarner Losh 80238e3e3a7aSWarner Losh 80248e3e3a7aSWarner Losh 80258e3e3a7aSWarner Losh<p> 80268e3e3a7aSWarner Losh<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> 80270495ed39SKyle EvansOpens the named file and executes its content as a Lua chunk. 80288e3e3a7aSWarner LoshWhen called without arguments, 80290495ed39SKyle Evans<code>dofile</code> executes the content of the standard input (<code>stdin</code>). 80308e3e3a7aSWarner LoshReturns all values returned by the chunk. 80318e3e3a7aSWarner LoshIn case of errors, <code>dofile</code> propagates the error 80320495ed39SKyle Evansto its caller. 80330495ed39SKyle Evans(That is, <code>dofile</code> does not run in protected mode.) 80348e3e3a7aSWarner Losh 80358e3e3a7aSWarner Losh 80368e3e3a7aSWarner Losh 80378e3e3a7aSWarner Losh 80388e3e3a7aSWarner Losh<p> 80398e3e3a7aSWarner Losh<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> 80408c784bb8SWarner LoshRaises an error (see <a href="#2.3">§2.3</a>) with <code>message</code> as the error object. 80410495ed39SKyle EvansThis function never returns. 80428e3e3a7aSWarner Losh 80438e3e3a7aSWarner Losh 80448e3e3a7aSWarner Losh<p> 80458e3e3a7aSWarner LoshUsually, <code>error</code> adds some information about the error position 80468e3e3a7aSWarner Loshat the beginning of the message, if the message is a string. 80478e3e3a7aSWarner LoshThe <code>level</code> argument specifies how to get the error position. 80488e3e3a7aSWarner LoshWith level 1 (the default), the error position is where the 80498e3e3a7aSWarner Losh<code>error</code> function was called. 80508e3e3a7aSWarner LoshLevel 2 points the error to where the function 80518e3e3a7aSWarner Loshthat called <code>error</code> was called; and so on. 80528e3e3a7aSWarner LoshPassing a level 0 avoids the addition of error position information 80538e3e3a7aSWarner Loshto the message. 80548e3e3a7aSWarner Losh 80558e3e3a7aSWarner Losh 80568e3e3a7aSWarner Losh 80578e3e3a7aSWarner Losh 80588e3e3a7aSWarner Losh<p> 80598e3e3a7aSWarner Losh<hr><h3><a name="pdf-_G"><code>_G</code></a></h3> 80608e3e3a7aSWarner LoshA global variable (not a function) that 80618e3e3a7aSWarner Loshholds the global environment (see <a href="#2.2">§2.2</a>). 80628e3e3a7aSWarner LoshLua itself does not use this variable; 80638e3e3a7aSWarner Loshchanging its value does not affect any environment, 80648e3e3a7aSWarner Loshnor vice versa. 80658e3e3a7aSWarner Losh 80668e3e3a7aSWarner Losh 80678e3e3a7aSWarner Losh 80688e3e3a7aSWarner Losh 80698e3e3a7aSWarner Losh<p> 80708e3e3a7aSWarner Losh<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> 80718e3e3a7aSWarner Losh 80728e3e3a7aSWarner Losh 80738e3e3a7aSWarner Losh<p> 80748e3e3a7aSWarner LoshIf <code>object</code> does not have a metatable, returns <b>nil</b>. 80758e3e3a7aSWarner LoshOtherwise, 80768e3e3a7aSWarner Loshif the object's metatable has a <code>__metatable</code> field, 80778e3e3a7aSWarner Loshreturns the associated value. 80788e3e3a7aSWarner LoshOtherwise, returns the metatable of the given object. 80798e3e3a7aSWarner Losh 80808e3e3a7aSWarner Losh 80818e3e3a7aSWarner Losh 80828e3e3a7aSWarner Losh 80838e3e3a7aSWarner Losh<p> 80848e3e3a7aSWarner Losh<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> 80858e3e3a7aSWarner Losh 80868e3e3a7aSWarner Losh 80878e3e3a7aSWarner Losh<p> 80888e3e3a7aSWarner LoshReturns three values (an iterator function, the table <code>t</code>, and 0) 80898e3e3a7aSWarner Loshso that the construction 80908e3e3a7aSWarner Losh 80918e3e3a7aSWarner Losh<pre> 80928e3e3a7aSWarner Losh for i,v in ipairs(t) do <em>body</em> end 80938e3e3a7aSWarner Losh</pre><p> 80948e3e3a7aSWarner Loshwill iterate over the key–value pairs 80958e3e3a7aSWarner Losh(<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., 80960495ed39SKyle Evansup to the first absent index. 80978e3e3a7aSWarner Losh 80988e3e3a7aSWarner Losh 80998e3e3a7aSWarner Losh 81008e3e3a7aSWarner Losh 81018e3e3a7aSWarner Losh<p> 81028e3e3a7aSWarner Losh<hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3> 81038e3e3a7aSWarner Losh 81048e3e3a7aSWarner Losh 81058e3e3a7aSWarner Losh<p> 81068e3e3a7aSWarner LoshLoads a chunk. 81078e3e3a7aSWarner Losh 81088e3e3a7aSWarner Losh 81098e3e3a7aSWarner Losh<p> 81108e3e3a7aSWarner LoshIf <code>chunk</code> is a string, the chunk is this string. 81118e3e3a7aSWarner LoshIf <code>chunk</code> is a function, 81128e3e3a7aSWarner Losh<code>load</code> calls it repeatedly to get the chunk pieces. 81138e3e3a7aSWarner LoshEach call to <code>chunk</code> must return a string that concatenates 81148e3e3a7aSWarner Loshwith previous results. 81158e3e3a7aSWarner LoshA return of an empty string, <b>nil</b>, or no value signals the end of the chunk. 81168e3e3a7aSWarner Losh 81178e3e3a7aSWarner Losh 81188e3e3a7aSWarner Losh<p> 81198e3e3a7aSWarner LoshIf there are no syntactic errors, 81200495ed39SKyle Evans<code>load</code> returns the compiled chunk as a function; 81210495ed39SKyle Evansotherwise, it returns <b>fail</b> plus the error message. 81228e3e3a7aSWarner Losh 81238e3e3a7aSWarner Losh 81248e3e3a7aSWarner Losh<p> 81250495ed39SKyle EvansWhen you load a main chunk, 81268e3e3a7aSWarner Loshthe resulting function will always have exactly one upvalue, 81278e3e3a7aSWarner Loshthe <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 81288e3e3a7aSWarner LoshHowever, 81298e3e3a7aSWarner Loshwhen you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>), 81300495ed39SKyle Evansthe resulting function can have an arbitrary number of upvalues, 81310495ed39SKyle Evansand there is no guarantee that its first upvalue will be 81320495ed39SKyle Evansthe <code>_ENV</code> variable. 81330495ed39SKyle Evans(A non-main function may not even have an <code>_ENV</code> upvalue.) 81340495ed39SKyle Evans 81350495ed39SKyle Evans 81360495ed39SKyle Evans<p> 81370495ed39SKyle EvansRegardless, if the resulting function has any upvalues, 81380495ed39SKyle Evansits first upvalue is set to the value of <code>env</code>, 81390495ed39SKyle Evansif that parameter is given, 81400495ed39SKyle Evansor to the value of the global environment. 81410495ed39SKyle EvansOther upvalues are initialized with <b>nil</b>. 81428e3e3a7aSWarner LoshAll upvalues are fresh, that is, 81438e3e3a7aSWarner Loshthey are not shared with any other function. 81448e3e3a7aSWarner Losh 81458e3e3a7aSWarner Losh 81468e3e3a7aSWarner Losh<p> 81478e3e3a7aSWarner Losh<code>chunkname</code> is used as the name of the chunk for error messages 81480495ed39SKyle Evansand debug information (see <a href="#4.7">§4.7</a>). 81498e3e3a7aSWarner LoshWhen absent, 81508e3e3a7aSWarner Loshit defaults to <code>chunk</code>, if <code>chunk</code> is a string, 81518e3e3a7aSWarner Loshor to "<code>=(load)</code>" otherwise. 81528e3e3a7aSWarner Losh 81538e3e3a7aSWarner Losh 81548e3e3a7aSWarner Losh<p> 81558e3e3a7aSWarner LoshThe string <code>mode</code> controls whether the chunk can be text or binary 81568e3e3a7aSWarner Losh(that is, a precompiled chunk). 81578e3e3a7aSWarner LoshIt may be the string "<code>b</code>" (only binary chunks), 81588e3e3a7aSWarner Losh"<code>t</code>" (only text chunks), 81598e3e3a7aSWarner Loshor "<code>bt</code>" (both binary and text). 81608e3e3a7aSWarner LoshThe default is "<code>bt</code>". 81618e3e3a7aSWarner Losh 81628e3e3a7aSWarner Losh 81638e3e3a7aSWarner Losh<p> 81640495ed39SKyle EvansIt is safe to load malformed binary chunks; 81650495ed39SKyle Evans<code>load</code> signals an appropriate error. 81660495ed39SKyle EvansHowever, 81670495ed39SKyle EvansLua does not check the consistency of the code inside binary chunks; 81680495ed39SKyle Evansrunning maliciously crafted bytecode can crash the interpreter. 81698e3e3a7aSWarner Losh 81708e3e3a7aSWarner Losh 81718e3e3a7aSWarner Losh 81728e3e3a7aSWarner Losh 81738e3e3a7aSWarner Losh<p> 81748e3e3a7aSWarner Losh<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3> 81758e3e3a7aSWarner Losh 81768e3e3a7aSWarner Losh 81778e3e3a7aSWarner Losh<p> 81788e3e3a7aSWarner LoshSimilar to <a href="#pdf-load"><code>load</code></a>, 81798e3e3a7aSWarner Loshbut gets the chunk from file <code>filename</code> 81808e3e3a7aSWarner Loshor from the standard input, 81818e3e3a7aSWarner Loshif no file name is given. 81828e3e3a7aSWarner Losh 81838e3e3a7aSWarner Losh 81848e3e3a7aSWarner Losh 81858e3e3a7aSWarner Losh 81868e3e3a7aSWarner Losh<p> 81878e3e3a7aSWarner Losh<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> 81888e3e3a7aSWarner Losh 81898e3e3a7aSWarner Losh 81908e3e3a7aSWarner Losh<p> 81918e3e3a7aSWarner LoshAllows a program to traverse all fields of a table. 81928e3e3a7aSWarner LoshIts first argument is a table and its second argument 81938e3e3a7aSWarner Loshis an index in this table. 81940495ed39SKyle EvansA call to <code>next</code> returns the next index of the table 81958e3e3a7aSWarner Loshand its associated value. 81968e3e3a7aSWarner LoshWhen called with <b>nil</b> as its second argument, 81978e3e3a7aSWarner Losh<code>next</code> returns an initial index 81988e3e3a7aSWarner Loshand its associated value. 81998e3e3a7aSWarner LoshWhen called with the last index, 82008e3e3a7aSWarner Loshor with <b>nil</b> in an empty table, 82018e3e3a7aSWarner Losh<code>next</code> returns <b>nil</b>. 82028e3e3a7aSWarner LoshIf the second argument is absent, then it is interpreted as <b>nil</b>. 82038e3e3a7aSWarner LoshIn particular, 82048e3e3a7aSWarner Loshyou can use <code>next(t)</code> to check whether a table is empty. 82058e3e3a7aSWarner Losh 82068e3e3a7aSWarner Losh 82078e3e3a7aSWarner Losh<p> 82088e3e3a7aSWarner LoshThe order in which the indices are enumerated is not specified, 82098e3e3a7aSWarner Losh<em>even for numeric indices</em>. 82108e3e3a7aSWarner Losh(To traverse a table in numerical order, 82118e3e3a7aSWarner Loshuse a numerical <b>for</b>.) 82128e3e3a7aSWarner Losh 82138e3e3a7aSWarner Losh 82148e3e3a7aSWarner Losh<p> 82158c784bb8SWarner LoshYou should not assign any value to a non-existent field in a table 82168c784bb8SWarner Loshduring its traversal. 82178e3e3a7aSWarner LoshYou may however modify existing fields. 82180495ed39SKyle EvansIn particular, you may set existing fields to nil. 82198e3e3a7aSWarner Losh 82208e3e3a7aSWarner Losh 82218e3e3a7aSWarner Losh 82228e3e3a7aSWarner Losh 82238e3e3a7aSWarner Losh<p> 82248e3e3a7aSWarner Losh<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> 82258e3e3a7aSWarner Losh 82268e3e3a7aSWarner Losh 82278e3e3a7aSWarner Losh<p> 82288e3e3a7aSWarner LoshIf <code>t</code> has a metamethod <code>__pairs</code>, 82298e3e3a7aSWarner Loshcalls it with <code>t</code> as argument and returns the first three 82308e3e3a7aSWarner Loshresults from the call. 82318e3e3a7aSWarner Losh 82328e3e3a7aSWarner Losh 82338e3e3a7aSWarner Losh<p> 82348e3e3a7aSWarner LoshOtherwise, 82358e3e3a7aSWarner Loshreturns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, 82368e3e3a7aSWarner Loshso that the construction 82378e3e3a7aSWarner Losh 82388e3e3a7aSWarner Losh<pre> 82398e3e3a7aSWarner Losh for k,v in pairs(t) do <em>body</em> end 82408e3e3a7aSWarner Losh</pre><p> 82418e3e3a7aSWarner Loshwill iterate over all key–value pairs of table <code>t</code>. 82428e3e3a7aSWarner Losh 82438e3e3a7aSWarner Losh 82448e3e3a7aSWarner Losh<p> 82458e3e3a7aSWarner LoshSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 82468e3e3a7aSWarner Loshthe table during its traversal. 82478e3e3a7aSWarner Losh 82488e3e3a7aSWarner Losh 82498e3e3a7aSWarner Losh 82508e3e3a7aSWarner Losh 82518e3e3a7aSWarner Losh<p> 82528e3e3a7aSWarner Losh<hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3> 82538e3e3a7aSWarner Losh 82548e3e3a7aSWarner Losh 82558e3e3a7aSWarner Losh<p> 82560495ed39SKyle EvansCalls the function <code>f</code> with 82578e3e3a7aSWarner Loshthe given arguments in <em>protected mode</em>. 82588e3e3a7aSWarner LoshThis means that any error inside <code>f</code> is not propagated; 82598e3e3a7aSWarner Loshinstead, <code>pcall</code> catches the error 82608e3e3a7aSWarner Loshand returns a status code. 82618e3e3a7aSWarner LoshIts first result is the status code (a boolean), 82628c784bb8SWarner Loshwhich is <b>true</b> if the call succeeds without errors. 82638e3e3a7aSWarner LoshIn such case, <code>pcall</code> also returns all results from the call, 82648e3e3a7aSWarner Loshafter this first result. 82650495ed39SKyle EvansIn case of any error, <code>pcall</code> returns <b>false</b> plus the error object. 82660495ed39SKyle EvansNote that errors caught by <code>pcall</code> do not call a message handler. 82678e3e3a7aSWarner Losh 82688e3e3a7aSWarner Losh 82698e3e3a7aSWarner Losh 82708e3e3a7aSWarner Losh 82718e3e3a7aSWarner Losh<p> 82728e3e3a7aSWarner Losh<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> 82738e3e3a7aSWarner LoshReceives any number of arguments 82748e3e3a7aSWarner Loshand prints their values to <code>stdout</code>, 82750495ed39SKyle Evansconverting each argument to a string 82760495ed39SKyle Evansfollowing the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 82770495ed39SKyle Evans 82780495ed39SKyle Evans 82790495ed39SKyle Evans<p> 82800495ed39SKyle EvansThe function <code>print</code> is not intended for formatted output, 82818e3e3a7aSWarner Loshbut only as a quick way to show a value, 82828e3e3a7aSWarner Loshfor instance for debugging. 82838e3e3a7aSWarner LoshFor complete control over the output, 82848e3e3a7aSWarner Loshuse <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. 82858e3e3a7aSWarner Losh 82868e3e3a7aSWarner Losh 82878e3e3a7aSWarner Losh 82888e3e3a7aSWarner Losh 82898e3e3a7aSWarner Losh<p> 82908e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> 82918e3e3a7aSWarner LoshChecks whether <code>v1</code> is equal to <code>v2</code>, 82928e3e3a7aSWarner Loshwithout invoking the <code>__eq</code> metamethod. 82938e3e3a7aSWarner LoshReturns a boolean. 82948e3e3a7aSWarner Losh 82958e3e3a7aSWarner Losh 82968e3e3a7aSWarner Losh 82978e3e3a7aSWarner Losh 82988e3e3a7aSWarner Losh<p> 82998e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> 83008e3e3a7aSWarner LoshGets the real value of <code>table[index]</code>, 83010495ed39SKyle Evanswithout using the <code>__index</code> metavalue. 83028e3e3a7aSWarner Losh<code>table</code> must be a table; 83038e3e3a7aSWarner Losh<code>index</code> may be any value. 83048e3e3a7aSWarner Losh 83058e3e3a7aSWarner Losh 83068e3e3a7aSWarner Losh 83078e3e3a7aSWarner Losh 83088e3e3a7aSWarner Losh<p> 83098e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3> 83108e3e3a7aSWarner LoshReturns the length of the object <code>v</code>, 83118e3e3a7aSWarner Loshwhich must be a table or a string, 83128e3e3a7aSWarner Loshwithout invoking the <code>__len</code> metamethod. 83138e3e3a7aSWarner LoshReturns an integer. 83148e3e3a7aSWarner Losh 83158e3e3a7aSWarner Losh 83168e3e3a7aSWarner Losh 83178e3e3a7aSWarner Losh 83188e3e3a7aSWarner Losh<p> 83198e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> 83208e3e3a7aSWarner LoshSets the real value of <code>table[index]</code> to <code>value</code>, 83210495ed39SKyle Evanswithout using the <code>__newindex</code> metavalue. 83228e3e3a7aSWarner Losh<code>table</code> must be a table, 83238e3e3a7aSWarner Losh<code>index</code> any value different from <b>nil</b> and NaN, 83248e3e3a7aSWarner Loshand <code>value</code> any Lua value. 83258e3e3a7aSWarner Losh 83268e3e3a7aSWarner Losh 83278e3e3a7aSWarner Losh<p> 83288e3e3a7aSWarner LoshThis function returns <code>table</code>. 83298e3e3a7aSWarner Losh 83308e3e3a7aSWarner Losh 83318e3e3a7aSWarner Losh 83328e3e3a7aSWarner Losh 83338e3e3a7aSWarner Losh<p> 83348e3e3a7aSWarner Losh<hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> 83358e3e3a7aSWarner Losh 83368e3e3a7aSWarner Losh 83378e3e3a7aSWarner Losh<p> 83388e3e3a7aSWarner LoshIf <code>index</code> is a number, 83398e3e3a7aSWarner Loshreturns all arguments after argument number <code>index</code>; 83408e3e3a7aSWarner Losha negative number indexes from the end (-1 is the last argument). 83418e3e3a7aSWarner LoshOtherwise, <code>index</code> must be the string <code>"#"</code>, 83428e3e3a7aSWarner Loshand <code>select</code> returns the total number of extra arguments it received. 83438e3e3a7aSWarner Losh 83448e3e3a7aSWarner Losh 83458e3e3a7aSWarner Losh 83468e3e3a7aSWarner Losh 83478e3e3a7aSWarner Losh<p> 83488e3e3a7aSWarner Losh<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> 83498e3e3a7aSWarner Losh 83508e3e3a7aSWarner Losh 83518e3e3a7aSWarner Losh<p> 83528e3e3a7aSWarner LoshSets the metatable for the given table. 83538e3e3a7aSWarner LoshIf <code>metatable</code> is <b>nil</b>, 83548e3e3a7aSWarner Loshremoves the metatable of the given table. 83558e3e3a7aSWarner LoshIf the original metatable has a <code>__metatable</code> field, 83568e3e3a7aSWarner Loshraises an error. 83578e3e3a7aSWarner Losh 83588e3e3a7aSWarner Losh 83598e3e3a7aSWarner Losh<p> 83608e3e3a7aSWarner LoshThis function returns <code>table</code>. 83618e3e3a7aSWarner Losh 83628e3e3a7aSWarner Losh 83630495ed39SKyle Evans<p> 83640495ed39SKyle EvansTo change the metatable of other types from Lua code, 83650495ed39SKyle Evansyou must use the debug library (<a href="#6.10">§6.10</a>). 83660495ed39SKyle Evans 83670495ed39SKyle Evans 83688e3e3a7aSWarner Losh 83698e3e3a7aSWarner Losh 83708e3e3a7aSWarner Losh<p> 83718e3e3a7aSWarner Losh<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> 83728e3e3a7aSWarner Losh 83738e3e3a7aSWarner Losh 83748e3e3a7aSWarner Losh<p> 83758e3e3a7aSWarner LoshWhen called with no <code>base</code>, 83768e3e3a7aSWarner Losh<code>tonumber</code> tries to convert its argument to a number. 83778e3e3a7aSWarner LoshIf the argument is already a number or 83788e3e3a7aSWarner Losha string convertible to a number, 83798e3e3a7aSWarner Loshthen <code>tonumber</code> returns this number; 83800495ed39SKyle Evansotherwise, it returns <b>fail</b>. 83818e3e3a7aSWarner Losh 83828e3e3a7aSWarner Losh 83838e3e3a7aSWarner Losh<p> 83848e3e3a7aSWarner LoshThe conversion of strings can result in integers or floats, 83858e3e3a7aSWarner Loshaccording to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 83860495ed39SKyle EvansThe string may have leading and trailing spaces and a sign. 83878e3e3a7aSWarner Losh 83888e3e3a7aSWarner Losh 83898e3e3a7aSWarner Losh<p> 83908e3e3a7aSWarner LoshWhen called with <code>base</code>, 83918e3e3a7aSWarner Loshthen <code>e</code> must be a string to be interpreted as 83928e3e3a7aSWarner Loshan integer numeral in that base. 83938e3e3a7aSWarner LoshThe base may be any integer between 2 and 36, inclusive. 83948e3e3a7aSWarner LoshIn bases above 10, the letter '<code>A</code>' (in either upper or lower case) 83958e3e3a7aSWarner Loshrepresents 10, '<code>B</code>' represents 11, and so forth, 83968e3e3a7aSWarner Loshwith '<code>Z</code>' representing 35. 83978e3e3a7aSWarner LoshIf the string <code>e</code> is not a valid numeral in the given base, 83980495ed39SKyle Evansthe function returns <b>fail</b>. 83998e3e3a7aSWarner Losh 84008e3e3a7aSWarner Losh 84018e3e3a7aSWarner Losh 84028e3e3a7aSWarner Losh 84038e3e3a7aSWarner Losh<p> 84048e3e3a7aSWarner Losh<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3> 84050495ed39SKyle Evans 84060495ed39SKyle Evans 84070495ed39SKyle Evans<p> 84088e3e3a7aSWarner LoshReceives a value of any type and 84098e3e3a7aSWarner Loshconverts it to a string in a human-readable format. 84108e3e3a7aSWarner Losh 84118e3e3a7aSWarner Losh 84128e3e3a7aSWarner Losh<p> 84138e3e3a7aSWarner LoshIf the metatable of <code>v</code> has a <code>__tostring</code> field, 84148e3e3a7aSWarner Loshthen <code>tostring</code> calls the corresponding value 84158e3e3a7aSWarner Loshwith <code>v</code> as argument, 84168e3e3a7aSWarner Loshand uses the result of the call as its result. 84170495ed39SKyle EvansOtherwise, if the metatable of <code>v</code> has a <code>__name</code> field 84180495ed39SKyle Evanswith a string value, 84190495ed39SKyle Evans<code>tostring</code> may use that string in its final result. 84200495ed39SKyle Evans 84210495ed39SKyle Evans 84220495ed39SKyle Evans<p> 84230495ed39SKyle EvansFor complete control of how numbers are converted, 84240495ed39SKyle Evansuse <a href="#pdf-string.format"><code>string.format</code></a>. 84258e3e3a7aSWarner Losh 84268e3e3a7aSWarner Losh 84278e3e3a7aSWarner Losh 84288e3e3a7aSWarner Losh 84298e3e3a7aSWarner Losh<p> 84308e3e3a7aSWarner Losh<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> 84310495ed39SKyle Evans 84320495ed39SKyle Evans 84330495ed39SKyle Evans<p> 84348e3e3a7aSWarner LoshReturns the type of its only argument, coded as a string. 84358e3e3a7aSWarner LoshThe possible results of this function are 84368e3e3a7aSWarner Losh"<code>nil</code>" (a string, not the value <b>nil</b>), 84378e3e3a7aSWarner Losh"<code>number</code>", 84388e3e3a7aSWarner Losh"<code>string</code>", 84398e3e3a7aSWarner Losh"<code>boolean</code>", 84408e3e3a7aSWarner Losh"<code>table</code>", 84418e3e3a7aSWarner Losh"<code>function</code>", 84428e3e3a7aSWarner Losh"<code>thread</code>", 84438e3e3a7aSWarner Loshand "<code>userdata</code>". 84448e3e3a7aSWarner Losh 84458e3e3a7aSWarner Losh 84468e3e3a7aSWarner Losh 84478e3e3a7aSWarner Losh 84488e3e3a7aSWarner Losh<p> 84498e3e3a7aSWarner Losh<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> 84508e3e3a7aSWarner Losh 84518e3e3a7aSWarner Losh 84528e3e3a7aSWarner Losh<p> 84538e3e3a7aSWarner LoshA global variable (not a function) that 84548e3e3a7aSWarner Loshholds a string containing the running Lua version. 84550495ed39SKyle EvansThe current value of this variable is "<code>Lua 5.4</code>". 84560495ed39SKyle Evans 84570495ed39SKyle Evans 84580495ed39SKyle Evans 84590495ed39SKyle Evans 84600495ed39SKyle Evans<p> 84610495ed39SKyle Evans<hr><h3><a name="pdf-warn"><code>warn (msg1, ···)</code></a></h3> 84620495ed39SKyle Evans 84630495ed39SKyle Evans 84640495ed39SKyle Evans<p> 84650495ed39SKyle EvansEmits a warning with a message composed by the concatenation 84660495ed39SKyle Evansof all its arguments (which should be strings). 84670495ed39SKyle Evans 84680495ed39SKyle Evans 84690495ed39SKyle Evans<p> 84700495ed39SKyle EvansBy convention, 84710495ed39SKyle Evansa one-piece message starting with '<code>@</code>' 84720495ed39SKyle Evansis intended to be a <em>control message</em>, 84730495ed39SKyle Evanswhich is a message to the warning system itself. 84740495ed39SKyle EvansIn particular, the standard warning function in Lua 84750495ed39SKyle Evansrecognizes the control messages "<code>@off</code>", 84760495ed39SKyle Evansto stop the emission of warnings, 84770495ed39SKyle Evansand "<code>@on</code>", to (re)start the emission; 84780495ed39SKyle Evansit ignores unknown control messages. 84798e3e3a7aSWarner Losh 84808e3e3a7aSWarner Losh 84818e3e3a7aSWarner Losh 84828e3e3a7aSWarner Losh 84838e3e3a7aSWarner Losh<p> 84848e3e3a7aSWarner Losh<hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3> 84858e3e3a7aSWarner Losh 84868e3e3a7aSWarner Losh 84878e3e3a7aSWarner Losh<p> 84888e3e3a7aSWarner LoshThis function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, 84898e3e3a7aSWarner Loshexcept that it sets a new message handler <code>msgh</code>. 84908e3e3a7aSWarner Losh 84918e3e3a7aSWarner Losh 84928e3e3a7aSWarner Losh 84938e3e3a7aSWarner Losh 84948e3e3a7aSWarner Losh 84958e3e3a7aSWarner Losh 84968e3e3a7aSWarner Losh 84978e3e3a7aSWarner Losh<h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2> 84988e3e3a7aSWarner Losh 84998e3e3a7aSWarner Losh<p> 85008e3e3a7aSWarner LoshThis library comprises the operations to manipulate coroutines, 85018e3e3a7aSWarner Loshwhich come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. 85028e3e3a7aSWarner LoshSee <a href="#2.6">§2.6</a> for a general description of coroutines. 85038e3e3a7aSWarner Losh 85048e3e3a7aSWarner Losh 85058e3e3a7aSWarner Losh<p> 85060495ed39SKyle Evans<hr><h3><a name="pdf-coroutine.close"><code>coroutine.close (co)</code></a></h3> 85070495ed39SKyle Evans 85080495ed39SKyle Evans 85090495ed39SKyle Evans<p> 85100495ed39SKyle EvansCloses coroutine <code>co</code>, 85110495ed39SKyle Evansthat is, 85120495ed39SKyle Evanscloses all its pending to-be-closed variables 85130495ed39SKyle Evansand puts the coroutine in a dead state. 85140495ed39SKyle EvansThe given coroutine must be dead or suspended. 85158c784bb8SWarner LoshIn case of error 85168c784bb8SWarner Losh(either the original error that stopped the coroutine or 85178c784bb8SWarner Losherrors in closing methods), 85180495ed39SKyle Evansreturns <b>false</b> plus the error object; 85190495ed39SKyle Evansotherwise returns <b>true</b>. 85200495ed39SKyle Evans 85210495ed39SKyle Evans 85220495ed39SKyle Evans 85230495ed39SKyle Evans 85240495ed39SKyle Evans<p> 85258e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> 85268e3e3a7aSWarner Losh 85278e3e3a7aSWarner Losh 85288e3e3a7aSWarner Losh<p> 85298e3e3a7aSWarner LoshCreates a new coroutine, with body <code>f</code>. 85308e3e3a7aSWarner Losh<code>f</code> must be a function. 85318e3e3a7aSWarner LoshReturns this new coroutine, 85328e3e3a7aSWarner Loshan object with type <code>"thread"</code>. 85338e3e3a7aSWarner Losh 85348e3e3a7aSWarner Losh 85358e3e3a7aSWarner Losh 85368e3e3a7aSWarner Losh 85378e3e3a7aSWarner Losh<p> 85380495ed39SKyle Evans<hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ([co])</code></a></h3> 85398e3e3a7aSWarner Losh 85408e3e3a7aSWarner Losh 85418e3e3a7aSWarner Losh<p> 85428c784bb8SWarner LoshReturns <b>true</b> when the coroutine <code>co</code> can yield. 85430495ed39SKyle EvansThe default for <code>co</code> is the running coroutine. 85448e3e3a7aSWarner Losh 85458e3e3a7aSWarner Losh 85468e3e3a7aSWarner Losh<p> 85470495ed39SKyle EvansA coroutine is yieldable if it is not the main thread and 85488e3e3a7aSWarner Loshit is not inside a non-yieldable C function. 85498e3e3a7aSWarner Losh 85508e3e3a7aSWarner Losh 85518e3e3a7aSWarner Losh 85528e3e3a7aSWarner Losh 85538e3e3a7aSWarner Losh<p> 85548e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> 85558e3e3a7aSWarner Losh 85568e3e3a7aSWarner Losh 85578e3e3a7aSWarner Losh<p> 85588e3e3a7aSWarner LoshStarts or continues the execution of coroutine <code>co</code>. 85598e3e3a7aSWarner LoshThe first time you resume a coroutine, 85608e3e3a7aSWarner Loshit starts running its body. 85618e3e3a7aSWarner LoshThe values <code>val1</code>, ... are passed 85628e3e3a7aSWarner Loshas the arguments to the body function. 85638e3e3a7aSWarner LoshIf the coroutine has yielded, 85648e3e3a7aSWarner Losh<code>resume</code> restarts it; 85658e3e3a7aSWarner Loshthe values <code>val1</code>, ... are passed 85668e3e3a7aSWarner Loshas the results from the yield. 85678e3e3a7aSWarner Losh 85688e3e3a7aSWarner Losh 85698e3e3a7aSWarner Losh<p> 85708e3e3a7aSWarner LoshIf the coroutine runs without any errors, 85718e3e3a7aSWarner Losh<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> 85728e3e3a7aSWarner Losh(when the coroutine yields) or any values returned by the body function 85738e3e3a7aSWarner Losh(when the coroutine terminates). 85748e3e3a7aSWarner LoshIf there is any error, 85758e3e3a7aSWarner Losh<code>resume</code> returns <b>false</b> plus the error message. 85768e3e3a7aSWarner Losh 85778e3e3a7aSWarner Losh 85788e3e3a7aSWarner Losh 85798e3e3a7aSWarner Losh 85808e3e3a7aSWarner Losh<p> 85818e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> 85828e3e3a7aSWarner Losh 85838e3e3a7aSWarner Losh 85848e3e3a7aSWarner Losh<p> 85858e3e3a7aSWarner LoshReturns the running coroutine plus a boolean, 85868c784bb8SWarner Losh<b>true</b> when the running coroutine is the main one. 85878e3e3a7aSWarner Losh 85888e3e3a7aSWarner Losh 85898e3e3a7aSWarner Losh 85908e3e3a7aSWarner Losh 85918e3e3a7aSWarner Losh<p> 85928e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> 85938e3e3a7aSWarner Losh 85948e3e3a7aSWarner Losh 85958e3e3a7aSWarner Losh<p> 85960495ed39SKyle EvansReturns the status of the coroutine <code>co</code>, as a string: 85978e3e3a7aSWarner Losh<code>"running"</code>, 85980495ed39SKyle Evansif the coroutine is running 85990495ed39SKyle Evans(that is, it is the one that called <code>status</code>); 86008e3e3a7aSWarner Losh<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, 86018e3e3a7aSWarner Loshor if it has not started running yet; 86028e3e3a7aSWarner Losh<code>"normal"</code> if the coroutine is active but not running 86038e3e3a7aSWarner Losh(that is, it has resumed another coroutine); 86048e3e3a7aSWarner Loshand <code>"dead"</code> if the coroutine has finished its body function, 86058e3e3a7aSWarner Loshor if it has stopped with an error. 86068e3e3a7aSWarner Losh 86078e3e3a7aSWarner Losh 86088e3e3a7aSWarner Losh 86098e3e3a7aSWarner Losh 86108e3e3a7aSWarner Losh<p> 86118e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> 86128e3e3a7aSWarner Losh 86138e3e3a7aSWarner Losh 86148e3e3a7aSWarner Losh<p> 86150495ed39SKyle EvansCreates a new coroutine, with body <code>f</code>; 86168e3e3a7aSWarner Losh<code>f</code> must be a function. 86178e3e3a7aSWarner LoshReturns a function that resumes the coroutine each time it is called. 86180495ed39SKyle EvansAny arguments passed to this function behave as the 86198e3e3a7aSWarner Loshextra arguments to <code>resume</code>. 86200495ed39SKyle EvansThe function returns the same values returned by <code>resume</code>, 86218e3e3a7aSWarner Loshexcept the first boolean. 86220495ed39SKyle EvansIn case of error, 86230495ed39SKyle Evansthe function closes the coroutine and propagates the error. 86248e3e3a7aSWarner Losh 86258e3e3a7aSWarner Losh 86268e3e3a7aSWarner Losh 86278e3e3a7aSWarner Losh 86288e3e3a7aSWarner Losh<p> 86298e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> 86308e3e3a7aSWarner Losh 86318e3e3a7aSWarner Losh 86328e3e3a7aSWarner Losh<p> 86338e3e3a7aSWarner LoshSuspends the execution of the calling coroutine. 86348e3e3a7aSWarner LoshAny arguments to <code>yield</code> are passed as extra results to <code>resume</code>. 86358e3e3a7aSWarner Losh 86368e3e3a7aSWarner Losh 86378e3e3a7aSWarner Losh 86388e3e3a7aSWarner Losh 86398e3e3a7aSWarner Losh 86408e3e3a7aSWarner Losh 86418e3e3a7aSWarner Losh 86428e3e3a7aSWarner Losh<h2>6.3 – <a name="6.3">Modules</a></h2> 86438e3e3a7aSWarner Losh 86448e3e3a7aSWarner Losh<p> 86458e3e3a7aSWarner LoshThe package library provides basic 86468e3e3a7aSWarner Loshfacilities for loading modules in Lua. 86478e3e3a7aSWarner LoshIt exports one function directly in the global environment: 86488e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a>. 86490495ed39SKyle EvansEverything else is exported in the table <a name="pdf-package"><code>package</code></a>. 86508e3e3a7aSWarner Losh 86518e3e3a7aSWarner Losh 86528e3e3a7aSWarner Losh<p> 86538e3e3a7aSWarner Losh<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> 86548e3e3a7aSWarner Losh 86558e3e3a7aSWarner Losh 86568e3e3a7aSWarner Losh<p> 86578e3e3a7aSWarner LoshLoads the given module. 86588e3e3a7aSWarner LoshThe function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table 86598e3e3a7aSWarner Loshto determine whether <code>modname</code> is already loaded. 86608e3e3a7aSWarner LoshIf it is, then <code>require</code> returns the value stored 86618e3e3a7aSWarner Loshat <code>package.loaded[modname]</code>. 86620495ed39SKyle Evans(The absence of a second result in this case 86630495ed39SKyle Evanssignals that this call did not have to load the module.) 86648e3e3a7aSWarner LoshOtherwise, it tries to find a <em>loader</em> for the module. 86658e3e3a7aSWarner Losh 86668e3e3a7aSWarner Losh 86678e3e3a7aSWarner Losh<p> 86688e3e3a7aSWarner LoshTo find a loader, 86690495ed39SKyle Evans<code>require</code> is guided by the table <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 86700495ed39SKyle EvansEach item in this table is a search function, 86710495ed39SKyle Evansthat searches for the module in a particular way. 86720495ed39SKyle EvansBy changing this table, 86738e3e3a7aSWarner Loshwe can change how <code>require</code> looks for a module. 86748e3e3a7aSWarner LoshThe following explanation is based on the default configuration 86758e3e3a7aSWarner Loshfor <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 86768e3e3a7aSWarner Losh 86778e3e3a7aSWarner Losh 86788e3e3a7aSWarner Losh<p> 86798e3e3a7aSWarner LoshFirst <code>require</code> queries <code>package.preload[modname]</code>. 86808e3e3a7aSWarner LoshIf it has a value, 86818e3e3a7aSWarner Loshthis value (which must be a function) is the loader. 86828e3e3a7aSWarner LoshOtherwise <code>require</code> searches for a Lua loader using the 86838e3e3a7aSWarner Loshpath stored in <a href="#pdf-package.path"><code>package.path</code></a>. 86848e3e3a7aSWarner LoshIf that also fails, it searches for a C loader using the 86858e3e3a7aSWarner Loshpath stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 86868e3e3a7aSWarner LoshIf that also fails, 86878e3e3a7aSWarner Loshit tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>). 86888e3e3a7aSWarner Losh 86898e3e3a7aSWarner Losh 86908e3e3a7aSWarner Losh<p> 86918e3e3a7aSWarner LoshOnce a loader is found, 86928e3e3a7aSWarner Losh<code>require</code> calls the loader with two arguments: 86930495ed39SKyle Evans<code>modname</code> and an extra value, 86940495ed39SKyle Evansa <em>loader data</em>, 86950495ed39SKyle Evansalso returned by the searcher. 86960495ed39SKyle EvansThe loader data can be any value useful to the module; 86970495ed39SKyle Evansfor the default searchers, 86980495ed39SKyle Evansit indicates where the loader was found. 86990495ed39SKyle Evans(For instance, if the loader came from a file, 87000495ed39SKyle Evansthis extra value is the file path.) 87018e3e3a7aSWarner LoshIf the loader returns any non-nil value, 87028e3e3a7aSWarner Losh<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. 87038e3e3a7aSWarner LoshIf the loader does not return a non-nil value and 87048e3e3a7aSWarner Loshhas not assigned any value to <code>package.loaded[modname]</code>, 87058e3e3a7aSWarner Loshthen <code>require</code> assigns <b>true</b> to this entry. 87068e3e3a7aSWarner LoshIn any case, <code>require</code> returns the 87078e3e3a7aSWarner Loshfinal value of <code>package.loaded[modname]</code>. 87080495ed39SKyle EvansBesides that value, <code>require</code> also returns as a second result 87090495ed39SKyle Evansthe loader data returned by the searcher, 87100495ed39SKyle Evanswhich indicates how <code>require</code> found the module. 87118e3e3a7aSWarner Losh 87128e3e3a7aSWarner Losh 87138e3e3a7aSWarner Losh<p> 87148e3e3a7aSWarner LoshIf there is any error loading or running the module, 87158e3e3a7aSWarner Loshor if it cannot find any loader for the module, 87168e3e3a7aSWarner Loshthen <code>require</code> raises an error. 87178e3e3a7aSWarner Losh 87188e3e3a7aSWarner Losh 87198e3e3a7aSWarner Losh 87208e3e3a7aSWarner Losh 87218e3e3a7aSWarner Losh<p> 87228e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3> 87238e3e3a7aSWarner Losh 87248e3e3a7aSWarner Losh 87258e3e3a7aSWarner Losh<p> 87268e3e3a7aSWarner LoshA string describing some compile-time configurations for packages. 87278e3e3a7aSWarner LoshThis string is a sequence of lines: 87288e3e3a7aSWarner Losh 87298e3e3a7aSWarner Losh<ul> 87308e3e3a7aSWarner Losh 87318e3e3a7aSWarner Losh<li>The first line is the directory separator string. 87328e3e3a7aSWarner LoshDefault is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li> 87338e3e3a7aSWarner Losh 87348e3e3a7aSWarner Losh<li>The second line is the character that separates templates in a path. 87358e3e3a7aSWarner LoshDefault is '<code>;</code>'.</li> 87368e3e3a7aSWarner Losh 87378e3e3a7aSWarner Losh<li>The third line is the string that marks the 87388e3e3a7aSWarner Loshsubstitution points in a template. 87398e3e3a7aSWarner LoshDefault is '<code>?</code>'.</li> 87408e3e3a7aSWarner Losh 87418e3e3a7aSWarner Losh<li>The fourth line is a string that, in a path in Windows, 87428e3e3a7aSWarner Loshis replaced by the executable's directory. 87438e3e3a7aSWarner LoshDefault is '<code>!</code>'.</li> 87448e3e3a7aSWarner Losh 87458e3e3a7aSWarner Losh<li>The fifth line is a mark to ignore all text after it 87468e3e3a7aSWarner Loshwhen building the <code>luaopen_</code> function name. 87478e3e3a7aSWarner LoshDefault is '<code>-</code>'.</li> 87488e3e3a7aSWarner Losh 87498e3e3a7aSWarner Losh</ul> 87508e3e3a7aSWarner Losh 87518e3e3a7aSWarner Losh 87528e3e3a7aSWarner Losh 87538e3e3a7aSWarner Losh<p> 87548e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> 87558e3e3a7aSWarner Losh 87568e3e3a7aSWarner Losh 87578e3e3a7aSWarner Losh<p> 87580495ed39SKyle EvansA string with the path used by <a href="#pdf-require"><code>require</code></a> 87590495ed39SKyle Evansto search for a C loader. 87608e3e3a7aSWarner Losh 87618e3e3a7aSWarner Losh 87628e3e3a7aSWarner Losh<p> 87638e3e3a7aSWarner LoshLua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way 87648e3e3a7aSWarner Loshit initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, 87650495ed39SKyle Evansusing the environment variable <a name="pdf-LUA_CPATH_5_4"><code>LUA_CPATH_5_4</code></a>, 87668e3e3a7aSWarner Loshor the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>, 87678e3e3a7aSWarner Loshor a default path defined in <code>luaconf.h</code>. 87688e3e3a7aSWarner Losh 87698e3e3a7aSWarner Losh 87708e3e3a7aSWarner Losh 87718e3e3a7aSWarner Losh 87728e3e3a7aSWarner Losh<p> 87738e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> 87748e3e3a7aSWarner Losh 87758e3e3a7aSWarner Losh 87768e3e3a7aSWarner Losh<p> 87778e3e3a7aSWarner LoshA table used by <a href="#pdf-require"><code>require</code></a> to control which 87788e3e3a7aSWarner Loshmodules are already loaded. 87798e3e3a7aSWarner LoshWhen you require a module <code>modname</code> and 87808e3e3a7aSWarner Losh<code>package.loaded[modname]</code> is not false, 87818e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a> simply returns the value stored there. 87828e3e3a7aSWarner Losh 87838e3e3a7aSWarner Losh 87848e3e3a7aSWarner Losh<p> 87858e3e3a7aSWarner LoshThis variable is only a reference to the real table; 87868e3e3a7aSWarner Loshassignments to this variable do not change the 87878e3e3a7aSWarner Loshtable used by <a href="#pdf-require"><code>require</code></a>. 8788*a9490b81SWarner LoshThe real table is stored in the C registry (see <a href="#4.3">§4.3</a>), 8789*a9490b81SWarner Loshindexed by the key <a name="pdf-LUA_LOADED_TABLE"><code>LUA_LOADED_TABLE</code></a>, a string. 87908e3e3a7aSWarner Losh 87918e3e3a7aSWarner Losh 87928e3e3a7aSWarner Losh 87938e3e3a7aSWarner Losh 87948e3e3a7aSWarner Losh<p> 87958e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> 87968e3e3a7aSWarner Losh 87978e3e3a7aSWarner Losh 87988e3e3a7aSWarner Losh<p> 87998e3e3a7aSWarner LoshDynamically links the host program with the C library <code>libname</code>. 88008e3e3a7aSWarner Losh 88018e3e3a7aSWarner Losh 88028e3e3a7aSWarner Losh<p> 88038e3e3a7aSWarner LoshIf <code>funcname</code> is "<code>*</code>", 88048e3e3a7aSWarner Loshthen it only links with the library, 88058e3e3a7aSWarner Loshmaking the symbols exported by the library 88068e3e3a7aSWarner Loshavailable to other dynamically linked libraries. 88078e3e3a7aSWarner LoshOtherwise, 88088e3e3a7aSWarner Loshit looks for a function <code>funcname</code> inside the library 88098e3e3a7aSWarner Loshand returns this function as a C function. 88108e3e3a7aSWarner LoshSo, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype 88118e3e3a7aSWarner Losh(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 88128e3e3a7aSWarner Losh 88138e3e3a7aSWarner Losh 88148e3e3a7aSWarner Losh<p> 88158e3e3a7aSWarner LoshThis is a low-level function. 88168e3e3a7aSWarner LoshIt completely bypasses the package and module system. 88178e3e3a7aSWarner LoshUnlike <a href="#pdf-require"><code>require</code></a>, 88188e3e3a7aSWarner Loshit does not perform any path searching and 88198e3e3a7aSWarner Loshdoes not automatically adds extensions. 88208e3e3a7aSWarner Losh<code>libname</code> must be the complete file name of the C library, 88218e3e3a7aSWarner Loshincluding if necessary a path and an extension. 88228e3e3a7aSWarner Losh<code>funcname</code> must be the exact name exported by the C library 88238e3e3a7aSWarner Losh(which may depend on the C compiler and linker used). 88248e3e3a7aSWarner Losh 88258e3e3a7aSWarner Losh 88268e3e3a7aSWarner Losh<p> 8827*a9490b81SWarner LoshThis functionality is not supported by ISO C. 88288e3e3a7aSWarner LoshAs such, it is only available on some platforms 88298e3e3a7aSWarner Losh(Windows, Linux, Mac OS X, Solaris, BSD, 88308e3e3a7aSWarner Loshplus other Unix systems that support the <code>dlfcn</code> standard). 88318e3e3a7aSWarner Losh 88328e3e3a7aSWarner Losh 88330495ed39SKyle Evans<p> 88340495ed39SKyle EvansThis function is inherently insecure, 88350495ed39SKyle Evansas it allows Lua to call any function in any readable dynamic 88360495ed39SKyle Evanslibrary in the system. 88370495ed39SKyle Evans(Lua calls any function assuming the function 88380495ed39SKyle Evanshas a proper prototype and respects a proper protocol 88390495ed39SKyle Evans(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 88400495ed39SKyle EvansTherefore, 88410495ed39SKyle Evanscalling an arbitrary function in an arbitrary dynamic library 88420495ed39SKyle Evansmore often than not results in an access violation.) 88430495ed39SKyle Evans 88440495ed39SKyle Evans 88458e3e3a7aSWarner Losh 88468e3e3a7aSWarner Losh 88478e3e3a7aSWarner Losh<p> 88488e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> 88498e3e3a7aSWarner Losh 88508e3e3a7aSWarner Losh 88518e3e3a7aSWarner Losh<p> 88520495ed39SKyle EvansA string with the path used by <a href="#pdf-require"><code>require</code></a> 88530495ed39SKyle Evansto search for a Lua loader. 88548e3e3a7aSWarner Losh 88558e3e3a7aSWarner Losh 88568e3e3a7aSWarner Losh<p> 88578e3e3a7aSWarner LoshAt start-up, Lua initializes this variable with 88580495ed39SKyle Evansthe value of the environment variable <a name="pdf-LUA_PATH_5_4"><code>LUA_PATH_5_4</code></a> or 88598e3e3a7aSWarner Loshthe environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or 88608e3e3a7aSWarner Loshwith a default path defined in <code>luaconf.h</code>, 88618e3e3a7aSWarner Loshif those environment variables are not defined. 88620495ed39SKyle EvansA "<code>;;</code>" in the value of the environment variable 88638e3e3a7aSWarner Loshis replaced by the default path. 88648e3e3a7aSWarner Losh 88658e3e3a7aSWarner Losh 88668e3e3a7aSWarner Losh 88678e3e3a7aSWarner Losh 88688e3e3a7aSWarner Losh<p> 88698e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> 88708e3e3a7aSWarner Losh 88718e3e3a7aSWarner Losh 88728e3e3a7aSWarner Losh<p> 88738e3e3a7aSWarner LoshA table to store loaders for specific modules 88748e3e3a7aSWarner Losh(see <a href="#pdf-require"><code>require</code></a>). 88758e3e3a7aSWarner Losh 88768e3e3a7aSWarner Losh 88778e3e3a7aSWarner Losh<p> 88788e3e3a7aSWarner LoshThis variable is only a reference to the real table; 88798e3e3a7aSWarner Loshassignments to this variable do not change the 88808e3e3a7aSWarner Loshtable used by <a href="#pdf-require"><code>require</code></a>. 8881*a9490b81SWarner LoshThe real table is stored in the C registry (see <a href="#4.3">§4.3</a>), 8882*a9490b81SWarner Loshindexed by the key <a name="pdf-LUA_PRELOAD_TABLE"><code>LUA_PRELOAD_TABLE</code></a>, a string. 88838e3e3a7aSWarner Losh 88848e3e3a7aSWarner Losh 88858e3e3a7aSWarner Losh 88868e3e3a7aSWarner Losh 88878e3e3a7aSWarner Losh<p> 88888e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3> 88898e3e3a7aSWarner Losh 88908e3e3a7aSWarner Losh 88918e3e3a7aSWarner Losh<p> 88920495ed39SKyle EvansA table used by <a href="#pdf-require"><code>require</code></a> to control how to find modules. 88938e3e3a7aSWarner Losh 88948e3e3a7aSWarner Losh 88958e3e3a7aSWarner Losh<p> 88968e3e3a7aSWarner LoshEach entry in this table is a <em>searcher function</em>. 88978e3e3a7aSWarner LoshWhen looking for a module, 88988e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, 88998e3e3a7aSWarner Loshwith the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its 89000495ed39SKyle Evanssole argument. 89010495ed39SKyle EvansIf the searcher finds the module, 89020495ed39SKyle Evansit returns another function, the module <em>loader</em>, 89030495ed39SKyle Evansplus an extra value, a <em>loader data</em>, 89040495ed39SKyle Evansthat will be passed to that loader and 89050495ed39SKyle Evansreturned as a second result by <a href="#pdf-require"><code>require</code></a>. 89060495ed39SKyle EvansIf it cannot find the module, 89070495ed39SKyle Evansit returns a string explaining why 89088e3e3a7aSWarner Losh(or <b>nil</b> if it has nothing to say). 89098e3e3a7aSWarner Losh 89108e3e3a7aSWarner Losh 89118e3e3a7aSWarner Losh<p> 89128e3e3a7aSWarner LoshLua initializes this table with four searcher functions. 89138e3e3a7aSWarner Losh 89148e3e3a7aSWarner Losh 89158e3e3a7aSWarner Losh<p> 89168e3e3a7aSWarner LoshThe first searcher simply looks for a loader in the 89178e3e3a7aSWarner Losh<a href="#pdf-package.preload"><code>package.preload</code></a> table. 89188e3e3a7aSWarner Losh 89198e3e3a7aSWarner Losh 89208e3e3a7aSWarner Losh<p> 89218e3e3a7aSWarner LoshThe second searcher looks for a loader as a Lua library, 89228e3e3a7aSWarner Loshusing the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. 89238e3e3a7aSWarner LoshThe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 89248e3e3a7aSWarner Losh 89258e3e3a7aSWarner Losh 89268e3e3a7aSWarner Losh<p> 89278e3e3a7aSWarner LoshThe third searcher looks for a loader as a C library, 89288e3e3a7aSWarner Loshusing the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 89298e3e3a7aSWarner LoshAgain, 89308e3e3a7aSWarner Loshthe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 89318e3e3a7aSWarner LoshFor instance, 89328e3e3a7aSWarner Loshif the C path is the string 89338e3e3a7aSWarner Losh 89348e3e3a7aSWarner Losh<pre> 89358e3e3a7aSWarner Losh "./?.so;./?.dll;/usr/local/?/init.so" 89368e3e3a7aSWarner Losh</pre><p> 89378e3e3a7aSWarner Loshthe searcher for module <code>foo</code> 89388e3e3a7aSWarner Loshwill try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, 89398e3e3a7aSWarner Loshand <code>/usr/local/foo/init.so</code>, in that order. 89408e3e3a7aSWarner LoshOnce it finds a C library, 89418e3e3a7aSWarner Loshthis searcher first uses a dynamic link facility to link the 89428e3e3a7aSWarner Loshapplication with the library. 89438e3e3a7aSWarner LoshThen it tries to find a C function inside the library to 89448e3e3a7aSWarner Loshbe used as the loader. 89458e3e3a7aSWarner LoshThe name of this C function is the string "<code>luaopen_</code>" 89468e3e3a7aSWarner Loshconcatenated with a copy of the module name where each dot 89478e3e3a7aSWarner Loshis replaced by an underscore. 89488e3e3a7aSWarner LoshMoreover, if the module name has a hyphen, 89498e3e3a7aSWarner Loshits suffix after (and including) the first hyphen is removed. 89508e3e3a7aSWarner LoshFor instance, if the module name is <code>a.b.c-v2.1</code>, 89518e3e3a7aSWarner Loshthe function name will be <code>luaopen_a_b_c</code>. 89528e3e3a7aSWarner Losh 89538e3e3a7aSWarner Losh 89548e3e3a7aSWarner Losh<p> 89558e3e3a7aSWarner LoshThe fourth searcher tries an <em>all-in-one loader</em>. 89568e3e3a7aSWarner LoshIt searches the C path for a library for 89578e3e3a7aSWarner Loshthe root name of the given module. 89588e3e3a7aSWarner LoshFor instance, when requiring <code>a.b.c</code>, 89598e3e3a7aSWarner Loshit will search for a C library for <code>a</code>. 89608e3e3a7aSWarner LoshIf found, it looks into it for an open function for 89618e3e3a7aSWarner Loshthe submodule; 89628e3e3a7aSWarner Loshin our example, that would be <code>luaopen_a_b_c</code>. 89638e3e3a7aSWarner LoshWith this facility, a package can pack several C submodules 89648e3e3a7aSWarner Loshinto one single library, 89658e3e3a7aSWarner Loshwith each submodule keeping its original open function. 89668e3e3a7aSWarner Losh 89678e3e3a7aSWarner Losh 89688e3e3a7aSWarner Losh<p> 89698e3e3a7aSWarner LoshAll searchers except the first one (preload) return as the extra value 89700495ed39SKyle Evansthe file path where the module was found, 89718e3e3a7aSWarner Loshas returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 89720495ed39SKyle EvansThe first searcher always returns the string "<code>:preload:</code>". 89730495ed39SKyle Evans 89740495ed39SKyle Evans 89750495ed39SKyle Evans<p> 89760495ed39SKyle EvansSearchers should raise no errors and have no side effects in Lua. 89770495ed39SKyle Evans(They may have side effects in C, 89780495ed39SKyle Evansfor instance by linking the application with a library.) 89798e3e3a7aSWarner Losh 89808e3e3a7aSWarner Losh 89818e3e3a7aSWarner Losh 89828e3e3a7aSWarner Losh 89838e3e3a7aSWarner Losh<p> 89848e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3> 89858e3e3a7aSWarner Losh 89868e3e3a7aSWarner Losh 89878e3e3a7aSWarner Losh<p> 89888e3e3a7aSWarner LoshSearches for the given <code>name</code> in the given <code>path</code>. 89898e3e3a7aSWarner Losh 89908e3e3a7aSWarner Losh 89918e3e3a7aSWarner Losh<p> 89928e3e3a7aSWarner LoshA path is a string containing a sequence of 89938e3e3a7aSWarner Losh<em>templates</em> separated by semicolons. 89948e3e3a7aSWarner LoshFor each template, 89958e3e3a7aSWarner Loshthe function replaces each interrogation mark (if any) 89968e3e3a7aSWarner Loshin the template with a copy of <code>name</code> 89978e3e3a7aSWarner Loshwherein all occurrences of <code>sep</code> 89988e3e3a7aSWarner Losh(a dot, by default) 89998e3e3a7aSWarner Loshwere replaced by <code>rep</code> 90008e3e3a7aSWarner Losh(the system's directory separator, by default), 90018e3e3a7aSWarner Loshand then tries to open the resulting file name. 90028e3e3a7aSWarner Losh 90038e3e3a7aSWarner Losh 90048e3e3a7aSWarner Losh<p> 90058e3e3a7aSWarner LoshFor instance, if the path is the string 90068e3e3a7aSWarner Losh 90078e3e3a7aSWarner Losh<pre> 90088e3e3a7aSWarner Losh "./?.lua;./?.lc;/usr/local/?/init.lua" 90098e3e3a7aSWarner Losh</pre><p> 90108e3e3a7aSWarner Loshthe search for the name <code>foo.a</code> 90118e3e3a7aSWarner Loshwill try to open the files 90128e3e3a7aSWarner Losh<code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and 90138e3e3a7aSWarner Losh<code>/usr/local/foo/a/init.lua</code>, in that order. 90148e3e3a7aSWarner Losh 90158e3e3a7aSWarner Losh 90168e3e3a7aSWarner Losh<p> 90178e3e3a7aSWarner LoshReturns the resulting name of the first file that it can 90188e3e3a7aSWarner Loshopen in read mode (after closing the file), 90190495ed39SKyle Evansor <b>fail</b> plus an error message if none succeeds. 90208e3e3a7aSWarner Losh(This error message lists all file names it tried to open.) 90218e3e3a7aSWarner Losh 90228e3e3a7aSWarner Losh 90238e3e3a7aSWarner Losh 90248e3e3a7aSWarner Losh 90258e3e3a7aSWarner Losh 90268e3e3a7aSWarner Losh 90278e3e3a7aSWarner Losh 90288e3e3a7aSWarner Losh<h2>6.4 – <a name="6.4">String Manipulation</a></h2> 90298e3e3a7aSWarner Losh 90300495ed39SKyle Evans 90310495ed39SKyle Evans 90328e3e3a7aSWarner Losh<p> 90338e3e3a7aSWarner LoshThis library provides generic functions for string manipulation, 90348e3e3a7aSWarner Loshsuch as finding and extracting substrings, and pattern matching. 90358e3e3a7aSWarner LoshWhen indexing a string in Lua, the first character is at position 1 90368e3e3a7aSWarner Losh(not at 0, as in C). 90378e3e3a7aSWarner LoshIndices are allowed to be negative and are interpreted as indexing backwards, 90388e3e3a7aSWarner Loshfrom the end of the string. 90398e3e3a7aSWarner LoshThus, the last character is at position -1, and so on. 90408e3e3a7aSWarner Losh 90418e3e3a7aSWarner Losh 90428e3e3a7aSWarner Losh<p> 90438e3e3a7aSWarner LoshThe string library provides all its functions inside the table 90448e3e3a7aSWarner Losh<a name="pdf-string"><code>string</code></a>. 90458e3e3a7aSWarner LoshIt also sets a metatable for strings 90468e3e3a7aSWarner Loshwhere the <code>__index</code> field points to the <code>string</code> table. 90478e3e3a7aSWarner LoshTherefore, you can use the string functions in object-oriented style. 90488e3e3a7aSWarner LoshFor instance, <code>string.byte(s,i)</code> 90498e3e3a7aSWarner Loshcan be written as <code>s:byte(i)</code>. 90508e3e3a7aSWarner Losh 90518e3e3a7aSWarner Losh 90528e3e3a7aSWarner Losh<p> 90538e3e3a7aSWarner LoshThe string library assumes one-byte character encodings. 90548e3e3a7aSWarner Losh 90558e3e3a7aSWarner Losh 90568e3e3a7aSWarner Losh<p> 90578e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> 90588e3e3a7aSWarner LoshReturns the internal numeric codes of the characters <code>s[i]</code>, 90598e3e3a7aSWarner Losh<code>s[i+1]</code>, ..., <code>s[j]</code>. 90608e3e3a7aSWarner LoshThe default value for <code>i</code> is 1; 90618e3e3a7aSWarner Loshthe default value for <code>j</code> is <code>i</code>. 90628e3e3a7aSWarner LoshThese indices are corrected 90638e3e3a7aSWarner Loshfollowing the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>. 90648e3e3a7aSWarner Losh 90658e3e3a7aSWarner Losh 90668e3e3a7aSWarner Losh<p> 90678e3e3a7aSWarner LoshNumeric codes are not necessarily portable across platforms. 90688e3e3a7aSWarner Losh 90698e3e3a7aSWarner Losh 90708e3e3a7aSWarner Losh 90718e3e3a7aSWarner Losh 90728e3e3a7aSWarner Losh<p> 90738e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> 90748e3e3a7aSWarner LoshReceives zero or more integers. 90758e3e3a7aSWarner LoshReturns a string with length equal to the number of arguments, 90768e3e3a7aSWarner Loshin which each character has the internal numeric code equal 90778e3e3a7aSWarner Loshto its corresponding argument. 90788e3e3a7aSWarner Losh 90798e3e3a7aSWarner Losh 90808e3e3a7aSWarner Losh<p> 90818e3e3a7aSWarner LoshNumeric codes are not necessarily portable across platforms. 90828e3e3a7aSWarner Losh 90838e3e3a7aSWarner Losh 90848e3e3a7aSWarner Losh 90858e3e3a7aSWarner Losh 90868e3e3a7aSWarner Losh<p> 90878e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3> 90888e3e3a7aSWarner Losh 90898e3e3a7aSWarner Losh 90908e3e3a7aSWarner Losh<p> 90918e3e3a7aSWarner LoshReturns a string containing a binary representation 90928e3e3a7aSWarner Losh(a <em>binary chunk</em>) 90938e3e3a7aSWarner Loshof the given function, 90948e3e3a7aSWarner Loshso that a later <a href="#pdf-load"><code>load</code></a> on this string returns 90958e3e3a7aSWarner Losha copy of the function (but with new upvalues). 90968e3e3a7aSWarner LoshIf <code>strip</code> is a true value, 90978e3e3a7aSWarner Loshthe binary representation may not include all debug information 90988e3e3a7aSWarner Loshabout the function, 90998e3e3a7aSWarner Loshto save space. 91008e3e3a7aSWarner Losh 91018e3e3a7aSWarner Losh 91028e3e3a7aSWarner Losh<p> 91038e3e3a7aSWarner LoshFunctions with upvalues have only their number of upvalues saved. 91048e3e3a7aSWarner LoshWhen (re)loaded, 91050495ed39SKyle Evansthose upvalues receive fresh instances. 91060495ed39SKyle Evans(See the <a href="#pdf-load"><code>load</code></a> function for details about 91070495ed39SKyle Evanshow these upvalues are initialized. 91080495ed39SKyle EvansYou can use the debug library to serialize 91098e3e3a7aSWarner Loshand reload the upvalues of a function 91108e3e3a7aSWarner Loshin a way adequate to your needs.) 91118e3e3a7aSWarner Losh 91128e3e3a7aSWarner Losh 91138e3e3a7aSWarner Losh 91148e3e3a7aSWarner Losh 91158e3e3a7aSWarner Losh<p> 91168e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> 91178e3e3a7aSWarner Losh 91188e3e3a7aSWarner Losh 91198e3e3a7aSWarner Losh<p> 91208e3e3a7aSWarner LoshLooks for the first match of 91218e3e3a7aSWarner Losh<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 91228e3e3a7aSWarner LoshIf it finds a match, then <code>find</code> returns the indices of <code>s</code> 91238e3e3a7aSWarner Loshwhere this occurrence starts and ends; 91240495ed39SKyle Evansotherwise, it returns <b>fail</b>. 91258e3e3a7aSWarner LoshA third, optional numeric argument <code>init</code> specifies 91268e3e3a7aSWarner Loshwhere to start the search; 91278e3e3a7aSWarner Loshits default value is 1 and can be negative. 91288c784bb8SWarner LoshA <b>true</b> as a fourth, optional argument <code>plain</code> 91298e3e3a7aSWarner Loshturns off the pattern matching facilities, 91308e3e3a7aSWarner Loshso the function does a plain "find substring" operation, 91318e3e3a7aSWarner Loshwith no characters in <code>pattern</code> being considered magic. 91328e3e3a7aSWarner Losh 91338e3e3a7aSWarner Losh 91348e3e3a7aSWarner Losh<p> 91358e3e3a7aSWarner LoshIf the pattern has captures, 91368e3e3a7aSWarner Loshthen in a successful match 91378e3e3a7aSWarner Loshthe captured values are also returned, 91388e3e3a7aSWarner Loshafter the two indices. 91398e3e3a7aSWarner Losh 91408e3e3a7aSWarner Losh 91418e3e3a7aSWarner Losh 91428e3e3a7aSWarner Losh 91438e3e3a7aSWarner Losh<p> 91448e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> 91458e3e3a7aSWarner Losh 91468e3e3a7aSWarner Losh 91478e3e3a7aSWarner Losh<p> 91488e3e3a7aSWarner LoshReturns a formatted version of its variable number of arguments 91490495ed39SKyle Evansfollowing the description given in its first argument, 91500495ed39SKyle Evanswhich must be a string. 91518e3e3a7aSWarner LoshThe format string follows the same rules as the ISO C function <code>sprintf</code>. 91520495ed39SKyle EvansThe only differences are that the conversion specifiers and modifiers 91538c784bb8SWarner Losh<code>F</code>, <code>n</code>, <code>*</code>, <code>h</code>, <code>L</code>, and <code>l</code> are not supported 91540495ed39SKyle Evansand that there is an extra specifier, <code>q</code>. 91558c784bb8SWarner LoshBoth width and precision, when present, 91568c784bb8SWarner Loshare limited to two digits. 91578e3e3a7aSWarner Losh 91588e3e3a7aSWarner Losh 91598e3e3a7aSWarner Losh<p> 91600495ed39SKyle EvansThe specifier <code>q</code> formats booleans, nil, numbers, and strings 91610495ed39SKyle Evansin a way that the result is a valid constant in Lua source code. 91620495ed39SKyle EvansBooleans and nil are written in the obvious way 91630495ed39SKyle Evans(<code>true</code>, <code>false</code>, <code>nil</code>). 91640495ed39SKyle EvansFloats are written in hexadecimal, 91650495ed39SKyle Evansto preserve full precision. 91660495ed39SKyle EvansA string is written between double quotes, 91678e3e3a7aSWarner Loshusing escape sequences when necessary to ensure that 91688e3e3a7aSWarner Loshit can safely be read back by the Lua interpreter. 91698e3e3a7aSWarner LoshFor instance, the call 91708e3e3a7aSWarner Losh 91718e3e3a7aSWarner Losh<pre> 91728e3e3a7aSWarner Losh string.format('%q', 'a string with "quotes" and \n new line') 91738e3e3a7aSWarner Losh</pre><p> 91748e3e3a7aSWarner Loshmay produce the string: 91758e3e3a7aSWarner Losh 91768e3e3a7aSWarner Losh<pre> 91778e3e3a7aSWarner Losh "a string with \"quotes\" and \ 91788e3e3a7aSWarner Losh new line" 91790495ed39SKyle Evans</pre><p> 91808c784bb8SWarner LoshThis specifier does not support modifiers (flags, width, precision). 91810495ed39SKyle Evans 91828e3e3a7aSWarner Losh 91838e3e3a7aSWarner Losh<p> 91840495ed39SKyle EvansThe conversion specifiers 91858e3e3a7aSWarner Losh<code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>, 91868e3e3a7aSWarner Losh<code>G</code>, and <code>g</code> all expect a number as argument. 91870495ed39SKyle EvansThe specifiers <code>c</code>, <code>d</code>, 91888e3e3a7aSWarner Losh<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> 91898e3e3a7aSWarner Loshexpect an integer. 91908e3e3a7aSWarner LoshWhen Lua is compiled with a C89 compiler, 91910495ed39SKyle Evansthe specifiers <code>A</code> and <code>a</code> (hexadecimal floats) 91920495ed39SKyle Evansdo not support modifiers. 91938e3e3a7aSWarner Losh 91948e3e3a7aSWarner Losh 91958e3e3a7aSWarner Losh<p> 91960495ed39SKyle EvansThe specifier <code>s</code> expects a string; 91978e3e3a7aSWarner Loshif its argument is not a string, 91988e3e3a7aSWarner Loshit is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 91990495ed39SKyle EvansIf the specifier has any modifier, 92000495ed39SKyle Evansthe corresponding string argument should not contain embedded zeros. 92010495ed39SKyle Evans 92020495ed39SKyle Evans 92030495ed39SKyle Evans<p> 92040495ed39SKyle EvansThe specifier <code>p</code> formats the pointer 92050495ed39SKyle Evansreturned by <a href="#lua_topointer"><code>lua_topointer</code></a>. 92060495ed39SKyle EvansThat gives a unique string identifier for tables, userdata, 92070495ed39SKyle Evansthreads, strings, and functions. 92080495ed39SKyle EvansFor other values (numbers, nil, booleans), 92090495ed39SKyle Evansthis specifier results in a string representing 92100495ed39SKyle Evansthe pointer <code>NULL</code>. 92118e3e3a7aSWarner Losh 92128e3e3a7aSWarner Losh 92138e3e3a7aSWarner Losh 92148e3e3a7aSWarner Losh 92158e3e3a7aSWarner Losh<p> 92160495ed39SKyle Evans<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern [, init])</code></a></h3> 92178e3e3a7aSWarner LoshReturns an iterator function that, 92188e3e3a7aSWarner Losheach time it is called, 92198e3e3a7aSWarner Loshreturns the next captures from <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) 92208e3e3a7aSWarner Loshover the string <code>s</code>. 92218e3e3a7aSWarner LoshIf <code>pattern</code> specifies no captures, 92228e3e3a7aSWarner Loshthen the whole match is produced in each call. 92230495ed39SKyle EvansA third, optional numeric argument <code>init</code> specifies 92240495ed39SKyle Evanswhere to start the search; 92250495ed39SKyle Evansits default value is 1 and can be negative. 92268e3e3a7aSWarner Losh 92278e3e3a7aSWarner Losh 92288e3e3a7aSWarner Losh<p> 92298e3e3a7aSWarner LoshAs an example, the following loop 92308e3e3a7aSWarner Loshwill iterate over all the words from string <code>s</code>, 92318e3e3a7aSWarner Loshprinting one per line: 92328e3e3a7aSWarner Losh 92338e3e3a7aSWarner Losh<pre> 92348e3e3a7aSWarner Losh s = "hello world from Lua" 92358e3e3a7aSWarner Losh for w in string.gmatch(s, "%a+") do 92368e3e3a7aSWarner Losh print(w) 92378e3e3a7aSWarner Losh end 92388e3e3a7aSWarner Losh</pre><p> 92398e3e3a7aSWarner LoshThe next example collects all pairs <code>key=value</code> from the 92408e3e3a7aSWarner Loshgiven string into a table: 92418e3e3a7aSWarner Losh 92428e3e3a7aSWarner Losh<pre> 92438e3e3a7aSWarner Losh t = {} 92448e3e3a7aSWarner Losh s = "from=world, to=Lua" 92458e3e3a7aSWarner Losh for k, v in string.gmatch(s, "(%w+)=(%w+)") do 92468e3e3a7aSWarner Losh t[k] = v 92478e3e3a7aSWarner Losh end 92488e3e3a7aSWarner Losh</pre> 92498e3e3a7aSWarner Losh 92508e3e3a7aSWarner Losh<p> 92518e3e3a7aSWarner LoshFor this function, a caret '<code>^</code>' at the start of a pattern does not 92528e3e3a7aSWarner Loshwork as an anchor, as this would prevent the iteration. 92538e3e3a7aSWarner Losh 92548e3e3a7aSWarner Losh 92558e3e3a7aSWarner Losh 92568e3e3a7aSWarner Losh 92578e3e3a7aSWarner Losh<p> 92588e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> 92598e3e3a7aSWarner LoshReturns a copy of <code>s</code> 92608e3e3a7aSWarner Loshin which all (or the first <code>n</code>, if given) 92618e3e3a7aSWarner Loshoccurrences of the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) have been 92628e3e3a7aSWarner Loshreplaced by a replacement string specified by <code>repl</code>, 92638e3e3a7aSWarner Loshwhich can be a string, a table, or a function. 92648e3e3a7aSWarner Losh<code>gsub</code> also returns, as its second value, 92658e3e3a7aSWarner Loshthe total number of matches that occurred. 92668e3e3a7aSWarner LoshThe name <code>gsub</code> comes from <em>Global SUBstitution</em>. 92678e3e3a7aSWarner Losh 92688e3e3a7aSWarner Losh 92698e3e3a7aSWarner Losh<p> 92708e3e3a7aSWarner LoshIf <code>repl</code> is a string, then its value is used for replacement. 92718e3e3a7aSWarner LoshThe character <code>%</code> works as an escape character: 92728e3e3a7aSWarner Loshany sequence in <code>repl</code> of the form <code>%<em>d</em></code>, 92738e3e3a7aSWarner Loshwith <em>d</em> between 1 and 9, 92740495ed39SKyle Evansstands for the value of the <em>d</em>-th captured substring; 92750495ed39SKyle Evansthe sequence <code>%0</code> stands for the whole match; 92760495ed39SKyle Evansthe sequence <code>%%</code> stands for a single <code>%</code>. 92778e3e3a7aSWarner Losh 92788e3e3a7aSWarner Losh 92798e3e3a7aSWarner Losh<p> 92808e3e3a7aSWarner LoshIf <code>repl</code> is a table, then the table is queried for every match, 92818e3e3a7aSWarner Loshusing the first capture as the key. 92828e3e3a7aSWarner Losh 92838e3e3a7aSWarner Losh 92848e3e3a7aSWarner Losh<p> 92858e3e3a7aSWarner LoshIf <code>repl</code> is a function, then this function is called every time a 92868e3e3a7aSWarner Loshmatch occurs, with all captured substrings passed as arguments, 92878e3e3a7aSWarner Loshin order. 92888e3e3a7aSWarner Losh 92898e3e3a7aSWarner Losh 92908e3e3a7aSWarner Losh<p> 92918e3e3a7aSWarner LoshIn any case, 92928e3e3a7aSWarner Loshif the pattern specifies no captures, 92938e3e3a7aSWarner Loshthen it behaves as if the whole pattern was inside a capture. 92948e3e3a7aSWarner Losh 92958e3e3a7aSWarner Losh 92968e3e3a7aSWarner Losh<p> 92978e3e3a7aSWarner LoshIf the value returned by the table query or by the function call 92988e3e3a7aSWarner Loshis a string or a number, 92998e3e3a7aSWarner Loshthen it is used as the replacement string; 93008e3e3a7aSWarner Loshotherwise, if it is <b>false</b> or <b>nil</b>, 93018e3e3a7aSWarner Loshthen there is no replacement 93028e3e3a7aSWarner Losh(that is, the original match is kept in the string). 93038e3e3a7aSWarner Losh 93048e3e3a7aSWarner Losh 93058e3e3a7aSWarner Losh<p> 93068e3e3a7aSWarner LoshHere are some examples: 93078e3e3a7aSWarner Losh 93088e3e3a7aSWarner Losh<pre> 93098e3e3a7aSWarner Losh x = string.gsub("hello world", "(%w+)", "%1 %1") 93108e3e3a7aSWarner Losh --> x="hello hello world world" 93118e3e3a7aSWarner Losh 93128e3e3a7aSWarner Losh x = string.gsub("hello world", "%w+", "%0 %0", 1) 93138e3e3a7aSWarner Losh --> x="hello hello world" 93148e3e3a7aSWarner Losh 93158e3e3a7aSWarner Losh x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 93168e3e3a7aSWarner Losh --> x="world hello Lua from" 93178e3e3a7aSWarner Losh 93188e3e3a7aSWarner Losh x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) 93198e3e3a7aSWarner Losh --> x="home = /home/roberto, user = roberto" 93208e3e3a7aSWarner Losh 93218e3e3a7aSWarner Losh x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 93228e3e3a7aSWarner Losh return load(s)() 93238e3e3a7aSWarner Losh end) 93248e3e3a7aSWarner Losh --> x="4+5 = 9" 93258e3e3a7aSWarner Losh 93260495ed39SKyle Evans local t = {name="lua", version="5.4"} 93278e3e3a7aSWarner Losh x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 93280495ed39SKyle Evans --> x="lua-5.4.tar.gz" 93298e3e3a7aSWarner Losh</pre> 93308e3e3a7aSWarner Losh 93318e3e3a7aSWarner Losh 93328e3e3a7aSWarner Losh 93338e3e3a7aSWarner Losh<p> 93348e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> 93350495ed39SKyle Evans 93360495ed39SKyle Evans 93370495ed39SKyle Evans<p> 93388e3e3a7aSWarner LoshReceives a string and returns its length. 93398e3e3a7aSWarner LoshThe empty string <code>""</code> has length 0. 93408e3e3a7aSWarner LoshEmbedded zeros are counted, 93418e3e3a7aSWarner Loshso <code>"a\000bc\000"</code> has length 5. 93428e3e3a7aSWarner Losh 93438e3e3a7aSWarner Losh 93448e3e3a7aSWarner Losh 93458e3e3a7aSWarner Losh 93468e3e3a7aSWarner Losh<p> 93478e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> 93480495ed39SKyle Evans 93490495ed39SKyle Evans 93500495ed39SKyle Evans<p> 93518e3e3a7aSWarner LoshReceives a string and returns a copy of this string with all 93528e3e3a7aSWarner Loshuppercase letters changed to lowercase. 93538e3e3a7aSWarner LoshAll other characters are left unchanged. 93548e3e3a7aSWarner LoshThe definition of what an uppercase letter is depends on the current locale. 93558e3e3a7aSWarner Losh 93568e3e3a7aSWarner Losh 93578e3e3a7aSWarner Losh 93588e3e3a7aSWarner Losh 93598e3e3a7aSWarner Losh<p> 93608e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> 93610495ed39SKyle Evans 93620495ed39SKyle Evans 93630495ed39SKyle Evans<p> 93648e3e3a7aSWarner LoshLooks for the first <em>match</em> of 93650495ed39SKyle Evansthe <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 93668e3e3a7aSWarner LoshIf it finds one, then <code>match</code> returns 93678e3e3a7aSWarner Loshthe captures from the pattern; 93680495ed39SKyle Evansotherwise it returns <b>fail</b>. 93698e3e3a7aSWarner LoshIf <code>pattern</code> specifies no captures, 93708e3e3a7aSWarner Loshthen the whole match is returned. 93718e3e3a7aSWarner LoshA third, optional numeric argument <code>init</code> specifies 93728e3e3a7aSWarner Loshwhere to start the search; 93738e3e3a7aSWarner Loshits default value is 1 and can be negative. 93748e3e3a7aSWarner Losh 93758e3e3a7aSWarner Losh 93768e3e3a7aSWarner Losh 93778e3e3a7aSWarner Losh 93788e3e3a7aSWarner Losh<p> 93798e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, ···)</code></a></h3> 93808e3e3a7aSWarner Losh 93818e3e3a7aSWarner Losh 93828e3e3a7aSWarner Losh<p> 93838e3e3a7aSWarner LoshReturns a binary string containing the values <code>v1</code>, <code>v2</code>, etc. 93840495ed39SKyle Evansserialized in binary form (packed) 93858e3e3a7aSWarner Loshaccording to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 93868e3e3a7aSWarner Losh 93878e3e3a7aSWarner Losh 93888e3e3a7aSWarner Losh 93898e3e3a7aSWarner Losh 93908e3e3a7aSWarner Losh<p> 93918e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3> 93928e3e3a7aSWarner Losh 93938e3e3a7aSWarner Losh 93948e3e3a7aSWarner Losh<p> 9395*a9490b81SWarner LoshReturns the length of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a> 93968e3e3a7aSWarner Loshwith the given format. 93978e3e3a7aSWarner LoshThe format string cannot have the variable-length options 93988e3e3a7aSWarner Losh'<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">§6.4.2</a>). 93998e3e3a7aSWarner Losh 94008e3e3a7aSWarner Losh 94018e3e3a7aSWarner Losh 94028e3e3a7aSWarner Losh 94038e3e3a7aSWarner Losh<p> 94048e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3> 94050495ed39SKyle Evans 94060495ed39SKyle Evans 94070495ed39SKyle Evans<p> 94088e3e3a7aSWarner LoshReturns a string that is the concatenation of <code>n</code> copies of 94098e3e3a7aSWarner Loshthe string <code>s</code> separated by the string <code>sep</code>. 94108e3e3a7aSWarner LoshThe default value for <code>sep</code> is the empty string 94118e3e3a7aSWarner Losh(that is, no separator). 94128e3e3a7aSWarner LoshReturns the empty string if <code>n</code> is not positive. 94138e3e3a7aSWarner Losh 94148e3e3a7aSWarner Losh 94158e3e3a7aSWarner Losh<p> 94168e3e3a7aSWarner Losh(Note that it is very easy to exhaust the memory of your machine 94178e3e3a7aSWarner Loshwith a single call to this function.) 94188e3e3a7aSWarner Losh 94198e3e3a7aSWarner Losh 94208e3e3a7aSWarner Losh 94218e3e3a7aSWarner Losh 94228e3e3a7aSWarner Losh<p> 94238e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> 94240495ed39SKyle Evans 94250495ed39SKyle Evans 94260495ed39SKyle Evans<p> 94278e3e3a7aSWarner LoshReturns a string that is the string <code>s</code> reversed. 94288e3e3a7aSWarner Losh 94298e3e3a7aSWarner Losh 94308e3e3a7aSWarner Losh 94318e3e3a7aSWarner Losh 94328e3e3a7aSWarner Losh<p> 94338e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> 94340495ed39SKyle Evans 94350495ed39SKyle Evans 94360495ed39SKyle Evans<p> 94378e3e3a7aSWarner LoshReturns the substring of <code>s</code> that 94388e3e3a7aSWarner Loshstarts at <code>i</code> and continues until <code>j</code>; 94398e3e3a7aSWarner Losh<code>i</code> and <code>j</code> can be negative. 94408e3e3a7aSWarner LoshIf <code>j</code> is absent, then it is assumed to be equal to -1 94418e3e3a7aSWarner Losh(which is the same as the string length). 94428e3e3a7aSWarner LoshIn particular, 94438e3e3a7aSWarner Loshthe call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 94448e3e3a7aSWarner Loshwith length <code>j</code>, 94458e3e3a7aSWarner Loshand <code>string.sub(s, -i)</code> (for a positive <code>i</code>) 94468e3e3a7aSWarner Loshreturns a suffix of <code>s</code> 94478e3e3a7aSWarner Loshwith length <code>i</code>. 94488e3e3a7aSWarner Losh 94498e3e3a7aSWarner Losh 94508e3e3a7aSWarner Losh<p> 94518e3e3a7aSWarner LoshIf, after the translation of negative indices, 94528e3e3a7aSWarner Losh<code>i</code> is less than 1, 94538e3e3a7aSWarner Loshit is corrected to 1. 94548e3e3a7aSWarner LoshIf <code>j</code> is greater than the string length, 94558e3e3a7aSWarner Loshit is corrected to that length. 94568e3e3a7aSWarner LoshIf, after these corrections, 94578e3e3a7aSWarner Losh<code>i</code> is greater than <code>j</code>, 94588e3e3a7aSWarner Loshthe function returns the empty string. 94598e3e3a7aSWarner Losh 94608e3e3a7aSWarner Losh 94618e3e3a7aSWarner Losh 94628e3e3a7aSWarner Losh 94638e3e3a7aSWarner Losh<p> 94648e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3> 94658e3e3a7aSWarner Losh 94668e3e3a7aSWarner Losh 94678e3e3a7aSWarner Losh<p> 94688e3e3a7aSWarner LoshReturns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>) 94698e3e3a7aSWarner Loshaccording to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 94708e3e3a7aSWarner LoshAn optional <code>pos</code> marks where 94718e3e3a7aSWarner Loshto start reading in <code>s</code> (default is 1). 94728e3e3a7aSWarner LoshAfter the read values, 94738e3e3a7aSWarner Loshthis function also returns the index of the first unread byte in <code>s</code>. 94748e3e3a7aSWarner Losh 94758e3e3a7aSWarner Losh 94768e3e3a7aSWarner Losh 94778e3e3a7aSWarner Losh 94788e3e3a7aSWarner Losh<p> 94798e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> 94800495ed39SKyle Evans 94810495ed39SKyle Evans 94820495ed39SKyle Evans<p> 94838e3e3a7aSWarner LoshReceives a string and returns a copy of this string with all 94848e3e3a7aSWarner Loshlowercase letters changed to uppercase. 94858e3e3a7aSWarner LoshAll other characters are left unchanged. 94868e3e3a7aSWarner LoshThe definition of what a lowercase letter is depends on the current locale. 94878e3e3a7aSWarner Losh 94888e3e3a7aSWarner Losh 94898e3e3a7aSWarner Losh 94908e3e3a7aSWarner Losh 94918e3e3a7aSWarner Losh 94920495ed39SKyle Evans 94930495ed39SKyle Evans 94948e3e3a7aSWarner Losh<h3>6.4.1 – <a name="6.4.1">Patterns</a></h3> 94958e3e3a7aSWarner Losh 94960495ed39SKyle Evans 94970495ed39SKyle Evans 94988e3e3a7aSWarner Losh<p> 94998e3e3a7aSWarner LoshPatterns in Lua are described by regular strings, 95008e3e3a7aSWarner Loshwhich are interpreted as patterns by the pattern-matching functions 95018e3e3a7aSWarner Losh<a href="#pdf-string.find"><code>string.find</code></a>, 95028e3e3a7aSWarner Losh<a href="#pdf-string.gmatch"><code>string.gmatch</code></a>, 95038e3e3a7aSWarner Losh<a href="#pdf-string.gsub"><code>string.gsub</code></a>, 95048e3e3a7aSWarner Loshand <a href="#pdf-string.match"><code>string.match</code></a>. 95058e3e3a7aSWarner LoshThis section describes the syntax and the meaning 95068e3e3a7aSWarner Losh(that is, what they match) of these strings. 95078e3e3a7aSWarner Losh 95088e3e3a7aSWarner Losh 95098e3e3a7aSWarner Losh 95100495ed39SKyle Evans 95110495ed39SKyle Evans 95128e3e3a7aSWarner Losh<h4>Character Class:</h4><p> 95138e3e3a7aSWarner LoshA <em>character class</em> is used to represent a set of characters. 95148e3e3a7aSWarner LoshThe following combinations are allowed in describing a character class: 95158e3e3a7aSWarner Losh 95168e3e3a7aSWarner Losh<ul> 95178e3e3a7aSWarner Losh 95188e3e3a7aSWarner Losh<li><b><em>x</em>: </b> 95198e3e3a7aSWarner Losh(where <em>x</em> is not one of the <em>magic characters</em> 95208e3e3a7aSWarner Losh<code>^$()%.[]*+-?</code>) 95218e3e3a7aSWarner Loshrepresents the character <em>x</em> itself. 95228e3e3a7aSWarner Losh</li> 95238e3e3a7aSWarner Losh 95248e3e3a7aSWarner Losh<li><b><code>.</code>: </b> (a dot) represents all characters.</li> 95258e3e3a7aSWarner Losh 95268e3e3a7aSWarner Losh<li><b><code>%a</code>: </b> represents all letters.</li> 95278e3e3a7aSWarner Losh 95288e3e3a7aSWarner Losh<li><b><code>%c</code>: </b> represents all control characters.</li> 95298e3e3a7aSWarner Losh 95308e3e3a7aSWarner Losh<li><b><code>%d</code>: </b> represents all digits.</li> 95318e3e3a7aSWarner Losh 95328e3e3a7aSWarner Losh<li><b><code>%g</code>: </b> represents all printable characters except space.</li> 95338e3e3a7aSWarner Losh 95348e3e3a7aSWarner Losh<li><b><code>%l</code>: </b> represents all lowercase letters.</li> 95358e3e3a7aSWarner Losh 95368e3e3a7aSWarner Losh<li><b><code>%p</code>: </b> represents all punctuation characters.</li> 95378e3e3a7aSWarner Losh 95388e3e3a7aSWarner Losh<li><b><code>%s</code>: </b> represents all space characters.</li> 95398e3e3a7aSWarner Losh 95408e3e3a7aSWarner Losh<li><b><code>%u</code>: </b> represents all uppercase letters.</li> 95418e3e3a7aSWarner Losh 95428e3e3a7aSWarner Losh<li><b><code>%w</code>: </b> represents all alphanumeric characters.</li> 95438e3e3a7aSWarner Losh 95448e3e3a7aSWarner Losh<li><b><code>%x</code>: </b> represents all hexadecimal digits.</li> 95458e3e3a7aSWarner Losh 95468e3e3a7aSWarner Losh<li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character) 95478e3e3a7aSWarner Loshrepresents the character <em>x</em>. 95488e3e3a7aSWarner LoshThis is the standard way to escape the magic characters. 95498e3e3a7aSWarner LoshAny non-alphanumeric character 95508e3e3a7aSWarner Losh(including all punctuation characters, even the non-magical) 95510495ed39SKyle Evanscan be preceded by a '<code>%</code>' to represent itself in a pattern. 95528e3e3a7aSWarner Losh</li> 95538e3e3a7aSWarner Losh 95548e3e3a7aSWarner Losh<li><b><code>[<em>set</em>]</code>: </b> 95558e3e3a7aSWarner Loshrepresents the class which is the union of all 95568e3e3a7aSWarner Loshcharacters in <em>set</em>. 95578e3e3a7aSWarner LoshA range of characters can be specified by 95588e3e3a7aSWarner Loshseparating the end characters of the range, 95598e3e3a7aSWarner Loshin ascending order, with a '<code>-</code>'. 95608e3e3a7aSWarner LoshAll classes <code>%</code><em>x</em> described above can also be used as 95618e3e3a7aSWarner Loshcomponents in <em>set</em>. 95628e3e3a7aSWarner LoshAll other characters in <em>set</em> represent themselves. 95638e3e3a7aSWarner LoshFor example, <code>[%w_]</code> (or <code>[_%w]</code>) 95648e3e3a7aSWarner Loshrepresents all alphanumeric characters plus the underscore, 95658e3e3a7aSWarner Losh<code>[0-7]</code> represents the octal digits, 95668e3e3a7aSWarner Loshand <code>[0-7%l%-]</code> represents the octal digits plus 95678e3e3a7aSWarner Loshthe lowercase letters plus the '<code>-</code>' character. 95688e3e3a7aSWarner Losh 95698e3e3a7aSWarner Losh 95708e3e3a7aSWarner Losh<p> 95718e3e3a7aSWarner LoshYou can put a closing square bracket in a set 95728e3e3a7aSWarner Loshby positioning it as the first character in the set. 9573e112e9d2SKyle EvansYou can put a hyphen in a set 95748e3e3a7aSWarner Loshby positioning it as the first or the last character in the set. 95758e3e3a7aSWarner Losh(You can also use an escape for both cases.) 95768e3e3a7aSWarner Losh 95778e3e3a7aSWarner Losh 95788e3e3a7aSWarner Losh<p> 95798e3e3a7aSWarner LoshThe interaction between ranges and classes is not defined. 95808e3e3a7aSWarner LoshTherefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> 95818e3e3a7aSWarner Loshhave no meaning. 95828e3e3a7aSWarner Losh</li> 95838e3e3a7aSWarner Losh 95848e3e3a7aSWarner Losh<li><b><code>[^<em>set</em>]</code>: </b> 95858e3e3a7aSWarner Loshrepresents the complement of <em>set</em>, 95868e3e3a7aSWarner Loshwhere <em>set</em> is interpreted as above. 95878e3e3a7aSWarner Losh</li> 95888e3e3a7aSWarner Losh 95898e3e3a7aSWarner Losh</ul><p> 95908e3e3a7aSWarner LoshFor all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), 95918e3e3a7aSWarner Loshthe corresponding uppercase letter represents the complement of the class. 95928e3e3a7aSWarner LoshFor instance, <code>%S</code> represents all non-space characters. 95938e3e3a7aSWarner Losh 95948e3e3a7aSWarner Losh 95958e3e3a7aSWarner Losh<p> 95968e3e3a7aSWarner LoshThe definitions of letter, space, and other character groups 95978e3e3a7aSWarner Loshdepend on the current locale. 95988e3e3a7aSWarner LoshIn particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. 95998e3e3a7aSWarner Losh 96008e3e3a7aSWarner Losh 96018e3e3a7aSWarner Losh 96028e3e3a7aSWarner Losh 96038e3e3a7aSWarner Losh 96048e3e3a7aSWarner Losh<h4>Pattern Item:</h4><p> 96058e3e3a7aSWarner LoshA <em>pattern item</em> can be 96068e3e3a7aSWarner Losh 96078e3e3a7aSWarner Losh<ul> 96088e3e3a7aSWarner Losh 96098e3e3a7aSWarner Losh<li> 96108e3e3a7aSWarner Losha single character class, 96118e3e3a7aSWarner Loshwhich matches any single character in the class; 96128e3e3a7aSWarner Losh</li> 96138e3e3a7aSWarner Losh 96148e3e3a7aSWarner Losh<li> 96158e3e3a7aSWarner Losha single character class followed by '<code>*</code>', 96160495ed39SKyle Evanswhich matches sequences of zero or more characters in the class. 96178e3e3a7aSWarner LoshThese repetition items will always match the longest possible sequence; 96188e3e3a7aSWarner Losh</li> 96198e3e3a7aSWarner Losh 96208e3e3a7aSWarner Losh<li> 96218e3e3a7aSWarner Losha single character class followed by '<code>+</code>', 96220495ed39SKyle Evanswhich matches sequences of one or more characters in the class. 96238e3e3a7aSWarner LoshThese repetition items will always match the longest possible sequence; 96248e3e3a7aSWarner Losh</li> 96258e3e3a7aSWarner Losh 96268e3e3a7aSWarner Losh<li> 96278e3e3a7aSWarner Losha single character class followed by '<code>-</code>', 96280495ed39SKyle Evanswhich also matches sequences of zero or more characters in the class. 96298e3e3a7aSWarner LoshUnlike '<code>*</code>', 96308e3e3a7aSWarner Loshthese repetition items will always match the shortest possible sequence; 96318e3e3a7aSWarner Losh</li> 96328e3e3a7aSWarner Losh 96338e3e3a7aSWarner Losh<li> 96348e3e3a7aSWarner Losha single character class followed by '<code>?</code>', 96358e3e3a7aSWarner Loshwhich matches zero or one occurrence of a character in the class. 96368e3e3a7aSWarner LoshIt always matches one occurrence if possible; 96378e3e3a7aSWarner Losh</li> 96388e3e3a7aSWarner Losh 96398e3e3a7aSWarner Losh<li> 96408e3e3a7aSWarner Losh<code>%<em>n</em></code>, for <em>n</em> between 1 and 9; 96418e3e3a7aSWarner Loshsuch item matches a substring equal to the <em>n</em>-th captured string 96428e3e3a7aSWarner Losh(see below); 96438e3e3a7aSWarner Losh</li> 96448e3e3a7aSWarner Losh 96458e3e3a7aSWarner Losh<li> 96468e3e3a7aSWarner Losh<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; 96478e3e3a7aSWarner Loshsuch item matches strings that start with <em>x</em>, end with <em>y</em>, 96488e3e3a7aSWarner Loshand where the <em>x</em> and <em>y</em> are <em>balanced</em>. 96498e3e3a7aSWarner LoshThis means that, if one reads the string from left to right, 96508e3e3a7aSWarner Loshcounting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, 96518e3e3a7aSWarner Loshthe ending <em>y</em> is the first <em>y</em> where the count reaches 0. 96528e3e3a7aSWarner LoshFor instance, the item <code>%b()</code> matches expressions with 96538e3e3a7aSWarner Loshbalanced parentheses. 96548e3e3a7aSWarner Losh</li> 96558e3e3a7aSWarner Losh 96568e3e3a7aSWarner Losh<li> 96578e3e3a7aSWarner Losh<code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>; 96588e3e3a7aSWarner Loshsuch item matches an empty string at any position such that 96598e3e3a7aSWarner Loshthe next character belongs to <em>set</em> 96608e3e3a7aSWarner Loshand the previous character does not belong to <em>set</em>. 96618e3e3a7aSWarner LoshThe set <em>set</em> is interpreted as previously described. 96628e3e3a7aSWarner LoshThe beginning and the end of the subject are handled as if 96638e3e3a7aSWarner Loshthey were the character '<code>\0</code>'. 96648e3e3a7aSWarner Losh</li> 96658e3e3a7aSWarner Losh 96668e3e3a7aSWarner Losh</ul> 96678e3e3a7aSWarner Losh 96688e3e3a7aSWarner Losh 96698e3e3a7aSWarner Losh 96708e3e3a7aSWarner Losh 96718e3e3a7aSWarner Losh<h4>Pattern:</h4><p> 96728e3e3a7aSWarner LoshA <em>pattern</em> is a sequence of pattern items. 96738e3e3a7aSWarner LoshA caret '<code>^</code>' at the beginning of a pattern anchors the match at the 96748e3e3a7aSWarner Loshbeginning of the subject string. 96758e3e3a7aSWarner LoshA '<code>$</code>' at the end of a pattern anchors the match at the 96768e3e3a7aSWarner Loshend of the subject string. 96778e3e3a7aSWarner LoshAt other positions, 96788e3e3a7aSWarner Losh'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. 96798e3e3a7aSWarner Losh 96808e3e3a7aSWarner Losh 96818e3e3a7aSWarner Losh 96828e3e3a7aSWarner Losh 96838e3e3a7aSWarner Losh 96848e3e3a7aSWarner Losh<h4>Captures:</h4><p> 96858e3e3a7aSWarner LoshA pattern can contain sub-patterns enclosed in parentheses; 96868e3e3a7aSWarner Loshthey describe <em>captures</em>. 96878e3e3a7aSWarner LoshWhen a match succeeds, the substrings of the subject string 96888e3e3a7aSWarner Loshthat match captures are stored (<em>captured</em>) for future use. 96898e3e3a7aSWarner LoshCaptures are numbered according to their left parentheses. 96908e3e3a7aSWarner LoshFor instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, 96918e3e3a7aSWarner Loshthe part of the string matching <code>"a*(.)%w(%s*)"</code> is 96920495ed39SKyle Evansstored as the first capture, and therefore has number 1; 96938e3e3a7aSWarner Loshthe character matching "<code>.</code>" is captured with number 2, 96948e3e3a7aSWarner Loshand the part matching "<code>%s*</code>" has number 3. 96958e3e3a7aSWarner Losh 96968e3e3a7aSWarner Losh 96978e3e3a7aSWarner Losh<p> 96980495ed39SKyle EvansAs a special case, the capture <code>()</code> captures 96998e3e3a7aSWarner Loshthe current string position (a number). 97008e3e3a7aSWarner LoshFor instance, if we apply the pattern <code>"()aa()"</code> on the 97018e3e3a7aSWarner Loshstring <code>"flaaap"</code>, there will be two captures: 3 and 5. 97028e3e3a7aSWarner Losh 97038e3e3a7aSWarner Losh 97048e3e3a7aSWarner Losh 97058e3e3a7aSWarner Losh 97068e3e3a7aSWarner Losh 97070495ed39SKyle Evans<h4>Multiple matches:</h4><p> 97080495ed39SKyle EvansThe function <a href="#pdf-string.gsub"><code>string.gsub</code></a> and the iterator <a href="#pdf-string.gmatch"><code>string.gmatch</code></a> 97090495ed39SKyle Evansmatch multiple occurrences of the given pattern in the subject. 97100495ed39SKyle EvansFor these functions, 97110495ed39SKyle Evansa new match is considered valid only 97120495ed39SKyle Evansif it ends at least one byte after the end of the previous match. 97130495ed39SKyle EvansIn other words, the pattern machine never accepts the 97140495ed39SKyle Evansempty string as a match immediately after another match. 97150495ed39SKyle EvansAs an example, 97160495ed39SKyle Evansconsider the results of the following code: 97170495ed39SKyle Evans 97180495ed39SKyle Evans<pre> 97190495ed39SKyle Evans > string.gsub("abc", "()a*()", print); 97200495ed39SKyle Evans --> 1 2 97210495ed39SKyle Evans --> 3 3 97220495ed39SKyle Evans --> 4 4 97230495ed39SKyle Evans</pre><p> 97240495ed39SKyle EvansThe second and third results come from Lua matching an empty 97250495ed39SKyle Evansstring after '<code>b</code>' and another one after '<code>c</code>'. 97260495ed39SKyle EvansLua does not match an empty string after '<code>a</code>', 97270495ed39SKyle Evansbecause it would end at the same position of the previous match. 97280495ed39SKyle Evans 97290495ed39SKyle Evans 97300495ed39SKyle Evans 97310495ed39SKyle Evans 97320495ed39SKyle Evans 97338e3e3a7aSWarner Losh 97348e3e3a7aSWarner Losh 97358e3e3a7aSWarner Losh<h3>6.4.2 – <a name="6.4.2">Format Strings for Pack and Unpack</a></h3> 97368e3e3a7aSWarner Losh 97378e3e3a7aSWarner Losh<p> 97388e3e3a7aSWarner LoshThe first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>, 97398e3e3a7aSWarner Losh<a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a> 97408e3e3a7aSWarner Loshis a format string, 97418e3e3a7aSWarner Loshwhich describes the layout of the structure being created or read. 97428e3e3a7aSWarner Losh 97438e3e3a7aSWarner Losh 97448e3e3a7aSWarner Losh<p> 97458e3e3a7aSWarner LoshA format string is a sequence of conversion options. 97468e3e3a7aSWarner LoshThe conversion options are as follows: 97478e3e3a7aSWarner Losh 97488e3e3a7aSWarner Losh<ul> 97498e3e3a7aSWarner Losh<li><b><code><</code>: </b>sets little endian</li> 97508e3e3a7aSWarner Losh<li><b><code>></code>: </b>sets big endian</li> 97518e3e3a7aSWarner Losh<li><b><code>=</code>: </b>sets native endian</li> 97528e3e3a7aSWarner Losh<li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code> 97538e3e3a7aSWarner Losh(default is native alignment)</li> 97548e3e3a7aSWarner Losh<li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li> 97558e3e3a7aSWarner Losh<li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li> 97568e3e3a7aSWarner Losh<li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li> 97578e3e3a7aSWarner Losh<li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li> 97588e3e3a7aSWarner Losh<li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li> 97598e3e3a7aSWarner Losh<li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li> 97608e3e3a7aSWarner Losh<li><b><code>j</code>: </b>a <code>lua_Integer</code></li> 97618e3e3a7aSWarner Losh<li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li> 97628e3e3a7aSWarner Losh<li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li> 97638e3e3a7aSWarner Losh<li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes 97648e3e3a7aSWarner Losh(default is native size)</li> 97658e3e3a7aSWarner Losh<li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes 97668e3e3a7aSWarner Losh(default is native size)</li> 97678e3e3a7aSWarner Losh<li><b><code>f</code>: </b>a <code>float</code> (native size)</li> 97688e3e3a7aSWarner Losh<li><b><code>d</code>: </b>a <code>double</code> (native size)</li> 97698e3e3a7aSWarner Losh<li><b><code>n</code>: </b>a <code>lua_Number</code></li> 97708e3e3a7aSWarner Losh<li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li> 97718e3e3a7aSWarner Losh<li><b><code>z</code>: </b>a zero-terminated string</li> 97728e3e3a7aSWarner Losh<li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length 97738e3e3a7aSWarner Loshcoded as an unsigned integer with <code>n</code> bytes 97748e3e3a7aSWarner Losh(default is a <code>size_t</code>)</li> 97758e3e3a7aSWarner Losh<li><b><code>x</code>: </b>one byte of padding</li> 97768e3e3a7aSWarner Losh<li><b><code>X<em>op</em></code>: </b>an empty item that aligns 97778e3e3a7aSWarner Loshaccording to option <code>op</code> 97788e3e3a7aSWarner Losh(which is otherwise ignored)</li> 97790495ed39SKyle Evans<li><b>'<code> </code>': </b>(space) ignored</li> 97808e3e3a7aSWarner Losh</ul><p> 97818e3e3a7aSWarner Losh(A "<code>[<em>n</em>]</code>" means an optional integral numeral.) 97828e3e3a7aSWarner LoshExcept for padding, spaces, and configurations 97838e3e3a7aSWarner Losh(options "<code>xX <=>!</code>"), 97840495ed39SKyle Evanseach option corresponds to an argument in <a href="#pdf-string.pack"><code>string.pack</code></a> 97850495ed39SKyle Evansor a result in <a href="#pdf-string.unpack"><code>string.unpack</code></a>. 97868e3e3a7aSWarner Losh 97878e3e3a7aSWarner Losh 97888e3e3a7aSWarner Losh<p> 97898e3e3a7aSWarner 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>", 97908e3e3a7aSWarner Losh<code>n</code> can be any integer between 1 and 16. 97918e3e3a7aSWarner LoshAll integral options check overflows; 97928e3e3a7aSWarner Losh<a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size; 97938e3e3a7aSWarner Losh<a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer. 97940495ed39SKyle EvansFor the unsigned options, 97950495ed39SKyle EvansLua integers are treated as unsigned values too. 97968e3e3a7aSWarner Losh 97978e3e3a7aSWarner Losh 97988e3e3a7aSWarner Losh<p> 97998e3e3a7aSWarner LoshAny format string starts as if prefixed by "<code>!1=</code>", 98008e3e3a7aSWarner Loshthat is, 98018e3e3a7aSWarner Loshwith maximum alignment of 1 (no alignment) 98028e3e3a7aSWarner Loshand native endianness. 98038e3e3a7aSWarner Losh 98048e3e3a7aSWarner Losh 98058e3e3a7aSWarner Losh<p> 98060495ed39SKyle EvansNative endianness assumes that the whole system is 98070495ed39SKyle Evanseither big or little endian. 98080495ed39SKyle EvansThe packing functions will not emulate correctly the behavior 98090495ed39SKyle Evansof mixed-endian formats. 98100495ed39SKyle Evans 98110495ed39SKyle Evans 98120495ed39SKyle Evans<p> 98138e3e3a7aSWarner LoshAlignment works as follows: 98148e3e3a7aSWarner LoshFor each option, 98158e3e3a7aSWarner Loshthe format gets extra padding until the data starts 98168e3e3a7aSWarner Loshat an offset that is a multiple of the minimum between the 98178e3e3a7aSWarner Loshoption size and the maximum alignment; 98188e3e3a7aSWarner Loshthis minimum must be a power of 2. 98198e3e3a7aSWarner LoshOptions "<code>c</code>" and "<code>z</code>" are not aligned; 98208e3e3a7aSWarner Loshoption "<code>s</code>" follows the alignment of its starting integer. 98218e3e3a7aSWarner Losh 98228e3e3a7aSWarner Losh 98238e3e3a7aSWarner Losh<p> 98248e3e3a7aSWarner LoshAll padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a> 98250495ed39SKyle Evansand ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>. 98268e3e3a7aSWarner Losh 98278e3e3a7aSWarner Losh 98288e3e3a7aSWarner Losh 98298e3e3a7aSWarner Losh 98308e3e3a7aSWarner Losh 98318e3e3a7aSWarner Losh 98328e3e3a7aSWarner Losh 98338e3e3a7aSWarner Losh<h2>6.5 – <a name="6.5">UTF-8 Support</a></h2> 98348e3e3a7aSWarner Losh 98358e3e3a7aSWarner Losh<p> 98368e3e3a7aSWarner LoshThis library provides basic support for UTF-8 encoding. 98378e3e3a7aSWarner LoshIt provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>. 98388e3e3a7aSWarner LoshThis library does not provide any support for Unicode other 98398e3e3a7aSWarner Loshthan the handling of the encoding. 98408e3e3a7aSWarner LoshAny operation that needs the meaning of a character, 98418e3e3a7aSWarner Loshsuch as character classification, is outside its scope. 98428e3e3a7aSWarner Losh 98438e3e3a7aSWarner Losh 98448e3e3a7aSWarner Losh<p> 98458e3e3a7aSWarner LoshUnless stated otherwise, 98468e3e3a7aSWarner Loshall functions that expect a byte position as a parameter 98478e3e3a7aSWarner Loshassume that the given position is either the start of a byte sequence 98488e3e3a7aSWarner Loshor one plus the length of the subject string. 98498e3e3a7aSWarner LoshAs in the string library, 98508e3e3a7aSWarner Loshnegative indices count from the end of the string. 98518e3e3a7aSWarner Losh 98528e3e3a7aSWarner Losh 98538e3e3a7aSWarner Losh<p> 98540495ed39SKyle EvansFunctions that create byte sequences 98550495ed39SKyle Evansaccept all values up to <code>0x7FFFFFFF</code>, 98560495ed39SKyle Evansas defined in the original UTF-8 specification; 98570495ed39SKyle Evansthat implies byte sequences of up to six bytes. 98580495ed39SKyle Evans 98590495ed39SKyle Evans 98600495ed39SKyle Evans<p> 98610495ed39SKyle EvansFunctions that interpret byte sequences only accept 98620495ed39SKyle Evansvalid sequences (well formed and not overlong). 98630495ed39SKyle EvansBy default, they only accept byte sequences 98640495ed39SKyle Evansthat result in valid Unicode code points, 98650495ed39SKyle Evansrejecting values greater than <code>10FFFF</code> and surrogates. 98660495ed39SKyle EvansA boolean argument <code>lax</code>, when available, 98670495ed39SKyle Evanslifts these checks, 98680495ed39SKyle Evansso that all values up to <code>0x7FFFFFFF</code> are accepted. 98690495ed39SKyle Evans(Not well formed and overlong sequences are still rejected.) 98700495ed39SKyle Evans 98710495ed39SKyle Evans 98720495ed39SKyle Evans<p> 98738e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3> 98740495ed39SKyle Evans 98750495ed39SKyle Evans 98760495ed39SKyle Evans<p> 98778e3e3a7aSWarner LoshReceives zero or more integers, 98788e3e3a7aSWarner Loshconverts each one to its corresponding UTF-8 byte sequence 98798e3e3a7aSWarner Loshand returns a string with the concatenation of all these sequences. 98808e3e3a7aSWarner Losh 98818e3e3a7aSWarner Losh 98828e3e3a7aSWarner Losh 98838e3e3a7aSWarner Losh 98848e3e3a7aSWarner Losh<p> 98858e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3> 98860495ed39SKyle Evans 98870495ed39SKyle Evans 98880495ed39SKyle Evans<p> 98890495ed39SKyle EvansThe pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xFD][\x80-\xBF]*</code>" 98908e3e3a7aSWarner Losh(see <a href="#6.4.1">§6.4.1</a>), 98918e3e3a7aSWarner Loshwhich matches exactly one UTF-8 byte sequence, 98928e3e3a7aSWarner Loshassuming that the subject is a valid UTF-8 string. 98938e3e3a7aSWarner Losh 98948e3e3a7aSWarner Losh 98958e3e3a7aSWarner Losh 98968e3e3a7aSWarner Losh 98978e3e3a7aSWarner Losh<p> 98980495ed39SKyle Evans<hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s [, lax])</code></a></h3> 98998e3e3a7aSWarner Losh 99008e3e3a7aSWarner Losh 99018e3e3a7aSWarner Losh<p> 99028e3e3a7aSWarner LoshReturns values so that the construction 99038e3e3a7aSWarner Losh 99048e3e3a7aSWarner Losh<pre> 99058e3e3a7aSWarner Losh for p, c in utf8.codes(s) do <em>body</em> end 99068e3e3a7aSWarner Losh</pre><p> 99070495ed39SKyle Evanswill iterate over all UTF-8 characters in string <code>s</code>, 99088e3e3a7aSWarner Loshwith <code>p</code> being the position (in bytes) and <code>c</code> the code point 99098e3e3a7aSWarner Loshof each character. 99108e3e3a7aSWarner LoshIt raises an error if it meets any invalid byte sequence. 99118e3e3a7aSWarner Losh 99128e3e3a7aSWarner Losh 99138e3e3a7aSWarner Losh 99148e3e3a7aSWarner Losh 99158e3e3a7aSWarner Losh<p> 99160495ed39SKyle Evans<hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j [, lax]]])</code></a></h3> 99170495ed39SKyle Evans 99180495ed39SKyle Evans 99190495ed39SKyle Evans<p> 99208e3e3a7aSWarner LoshReturns the code points (as integers) from all characters in <code>s</code> 99218e3e3a7aSWarner Loshthat start between byte position <code>i</code> and <code>j</code> (both included). 99228e3e3a7aSWarner LoshThe default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>. 99238e3e3a7aSWarner LoshIt raises an error if it meets any invalid byte sequence. 99248e3e3a7aSWarner Losh 99258e3e3a7aSWarner Losh 99268e3e3a7aSWarner Losh 99278e3e3a7aSWarner Losh 99288e3e3a7aSWarner Losh<p> 99290495ed39SKyle Evans<hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j [, lax]]])</code></a></h3> 99300495ed39SKyle Evans 99310495ed39SKyle Evans 99320495ed39SKyle Evans<p> 99338e3e3a7aSWarner LoshReturns the number of UTF-8 characters in string <code>s</code> 99348e3e3a7aSWarner Loshthat start between positions <code>i</code> and <code>j</code> (both inclusive). 99358e3e3a7aSWarner LoshThe default for <code>i</code> is 1 and for <code>j</code> is -1. 99368e3e3a7aSWarner LoshIf it finds any invalid byte sequence, 99370495ed39SKyle Evansreturns <b>fail</b> plus the position of the first invalid byte. 99388e3e3a7aSWarner Losh 99398e3e3a7aSWarner Losh 99408e3e3a7aSWarner Losh 99418e3e3a7aSWarner Losh 99428e3e3a7aSWarner Losh<p> 99438e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3> 99440495ed39SKyle Evans 99450495ed39SKyle Evans 99460495ed39SKyle Evans<p> 99478e3e3a7aSWarner LoshReturns the position (in bytes) where the encoding of the 99488e3e3a7aSWarner Losh<code>n</code>-th character of <code>s</code> 99498e3e3a7aSWarner Losh(counting from position <code>i</code>) starts. 99508e3e3a7aSWarner LoshA negative <code>n</code> gets characters before position <code>i</code>. 99518e3e3a7aSWarner LoshThe default for <code>i</code> is 1 when <code>n</code> is non-negative 99528e3e3a7aSWarner Loshand <code>#s + 1</code> otherwise, 99538e3e3a7aSWarner Loshso that <code>utf8.offset(s, -n)</code> gets the offset of the 99548e3e3a7aSWarner Losh<code>n</code>-th character from the end of the string. 99558e3e3a7aSWarner LoshIf the specified character is neither in the subject 99568e3e3a7aSWarner Loshnor right after its end, 99570495ed39SKyle Evansthe function returns <b>fail</b>. 99588e3e3a7aSWarner Losh 99598e3e3a7aSWarner Losh 99608e3e3a7aSWarner Losh<p> 99618e3e3a7aSWarner LoshAs a special case, 99628e3e3a7aSWarner Loshwhen <code>n</code> is 0 the function returns the start of the encoding 99638e3e3a7aSWarner Loshof the character that contains the <code>i</code>-th byte of <code>s</code>. 99648e3e3a7aSWarner Losh 99658e3e3a7aSWarner Losh 99668e3e3a7aSWarner Losh<p> 99678e3e3a7aSWarner LoshThis function assumes that <code>s</code> is a valid UTF-8 string. 99688e3e3a7aSWarner Losh 99698e3e3a7aSWarner Losh 99708e3e3a7aSWarner Losh 99718e3e3a7aSWarner Losh 99728e3e3a7aSWarner Losh 99738e3e3a7aSWarner Losh 99748e3e3a7aSWarner Losh 99758e3e3a7aSWarner Losh<h2>6.6 – <a name="6.6">Table Manipulation</a></h2> 99768e3e3a7aSWarner Losh 99778e3e3a7aSWarner Losh<p> 99788e3e3a7aSWarner LoshThis library provides generic functions for table manipulation. 99798e3e3a7aSWarner LoshIt provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. 99808e3e3a7aSWarner Losh 99818e3e3a7aSWarner Losh 99828e3e3a7aSWarner Losh<p> 99838e3e3a7aSWarner LoshRemember that, whenever an operation needs the length of a table, 99848e3e3a7aSWarner Loshall caveats about the length operator apply (see <a href="#3.4.7">§3.4.7</a>). 99858e3e3a7aSWarner LoshAll functions ignore non-numeric keys 99868e3e3a7aSWarner Loshin the tables given as arguments. 99878e3e3a7aSWarner Losh 99888e3e3a7aSWarner Losh 99898e3e3a7aSWarner Losh<p> 99908e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3> 99918e3e3a7aSWarner Losh 99928e3e3a7aSWarner Losh 99938e3e3a7aSWarner Losh<p> 99948e3e3a7aSWarner LoshGiven a list where all elements are strings or numbers, 99958e3e3a7aSWarner Loshreturns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>. 99968e3e3a7aSWarner LoshThe default value for <code>sep</code> is the empty string, 99978e3e3a7aSWarner Loshthe default for <code>i</code> is 1, 99988e3e3a7aSWarner Loshand the default for <code>j</code> is <code>#list</code>. 99998e3e3a7aSWarner LoshIf <code>i</code> is greater than <code>j</code>, returns the empty string. 100008e3e3a7aSWarner Losh 100018e3e3a7aSWarner Losh 100028e3e3a7aSWarner Losh 100038e3e3a7aSWarner Losh 100048e3e3a7aSWarner Losh<p> 100058e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3> 100068e3e3a7aSWarner Losh 100078e3e3a7aSWarner Losh 100088e3e3a7aSWarner Losh<p> 100098e3e3a7aSWarner LoshInserts element <code>value</code> at position <code>pos</code> in <code>list</code>, 100108e3e3a7aSWarner Loshshifting up the elements 100118e3e3a7aSWarner Losh<code>list[pos], list[pos+1], ···, list[#list]</code>. 100128e3e3a7aSWarner LoshThe default value for <code>pos</code> is <code>#list+1</code>, 100138e3e3a7aSWarner Loshso that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end 100140495ed39SKyle Evansof the list <code>t</code>. 100158e3e3a7aSWarner Losh 100168e3e3a7aSWarner Losh 100178e3e3a7aSWarner Losh 100188e3e3a7aSWarner Losh 100198e3e3a7aSWarner Losh<p> 100208e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3> 100218e3e3a7aSWarner Losh 100228e3e3a7aSWarner Losh 100238e3e3a7aSWarner Losh<p> 100240495ed39SKyle EvansMoves elements from the table <code>a1</code> to the table <code>a2</code>, 100258e3e3a7aSWarner Loshperforming the equivalent to the following 100268e3e3a7aSWarner Loshmultiple assignment: 100278e3e3a7aSWarner Losh<code>a2[t],··· = a1[f],···,a1[e]</code>. 100288e3e3a7aSWarner LoshThe default for <code>a2</code> is <code>a1</code>. 100298e3e3a7aSWarner LoshThe destination range can overlap with the source range. 100308e3e3a7aSWarner LoshThe number of elements to be moved must fit in a Lua integer. 100318e3e3a7aSWarner Losh 100328e3e3a7aSWarner Losh 100338e3e3a7aSWarner Losh<p> 100348e3e3a7aSWarner LoshReturns the destination table <code>a2</code>. 100358e3e3a7aSWarner Losh 100368e3e3a7aSWarner Losh 100378e3e3a7aSWarner Losh 100388e3e3a7aSWarner Losh 100398e3e3a7aSWarner Losh<p> 100408e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3> 100418e3e3a7aSWarner Losh 100428e3e3a7aSWarner Losh 100438e3e3a7aSWarner Losh<p> 10044e112e9d2SKyle EvansReturns a new table with all arguments stored into keys 1, 2, etc. 10045e112e9d2SKyle Evansand with a field "<code>n</code>" with the total number of arguments. 100460495ed39SKyle EvansNote that the resulting table may not be a sequence, 100470495ed39SKyle Evansif some arguments are <b>nil</b>. 100488e3e3a7aSWarner Losh 100498e3e3a7aSWarner Losh 100508e3e3a7aSWarner Losh 100518e3e3a7aSWarner Losh 100528e3e3a7aSWarner Losh<p> 100538e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3> 100548e3e3a7aSWarner Losh 100558e3e3a7aSWarner Losh 100568e3e3a7aSWarner Losh<p> 100578e3e3a7aSWarner LoshRemoves from <code>list</code> the element at position <code>pos</code>, 100588e3e3a7aSWarner Loshreturning the value of the removed element. 100598e3e3a7aSWarner LoshWhen <code>pos</code> is an integer between 1 and <code>#list</code>, 100608e3e3a7aSWarner Loshit shifts down the elements 100618e3e3a7aSWarner Losh<code>list[pos+1], list[pos+2], ···, list[#list]</code> 100628e3e3a7aSWarner Loshand erases element <code>list[#list]</code>; 100638e3e3a7aSWarner LoshThe index <code>pos</code> can also be 0 when <code>#list</code> is 0, 100640495ed39SKyle Evansor <code>#list + 1</code>. 100658e3e3a7aSWarner Losh 100668e3e3a7aSWarner Losh 100678e3e3a7aSWarner Losh<p> 100688e3e3a7aSWarner LoshThe default value for <code>pos</code> is <code>#list</code>, 100698e3e3a7aSWarner Loshso that a call <code>table.remove(l)</code> removes the last element 100700495ed39SKyle Evansof the list <code>l</code>. 100718e3e3a7aSWarner Losh 100728e3e3a7aSWarner Losh 100738e3e3a7aSWarner Losh 100748e3e3a7aSWarner Losh 100758e3e3a7aSWarner Losh<p> 100768e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3> 100778e3e3a7aSWarner Losh 100788e3e3a7aSWarner Losh 100798e3e3a7aSWarner Losh<p> 100800495ed39SKyle EvansSorts the list elements in a given order, <em>in-place</em>, 100818e3e3a7aSWarner Loshfrom <code>list[1]</code> to <code>list[#list]</code>. 100828e3e3a7aSWarner LoshIf <code>comp</code> is given, 100838e3e3a7aSWarner Loshthen it must be a function that receives two list elements 100848e3e3a7aSWarner Loshand returns true when the first element must come 100858c784bb8SWarner Loshbefore the second in the final order, 100868c784bb8SWarner Loshso that, after the sort, 100878c784bb8SWarner Losh<code>i <= j</code> implies <code>not comp(list[j],list[i])</code>. 100888e3e3a7aSWarner LoshIf <code>comp</code> is not given, 100898e3e3a7aSWarner Loshthen the standard Lua operator <code><</code> is used instead. 100908e3e3a7aSWarner Losh 100918e3e3a7aSWarner Losh 100928e3e3a7aSWarner Losh<p> 100938c784bb8SWarner LoshThe <code>comp</code> function must define a consistent order; 100948c784bb8SWarner Loshmore formally, the function must define a strict weak order. 100958c784bb8SWarner Losh(A weak order is similar to a total order, 100968c784bb8SWarner Loshbut it can equate different elements for comparison purposes.) 100978e3e3a7aSWarner Losh 100988e3e3a7aSWarner Losh 100998e3e3a7aSWarner Losh<p> 101008e3e3a7aSWarner LoshThe sort algorithm is not stable: 101018c784bb8SWarner LoshDifferent elements considered equal by the given order 101028e3e3a7aSWarner Loshmay have their relative positions changed by the sort. 101038e3e3a7aSWarner Losh 101048e3e3a7aSWarner Losh 101058e3e3a7aSWarner Losh 101068e3e3a7aSWarner Losh 101078e3e3a7aSWarner Losh<p> 101088e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3> 101098e3e3a7aSWarner Losh 101108e3e3a7aSWarner Losh 101118e3e3a7aSWarner Losh<p> 101128e3e3a7aSWarner LoshReturns the elements from the given list. 101138e3e3a7aSWarner LoshThis function is equivalent to 101148e3e3a7aSWarner Losh 101158e3e3a7aSWarner Losh<pre> 101168e3e3a7aSWarner Losh return list[i], list[i+1], ···, list[j] 101178e3e3a7aSWarner Losh</pre><p> 101188e3e3a7aSWarner LoshBy default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>. 101198e3e3a7aSWarner Losh 101208e3e3a7aSWarner Losh 101218e3e3a7aSWarner Losh 101228e3e3a7aSWarner Losh 101238e3e3a7aSWarner Losh 101248e3e3a7aSWarner Losh 101258e3e3a7aSWarner Losh 101268e3e3a7aSWarner Losh<h2>6.7 – <a name="6.7">Mathematical Functions</a></h2> 101278e3e3a7aSWarner Losh 101288e3e3a7aSWarner Losh<p> 101298e3e3a7aSWarner LoshThis library provides basic mathematical functions. 101308e3e3a7aSWarner LoshIt provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>. 101318e3e3a7aSWarner LoshFunctions with the annotation "<code>integer/float</code>" give 101328e3e3a7aSWarner Loshinteger results for integer arguments 101330495ed39SKyle Evansand float results for non-integer arguments. 101340495ed39SKyle EvansThe rounding functions 101350495ed39SKyle Evans<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> 101368e3e3a7aSWarner Loshreturn an integer when the result fits in the range of an integer, 101378e3e3a7aSWarner Loshor a float otherwise. 101388e3e3a7aSWarner Losh 101398e3e3a7aSWarner Losh 101408e3e3a7aSWarner Losh<p> 101418e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> 101428e3e3a7aSWarner Losh 101438e3e3a7aSWarner Losh 101448e3e3a7aSWarner Losh<p> 101450495ed39SKyle EvansReturns the maximum value between <code>x</code> and <code>-x</code>. (integer/float) 101468e3e3a7aSWarner Losh 101478e3e3a7aSWarner Losh 101488e3e3a7aSWarner Losh 101498e3e3a7aSWarner Losh 101508e3e3a7aSWarner Losh<p> 101518e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> 101528e3e3a7aSWarner Losh 101538e3e3a7aSWarner Losh 101548e3e3a7aSWarner Losh<p> 101558e3e3a7aSWarner LoshReturns the arc cosine of <code>x</code> (in radians). 101568e3e3a7aSWarner Losh 101578e3e3a7aSWarner Losh 101588e3e3a7aSWarner Losh 101598e3e3a7aSWarner Losh 101608e3e3a7aSWarner Losh<p> 101618e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> 101628e3e3a7aSWarner Losh 101638e3e3a7aSWarner Losh 101648e3e3a7aSWarner Losh<p> 101658e3e3a7aSWarner LoshReturns the arc sine of <code>x</code> (in radians). 101668e3e3a7aSWarner Losh 101678e3e3a7aSWarner Losh 101688e3e3a7aSWarner Losh 101698e3e3a7aSWarner Losh 101708e3e3a7aSWarner Losh<p> 101718e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3> 101728e3e3a7aSWarner Losh 101738e3e3a7aSWarner Losh 101748e3e3a7aSWarner Losh<p> 101758e3e3a7aSWarner Losh 101768e3e3a7aSWarner LoshReturns the arc tangent of <code>y/x</code> (in radians), 10177*a9490b81SWarner Loshusing the signs of both arguments to find the 101788e3e3a7aSWarner Loshquadrant of the result. 101790495ed39SKyle EvansIt also handles correctly the case of <code>x</code> being zero. 101808e3e3a7aSWarner Losh 101818e3e3a7aSWarner Losh 101828e3e3a7aSWarner Losh<p> 101838e3e3a7aSWarner LoshThe default value for <code>x</code> is 1, 101848e3e3a7aSWarner Loshso that the call <code>math.atan(y)</code> 101858e3e3a7aSWarner Loshreturns the arc tangent of <code>y</code>. 101868e3e3a7aSWarner Losh 101878e3e3a7aSWarner Losh 101888e3e3a7aSWarner Losh 101898e3e3a7aSWarner Losh 101908e3e3a7aSWarner Losh<p> 101918e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> 101928e3e3a7aSWarner Losh 101938e3e3a7aSWarner Losh 101948e3e3a7aSWarner Losh<p> 101950495ed39SKyle EvansReturns the smallest integral value greater than or equal to <code>x</code>. 101968e3e3a7aSWarner Losh 101978e3e3a7aSWarner Losh 101988e3e3a7aSWarner Losh 101998e3e3a7aSWarner Losh 102008e3e3a7aSWarner Losh<p> 102018e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> 102028e3e3a7aSWarner Losh 102038e3e3a7aSWarner Losh 102048e3e3a7aSWarner Losh<p> 102058e3e3a7aSWarner LoshReturns the cosine of <code>x</code> (assumed to be in radians). 102068e3e3a7aSWarner Losh 102078e3e3a7aSWarner Losh 102088e3e3a7aSWarner Losh 102098e3e3a7aSWarner Losh 102108e3e3a7aSWarner Losh<p> 102118e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> 102128e3e3a7aSWarner Losh 102138e3e3a7aSWarner Losh 102148e3e3a7aSWarner Losh<p> 102158e3e3a7aSWarner LoshConverts the angle <code>x</code> from radians to degrees. 102168e3e3a7aSWarner Losh 102178e3e3a7aSWarner Losh 102188e3e3a7aSWarner Losh 102198e3e3a7aSWarner Losh 102208e3e3a7aSWarner Losh<p> 102218e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> 102228e3e3a7aSWarner Losh 102238e3e3a7aSWarner Losh 102248e3e3a7aSWarner Losh<p> 102258e3e3a7aSWarner LoshReturns the value <em>e<sup>x</sup></em> 102268e3e3a7aSWarner Losh(where <code>e</code> is the base of natural logarithms). 102278e3e3a7aSWarner Losh 102288e3e3a7aSWarner Losh 102298e3e3a7aSWarner Losh 102308e3e3a7aSWarner Losh 102318e3e3a7aSWarner Losh<p> 102328e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> 102338e3e3a7aSWarner Losh 102348e3e3a7aSWarner Losh 102358e3e3a7aSWarner Losh<p> 102360495ed39SKyle EvansReturns the largest integral value less than or equal to <code>x</code>. 102378e3e3a7aSWarner Losh 102388e3e3a7aSWarner Losh 102398e3e3a7aSWarner Losh 102408e3e3a7aSWarner Losh 102418e3e3a7aSWarner Losh<p> 102428e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> 102438e3e3a7aSWarner Losh 102448e3e3a7aSWarner Losh 102458e3e3a7aSWarner Losh<p> 102468e3e3a7aSWarner LoshReturns the remainder of the division of <code>x</code> by <code>y</code> 102478e3e3a7aSWarner Loshthat rounds the quotient towards zero. (integer/float) 102488e3e3a7aSWarner Losh 102498e3e3a7aSWarner Losh 102508e3e3a7aSWarner Losh 102518e3e3a7aSWarner Losh 102528e3e3a7aSWarner Losh<p> 102538e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> 102548e3e3a7aSWarner Losh 102558e3e3a7aSWarner Losh 102568e3e3a7aSWarner Losh<p> 102578e3e3a7aSWarner LoshThe float value <code>HUGE_VAL</code>, 102580495ed39SKyle Evansa value greater than any other numeric value. 102598e3e3a7aSWarner Losh 102608e3e3a7aSWarner Losh 102618e3e3a7aSWarner Losh 102628e3e3a7aSWarner Losh 102638e3e3a7aSWarner Losh<p> 102648e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3> 102658e3e3a7aSWarner Losh 102668e3e3a7aSWarner Losh 102678e3e3a7aSWarner Losh<p> 102688e3e3a7aSWarner LoshReturns the logarithm of <code>x</code> in the given base. 102698e3e3a7aSWarner LoshThe default for <code>base</code> is <em>e</em> 102708e3e3a7aSWarner Losh(so that the function returns the natural logarithm of <code>x</code>). 102718e3e3a7aSWarner Losh 102728e3e3a7aSWarner Losh 102738e3e3a7aSWarner Losh 102748e3e3a7aSWarner Losh 102758e3e3a7aSWarner Losh<p> 102768e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> 102778e3e3a7aSWarner Losh 102788e3e3a7aSWarner Losh 102798e3e3a7aSWarner Losh<p> 102808e3e3a7aSWarner LoshReturns the argument with the maximum value, 102810495ed39SKyle Evansaccording to the Lua operator <code><</code>. 102828e3e3a7aSWarner Losh 102838e3e3a7aSWarner Losh 102848e3e3a7aSWarner Losh 102858e3e3a7aSWarner Losh 102868e3e3a7aSWarner Losh<p> 102878e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3> 102888e3e3a7aSWarner LoshAn integer with the maximum value for an integer. 102898e3e3a7aSWarner Losh 102908e3e3a7aSWarner Losh 102918e3e3a7aSWarner Losh 102928e3e3a7aSWarner Losh 102938e3e3a7aSWarner Losh<p> 102948e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> 102958e3e3a7aSWarner Losh 102968e3e3a7aSWarner Losh 102978e3e3a7aSWarner Losh<p> 102988e3e3a7aSWarner LoshReturns the argument with the minimum value, 102990495ed39SKyle Evansaccording to the Lua operator <code><</code>. 103008e3e3a7aSWarner Losh 103018e3e3a7aSWarner Losh 103028e3e3a7aSWarner Losh 103038e3e3a7aSWarner Losh 103048e3e3a7aSWarner Losh<p> 103058e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3> 103068e3e3a7aSWarner LoshAn integer with the minimum value for an integer. 103078e3e3a7aSWarner Losh 103088e3e3a7aSWarner Losh 103098e3e3a7aSWarner Losh 103108e3e3a7aSWarner Losh 103118e3e3a7aSWarner Losh<p> 103128e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> 103138e3e3a7aSWarner Losh 103148e3e3a7aSWarner Losh 103158e3e3a7aSWarner Losh<p> 103168e3e3a7aSWarner LoshReturns the integral part of <code>x</code> and the fractional part of <code>x</code>. 103178e3e3a7aSWarner LoshIts second result is always a float. 103188e3e3a7aSWarner Losh 103198e3e3a7aSWarner Losh 103208e3e3a7aSWarner Losh 103218e3e3a7aSWarner Losh 103228e3e3a7aSWarner Losh<p> 103238e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> 103248e3e3a7aSWarner Losh 103258e3e3a7aSWarner Losh 103268e3e3a7aSWarner Losh<p> 103278e3e3a7aSWarner LoshThe value of <em>π</em>. 103288e3e3a7aSWarner Losh 103298e3e3a7aSWarner Losh 103308e3e3a7aSWarner Losh 103318e3e3a7aSWarner Losh 103328e3e3a7aSWarner Losh<p> 103338e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> 103348e3e3a7aSWarner Losh 103358e3e3a7aSWarner Losh 103368e3e3a7aSWarner Losh<p> 103378e3e3a7aSWarner LoshConverts the angle <code>x</code> from degrees to radians. 103388e3e3a7aSWarner Losh 103398e3e3a7aSWarner Losh 103408e3e3a7aSWarner Losh 103418e3e3a7aSWarner Losh 103428e3e3a7aSWarner Losh<p> 103438e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> 103448e3e3a7aSWarner Losh 103458e3e3a7aSWarner Losh 103468e3e3a7aSWarner Losh<p> 103478e3e3a7aSWarner LoshWhen called without arguments, 103488e3e3a7aSWarner Loshreturns a pseudo-random float with uniform distribution 103498e3e3a7aSWarner Loshin the range <em>[0,1)</em>. 103508e3e3a7aSWarner LoshWhen called with two integers <code>m</code> and <code>n</code>, 103518e3e3a7aSWarner Losh<code>math.random</code> returns a pseudo-random integer 103528e3e3a7aSWarner Loshwith uniform distribution in the range <em>[m, n]</em>. 103530495ed39SKyle EvansThe call <code>math.random(n)</code>, for a positive <code>n</code>, 103540495ed39SKyle Evansis equivalent to <code>math.random(1,n)</code>. 103550495ed39SKyle EvansThe call <code>math.random(0)</code> produces an integer with 103560495ed39SKyle Evansall bits (pseudo)random. 103578e3e3a7aSWarner Losh 103588e3e3a7aSWarner Losh 103598e3e3a7aSWarner Losh<p> 103600495ed39SKyle EvansThis function uses the <code>xoshiro256**</code> algorithm to produce 103610495ed39SKyle Evanspseudo-random 64-bit integers, 103620495ed39SKyle Evanswhich are the results of calls with argument 0. 103630495ed39SKyle EvansOther results (ranges and floats) 103640495ed39SKyle Evansare unbiased extracted from these integers. 103650495ed39SKyle Evans 103660495ed39SKyle Evans 103670495ed39SKyle Evans<p> 103680495ed39SKyle EvansLua initializes its pseudo-random generator with the equivalent of 103690495ed39SKyle Evansa call to <a href="#pdf-math.randomseed"><code>math.randomseed</code></a> with no arguments, 103700495ed39SKyle Evansso that <code>math.random</code> should generate 103710495ed39SKyle Evansdifferent sequences of results each time the program runs. 103728e3e3a7aSWarner Losh 103738e3e3a7aSWarner Losh 103748e3e3a7aSWarner Losh 103758e3e3a7aSWarner Losh 103768e3e3a7aSWarner Losh<p> 103770495ed39SKyle Evans<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed ([x [, y]])</code></a></h3> 103788e3e3a7aSWarner Losh 103798e3e3a7aSWarner Losh 103808e3e3a7aSWarner Losh<p> 103810495ed39SKyle EvansWhen called with at least one argument, 103820495ed39SKyle Evansthe integer parameters <code>x</code> and <code>y</code> are 103830495ed39SKyle Evansjoined into a 128-bit <em>seed</em> that 103840495ed39SKyle Evansis used to reinitialize the pseudo-random generator; 103858e3e3a7aSWarner Loshequal seeds produce equal sequences of numbers. 103860495ed39SKyle EvansThe default for <code>y</code> is zero. 103870495ed39SKyle Evans 103880495ed39SKyle Evans 103890495ed39SKyle Evans<p> 103900495ed39SKyle EvansWhen called with no arguments, 103910495ed39SKyle EvansLua generates a seed with 103920495ed39SKyle Evansa weak attempt for randomness. 103930495ed39SKyle Evans 103940495ed39SKyle Evans 103950495ed39SKyle Evans<p> 103960495ed39SKyle EvansThis function returns the two seed components 103970495ed39SKyle Evansthat were effectively used, 103980495ed39SKyle Evansso that setting them again repeats the sequence. 103990495ed39SKyle Evans 104000495ed39SKyle Evans 104010495ed39SKyle Evans<p> 104020495ed39SKyle EvansTo ensure a required level of randomness to the initial state 104030495ed39SKyle Evans(or contrarily, to have a deterministic sequence, 104040495ed39SKyle Evansfor instance when debugging a program), 104050495ed39SKyle Evansyou should call <a href="#pdf-math.randomseed"><code>math.randomseed</code></a> with explicit arguments. 104068e3e3a7aSWarner Losh 104078e3e3a7aSWarner Losh 104088e3e3a7aSWarner Losh 104098e3e3a7aSWarner Losh 104108e3e3a7aSWarner Losh<p> 104118e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> 104128e3e3a7aSWarner Losh 104138e3e3a7aSWarner Losh 104148e3e3a7aSWarner Losh<p> 104158e3e3a7aSWarner LoshReturns the sine of <code>x</code> (assumed to be in radians). 104168e3e3a7aSWarner Losh 104178e3e3a7aSWarner Losh 104188e3e3a7aSWarner Losh 104198e3e3a7aSWarner Losh 104208e3e3a7aSWarner Losh<p> 104218e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> 104228e3e3a7aSWarner Losh 104238e3e3a7aSWarner Losh 104248e3e3a7aSWarner Losh<p> 104258e3e3a7aSWarner LoshReturns the square root of <code>x</code>. 104268e3e3a7aSWarner Losh(You can also use the expression <code>x^0.5</code> to compute this value.) 104278e3e3a7aSWarner Losh 104288e3e3a7aSWarner Losh 104298e3e3a7aSWarner Losh 104308e3e3a7aSWarner Losh 104318e3e3a7aSWarner Losh<p> 104328e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> 104338e3e3a7aSWarner Losh 104348e3e3a7aSWarner Losh 104358e3e3a7aSWarner Losh<p> 104368e3e3a7aSWarner LoshReturns the tangent of <code>x</code> (assumed to be in radians). 104378e3e3a7aSWarner Losh 104388e3e3a7aSWarner Losh 104398e3e3a7aSWarner Losh 104408e3e3a7aSWarner Losh 104418e3e3a7aSWarner Losh<p> 104428e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3> 104438e3e3a7aSWarner Losh 104448e3e3a7aSWarner Losh 104458e3e3a7aSWarner Losh<p> 104468e3e3a7aSWarner LoshIf the value <code>x</code> is convertible to an integer, 104478e3e3a7aSWarner Loshreturns that integer. 104480495ed39SKyle EvansOtherwise, returns <b>fail</b>. 104498e3e3a7aSWarner Losh 104508e3e3a7aSWarner Losh 104518e3e3a7aSWarner Losh 104528e3e3a7aSWarner Losh 104538e3e3a7aSWarner Losh<p> 104548e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3> 104558e3e3a7aSWarner Losh 104568e3e3a7aSWarner Losh 104578e3e3a7aSWarner Losh<p> 104588e3e3a7aSWarner LoshReturns "<code>integer</code>" if <code>x</code> is an integer, 104598e3e3a7aSWarner Losh"<code>float</code>" if it is a float, 104600495ed39SKyle Evansor <b>fail</b> if <code>x</code> is not a number. 104618e3e3a7aSWarner Losh 104628e3e3a7aSWarner Losh 104638e3e3a7aSWarner Losh 104648e3e3a7aSWarner Losh 104658e3e3a7aSWarner Losh<p> 104668e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3> 104678e3e3a7aSWarner Losh 104688e3e3a7aSWarner Losh 104698e3e3a7aSWarner Losh<p> 104708e3e3a7aSWarner LoshReturns a boolean, 104718c784bb8SWarner Losh<b>true</b> if and only if integer <code>m</code> is below integer <code>n</code> when 104728e3e3a7aSWarner Loshthey are compared as unsigned integers. 104738e3e3a7aSWarner Losh 104748e3e3a7aSWarner Losh 104758e3e3a7aSWarner Losh 104768e3e3a7aSWarner Losh 104778e3e3a7aSWarner Losh 104788e3e3a7aSWarner Losh 104798e3e3a7aSWarner Losh 104808e3e3a7aSWarner Losh<h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2> 104818e3e3a7aSWarner Losh 104828e3e3a7aSWarner Losh<p> 104838e3e3a7aSWarner LoshThe I/O library provides two different styles for file manipulation. 104848e3e3a7aSWarner LoshThe first one uses implicit file handles; 104858e3e3a7aSWarner Loshthat is, there are operations to set a default input file and a 104868e3e3a7aSWarner Loshdefault output file, 104870495ed39SKyle Evansand all input/output operations are done over these default files. 104888e3e3a7aSWarner LoshThe second style uses explicit file handles. 104898e3e3a7aSWarner Losh 104908e3e3a7aSWarner Losh 104918e3e3a7aSWarner Losh<p> 104928e3e3a7aSWarner LoshWhen using implicit file handles, 104938e3e3a7aSWarner Loshall operations are supplied by table <a name="pdf-io"><code>io</code></a>. 104948e3e3a7aSWarner LoshWhen using explicit file handles, 104958e3e3a7aSWarner Loshthe operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle 104968e3e3a7aSWarner Loshand then all operations are supplied as methods of the file handle. 104978e3e3a7aSWarner Losh 104988e3e3a7aSWarner Losh 104998e3e3a7aSWarner Losh<p> 105000495ed39SKyle EvansThe metatable for file handles provides metamethods 105010495ed39SKyle Evansfor <code>__gc</code> and <code>__close</code> that try 105020495ed39SKyle Evansto close the file when called. 105030495ed39SKyle Evans 105040495ed39SKyle Evans 105050495ed39SKyle Evans<p> 105068e3e3a7aSWarner LoshThe table <code>io</code> also provides 105078e3e3a7aSWarner Loshthree predefined file handles with their usual meanings from C: 105088e3e3a7aSWarner 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>. 105098e3e3a7aSWarner LoshThe I/O library never closes these files. 105108e3e3a7aSWarner Losh 105118e3e3a7aSWarner Losh 105128e3e3a7aSWarner Losh<p> 105138e3e3a7aSWarner LoshUnless otherwise stated, 105140495ed39SKyle Evansall I/O functions return <b>fail</b> on failure, 105150495ed39SKyle Evansplus an error message as a second result and 105160495ed39SKyle Evansa system-dependent error code as a third result, 105170495ed39SKyle Evansand some non-false value on success. 105180495ed39SKyle EvansOn non-POSIX systems, 105198e3e3a7aSWarner Loshthe computation of the error message and error code 105208e3e3a7aSWarner Loshin case of errors 105218e3e3a7aSWarner Loshmay be not thread safe, 105228e3e3a7aSWarner Loshbecause they rely on the global C variable <code>errno</code>. 105238e3e3a7aSWarner Losh 105248e3e3a7aSWarner Losh 105258e3e3a7aSWarner Losh<p> 105268e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> 105278e3e3a7aSWarner Losh 105288e3e3a7aSWarner Losh 105298e3e3a7aSWarner Losh<p> 105308e3e3a7aSWarner LoshEquivalent to <code>file:close()</code>. 105318e3e3a7aSWarner LoshWithout a <code>file</code>, closes the default output file. 105328e3e3a7aSWarner Losh 105338e3e3a7aSWarner Losh 105348e3e3a7aSWarner Losh 105358e3e3a7aSWarner Losh 105368e3e3a7aSWarner Losh<p> 105378e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> 105388e3e3a7aSWarner Losh 105398e3e3a7aSWarner Losh 105408e3e3a7aSWarner Losh<p> 105418e3e3a7aSWarner LoshEquivalent to <code>io.output():flush()</code>. 105428e3e3a7aSWarner Losh 105438e3e3a7aSWarner Losh 105448e3e3a7aSWarner Losh 105458e3e3a7aSWarner Losh 105468e3e3a7aSWarner Losh<p> 105478e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> 105488e3e3a7aSWarner Losh 105498e3e3a7aSWarner Losh 105508e3e3a7aSWarner Losh<p> 105518e3e3a7aSWarner LoshWhen called with a file name, it opens the named file (in text mode), 105528e3e3a7aSWarner Loshand sets its handle as the default input file. 105538e3e3a7aSWarner LoshWhen called with a file handle, 105548e3e3a7aSWarner Loshit simply sets this file handle as the default input file. 10555e112e9d2SKyle EvansWhen called without arguments, 105568e3e3a7aSWarner Loshit returns the current default input file. 105578e3e3a7aSWarner Losh 105588e3e3a7aSWarner Losh 105598e3e3a7aSWarner Losh<p> 105608e3e3a7aSWarner LoshIn case of errors this function raises the error, 105618e3e3a7aSWarner Loshinstead of returning an error code. 105628e3e3a7aSWarner Losh 105638e3e3a7aSWarner Losh 105648e3e3a7aSWarner Losh 105658e3e3a7aSWarner Losh 105668e3e3a7aSWarner Losh<p> 105678e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, ···])</code></a></h3> 105688e3e3a7aSWarner Losh 105698e3e3a7aSWarner Losh 105708e3e3a7aSWarner Losh<p> 105718e3e3a7aSWarner LoshOpens the given file name in read mode 105728e3e3a7aSWarner Loshand returns an iterator function that 105738e3e3a7aSWarner Loshworks like <code>file:lines(···)</code> over the opened file. 105740495ed39SKyle EvansWhen the iterator function fails to read any value, 105750495ed39SKyle Evansit automatically closes the file. 105760495ed39SKyle EvansBesides the iterator function, 105770495ed39SKyle Evans<code>io.lines</code> returns three other values: 105780495ed39SKyle Evanstwo <b>nil</b> values as placeholders, 105790495ed39SKyle Evansplus the created file handle. 105800495ed39SKyle EvansTherefore, when used in a generic <b>for</b> loop, 105810495ed39SKyle Evansthe file is closed also if the loop is interrupted by an 105820495ed39SKyle Evanserror or a <b>break</b>. 105838e3e3a7aSWarner Losh 105848e3e3a7aSWarner Losh 105858e3e3a7aSWarner Losh<p> 105868e3e3a7aSWarner LoshThe call <code>io.lines()</code> (with no file name) is equivalent 105870495ed39SKyle Evansto <code>io.input():lines("l")</code>; 105888e3e3a7aSWarner Loshthat is, it iterates over the lines of the default input file. 10589e112e9d2SKyle EvansIn this case, the iterator does not close the file when the loop ends. 105908e3e3a7aSWarner Losh 105918e3e3a7aSWarner Losh 105928e3e3a7aSWarner Losh<p> 105930495ed39SKyle EvansIn case of errors opening the file, 105940495ed39SKyle Evansthis function raises the error, 105958e3e3a7aSWarner Loshinstead of returning an error code. 105968e3e3a7aSWarner Losh 105978e3e3a7aSWarner Losh 105988e3e3a7aSWarner Losh 105998e3e3a7aSWarner Losh 106008e3e3a7aSWarner Losh<p> 106018e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> 106028e3e3a7aSWarner Losh 106038e3e3a7aSWarner Losh 106048e3e3a7aSWarner Losh<p> 106058e3e3a7aSWarner LoshThis function opens a file, 106068e3e3a7aSWarner Loshin the mode specified in the string <code>mode</code>. 106078e3e3a7aSWarner LoshIn case of success, 106088e3e3a7aSWarner Loshit returns a new file handle. 106098e3e3a7aSWarner Losh 106108e3e3a7aSWarner Losh 106118e3e3a7aSWarner Losh<p> 106128e3e3a7aSWarner LoshThe <code>mode</code> string can be any of the following: 106138e3e3a7aSWarner Losh 106148e3e3a7aSWarner Losh<ul> 106158e3e3a7aSWarner Losh<li><b>"<code>r</code>": </b> read mode (the default);</li> 106168e3e3a7aSWarner Losh<li><b>"<code>w</code>": </b> write mode;</li> 106178e3e3a7aSWarner Losh<li><b>"<code>a</code>": </b> append mode;</li> 106188e3e3a7aSWarner Losh<li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li> 106198e3e3a7aSWarner Losh<li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li> 106208e3e3a7aSWarner Losh<li><b>"<code>a+</code>": </b> append update mode, previous data is preserved, 106218e3e3a7aSWarner Losh writing is only allowed at the end of file.</li> 106228e3e3a7aSWarner Losh</ul><p> 106238e3e3a7aSWarner LoshThe <code>mode</code> string can also have a '<code>b</code>' at the end, 106248e3e3a7aSWarner Loshwhich is needed in some systems to open the file in binary mode. 106258e3e3a7aSWarner Losh 106268e3e3a7aSWarner Losh 106278e3e3a7aSWarner Losh 106288e3e3a7aSWarner Losh 106298e3e3a7aSWarner Losh<p> 106308e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> 106318e3e3a7aSWarner Losh 106328e3e3a7aSWarner Losh 106338e3e3a7aSWarner Losh<p> 106348e3e3a7aSWarner LoshSimilar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. 106358e3e3a7aSWarner Losh 106368e3e3a7aSWarner Losh 106378e3e3a7aSWarner Losh 106388e3e3a7aSWarner Losh 106398e3e3a7aSWarner Losh<p> 106408e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> 106418e3e3a7aSWarner Losh 106428e3e3a7aSWarner Losh 106438e3e3a7aSWarner Losh<p> 106448e3e3a7aSWarner LoshThis function is system dependent and is not available 106458e3e3a7aSWarner Loshon all platforms. 106468e3e3a7aSWarner Losh 106478e3e3a7aSWarner Losh 106488e3e3a7aSWarner Losh<p> 106490495ed39SKyle EvansStarts the program <code>prog</code> in a separated process and returns 106508e3e3a7aSWarner Losha file handle that you can use to read data from this program 106518e3e3a7aSWarner Losh(if <code>mode</code> is <code>"r"</code>, the default) 106528e3e3a7aSWarner Loshor to write data to this program 106538e3e3a7aSWarner Losh(if <code>mode</code> is <code>"w"</code>). 106548e3e3a7aSWarner Losh 106558e3e3a7aSWarner Losh 106568e3e3a7aSWarner Losh 106578e3e3a7aSWarner Losh 106588e3e3a7aSWarner Losh<p> 106598e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> 106608e3e3a7aSWarner Losh 106618e3e3a7aSWarner Losh 106628e3e3a7aSWarner Losh<p> 106638e3e3a7aSWarner LoshEquivalent to <code>io.input():read(···)</code>. 106648e3e3a7aSWarner Losh 106658e3e3a7aSWarner Losh 106668e3e3a7aSWarner Losh 106678e3e3a7aSWarner Losh 106688e3e3a7aSWarner Losh<p> 106698e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> 106708e3e3a7aSWarner Losh 106718e3e3a7aSWarner Losh 106728e3e3a7aSWarner Losh<p> 106738e3e3a7aSWarner LoshIn case of success, 106748e3e3a7aSWarner Loshreturns a handle for a temporary file. 106758e3e3a7aSWarner LoshThis file is opened in update mode 106768e3e3a7aSWarner Loshand it is automatically removed when the program ends. 106778e3e3a7aSWarner Losh 106788e3e3a7aSWarner Losh 106798e3e3a7aSWarner Losh 106808e3e3a7aSWarner Losh 106818e3e3a7aSWarner Losh<p> 106828e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> 106838e3e3a7aSWarner Losh 106848e3e3a7aSWarner Losh 106858e3e3a7aSWarner Losh<p> 106868e3e3a7aSWarner LoshChecks whether <code>obj</code> is a valid file handle. 106878e3e3a7aSWarner LoshReturns the string <code>"file"</code> if <code>obj</code> is an open file handle, 106888e3e3a7aSWarner Losh<code>"closed file"</code> if <code>obj</code> is a closed file handle, 106890495ed39SKyle Evansor <b>fail</b> if <code>obj</code> is not a file handle. 106908e3e3a7aSWarner Losh 106918e3e3a7aSWarner Losh 106928e3e3a7aSWarner Losh 106938e3e3a7aSWarner Losh 106948e3e3a7aSWarner Losh<p> 106958e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> 106968e3e3a7aSWarner Losh 106978e3e3a7aSWarner Losh 106988e3e3a7aSWarner Losh<p> 106998e3e3a7aSWarner LoshEquivalent to <code>io.output():write(···)</code>. 107008e3e3a7aSWarner Losh 107018e3e3a7aSWarner Losh 107028e3e3a7aSWarner Losh 107038e3e3a7aSWarner Losh 107048e3e3a7aSWarner Losh<p> 107058e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> 107068e3e3a7aSWarner Losh 107078e3e3a7aSWarner Losh 107088e3e3a7aSWarner Losh<p> 107098e3e3a7aSWarner LoshCloses <code>file</code>. 107108e3e3a7aSWarner LoshNote that files are automatically closed when 107118e3e3a7aSWarner Loshtheir handles are garbage collected, 107128e3e3a7aSWarner Loshbut that takes an unpredictable amount of time to happen. 107138e3e3a7aSWarner Losh 107148e3e3a7aSWarner Losh 107158e3e3a7aSWarner Losh<p> 107168e3e3a7aSWarner LoshWhen closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>, 107178e3e3a7aSWarner Losh<a href="#pdf-file:close"><code>file:close</code></a> returns the same values 107188e3e3a7aSWarner Loshreturned by <a href="#pdf-os.execute"><code>os.execute</code></a>. 107198e3e3a7aSWarner Losh 107208e3e3a7aSWarner Losh 107218e3e3a7aSWarner Losh 107228e3e3a7aSWarner Losh 107238e3e3a7aSWarner Losh<p> 107248e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> 107258e3e3a7aSWarner Losh 107268e3e3a7aSWarner Losh 107278e3e3a7aSWarner Losh<p> 107288e3e3a7aSWarner LoshSaves any written data to <code>file</code>. 107298e3e3a7aSWarner Losh 107308e3e3a7aSWarner Losh 107318e3e3a7aSWarner Losh 107328e3e3a7aSWarner Losh 107338e3e3a7aSWarner Losh<p> 107348e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3> 107358e3e3a7aSWarner Losh 107368e3e3a7aSWarner Losh 107378e3e3a7aSWarner Losh<p> 107388e3e3a7aSWarner LoshReturns an iterator function that, 107398e3e3a7aSWarner Losheach time it is called, 107408e3e3a7aSWarner Loshreads the file according to the given formats. 107418e3e3a7aSWarner LoshWhen no format is given, 107428e3e3a7aSWarner Loshuses "<code>l</code>" as a default. 107438e3e3a7aSWarner LoshAs an example, the construction 107448e3e3a7aSWarner Losh 107458e3e3a7aSWarner Losh<pre> 107468e3e3a7aSWarner Losh for c in file:lines(1) do <em>body</em> end 107478e3e3a7aSWarner Losh</pre><p> 107488e3e3a7aSWarner Loshwill iterate over all characters of the file, 107498e3e3a7aSWarner Loshstarting at the current position. 107508e3e3a7aSWarner LoshUnlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file 107518e3e3a7aSWarner Loshwhen the loop ends. 107528e3e3a7aSWarner Losh 107538e3e3a7aSWarner Losh 107548e3e3a7aSWarner Losh 107558e3e3a7aSWarner Losh 107568e3e3a7aSWarner Losh<p> 107578e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> 107588e3e3a7aSWarner Losh 107598e3e3a7aSWarner Losh 107608e3e3a7aSWarner Losh<p> 107618e3e3a7aSWarner LoshReads the file <code>file</code>, 107628e3e3a7aSWarner Loshaccording to the given formats, which specify what to read. 107638e3e3a7aSWarner LoshFor each format, 107648e3e3a7aSWarner Loshthe function returns a string or a number with the characters read, 107650495ed39SKyle Evansor <b>fail</b> if it cannot read data with the specified format. 107668e3e3a7aSWarner Losh(In this latter case, 107678e3e3a7aSWarner Loshthe function does not read subsequent formats.) 107680495ed39SKyle EvansWhen called without arguments, 107698e3e3a7aSWarner Loshit uses a default format that reads the next line 107708e3e3a7aSWarner Losh(see below). 107718e3e3a7aSWarner Losh 107728e3e3a7aSWarner Losh 107738e3e3a7aSWarner Losh<p> 107748e3e3a7aSWarner LoshThe available formats are 107758e3e3a7aSWarner Losh 107768e3e3a7aSWarner Losh<ul> 107778e3e3a7aSWarner Losh 107788e3e3a7aSWarner Losh<li><b>"<code>n</code>": </b> 107798e3e3a7aSWarner Loshreads a numeral and returns it as a float or an integer, 107808e3e3a7aSWarner Loshfollowing the lexical conventions of Lua. 107810495ed39SKyle Evans(The numeral may have leading whitespaces and a sign.) 107828e3e3a7aSWarner LoshThis format always reads the longest input sequence that 107838e3e3a7aSWarner Loshis a valid prefix for a numeral; 107848e3e3a7aSWarner Loshif that prefix does not form a valid numeral 107850495ed39SKyle Evans(e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>") 107860495ed39SKyle Evansor it is too long (more than 200 characters), 107870495ed39SKyle Evansit is discarded and the format returns <b>fail</b>. 107888e3e3a7aSWarner Losh</li> 107898e3e3a7aSWarner Losh 107908e3e3a7aSWarner Losh<li><b>"<code>a</code>": </b> 107918e3e3a7aSWarner Loshreads the whole file, starting at the current position. 107920495ed39SKyle EvansOn end of file, it returns the empty string; 107930495ed39SKyle Evansthis format never fails. 107948e3e3a7aSWarner Losh</li> 107958e3e3a7aSWarner Losh 107968e3e3a7aSWarner Losh<li><b>"<code>l</code>": </b> 107978e3e3a7aSWarner Loshreads the next line skipping the end of line, 107980495ed39SKyle Evansreturning <b>fail</b> on end of file. 107998e3e3a7aSWarner LoshThis is the default format. 108008e3e3a7aSWarner Losh</li> 108018e3e3a7aSWarner Losh 108028e3e3a7aSWarner Losh<li><b>"<code>L</code>": </b> 108038e3e3a7aSWarner Loshreads the next line keeping the end-of-line character (if present), 108040495ed39SKyle Evansreturning <b>fail</b> on end of file. 108058e3e3a7aSWarner Losh</li> 108068e3e3a7aSWarner Losh 108078e3e3a7aSWarner Losh<li><b><em>number</em>: </b> 108088e3e3a7aSWarner Loshreads a string with up to this number of bytes, 108090495ed39SKyle Evansreturning <b>fail</b> on end of file. 108108e3e3a7aSWarner LoshIf <code>number</code> is zero, 108118e3e3a7aSWarner Loshit reads nothing and returns an empty string, 108120495ed39SKyle Evansor <b>fail</b> on end of file. 108138e3e3a7aSWarner Losh</li> 108148e3e3a7aSWarner Losh 108158e3e3a7aSWarner Losh</ul><p> 108168e3e3a7aSWarner LoshThe formats "<code>l</code>" and "<code>L</code>" should be used only for text files. 108178e3e3a7aSWarner Losh 108188e3e3a7aSWarner Losh 108198e3e3a7aSWarner Losh 108208e3e3a7aSWarner Losh 108218e3e3a7aSWarner Losh<p> 108228e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3> 108238e3e3a7aSWarner Losh 108248e3e3a7aSWarner Losh 108258e3e3a7aSWarner Losh<p> 108268e3e3a7aSWarner LoshSets and gets the file position, 108278e3e3a7aSWarner Loshmeasured from the beginning of the file, 108288e3e3a7aSWarner Loshto the position given by <code>offset</code> plus a base 108298e3e3a7aSWarner Loshspecified by the string <code>whence</code>, as follows: 108308e3e3a7aSWarner Losh 108318e3e3a7aSWarner Losh<ul> 108328e3e3a7aSWarner Losh<li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li> 108338e3e3a7aSWarner Losh<li><b>"<code>cur</code>": </b> base is current position;</li> 108348e3e3a7aSWarner Losh<li><b>"<code>end</code>": </b> base is end of file;</li> 108358e3e3a7aSWarner Losh</ul><p> 108368e3e3a7aSWarner LoshIn case of success, <code>seek</code> returns the final file position, 108378e3e3a7aSWarner Loshmeasured in bytes from the beginning of the file. 108380495ed39SKyle EvansIf <code>seek</code> fails, it returns <b>fail</b>, 108398e3e3a7aSWarner Loshplus a string describing the error. 108408e3e3a7aSWarner Losh 108418e3e3a7aSWarner Losh 108428e3e3a7aSWarner Losh<p> 108438e3e3a7aSWarner LoshThe default value for <code>whence</code> is <code>"cur"</code>, 108448e3e3a7aSWarner Loshand for <code>offset</code> is 0. 108458e3e3a7aSWarner LoshTherefore, the call <code>file:seek()</code> returns the current 108468e3e3a7aSWarner Loshfile position, without changing it; 108478e3e3a7aSWarner Loshthe call <code>file:seek("set")</code> sets the position to the 108488e3e3a7aSWarner Loshbeginning of the file (and returns 0); 108498e3e3a7aSWarner Loshand the call <code>file:seek("end")</code> sets the position to the 108508e3e3a7aSWarner Loshend of the file, and returns its size. 108518e3e3a7aSWarner Losh 108528e3e3a7aSWarner Losh 108538e3e3a7aSWarner Losh 108548e3e3a7aSWarner Losh 108558e3e3a7aSWarner Losh<p> 108568e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> 108578e3e3a7aSWarner Losh 108588e3e3a7aSWarner Losh 108598e3e3a7aSWarner Losh<p> 108600495ed39SKyle EvansSets the buffering mode for a file. 108618e3e3a7aSWarner LoshThere are three available modes: 108628e3e3a7aSWarner Losh 108638e3e3a7aSWarner Losh<ul> 108640495ed39SKyle Evans<li><b>"<code>no</code>": </b> no buffering.</li> 108650495ed39SKyle Evans<li><b>"<code>full</code>": </b> full buffering.</li> 108660495ed39SKyle Evans<li><b>"<code>line</code>": </b> line buffering.</li> 108670495ed39SKyle Evans</ul> 108688e3e3a7aSWarner Losh 108690495ed39SKyle Evans<p> 108700495ed39SKyle EvansFor the last two cases, 108710495ed39SKyle Evans<code>size</code> is a hint for the size of the buffer, in bytes. 108728e3e3a7aSWarner LoshThe default is an appropriate size. 108738e3e3a7aSWarner Losh 108748e3e3a7aSWarner Losh 108750495ed39SKyle Evans<p> 108760495ed39SKyle EvansThe specific behavior of each mode is non portable; 108770495ed39SKyle Evanscheck the underlying ISO C function <code>setvbuf</code> in your platform for 108780495ed39SKyle Evansmore details. 108790495ed39SKyle Evans 108800495ed39SKyle Evans 108818e3e3a7aSWarner Losh 108828e3e3a7aSWarner Losh 108838e3e3a7aSWarner Losh<p> 108848e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> 108858e3e3a7aSWarner Losh 108868e3e3a7aSWarner Losh 108878e3e3a7aSWarner Losh<p> 108888e3e3a7aSWarner LoshWrites the value of each of its arguments to <code>file</code>. 108898e3e3a7aSWarner LoshThe arguments must be strings or numbers. 108908e3e3a7aSWarner Losh 108918e3e3a7aSWarner Losh 108928e3e3a7aSWarner Losh<p> 108938e3e3a7aSWarner LoshIn case of success, this function returns <code>file</code>. 108948e3e3a7aSWarner Losh 108958e3e3a7aSWarner Losh 108968e3e3a7aSWarner Losh 108978e3e3a7aSWarner Losh 108988e3e3a7aSWarner Losh 108998e3e3a7aSWarner Losh 109008e3e3a7aSWarner Losh 109018e3e3a7aSWarner Losh<h2>6.9 – <a name="6.9">Operating System Facilities</a></h2> 109028e3e3a7aSWarner Losh 109038e3e3a7aSWarner Losh<p> 109048e3e3a7aSWarner LoshThis library is implemented through table <a name="pdf-os"><code>os</code></a>. 109058e3e3a7aSWarner Losh 109068e3e3a7aSWarner Losh 109078e3e3a7aSWarner Losh<p> 109088e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> 109098e3e3a7aSWarner Losh 109108e3e3a7aSWarner Losh 109118e3e3a7aSWarner Losh<p> 109128e3e3a7aSWarner LoshReturns an approximation of the amount in seconds of CPU time 109130495ed39SKyle Evansused by the program, 109140495ed39SKyle Evansas returned by the underlying ISO C function <code>clock</code>. 109158e3e3a7aSWarner Losh 109168e3e3a7aSWarner Losh 109178e3e3a7aSWarner Losh 109188e3e3a7aSWarner Losh 109198e3e3a7aSWarner Losh<p> 109208e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> 109218e3e3a7aSWarner Losh 109228e3e3a7aSWarner Losh 109238e3e3a7aSWarner Losh<p> 109248e3e3a7aSWarner LoshReturns a string or a table containing date and time, 109258e3e3a7aSWarner Loshformatted according to the given string <code>format</code>. 109268e3e3a7aSWarner Losh 109278e3e3a7aSWarner Losh 109288e3e3a7aSWarner Losh<p> 109298e3e3a7aSWarner LoshIf the <code>time</code> argument is present, 109308e3e3a7aSWarner Loshthis is the time to be formatted 109318e3e3a7aSWarner Losh(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). 109328e3e3a7aSWarner LoshOtherwise, <code>date</code> formats the current time. 109338e3e3a7aSWarner Losh 109348e3e3a7aSWarner Losh 109358e3e3a7aSWarner Losh<p> 109368e3e3a7aSWarner LoshIf <code>format</code> starts with '<code>!</code>', 109378e3e3a7aSWarner Loshthen the date is formatted in Coordinated Universal Time. 109388e3e3a7aSWarner LoshAfter this optional character, 109398e3e3a7aSWarner Loshif <code>format</code> is the string "<code>*t</code>", 109408e3e3a7aSWarner Loshthen <code>date</code> returns a table with the following fields: 109418e3e3a7aSWarner Losh<code>year</code>, <code>month</code> (1–12), <code>day</code> (1–31), 109420495ed39SKyle Evans<code>hour</code> (0–23), <code>min</code> (0–59), 109430495ed39SKyle Evans<code>sec</code> (0–61, due to leap seconds), 109448e3e3a7aSWarner Losh<code>wday</code> (weekday, 1–7, Sunday is 1), 109458e3e3a7aSWarner Losh<code>yday</code> (day of the year, 1–366), 109468e3e3a7aSWarner Loshand <code>isdst</code> (daylight saving flag, a boolean). 109478e3e3a7aSWarner LoshThis last field may be absent 109488e3e3a7aSWarner Loshif the information is not available. 109498e3e3a7aSWarner Losh 109508e3e3a7aSWarner Losh 109518e3e3a7aSWarner Losh<p> 109528e3e3a7aSWarner LoshIf <code>format</code> is not "<code>*t</code>", 109538e3e3a7aSWarner Loshthen <code>date</code> returns the date as a string, 109548e3e3a7aSWarner Loshformatted according to the same rules as the ISO C function <code>strftime</code>. 109558e3e3a7aSWarner Losh 109568e3e3a7aSWarner Losh 109578e3e3a7aSWarner Losh<p> 109580495ed39SKyle EvansIf <code>format</code> is absent, it defaults to "<code>%c</code>", 109590495ed39SKyle Evanswhich gives a human-readable date and time representation 109600495ed39SKyle Evansusing the current locale. 109618e3e3a7aSWarner Losh 109628e3e3a7aSWarner Losh 109638e3e3a7aSWarner Losh<p> 109640495ed39SKyle EvansOn non-POSIX systems, 109658e3e3a7aSWarner Loshthis function may be not thread safe 109668e3e3a7aSWarner Loshbecause of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>. 109678e3e3a7aSWarner Losh 109688e3e3a7aSWarner Losh 109698e3e3a7aSWarner Losh 109708e3e3a7aSWarner Losh 109718e3e3a7aSWarner Losh<p> 109728e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> 109738e3e3a7aSWarner Losh 109748e3e3a7aSWarner Losh 109758e3e3a7aSWarner Losh<p> 109768e3e3a7aSWarner LoshReturns the difference, in seconds, 109778e3e3a7aSWarner Loshfrom time <code>t1</code> to time <code>t2</code> 109788e3e3a7aSWarner Losh(where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>). 109798e3e3a7aSWarner LoshIn POSIX, Windows, and some other systems, 109808e3e3a7aSWarner Loshthis value is exactly <code>t2</code><em>-</em><code>t1</code>. 109818e3e3a7aSWarner Losh 109828e3e3a7aSWarner Losh 109838e3e3a7aSWarner Losh 109848e3e3a7aSWarner Losh 109858e3e3a7aSWarner Losh<p> 109868e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> 109878e3e3a7aSWarner Losh 109888e3e3a7aSWarner Losh 109898e3e3a7aSWarner Losh<p> 109908e3e3a7aSWarner LoshThis function is equivalent to the ISO C function <code>system</code>. 109918e3e3a7aSWarner LoshIt passes <code>command</code> to be executed by an operating system shell. 109928e3e3a7aSWarner LoshIts first result is <b>true</b> 109938e3e3a7aSWarner Loshif the command terminated successfully, 109940495ed39SKyle Evansor <b>fail</b> otherwise. 109958e3e3a7aSWarner LoshAfter this first result 109968e3e3a7aSWarner Loshthe function returns a string plus a number, 109978e3e3a7aSWarner Loshas follows: 109988e3e3a7aSWarner Losh 109998e3e3a7aSWarner Losh<ul> 110008e3e3a7aSWarner Losh 110018e3e3a7aSWarner Losh<li><b>"<code>exit</code>": </b> 110028e3e3a7aSWarner Loshthe command terminated normally; 110038e3e3a7aSWarner Loshthe following number is the exit status of the command. 110048e3e3a7aSWarner Losh</li> 110058e3e3a7aSWarner Losh 110068e3e3a7aSWarner Losh<li><b>"<code>signal</code>": </b> 110078e3e3a7aSWarner Loshthe command was terminated by a signal; 110088e3e3a7aSWarner Loshthe following number is the signal that terminated the command. 110098e3e3a7aSWarner Losh</li> 110108e3e3a7aSWarner Losh 110118e3e3a7aSWarner Losh</ul> 110128e3e3a7aSWarner Losh 110138e3e3a7aSWarner Losh<p> 110148e3e3a7aSWarner LoshWhen called without a <code>command</code>, 110158e3e3a7aSWarner Losh<code>os.execute</code> returns a boolean that is true if a shell is available. 110168e3e3a7aSWarner Losh 110178e3e3a7aSWarner Losh 110188e3e3a7aSWarner Losh 110198e3e3a7aSWarner Losh 110208e3e3a7aSWarner Losh<p> 110218e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3> 110228e3e3a7aSWarner Losh 110238e3e3a7aSWarner Losh 110248e3e3a7aSWarner Losh<p> 110258e3e3a7aSWarner LoshCalls the ISO C function <code>exit</code> to terminate the host program. 110268e3e3a7aSWarner LoshIf <code>code</code> is <b>true</b>, 110278e3e3a7aSWarner Loshthe returned status is <code>EXIT_SUCCESS</code>; 110288e3e3a7aSWarner Loshif <code>code</code> is <b>false</b>, 110298e3e3a7aSWarner Loshthe returned status is <code>EXIT_FAILURE</code>; 110308e3e3a7aSWarner Loshif <code>code</code> is a number, 110318e3e3a7aSWarner Loshthe returned status is this number. 110328e3e3a7aSWarner LoshThe default value for <code>code</code> is <b>true</b>. 110338e3e3a7aSWarner Losh 110348e3e3a7aSWarner Losh 110358e3e3a7aSWarner Losh<p> 110368e3e3a7aSWarner LoshIf the optional second argument <code>close</code> is true, 11037*a9490b81SWarner Loshthe function closes the Lua state before exiting (see <a href="#lua_close"><code>lua_close</code></a>). 110388e3e3a7aSWarner Losh 110398e3e3a7aSWarner Losh 110408e3e3a7aSWarner Losh 110418e3e3a7aSWarner Losh 110428e3e3a7aSWarner Losh<p> 110438e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> 110448e3e3a7aSWarner Losh 110458e3e3a7aSWarner Losh 110468e3e3a7aSWarner Losh<p> 110470495ed39SKyle EvansReturns the value of the process environment variable <code>varname</code> 110480495ed39SKyle Evansor <b>fail</b> if the variable is not defined. 110498e3e3a7aSWarner Losh 110508e3e3a7aSWarner Losh 110518e3e3a7aSWarner Losh 110528e3e3a7aSWarner Losh 110538e3e3a7aSWarner Losh<p> 110548e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> 110558e3e3a7aSWarner Losh 110568e3e3a7aSWarner Losh 110578e3e3a7aSWarner Losh<p> 110588e3e3a7aSWarner LoshDeletes the file (or empty directory, on POSIX systems) 110598e3e3a7aSWarner Loshwith the given name. 110600495ed39SKyle EvansIf this function fails, it returns <b>fail</b> 110618e3e3a7aSWarner Loshplus a string describing the error and the error code. 110628e3e3a7aSWarner LoshOtherwise, it returns true. 110638e3e3a7aSWarner Losh 110648e3e3a7aSWarner Losh 110658e3e3a7aSWarner Losh 110668e3e3a7aSWarner Losh 110678e3e3a7aSWarner Losh<p> 110688e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> 110698e3e3a7aSWarner Losh 110708e3e3a7aSWarner Losh 110718e3e3a7aSWarner Losh<p> 110728e3e3a7aSWarner LoshRenames the file or directory named <code>oldname</code> to <code>newname</code>. 110730495ed39SKyle EvansIf this function fails, it returns <b>fail</b>, 110748e3e3a7aSWarner Loshplus a string describing the error and the error code. 110758e3e3a7aSWarner LoshOtherwise, it returns true. 110768e3e3a7aSWarner Losh 110778e3e3a7aSWarner Losh 110788e3e3a7aSWarner Losh 110798e3e3a7aSWarner Losh 110808e3e3a7aSWarner Losh<p> 110818e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> 110828e3e3a7aSWarner Losh 110838e3e3a7aSWarner Losh 110848e3e3a7aSWarner Losh<p> 110858e3e3a7aSWarner LoshSets the current locale of the program. 110868e3e3a7aSWarner Losh<code>locale</code> is a system-dependent string specifying a locale; 110878e3e3a7aSWarner Losh<code>category</code> is an optional string describing which category to change: 110888e3e3a7aSWarner Losh<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, 110898e3e3a7aSWarner Losh<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; 110908e3e3a7aSWarner Loshthe default category is <code>"all"</code>. 110918e3e3a7aSWarner LoshThe function returns the name of the new locale, 110920495ed39SKyle Evansor <b>fail</b> if the request cannot be honored. 110938e3e3a7aSWarner Losh 110948e3e3a7aSWarner Losh 110958e3e3a7aSWarner Losh<p> 110968e3e3a7aSWarner LoshIf <code>locale</code> is the empty string, 110978e3e3a7aSWarner Loshthe current locale is set to an implementation-defined native locale. 110988e3e3a7aSWarner LoshIf <code>locale</code> is the string "<code>C</code>", 110998e3e3a7aSWarner Loshthe current locale is set to the standard C locale. 111008e3e3a7aSWarner Losh 111018e3e3a7aSWarner Losh 111028e3e3a7aSWarner Losh<p> 111038e3e3a7aSWarner LoshWhen called with <b>nil</b> as the first argument, 111048e3e3a7aSWarner Loshthis function only returns the name of the current locale 111058e3e3a7aSWarner Loshfor the given category. 111068e3e3a7aSWarner Losh 111078e3e3a7aSWarner Losh 111088e3e3a7aSWarner Losh<p> 111098e3e3a7aSWarner LoshThis function may be not thread safe 111108e3e3a7aSWarner Loshbecause of its reliance on C function <code>setlocale</code>. 111118e3e3a7aSWarner Losh 111128e3e3a7aSWarner Losh 111138e3e3a7aSWarner Losh 111148e3e3a7aSWarner Losh 111158e3e3a7aSWarner Losh<p> 111168e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> 111178e3e3a7aSWarner Losh 111188e3e3a7aSWarner Losh 111198e3e3a7aSWarner Losh<p> 111208e3e3a7aSWarner LoshReturns the current time when called without arguments, 111218e3e3a7aSWarner Loshor a time representing the local date and time specified by the given table. 111228e3e3a7aSWarner LoshThis table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, 111238e3e3a7aSWarner Loshand may have fields 111248e3e3a7aSWarner Losh<code>hour</code> (default is 12), 111258e3e3a7aSWarner Losh<code>min</code> (default is 0), 111268e3e3a7aSWarner Losh<code>sec</code> (default is 0), 111278e3e3a7aSWarner Loshand <code>isdst</code> (default is <b>nil</b>). 111288e3e3a7aSWarner LoshOther fields are ignored. 111298e3e3a7aSWarner LoshFor a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function. 111308e3e3a7aSWarner Losh 111318e3e3a7aSWarner Losh 111328e3e3a7aSWarner Losh<p> 111330495ed39SKyle EvansWhen the function is called, 111340495ed39SKyle Evansthe values in these fields do not need to be inside their valid ranges. 111358e3e3a7aSWarner LoshFor instance, if <code>sec</code> is -10, 111360495ed39SKyle Evansit means 10 seconds before the time specified by the other fields; 111378e3e3a7aSWarner Loshif <code>hour</code> is 1000, 111380495ed39SKyle Evansit means 1000 hours after the time specified by the other fields. 111398e3e3a7aSWarner Losh 111408e3e3a7aSWarner Losh 111418e3e3a7aSWarner Losh<p> 111428e3e3a7aSWarner LoshThe returned value is a number, whose meaning depends on your system. 111438e3e3a7aSWarner LoshIn POSIX, Windows, and some other systems, 111448e3e3a7aSWarner Loshthis number counts the number 111458e3e3a7aSWarner Loshof seconds since some given start time (the "epoch"). 111468e3e3a7aSWarner LoshIn other systems, the meaning is not specified, 111478e3e3a7aSWarner Loshand the number returned by <code>time</code> can be used only as an argument to 111488e3e3a7aSWarner Losh<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. 111498e3e3a7aSWarner Losh 111508e3e3a7aSWarner Losh 111510495ed39SKyle Evans<p> 111520495ed39SKyle EvansWhen called with a table, 111530495ed39SKyle Evans<code>os.time</code> also normalizes all the fields 111540495ed39SKyle Evansdocumented in the <a href="#pdf-os.date"><code>os.date</code></a> function, 111550495ed39SKyle Evansso that they represent the same time as before the call 111560495ed39SKyle Evansbut with values inside their valid ranges. 111570495ed39SKyle Evans 111580495ed39SKyle Evans 111598e3e3a7aSWarner Losh 111608e3e3a7aSWarner Losh 111618e3e3a7aSWarner Losh<p> 111628e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> 111638e3e3a7aSWarner Losh 111648e3e3a7aSWarner Losh 111658e3e3a7aSWarner Losh<p> 111668e3e3a7aSWarner LoshReturns a string with a file name that can 111678e3e3a7aSWarner Loshbe used for a temporary file. 111688e3e3a7aSWarner LoshThe file must be explicitly opened before its use 111698e3e3a7aSWarner Loshand explicitly removed when no longer needed. 111708e3e3a7aSWarner Losh 111718e3e3a7aSWarner Losh 111728e3e3a7aSWarner Losh<p> 11173e112e9d2SKyle EvansIn POSIX systems, 111748e3e3a7aSWarner Loshthis function also creates a file with that name, 111758e3e3a7aSWarner Loshto avoid security risks. 111768e3e3a7aSWarner Losh(Someone else might create the file with wrong permissions 111778e3e3a7aSWarner Loshin the time between getting the name and creating the file.) 111788e3e3a7aSWarner LoshYou still have to open the file to use it 111798e3e3a7aSWarner Loshand to remove it (even if you do not use it). 111808e3e3a7aSWarner Losh 111818e3e3a7aSWarner Losh 111828e3e3a7aSWarner Losh<p> 111838e3e3a7aSWarner LoshWhen possible, 111848e3e3a7aSWarner Loshyou may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, 111858e3e3a7aSWarner Loshwhich automatically removes the file when the program ends. 111868e3e3a7aSWarner Losh 111878e3e3a7aSWarner Losh 111888e3e3a7aSWarner Losh 111898e3e3a7aSWarner Losh 111908e3e3a7aSWarner Losh 111918e3e3a7aSWarner Losh 111928e3e3a7aSWarner Losh 111938e3e3a7aSWarner Losh<h2>6.10 – <a name="6.10">The Debug Library</a></h2> 111948e3e3a7aSWarner Losh 111958e3e3a7aSWarner Losh<p> 111968e3e3a7aSWarner LoshThis library provides 111970495ed39SKyle Evansthe functionality of the debug interface (<a href="#4.7">§4.7</a>) to Lua programs. 111988e3e3a7aSWarner LoshYou should exert care when using this library. 111998e3e3a7aSWarner LoshSeveral of its functions 112008e3e3a7aSWarner Loshviolate basic assumptions about Lua code 112018e3e3a7aSWarner Losh(e.g., that variables local to a function 112028e3e3a7aSWarner Loshcannot be accessed from outside; 112038e3e3a7aSWarner Loshthat userdata metatables cannot be changed by Lua code; 112048e3e3a7aSWarner Loshthat Lua programs do not crash) 112058e3e3a7aSWarner Loshand therefore can compromise otherwise secure code. 112068e3e3a7aSWarner LoshMoreover, some functions in this library may be slow. 112078e3e3a7aSWarner Losh 112088e3e3a7aSWarner Losh 112098e3e3a7aSWarner Losh<p> 112108e3e3a7aSWarner LoshAll functions in this library are provided 112118e3e3a7aSWarner Loshinside the <a name="pdf-debug"><code>debug</code></a> table. 112128e3e3a7aSWarner LoshAll functions that operate over a thread 112138e3e3a7aSWarner Loshhave an optional first argument which is the 112148e3e3a7aSWarner Loshthread to operate over. 112158e3e3a7aSWarner LoshThe default is always the current thread. 112168e3e3a7aSWarner Losh 112178e3e3a7aSWarner Losh 112188e3e3a7aSWarner Losh<p> 112198e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> 112208e3e3a7aSWarner Losh 112218e3e3a7aSWarner Losh 112228e3e3a7aSWarner Losh<p> 112238e3e3a7aSWarner LoshEnters an interactive mode with the user, 112248e3e3a7aSWarner Loshrunning each string that the user enters. 112258e3e3a7aSWarner LoshUsing simple commands and other debug facilities, 112268e3e3a7aSWarner Loshthe user can inspect global and local variables, 112278e3e3a7aSWarner Loshchange their values, evaluate expressions, and so on. 112288e3e3a7aSWarner LoshA line containing only the word <code>cont</code> finishes this function, 112298e3e3a7aSWarner Loshso that the caller continues its execution. 112308e3e3a7aSWarner Losh 112318e3e3a7aSWarner Losh 112328e3e3a7aSWarner Losh<p> 112338e3e3a7aSWarner LoshNote that commands for <code>debug.debug</code> are not lexically nested 112348e3e3a7aSWarner Loshwithin any function and so have no direct access to local variables. 112358e3e3a7aSWarner Losh 112368e3e3a7aSWarner Losh 112378e3e3a7aSWarner Losh 112388e3e3a7aSWarner Losh 112398e3e3a7aSWarner Losh<p> 112408e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> 112418e3e3a7aSWarner Losh 112428e3e3a7aSWarner Losh 112438e3e3a7aSWarner Losh<p> 112448e3e3a7aSWarner LoshReturns the current hook settings of the thread, as three values: 112458e3e3a7aSWarner Loshthe current hook function, the current hook mask, 112460495ed39SKyle Evansand the current hook count, 112470495ed39SKyle Evansas set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function. 112480495ed39SKyle Evans 112490495ed39SKyle Evans 112500495ed39SKyle Evans<p> 112510495ed39SKyle EvansReturns <b>fail</b> if there is no active hook. 112528e3e3a7aSWarner Losh 112538e3e3a7aSWarner Losh 112548e3e3a7aSWarner Losh 112558e3e3a7aSWarner Losh 112568e3e3a7aSWarner Losh<p> 112578e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> 112588e3e3a7aSWarner Losh 112598e3e3a7aSWarner Losh 112608e3e3a7aSWarner Losh<p> 112618e3e3a7aSWarner LoshReturns a table with information about a function. 112628e3e3a7aSWarner LoshYou can give the function directly 112638e3e3a7aSWarner Loshor you can give a number as the value of <code>f</code>, 112648e3e3a7aSWarner Loshwhich means the function running at level <code>f</code> of the call stack 112658e3e3a7aSWarner Loshof the given thread: 112668e3e3a7aSWarner Loshlevel 0 is the current function (<code>getinfo</code> itself); 112678e3e3a7aSWarner Loshlevel 1 is the function that called <code>getinfo</code> 112680495ed39SKyle Evans(except for tail calls, which do not count in the stack); 112698e3e3a7aSWarner Loshand so on. 112700495ed39SKyle EvansIf <code>f</code> is a number greater than the number of active functions, 112710495ed39SKyle Evansthen <code>getinfo</code> returns <b>fail</b>. 112728e3e3a7aSWarner Losh 112738e3e3a7aSWarner Losh 112748e3e3a7aSWarner Losh<p> 112758e3e3a7aSWarner LoshThe returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, 112768e3e3a7aSWarner Loshwith the string <code>what</code> describing which fields to fill in. 112778e3e3a7aSWarner LoshThe default for <code>what</code> is to get all information available, 112788e3e3a7aSWarner Loshexcept the table of valid lines. 112798e3e3a7aSWarner LoshIf present, 112808e3e3a7aSWarner Loshthe option '<code>f</code>' 112818e3e3a7aSWarner Loshadds a field named <code>func</code> with the function itself. 112828e3e3a7aSWarner LoshIf present, 112838e3e3a7aSWarner Loshthe option '<code>L</code>' 112848e3e3a7aSWarner Loshadds a field named <code>activelines</code> with the table of 112858e3e3a7aSWarner Loshvalid lines. 112868e3e3a7aSWarner Losh 112878e3e3a7aSWarner Losh 112888e3e3a7aSWarner Losh<p> 112898e3e3a7aSWarner LoshFor instance, the expression <code>debug.getinfo(1,"n").name</code> returns 112908e3e3a7aSWarner Losha name for the current function, 112918e3e3a7aSWarner Loshif a reasonable name can be found, 112928e3e3a7aSWarner Loshand the expression <code>debug.getinfo(print)</code> 112938e3e3a7aSWarner Loshreturns a table with all available information 112948e3e3a7aSWarner Loshabout the <a href="#pdf-print"><code>print</code></a> function. 112958e3e3a7aSWarner Losh 112968e3e3a7aSWarner Losh 112978e3e3a7aSWarner Losh 112988e3e3a7aSWarner Losh 112998e3e3a7aSWarner Losh<p> 113008e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3> 113018e3e3a7aSWarner Losh 113028e3e3a7aSWarner Losh 113038e3e3a7aSWarner Losh<p> 113048e3e3a7aSWarner LoshThis function returns the name and the value of the local variable 113058e3e3a7aSWarner Loshwith index <code>local</code> of the function at level <code>f</code> of the stack. 113068e3e3a7aSWarner LoshThis function accesses not only explicit local variables, 113070495ed39SKyle Evansbut also parameters and temporary values. 113088e3e3a7aSWarner Losh 113098e3e3a7aSWarner Losh 113108e3e3a7aSWarner Losh<p> 113118e3e3a7aSWarner LoshThe first parameter or local variable has index 1, and so on, 113128e3e3a7aSWarner Loshfollowing the order that they are declared in the code, 113138e3e3a7aSWarner Loshcounting only the variables that are active 113148e3e3a7aSWarner Loshin the current scope of the function. 113150495ed39SKyle EvansCompile-time constants may not appear in this listing, 113160495ed39SKyle Evansif they were optimized away by the compiler. 11317e112e9d2SKyle EvansNegative indices refer to vararg arguments; 11318e112e9d2SKyle Evans-1 is the first vararg argument. 113190495ed39SKyle EvansThe function returns <b>fail</b> 113200495ed39SKyle Evansif there is no variable with the given index, 113218e3e3a7aSWarner Loshand raises an error when called with a level out of range. 113228e3e3a7aSWarner Losh(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) 113238e3e3a7aSWarner Losh 113248e3e3a7aSWarner Losh 113258e3e3a7aSWarner Losh<p> 113268e3e3a7aSWarner LoshVariable names starting with '<code>(</code>' (open parenthesis) 113278e3e3a7aSWarner Loshrepresent variables with no known names 113288e3e3a7aSWarner Losh(internal variables such as loop control variables, 113298e3e3a7aSWarner Loshand variables from chunks saved without debug information). 113308e3e3a7aSWarner Losh 113318e3e3a7aSWarner Losh 113328e3e3a7aSWarner Losh<p> 113338e3e3a7aSWarner LoshThe parameter <code>f</code> may also be a function. 113348e3e3a7aSWarner LoshIn that case, <code>getlocal</code> returns only the name of function parameters. 113358e3e3a7aSWarner Losh 113368e3e3a7aSWarner Losh 113378e3e3a7aSWarner Losh 113388e3e3a7aSWarner Losh 113398e3e3a7aSWarner Losh<p> 113408e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3> 113418e3e3a7aSWarner Losh 113428e3e3a7aSWarner Losh 113438e3e3a7aSWarner Losh<p> 113448e3e3a7aSWarner LoshReturns the metatable of the given <code>value</code> 113458e3e3a7aSWarner Loshor <b>nil</b> if it does not have a metatable. 113468e3e3a7aSWarner Losh 113478e3e3a7aSWarner Losh 113488e3e3a7aSWarner Losh 113498e3e3a7aSWarner Losh 113508e3e3a7aSWarner Losh<p> 113518e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> 113528e3e3a7aSWarner Losh 113538e3e3a7aSWarner Losh 113548e3e3a7aSWarner Losh<p> 113550495ed39SKyle EvansReturns the registry table (see <a href="#4.3">§4.3</a>). 113568e3e3a7aSWarner Losh 113578e3e3a7aSWarner Losh 113588e3e3a7aSWarner Losh 113598e3e3a7aSWarner Losh 113608e3e3a7aSWarner Losh<p> 113618e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3> 113628e3e3a7aSWarner Losh 113638e3e3a7aSWarner Losh 113648e3e3a7aSWarner Losh<p> 113658e3e3a7aSWarner LoshThis function returns the name and the value of the upvalue 113668e3e3a7aSWarner Loshwith index <code>up</code> of the function <code>f</code>. 113670495ed39SKyle EvansThe function returns <b>fail</b> 113680495ed39SKyle Evansif there is no upvalue with the given index. 113698e3e3a7aSWarner Losh 113708e3e3a7aSWarner Losh 113718e3e3a7aSWarner Losh<p> 113720495ed39SKyle Evans(For Lua functions, 113730495ed39SKyle Evansupvalues are the external local variables that the function uses, 113740495ed39SKyle Evansand that are consequently included in its closure.) 113750495ed39SKyle Evans 113760495ed39SKyle Evans 113770495ed39SKyle Evans<p> 113780495ed39SKyle EvansFor C functions, this function uses the empty string <code>""</code> 113790495ed39SKyle Evansas a name for all upvalues. 113800495ed39SKyle Evans 113810495ed39SKyle Evans 113820495ed39SKyle Evans<p> 113830495ed39SKyle EvansVariable name '<code>?</code>' (interrogation mark) 113840495ed39SKyle Evansrepresents variables with no known names 113858e3e3a7aSWarner Losh(variables from chunks saved without debug information). 113868e3e3a7aSWarner Losh 113878e3e3a7aSWarner Losh 113888e3e3a7aSWarner Losh 113898e3e3a7aSWarner Losh 113908e3e3a7aSWarner Losh<p> 113910495ed39SKyle Evans<hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u, n)</code></a></h3> 113928e3e3a7aSWarner Losh 113938e3e3a7aSWarner Losh 113948e3e3a7aSWarner Losh<p> 113950495ed39SKyle EvansReturns the <code>n</code>-th user value associated 113960495ed39SKyle Evansto the userdata <code>u</code> plus a boolean, 113970495ed39SKyle Evans<b>false</b> if the userdata does not have that value. 113988e3e3a7aSWarner Losh 113998e3e3a7aSWarner Losh 114008e3e3a7aSWarner Losh 114018e3e3a7aSWarner Losh 114028e3e3a7aSWarner Losh<p> 114038e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> 114048e3e3a7aSWarner Losh 114058e3e3a7aSWarner Losh 114068e3e3a7aSWarner Losh<p> 114070495ed39SKyle EvansSets the given function as the debug hook. 114088e3e3a7aSWarner LoshThe string <code>mask</code> and the number <code>count</code> describe 114098e3e3a7aSWarner Loshwhen the hook will be called. 114108e3e3a7aSWarner LoshThe string mask may have any combination of the following characters, 114118e3e3a7aSWarner Loshwith the given meaning: 114128e3e3a7aSWarner Losh 114138e3e3a7aSWarner Losh<ul> 114148e3e3a7aSWarner Losh<li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li> 114158e3e3a7aSWarner Losh<li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li> 114168e3e3a7aSWarner Losh<li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li> 114178e3e3a7aSWarner Losh</ul><p> 114188e3e3a7aSWarner LoshMoreover, 114198e3e3a7aSWarner Loshwith a <code>count</code> different from zero, 114208e3e3a7aSWarner Loshthe hook is called also after every <code>count</code> instructions. 114218e3e3a7aSWarner Losh 114228e3e3a7aSWarner Losh 114238e3e3a7aSWarner Losh<p> 114248e3e3a7aSWarner LoshWhen called without arguments, 114258e3e3a7aSWarner Losh<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. 114268e3e3a7aSWarner Losh 114278e3e3a7aSWarner Losh 114288e3e3a7aSWarner Losh<p> 114290495ed39SKyle EvansWhen the hook is called, its first parameter is a string 114308e3e3a7aSWarner Loshdescribing the event that has triggered its call: 114310495ed39SKyle Evans<code>"call"</code>, <code>"tail call"</code>, <code>"return"</code>, 114328e3e3a7aSWarner Losh<code>"line"</code>, and <code>"count"</code>. 114338e3e3a7aSWarner LoshFor line events, 114348e3e3a7aSWarner Loshthe hook also gets the new line number as its second parameter. 114358e3e3a7aSWarner LoshInside a hook, 114368e3e3a7aSWarner Loshyou can call <code>getinfo</code> with level 2 to get more information about 114370495ed39SKyle Evansthe running function. 114380495ed39SKyle Evans(Level 0 is the <code>getinfo</code> function, 114390495ed39SKyle Evansand level 1 is the hook function.) 114408e3e3a7aSWarner Losh 114418e3e3a7aSWarner Losh 114428e3e3a7aSWarner Losh 114438e3e3a7aSWarner Losh 114448e3e3a7aSWarner Losh<p> 114458e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> 114468e3e3a7aSWarner Losh 114478e3e3a7aSWarner Losh 114488e3e3a7aSWarner Losh<p> 114498e3e3a7aSWarner LoshThis function assigns the value <code>value</code> to the local variable 114508e3e3a7aSWarner Loshwith index <code>local</code> of the function at level <code>level</code> of the stack. 114510495ed39SKyle EvansThe function returns <b>fail</b> if there is no local 114528e3e3a7aSWarner Loshvariable with the given index, 114538e3e3a7aSWarner Loshand raises an error when called with a <code>level</code> out of range. 114548e3e3a7aSWarner Losh(You can call <code>getinfo</code> to check whether the level is valid.) 114558e3e3a7aSWarner LoshOtherwise, it returns the name of the local variable. 114568e3e3a7aSWarner Losh 114578e3e3a7aSWarner Losh 114588e3e3a7aSWarner Losh<p> 114598e3e3a7aSWarner LoshSee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about 114608e3e3a7aSWarner Loshvariable indices and names. 114618e3e3a7aSWarner Losh 114628e3e3a7aSWarner Losh 114638e3e3a7aSWarner Losh 114648e3e3a7aSWarner Losh 114658e3e3a7aSWarner Losh<p> 114668e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> 114678e3e3a7aSWarner Losh 114688e3e3a7aSWarner Losh 114698e3e3a7aSWarner Losh<p> 114708e3e3a7aSWarner LoshSets the metatable for the given <code>value</code> to the given <code>table</code> 114718e3e3a7aSWarner Losh(which can be <b>nil</b>). 114728e3e3a7aSWarner LoshReturns <code>value</code>. 114738e3e3a7aSWarner Losh 114748e3e3a7aSWarner Losh 114758e3e3a7aSWarner Losh 114768e3e3a7aSWarner Losh 114778e3e3a7aSWarner Losh<p> 114788e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> 114798e3e3a7aSWarner Losh 114808e3e3a7aSWarner Losh 114818e3e3a7aSWarner Losh<p> 114828e3e3a7aSWarner LoshThis function assigns the value <code>value</code> to the upvalue 114838e3e3a7aSWarner Loshwith index <code>up</code> of the function <code>f</code>. 114840495ed39SKyle EvansThe function returns <b>fail</b> if there is no upvalue 114858e3e3a7aSWarner Loshwith the given index. 114868e3e3a7aSWarner LoshOtherwise, it returns the name of the upvalue. 114878e3e3a7aSWarner Losh 114888e3e3a7aSWarner Losh 114890495ed39SKyle Evans<p> 114900495ed39SKyle EvansSee <a href="#pdf-debug.getupvalue"><code>debug.getupvalue</code></a> for more information about upvalues. 114910495ed39SKyle Evans 114920495ed39SKyle Evans 114938e3e3a7aSWarner Losh 114948e3e3a7aSWarner Losh 114958e3e3a7aSWarner Losh<p> 114960495ed39SKyle Evans<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value, n)</code></a></h3> 114978e3e3a7aSWarner Losh 114988e3e3a7aSWarner Losh 114998e3e3a7aSWarner Losh<p> 115008e3e3a7aSWarner LoshSets the given <code>value</code> as 115010495ed39SKyle Evansthe <code>n</code>-th user value associated to the given <code>udata</code>. 115028e3e3a7aSWarner Losh<code>udata</code> must be a full userdata. 115038e3e3a7aSWarner Losh 115048e3e3a7aSWarner Losh 115058e3e3a7aSWarner Losh<p> 115060495ed39SKyle EvansReturns <code>udata</code>, 115070495ed39SKyle Evansor <b>fail</b> if the userdata does not have that value. 115088e3e3a7aSWarner Losh 115098e3e3a7aSWarner Losh 115108e3e3a7aSWarner Losh 115118e3e3a7aSWarner Losh 115128e3e3a7aSWarner Losh<p> 115138e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> 115148e3e3a7aSWarner Losh 115158e3e3a7aSWarner Losh 115168e3e3a7aSWarner Losh<p> 115178e3e3a7aSWarner LoshIf <code>message</code> is present but is neither a string nor <b>nil</b>, 115188e3e3a7aSWarner Loshthis function returns <code>message</code> without further processing. 115198e3e3a7aSWarner LoshOtherwise, 115208e3e3a7aSWarner Loshit returns a string with a traceback of the call stack. 115218e3e3a7aSWarner LoshThe optional <code>message</code> string is appended 115228e3e3a7aSWarner Loshat the beginning of the traceback. 115238e3e3a7aSWarner LoshAn optional <code>level</code> number tells at which level 115248e3e3a7aSWarner Loshto start the traceback 115258e3e3a7aSWarner Losh(default is 1, the function calling <code>traceback</code>). 115268e3e3a7aSWarner Losh 115278e3e3a7aSWarner Losh 115288e3e3a7aSWarner Losh 115298e3e3a7aSWarner Losh 115308e3e3a7aSWarner Losh<p> 115318e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3> 115328e3e3a7aSWarner Losh 115338e3e3a7aSWarner Losh 115348e3e3a7aSWarner Losh<p> 115358e3e3a7aSWarner LoshReturns a unique identifier (as a light userdata) 115368e3e3a7aSWarner Loshfor the upvalue numbered <code>n</code> 115378e3e3a7aSWarner Loshfrom the given function. 115388e3e3a7aSWarner Losh 115398e3e3a7aSWarner Losh 115408e3e3a7aSWarner Losh<p> 115418e3e3a7aSWarner LoshThese unique identifiers allow a program to check whether different 115428e3e3a7aSWarner Loshclosures share upvalues. 115438e3e3a7aSWarner LoshLua closures that share an upvalue 115448e3e3a7aSWarner Losh(that is, that access a same external local variable) 115458e3e3a7aSWarner Loshwill return identical ids for those upvalue indices. 115468e3e3a7aSWarner Losh 115478e3e3a7aSWarner Losh 115488e3e3a7aSWarner Losh 115498e3e3a7aSWarner Losh 115508e3e3a7aSWarner Losh<p> 115518e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3> 115528e3e3a7aSWarner Losh 115538e3e3a7aSWarner Losh 115548e3e3a7aSWarner Losh<p> 115558e3e3a7aSWarner LoshMake the <code>n1</code>-th upvalue of the Lua closure <code>f1</code> 115568e3e3a7aSWarner Loshrefer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>. 115578e3e3a7aSWarner Losh 115588e3e3a7aSWarner Losh 115598e3e3a7aSWarner Losh 115608e3e3a7aSWarner Losh 115618e3e3a7aSWarner Losh 115628e3e3a7aSWarner Losh 115638e3e3a7aSWarner Losh 115648e3e3a7aSWarner Losh<h1>7 – <a name="7">Lua Standalone</a></h1> 115658e3e3a7aSWarner Losh 115668e3e3a7aSWarner Losh<p> 115678e3e3a7aSWarner LoshAlthough Lua has been designed as an extension language, 115688e3e3a7aSWarner Loshto be embedded in a host C program, 115698e3e3a7aSWarner Loshit is also frequently used as a standalone language. 115708e3e3a7aSWarner LoshAn interpreter for Lua as a standalone language, 115718e3e3a7aSWarner Loshcalled simply <code>lua</code>, 115728e3e3a7aSWarner Loshis provided with the standard distribution. 115738e3e3a7aSWarner LoshThe standalone interpreter includes 115740495ed39SKyle Evansall standard libraries. 115758e3e3a7aSWarner LoshIts usage is: 115768e3e3a7aSWarner Losh 115778e3e3a7aSWarner Losh<pre> 115788e3e3a7aSWarner Losh lua [options] [script [args]] 115798e3e3a7aSWarner Losh</pre><p> 115808e3e3a7aSWarner LoshThe options are: 115818e3e3a7aSWarner Losh 115828e3e3a7aSWarner Losh<ul> 115830495ed39SKyle Evans<li><b><code>-e <em>stat</em></code>: </b> execute string <em>stat</em>;</li> 115840495ed39SKyle Evans<li><b><code>-i</code>: </b> enter interactive mode after running <em>script</em>;</li> 115850495ed39SKyle Evans<li><b><code>-l <em>mod</em></code>: </b> "require" <em>mod</em> and assign the 115860495ed39SKyle Evans result to global <em>mod</em>;</li> 11587*a9490b81SWarner Losh<li><b><code>-l <em>g=mod</em></code>: </b> "require" <em>mod</em> and assign the 11588*a9490b81SWarner Losh result to global <em>g</em>;</li> 115890495ed39SKyle Evans<li><b><code>-v</code>: </b> print version information;</li> 115900495ed39SKyle Evans<li><b><code>-E</code>: </b> ignore environment variables;</li> 115910495ed39SKyle Evans<li><b><code>-W</code>: </b> turn warnings on;</li> 115920495ed39SKyle Evans<li><b><code>--</code>: </b> stop handling options;</li> 115930495ed39SKyle Evans<li><b><code>-</code>: </b> execute <code>stdin</code> as a file and stop handling options.</li> 115948e3e3a7aSWarner Losh</ul><p> 11595*a9490b81SWarner Losh(The form <code>-l <em>g=mod</em></code> was introduced in release 5.4.4.) 11596*a9490b81SWarner Losh 11597*a9490b81SWarner Losh 11598*a9490b81SWarner Losh<p> 115998e3e3a7aSWarner LoshAfter handling its options, <code>lua</code> runs the given <em>script</em>. 116008e3e3a7aSWarner LoshWhen called without arguments, 116018e3e3a7aSWarner Losh<code>lua</code> behaves as <code>lua -v -i</code> 116028e3e3a7aSWarner Loshwhen the standard input (<code>stdin</code>) is a terminal, 116038e3e3a7aSWarner Loshand as <code>lua -</code> otherwise. 116048e3e3a7aSWarner Losh 116058e3e3a7aSWarner Losh 116068e3e3a7aSWarner Losh<p> 116070495ed39SKyle EvansWhen called without the option <code>-E</code>, 116080495ed39SKyle Evansthe interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_4"><code>LUA_INIT_5_4</code></a> 116098e3e3a7aSWarner Losh(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined) 116108e3e3a7aSWarner Loshbefore running any argument. 116118e3e3a7aSWarner LoshIf the variable content has the format <code>@<em>filename</em></code>, 116128e3e3a7aSWarner Loshthen <code>lua</code> executes the file. 116138e3e3a7aSWarner LoshOtherwise, <code>lua</code> executes the string itself. 116148e3e3a7aSWarner Losh 116158e3e3a7aSWarner Losh 116168e3e3a7aSWarner Losh<p> 116170495ed39SKyle EvansWhen called with the option <code>-E</code>, 116180495ed39SKyle EvansLua does not consult any environment variables. 116190495ed39SKyle EvansIn particular, 116200495ed39SKyle Evansthe values of <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a> 116210495ed39SKyle Evansare set with the default paths defined in <code>luaconf.h</code>. 116228e3e3a7aSWarner Losh 116238e3e3a7aSWarner Losh 116248e3e3a7aSWarner Losh<p> 116250495ed39SKyle EvansThe options <code>-e</code>, <code>-l</code>, and <code>-W</code> are handled in 116260495ed39SKyle Evansthe order they appear. 116278e3e3a7aSWarner LoshFor instance, an invocation like 116288e3e3a7aSWarner Losh 116298e3e3a7aSWarner Losh<pre> 116300495ed39SKyle Evans $ lua -e 'a=1' -llib1 script.lua 116318e3e3a7aSWarner Losh</pre><p> 116320495ed39SKyle Evanswill first set <code>a</code> to 1, then require the library <code>lib1</code>, 116338e3e3a7aSWarner Loshand finally run the file <code>script.lua</code> with no arguments. 116348e3e3a7aSWarner Losh(Here <code>$</code> is the shell prompt. Your prompt may be different.) 116358e3e3a7aSWarner Losh 116368e3e3a7aSWarner Losh 116378e3e3a7aSWarner Losh<p> 116388e3e3a7aSWarner LoshBefore running any code, 116398e3e3a7aSWarner Losh<code>lua</code> collects all command-line arguments 116408e3e3a7aSWarner Loshin a global table called <code>arg</code>. 116418e3e3a7aSWarner LoshThe script name goes to index 0, 116428e3e3a7aSWarner Loshthe first argument after the script name goes to index 1, 116438e3e3a7aSWarner Loshand so on. 116448e3e3a7aSWarner LoshAny arguments before the script name 116458e3e3a7aSWarner Losh(that is, the interpreter name plus its options) 116468e3e3a7aSWarner Loshgo to negative indices. 116478e3e3a7aSWarner LoshFor instance, in the call 116488e3e3a7aSWarner Losh 116498e3e3a7aSWarner Losh<pre> 116508e3e3a7aSWarner Losh $ lua -la b.lua t1 t2 116518e3e3a7aSWarner Losh</pre><p> 116528e3e3a7aSWarner Loshthe table is like this: 116538e3e3a7aSWarner Losh 116548e3e3a7aSWarner Losh<pre> 116558e3e3a7aSWarner Losh arg = { [-2] = "lua", [-1] = "-la", 116568e3e3a7aSWarner Losh [0] = "b.lua", 116578e3e3a7aSWarner Losh [1] = "t1", [2] = "t2" } 116588e3e3a7aSWarner Losh</pre><p> 116598e3e3a7aSWarner LoshIf there is no script in the call, 116608e3e3a7aSWarner Loshthe interpreter name goes to index 0, 116618e3e3a7aSWarner Loshfollowed by the other arguments. 116628e3e3a7aSWarner LoshFor instance, the call 116638e3e3a7aSWarner Losh 116648e3e3a7aSWarner Losh<pre> 116658e3e3a7aSWarner Losh $ lua -e "print(arg[1])" 116668e3e3a7aSWarner Losh</pre><p> 116678e3e3a7aSWarner Loshwill print "<code>-e</code>". 116688e3e3a7aSWarner LoshIf there is a script, 11669e112e9d2SKyle Evansthe script is called with arguments 116708e3e3a7aSWarner Losh<code>arg[1]</code>, ···, <code>arg[#arg]</code>. 116710495ed39SKyle EvansLike all chunks in Lua, 11672*a9490b81SWarner Loshthe script is compiled as a variadic function. 116738e3e3a7aSWarner Losh 116748e3e3a7aSWarner Losh 116758e3e3a7aSWarner Losh<p> 116768e3e3a7aSWarner LoshIn interactive mode, 116778e3e3a7aSWarner LoshLua repeatedly prompts and waits for a line. 116788e3e3a7aSWarner LoshAfter reading a line, 116798e3e3a7aSWarner LoshLua first try to interpret the line as an expression. 116808e3e3a7aSWarner LoshIf it succeeds, it prints its value. 116818e3e3a7aSWarner LoshOtherwise, it interprets the line as a statement. 116828e3e3a7aSWarner LoshIf you write an incomplete statement, 116838e3e3a7aSWarner Loshthe interpreter waits for its completion 116848e3e3a7aSWarner Loshby issuing a different prompt. 116858e3e3a7aSWarner Losh 116868e3e3a7aSWarner Losh 116878e3e3a7aSWarner Losh<p> 116888e3e3a7aSWarner LoshIf the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, 116898e3e3a7aSWarner Loshthen its value is used as the prompt. 116908e3e3a7aSWarner LoshSimilarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, 116918e3e3a7aSWarner Loshits value is used as the secondary prompt 116928e3e3a7aSWarner Losh(issued during incomplete statements). 116938e3e3a7aSWarner Losh 116948e3e3a7aSWarner Losh 116958e3e3a7aSWarner Losh<p> 116968e3e3a7aSWarner LoshIn case of unprotected errors in the script, 116978e3e3a7aSWarner Loshthe interpreter reports the error to the standard error stream. 116988e3e3a7aSWarner LoshIf the error object is not a string but 116998e3e3a7aSWarner Loshhas a metamethod <code>__tostring</code>, 117008e3e3a7aSWarner Loshthe interpreter calls this metamethod to produce the final message. 117018e3e3a7aSWarner LoshOtherwise, the interpreter converts the error object to a string 117028e3e3a7aSWarner Loshand adds a stack traceback to it. 117030495ed39SKyle EvansWhen warnings are on, 117040495ed39SKyle Evansthey are simply printed in the standard error output. 117058e3e3a7aSWarner Losh 117068e3e3a7aSWarner Losh 117078e3e3a7aSWarner Losh<p> 117088e3e3a7aSWarner LoshWhen finishing normally, 117098e3e3a7aSWarner Loshthe interpreter closes its main Lua state 117108e3e3a7aSWarner Losh(see <a href="#lua_close"><code>lua_close</code></a>). 117118e3e3a7aSWarner LoshThe script can avoid this step by 117128e3e3a7aSWarner Loshcalling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate. 117138e3e3a7aSWarner Losh 117148e3e3a7aSWarner Losh 117158e3e3a7aSWarner Losh<p> 117168e3e3a7aSWarner LoshTo allow the use of Lua as a 117178e3e3a7aSWarner Loshscript interpreter in Unix systems, 117180495ed39SKyle EvansLua skips the first line of a file chunk if it starts with <code>#</code>. 117198e3e3a7aSWarner LoshTherefore, Lua scripts can be made into executable programs 117208e3e3a7aSWarner Loshby using <code>chmod +x</code> and the <code>#!</code> form, 117218e3e3a7aSWarner Loshas in 117228e3e3a7aSWarner Losh 117238e3e3a7aSWarner Losh<pre> 117248e3e3a7aSWarner Losh #!/usr/local/bin/lua 117258e3e3a7aSWarner Losh</pre><p> 117260495ed39SKyle EvansOf course, 117278e3e3a7aSWarner Loshthe location of the Lua interpreter may be different in your machine. 117288e3e3a7aSWarner LoshIf <code>lua</code> is in your <code>PATH</code>, 117298e3e3a7aSWarner Loshthen 117308e3e3a7aSWarner Losh 117318e3e3a7aSWarner Losh<pre> 117328e3e3a7aSWarner Losh #!/usr/bin/env lua 117338e3e3a7aSWarner Losh</pre><p> 117340495ed39SKyle Evansis a more portable solution. 117358e3e3a7aSWarner Losh 117368e3e3a7aSWarner Losh 117378e3e3a7aSWarner Losh 117388e3e3a7aSWarner Losh<h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> 117398e3e3a7aSWarner Losh 117400495ed39SKyle Evans 117410495ed39SKyle Evans 117428e3e3a7aSWarner Losh<p> 117438e3e3a7aSWarner LoshHere we list the incompatibilities that you may find when moving a program 117440495ed39SKyle Evansfrom Lua 5.3 to Lua 5.4. 117450495ed39SKyle Evans 117460495ed39SKyle Evans 117470495ed39SKyle Evans<p> 117488e3e3a7aSWarner LoshYou can avoid some incompatibilities by compiling Lua with 117498e3e3a7aSWarner Loshappropriate options (see file <code>luaconf.h</code>). 117508e3e3a7aSWarner LoshHowever, 117518e3e3a7aSWarner Loshall these compatibility options will be removed in the future. 117520495ed39SKyle EvansMore often than not, 117530495ed39SKyle Evanscompatibility issues arise when these compatibility options 117540495ed39SKyle Evansare removed. 117550495ed39SKyle EvansSo, whenever you have the chance, 117560495ed39SKyle Evansyou should try to test your code with a version of Lua compiled 117570495ed39SKyle Evanswith all compatibility options turned off. 117580495ed39SKyle EvansThat will ease transitions to newer versions of Lua. 117598e3e3a7aSWarner Losh 117608e3e3a7aSWarner Losh 117618e3e3a7aSWarner Losh<p> 117628e3e3a7aSWarner LoshLua versions can always change the C API in ways that 117638e3e3a7aSWarner Loshdo not imply source-code changes in a program, 117648e3e3a7aSWarner Loshsuch as the numeric values for constants 117658e3e3a7aSWarner Loshor the implementation of functions as macros. 117668e3e3a7aSWarner LoshTherefore, 117670495ed39SKyle Evansyou should never assume that binaries are compatible between 117688e3e3a7aSWarner Loshdifferent Lua versions. 117698e3e3a7aSWarner LoshAlways recompile clients of the Lua API when 117708e3e3a7aSWarner Loshusing a new version. 117718e3e3a7aSWarner Losh 117728e3e3a7aSWarner Losh 117738e3e3a7aSWarner Losh<p> 117748e3e3a7aSWarner LoshSimilarly, Lua versions can always change the internal representation 117758e3e3a7aSWarner Loshof precompiled chunks; 117768e3e3a7aSWarner Loshprecompiled chunks are not compatible between different Lua versions. 117778e3e3a7aSWarner Losh 117788e3e3a7aSWarner Losh 117798e3e3a7aSWarner Losh<p> 117808e3e3a7aSWarner LoshThe standard paths in the official distribution may 117818e3e3a7aSWarner Loshchange between versions. 117828e3e3a7aSWarner Losh 117838e3e3a7aSWarner Losh 117848e3e3a7aSWarner Losh 117850495ed39SKyle Evans 117860495ed39SKyle Evans 117870495ed39SKyle Evans<h2>8.1 – <a name="8.1">Incompatibilities in the Language</a></h2> 117888e3e3a7aSWarner Losh<ul> 117898e3e3a7aSWarner Losh 117908e3e3a7aSWarner Losh<li> 117910495ed39SKyle EvansThe coercion of strings to numbers in 117920495ed39SKyle Evansarithmetic and bitwise operations 117930495ed39SKyle Evanshas been removed from the core language. 117940495ed39SKyle EvansThe string library does a similar job 117950495ed39SKyle Evansfor arithmetic (but not for bitwise) operations 117960495ed39SKyle Evansusing the string metamethods. 117970495ed39SKyle EvansHowever, unlike in previous versions, 117980495ed39SKyle Evansthe new implementation preserves the implicit type of the numeral 117990495ed39SKyle Evansin the string. 118000495ed39SKyle EvansFor instance, the result of <code>"1" + "2"</code> now is an integer, 118010495ed39SKyle Evansnot a float. 118028e3e3a7aSWarner Losh</li> 118038e3e3a7aSWarner Losh 118048e3e3a7aSWarner Losh<li> 118050495ed39SKyle EvansLiteral decimal integer constants that overflow are read as floats, 118060495ed39SKyle Evansinstead of wrapping around. 118070495ed39SKyle EvansYou can use hexadecimal notation for such constants if you 118080495ed39SKyle Evanswant the old behavior 118090495ed39SKyle Evans(reading them as integers with wrap around). 118108e3e3a7aSWarner Losh</li> 118118e3e3a7aSWarner Losh 118128e3e3a7aSWarner Losh<li> 118130495ed39SKyle EvansThe use of the <code>__lt</code> metamethod to emulate <code>__le</code> 118140495ed39SKyle Evanshas been removed. 118150495ed39SKyle EvansWhen needed, this metamethod must be explicitly defined. 118160495ed39SKyle Evans</li> 118170495ed39SKyle Evans 118180495ed39SKyle Evans<li> 118190495ed39SKyle EvansThe semantics of the numerical <b>for</b> loop 118200495ed39SKyle Evansover integers changed in some details. 118210495ed39SKyle EvansIn particular, the control variable never wraps around. 118220495ed39SKyle Evans</li> 118230495ed39SKyle Evans 118240495ed39SKyle Evans<li> 118250495ed39SKyle EvansA label for a <b>goto</b> cannot be declared where a label with the same 118260495ed39SKyle Evansname is visible, even if this other label is declared in an enclosing 118270495ed39SKyle Evansblock. 118280495ed39SKyle Evans</li> 118290495ed39SKyle Evans 118300495ed39SKyle Evans<li> 118310495ed39SKyle EvansWhen finalizing an object, 118320495ed39SKyle EvansLua does not ignore <code>__gc</code> metamethods that are not functions. 118330495ed39SKyle EvansAny value will be called, if present. 118340495ed39SKyle Evans(Non-callable values will generate a warning, 118350495ed39SKyle Evanslike any other error when calling a finalizer.) 118368e3e3a7aSWarner Losh</li> 118378e3e3a7aSWarner Losh 118388e3e3a7aSWarner Losh</ul> 118398e3e3a7aSWarner Losh 118408e3e3a7aSWarner Losh 118418e3e3a7aSWarner Losh 118428e3e3a7aSWarner Losh 118430495ed39SKyle Evans<h2>8.2 – <a name="8.2">Incompatibilities in the Libraries</a></h2> 118448e3e3a7aSWarner Losh<ul> 118458e3e3a7aSWarner Losh 118468e3e3a7aSWarner Losh<li> 118470495ed39SKyle EvansThe function <a href="#pdf-print"><code>print</code></a> does not call <a href="#pdf-tostring"><code>tostring</code></a> 118480495ed39SKyle Evansto format its arguments; 118490495ed39SKyle Evansinstead, it has this functionality hardwired. 118500495ed39SKyle EvansYou should use <code>__tostring</code> to modify how values are printed. 118518e3e3a7aSWarner Losh</li> 118528e3e3a7aSWarner Losh 118538e3e3a7aSWarner Losh<li> 118540495ed39SKyle EvansThe pseudo-random number generator used by the function <a href="#pdf-math.random"><code>math.random</code></a> 118550495ed39SKyle Evansnow starts with a somewhat random seed. 118560495ed39SKyle EvansMoreover, it uses a different algorithm. 118578e3e3a7aSWarner Losh</li> 118588e3e3a7aSWarner Losh 118598e3e3a7aSWarner Losh<li> 118600495ed39SKyle EvansBy default, the decoding functions in the <a href="#pdf-utf8"><code>utf8</code></a> library 118610495ed39SKyle Evansdo not accept surrogates as valid code points. 118620495ed39SKyle EvansAn extra parameter in these functions makes them more permissive. 118638e3e3a7aSWarner Losh</li> 118648e3e3a7aSWarner Losh 118658e3e3a7aSWarner Losh<li> 118660495ed39SKyle EvansThe options "<code>setpause</code>" and "<code>setstepmul</code>" 118670495ed39SKyle Evansof the function <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> are deprecated. 118680495ed39SKyle EvansYou should use the new option "<code>incremental</code>" to set them. 118698e3e3a7aSWarner Losh</li> 118708e3e3a7aSWarner Losh 118718e3e3a7aSWarner Losh<li> 118720495ed39SKyle EvansThe function <a href="#pdf-io.lines"><code>io.lines</code></a> now returns four values, 118730495ed39SKyle Evansinstead of just one. 118740495ed39SKyle EvansThat can be a problem when it is used as the sole 118750495ed39SKyle Evansargument to another function that has optional parameters, 118760495ed39SKyle Evanssuch as in <code>load(io.lines(filename, "L"))</code>. 118770495ed39SKyle EvansTo fix that issue, 118780495ed39SKyle Evansyou can wrap the call into parentheses, 118790495ed39SKyle Evansto adjust its number of results to one. 118808e3e3a7aSWarner Losh</li> 118818e3e3a7aSWarner Losh 118828e3e3a7aSWarner Losh</ul> 118838e3e3a7aSWarner Losh 118848e3e3a7aSWarner Losh 118858e3e3a7aSWarner Losh 118868e3e3a7aSWarner Losh 118870495ed39SKyle Evans<h2>8.3 – <a name="8.3">Incompatibilities in the API</a></h2> 118888e3e3a7aSWarner Losh 118898e3e3a7aSWarner Losh 118908e3e3a7aSWarner Losh<ul> 118918e3e3a7aSWarner Losh 118928e3e3a7aSWarner Losh<li> 118930495ed39SKyle EvansFull userdata now has an arbitrary number of associated user values. 118940495ed39SKyle EvansTherefore, the functions <code>lua_newuserdata</code>, 118950495ed39SKyle Evans<code>lua_setuservalue</code>, and <code>lua_getuservalue</code> were 118960495ed39SKyle Evansreplaced by <a href="#lua_newuserdatauv"><code>lua_newuserdatauv</code></a>, 118970495ed39SKyle Evans<a href="#lua_setiuservalue"><code>lua_setiuservalue</code></a>, and <a href="#lua_getiuservalue"><code>lua_getiuservalue</code></a>, 118980495ed39SKyle Evanswhich have an extra argument. 118990495ed39SKyle Evans 119000495ed39SKyle Evans 119010495ed39SKyle Evans<p> 119020495ed39SKyle EvansFor compatibility, the old names still work as macros assuming 119030495ed39SKyle Evansone single user value. 119040495ed39SKyle EvansNote, however, that userdata with zero user values 119050495ed39SKyle Evansare more efficient memory-wise. 119068e3e3a7aSWarner Losh</li> 119078e3e3a7aSWarner Losh 119088e3e3a7aSWarner Losh<li> 119090495ed39SKyle EvansThe function <a href="#lua_resume"><code>lua_resume</code></a> has an extra parameter. 119100495ed39SKyle EvansThis out parameter returns the number of values on 119110495ed39SKyle Evansthe top of the stack that were yielded or returned by the coroutine. 119120495ed39SKyle Evans(In previous versions, 119130495ed39SKyle Evansthose values were the entire stack.) 119148e3e3a7aSWarner Losh</li> 119158e3e3a7aSWarner Losh 119168e3e3a7aSWarner Losh<li> 119170495ed39SKyle EvansThe function <a href="#lua_version"><code>lua_version</code></a> returns the version number, 119180495ed39SKyle Evansinstead of an address of the version number. 119190495ed39SKyle EvansThe Lua core should work correctly with libraries using their 119200495ed39SKyle Evansown static copies of the same core, 119210495ed39SKyle Evansso there is no need to check whether they are using the same 119220495ed39SKyle Evansaddress space. 119238e3e3a7aSWarner Losh</li> 119248e3e3a7aSWarner Losh 119258e3e3a7aSWarner Losh<li> 119260495ed39SKyle EvansThe constant <code>LUA_ERRGCMM</code> was removed. 119270495ed39SKyle EvansErrors in finalizers are never propagated; 119280495ed39SKyle Evansinstead, they generate a warning. 119290495ed39SKyle Evans</li> 119300495ed39SKyle Evans 119310495ed39SKyle Evans<li> 119320495ed39SKyle EvansThe options <code>LUA_GCSETPAUSE</code> and <code>LUA_GCSETSTEPMUL</code> 119330495ed39SKyle Evansof the function <a href="#lua_gc"><code>lua_gc</code></a> are deprecated. 119340495ed39SKyle EvansYou should use the new option <code>LUA_GCINC</code> to set them. 119358e3e3a7aSWarner Losh</li> 119368e3e3a7aSWarner Losh 119378e3e3a7aSWarner Losh</ul> 119388e3e3a7aSWarner Losh 119398e3e3a7aSWarner Losh 119408e3e3a7aSWarner Losh 119418e3e3a7aSWarner Losh 119428e3e3a7aSWarner Losh<h1>9 – <a name="9">The Complete Syntax of Lua</a></h1> 119438e3e3a7aSWarner Losh 119448e3e3a7aSWarner Losh<p> 119458e3e3a7aSWarner LoshHere is the complete syntax of Lua in extended BNF. 119468e3e3a7aSWarner LoshAs usual in extended BNF, 119478e3e3a7aSWarner Losh{A} means 0 or more As, 119488e3e3a7aSWarner Loshand [A] means an optional A. 119498e3e3a7aSWarner Losh(For operator precedences, see <a href="#3.4.8">§3.4.8</a>; 119508e3e3a7aSWarner Loshfor a description of the terminals 119518e3e3a7aSWarner LoshName, Numeral, 119528e3e3a7aSWarner Loshand LiteralString, see <a href="#3.1">§3.1</a>.) 119538e3e3a7aSWarner Losh 119548e3e3a7aSWarner Losh 119558e3e3a7aSWarner Losh 119568e3e3a7aSWarner Losh 119578e3e3a7aSWarner Losh<pre> 119588e3e3a7aSWarner Losh 119598e3e3a7aSWarner Losh chunk ::= block 119608e3e3a7aSWarner Losh 119618e3e3a7aSWarner Losh block ::= {stat} [retstat] 119628e3e3a7aSWarner Losh 119638e3e3a7aSWarner Losh stat ::= ‘<b>;</b>’ | 119648e3e3a7aSWarner Losh varlist ‘<b>=</b>’ explist | 119658e3e3a7aSWarner Losh functioncall | 119668e3e3a7aSWarner Losh label | 119678e3e3a7aSWarner Losh <b>break</b> | 119688e3e3a7aSWarner Losh <b>goto</b> Name | 119698e3e3a7aSWarner Losh <b>do</b> block <b>end</b> | 119708e3e3a7aSWarner Losh <b>while</b> exp <b>do</b> block <b>end</b> | 119718e3e3a7aSWarner Losh <b>repeat</b> block <b>until</b> exp | 119728e3e3a7aSWarner Losh <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 119738e3e3a7aSWarner Losh <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> | 119748e3e3a7aSWarner Losh <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 119758e3e3a7aSWarner Losh <b>function</b> funcname funcbody | 119768e3e3a7aSWarner Losh <b>local</b> <b>function</b> Name funcbody | 119770495ed39SKyle Evans <b>local</b> attnamelist [‘<b>=</b>’ explist] 119780495ed39SKyle Evans 119790495ed39SKyle Evans attnamelist ::= Name attrib {‘<b>,</b>’ Name attrib} 119800495ed39SKyle Evans 119810495ed39SKyle Evans attrib ::= [‘<b><</b>’ Name ‘<b>></b>’] 119828e3e3a7aSWarner Losh 119838e3e3a7aSWarner Losh retstat ::= <b>return</b> [explist] [‘<b>;</b>’] 119848e3e3a7aSWarner Losh 119858e3e3a7aSWarner Losh label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 119868e3e3a7aSWarner Losh 119878e3e3a7aSWarner Losh funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 119888e3e3a7aSWarner Losh 119898e3e3a7aSWarner Losh varlist ::= var {‘<b>,</b>’ var} 119908e3e3a7aSWarner Losh 119918e3e3a7aSWarner Losh var ::= Name | prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | prefixexp ‘<b>.</b>’ Name 119928e3e3a7aSWarner Losh 119938e3e3a7aSWarner Losh namelist ::= Name {‘<b>,</b>’ Name} 119948e3e3a7aSWarner Losh 119958e3e3a7aSWarner Losh explist ::= exp {‘<b>,</b>’ exp} 119968e3e3a7aSWarner Losh 119978e3e3a7aSWarner Losh exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | ‘<b>...</b>’ | functiondef | 119988e3e3a7aSWarner Losh prefixexp | tableconstructor | exp binop exp | unop exp 119998e3e3a7aSWarner Losh 120008e3e3a7aSWarner Losh prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 120018e3e3a7aSWarner Losh 120028e3e3a7aSWarner Losh functioncall ::= prefixexp args | prefixexp ‘<b>:</b>’ Name args 120038e3e3a7aSWarner Losh 120048e3e3a7aSWarner Losh args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | tableconstructor | LiteralString 120058e3e3a7aSWarner Losh 120068e3e3a7aSWarner Losh functiondef ::= <b>function</b> funcbody 120078e3e3a7aSWarner Losh 120088e3e3a7aSWarner Losh funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 120098e3e3a7aSWarner Losh 120108e3e3a7aSWarner Losh parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 120118e3e3a7aSWarner Losh 120128e3e3a7aSWarner Losh tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 120138e3e3a7aSWarner Losh 120148e3e3a7aSWarner Losh fieldlist ::= field {fieldsep field} [fieldsep] 120158e3e3a7aSWarner Losh 120168e3e3a7aSWarner Losh field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 120178e3e3a7aSWarner Losh 120188e3e3a7aSWarner Losh fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 120198e3e3a7aSWarner Losh 120208e3e3a7aSWarner Losh binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</b>’ | ‘<b>//</b>’ | ‘<b>^</b>’ | ‘<b>%</b>’ | 120218e3e3a7aSWarner Losh ‘<b>&</b>’ | ‘<b>~</b>’ | ‘<b>|</b>’ | ‘<b>>></b>’ | ‘<b><<</b>’ | ‘<b>..</b>’ | 120228e3e3a7aSWarner Losh ‘<b><</b>’ | ‘<b><=</b>’ | ‘<b>></b>’ | ‘<b>>=</b>’ | ‘<b>==</b>’ | ‘<b>~=</b>’ | 120238e3e3a7aSWarner Losh <b>and</b> | <b>or</b> 120248e3e3a7aSWarner Losh 120258e3e3a7aSWarner Losh unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’ | ‘<b>~</b>’ 120268e3e3a7aSWarner Losh 120278e3e3a7aSWarner Losh</pre> 120288e3e3a7aSWarner Losh 120298e3e3a7aSWarner Losh<p> 120308e3e3a7aSWarner Losh 120318e3e3a7aSWarner Losh 120328e3e3a7aSWarner Losh 120338e3e3a7aSWarner Losh 120348e3e3a7aSWarner Losh 120358e3e3a7aSWarner Losh 120368e3e3a7aSWarner Losh 120378e3e3a7aSWarner Losh<P CLASS="footer"> 120388e3e3a7aSWarner LoshLast update: 12039*a9490b81SWarner LoshTue May 2 20:09:38 UTC 2023 120408e3e3a7aSWarner Losh</P> 120418e3e3a7aSWarner Losh<!-- 12042*a9490b81SWarner LoshLast change: revised for Lua 5.4.6 120438e3e3a7aSWarner Losh--> 120448e3e3a7aSWarner Losh 120458e3e3a7aSWarner Losh</body></html> 120468e3e3a7aSWarner Losh 12047