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*8c784bb8SWarner LoshCopyright © 2020–2022 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>, 668e3e3a7aSWarner Loshthe common subset of Standard C and C++. 678e3e3a7aSWarner LoshThe Lua distribution includes a host program called <code>lua</code>, 688e3e3a7aSWarner Loshwhich uses the Lua library to offer a complete, 698e3e3a7aSWarner Loshstandalone Lua interpreter, 708e3e3a7aSWarner Loshfor interactive or batch use. 718e3e3a7aSWarner LoshLua is intended to be used both as a powerful, lightweight, 728e3e3a7aSWarner Loshembeddable scripting language for any program that needs one, 738e3e3a7aSWarner Loshand as a powerful but lightweight and efficient stand-alone language. 748e3e3a7aSWarner Losh 758e3e3a7aSWarner Losh 768e3e3a7aSWarner Losh<p> 778e3e3a7aSWarner LoshAs an extension language, Lua has no notion of a "main" program: 788e3e3a7aSWarner Loshit works <em>embedded</em> in a host client, 798e3e3a7aSWarner Loshcalled the <em>embedding program</em> or simply the <em>host</em>. 808e3e3a7aSWarner Losh(Frequently, this host is the stand-alone <code>lua</code> program.) 818e3e3a7aSWarner LoshThe host program can invoke functions to execute a piece of Lua code, 828e3e3a7aSWarner Loshcan write and read Lua variables, 838e3e3a7aSWarner Loshand can register C functions to be called by Lua code. 848e3e3a7aSWarner LoshThrough the use of C functions, Lua can be augmented to cope with 858e3e3a7aSWarner Losha wide range of different domains, 868e3e3a7aSWarner Loshthus creating customized programming languages sharing a syntactical framework. 878e3e3a7aSWarner Losh 888e3e3a7aSWarner Losh 898e3e3a7aSWarner Losh<p> 908e3e3a7aSWarner LoshLua is free software, 918e3e3a7aSWarner Loshand is provided as usual with no guarantees, 928e3e3a7aSWarner Loshas stated in its license. 938e3e3a7aSWarner LoshThe implementation described in this manual is available 948e3e3a7aSWarner Loshat Lua's official web site, <code>www.lua.org</code>. 958e3e3a7aSWarner Losh 968e3e3a7aSWarner Losh 978e3e3a7aSWarner Losh<p> 988e3e3a7aSWarner LoshLike any other reference manual, 998e3e3a7aSWarner Loshthis document is dry in places. 1008e3e3a7aSWarner LoshFor a discussion of the decisions behind the design of Lua, 1018e3e3a7aSWarner Loshsee the technical papers available at Lua's web site. 1028e3e3a7aSWarner LoshFor a detailed introduction to programming in Lua, 1038e3e3a7aSWarner Loshsee Roberto's book, <em>Programming in Lua</em>. 1048e3e3a7aSWarner Losh 1058e3e3a7aSWarner Losh 1068e3e3a7aSWarner Losh 1078e3e3a7aSWarner Losh<h1>2 – <a name="2">Basic Concepts</a></h1> 1088e3e3a7aSWarner Losh 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. 146*8c784bb8SWarner LoshDespite its name, 147*8c784bb8SWarner Losh<b>false</b> is frequently used as an alternative to <b>nil</b>, 148*8c784bb8SWarner Loshwith the key difference that <b>false</b> behaves 149*8c784bb8SWarner Loshlike a regular value in a table, 150*8c784bb8SWarner 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, 442*8c784bb8SWarner 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 909*8c784bb8SWarner 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> 964*8c784bb8SWarner LoshFinalizers cannot yield nor run the garbage collector. 965*8c784bb8SWarner 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, 13828e3e3a7aSWarner Loshmarked by a letter '<code>p</code>' or '<code>P</code>'. 13830495ed39SKyle Evans 13840495ed39SKyle Evans 13850495ed39SKyle Evans<p> 13868e3e3a7aSWarner LoshA numeric constant with a radix point or an exponent 13878e3e3a7aSWarner Loshdenotes a float; 13888e3e3a7aSWarner Loshotherwise, 13890495ed39SKyle Evansif its value fits in an integer or it is a hexadecimal constant, 13900495ed39SKyle Evansit denotes an integer; 13910495ed39SKyle Evansotherwise (that is, a decimal integer numeral that overflows), 13920495ed39SKyle Evansit denotes a float. 13930495ed39SKyle EvansHexadecimal numerals with neither a radix point nor an exponent 13940495ed39SKyle Evansalways denote an integer value; 13950495ed39SKyle Evansif the value overflows, it <em>wraps around</em> 13960495ed39SKyle Evansto fit into a valid integer. 13970495ed39SKyle Evans 13980495ed39SKyle Evans 13990495ed39SKyle Evans<p> 14008e3e3a7aSWarner LoshExamples of valid integer constants are 14018e3e3a7aSWarner Losh 14028e3e3a7aSWarner Losh<pre> 14038e3e3a7aSWarner Losh 3 345 0xff 0xBEBADA 14048e3e3a7aSWarner Losh</pre><p> 14058e3e3a7aSWarner LoshExamples of valid float constants are 14068e3e3a7aSWarner Losh 14078e3e3a7aSWarner Losh<pre> 14088e3e3a7aSWarner Losh 3.0 3.1416 314.16e-2 0.31416E1 34e1 14098e3e3a7aSWarner Losh 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 14108e3e3a7aSWarner Losh</pre> 14118e3e3a7aSWarner Losh 14128e3e3a7aSWarner Losh<p> 14138e3e3a7aSWarner LoshA <em>comment</em> starts with a double hyphen (<code>--</code>) 14148e3e3a7aSWarner Loshanywhere outside a string. 14158e3e3a7aSWarner LoshIf the text immediately after <code>--</code> is not an opening long bracket, 14168e3e3a7aSWarner Loshthe comment is a <em>short comment</em>, 14178e3e3a7aSWarner Loshwhich runs until the end of the line. 14188e3e3a7aSWarner LoshOtherwise, it is a <em>long comment</em>, 14198e3e3a7aSWarner Loshwhich runs until the corresponding closing long bracket. 14208e3e3a7aSWarner Losh 14218e3e3a7aSWarner Losh 14228e3e3a7aSWarner Losh 14238e3e3a7aSWarner Losh 14248e3e3a7aSWarner Losh 14258e3e3a7aSWarner Losh<h2>3.2 – <a name="3.2">Variables</a></h2> 14268e3e3a7aSWarner Losh 14278e3e3a7aSWarner Losh<p> 14288e3e3a7aSWarner LoshVariables are places that store values. 14298e3e3a7aSWarner LoshThere are three kinds of variables in Lua: 14308e3e3a7aSWarner Loshglobal variables, local variables, and table fields. 14318e3e3a7aSWarner Losh 14328e3e3a7aSWarner Losh 14338e3e3a7aSWarner Losh<p> 14348e3e3a7aSWarner LoshA single name can denote a global variable or a local variable 14358e3e3a7aSWarner Losh(or a function's formal parameter, 14368e3e3a7aSWarner Loshwhich is a particular kind of local variable): 14378e3e3a7aSWarner Losh 14388e3e3a7aSWarner Losh<pre> 14398e3e3a7aSWarner Losh var ::= Name 14408e3e3a7aSWarner Losh</pre><p> 14410495ed39SKyle EvansName denotes identifiers (see <a href="#3.1">§3.1</a>). 14428e3e3a7aSWarner Losh 14438e3e3a7aSWarner Losh 14448e3e3a7aSWarner Losh<p> 14458e3e3a7aSWarner LoshAny variable name is assumed to be global unless explicitly declared 14468e3e3a7aSWarner Loshas a local (see <a href="#3.3.7">§3.3.7</a>). 14478e3e3a7aSWarner LoshLocal variables are <em>lexically scoped</em>: 14488e3e3a7aSWarner Loshlocal variables can be freely accessed by functions 14498e3e3a7aSWarner Loshdefined inside their scope (see <a href="#3.5">§3.5</a>). 14508e3e3a7aSWarner Losh 14518e3e3a7aSWarner Losh 14528e3e3a7aSWarner Losh<p> 14538e3e3a7aSWarner LoshBefore the first assignment to a variable, its value is <b>nil</b>. 14548e3e3a7aSWarner Losh 14558e3e3a7aSWarner Losh 14568e3e3a7aSWarner Losh<p> 14578e3e3a7aSWarner LoshSquare brackets are used to index a table: 14588e3e3a7aSWarner Losh 14598e3e3a7aSWarner Losh<pre> 14608e3e3a7aSWarner Losh var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ 14618e3e3a7aSWarner Losh</pre><p> 1462e112e9d2SKyle EvansThe meaning of accesses to table fields can be changed via metatables 1463e112e9d2SKyle Evans(see <a href="#2.4">§2.4</a>). 14648e3e3a7aSWarner Losh 14658e3e3a7aSWarner Losh 14668e3e3a7aSWarner Losh<p> 14678e3e3a7aSWarner LoshThe syntax <code>var.Name</code> is just syntactic sugar for 14688e3e3a7aSWarner Losh<code>var["Name"]</code>: 14698e3e3a7aSWarner Losh 14708e3e3a7aSWarner Losh<pre> 14718e3e3a7aSWarner Losh var ::= prefixexp ‘<b>.</b>’ Name 14728e3e3a7aSWarner Losh</pre> 14738e3e3a7aSWarner Losh 14748e3e3a7aSWarner Losh<p> 14758e3e3a7aSWarner LoshAn access to a global variable <code>x</code> 14768e3e3a7aSWarner Loshis equivalent to <code>_ENV.x</code>. 14778e3e3a7aSWarner LoshDue to the way that chunks are compiled, 14780495ed39SKyle Evansthe variable <code>_ENV</code> itself is never global (see <a href="#2.2">§2.2</a>). 14798e3e3a7aSWarner Losh 14808e3e3a7aSWarner Losh 14818e3e3a7aSWarner Losh 14828e3e3a7aSWarner Losh 14838e3e3a7aSWarner Losh 14848e3e3a7aSWarner Losh<h2>3.3 – <a name="3.3">Statements</a></h2> 14858e3e3a7aSWarner Losh 14860495ed39SKyle Evans 14870495ed39SKyle Evans 14888e3e3a7aSWarner Losh<p> 14898e3e3a7aSWarner LoshLua supports an almost conventional set of statements, 14900495ed39SKyle Evanssimilar to those in other conventional languages. 14918e3e3a7aSWarner LoshThis set includes 14920495ed39SKyle Evansblocks, assignments, control structures, function calls, 14938e3e3a7aSWarner Loshand variable declarations. 14948e3e3a7aSWarner Losh 14958e3e3a7aSWarner Losh 14968e3e3a7aSWarner Losh 14970495ed39SKyle Evans 14980495ed39SKyle Evans 14998e3e3a7aSWarner Losh<h3>3.3.1 – <a name="3.3.1">Blocks</a></h3> 15008e3e3a7aSWarner Losh 15018e3e3a7aSWarner Losh<p> 15028e3e3a7aSWarner LoshA block is a list of statements, 15038e3e3a7aSWarner Loshwhich are executed sequentially: 15048e3e3a7aSWarner Losh 15058e3e3a7aSWarner Losh<pre> 15068e3e3a7aSWarner Losh block ::= {stat} 15078e3e3a7aSWarner Losh</pre><p> 15088e3e3a7aSWarner LoshLua has <em>empty statements</em> 15098e3e3a7aSWarner Loshthat allow you to separate statements with semicolons, 15108e3e3a7aSWarner Loshstart a block with a semicolon 15118e3e3a7aSWarner Loshor write two semicolons in sequence: 15128e3e3a7aSWarner Losh 15138e3e3a7aSWarner Losh<pre> 15148e3e3a7aSWarner Losh stat ::= ‘<b>;</b>’ 15158e3e3a7aSWarner Losh</pre> 15168e3e3a7aSWarner Losh 15178e3e3a7aSWarner Losh<p> 15180495ed39SKyle EvansBoth function calls and assignments 15198e3e3a7aSWarner Loshcan start with an open parenthesis. 15208e3e3a7aSWarner LoshThis possibility leads to an ambiguity in Lua's grammar. 15218e3e3a7aSWarner LoshConsider the following fragment: 15228e3e3a7aSWarner Losh 15238e3e3a7aSWarner Losh<pre> 15248e3e3a7aSWarner Losh a = b + c 15258e3e3a7aSWarner Losh (print or io.write)('done') 15268e3e3a7aSWarner Losh</pre><p> 15270495ed39SKyle EvansThe grammar could see this fragment in two ways: 15288e3e3a7aSWarner Losh 15298e3e3a7aSWarner Losh<pre> 15308e3e3a7aSWarner Losh a = b + c(print or io.write)('done') 15318e3e3a7aSWarner Losh 15328e3e3a7aSWarner Losh a = b + c; (print or io.write)('done') 15338e3e3a7aSWarner Losh</pre><p> 15348e3e3a7aSWarner LoshThe current parser always sees such constructions 15358e3e3a7aSWarner Loshin the first way, 15368e3e3a7aSWarner Loshinterpreting the open parenthesis 15378e3e3a7aSWarner Loshas the start of the arguments to a call. 15388e3e3a7aSWarner LoshTo avoid this ambiguity, 15398e3e3a7aSWarner Loshit is a good practice to always precede with a semicolon 15408e3e3a7aSWarner Loshstatements that start with a parenthesis: 15418e3e3a7aSWarner Losh 15428e3e3a7aSWarner Losh<pre> 15438e3e3a7aSWarner Losh ;(print or io.write)('done') 15448e3e3a7aSWarner Losh</pre> 15458e3e3a7aSWarner Losh 15468e3e3a7aSWarner Losh<p> 15478e3e3a7aSWarner LoshA block can be explicitly delimited to produce a single statement: 15488e3e3a7aSWarner Losh 15498e3e3a7aSWarner Losh<pre> 15508e3e3a7aSWarner Losh stat ::= <b>do</b> block <b>end</b> 15518e3e3a7aSWarner Losh</pre><p> 15528e3e3a7aSWarner LoshExplicit blocks are useful 15538e3e3a7aSWarner Loshto control the scope of variable declarations. 15548e3e3a7aSWarner LoshExplicit blocks are also sometimes used to 15558e3e3a7aSWarner Loshadd a <b>return</b> statement in the middle 15568e3e3a7aSWarner Loshof another block (see <a href="#3.3.4">§3.3.4</a>). 15578e3e3a7aSWarner Losh 15588e3e3a7aSWarner Losh 15598e3e3a7aSWarner Losh 15608e3e3a7aSWarner Losh 15618e3e3a7aSWarner Losh 15628e3e3a7aSWarner Losh<h3>3.3.2 – <a name="3.3.2">Chunks</a></h3> 15638e3e3a7aSWarner Losh 15648e3e3a7aSWarner Losh<p> 15658e3e3a7aSWarner LoshThe unit of compilation of Lua is called a <em>chunk</em>. 15668e3e3a7aSWarner LoshSyntactically, 15678e3e3a7aSWarner Losha chunk is simply a block: 15688e3e3a7aSWarner Losh 15698e3e3a7aSWarner Losh<pre> 15708e3e3a7aSWarner Losh chunk ::= block 15718e3e3a7aSWarner Losh</pre> 15728e3e3a7aSWarner Losh 15738e3e3a7aSWarner Losh<p> 15748e3e3a7aSWarner LoshLua handles a chunk as the body of an anonymous function 15758e3e3a7aSWarner Loshwith a variable number of arguments 15768e3e3a7aSWarner Losh(see <a href="#3.4.11">§3.4.11</a>). 15778e3e3a7aSWarner LoshAs such, chunks can define local variables, 15788e3e3a7aSWarner Loshreceive arguments, and return values. 15798e3e3a7aSWarner LoshMoreover, such anonymous function is compiled as in the 15808e3e3a7aSWarner Loshscope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>). 15810495ed39SKyle EvansThe resulting function always has <code>_ENV</code> as its only external variable, 15828e3e3a7aSWarner Losheven if it does not use that variable. 15838e3e3a7aSWarner Losh 15848e3e3a7aSWarner Losh 15858e3e3a7aSWarner Losh<p> 15868e3e3a7aSWarner LoshA chunk can be stored in a file or in a string inside the host program. 15878e3e3a7aSWarner LoshTo execute a chunk, 15888e3e3a7aSWarner LoshLua first <em>loads</em> it, 15898e3e3a7aSWarner Loshprecompiling the chunk's code into instructions for a virtual machine, 15908e3e3a7aSWarner Loshand then Lua executes the compiled code 15918e3e3a7aSWarner Loshwith an interpreter for the virtual machine. 15928e3e3a7aSWarner Losh 15938e3e3a7aSWarner Losh 15948e3e3a7aSWarner Losh<p> 15958e3e3a7aSWarner LoshChunks can also be precompiled into binary form; 15960495ed39SKyle Evanssee the program <code>luac</code> and the function <a href="#pdf-string.dump"><code>string.dump</code></a> for details. 15978e3e3a7aSWarner LoshPrograms in source and compiled forms are interchangeable; 15988e3e3a7aSWarner LoshLua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>). 15998e3e3a7aSWarner Losh 16008e3e3a7aSWarner Losh 16018e3e3a7aSWarner Losh 16028e3e3a7aSWarner Losh 16038e3e3a7aSWarner Losh 16048e3e3a7aSWarner Losh<h3>3.3.3 – <a name="3.3.3">Assignment</a></h3> 16058e3e3a7aSWarner Losh 16068e3e3a7aSWarner Losh<p> 16078e3e3a7aSWarner LoshLua allows multiple assignments. 16088e3e3a7aSWarner LoshTherefore, the syntax for assignment 16098e3e3a7aSWarner Loshdefines a list of variables on the left side 16108e3e3a7aSWarner Loshand a list of expressions on the right side. 16118e3e3a7aSWarner LoshThe elements in both lists are separated by commas: 16128e3e3a7aSWarner Losh 16138e3e3a7aSWarner Losh<pre> 16148e3e3a7aSWarner Losh stat ::= varlist ‘<b>=</b>’ explist 16158e3e3a7aSWarner Losh varlist ::= var {‘<b>,</b>’ var} 16168e3e3a7aSWarner Losh explist ::= exp {‘<b>,</b>’ exp} 16178e3e3a7aSWarner Losh</pre><p> 16188e3e3a7aSWarner LoshExpressions are discussed in <a href="#3.4">§3.4</a>. 16198e3e3a7aSWarner Losh 16208e3e3a7aSWarner Losh 16218e3e3a7aSWarner Losh<p> 16228e3e3a7aSWarner LoshBefore the assignment, 16238e3e3a7aSWarner Loshthe list of values is <em>adjusted</em> to the length of 16248e3e3a7aSWarner Loshthe list of variables. 16258e3e3a7aSWarner LoshIf there are more values than needed, 16268e3e3a7aSWarner Loshthe excess values are thrown away. 16278e3e3a7aSWarner LoshIf there are fewer values than needed, 16280495ed39SKyle Evansthe list is extended with <b>nil</b>'s. 16298e3e3a7aSWarner LoshIf the list of expressions ends with a function call, 16308e3e3a7aSWarner Loshthen all values returned by that call enter the list of values, 16318e3e3a7aSWarner Loshbefore the adjustment 16328e3e3a7aSWarner Losh(except when the call is enclosed in parentheses; see <a href="#3.4">§3.4</a>). 16338e3e3a7aSWarner Losh 16348e3e3a7aSWarner Losh 16358e3e3a7aSWarner Losh<p> 1636*8c784bb8SWarner LoshIf a variable is both assigned and read 1637*8c784bb8SWarner Loshinside a multiple assignment, 1638*8c784bb8SWarner LoshLua ensures all reads get the value of the variable 1639*8c784bb8SWarner Loshbefore the assignment. 16408e3e3a7aSWarner LoshThus the code 16418e3e3a7aSWarner Losh 16428e3e3a7aSWarner Losh<pre> 16438e3e3a7aSWarner Losh i = 3 16448e3e3a7aSWarner Losh i, a[i] = i+1, 20 16458e3e3a7aSWarner Losh</pre><p> 16468e3e3a7aSWarner Loshsets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 16478e3e3a7aSWarner Loshbecause the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 16488e3e3a7aSWarner Loshbefore it is assigned 4. 16498e3e3a7aSWarner LoshSimilarly, the line 16508e3e3a7aSWarner Losh 16518e3e3a7aSWarner Losh<pre> 16528e3e3a7aSWarner Losh x, y = y, x 16538e3e3a7aSWarner Losh</pre><p> 16548e3e3a7aSWarner Loshexchanges the values of <code>x</code> and <code>y</code>, 16558e3e3a7aSWarner Loshand 16568e3e3a7aSWarner Losh 16578e3e3a7aSWarner Losh<pre> 16588e3e3a7aSWarner Losh x, y, z = y, z, x 16598e3e3a7aSWarner Losh</pre><p> 16608e3e3a7aSWarner Loshcyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 16618e3e3a7aSWarner Losh 16628e3e3a7aSWarner Losh 16638e3e3a7aSWarner Losh<p> 1664*8c784bb8SWarner LoshNote that this guarantee covers only accesses 1665*8c784bb8SWarner Loshsyntactically inside the assignment statement. 1666*8c784bb8SWarner LoshIf a function or a metamethod called during the assignment 1667*8c784bb8SWarner Loshchanges the value of a variable, 1668*8c784bb8SWarner LoshLua gives no guarantees about the order of that access. 1669*8c784bb8SWarner Losh 1670*8c784bb8SWarner Losh 1671*8c784bb8SWarner Losh<p> 16728e3e3a7aSWarner LoshAn assignment to a global name <code>x = val</code> 16738e3e3a7aSWarner Loshis equivalent to the assignment 16748e3e3a7aSWarner Losh<code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>). 16758e3e3a7aSWarner Losh 16768e3e3a7aSWarner Losh 1677e112e9d2SKyle Evans<p> 1678e112e9d2SKyle EvansThe meaning of assignments to table fields and 1679e112e9d2SKyle Evansglobal variables (which are actually table fields, too) 1680e112e9d2SKyle Evanscan be changed via metatables (see <a href="#2.4">§2.4</a>). 1681e112e9d2SKyle Evans 1682e112e9d2SKyle Evans 16838e3e3a7aSWarner Losh 16848e3e3a7aSWarner Losh 16858e3e3a7aSWarner Losh 16868e3e3a7aSWarner Losh<h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p> 16878e3e3a7aSWarner LoshThe control structures 16888e3e3a7aSWarner Losh<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 16898e3e3a7aSWarner Loshfamiliar syntax: 16908e3e3a7aSWarner Losh 16918e3e3a7aSWarner Losh 16928e3e3a7aSWarner Losh 16938e3e3a7aSWarner Losh 16948e3e3a7aSWarner Losh<pre> 16958e3e3a7aSWarner Losh stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 16968e3e3a7aSWarner Losh stat ::= <b>repeat</b> block <b>until</b> exp 16978e3e3a7aSWarner 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> 16988e3e3a7aSWarner Losh</pre><p> 16998e3e3a7aSWarner LoshLua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>). 17008e3e3a7aSWarner Losh 17018e3e3a7aSWarner Losh 17028e3e3a7aSWarner Losh<p> 17038e3e3a7aSWarner LoshThe condition expression of a 17048e3e3a7aSWarner Loshcontrol structure can return any value. 17050495ed39SKyle EvansBoth <b>false</b> and <b>nil</b> test false. 17060495ed39SKyle EvansAll values different from <b>nil</b> and <b>false</b> test true. 17070495ed39SKyle EvansIn particular, the number 0 and the empty string also test true. 17088e3e3a7aSWarner Losh 17098e3e3a7aSWarner Losh 17108e3e3a7aSWarner Losh<p> 17118e3e3a7aSWarner LoshIn the <b>repeat</b>–<b>until</b> loop, 17128e3e3a7aSWarner Loshthe inner block does not end at the <b>until</b> keyword, 17138e3e3a7aSWarner Loshbut only after the condition. 17148e3e3a7aSWarner LoshSo, the condition can refer to local variables 17158e3e3a7aSWarner Loshdeclared inside the loop block. 17168e3e3a7aSWarner Losh 17178e3e3a7aSWarner Losh 17188e3e3a7aSWarner Losh<p> 17198e3e3a7aSWarner LoshThe <b>goto</b> statement transfers the program control to a label. 17208e3e3a7aSWarner LoshFor syntactical reasons, 17218e3e3a7aSWarner Loshlabels in Lua are considered statements too: 17228e3e3a7aSWarner Losh 17238e3e3a7aSWarner Losh 17248e3e3a7aSWarner Losh 17258e3e3a7aSWarner Losh<pre> 17268e3e3a7aSWarner Losh stat ::= <b>goto</b> Name 17278e3e3a7aSWarner Losh stat ::= label 17288e3e3a7aSWarner Losh label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 17298e3e3a7aSWarner Losh</pre> 17308e3e3a7aSWarner Losh 17318e3e3a7aSWarner Losh<p> 17328e3e3a7aSWarner LoshA label is visible in the entire block where it is defined, 17330495ed39SKyle Evansexcept inside nested functions. 17348e3e3a7aSWarner LoshA goto may jump to any visible label as long as it does not 17358e3e3a7aSWarner Loshenter into the scope of a local variable. 17360495ed39SKyle EvansA label should not be declared 17370495ed39SKyle Evanswhere a label with the same name is visible, 17380495ed39SKyle Evanseven if this other label has been declared in an enclosing block. 17398e3e3a7aSWarner Losh 17408e3e3a7aSWarner Losh 17418e3e3a7aSWarner Losh<p> 17428e3e3a7aSWarner LoshLabels and empty statements are called <em>void statements</em>, 17438e3e3a7aSWarner Loshas they perform no actions. 17448e3e3a7aSWarner Losh 17458e3e3a7aSWarner Losh 17468e3e3a7aSWarner Losh<p> 17478e3e3a7aSWarner LoshThe <b>break</b> statement terminates the execution of a 17488e3e3a7aSWarner Losh<b>while</b>, <b>repeat</b>, or <b>for</b> loop, 17498e3e3a7aSWarner Loshskipping to the next statement after the loop: 17508e3e3a7aSWarner Losh 17518e3e3a7aSWarner Losh 17528e3e3a7aSWarner Losh<pre> 17538e3e3a7aSWarner Losh stat ::= <b>break</b> 17548e3e3a7aSWarner Losh</pre><p> 17558e3e3a7aSWarner LoshA <b>break</b> ends the innermost enclosing loop. 17568e3e3a7aSWarner Losh 17578e3e3a7aSWarner Losh 17588e3e3a7aSWarner Losh<p> 17598e3e3a7aSWarner LoshThe <b>return</b> statement is used to return values 17608e3e3a7aSWarner Loshfrom a function or a chunk 17610495ed39SKyle Evans(which is handled as an anonymous function). 17628e3e3a7aSWarner Losh 17638e3e3a7aSWarner LoshFunctions can return more than one value, 17648e3e3a7aSWarner Loshso the syntax for the <b>return</b> statement is 17658e3e3a7aSWarner Losh 17668e3e3a7aSWarner Losh<pre> 17678e3e3a7aSWarner Losh stat ::= <b>return</b> [explist] [‘<b>;</b>’] 17688e3e3a7aSWarner Losh</pre> 17698e3e3a7aSWarner Losh 17708e3e3a7aSWarner Losh<p> 17718e3e3a7aSWarner LoshThe <b>return</b> statement can only be written 17728e3e3a7aSWarner Loshas the last statement of a block. 17730495ed39SKyle EvansIf it is necessary to <b>return</b> in the middle of a block, 17748e3e3a7aSWarner Loshthen an explicit inner block can be used, 17758e3e3a7aSWarner Loshas in the idiom <code>do return end</code>, 17768e3e3a7aSWarner Loshbecause now <b>return</b> is the last statement in its (inner) block. 17778e3e3a7aSWarner Losh 17788e3e3a7aSWarner Losh 17798e3e3a7aSWarner Losh 17808e3e3a7aSWarner Losh 17818e3e3a7aSWarner Losh 17828e3e3a7aSWarner Losh<h3>3.3.5 – <a name="3.3.5">For Statement</a></h3> 17838e3e3a7aSWarner Losh 17848e3e3a7aSWarner Losh<p> 17858e3e3a7aSWarner Losh 17868e3e3a7aSWarner LoshThe <b>for</b> statement has two forms: 17878e3e3a7aSWarner Loshone numerical and one generic. 17888e3e3a7aSWarner Losh 17898e3e3a7aSWarner Losh 17900495ed39SKyle Evans 17910495ed39SKyle Evans<h4>The numerical <b>for</b> loop</h4> 17920495ed39SKyle Evans 17938e3e3a7aSWarner Losh<p> 17948e3e3a7aSWarner LoshThe numerical <b>for</b> loop repeats a block of code while a 17950495ed39SKyle Evanscontrol variable goes through an arithmetic progression. 17968e3e3a7aSWarner LoshIt has the following syntax: 17978e3e3a7aSWarner Losh 17988e3e3a7aSWarner Losh<pre> 17998e3e3a7aSWarner Losh stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> 18008e3e3a7aSWarner Losh</pre><p> 18010495ed39SKyle EvansThe given identifier (Name) defines the control variable, 18020495ed39SKyle Evanswhich is a new variable local to the loop body (<em>block</em>). 18038e3e3a7aSWarner Losh 18048e3e3a7aSWarner Losh 18058e3e3a7aSWarner Losh<p> 18060495ed39SKyle EvansThe loop starts by evaluating once the three control expressions. 18070495ed39SKyle EvansTheir values are called respectively 18080495ed39SKyle Evansthe <em>initial value</em>, the <em>limit</em>, and the <em>step</em>. 18090495ed39SKyle EvansIf the step is absent, it defaults to 1. 18108e3e3a7aSWarner Losh 18118e3e3a7aSWarner Losh 18120495ed39SKyle Evans<p> 18130495ed39SKyle EvansIf both the initial value and the step are integers, 18140495ed39SKyle Evansthe loop is done with integers; 18150495ed39SKyle Evansnote that the limit may not be an integer. 18160495ed39SKyle EvansOtherwise, the three values are converted to 18170495ed39SKyle Evansfloats and the loop is done with floats. 18180495ed39SKyle EvansBeware of floating-point accuracy in this case. 18198e3e3a7aSWarner Losh 18208e3e3a7aSWarner Losh 18210495ed39SKyle Evans<p> 18220495ed39SKyle EvansAfter that initialization, 18230495ed39SKyle Evansthe loop body is repeated with the value of the control variable 18240495ed39SKyle Evansgoing through an arithmetic progression, 18250495ed39SKyle Evansstarting at the initial value, 18260495ed39SKyle Evanswith a common difference given by the step. 18270495ed39SKyle EvansA negative step makes a decreasing sequence; 18280495ed39SKyle Evansa step equal to zero raises an error. 18290495ed39SKyle EvansThe loop continues while the value is less than 18300495ed39SKyle Evansor equal to the limit 18310495ed39SKyle Evans(greater than or equal to for a negative step). 18320495ed39SKyle EvansIf the initial value is already greater than the limit 18330495ed39SKyle Evans(or less than, if the step is negative), 18340495ed39SKyle Evansthe body is not executed. 18358e3e3a7aSWarner Losh 18368e3e3a7aSWarner Losh 18370495ed39SKyle Evans<p> 18380495ed39SKyle EvansFor integer loops, 18390495ed39SKyle Evansthe control variable never wraps around; 18400495ed39SKyle Evansinstead, the loop ends in case of an overflow. 18410495ed39SKyle Evans 18420495ed39SKyle Evans 18430495ed39SKyle Evans<p> 18440495ed39SKyle EvansYou should not change the value of the control variable 18450495ed39SKyle Evansduring the loop. 18468e3e3a7aSWarner LoshIf you need its value after the loop, 18478e3e3a7aSWarner Loshassign it to another variable before exiting the loop. 18488e3e3a7aSWarner Losh 18490495ed39SKyle Evans 18500495ed39SKyle Evans 18510495ed39SKyle Evans 18520495ed39SKyle Evans 18530495ed39SKyle Evans<h4>The generic <b>for</b> loop</h4> 18548e3e3a7aSWarner Losh 18558e3e3a7aSWarner Losh<p> 18568e3e3a7aSWarner LoshThe generic <b>for</b> statement works over functions, 18578e3e3a7aSWarner Loshcalled <em>iterators</em>. 18588e3e3a7aSWarner LoshOn each iteration, the iterator function is called to produce a new value, 18598e3e3a7aSWarner Loshstopping when this new value is <b>nil</b>. 18608e3e3a7aSWarner LoshThe generic <b>for</b> loop has the following syntax: 18618e3e3a7aSWarner Losh 18628e3e3a7aSWarner Losh<pre> 18638e3e3a7aSWarner Losh stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> 18648e3e3a7aSWarner Losh namelist ::= Name {‘<b>,</b>’ Name} 18658e3e3a7aSWarner Losh</pre><p> 18668e3e3a7aSWarner LoshA <b>for</b> statement like 18678e3e3a7aSWarner Losh 18688e3e3a7aSWarner Losh<pre> 18690495ed39SKyle Evans for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>body</em> end 18708e3e3a7aSWarner Losh</pre><p> 18710495ed39SKyle Evansworks as follows. 18728e3e3a7aSWarner Losh 18738e3e3a7aSWarner Losh 18740495ed39SKyle Evans<p> 18750495ed39SKyle EvansThe names <em>var_i</em> declare loop variables local to the loop body. 18760495ed39SKyle EvansThe first of these variables is the <em>control variable</em>. 18778e3e3a7aSWarner Losh 18780495ed39SKyle Evans 18790495ed39SKyle Evans<p> 18800495ed39SKyle EvansThe loop starts by evaluating <em>explist</em> 18810495ed39SKyle Evansto produce four values: 18820495ed39SKyle Evansan <em>iterator function</em>, 18838e3e3a7aSWarner Losha <em>state</em>, 18840495ed39SKyle Evansan initial value for the control variable, 18850495ed39SKyle Evansand a <em>closing value</em>. 18868e3e3a7aSWarner Losh 18878e3e3a7aSWarner Losh 18880495ed39SKyle Evans<p> 18890495ed39SKyle EvansThen, at each iteration, 18900495ed39SKyle EvansLua calls the iterator function with two arguments: 18910495ed39SKyle Evansthe state and the control variable. 18920495ed39SKyle EvansThe results from this call are then assigned to the loop variables, 18930495ed39SKyle Evansfollowing the rules of multiple assignments (see <a href="#3.3.3">§3.3.3</a>). 18940495ed39SKyle EvansIf the control variable becomes <b>nil</b>, 18950495ed39SKyle Evansthe loop terminates. 18960495ed39SKyle EvansOtherwise, the body is executed and the loop goes 18970495ed39SKyle Evansto the next iteration. 18988e3e3a7aSWarner Losh 18998e3e3a7aSWarner Losh 19000495ed39SKyle Evans<p> 19010495ed39SKyle EvansThe closing value behaves like a 19020495ed39SKyle Evansto-be-closed variable (see <a href="#3.3.8">§3.3.8</a>), 19030495ed39SKyle Evanswhich can be used to release resources when the loop ends. 19040495ed39SKyle EvansOtherwise, it does not interfere with the loop. 19050495ed39SKyle Evans 19060495ed39SKyle Evans 19070495ed39SKyle Evans<p> 19080495ed39SKyle EvansYou should not change the value of the control variable 19090495ed39SKyle Evansduring the loop. 19100495ed39SKyle Evans 19110495ed39SKyle Evans 19120495ed39SKyle Evans 19138e3e3a7aSWarner Losh 19148e3e3a7aSWarner Losh 19158e3e3a7aSWarner Losh 19168e3e3a7aSWarner Losh 19178e3e3a7aSWarner Losh<h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p> 19188e3e3a7aSWarner LoshTo allow possible side-effects, 19198e3e3a7aSWarner Loshfunction calls can be executed as statements: 19208e3e3a7aSWarner Losh 19218e3e3a7aSWarner Losh<pre> 19228e3e3a7aSWarner Losh stat ::= functioncall 19238e3e3a7aSWarner Losh</pre><p> 19248e3e3a7aSWarner LoshIn this case, all returned values are thrown away. 19258e3e3a7aSWarner LoshFunction calls are explained in <a href="#3.4.10">§3.4.10</a>. 19268e3e3a7aSWarner Losh 19278e3e3a7aSWarner Losh 19288e3e3a7aSWarner Losh 19298e3e3a7aSWarner Losh 19308e3e3a7aSWarner Losh 19318e3e3a7aSWarner Losh<h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p> 19328e3e3a7aSWarner LoshLocal variables can be declared anywhere inside a block. 19330495ed39SKyle EvansThe declaration can include an initialization: 19348e3e3a7aSWarner Losh 19358e3e3a7aSWarner Losh<pre> 19360495ed39SKyle Evans stat ::= <b>local</b> attnamelist [‘<b>=</b>’ explist] 19370495ed39SKyle Evans attnamelist ::= Name attrib {‘<b>,</b>’ Name attrib} 19388e3e3a7aSWarner Losh</pre><p> 19398e3e3a7aSWarner LoshIf present, an initial assignment has the same semantics 19408e3e3a7aSWarner Loshof a multiple assignment (see <a href="#3.3.3">§3.3.3</a>). 19418e3e3a7aSWarner LoshOtherwise, all variables are initialized with <b>nil</b>. 19428e3e3a7aSWarner Losh 19438e3e3a7aSWarner Losh 19448e3e3a7aSWarner Losh<p> 19450495ed39SKyle EvansEach variable name may be postfixed by an attribute 19460495ed39SKyle Evans(a name between angle brackets): 19470495ed39SKyle Evans 19480495ed39SKyle Evans<pre> 19490495ed39SKyle Evans attrib ::= [‘<b><</b>’ Name ‘<b>></b>’] 19500495ed39SKyle Evans</pre><p> 19510495ed39SKyle EvansThere are two possible attributes: 19520495ed39SKyle Evans<code>const</code>, which declares a constant variable, 19530495ed39SKyle Evansthat is, a variable that cannot be assigned to 19540495ed39SKyle Evansafter its initialization; 19550495ed39SKyle Evansand <code>close</code>, which declares a to-be-closed variable (see <a href="#3.3.8">§3.3.8</a>). 19560495ed39SKyle EvansA list of variables can contain at most one to-be-closed variable. 19570495ed39SKyle Evans 19580495ed39SKyle Evans 19590495ed39SKyle Evans<p> 19608e3e3a7aSWarner LoshA chunk is also a block (see <a href="#3.3.2">§3.3.2</a>), 19618e3e3a7aSWarner Loshand so local variables can be declared in a chunk outside any explicit block. 19628e3e3a7aSWarner Losh 19638e3e3a7aSWarner Losh 19648e3e3a7aSWarner Losh<p> 19658e3e3a7aSWarner LoshThe visibility rules for local variables are explained in <a href="#3.5">§3.5</a>. 19668e3e3a7aSWarner Losh 19678e3e3a7aSWarner Losh 19688e3e3a7aSWarner Losh 19698e3e3a7aSWarner Losh 19708e3e3a7aSWarner Losh 19710495ed39SKyle Evans<h3>3.3.8 – <a name="3.3.8">To-be-closed Variables</a></h3> 19720495ed39SKyle Evans 19730495ed39SKyle Evans<p> 19740495ed39SKyle EvansA to-be-closed variable behaves like a constant local variable, 19750495ed39SKyle Evansexcept that its value is <em>closed</em> whenever the variable 19760495ed39SKyle Evansgoes out of scope, including normal block termination, 19770495ed39SKyle Evansexiting its block by <b>break</b>/<b>goto</b>/<b>return</b>, 19780495ed39SKyle Evansor exiting by an error. 19790495ed39SKyle Evans 19800495ed39SKyle Evans 19810495ed39SKyle Evans<p> 19820495ed39SKyle EvansHere, to <em>close</em> a value means 19830495ed39SKyle Evansto call its <code>__close</code> metamethod. 19840495ed39SKyle EvansWhen calling the metamethod, 19850495ed39SKyle Evansthe value itself is passed as the first argument 19860495ed39SKyle Evansand the error object that caused the exit (if any) 19870495ed39SKyle Evansis passed as a second argument; 19880495ed39SKyle Evansif there was no error, the second argument is <b>nil</b>. 19890495ed39SKyle Evans 19900495ed39SKyle Evans 19910495ed39SKyle Evans<p> 19920495ed39SKyle EvansThe value assigned to a to-be-closed variable 19930495ed39SKyle Evansmust have a <code>__close</code> metamethod 19940495ed39SKyle Evansor be a false value. 19950495ed39SKyle Evans(<b>nil</b> and <b>false</b> are ignored as to-be-closed values.) 19960495ed39SKyle Evans 19970495ed39SKyle Evans 19980495ed39SKyle Evans<p> 19990495ed39SKyle EvansIf several to-be-closed variables go out of scope at the same event, 20000495ed39SKyle Evansthey are closed in the reverse order that they were declared. 20010495ed39SKyle Evans 20020495ed39SKyle Evans 20030495ed39SKyle Evans<p> 20040495ed39SKyle EvansIf there is any error while running a closing method, 20050495ed39SKyle Evansthat error is handled like an error in the regular code 20060495ed39SKyle Evanswhere the variable was defined. 20070495ed39SKyle EvansAfter an error, 20080495ed39SKyle Evansthe other pending closing methods will still be called. 20090495ed39SKyle Evans 20100495ed39SKyle Evans 20110495ed39SKyle Evans<p> 20120495ed39SKyle EvansIf a coroutine yields and is never resumed again, 20130495ed39SKyle Evanssome variables may never go out of scope, 20140495ed39SKyle Evansand therefore they will never be closed. 20150495ed39SKyle Evans(These variables are the ones created inside the coroutine 20160495ed39SKyle Evansand in scope at the point where the coroutine yielded.) 20170495ed39SKyle EvansSimilarly, if a coroutine ends with an error, 20180495ed39SKyle Evansit does not unwind its stack, 20190495ed39SKyle Evansso it does not close any variable. 20200495ed39SKyle EvansIn both cases, 20210495ed39SKyle Evansyou can either use finalizers 20220495ed39SKyle Evansor call <a href="#pdf-coroutine.close"><code>coroutine.close</code></a> to close the variables. 20230495ed39SKyle EvansHowever, if the coroutine was created 20240495ed39SKyle Evansthrough <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a>, 20250495ed39SKyle Evansthen its corresponding function will close the coroutine 20260495ed39SKyle Evansin case of errors. 20270495ed39SKyle Evans 20280495ed39SKyle Evans 20290495ed39SKyle Evans 20300495ed39SKyle Evans 20310495ed39SKyle Evans 20328e3e3a7aSWarner Losh 20338e3e3a7aSWarner Losh 20348e3e3a7aSWarner Losh<h2>3.4 – <a name="3.4">Expressions</a></h2> 20358e3e3a7aSWarner Losh 20360495ed39SKyle Evans 20370495ed39SKyle Evans 20388e3e3a7aSWarner Losh<p> 20398e3e3a7aSWarner LoshThe basic expressions in Lua are the following: 20408e3e3a7aSWarner Losh 20418e3e3a7aSWarner Losh<pre> 20428e3e3a7aSWarner Losh exp ::= prefixexp 20438e3e3a7aSWarner Losh exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 20448e3e3a7aSWarner Losh exp ::= Numeral 20458e3e3a7aSWarner Losh exp ::= LiteralString 20468e3e3a7aSWarner Losh exp ::= functiondef 20478e3e3a7aSWarner Losh exp ::= tableconstructor 20488e3e3a7aSWarner Losh exp ::= ‘<b>...</b>’ 20498e3e3a7aSWarner Losh exp ::= exp binop exp 20508e3e3a7aSWarner Losh exp ::= unop exp 20518e3e3a7aSWarner Losh prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 20528e3e3a7aSWarner Losh</pre> 20538e3e3a7aSWarner Losh 20548e3e3a7aSWarner Losh<p> 20558e3e3a7aSWarner LoshNumerals and literal strings are explained in <a href="#3.1">§3.1</a>; 20568e3e3a7aSWarner Loshvariables are explained in <a href="#3.2">§3.2</a>; 20578e3e3a7aSWarner Loshfunction definitions are explained in <a href="#3.4.11">§3.4.11</a>; 20588e3e3a7aSWarner Loshfunction calls are explained in <a href="#3.4.10">§3.4.10</a>; 20598e3e3a7aSWarner Loshtable constructors are explained in <a href="#3.4.9">§3.4.9</a>. 20608e3e3a7aSWarner LoshVararg expressions, 20618e3e3a7aSWarner Loshdenoted by three dots ('<code>...</code>'), can only be used when 20628e3e3a7aSWarner Loshdirectly inside a vararg function; 20638e3e3a7aSWarner Loshthey are explained in <a href="#3.4.11">§3.4.11</a>. 20648e3e3a7aSWarner Losh 20658e3e3a7aSWarner Losh 20668e3e3a7aSWarner Losh<p> 20678e3e3a7aSWarner LoshBinary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), 20688e3e3a7aSWarner Loshbitwise operators (see <a href="#3.4.2">§3.4.2</a>), 20698e3e3a7aSWarner Loshrelational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>), 20708e3e3a7aSWarner Loshand the concatenation operator (see <a href="#3.4.6">§3.4.6</a>). 20718e3e3a7aSWarner LoshUnary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), 20728e3e3a7aSWarner Loshthe unary bitwise NOT (see <a href="#3.4.2">§3.4.2</a>), 20738e3e3a7aSWarner Loshthe unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), 20748e3e3a7aSWarner Loshand the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). 20758e3e3a7aSWarner Losh 20768e3e3a7aSWarner Losh 20778e3e3a7aSWarner Losh<p> 20788e3e3a7aSWarner LoshBoth function calls and vararg expressions can result in multiple values. 20798e3e3a7aSWarner LoshIf a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>), 20808e3e3a7aSWarner Loshthen its return list is adjusted to zero elements, 20818e3e3a7aSWarner Loshthus discarding all returned values. 20828e3e3a7aSWarner LoshIf an expression is used as the last (or the only) element 20838e3e3a7aSWarner Loshof a list of expressions, 20848e3e3a7aSWarner Loshthen no adjustment is made 20858e3e3a7aSWarner Losh(unless the expression is enclosed in parentheses). 20868e3e3a7aSWarner LoshIn all other contexts, 20878e3e3a7aSWarner LoshLua adjusts the result list to one element, 20888e3e3a7aSWarner Losheither discarding all values except the first one 20898e3e3a7aSWarner Loshor adding a single <b>nil</b> if there are no values. 20908e3e3a7aSWarner Losh 20918e3e3a7aSWarner Losh 20928e3e3a7aSWarner Losh<p> 20938e3e3a7aSWarner LoshHere are some examples: 20948e3e3a7aSWarner Losh 20958e3e3a7aSWarner Losh<pre> 20968e3e3a7aSWarner Losh f() -- adjusted to 0 results 20978e3e3a7aSWarner Losh g(f(), x) -- f() is adjusted to 1 result 20988e3e3a7aSWarner Losh g(x, f()) -- g gets x plus all results from f() 20998e3e3a7aSWarner Losh a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) 2100e112e9d2SKyle Evans a,b = ... -- a gets the first vararg argument, b gets 21018e3e3a7aSWarner Losh -- the second (both a and b can get nil if there 2102e112e9d2SKyle Evans -- is no corresponding vararg argument) 21038e3e3a7aSWarner Losh 21048e3e3a7aSWarner Losh a,b,c = x, f() -- f() is adjusted to 2 results 21058e3e3a7aSWarner Losh a,b,c = f() -- f() is adjusted to 3 results 21068e3e3a7aSWarner Losh return f() -- returns all results from f() 2107e112e9d2SKyle Evans return ... -- returns all received vararg arguments 21088e3e3a7aSWarner Losh return x,y,f() -- returns x, y, and all results from f() 21098e3e3a7aSWarner Losh {f()} -- creates a list with all results from f() 2110e112e9d2SKyle Evans {...} -- creates a list with all vararg arguments 21118e3e3a7aSWarner Losh {f(), nil} -- f() is adjusted to 1 result 21128e3e3a7aSWarner Losh</pre> 21138e3e3a7aSWarner Losh 21148e3e3a7aSWarner Losh<p> 21158e3e3a7aSWarner LoshAny expression enclosed in parentheses always results in only one value. 21168e3e3a7aSWarner LoshThus, 21178e3e3a7aSWarner Losh<code>(f(x,y,z))</code> is always a single value, 21188e3e3a7aSWarner Losheven if <code>f</code> returns several values. 21198e3e3a7aSWarner Losh(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> 21208e3e3a7aSWarner Loshor <b>nil</b> if <code>f</code> does not return any values.) 21218e3e3a7aSWarner Losh 21228e3e3a7aSWarner Losh 21238e3e3a7aSWarner Losh 21240495ed39SKyle Evans 21250495ed39SKyle Evans 21268e3e3a7aSWarner Losh<h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p> 21278e3e3a7aSWarner LoshLua supports the following arithmetic operators: 21288e3e3a7aSWarner Losh 21298e3e3a7aSWarner Losh<ul> 21308e3e3a7aSWarner Losh<li><b><code>+</code>: </b>addition</li> 21318e3e3a7aSWarner Losh<li><b><code>-</code>: </b>subtraction</li> 21328e3e3a7aSWarner Losh<li><b><code>*</code>: </b>multiplication</li> 21338e3e3a7aSWarner Losh<li><b><code>/</code>: </b>float division</li> 21348e3e3a7aSWarner Losh<li><b><code>//</code>: </b>floor division</li> 21358e3e3a7aSWarner Losh<li><b><code>%</code>: </b>modulo</li> 21368e3e3a7aSWarner Losh<li><b><code>^</code>: </b>exponentiation</li> 21378e3e3a7aSWarner Losh<li><b><code>-</code>: </b>unary minus</li> 21388e3e3a7aSWarner Losh</ul> 21398e3e3a7aSWarner Losh 21408e3e3a7aSWarner Losh<p> 21418e3e3a7aSWarner LoshWith the exception of exponentiation and float division, 21428e3e3a7aSWarner Loshthe arithmetic operators work as follows: 21438e3e3a7aSWarner LoshIf both operands are integers, 21448e3e3a7aSWarner Loshthe operation is performed over integers and the result is an integer. 21450495ed39SKyle EvansOtherwise, if both operands are numbers, 21468e3e3a7aSWarner Loshthen they are converted to floats, 21470495ed39SKyle Evansthe operation is performed following the machine's rules 21488e3e3a7aSWarner Loshfor floating-point arithmetic 21498e3e3a7aSWarner Losh(usually the IEEE 754 standard), 21508e3e3a7aSWarner Loshand the result is a float. 21510495ed39SKyle Evans(The string library coerces strings to numbers in 21520495ed39SKyle Evansarithmetic operations; see <a href="#3.4.3">§3.4.3</a> for details.) 21538e3e3a7aSWarner Losh 21548e3e3a7aSWarner Losh 21558e3e3a7aSWarner Losh<p> 21568e3e3a7aSWarner LoshExponentiation and float division (<code>/</code>) 21578e3e3a7aSWarner Loshalways convert their operands to floats 21588e3e3a7aSWarner Loshand the result is always a float. 21598e3e3a7aSWarner LoshExponentiation uses the ISO C function <code>pow</code>, 21608e3e3a7aSWarner Loshso that it works for non-integer exponents too. 21618e3e3a7aSWarner Losh 21628e3e3a7aSWarner Losh 21638e3e3a7aSWarner Losh<p> 21648e3e3a7aSWarner LoshFloor division (<code>//</code>) is a division 21658e3e3a7aSWarner Loshthat rounds the quotient towards minus infinity, 21660495ed39SKyle Evansresulting in the floor of the division of its operands. 21678e3e3a7aSWarner Losh 21688e3e3a7aSWarner Losh 21698e3e3a7aSWarner Losh<p> 21708e3e3a7aSWarner LoshModulo is defined as the remainder of a division 21718e3e3a7aSWarner Loshthat rounds the quotient towards minus infinity (floor division). 21728e3e3a7aSWarner Losh 21738e3e3a7aSWarner Losh 21748e3e3a7aSWarner Losh<p> 21758e3e3a7aSWarner LoshIn case of overflows in integer arithmetic, 21760495ed39SKyle Evansall operations <em>wrap around</em>. 21778e3e3a7aSWarner Losh 21788e3e3a7aSWarner Losh 21798e3e3a7aSWarner Losh 21808e3e3a7aSWarner Losh<h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p> 21818e3e3a7aSWarner LoshLua supports the following bitwise operators: 21828e3e3a7aSWarner Losh 21838e3e3a7aSWarner Losh<ul> 21848e3e3a7aSWarner Losh<li><b><code>&</code>: </b>bitwise AND</li> 21858e3e3a7aSWarner Losh<li><b><code>|</code>: </b>bitwise OR</li> 21868e3e3a7aSWarner Losh<li><b><code>~</code>: </b>bitwise exclusive OR</li> 21878e3e3a7aSWarner Losh<li><b><code>>></code>: </b>right shift</li> 21888e3e3a7aSWarner Losh<li><b><code><<</code>: </b>left shift</li> 21898e3e3a7aSWarner Losh<li><b><code>~</code>: </b>unary bitwise NOT</li> 21908e3e3a7aSWarner Losh</ul> 21918e3e3a7aSWarner Losh 21928e3e3a7aSWarner Losh<p> 21938e3e3a7aSWarner LoshAll bitwise operations convert its operands to integers 21948e3e3a7aSWarner Losh(see <a href="#3.4.3">§3.4.3</a>), 21958e3e3a7aSWarner Loshoperate on all bits of those integers, 21968e3e3a7aSWarner Loshand result in an integer. 21978e3e3a7aSWarner Losh 21988e3e3a7aSWarner Losh 21998e3e3a7aSWarner Losh<p> 22008e3e3a7aSWarner LoshBoth right and left shifts fill the vacant bits with zeros. 22018e3e3a7aSWarner LoshNegative displacements shift to the other direction; 22028e3e3a7aSWarner Loshdisplacements with absolute values equal to or higher than 22038e3e3a7aSWarner Loshthe number of bits in an integer 22048e3e3a7aSWarner Loshresult in zero (as all bits are shifted out). 22058e3e3a7aSWarner Losh 22068e3e3a7aSWarner Losh 22078e3e3a7aSWarner Losh 22088e3e3a7aSWarner Losh 22098e3e3a7aSWarner Losh 22108e3e3a7aSWarner Losh<h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p> 22118e3e3a7aSWarner LoshLua provides some automatic conversions between some 22128e3e3a7aSWarner Loshtypes and representations at run time. 22138e3e3a7aSWarner LoshBitwise operators always convert float operands to integers. 22148e3e3a7aSWarner LoshExponentiation and float division 22158e3e3a7aSWarner Loshalways convert integer operands to floats. 22168e3e3a7aSWarner LoshAll other arithmetic operations applied to mixed numbers 22170495ed39SKyle Evans(integers and floats) convert the integer operand to a float. 22188e3e3a7aSWarner LoshThe C API also converts both integers to floats and 22198e3e3a7aSWarner Loshfloats to integers, as needed. 22208e3e3a7aSWarner LoshMoreover, string concatenation accepts numbers as arguments, 22218e3e3a7aSWarner Loshbesides strings. 22228e3e3a7aSWarner Losh 22238e3e3a7aSWarner Losh 22248e3e3a7aSWarner Losh<p> 22258e3e3a7aSWarner LoshIn a conversion from integer to float, 22268e3e3a7aSWarner Loshif the integer value has an exact representation as a float, 22278e3e3a7aSWarner Loshthat is the result. 22288e3e3a7aSWarner LoshOtherwise, 22298e3e3a7aSWarner Loshthe conversion gets the nearest higher or 22308e3e3a7aSWarner Loshthe nearest lower representable value. 22318e3e3a7aSWarner LoshThis kind of conversion never fails. 22328e3e3a7aSWarner Losh 22338e3e3a7aSWarner Losh 22348e3e3a7aSWarner Losh<p> 22358e3e3a7aSWarner LoshThe conversion from float to integer 22368e3e3a7aSWarner Loshchecks whether the float has an exact representation as an integer 22378e3e3a7aSWarner Losh(that is, the float has an integral value and 22388e3e3a7aSWarner Loshit is in the range of integer representation). 22398e3e3a7aSWarner LoshIf it does, that representation is the result. 22408e3e3a7aSWarner LoshOtherwise, the conversion fails. 22418e3e3a7aSWarner Losh 22428e3e3a7aSWarner Losh 22438e3e3a7aSWarner Losh<p> 22440495ed39SKyle EvansSeveral places in Lua coerce strings to numbers when necessary. 22450495ed39SKyle EvansIn particular, 22460495ed39SKyle Evansthe string library sets metamethods that try to coerce 22470495ed39SKyle Evansstrings to numbers in all arithmetic operations. 22480495ed39SKyle EvansIf the conversion fails, 22490495ed39SKyle Evansthe library calls the metamethod of the other operand 22500495ed39SKyle Evans(if present) or it raises an error. 22510495ed39SKyle EvansNote that bitwise operators do not do this coercion. 22528e3e3a7aSWarner Losh 22538e3e3a7aSWarner Losh 22548e3e3a7aSWarner Losh<p> 22550495ed39SKyle EvansNonetheless, it is always a good practice not to rely on these 22560495ed39SKyle Evansimplicit coercions, as they are not always applied; 22570495ed39SKyle Evansin particular, <code>"1"==1</code> is false and <code>"1"<1</code> raises an error 22580495ed39SKyle Evans(see <a href="#3.4.4">§3.4.4</a>). 22590495ed39SKyle EvansThese coercions exist mainly for compatibility and may be removed 22600495ed39SKyle Evansin future versions of the language. 22610495ed39SKyle Evans 22620495ed39SKyle Evans 22630495ed39SKyle Evans<p> 22640495ed39SKyle EvansA string is converted to an integer or a float 22650495ed39SKyle Evansfollowing its syntax and the rules of the Lua lexer. 22660495ed39SKyle EvansThe string may have also leading and trailing whitespaces and a sign. 22678e3e3a7aSWarner LoshAll conversions from strings to numbers 22688e3e3a7aSWarner Loshaccept both a dot and the current locale mark 22698e3e3a7aSWarner Loshas the radix character. 22708e3e3a7aSWarner Losh(The Lua lexer, however, accepts only a dot.) 22710495ed39SKyle EvansIf the string is not a valid numeral, 22720495ed39SKyle Evansthe conversion fails. 22730495ed39SKyle EvansIf necessary, the result of this first step is then converted 22740495ed39SKyle Evansto a specific number subtype following the previous rules 22750495ed39SKyle Evansfor conversions between floats and integers. 22768e3e3a7aSWarner Losh 22778e3e3a7aSWarner Losh 22788e3e3a7aSWarner Losh<p> 22798e3e3a7aSWarner LoshThe conversion from numbers to strings uses a 22808e3e3a7aSWarner Loshnon-specified human-readable format. 22810495ed39SKyle EvansTo convert numbers to strings in any specific way, 22820495ed39SKyle Evansuse the function <a href="#pdf-string.format"><code>string.format</code></a>. 22838e3e3a7aSWarner Losh 22848e3e3a7aSWarner Losh 22858e3e3a7aSWarner Losh 22868e3e3a7aSWarner Losh 22878e3e3a7aSWarner Losh 22888e3e3a7aSWarner Losh<h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p> 22898e3e3a7aSWarner LoshLua supports the following relational operators: 22908e3e3a7aSWarner Losh 22918e3e3a7aSWarner Losh<ul> 22928e3e3a7aSWarner Losh<li><b><code>==</code>: </b>equality</li> 22938e3e3a7aSWarner Losh<li><b><code>~=</code>: </b>inequality</li> 22948e3e3a7aSWarner Losh<li><b><code><</code>: </b>less than</li> 22958e3e3a7aSWarner Losh<li><b><code>></code>: </b>greater than</li> 22968e3e3a7aSWarner Losh<li><b><code><=</code>: </b>less or equal</li> 22978e3e3a7aSWarner Losh<li><b><code>>=</code>: </b>greater or equal</li> 22988e3e3a7aSWarner Losh</ul><p> 22998e3e3a7aSWarner LoshThese operators always result in <b>false</b> or <b>true</b>. 23008e3e3a7aSWarner Losh 23018e3e3a7aSWarner Losh 23028e3e3a7aSWarner Losh<p> 23038e3e3a7aSWarner LoshEquality (<code>==</code>) first compares the type of its operands. 23048e3e3a7aSWarner LoshIf the types are different, then the result is <b>false</b>. 23058e3e3a7aSWarner LoshOtherwise, the values of the operands are compared. 23060495ed39SKyle EvansStrings are equal if they have the same byte content. 23078e3e3a7aSWarner LoshNumbers are equal if they denote the same mathematical value. 23088e3e3a7aSWarner Losh 23098e3e3a7aSWarner Losh 23108e3e3a7aSWarner Losh<p> 23118e3e3a7aSWarner LoshTables, userdata, and threads 23128e3e3a7aSWarner Loshare compared by reference: 23138e3e3a7aSWarner Loshtwo objects are considered equal only if they are the same object. 23148e3e3a7aSWarner LoshEvery time you create a new object 23150495ed39SKyle Evans(a table, a userdata, or a thread), 23168e3e3a7aSWarner Loshthis new object is different from any previously existing object. 23170495ed39SKyle EvansA function is always equal to itself. 23180495ed39SKyle EvansFunctions with any detectable difference 23198e3e3a7aSWarner Losh(different behavior, different definition) are always different. 23200495ed39SKyle EvansFunctions created at different times but with no detectable differences 2321e112e9d2SKyle Evansmay be classified as equal or not 2322e112e9d2SKyle Evans(depending on internal caching details). 23238e3e3a7aSWarner Losh 23248e3e3a7aSWarner Losh 23258e3e3a7aSWarner Losh<p> 23268e3e3a7aSWarner LoshYou can change the way that Lua compares tables and userdata 23270495ed39SKyle Evansby using the <code>__eq</code> metamethod (see <a href="#2.4">§2.4</a>). 23288e3e3a7aSWarner Losh 23298e3e3a7aSWarner Losh 23308e3e3a7aSWarner Losh<p> 23318e3e3a7aSWarner LoshEquality comparisons do not convert strings to numbers 23328e3e3a7aSWarner Loshor vice versa. 23338e3e3a7aSWarner LoshThus, <code>"0"==0</code> evaluates to <b>false</b>, 23348e3e3a7aSWarner Loshand <code>t[0]</code> and <code>t["0"]</code> denote different 23358e3e3a7aSWarner Loshentries in a table. 23368e3e3a7aSWarner Losh 23378e3e3a7aSWarner Losh 23388e3e3a7aSWarner Losh<p> 23398e3e3a7aSWarner LoshThe operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 23408e3e3a7aSWarner Losh 23418e3e3a7aSWarner Losh 23428e3e3a7aSWarner Losh<p> 23438e3e3a7aSWarner LoshThe order operators work as follows. 23448e3e3a7aSWarner LoshIf both arguments are numbers, 23450495ed39SKyle Evansthen they are compared according to their mathematical values, 23460495ed39SKyle Evansregardless of their subtypes. 23478e3e3a7aSWarner LoshOtherwise, if both arguments are strings, 23488e3e3a7aSWarner Loshthen their values are compared according to the current locale. 23490495ed39SKyle EvansOtherwise, Lua tries to call the <code>__lt</code> or the <code>__le</code> 23508e3e3a7aSWarner Loshmetamethod (see <a href="#2.4">§2.4</a>). 23518e3e3a7aSWarner LoshA comparison <code>a > b</code> is translated to <code>b < a</code> 23528e3e3a7aSWarner Loshand <code>a >= b</code> is translated to <code>b <= a</code>. 23538e3e3a7aSWarner Losh 23548e3e3a7aSWarner Losh 23558e3e3a7aSWarner Losh<p> 23568e3e3a7aSWarner LoshFollowing the IEEE 754 standard, 23570495ed39SKyle Evansthe special value NaN is considered neither less than, 23580495ed39SKyle Evansnor equal to, nor greater than any value, including itself. 23598e3e3a7aSWarner Losh 23608e3e3a7aSWarner Losh 23618e3e3a7aSWarner Losh 23628e3e3a7aSWarner Losh 23638e3e3a7aSWarner Losh 23648e3e3a7aSWarner Losh<h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p> 23658e3e3a7aSWarner LoshThe logical operators in Lua are 23668e3e3a7aSWarner Losh<b>and</b>, <b>or</b>, and <b>not</b>. 23678e3e3a7aSWarner LoshLike the control structures (see <a href="#3.3.4">§3.3.4</a>), 23688e3e3a7aSWarner Loshall logical operators consider both <b>false</b> and <b>nil</b> as false 23698e3e3a7aSWarner Loshand anything else as true. 23708e3e3a7aSWarner Losh 23718e3e3a7aSWarner Losh 23728e3e3a7aSWarner Losh<p> 23738e3e3a7aSWarner LoshThe negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 23748e3e3a7aSWarner LoshThe conjunction operator <b>and</b> returns its first argument 23758e3e3a7aSWarner Loshif this value is <b>false</b> or <b>nil</b>; 23768e3e3a7aSWarner Loshotherwise, <b>and</b> returns its second argument. 23778e3e3a7aSWarner LoshThe disjunction operator <b>or</b> returns its first argument 23788e3e3a7aSWarner Loshif this value is different from <b>nil</b> and <b>false</b>; 23798e3e3a7aSWarner Loshotherwise, <b>or</b> returns its second argument. 23808e3e3a7aSWarner LoshBoth <b>and</b> and <b>or</b> use short-circuit evaluation; 23818e3e3a7aSWarner Loshthat is, 23828e3e3a7aSWarner Loshthe second operand is evaluated only if necessary. 23838e3e3a7aSWarner LoshHere are some examples: 23848e3e3a7aSWarner Losh 23858e3e3a7aSWarner Losh<pre> 23868e3e3a7aSWarner Losh 10 or 20 --> 10 23878e3e3a7aSWarner Losh 10 or error() --> 10 23888e3e3a7aSWarner Losh nil or "a" --> "a" 23898e3e3a7aSWarner Losh nil and 10 --> nil 23908e3e3a7aSWarner Losh false and error() --> false 23918e3e3a7aSWarner Losh false and nil --> false 23928e3e3a7aSWarner Losh false or nil --> nil 23938e3e3a7aSWarner Losh 10 and 20 --> 20 23940495ed39SKyle Evans</pre> 23958e3e3a7aSWarner Losh 23968e3e3a7aSWarner Losh 23978e3e3a7aSWarner Losh 23988e3e3a7aSWarner Losh 23998e3e3a7aSWarner Losh<h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p> 24008e3e3a7aSWarner LoshThe string concatenation operator in Lua is 24018e3e3a7aSWarner Loshdenoted by two dots ('<code>..</code>'). 24020495ed39SKyle EvansIf both operands are strings or numbers, 24030495ed39SKyle Evansthen the numbers are converted to strings 24040495ed39SKyle Evansin a non-specified format (see <a href="#3.4.3">§3.4.3</a>). 24058e3e3a7aSWarner LoshOtherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). 24068e3e3a7aSWarner Losh 24078e3e3a7aSWarner Losh 24088e3e3a7aSWarner Losh 24098e3e3a7aSWarner Losh 24108e3e3a7aSWarner Losh 24118e3e3a7aSWarner Losh<h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3> 24128e3e3a7aSWarner Losh 24138e3e3a7aSWarner Losh<p> 24148e3e3a7aSWarner LoshThe length operator is denoted by the unary prefix operator <code>#</code>. 24158e3e3a7aSWarner Losh 24168e3e3a7aSWarner Losh 24178e3e3a7aSWarner Losh<p> 24180495ed39SKyle EvansThe length of a string is its number of bytes. 24190495ed39SKyle Evans(That is the usual meaning of string length when each 24200495ed39SKyle Evanscharacter is one byte.) 24218e3e3a7aSWarner Losh 24228e3e3a7aSWarner Losh 24238e3e3a7aSWarner Losh<p> 24248e3e3a7aSWarner LoshThe length operator applied on a table 24258e3e3a7aSWarner Loshreturns a border in that table. 2426*8c784bb8SWarner LoshA <em>border</em> in a table <code>t</code> is any non-negative integer 24278e3e3a7aSWarner Loshthat satisfies the following condition: 24288e3e3a7aSWarner Losh 24298e3e3a7aSWarner Losh<pre> 2430*8c784bb8SWarner Losh (border == 0 or t[border] ~= nil) and 2431*8c784bb8SWarner Losh (t[border + 1] == nil or border == math.maxinteger) 24328e3e3a7aSWarner Losh</pre><p> 24338e3e3a7aSWarner LoshIn words, 2434*8c784bb8SWarner Losha border is any positive integer index present in the table 2435*8c784bb8SWarner Loshthat is followed by an absent index, 2436*8c784bb8SWarner Loshplus two limit cases: 2437*8c784bb8SWarner Loshzero, when index 1 is absent; 2438*8c784bb8SWarner Loshand the maximum value for an integer, when that index is present. 2439*8c784bb8SWarner LoshNote that keys that are not positive integers 2440*8c784bb8SWarner Loshdo not interfere with borders. 24418e3e3a7aSWarner Losh 24428e3e3a7aSWarner Losh 24438e3e3a7aSWarner Losh<p> 24448e3e3a7aSWarner LoshA table with exactly one border is called a <em>sequence</em>. 24458e3e3a7aSWarner LoshFor instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence, 24468e3e3a7aSWarner Loshas it has only one border (5). 24478e3e3a7aSWarner LoshThe table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5), 24488e3e3a7aSWarner Loshand therefore it is not a sequence. 24490495ed39SKyle Evans(The <b>nil</b> at index 4 is called a <em>hole</em>.) 24508e3e3a7aSWarner LoshThe table <code>{nil, 20, 30, nil, nil, 60, nil}</code> 2451*8c784bb8SWarner Loshhas three borders (0, 3, and 6), 24528e3e3a7aSWarner Loshso it is not a sequence, too. 24538e3e3a7aSWarner LoshThe table <code>{}</code> is a sequence with border 0. 24548e3e3a7aSWarner Losh 24558e3e3a7aSWarner Losh 24568e3e3a7aSWarner Losh<p> 24578e3e3a7aSWarner LoshWhen <code>t</code> is a sequence, 24588e3e3a7aSWarner Losh<code>#t</code> returns its only border, 24598e3e3a7aSWarner Loshwhich corresponds to the intuitive notion of the length of the sequence. 24608e3e3a7aSWarner LoshWhen <code>t</code> is not a sequence, 24618e3e3a7aSWarner Losh<code>#t</code> can return any of its borders. 24628e3e3a7aSWarner Losh(The exact one depends on details of 24638e3e3a7aSWarner Loshthe internal representation of the table, 24648e3e3a7aSWarner Loshwhich in turn can depend on how the table was populated and 24658e3e3a7aSWarner Loshthe memory addresses of its non-numeric keys.) 24668e3e3a7aSWarner Losh 24678e3e3a7aSWarner Losh 24688e3e3a7aSWarner Losh<p> 24698e3e3a7aSWarner LoshThe computation of the length of a table 24708e3e3a7aSWarner Loshhas a guaranteed worst time of <em>O(log n)</em>, 2471*8c784bb8SWarner Loshwhere <em>n</em> is the largest integer key in the table. 24728e3e3a7aSWarner Losh 24738e3e3a7aSWarner Losh 24748e3e3a7aSWarner Losh<p> 24758e3e3a7aSWarner LoshA program can modify the behavior of the length operator for 24768e3e3a7aSWarner Loshany value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>). 24778e3e3a7aSWarner Losh 24788e3e3a7aSWarner Losh 24798e3e3a7aSWarner Losh 24808e3e3a7aSWarner Losh 24818e3e3a7aSWarner Losh 24828e3e3a7aSWarner Losh<h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p> 24838e3e3a7aSWarner LoshOperator precedence in Lua follows the table below, 24848e3e3a7aSWarner Loshfrom lower to higher priority: 24858e3e3a7aSWarner Losh 24868e3e3a7aSWarner Losh<pre> 24878e3e3a7aSWarner Losh or 24888e3e3a7aSWarner Losh and 24898e3e3a7aSWarner Losh < > <= >= ~= == 24908e3e3a7aSWarner Losh | 24918e3e3a7aSWarner Losh ~ 24928e3e3a7aSWarner Losh & 24938e3e3a7aSWarner Losh << >> 24948e3e3a7aSWarner Losh .. 24958e3e3a7aSWarner Losh + - 24968e3e3a7aSWarner Losh * / // % 24978e3e3a7aSWarner Losh unary operators (not # - ~) 24988e3e3a7aSWarner Losh ^ 24998e3e3a7aSWarner Losh</pre><p> 25008e3e3a7aSWarner LoshAs usual, 25018e3e3a7aSWarner Loshyou can use parentheses to change the precedences of an expression. 25028e3e3a7aSWarner LoshThe concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 25038e3e3a7aSWarner Loshoperators are right associative. 25048e3e3a7aSWarner LoshAll other binary operators are left associative. 25058e3e3a7aSWarner Losh 25068e3e3a7aSWarner Losh 25078e3e3a7aSWarner Losh 25088e3e3a7aSWarner Losh 25098e3e3a7aSWarner Losh 25108e3e3a7aSWarner Losh<h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p> 25118e3e3a7aSWarner LoshTable constructors are expressions that create tables. 25128e3e3a7aSWarner LoshEvery time a constructor is evaluated, a new table is created. 25138e3e3a7aSWarner LoshA constructor can be used to create an empty table 25148e3e3a7aSWarner Loshor to create a table and initialize some of its fields. 25158e3e3a7aSWarner LoshThe general syntax for constructors is 25168e3e3a7aSWarner Losh 25178e3e3a7aSWarner Losh<pre> 25188e3e3a7aSWarner Losh tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 25198e3e3a7aSWarner Losh fieldlist ::= field {fieldsep field} [fieldsep] 25208e3e3a7aSWarner Losh field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 25218e3e3a7aSWarner Losh fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 25228e3e3a7aSWarner Losh</pre> 25238e3e3a7aSWarner Losh 25248e3e3a7aSWarner Losh<p> 25258e3e3a7aSWarner LoshEach field of the form <code>[exp1] = exp2</code> adds to the new table an entry 25268e3e3a7aSWarner Loshwith key <code>exp1</code> and value <code>exp2</code>. 25278e3e3a7aSWarner LoshA field of the form <code>name = exp</code> is equivalent to 25288e3e3a7aSWarner Losh<code>["name"] = exp</code>. 25290495ed39SKyle EvansFields of the form <code>exp</code> are equivalent to 25308e3e3a7aSWarner Losh<code>[i] = exp</code>, where <code>i</code> are consecutive integers 25310495ed39SKyle Evansstarting with 1; 25320495ed39SKyle Evansfields in the other formats do not affect this counting. 25338e3e3a7aSWarner LoshFor example, 25348e3e3a7aSWarner Losh 25358e3e3a7aSWarner Losh<pre> 25368e3e3a7aSWarner Losh a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 25378e3e3a7aSWarner Losh</pre><p> 25388e3e3a7aSWarner Loshis equivalent to 25398e3e3a7aSWarner Losh 25408e3e3a7aSWarner Losh<pre> 25418e3e3a7aSWarner Losh do 25428e3e3a7aSWarner Losh local t = {} 25438e3e3a7aSWarner Losh t[f(1)] = g 25448e3e3a7aSWarner Losh t[1] = "x" -- 1st exp 25458e3e3a7aSWarner Losh t[2] = "y" -- 2nd exp 25468e3e3a7aSWarner Losh t.x = 1 -- t["x"] = 1 25478e3e3a7aSWarner Losh t[3] = f(x) -- 3rd exp 25488e3e3a7aSWarner Losh t[30] = 23 25498e3e3a7aSWarner Losh t[4] = 45 -- 4th exp 25508e3e3a7aSWarner Losh a = t 25518e3e3a7aSWarner Losh end 25528e3e3a7aSWarner Losh</pre> 25538e3e3a7aSWarner Losh 25548e3e3a7aSWarner Losh<p> 25558e3e3a7aSWarner LoshThe order of the assignments in a constructor is undefined. 25568e3e3a7aSWarner Losh(This order would be relevant only when there are repeated keys.) 25578e3e3a7aSWarner Losh 25588e3e3a7aSWarner Losh 25598e3e3a7aSWarner Losh<p> 25608e3e3a7aSWarner LoshIf the last field in the list has the form <code>exp</code> 25618e3e3a7aSWarner Loshand the expression is a function call or a vararg expression, 25628e3e3a7aSWarner Loshthen all values returned by this expression enter the list consecutively 25638e3e3a7aSWarner Losh(see <a href="#3.4.10">§3.4.10</a>). 25648e3e3a7aSWarner Losh 25658e3e3a7aSWarner Losh 25668e3e3a7aSWarner Losh<p> 25678e3e3a7aSWarner LoshThe field list can have an optional trailing separator, 25688e3e3a7aSWarner Loshas a convenience for machine-generated code. 25698e3e3a7aSWarner Losh 25708e3e3a7aSWarner Losh 25718e3e3a7aSWarner Losh 25728e3e3a7aSWarner Losh 25738e3e3a7aSWarner Losh 25748e3e3a7aSWarner Losh<h3>3.4.10 – <a name="3.4.10">Function Calls</a></h3><p> 25758e3e3a7aSWarner LoshA function call in Lua has the following syntax: 25768e3e3a7aSWarner Losh 25778e3e3a7aSWarner Losh<pre> 25788e3e3a7aSWarner Losh functioncall ::= prefixexp args 25798e3e3a7aSWarner Losh</pre><p> 25808e3e3a7aSWarner LoshIn a function call, 25818e3e3a7aSWarner Loshfirst prefixexp and args are evaluated. 25828e3e3a7aSWarner LoshIf the value of prefixexp has type <em>function</em>, 25838e3e3a7aSWarner Loshthen this function is called 25848e3e3a7aSWarner Loshwith the given arguments. 25850495ed39SKyle EvansOtherwise, if present, 25860495ed39SKyle Evansthe prefixexp <code>__call</code> metamethod is called: 25870495ed39SKyle Evansits first argument is the value of prefixexp, 25888e3e3a7aSWarner Loshfollowed by the original call arguments 25898e3e3a7aSWarner Losh(see <a href="#2.4">§2.4</a>). 25908e3e3a7aSWarner Losh 25918e3e3a7aSWarner Losh 25928e3e3a7aSWarner Losh<p> 25938e3e3a7aSWarner LoshThe form 25948e3e3a7aSWarner Losh 25958e3e3a7aSWarner Losh<pre> 25968e3e3a7aSWarner Losh functioncall ::= prefixexp ‘<b>:</b>’ Name args 25978e3e3a7aSWarner Losh</pre><p> 25980495ed39SKyle Evanscan be used to emulate methods. 25998e3e3a7aSWarner LoshA call <code>v:name(<em>args</em>)</code> 26008e3e3a7aSWarner Loshis syntactic sugar for <code>v.name(v,<em>args</em>)</code>, 26018e3e3a7aSWarner Loshexcept that <code>v</code> is evaluated only once. 26028e3e3a7aSWarner Losh 26038e3e3a7aSWarner Losh 26048e3e3a7aSWarner Losh<p> 26058e3e3a7aSWarner LoshArguments have the following syntax: 26068e3e3a7aSWarner Losh 26078e3e3a7aSWarner Losh<pre> 26088e3e3a7aSWarner Losh args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ 26098e3e3a7aSWarner Losh args ::= tableconstructor 26108e3e3a7aSWarner Losh args ::= LiteralString 26118e3e3a7aSWarner Losh</pre><p> 26128e3e3a7aSWarner LoshAll argument expressions are evaluated before the call. 26138e3e3a7aSWarner LoshA call of the form <code>f{<em>fields</em>}</code> is 26148e3e3a7aSWarner Loshsyntactic sugar for <code>f({<em>fields</em>})</code>; 26158e3e3a7aSWarner Loshthat is, the argument list is a single new table. 26168e3e3a7aSWarner LoshA call of the form <code>f'<em>string</em>'</code> 26178e3e3a7aSWarner Losh(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 26188e3e3a7aSWarner Loshis syntactic sugar for <code>f('<em>string</em>')</code>; 26198e3e3a7aSWarner Loshthat is, the argument list is a single literal string. 26208e3e3a7aSWarner Losh 26218e3e3a7aSWarner Losh 26228e3e3a7aSWarner Losh<p> 26230495ed39SKyle EvansA call of the form <code>return <em>functioncall</em></code> not in the 26240495ed39SKyle Evansscope of a to-be-closed variable is called a <em>tail call</em>. 26258e3e3a7aSWarner LoshLua implements <em>proper tail calls</em> 26268e3e3a7aSWarner Losh(or <em>proper tail recursion</em>): 26278e3e3a7aSWarner Loshin a tail call, 26288e3e3a7aSWarner Loshthe called function reuses the stack entry of the calling function. 26298e3e3a7aSWarner LoshTherefore, there is no limit on the number of nested tail calls that 26308e3e3a7aSWarner Losha program can execute. 26318e3e3a7aSWarner LoshHowever, a tail call erases any debug information about the 26328e3e3a7aSWarner Loshcalling function. 26338e3e3a7aSWarner LoshNote that a tail call only happens with a particular syntax, 26340495ed39SKyle Evanswhere the <b>return</b> has one single function call as argument, 26350495ed39SKyle Evansand it is outside the scope of any to-be-closed variable. 26360495ed39SKyle EvansThis syntax makes the calling function return exactly 26370495ed39SKyle Evansthe returns of the called function, 26380495ed39SKyle Evanswithout any intervening action. 26398e3e3a7aSWarner LoshSo, none of the following examples are tail calls: 26408e3e3a7aSWarner Losh 26418e3e3a7aSWarner Losh<pre> 26428e3e3a7aSWarner Losh return (f(x)) -- results adjusted to 1 26430495ed39SKyle Evans return 2 * f(x) -- result multiplied by 2 26448e3e3a7aSWarner Losh return x, f(x) -- additional results 26458e3e3a7aSWarner Losh f(x); return -- results discarded 26468e3e3a7aSWarner Losh return x or f(x) -- results adjusted to 1 26478e3e3a7aSWarner Losh</pre> 26488e3e3a7aSWarner Losh 26498e3e3a7aSWarner Losh 26508e3e3a7aSWarner Losh 26518e3e3a7aSWarner Losh 26528e3e3a7aSWarner Losh<h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3> 26538e3e3a7aSWarner Losh 26548e3e3a7aSWarner Losh<p> 26558e3e3a7aSWarner LoshThe syntax for function definition is 26568e3e3a7aSWarner Losh 26578e3e3a7aSWarner Losh<pre> 26588e3e3a7aSWarner Losh functiondef ::= <b>function</b> funcbody 26598e3e3a7aSWarner Losh funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 26608e3e3a7aSWarner Losh</pre> 26618e3e3a7aSWarner Losh 26628e3e3a7aSWarner Losh<p> 26638e3e3a7aSWarner LoshThe following syntactic sugar simplifies function definitions: 26648e3e3a7aSWarner Losh 26658e3e3a7aSWarner Losh<pre> 26668e3e3a7aSWarner Losh stat ::= <b>function</b> funcname funcbody 26678e3e3a7aSWarner Losh stat ::= <b>local</b> <b>function</b> Name funcbody 26688e3e3a7aSWarner Losh funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 26698e3e3a7aSWarner Losh</pre><p> 26708e3e3a7aSWarner LoshThe statement 26718e3e3a7aSWarner Losh 26728e3e3a7aSWarner Losh<pre> 26738e3e3a7aSWarner Losh function f () <em>body</em> end 26748e3e3a7aSWarner Losh</pre><p> 26758e3e3a7aSWarner Loshtranslates to 26768e3e3a7aSWarner Losh 26778e3e3a7aSWarner Losh<pre> 26788e3e3a7aSWarner Losh f = function () <em>body</em> end 26798e3e3a7aSWarner Losh</pre><p> 26808e3e3a7aSWarner LoshThe statement 26818e3e3a7aSWarner Losh 26828e3e3a7aSWarner Losh<pre> 26838e3e3a7aSWarner Losh function t.a.b.c.f () <em>body</em> end 26848e3e3a7aSWarner Losh</pre><p> 26858e3e3a7aSWarner Loshtranslates to 26868e3e3a7aSWarner Losh 26878e3e3a7aSWarner Losh<pre> 26888e3e3a7aSWarner Losh t.a.b.c.f = function () <em>body</em> end 26898e3e3a7aSWarner Losh</pre><p> 26908e3e3a7aSWarner LoshThe statement 26918e3e3a7aSWarner Losh 26928e3e3a7aSWarner Losh<pre> 26938e3e3a7aSWarner Losh local function f () <em>body</em> end 26948e3e3a7aSWarner Losh</pre><p> 26958e3e3a7aSWarner Loshtranslates to 26968e3e3a7aSWarner Losh 26978e3e3a7aSWarner Losh<pre> 26988e3e3a7aSWarner Losh local f; f = function () <em>body</em> end 26998e3e3a7aSWarner Losh</pre><p> 27008e3e3a7aSWarner Loshnot to 27018e3e3a7aSWarner Losh 27028e3e3a7aSWarner Losh<pre> 27038e3e3a7aSWarner Losh local f = function () <em>body</em> end 27048e3e3a7aSWarner Losh</pre><p> 27058e3e3a7aSWarner Losh(This only makes a difference when the body of the function 27068e3e3a7aSWarner Loshcontains references to <code>f</code>.) 27078e3e3a7aSWarner Losh 27088e3e3a7aSWarner Losh 27098e3e3a7aSWarner Losh<p> 27108e3e3a7aSWarner LoshA function definition is an executable expression, 27118e3e3a7aSWarner Loshwhose value has type <em>function</em>. 27128e3e3a7aSWarner LoshWhen Lua precompiles a chunk, 27130495ed39SKyle Evansall its function bodies are precompiled too, 27140495ed39SKyle Evansbut they are not created yet. 27158e3e3a7aSWarner LoshThen, whenever Lua executes the function definition, 27168e3e3a7aSWarner Loshthe function is <em>instantiated</em> (or <em>closed</em>). 27170495ed39SKyle EvansThis function instance, or <em>closure</em>, 27188e3e3a7aSWarner Loshis the final value of the expression. 27198e3e3a7aSWarner Losh 27208e3e3a7aSWarner Losh 27218e3e3a7aSWarner Losh<p> 27228e3e3a7aSWarner LoshParameters act as local variables that are 27238e3e3a7aSWarner Loshinitialized with the argument values: 27248e3e3a7aSWarner Losh 27258e3e3a7aSWarner Losh<pre> 27268e3e3a7aSWarner Losh parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 27278e3e3a7aSWarner Losh</pre><p> 27280495ed39SKyle EvansWhen a Lua function is called, 27290495ed39SKyle Evansit adjusts its list of arguments to 27300495ed39SKyle Evansthe length of its list of parameters, 27318e3e3a7aSWarner Loshunless the function is a <em>vararg function</em>, 27328e3e3a7aSWarner Loshwhich is indicated by three dots ('<code>...</code>') 27338e3e3a7aSWarner Loshat the end of its parameter list. 27348e3e3a7aSWarner LoshA vararg function does not adjust its argument list; 27358e3e3a7aSWarner Loshinstead, it collects all extra arguments and supplies them 27368e3e3a7aSWarner Loshto the function through a <em>vararg expression</em>, 27378e3e3a7aSWarner Loshwhich is also written as three dots. 27388e3e3a7aSWarner LoshThe value of this expression is a list of all actual extra arguments, 27398e3e3a7aSWarner Loshsimilar to a function with multiple results. 27408e3e3a7aSWarner LoshIf a vararg expression is used inside another expression 27418e3e3a7aSWarner Loshor in the middle of a list of expressions, 27428e3e3a7aSWarner Loshthen its return list is adjusted to one element. 27438e3e3a7aSWarner LoshIf the expression is used as the last element of a list of expressions, 27448e3e3a7aSWarner Loshthen no adjustment is made 27458e3e3a7aSWarner Losh(unless that last expression is enclosed in parentheses). 27468e3e3a7aSWarner Losh 27478e3e3a7aSWarner Losh 27488e3e3a7aSWarner Losh<p> 27498e3e3a7aSWarner LoshAs an example, consider the following definitions: 27508e3e3a7aSWarner Losh 27518e3e3a7aSWarner Losh<pre> 27528e3e3a7aSWarner Losh function f(a, b) end 27538e3e3a7aSWarner Losh function g(a, b, ...) end 27548e3e3a7aSWarner Losh function r() return 1,2,3 end 27558e3e3a7aSWarner Losh</pre><p> 27568e3e3a7aSWarner LoshThen, we have the following mapping from arguments to parameters and 27578e3e3a7aSWarner Loshto the vararg expression: 27588e3e3a7aSWarner Losh 27598e3e3a7aSWarner Losh<pre> 27608e3e3a7aSWarner Losh CALL PARAMETERS 27618e3e3a7aSWarner Losh 27628e3e3a7aSWarner Losh f(3) a=3, b=nil 27638e3e3a7aSWarner Losh f(3, 4) a=3, b=4 27648e3e3a7aSWarner Losh f(3, 4, 5) a=3, b=4 27658e3e3a7aSWarner Losh f(r(), 10) a=1, b=10 27668e3e3a7aSWarner Losh f(r()) a=1, b=2 27678e3e3a7aSWarner Losh 27688e3e3a7aSWarner Losh g(3) a=3, b=nil, ... --> (nothing) 27698e3e3a7aSWarner Losh g(3, 4) a=3, b=4, ... --> (nothing) 27708e3e3a7aSWarner Losh g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 27718e3e3a7aSWarner Losh g(5, r()) a=5, b=1, ... --> 2 3 27728e3e3a7aSWarner Losh</pre> 27738e3e3a7aSWarner Losh 27748e3e3a7aSWarner Losh<p> 27758e3e3a7aSWarner LoshResults are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>). 27768e3e3a7aSWarner LoshIf control reaches the end of a function 27778e3e3a7aSWarner Loshwithout encountering a <b>return</b> statement, 27788e3e3a7aSWarner Loshthen the function returns with no results. 27798e3e3a7aSWarner Losh 27808e3e3a7aSWarner Losh 27818e3e3a7aSWarner Losh<p> 27828e3e3a7aSWarner Losh 27838e3e3a7aSWarner LoshThere is a system-dependent limit on the number of values 27848e3e3a7aSWarner Loshthat a function may return. 27850495ed39SKyle EvansThis limit is guaranteed to be greater than 1000. 27868e3e3a7aSWarner Losh 27878e3e3a7aSWarner Losh 27888e3e3a7aSWarner Losh<p> 27898e3e3a7aSWarner LoshThe <em>colon</em> syntax 27900495ed39SKyle Evansis used to emulate <em>methods</em>, 27910495ed39SKyle Evansadding an implicit extra parameter <code>self</code> to the function. 27928e3e3a7aSWarner LoshThus, the statement 27938e3e3a7aSWarner Losh 27948e3e3a7aSWarner Losh<pre> 27958e3e3a7aSWarner Losh function t.a.b.c:f (<em>params</em>) <em>body</em> end 27968e3e3a7aSWarner Losh</pre><p> 27978e3e3a7aSWarner Loshis syntactic sugar for 27988e3e3a7aSWarner Losh 27998e3e3a7aSWarner Losh<pre> 28008e3e3a7aSWarner Losh t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end 28018e3e3a7aSWarner Losh</pre> 28028e3e3a7aSWarner Losh 28038e3e3a7aSWarner Losh 28048e3e3a7aSWarner Losh 28058e3e3a7aSWarner Losh 28068e3e3a7aSWarner Losh 28078e3e3a7aSWarner Losh 28088e3e3a7aSWarner Losh<h2>3.5 – <a name="3.5">Visibility Rules</a></h2> 28098e3e3a7aSWarner Losh 28108e3e3a7aSWarner Losh<p> 28118e3e3a7aSWarner Losh 28128e3e3a7aSWarner LoshLua is a lexically scoped language. 28138e3e3a7aSWarner LoshThe scope of a local variable begins at the first statement after 28148e3e3a7aSWarner Loshits declaration and lasts until the last non-void statement 28158e3e3a7aSWarner Loshof the innermost block that includes the declaration. 28168e3e3a7aSWarner LoshConsider the following example: 28178e3e3a7aSWarner Losh 28188e3e3a7aSWarner Losh<pre> 28198e3e3a7aSWarner Losh x = 10 -- global variable 28208e3e3a7aSWarner Losh do -- new block 28218e3e3a7aSWarner Losh local x = x -- new 'x', with value 10 28228e3e3a7aSWarner Losh print(x) --> 10 28238e3e3a7aSWarner Losh x = x+1 28248e3e3a7aSWarner Losh do -- another block 28258e3e3a7aSWarner Losh local x = x+1 -- another 'x' 28268e3e3a7aSWarner Losh print(x) --> 12 28278e3e3a7aSWarner Losh end 28288e3e3a7aSWarner Losh print(x) --> 11 28298e3e3a7aSWarner Losh end 28308e3e3a7aSWarner Losh print(x) --> 10 (the global one) 28318e3e3a7aSWarner Losh</pre> 28328e3e3a7aSWarner Losh 28338e3e3a7aSWarner Losh<p> 28348e3e3a7aSWarner LoshNotice that, in a declaration like <code>local x = x</code>, 28358e3e3a7aSWarner Loshthe new <code>x</code> being declared is not in scope yet, 28368e3e3a7aSWarner Loshand so the second <code>x</code> refers to the outside variable. 28378e3e3a7aSWarner Losh 28388e3e3a7aSWarner Losh 28398e3e3a7aSWarner Losh<p> 28408e3e3a7aSWarner LoshBecause of the lexical scoping rules, 28418e3e3a7aSWarner Loshlocal variables can be freely accessed by functions 28428e3e3a7aSWarner Loshdefined inside their scope. 28430495ed39SKyle EvansA local variable used by an inner function is called an <em>upvalue</em> 28440495ed39SKyle Evans(or <em>external local variable</em>, or simply <em>external variable</em>) 28458e3e3a7aSWarner Loshinside the inner function. 28468e3e3a7aSWarner Losh 28478e3e3a7aSWarner Losh 28488e3e3a7aSWarner Losh<p> 28498e3e3a7aSWarner LoshNotice that each execution of a <b>local</b> statement 28508e3e3a7aSWarner Loshdefines new local variables. 28518e3e3a7aSWarner LoshConsider the following example: 28528e3e3a7aSWarner Losh 28538e3e3a7aSWarner Losh<pre> 28548e3e3a7aSWarner Losh a = {} 28558e3e3a7aSWarner Losh local x = 20 28568e3e3a7aSWarner Losh for i = 1, 10 do 28578e3e3a7aSWarner Losh local y = 0 28588e3e3a7aSWarner Losh a[i] = function () y = y + 1; return x + y end 28598e3e3a7aSWarner Losh end 28608e3e3a7aSWarner Losh</pre><p> 28618e3e3a7aSWarner LoshThe loop creates ten closures 28628e3e3a7aSWarner Losh(that is, ten instances of the anonymous function). 28638e3e3a7aSWarner LoshEach of these closures uses a different <code>y</code> variable, 28648e3e3a7aSWarner Loshwhile all of them share the same <code>x</code>. 28658e3e3a7aSWarner Losh 28668e3e3a7aSWarner Losh 28678e3e3a7aSWarner Losh 28688e3e3a7aSWarner Losh 28698e3e3a7aSWarner Losh 28708e3e3a7aSWarner Losh<h1>4 – <a name="4">The Application Program Interface</a></h1> 28718e3e3a7aSWarner Losh 28720495ed39SKyle Evans 28730495ed39SKyle Evans 28748e3e3a7aSWarner Losh<p> 28758e3e3a7aSWarner Losh 28768e3e3a7aSWarner LoshThis section describes the C API for Lua, that is, 28778e3e3a7aSWarner Loshthe set of C functions available to the host program to communicate 28788e3e3a7aSWarner Loshwith Lua. 28798e3e3a7aSWarner LoshAll API functions and related types and constants 28808e3e3a7aSWarner Loshare declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. 28818e3e3a7aSWarner Losh 28828e3e3a7aSWarner Losh 28838e3e3a7aSWarner Losh<p> 28848e3e3a7aSWarner LoshEven when we use the term "function", 28858e3e3a7aSWarner Loshany facility in the API may be provided as a macro instead. 28868e3e3a7aSWarner LoshExcept where stated otherwise, 28878e3e3a7aSWarner Loshall such macros use each of their arguments exactly once 28888e3e3a7aSWarner Losh(except for the first argument, which is always a Lua state), 28898e3e3a7aSWarner Loshand so do not generate any hidden side-effects. 28908e3e3a7aSWarner Losh 28918e3e3a7aSWarner Losh 28928e3e3a7aSWarner Losh<p> 28938e3e3a7aSWarner LoshAs in most C libraries, 28940495ed39SKyle Evansthe Lua API functions do not check their arguments 28950495ed39SKyle Evansfor validity or consistency. 28968e3e3a7aSWarner LoshHowever, you can change this behavior by compiling Lua 28978e3e3a7aSWarner Loshwith the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined. 28988e3e3a7aSWarner Losh 28998e3e3a7aSWarner Losh 29008e3e3a7aSWarner Losh<p> 29018e3e3a7aSWarner LoshThe Lua library is fully reentrant: 29028e3e3a7aSWarner Loshit has no global variables. 29038e3e3a7aSWarner LoshIt keeps all information it needs in a dynamic structure, 29048e3e3a7aSWarner Loshcalled the <em>Lua state</em>. 29058e3e3a7aSWarner Losh 29068e3e3a7aSWarner Losh 29078e3e3a7aSWarner Losh<p> 29088e3e3a7aSWarner LoshEach Lua state has one or more threads, 29098e3e3a7aSWarner Loshwhich correspond to independent, cooperative lines of execution. 29108e3e3a7aSWarner LoshThe type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread. 29118e3e3a7aSWarner Losh(Indirectly, through the thread, it also refers to the 29128e3e3a7aSWarner LoshLua state associated to the thread.) 29138e3e3a7aSWarner Losh 29148e3e3a7aSWarner Losh 29158e3e3a7aSWarner Losh<p> 29168e3e3a7aSWarner LoshA pointer to a thread must be passed as the first argument to 29178e3e3a7aSWarner Loshevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 29188e3e3a7aSWarner Loshwhich creates a Lua state from scratch and returns a pointer 29198e3e3a7aSWarner Loshto the <em>main thread</em> in the new state. 29208e3e3a7aSWarner Losh 29218e3e3a7aSWarner Losh 29228e3e3a7aSWarner Losh 29230495ed39SKyle Evans 29240495ed39SKyle Evans 29258e3e3a7aSWarner Losh<h2>4.1 – <a name="4.1">The Stack</a></h2> 29268e3e3a7aSWarner Losh 29270495ed39SKyle Evans 29280495ed39SKyle Evans 29298e3e3a7aSWarner Losh<p> 29308e3e3a7aSWarner LoshLua uses a <em>virtual stack</em> to pass values to and from C. 29318e3e3a7aSWarner LoshEach element in this stack represents a Lua value 29328e3e3a7aSWarner Losh(<b>nil</b>, number, string, etc.). 29338e3e3a7aSWarner LoshFunctions in the API can access this stack through the 29348e3e3a7aSWarner LoshLua state parameter that they receive. 29358e3e3a7aSWarner Losh 29368e3e3a7aSWarner Losh 29378e3e3a7aSWarner Losh<p> 29388e3e3a7aSWarner LoshWhenever Lua calls C, the called function gets a new stack, 29398e3e3a7aSWarner Loshwhich is independent of previous stacks and of stacks of 29408e3e3a7aSWarner LoshC functions that are still active. 29418e3e3a7aSWarner LoshThis stack initially contains any arguments to the C function 29428e3e3a7aSWarner Loshand it is where the C function can store temporary 29438e3e3a7aSWarner LoshLua values and must push its results 29448e3e3a7aSWarner Loshto be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 29458e3e3a7aSWarner Losh 29468e3e3a7aSWarner Losh 29478e3e3a7aSWarner Losh<p> 29488e3e3a7aSWarner LoshFor convenience, 29498e3e3a7aSWarner Loshmost query operations in the API do not follow a strict stack discipline. 29508e3e3a7aSWarner LoshInstead, they can refer to any element in the stack 29518e3e3a7aSWarner Loshby using an <em>index</em>: 29520495ed39SKyle EvansA positive index represents an absolute stack position, 29530495ed39SKyle Evansstarting at 1 as the bottom of the stack; 29548e3e3a7aSWarner Losha negative index represents an offset relative to the top of the stack. 29558e3e3a7aSWarner LoshMore specifically, if the stack has <em>n</em> elements, 29568e3e3a7aSWarner Loshthen index 1 represents the first element 29578e3e3a7aSWarner Losh(that is, the element that was pushed onto the stack first) 29588e3e3a7aSWarner Loshand 29598e3e3a7aSWarner Loshindex <em>n</em> represents the last element; 29608e3e3a7aSWarner Loshindex -1 also represents the last element 29618e3e3a7aSWarner Losh(that is, the element at the top) 29628e3e3a7aSWarner Loshand index <em>-n</em> represents the first element. 29638e3e3a7aSWarner Losh 29648e3e3a7aSWarner Losh 29658e3e3a7aSWarner Losh 29668e3e3a7aSWarner Losh 29678e3e3a7aSWarner Losh 29680495ed39SKyle Evans<h3>4.1.1 – <a name="4.1.1">Stack Size</a></h3> 29698e3e3a7aSWarner Losh 29708e3e3a7aSWarner Losh<p> 29718e3e3a7aSWarner LoshWhen you interact with the Lua API, 29728e3e3a7aSWarner Loshyou are responsible for ensuring consistency. 29738e3e3a7aSWarner LoshIn particular, 29748e3e3a7aSWarner Losh<em>you are responsible for controlling stack overflow</em>. 29750495ed39SKyle EvansWhen you call any API function, 29760495ed39SKyle Evansyou must ensure the stack has enough room to accommodate the results. 29770495ed39SKyle Evans 29780495ed39SKyle Evans 29790495ed39SKyle Evans<p> 29800495ed39SKyle EvansThere is one exception to the above rule: 29810495ed39SKyle EvansWhen you call a Lua function 29820495ed39SKyle Evanswithout a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>), 29830495ed39SKyle EvansLua ensures that the stack has enough space for all results. 29840495ed39SKyle EvansHowever, it does not ensure any extra space. 29850495ed39SKyle EvansSo, before pushing anything on the stack after such a call 29860495ed39SKyle Evansyou should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>. 29878e3e3a7aSWarner Losh 29888e3e3a7aSWarner Losh 29898e3e3a7aSWarner Losh<p> 29908e3e3a7aSWarner LoshWhenever Lua calls C, 29918e3e3a7aSWarner Loshit ensures that the stack has space for 29920495ed39SKyle Evansat least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra elements; 29930495ed39SKyle Evansthat is, you can safely push up to <code>LUA_MINSTACK</code> values into it. 29948e3e3a7aSWarner Losh<code>LUA_MINSTACK</code> is defined as 20, 29958e3e3a7aSWarner Loshso that usually you do not have to worry about stack space 29968e3e3a7aSWarner Loshunless your code has loops pushing elements onto the stack. 29970495ed39SKyle EvansWhenever necessary, 29980495ed39SKyle Evansyou can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> 29990495ed39SKyle Evansto ensure that the stack has enough space for pushing new elements. 30008e3e3a7aSWarner Losh 30018e3e3a7aSWarner Losh 30028e3e3a7aSWarner Losh 30038e3e3a7aSWarner Losh 30048e3e3a7aSWarner Losh 30050495ed39SKyle Evans<h3>4.1.2 – <a name="4.1.2">Valid and Acceptable Indices</a></h3> 30068e3e3a7aSWarner Losh 30078e3e3a7aSWarner Losh<p> 30088e3e3a7aSWarner LoshAny function in the API that receives stack indices 30098e3e3a7aSWarner Loshworks only with <em>valid indices</em> or <em>acceptable indices</em>. 30108e3e3a7aSWarner Losh 30118e3e3a7aSWarner Losh 30128e3e3a7aSWarner Losh<p> 30138e3e3a7aSWarner LoshA <em>valid index</em> is an index that refers to a 30148e3e3a7aSWarner Loshposition that stores a modifiable Lua value. 30158e3e3a7aSWarner LoshIt comprises stack indices between 1 and the stack top 30168e3e3a7aSWarner Losh(<code>1 ≤ abs(index) ≤ top</code>) 30178e3e3a7aSWarner Losh 30188e3e3a7aSWarner Loshplus <em>pseudo-indices</em>, 30198e3e3a7aSWarner Loshwhich represent some positions that are accessible to C code 30208e3e3a7aSWarner Loshbut that are not in the stack. 30210495ed39SKyle EvansPseudo-indices are used to access the registry (see <a href="#4.3">§4.3</a>) 30220495ed39SKyle Evansand the upvalues of a C function (see <a href="#4.2">§4.2</a>). 30238e3e3a7aSWarner Losh 30248e3e3a7aSWarner Losh 30258e3e3a7aSWarner Losh<p> 30268e3e3a7aSWarner LoshFunctions that do not need a specific mutable position, 30278e3e3a7aSWarner Loshbut only a value (e.g., query functions), 30288e3e3a7aSWarner Loshcan be called with acceptable indices. 30298e3e3a7aSWarner LoshAn <em>acceptable index</em> can be any valid index, 30308e3e3a7aSWarner Loshbut it also can be any positive index after the stack top 30318e3e3a7aSWarner Loshwithin the space allocated for the stack, 30328e3e3a7aSWarner Loshthat is, indices up to the stack size. 30338e3e3a7aSWarner Losh(Note that 0 is never an acceptable index.) 30340495ed39SKyle EvansIndices to upvalues (see <a href="#4.2">§4.2</a>) greater than the real number 30350495ed39SKyle Evansof upvalues in the current C function are also acceptable (but invalid). 30368e3e3a7aSWarner LoshExcept when noted otherwise, 30378e3e3a7aSWarner Loshfunctions in the API work with acceptable indices. 30388e3e3a7aSWarner Losh 30398e3e3a7aSWarner Losh 30408e3e3a7aSWarner Losh<p> 30418e3e3a7aSWarner LoshAcceptable indices serve to avoid extra tests 30428e3e3a7aSWarner Loshagainst the stack top when querying the stack. 30438e3e3a7aSWarner LoshFor instance, a C function can query its third argument 30440495ed39SKyle Evanswithout the need to check whether there is a third argument, 30458e3e3a7aSWarner Loshthat is, without the need to check whether 3 is a valid index. 30468e3e3a7aSWarner Losh 30478e3e3a7aSWarner Losh 30488e3e3a7aSWarner Losh<p> 30498e3e3a7aSWarner LoshFor functions that can be called with acceptable indices, 30508e3e3a7aSWarner Loshany non-valid index is treated as if it 30518e3e3a7aSWarner Loshcontains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>, 30528e3e3a7aSWarner Loshwhich behaves like a nil value. 30538e3e3a7aSWarner Losh 30548e3e3a7aSWarner Losh 30558e3e3a7aSWarner Losh 30568e3e3a7aSWarner Losh 30578e3e3a7aSWarner Losh 30580495ed39SKyle Evans<h3>4.1.3 – <a name="4.1.3">Pointers to strings</a></h3> 30590495ed39SKyle Evans 30600495ed39SKyle Evans<p> 30610495ed39SKyle EvansSeveral functions in the API return pointers (<code>const char*</code>) 30620495ed39SKyle Evansto Lua strings in the stack. 30630495ed39SKyle Evans(See <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>, 30640495ed39SKyle Evans<a href="#lua_pushstring"><code>lua_pushstring</code></a>, and <a href="#lua_tolstring"><code>lua_tolstring</code></a>. 30650495ed39SKyle EvansSee also <a href="#luaL_checklstring"><code>luaL_checklstring</code></a>, <a href="#luaL_checkstring"><code>luaL_checkstring</code></a>, 30660495ed39SKyle Evansand <a href="#luaL_tolstring"><code>luaL_tolstring</code></a> in the auxiliary library.) 30670495ed39SKyle Evans 30680495ed39SKyle Evans 30690495ed39SKyle Evans<p> 30700495ed39SKyle EvansIn general, 30710495ed39SKyle EvansLua's garbage collection can free or move internal memory 30720495ed39SKyle Evansand then invalidate pointers to internal strings. 30730495ed39SKyle EvansTo allow a safe use of these pointers, 30740495ed39SKyle EvansThe API guarantees that any pointer to a string in a stack index 30750495ed39SKyle Evansis valid while the string value at that index is not removed from the stack. 30760495ed39SKyle Evans(It can be moved to another index, though.) 30770495ed39SKyle EvansWhen the index is a pseudo-index (referring to an upvalue), 30780495ed39SKyle Evansthe pointer is valid while the corresponding call is active and 30790495ed39SKyle Evansthe corresponding upvalue is not modified. 30800495ed39SKyle Evans 30810495ed39SKyle Evans 30820495ed39SKyle Evans<p> 30830495ed39SKyle EvansSome functions in the debug interface 30840495ed39SKyle Evansalso return pointers to strings, 30850495ed39SKyle Evansnamely <a href="#lua_getlocal"><code>lua_getlocal</code></a>, <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, 30860495ed39SKyle Evans<a href="#lua_setlocal"><code>lua_setlocal</code></a>, and <a href="#lua_setupvalue"><code>lua_setupvalue</code></a>. 30870495ed39SKyle EvansFor these functions, the pointer is guaranteed to 30880495ed39SKyle Evansbe valid while the caller function is active and 30890495ed39SKyle Evansthe given closure (if one was given) is in the stack. 30900495ed39SKyle Evans 30910495ed39SKyle Evans 30920495ed39SKyle Evans<p> 30930495ed39SKyle EvansExcept for these guarantees, 30940495ed39SKyle Evansthe garbage collector is free to invalidate 30950495ed39SKyle Evansany pointer to internal strings. 30960495ed39SKyle Evans 30970495ed39SKyle Evans 30980495ed39SKyle Evans 30990495ed39SKyle Evans 31000495ed39SKyle Evans 31010495ed39SKyle Evans 31020495ed39SKyle Evans 31030495ed39SKyle Evans<h2>4.2 – <a name="4.2">C Closures</a></h2> 31048e3e3a7aSWarner Losh 31058e3e3a7aSWarner Losh<p> 31068e3e3a7aSWarner LoshWhen a C function is created, 31078e3e3a7aSWarner Loshit is possible to associate some values with it, 31088e3e3a7aSWarner Loshthus creating a <em>C closure</em> 31098e3e3a7aSWarner Losh(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>); 31108e3e3a7aSWarner Loshthese values are called <em>upvalues</em> and are 31118e3e3a7aSWarner Loshaccessible to the function whenever it is called. 31128e3e3a7aSWarner Losh 31138e3e3a7aSWarner Losh 31148e3e3a7aSWarner Losh<p> 31158e3e3a7aSWarner LoshWhenever a C function is called, 31168e3e3a7aSWarner Loshits upvalues are located at specific pseudo-indices. 31178e3e3a7aSWarner LoshThese pseudo-indices are produced by the macro 31188e3e3a7aSWarner Losh<a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>. 31198e3e3a7aSWarner LoshThe first upvalue associated with a function is at index 31208e3e3a7aSWarner Losh<code>lua_upvalueindex(1)</code>, and so on. 31218e3e3a7aSWarner LoshAny access to <code>lua_upvalueindex(<em>n</em>)</code>, 31228e3e3a7aSWarner Loshwhere <em>n</em> is greater than the number of upvalues of the 31238e3e3a7aSWarner Loshcurrent function 31248e3e3a7aSWarner Losh(but not greater than 256, 31258e3e3a7aSWarner Loshwhich is one plus the maximum number of upvalues in a closure), 31268e3e3a7aSWarner Loshproduces an acceptable but invalid index. 31278e3e3a7aSWarner Losh 31288e3e3a7aSWarner Losh 31290495ed39SKyle Evans<p> 31300495ed39SKyle EvansA C closure can also change the values 31310495ed39SKyle Evansof its corresponding upvalues. 31328e3e3a7aSWarner Losh 31338e3e3a7aSWarner Losh 31348e3e3a7aSWarner Losh 31350495ed39SKyle Evans 31360495ed39SKyle Evans 31370495ed39SKyle Evans<h2>4.3 – <a name="4.3">Registry</a></h2> 31388e3e3a7aSWarner Losh 31398e3e3a7aSWarner Losh<p> 31408e3e3a7aSWarner LoshLua provides a <em>registry</em>, 31418e3e3a7aSWarner Losha predefined table that can be used by any C code to 31428e3e3a7aSWarner Loshstore whatever Lua values it needs to store. 31430495ed39SKyle EvansThe registry table is always accessible at pseudo-index 31448e3e3a7aSWarner Losh<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. 31458e3e3a7aSWarner LoshAny C library can store data into this table, 31468e3e3a7aSWarner Loshbut it must take care to choose keys 31478e3e3a7aSWarner Loshthat are different from those used 31488e3e3a7aSWarner Loshby other libraries, to avoid collisions. 31498e3e3a7aSWarner LoshTypically, you should use as key a string containing your library name, 31508e3e3a7aSWarner Loshor a light userdata with the address of a C object in your code, 31518e3e3a7aSWarner Loshor any Lua object created by your code. 31528e3e3a7aSWarner LoshAs with variable names, 31538e3e3a7aSWarner Loshstring keys starting with an underscore followed by 31548e3e3a7aSWarner Loshuppercase letters are reserved for Lua. 31558e3e3a7aSWarner Losh 31568e3e3a7aSWarner Losh 31578e3e3a7aSWarner Losh<p> 31588e3e3a7aSWarner LoshThe integer keys in the registry are used 31598e3e3a7aSWarner Loshby the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>) 31608e3e3a7aSWarner Loshand by some predefined values. 31610495ed39SKyle EvansTherefore, integer keys in the registry 31620495ed39SKyle Evansmust not be used for other purposes. 31638e3e3a7aSWarner Losh 31648e3e3a7aSWarner Losh 31658e3e3a7aSWarner Losh<p> 31668e3e3a7aSWarner LoshWhen you create a new Lua state, 31678e3e3a7aSWarner Loshits registry comes with some predefined values. 31688e3e3a7aSWarner LoshThese predefined values are indexed with integer keys 31698e3e3a7aSWarner Loshdefined as constants in <code>lua.h</code>. 31708e3e3a7aSWarner LoshThe following constants are defined: 31718e3e3a7aSWarner Losh 31728e3e3a7aSWarner Losh<ul> 31738e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has 31748e3e3a7aSWarner Loshthe main thread of the state. 31758e3e3a7aSWarner Losh(The main thread is the one created together with the state.) 31768e3e3a7aSWarner Losh</li> 31778e3e3a7aSWarner Losh 31788e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has 31798e3e3a7aSWarner Loshthe global environment. 31808e3e3a7aSWarner Losh</li> 31818e3e3a7aSWarner Losh</ul> 31828e3e3a7aSWarner Losh 31838e3e3a7aSWarner Losh 31848e3e3a7aSWarner Losh 31858e3e3a7aSWarner Losh 31860495ed39SKyle Evans<h2>4.4 – <a name="4.4">Error Handling in C</a></h2> 31870495ed39SKyle Evans 31880495ed39SKyle Evans 31898e3e3a7aSWarner Losh 31908e3e3a7aSWarner Losh<p> 31918e3e3a7aSWarner LoshInternally, Lua uses the C <code>longjmp</code> facility to handle errors. 31928e3e3a7aSWarner Losh(Lua will use exceptions if you compile it as C++; 31938e3e3a7aSWarner Loshsearch for <code>LUAI_THROW</code> in the source code for details.) 31940495ed39SKyle EvansWhen Lua faces any error, 31950495ed39SKyle Evanssuch as a memory allocation error or a type error, 31968e3e3a7aSWarner Loshit <em>raises</em> an error; 31978e3e3a7aSWarner Loshthat is, it does a long jump. 31988e3e3a7aSWarner LoshA <em>protected environment</em> uses <code>setjmp</code> 31998e3e3a7aSWarner Loshto set a recovery point; 32008e3e3a7aSWarner Loshany error jumps to the most recent active recovery point. 32018e3e3a7aSWarner Losh 32028e3e3a7aSWarner Losh 32038e3e3a7aSWarner Losh<p> 32040495ed39SKyle EvansInside a C function you can raise an error explicitly 32050495ed39SKyle Evansby calling <a href="#lua_error"><code>lua_error</code></a>. 32068e3e3a7aSWarner Losh 32078e3e3a7aSWarner Losh 32088e3e3a7aSWarner Losh<p> 32098e3e3a7aSWarner LoshMost functions in the API can raise an error, 32108e3e3a7aSWarner Loshfor instance due to a memory allocation error. 32118e3e3a7aSWarner LoshThe documentation for each function indicates whether 32128e3e3a7aSWarner Loshit can raise errors. 32138e3e3a7aSWarner Losh 32148e3e3a7aSWarner Losh 32158e3e3a7aSWarner Losh<p> 32168e3e3a7aSWarner LoshIf an error happens outside any protected environment, 32178e3e3a7aSWarner LoshLua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) 32188e3e3a7aSWarner Loshand then calls <code>abort</code>, 32198e3e3a7aSWarner Loshthus exiting the host application. 32208e3e3a7aSWarner LoshYour panic function can avoid this exit by 32218e3e3a7aSWarner Loshnever returning 32228e3e3a7aSWarner Losh(e.g., doing a long jump to your own recovery point outside Lua). 32238e3e3a7aSWarner Losh 32248e3e3a7aSWarner Losh 32258e3e3a7aSWarner Losh<p> 32268e3e3a7aSWarner LoshThe panic function, 32278e3e3a7aSWarner Loshas its name implies, 32288e3e3a7aSWarner Loshis a mechanism of last resort. 32298e3e3a7aSWarner LoshPrograms should avoid it. 32308e3e3a7aSWarner LoshAs a general rule, 32318e3e3a7aSWarner Loshwhen a C function is called by Lua with a Lua state, 32328e3e3a7aSWarner Loshit can do whatever it wants on that Lua state, 32338e3e3a7aSWarner Loshas it should be already protected. 32348e3e3a7aSWarner LoshHowever, 32358e3e3a7aSWarner Loshwhen C code operates on other Lua states 32360495ed39SKyle Evans(e.g., a Lua-state argument to the function, 32378e3e3a7aSWarner Losha Lua state stored in the registry, or 32388e3e3a7aSWarner Loshthe result of <a href="#lua_newthread"><code>lua_newthread</code></a>), 32398e3e3a7aSWarner Loshit should use them only in API calls that cannot raise errors. 32408e3e3a7aSWarner Losh 32418e3e3a7aSWarner Losh 32428e3e3a7aSWarner Losh<p> 32438e3e3a7aSWarner LoshThe panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>); 32440495ed39SKyle Evansin particular, the error object is on the top of the stack. 32458e3e3a7aSWarner LoshHowever, there is no guarantee about stack space. 32468e3e3a7aSWarner LoshTo push anything on the stack, 32470495ed39SKyle Evansthe panic function must first check the available space (see <a href="#4.1.1">§4.1.1</a>). 32488e3e3a7aSWarner Losh 32498e3e3a7aSWarner Losh 32508e3e3a7aSWarner Losh 32518e3e3a7aSWarner Losh 32528e3e3a7aSWarner Losh 32530495ed39SKyle Evans<h3>4.4.1 – <a name="4.4.1">Status Codes</a></h3> 32540495ed39SKyle Evans 32550495ed39SKyle Evans<p> 32560495ed39SKyle EvansSeveral functions that report errors in the API use the following 32570495ed39SKyle Evansstatus codes to indicate different kinds of errors or other conditions: 32580495ed39SKyle Evans 32590495ed39SKyle Evans<ul> 32600495ed39SKyle Evans 32610495ed39SKyle Evans<li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> no errors.</li> 32620495ed39SKyle Evans 32630495ed39SKyle Evans<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b> a runtime error.</li> 32640495ed39SKyle Evans 32650495ed39SKyle Evans<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 32660495ed39SKyle Evansmemory allocation error. 32670495ed39SKyle EvansFor such errors, Lua does not call the message handler. 32680495ed39SKyle Evans</li> 32690495ed39SKyle Evans 32700495ed39SKyle Evans<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b> error while running the message handler.</li> 32710495ed39SKyle Evans 32720495ed39SKyle Evans<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> syntax error during precompilation.</li> 32730495ed39SKyle Evans 32740495ed39SKyle Evans<li><b><a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a>: </b> the thread (coroutine) yields.</li> 32750495ed39SKyle Evans 32760495ed39SKyle Evans<li><b><a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>: </b> a file-related error; 32770495ed39SKyle Evanse.g., it cannot open or read the file.</li> 32780495ed39SKyle Evans 32790495ed39SKyle Evans</ul><p> 32800495ed39SKyle EvansThese constants are defined in the header file <code>lua.h</code>. 32810495ed39SKyle Evans 32820495ed39SKyle Evans 32830495ed39SKyle Evans 32840495ed39SKyle Evans 32850495ed39SKyle Evans 32860495ed39SKyle Evans 32870495ed39SKyle Evans 32880495ed39SKyle Evans<h2>4.5 – <a name="4.5">Handling Yields in C</a></h2> 32898e3e3a7aSWarner Losh 32908e3e3a7aSWarner Losh<p> 32918e3e3a7aSWarner LoshInternally, Lua uses the C <code>longjmp</code> facility to yield a coroutine. 32928e3e3a7aSWarner LoshTherefore, if a C function <code>foo</code> calls an API function 32938e3e3a7aSWarner Loshand this API function yields 32948e3e3a7aSWarner Losh(directly or indirectly by calling another function that yields), 32958e3e3a7aSWarner LoshLua cannot return to <code>foo</code> any more, 32960495ed39SKyle Evansbecause the <code>longjmp</code> removes its frame from the C stack. 32978e3e3a7aSWarner Losh 32988e3e3a7aSWarner Losh 32998e3e3a7aSWarner Losh<p> 33008e3e3a7aSWarner LoshTo avoid this kind of problem, 33018e3e3a7aSWarner LoshLua raises an error whenever it tries to yield across an API call, 33028e3e3a7aSWarner Loshexcept for three functions: 33038e3e3a7aSWarner 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>. 33048e3e3a7aSWarner LoshAll those functions receive a <em>continuation function</em> 33058e3e3a7aSWarner Losh(as a parameter named <code>k</code>) to continue execution after a yield. 33068e3e3a7aSWarner Losh 33078e3e3a7aSWarner Losh 33088e3e3a7aSWarner Losh<p> 33098e3e3a7aSWarner LoshWe need to set some terminology to explain continuations. 33108e3e3a7aSWarner LoshWe have a C function called from Lua which we will call 33118e3e3a7aSWarner Loshthe <em>original function</em>. 33128e3e3a7aSWarner LoshThis original function then calls one of those three functions in the C API, 33138e3e3a7aSWarner Loshwhich we will call the <em>callee function</em>, 33148e3e3a7aSWarner Loshthat then yields the current thread. 33150495ed39SKyle EvansThis can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 33168e3e3a7aSWarner 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> 33170495ed39SKyle Evansand the function called by them yields. 33188e3e3a7aSWarner Losh 33198e3e3a7aSWarner Losh 33208e3e3a7aSWarner Losh<p> 33218e3e3a7aSWarner LoshSuppose the running thread yields while executing the callee function. 33228e3e3a7aSWarner LoshAfter the thread resumes, 33238e3e3a7aSWarner Loshit eventually will finish running the callee function. 33248e3e3a7aSWarner LoshHowever, 33258e3e3a7aSWarner Loshthe callee function cannot return to the original function, 33260495ed39SKyle Evansbecause its frame in the C stack was destroyed by the yield. 33278e3e3a7aSWarner LoshInstead, Lua calls a <em>continuation function</em>, 33288e3e3a7aSWarner Loshwhich was given as an argument to the callee function. 33298e3e3a7aSWarner LoshAs the name implies, 33308e3e3a7aSWarner Loshthe continuation function should continue the task 33318e3e3a7aSWarner Loshof the original function. 33328e3e3a7aSWarner Losh 33338e3e3a7aSWarner Losh 33348e3e3a7aSWarner Losh<p> 33358e3e3a7aSWarner LoshAs an illustration, consider the following function: 33368e3e3a7aSWarner Losh 33378e3e3a7aSWarner Losh<pre> 33388e3e3a7aSWarner Losh int original_function (lua_State *L) { 33398e3e3a7aSWarner Losh ... /* code 1 */ 33408e3e3a7aSWarner Losh status = lua_pcall(L, n, m, h); /* calls Lua */ 33418e3e3a7aSWarner Losh ... /* code 2 */ 33428e3e3a7aSWarner Losh } 33438e3e3a7aSWarner Losh</pre><p> 33448e3e3a7aSWarner LoshNow we want to allow 33458e3e3a7aSWarner Loshthe Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield. 33468e3e3a7aSWarner LoshFirst, we can rewrite our function like here: 33478e3e3a7aSWarner Losh 33488e3e3a7aSWarner Losh<pre> 33498e3e3a7aSWarner Losh int k (lua_State *L, int status, lua_KContext ctx) { 33508e3e3a7aSWarner Losh ... /* code 2 */ 33518e3e3a7aSWarner Losh } 33528e3e3a7aSWarner Losh 33538e3e3a7aSWarner Losh int original_function (lua_State *L) { 33548e3e3a7aSWarner Losh ... /* code 1 */ 33558e3e3a7aSWarner Losh return k(L, lua_pcall(L, n, m, h), ctx); 33568e3e3a7aSWarner Losh } 33578e3e3a7aSWarner Losh</pre><p> 33588e3e3a7aSWarner LoshIn the above code, 33598e3e3a7aSWarner Loshthe new function <code>k</code> is a 33608e3e3a7aSWarner Losh<em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>), 33618e3e3a7aSWarner Loshwhich should do all the work that the original function 33628e3e3a7aSWarner Loshwas doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>. 33638e3e3a7aSWarner LoshNow, we must inform Lua that it must call <code>k</code> if the Lua code 33648e3e3a7aSWarner Loshbeing executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way 33658e3e3a7aSWarner Losh(errors or yielding), 33668e3e3a7aSWarner Loshso we rewrite the code as here, 33678e3e3a7aSWarner Loshreplacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>: 33688e3e3a7aSWarner Losh 33698e3e3a7aSWarner Losh<pre> 33708e3e3a7aSWarner Losh int original_function (lua_State *L) { 33718e3e3a7aSWarner Losh ... /* code 1 */ 33728e3e3a7aSWarner Losh return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1); 33738e3e3a7aSWarner Losh } 33748e3e3a7aSWarner Losh</pre><p> 33758e3e3a7aSWarner LoshNote the external, explicit call to the continuation: 33768e3e3a7aSWarner LoshLua will call the continuation only if needed, that is, 33778e3e3a7aSWarner Loshin case of errors or resuming after a yield. 33788e3e3a7aSWarner LoshIf the called function returns normally without ever yielding, 33798e3e3a7aSWarner Losh<a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally. 33808e3e3a7aSWarner Losh(Of course, instead of calling the continuation in that case, 33818e3e3a7aSWarner Loshyou can do the equivalent work directly inside the original function.) 33828e3e3a7aSWarner Losh 33838e3e3a7aSWarner Losh 33848e3e3a7aSWarner Losh<p> 33858e3e3a7aSWarner LoshBesides the Lua state, 33868e3e3a7aSWarner Loshthe continuation function has two other parameters: 33870495ed39SKyle Evansthe final status of the call and the context value (<code>ctx</code>) that 33888e3e3a7aSWarner Loshwas passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>. 33890495ed39SKyle EvansLua does not use this context value; 33908e3e3a7aSWarner Loshit only passes this value from the original function to the 33910495ed39SKyle Evanscontinuation function. 33928e3e3a7aSWarner LoshFor <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 33938e3e3a7aSWarner Loshthe status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 33948e3e3a7aSWarner Loshexcept that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield 33958e3e3a7aSWarner Losh(instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>). 33968e3e3a7aSWarner LoshFor <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>, 33978e3e3a7aSWarner Loshthe status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation. 33988e3e3a7aSWarner Losh(For these two functions, 33998e3e3a7aSWarner LoshLua will not call the continuation in case of errors, 34008e3e3a7aSWarner Loshbecause they do not handle errors.) 34018e3e3a7aSWarner LoshSimilarly, when using <a href="#lua_callk"><code>lua_callk</code></a>, 34028e3e3a7aSWarner Loshyou should call the continuation function 34038e3e3a7aSWarner Loshwith <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status. 34048e3e3a7aSWarner Losh(For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling 34058e3e3a7aSWarner Loshdirectly the continuation function, 34068e3e3a7aSWarner Loshbecause <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.) 34078e3e3a7aSWarner Losh 34088e3e3a7aSWarner Losh 34098e3e3a7aSWarner Losh<p> 34108e3e3a7aSWarner LoshLua treats the continuation function as if it were the original function. 34118e3e3a7aSWarner LoshThe continuation function receives the same Lua stack 34128e3e3a7aSWarner Loshfrom the original function, 34138e3e3a7aSWarner Loshin the same state it would be if the callee function had returned. 34148e3e3a7aSWarner Losh(For instance, 34158e3e3a7aSWarner Loshafter a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are 34168e3e3a7aSWarner Loshremoved from the stack and replaced by the results from the call.) 34178e3e3a7aSWarner LoshIt also has the same upvalues. 34188e3e3a7aSWarner LoshWhatever it returns is handled by Lua as if it were the return 34198e3e3a7aSWarner Loshof the original function. 34208e3e3a7aSWarner Losh 34218e3e3a7aSWarner Losh 34228e3e3a7aSWarner Losh 34238e3e3a7aSWarner Losh 34248e3e3a7aSWarner Losh 34250495ed39SKyle Evans<h2>4.6 – <a name="4.6">Functions and Types</a></h2> 34268e3e3a7aSWarner Losh 34278e3e3a7aSWarner Losh<p> 34288e3e3a7aSWarner LoshHere we list all functions and types from the C API in 34298e3e3a7aSWarner Loshalphabetical order. 34308e3e3a7aSWarner LoshEach function has an indicator like this: 34318e3e3a7aSWarner Losh<span class="apii">[-o, +p, <em>x</em>]</span> 34328e3e3a7aSWarner Losh 34338e3e3a7aSWarner Losh 34348e3e3a7aSWarner Losh<p> 34358e3e3a7aSWarner LoshThe first field, <code>o</code>, 34368e3e3a7aSWarner Loshis how many elements the function pops from the stack. 34378e3e3a7aSWarner LoshThe second field, <code>p</code>, 34388e3e3a7aSWarner Loshis how many elements the function pushes onto the stack. 34398e3e3a7aSWarner Losh(Any function always pushes its results after popping its arguments.) 34408e3e3a7aSWarner LoshA field in the form <code>x|y</code> means the function can push (or pop) 34418e3e3a7aSWarner Losh<code>x</code> or <code>y</code> elements, 34428e3e3a7aSWarner Loshdepending on the situation; 34438e3e3a7aSWarner Loshan interrogation mark '<code>?</code>' means that 34448e3e3a7aSWarner Loshwe cannot know how many elements the function pops/pushes 34450495ed39SKyle Evansby looking only at its arguments. 34460495ed39SKyle Evans(For instance, they may depend on what is in the stack.) 34478e3e3a7aSWarner LoshThe third field, <code>x</code>, 34488e3e3a7aSWarner Loshtells whether the function may raise errors: 34498e3e3a7aSWarner Losh'<code>-</code>' means the function never raises any error; 34500495ed39SKyle Evans'<code>m</code>' means the function may raise only out-of-memory errors; 34510495ed39SKyle Evans'<code>v</code>' means the function may raise the errors explained in the text; 34520495ed39SKyle Evans'<code>e</code>' means the function can run arbitrary Lua code, 34530495ed39SKyle Evanseither directly or through metamethods, 34540495ed39SKyle Evansand therefore may raise any errors. 34558e3e3a7aSWarner Losh 34568e3e3a7aSWarner Losh 34578e3e3a7aSWarner Losh 34588e3e3a7aSWarner Losh<hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p> 34598e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 34608e3e3a7aSWarner Losh<pre>int lua_absindex (lua_State *L, int idx);</pre> 34618e3e3a7aSWarner Losh 34628e3e3a7aSWarner Losh<p> 34638e3e3a7aSWarner LoshConverts the acceptable index <code>idx</code> 34648e3e3a7aSWarner Loshinto an equivalent absolute index 34650495ed39SKyle Evans(that is, one that does not depend on the stack size). 34668e3e3a7aSWarner Losh 34678e3e3a7aSWarner Losh 34688e3e3a7aSWarner Losh 34698e3e3a7aSWarner Losh 34708e3e3a7aSWarner Losh 34718e3e3a7aSWarner Losh<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> 34728e3e3a7aSWarner Losh<pre>typedef void * (*lua_Alloc) (void *ud, 34738e3e3a7aSWarner Losh void *ptr, 34748e3e3a7aSWarner Losh size_t osize, 34758e3e3a7aSWarner Losh size_t nsize);</pre> 34768e3e3a7aSWarner Losh 34778e3e3a7aSWarner Losh<p> 34788e3e3a7aSWarner LoshThe type of the memory-allocation function used by Lua states. 34798e3e3a7aSWarner LoshThe allocator function must provide a 34808e3e3a7aSWarner Loshfunctionality similar to <code>realloc</code>, 34818e3e3a7aSWarner Loshbut not exactly the same. 34828e3e3a7aSWarner LoshIts arguments are 34838e3e3a7aSWarner Losh<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; 34848e3e3a7aSWarner Losh<code>ptr</code>, a pointer to the block being allocated/reallocated/freed; 34858e3e3a7aSWarner Losh<code>osize</code>, the original size of the block or some code about what 34868e3e3a7aSWarner Loshis being allocated; 34878e3e3a7aSWarner Loshand <code>nsize</code>, the new size of the block. 34888e3e3a7aSWarner Losh 34898e3e3a7aSWarner Losh 34908e3e3a7aSWarner Losh<p> 34918e3e3a7aSWarner LoshWhen <code>ptr</code> is not <code>NULL</code>, 34928e3e3a7aSWarner Losh<code>osize</code> is the size of the block pointed by <code>ptr</code>, 34938e3e3a7aSWarner Loshthat is, the size given when it was allocated or reallocated. 34948e3e3a7aSWarner Losh 34958e3e3a7aSWarner Losh 34968e3e3a7aSWarner Losh<p> 34978e3e3a7aSWarner LoshWhen <code>ptr</code> is <code>NULL</code>, 34988e3e3a7aSWarner Losh<code>osize</code> encodes the kind of object that Lua is allocating. 34998e3e3a7aSWarner Losh<code>osize</code> is any of 35008e3e3a7aSWarner 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>, 35018e3e3a7aSWarner 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) 35028e3e3a7aSWarner LoshLua is creating a new object of that type. 35038e3e3a7aSWarner LoshWhen <code>osize</code> is some other value, 35048e3e3a7aSWarner LoshLua is allocating memory for something else. 35058e3e3a7aSWarner Losh 35068e3e3a7aSWarner Losh 35078e3e3a7aSWarner Losh<p> 35088e3e3a7aSWarner LoshLua assumes the following behavior from the allocator function: 35098e3e3a7aSWarner Losh 35108e3e3a7aSWarner Losh 35118e3e3a7aSWarner Losh<p> 35128e3e3a7aSWarner LoshWhen <code>nsize</code> is zero, 35138e3e3a7aSWarner Loshthe allocator must behave like <code>free</code> 35140495ed39SKyle Evansand then return <code>NULL</code>. 35158e3e3a7aSWarner Losh 35168e3e3a7aSWarner Losh 35178e3e3a7aSWarner Losh<p> 35188e3e3a7aSWarner LoshWhen <code>nsize</code> is not zero, 35198e3e3a7aSWarner Loshthe allocator must behave like <code>realloc</code>. 35200495ed39SKyle EvansIn particular, the allocator returns <code>NULL</code> 35218e3e3a7aSWarner Loshif and only if it cannot fulfill the request. 35228e3e3a7aSWarner Losh 35238e3e3a7aSWarner Losh 35248e3e3a7aSWarner Losh<p> 35258e3e3a7aSWarner LoshHere is a simple implementation for the allocator function. 35268e3e3a7aSWarner LoshIt is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. 35278e3e3a7aSWarner Losh 35288e3e3a7aSWarner Losh<pre> 35298e3e3a7aSWarner Losh static void *l_alloc (void *ud, void *ptr, size_t osize, 35308e3e3a7aSWarner Losh size_t nsize) { 35318e3e3a7aSWarner Losh (void)ud; (void)osize; /* not used */ 35328e3e3a7aSWarner Losh if (nsize == 0) { 35338e3e3a7aSWarner Losh free(ptr); 35348e3e3a7aSWarner Losh return NULL; 35358e3e3a7aSWarner Losh } 35368e3e3a7aSWarner Losh else 35378e3e3a7aSWarner Losh return realloc(ptr, nsize); 35388e3e3a7aSWarner Losh } 35398e3e3a7aSWarner Losh</pre><p> 35408e3e3a7aSWarner LoshNote that Standard C ensures 35418e3e3a7aSWarner Loshthat <code>free(NULL)</code> has no effect and that 35428e3e3a7aSWarner Losh<code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>. 35438e3e3a7aSWarner Losh 35448e3e3a7aSWarner Losh 35458e3e3a7aSWarner Losh 35468e3e3a7aSWarner Losh 35478e3e3a7aSWarner Losh 35488e3e3a7aSWarner Losh<hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p> 35498e3e3a7aSWarner Losh<span class="apii">[-(2|1), +1, <em>e</em>]</span> 35508e3e3a7aSWarner Losh<pre>void lua_arith (lua_State *L, int op);</pre> 35518e3e3a7aSWarner Losh 35528e3e3a7aSWarner Losh<p> 35538e3e3a7aSWarner LoshPerforms an arithmetic or bitwise operation over the two values 35548e3e3a7aSWarner Losh(or one, in the case of negations) 35558e3e3a7aSWarner Loshat the top of the stack, 35560495ed39SKyle Evanswith the value on the top being the second operand, 35578e3e3a7aSWarner Loshpops these values, and pushes the result of the operation. 35588e3e3a7aSWarner LoshThe function follows the semantics of the corresponding Lua operator 35598e3e3a7aSWarner Losh(that is, it may call metamethods). 35608e3e3a7aSWarner Losh 35618e3e3a7aSWarner Losh 35628e3e3a7aSWarner Losh<p> 35638e3e3a7aSWarner LoshThe value of <code>op</code> must be one of the following constants: 35648e3e3a7aSWarner Losh 35658e3e3a7aSWarner Losh<ul> 35668e3e3a7aSWarner Losh 35678e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li> 35688e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li> 35698e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li> 35708e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li> 35718e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li> 35728e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li> 35738e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li> 35748e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li> 35758e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li> 35768e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&</code>)</li> 35778e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li> 35788e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li> 35798e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li> 35808e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li> 35818e3e3a7aSWarner Losh 35828e3e3a7aSWarner Losh</ul> 35838e3e3a7aSWarner Losh 35848e3e3a7aSWarner Losh 35858e3e3a7aSWarner Losh 35868e3e3a7aSWarner Losh 35878e3e3a7aSWarner Losh<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> 35888e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 35898e3e3a7aSWarner Losh<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> 35908e3e3a7aSWarner Losh 35918e3e3a7aSWarner Losh<p> 35920495ed39SKyle EvansSets a new panic function and returns the old one (see <a href="#4.4">§4.4</a>). 35938e3e3a7aSWarner Losh 35948e3e3a7aSWarner Losh 35958e3e3a7aSWarner Losh 35968e3e3a7aSWarner Losh 35978e3e3a7aSWarner Losh 35988e3e3a7aSWarner Losh<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> 35998e3e3a7aSWarner Losh<span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span> 36008e3e3a7aSWarner Losh<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> 36018e3e3a7aSWarner Losh 36028e3e3a7aSWarner Losh<p> 36038e3e3a7aSWarner LoshCalls a function. 36040495ed39SKyle EvansLike regular Lua calls, 36050495ed39SKyle Evans<code>lua_call</code> respects the <code>__call</code> metamethod. 36060495ed39SKyle EvansSo, here the word "function" 36070495ed39SKyle Evansmeans any callable value. 36088e3e3a7aSWarner Losh 36098e3e3a7aSWarner Losh 36108e3e3a7aSWarner Losh<p> 36110495ed39SKyle EvansTo do a call you must use the following protocol: 36128e3e3a7aSWarner Loshfirst, the function to be called is pushed onto the stack; 36130495ed39SKyle Evansthen, the arguments to the call are pushed 36148e3e3a7aSWarner Loshin direct order; 36158e3e3a7aSWarner Loshthat is, the first argument is pushed first. 36168e3e3a7aSWarner LoshFinally you call <a href="#lua_call"><code>lua_call</code></a>; 36178e3e3a7aSWarner Losh<code>nargs</code> is the number of arguments that you pushed onto the stack. 36180495ed39SKyle EvansWhen the function returns, 36190495ed39SKyle Evansall arguments and the function value are popped 36200495ed39SKyle Evansand the call results are pushed onto the stack. 36218e3e3a7aSWarner LoshThe number of results is adjusted to <code>nresults</code>, 36228e3e3a7aSWarner Loshunless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. 36238e3e3a7aSWarner LoshIn this case, all results from the function are pushed; 36248e3e3a7aSWarner LoshLua takes care that the returned values fit into the stack space, 36258e3e3a7aSWarner Loshbut it does not ensure any extra space in the stack. 36268e3e3a7aSWarner LoshThe function results are pushed onto the stack in direct order 36278e3e3a7aSWarner Losh(the first result is pushed first), 36288e3e3a7aSWarner Loshso that after the call the last result is on the top of the stack. 36298e3e3a7aSWarner Losh 36308e3e3a7aSWarner Losh 36318e3e3a7aSWarner Losh<p> 36320495ed39SKyle EvansAny error while calling and running the function is propagated upwards 36338e3e3a7aSWarner Losh(with a <code>longjmp</code>). 36348e3e3a7aSWarner Losh 36358e3e3a7aSWarner Losh 36368e3e3a7aSWarner Losh<p> 36378e3e3a7aSWarner LoshThe following example shows how the host program can do the 36388e3e3a7aSWarner Loshequivalent to this Lua code: 36398e3e3a7aSWarner Losh 36408e3e3a7aSWarner Losh<pre> 36418e3e3a7aSWarner Losh a = f("how", t.x, 14) 36428e3e3a7aSWarner Losh</pre><p> 36438e3e3a7aSWarner LoshHere it is in C: 36448e3e3a7aSWarner Losh 36458e3e3a7aSWarner Losh<pre> 36468e3e3a7aSWarner Losh lua_getglobal(L, "f"); /* function to be called */ 36478e3e3a7aSWarner Losh lua_pushliteral(L, "how"); /* 1st argument */ 36488e3e3a7aSWarner Losh lua_getglobal(L, "t"); /* table to be indexed */ 36498e3e3a7aSWarner Losh lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 36508e3e3a7aSWarner Losh lua_remove(L, -2); /* remove 't' from the stack */ 36518e3e3a7aSWarner Losh lua_pushinteger(L, 14); /* 3rd argument */ 36528e3e3a7aSWarner Losh lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ 36538e3e3a7aSWarner Losh lua_setglobal(L, "a"); /* set global 'a' */ 36548e3e3a7aSWarner Losh</pre><p> 36558e3e3a7aSWarner LoshNote that the code above is <em>balanced</em>: 36568e3e3a7aSWarner Loshat its end, the stack is back to its original configuration. 36578e3e3a7aSWarner LoshThis is considered good programming practice. 36588e3e3a7aSWarner Losh 36598e3e3a7aSWarner Losh 36608e3e3a7aSWarner Losh 36618e3e3a7aSWarner Losh 36628e3e3a7aSWarner Losh 36638e3e3a7aSWarner Losh<hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p> 36648e3e3a7aSWarner Losh<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> 36658e3e3a7aSWarner Losh<pre>void lua_callk (lua_State *L, 36668e3e3a7aSWarner Losh int nargs, 36678e3e3a7aSWarner Losh int nresults, 36688e3e3a7aSWarner Losh lua_KContext ctx, 36698e3e3a7aSWarner Losh lua_KFunction k);</pre> 36708e3e3a7aSWarner Losh 36718e3e3a7aSWarner Losh<p> 36728e3e3a7aSWarner LoshThis function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>, 36730495ed39SKyle Evansbut allows the called function to yield (see <a href="#4.5">§4.5</a>). 36748e3e3a7aSWarner Losh 36758e3e3a7aSWarner Losh 36768e3e3a7aSWarner Losh 36778e3e3a7aSWarner Losh 36788e3e3a7aSWarner Losh 36798e3e3a7aSWarner Losh<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> 36808e3e3a7aSWarner Losh<pre>typedef int (*lua_CFunction) (lua_State *L);</pre> 36818e3e3a7aSWarner Losh 36828e3e3a7aSWarner Losh<p> 36838e3e3a7aSWarner LoshType for C functions. 36848e3e3a7aSWarner Losh 36858e3e3a7aSWarner Losh 36868e3e3a7aSWarner Losh<p> 36878e3e3a7aSWarner LoshIn order to communicate properly with Lua, 36888e3e3a7aSWarner Losha C function must use the following protocol, 36898e3e3a7aSWarner Loshwhich defines the way parameters and results are passed: 36908e3e3a7aSWarner Losha C function receives its arguments from Lua in its stack 36918e3e3a7aSWarner Loshin direct order (the first argument is pushed first). 36928e3e3a7aSWarner LoshSo, when the function starts, 36938e3e3a7aSWarner Losh<code>lua_gettop(L)</code> returns the number of arguments received by the function. 36948e3e3a7aSWarner LoshThe first argument (if any) is at index 1 36958e3e3a7aSWarner Loshand its last argument is at index <code>lua_gettop(L)</code>. 36968e3e3a7aSWarner LoshTo return values to Lua, a C function just pushes them onto the stack, 36978e3e3a7aSWarner Loshin direct order (the first result is pushed first), 36980495ed39SKyle Evansand returns in C the number of results. 36998e3e3a7aSWarner LoshAny other value in the stack below the results will be properly 37008e3e3a7aSWarner Loshdiscarded by Lua. 37018e3e3a7aSWarner LoshLike a Lua function, a C function called by Lua can also return 37028e3e3a7aSWarner Loshmany results. 37038e3e3a7aSWarner Losh 37048e3e3a7aSWarner Losh 37058e3e3a7aSWarner Losh<p> 37068e3e3a7aSWarner LoshAs an example, the following function receives a variable number 37078e3e3a7aSWarner Loshof numeric arguments and returns their average and their sum: 37088e3e3a7aSWarner Losh 37098e3e3a7aSWarner Losh<pre> 37108e3e3a7aSWarner Losh static int foo (lua_State *L) { 37118e3e3a7aSWarner Losh int n = lua_gettop(L); /* number of arguments */ 37128e3e3a7aSWarner Losh lua_Number sum = 0.0; 37138e3e3a7aSWarner Losh int i; 37148e3e3a7aSWarner Losh for (i = 1; i <= n; i++) { 37158e3e3a7aSWarner Losh if (!lua_isnumber(L, i)) { 37168e3e3a7aSWarner Losh lua_pushliteral(L, "incorrect argument"); 37178e3e3a7aSWarner Losh lua_error(L); 37188e3e3a7aSWarner Losh } 37198e3e3a7aSWarner Losh sum += lua_tonumber(L, i); 37208e3e3a7aSWarner Losh } 37218e3e3a7aSWarner Losh lua_pushnumber(L, sum/n); /* first result */ 37228e3e3a7aSWarner Losh lua_pushnumber(L, sum); /* second result */ 37238e3e3a7aSWarner Losh return 2; /* number of results */ 37248e3e3a7aSWarner Losh } 37258e3e3a7aSWarner Losh</pre> 37268e3e3a7aSWarner Losh 37278e3e3a7aSWarner Losh 37288e3e3a7aSWarner Losh 37298e3e3a7aSWarner Losh 37308e3e3a7aSWarner Losh<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> 37318e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 37328e3e3a7aSWarner Losh<pre>int lua_checkstack (lua_State *L, int n);</pre> 37338e3e3a7aSWarner Losh 37348e3e3a7aSWarner Losh<p> 37350495ed39SKyle EvansEnsures that the stack has space for at least <code>n</code> extra elements, 37360495ed39SKyle Evansthat is, that you can safely push up to <code>n</code> values into it. 37378e3e3a7aSWarner LoshIt returns false if it cannot fulfill the request, 37388e3e3a7aSWarner Losheither because it would cause the stack 37390495ed39SKyle Evansto be greater than a fixed maximum size 37408e3e3a7aSWarner Losh(typically at least several thousand elements) or 37418e3e3a7aSWarner Loshbecause it cannot allocate memory for the extra space. 37428e3e3a7aSWarner LoshThis function never shrinks the stack; 37430495ed39SKyle Evansif the stack already has space for the extra elements, 37448e3e3a7aSWarner Loshit is left unchanged. 37458e3e3a7aSWarner Losh 37468e3e3a7aSWarner Losh 37478e3e3a7aSWarner Losh 37488e3e3a7aSWarner Losh 37498e3e3a7aSWarner Losh 37508e3e3a7aSWarner Losh<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> 37518e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 37528e3e3a7aSWarner Losh<pre>void lua_close (lua_State *L);</pre> 37538e3e3a7aSWarner Losh 37548e3e3a7aSWarner Losh<p> 37550495ed39SKyle EvansClose all active to-be-closed variables in the main thread, 37560495ed39SKyle Evansrelease all objects in the given Lua state 37570495ed39SKyle Evans(calling the corresponding garbage-collection metamethods, if any), 37588e3e3a7aSWarner Loshand frees all dynamic memory used by this state. 37590495ed39SKyle Evans 37600495ed39SKyle Evans 37610495ed39SKyle Evans<p> 37620495ed39SKyle EvansOn several platforms, you may not need to call this function, 37638e3e3a7aSWarner Loshbecause all resources are naturally released when the host program ends. 37648e3e3a7aSWarner LoshOn the other hand, long-running programs that create multiple states, 37658e3e3a7aSWarner Loshsuch as daemons or web servers, 37668e3e3a7aSWarner Loshwill probably need to close states as soon as they are not needed. 37678e3e3a7aSWarner Losh 37688e3e3a7aSWarner Losh 37698e3e3a7aSWarner Losh 37708e3e3a7aSWarner Losh 37718e3e3a7aSWarner Losh 3772*8c784bb8SWarner Losh<hr><h3><a name="lua_closeslot"><code>lua_closeslot</code></a></h3><p> 3773*8c784bb8SWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 3774*8c784bb8SWarner Losh<pre>void lua_closeslot (lua_State *L, int index);</pre> 3775*8c784bb8SWarner Losh 3776*8c784bb8SWarner Losh<p> 3777*8c784bb8SWarner LoshClose the to-be-closed slot at the given index and set its value to <b>nil</b>. 3778*8c784bb8SWarner LoshThe index must be the last index previously marked to be closed 3779*8c784bb8SWarner Losh(see <a href="#lua_toclose"><code>lua_toclose</code></a>) that is still active (that is, not closed yet). 3780*8c784bb8SWarner Losh 3781*8c784bb8SWarner Losh 3782*8c784bb8SWarner Losh<p> 3783*8c784bb8SWarner LoshA <code>__close</code> metamethod cannot yield 3784*8c784bb8SWarner Loshwhen called through this function. 3785*8c784bb8SWarner Losh 3786*8c784bb8SWarner Losh 3787*8c784bb8SWarner Losh<p> 3788*8c784bb8SWarner Losh(Exceptionally, this function was introduced in release 5.4.3. 3789*8c784bb8SWarner LoshIt is not present in previous 5.4 releases.) 3790*8c784bb8SWarner Losh 3791*8c784bb8SWarner Losh 3792*8c784bb8SWarner Losh 3793*8c784bb8SWarner Losh 3794*8c784bb8SWarner Losh 37958e3e3a7aSWarner Losh<hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p> 37968e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 37978e3e3a7aSWarner Losh<pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre> 37988e3e3a7aSWarner Losh 37998e3e3a7aSWarner Losh<p> 38008e3e3a7aSWarner LoshCompares two Lua values. 38018e3e3a7aSWarner LoshReturns 1 if the value at index <code>index1</code> satisfies <code>op</code> 38028e3e3a7aSWarner Loshwhen compared with the value at index <code>index2</code>, 38038e3e3a7aSWarner Loshfollowing the semantics of the corresponding Lua operator 38048e3e3a7aSWarner Losh(that is, it may call metamethods). 38058e3e3a7aSWarner LoshOtherwise returns 0. 38068e3e3a7aSWarner LoshAlso returns 0 if any of the indices is not valid. 38078e3e3a7aSWarner Losh 38088e3e3a7aSWarner Losh 38098e3e3a7aSWarner Losh<p> 38108e3e3a7aSWarner LoshThe value of <code>op</code> must be one of the following constants: 38118e3e3a7aSWarner Losh 38128e3e3a7aSWarner Losh<ul> 38138e3e3a7aSWarner Losh 38148e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li> 38158e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li> 38168e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li> 38178e3e3a7aSWarner Losh 38188e3e3a7aSWarner Losh</ul> 38198e3e3a7aSWarner Losh 38208e3e3a7aSWarner Losh 38218e3e3a7aSWarner Losh 38228e3e3a7aSWarner Losh 38238e3e3a7aSWarner Losh<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> 38248e3e3a7aSWarner Losh<span class="apii">[-n, +1, <em>e</em>]</span> 38258e3e3a7aSWarner Losh<pre>void lua_concat (lua_State *L, int n);</pre> 38268e3e3a7aSWarner Losh 38278e3e3a7aSWarner Losh<p> 38288e3e3a7aSWarner LoshConcatenates the <code>n</code> values at the top of the stack, 38290495ed39SKyle Evanspops them, and leaves the result on the top. 38308e3e3a7aSWarner LoshIf <code>n</code> is 1, the result is the single value on the stack 38318e3e3a7aSWarner Losh(that is, the function does nothing); 38328e3e3a7aSWarner Loshif <code>n</code> is 0, the result is the empty string. 38338e3e3a7aSWarner LoshConcatenation is performed following the usual semantics of Lua 38348e3e3a7aSWarner Losh(see <a href="#3.4.6">§3.4.6</a>). 38358e3e3a7aSWarner Losh 38368e3e3a7aSWarner Losh 38378e3e3a7aSWarner Losh 38388e3e3a7aSWarner Losh 38398e3e3a7aSWarner Losh 38408e3e3a7aSWarner Losh<hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p> 38418e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 38428e3e3a7aSWarner Losh<pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre> 38438e3e3a7aSWarner Losh 38448e3e3a7aSWarner Losh<p> 38458e3e3a7aSWarner LoshCopies the element at index <code>fromidx</code> 38468e3e3a7aSWarner Loshinto the valid index <code>toidx</code>, 38478e3e3a7aSWarner Loshreplacing the value at that position. 38488e3e3a7aSWarner LoshValues at other positions are not affected. 38498e3e3a7aSWarner Losh 38508e3e3a7aSWarner Losh 38518e3e3a7aSWarner Losh 38528e3e3a7aSWarner Losh 38538e3e3a7aSWarner Losh 38548e3e3a7aSWarner Losh<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> 38558e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 38568e3e3a7aSWarner Losh<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> 38578e3e3a7aSWarner Losh 38588e3e3a7aSWarner Losh<p> 38598e3e3a7aSWarner LoshCreates a new empty table and pushes it onto the stack. 38608e3e3a7aSWarner LoshParameter <code>narr</code> is a hint for how many elements the table 38618e3e3a7aSWarner Loshwill have as a sequence; 38628e3e3a7aSWarner Loshparameter <code>nrec</code> is a hint for how many other elements 38638e3e3a7aSWarner Loshthe table will have. 38648e3e3a7aSWarner LoshLua may use these hints to preallocate memory for the new table. 38650495ed39SKyle EvansThis preallocation may help performance when you know in advance 38668e3e3a7aSWarner Loshhow many elements the table will have. 38678e3e3a7aSWarner LoshOtherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. 38688e3e3a7aSWarner Losh 38698e3e3a7aSWarner Losh 38708e3e3a7aSWarner Losh 38718e3e3a7aSWarner Losh 38728e3e3a7aSWarner Losh 38738e3e3a7aSWarner Losh<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> 38748e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 38758e3e3a7aSWarner Losh<pre>int lua_dump (lua_State *L, 38768e3e3a7aSWarner Losh lua_Writer writer, 38778e3e3a7aSWarner Losh void *data, 38788e3e3a7aSWarner Losh int strip);</pre> 38798e3e3a7aSWarner Losh 38808e3e3a7aSWarner Losh<p> 38818e3e3a7aSWarner LoshDumps a function as a binary chunk. 38828e3e3a7aSWarner LoshReceives a Lua function on the top of the stack 38838e3e3a7aSWarner Loshand produces a binary chunk that, 38848e3e3a7aSWarner Loshif loaded again, 38858e3e3a7aSWarner Loshresults in a function equivalent to the one dumped. 38868e3e3a7aSWarner LoshAs it produces parts of the chunk, 38878e3e3a7aSWarner 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>) 38888e3e3a7aSWarner Loshwith the given <code>data</code> 38898e3e3a7aSWarner Loshto write them. 38908e3e3a7aSWarner Losh 38918e3e3a7aSWarner Losh 38928e3e3a7aSWarner Losh<p> 38938e3e3a7aSWarner LoshIf <code>strip</code> is true, 38948e3e3a7aSWarner Loshthe binary representation may not include all debug information 38958e3e3a7aSWarner Loshabout the function, 38968e3e3a7aSWarner Loshto save space. 38978e3e3a7aSWarner Losh 38988e3e3a7aSWarner Losh 38998e3e3a7aSWarner Losh<p> 39008e3e3a7aSWarner LoshThe value returned is the error code returned by the last 39018e3e3a7aSWarner Loshcall to the writer; 39028e3e3a7aSWarner Losh0 means no errors. 39038e3e3a7aSWarner Losh 39048e3e3a7aSWarner Losh 39058e3e3a7aSWarner Losh<p> 39068e3e3a7aSWarner LoshThis function does not pop the Lua function from the stack. 39078e3e3a7aSWarner Losh 39088e3e3a7aSWarner Losh 39098e3e3a7aSWarner Losh 39108e3e3a7aSWarner Losh 39118e3e3a7aSWarner Losh 39128e3e3a7aSWarner Losh<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> 39138e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>v</em>]</span> 39148e3e3a7aSWarner Losh<pre>int lua_error (lua_State *L);</pre> 39158e3e3a7aSWarner Losh 39168e3e3a7aSWarner Losh<p> 39170495ed39SKyle EvansRaises a Lua error, 39180495ed39SKyle Evansusing the value on the top of the stack as the error object. 39198e3e3a7aSWarner LoshThis function does a long jump, 39208e3e3a7aSWarner Loshand therefore never returns 39218e3e3a7aSWarner Losh(see <a href="#luaL_error"><code>luaL_error</code></a>). 39228e3e3a7aSWarner Losh 39238e3e3a7aSWarner Losh 39248e3e3a7aSWarner Losh 39258e3e3a7aSWarner Losh 39268e3e3a7aSWarner Losh 39278e3e3a7aSWarner Losh<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> 39280495ed39SKyle Evans<span class="apii">[-0, +0, –]</span> 39290495ed39SKyle Evans<pre>int lua_gc (lua_State *L, int what, ...);</pre> 39308e3e3a7aSWarner Losh 39318e3e3a7aSWarner Losh<p> 39328e3e3a7aSWarner LoshControls the garbage collector. 39338e3e3a7aSWarner Losh 39348e3e3a7aSWarner Losh 39358e3e3a7aSWarner Losh<p> 39368e3e3a7aSWarner LoshThis function performs several tasks, 39370495ed39SKyle Evansaccording to the value of the parameter <code>what</code>. 39380495ed39SKyle EvansFor options that need extra arguments, 39390495ed39SKyle Evansthey are listed after the option. 39408e3e3a7aSWarner Losh 39418e3e3a7aSWarner Losh<ul> 39428e3e3a7aSWarner Losh 39430495ed39SKyle Evans<li><b><code>LUA_GCCOLLECT</code>: </b> 39440495ed39SKyle EvansPerforms a full garbage-collection cycle. 39450495ed39SKyle Evans</li> 39460495ed39SKyle Evans 39478e3e3a7aSWarner Losh<li><b><code>LUA_GCSTOP</code>: </b> 39480495ed39SKyle EvansStops the garbage collector. 39498e3e3a7aSWarner Losh</li> 39508e3e3a7aSWarner Losh 39518e3e3a7aSWarner Losh<li><b><code>LUA_GCRESTART</code>: </b> 39520495ed39SKyle EvansRestarts the garbage collector. 39538e3e3a7aSWarner Losh</li> 39548e3e3a7aSWarner Losh 39558e3e3a7aSWarner Losh<li><b><code>LUA_GCCOUNT</code>: </b> 39560495ed39SKyle EvansReturns the current amount of memory (in Kbytes) in use by Lua. 39578e3e3a7aSWarner Losh</li> 39588e3e3a7aSWarner Losh 39598e3e3a7aSWarner Losh<li><b><code>LUA_GCCOUNTB</code>: </b> 39600495ed39SKyle EvansReturns the remainder of dividing the current amount of bytes of 39618e3e3a7aSWarner Loshmemory in use by Lua by 1024. 39628e3e3a7aSWarner Losh</li> 39638e3e3a7aSWarner Losh 39640495ed39SKyle Evans<li><b><code>LUA_GCSTEP</code> <code>(int stepsize)</code>: </b> 39650495ed39SKyle EvansPerforms an incremental step of garbage collection, 39660495ed39SKyle Evanscorresponding to the allocation of <code>stepsize</code> Kbytes. 39678e3e3a7aSWarner Losh</li> 39688e3e3a7aSWarner Losh 39698e3e3a7aSWarner Losh<li><b><code>LUA_GCISRUNNING</code>: </b> 39700495ed39SKyle EvansReturns a boolean that tells whether the collector is running 39718e3e3a7aSWarner Losh(i.e., not stopped). 39728e3e3a7aSWarner Losh</li> 39738e3e3a7aSWarner Losh 39740495ed39SKyle Evans<li><b><code>LUA_GCINC</code> (int pause, int stepmul, stepsize): </b> 39750495ed39SKyle EvansChanges the collector to incremental mode 39760495ed39SKyle Evanswith the given parameters (see <a href="#2.5.1">§2.5.1</a>). 39770495ed39SKyle EvansReturns the previous mode (<code>LUA_GCGEN</code> or <code>LUA_GCINC</code>). 39780495ed39SKyle Evans</li> 39798e3e3a7aSWarner Losh 39800495ed39SKyle Evans<li><b><code>LUA_GCGEN</code> (int minormul, int majormul): </b> 39810495ed39SKyle EvansChanges the collector to generational mode 39820495ed39SKyle Evanswith the given parameters (see <a href="#2.5.2">§2.5.2</a>). 39830495ed39SKyle EvansReturns the previous mode (<code>LUA_GCGEN</code> or <code>LUA_GCINC</code>). 39840495ed39SKyle Evans</li> 39850495ed39SKyle Evans 39860495ed39SKyle Evans</ul><p> 39878e3e3a7aSWarner LoshFor more details about these options, 39888e3e3a7aSWarner Loshsee <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>. 39898e3e3a7aSWarner Losh 39908e3e3a7aSWarner Losh 3991*8c784bb8SWarner Losh<p> 3992*8c784bb8SWarner LoshThis function should not be called by a finalizer. 3993*8c784bb8SWarner Losh 3994*8c784bb8SWarner Losh 39958e3e3a7aSWarner Losh 39968e3e3a7aSWarner Losh 39978e3e3a7aSWarner Losh 39988e3e3a7aSWarner Losh<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> 39998e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 40008e3e3a7aSWarner Losh<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> 40018e3e3a7aSWarner Losh 40028e3e3a7aSWarner Losh<p> 40038e3e3a7aSWarner LoshReturns the memory-allocation function of a given state. 40048e3e3a7aSWarner LoshIf <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the 40058e3e3a7aSWarner Loshopaque pointer given when the memory-allocator function was set. 40068e3e3a7aSWarner Losh 40078e3e3a7aSWarner Losh 40088e3e3a7aSWarner Losh 40098e3e3a7aSWarner Losh 40108e3e3a7aSWarner Losh 40118e3e3a7aSWarner Losh<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> 40128e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 40138e3e3a7aSWarner Losh<pre>int lua_getfield (lua_State *L, int index, const char *k);</pre> 40148e3e3a7aSWarner Losh 40158e3e3a7aSWarner Losh<p> 40168e3e3a7aSWarner LoshPushes onto the stack the value <code>t[k]</code>, 40178e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index. 40188e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 40198e3e3a7aSWarner Loshfor the "index" event (see <a href="#2.4">§2.4</a>). 40208e3e3a7aSWarner Losh 40218e3e3a7aSWarner Losh 40228e3e3a7aSWarner Losh<p> 40238e3e3a7aSWarner LoshReturns the type of the pushed value. 40248e3e3a7aSWarner Losh 40258e3e3a7aSWarner Losh 40268e3e3a7aSWarner Losh 40278e3e3a7aSWarner Losh 40288e3e3a7aSWarner Losh 40298e3e3a7aSWarner Losh<hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p> 40308e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 40318e3e3a7aSWarner Losh<pre>void *lua_getextraspace (lua_State *L);</pre> 40328e3e3a7aSWarner Losh 40338e3e3a7aSWarner Losh<p> 40348e3e3a7aSWarner LoshReturns a pointer to a raw memory area associated with the 40358e3e3a7aSWarner Loshgiven Lua state. 40368e3e3a7aSWarner LoshThe application can use this area for any purpose; 40378e3e3a7aSWarner LoshLua does not use it for anything. 40388e3e3a7aSWarner Losh 40398e3e3a7aSWarner Losh 40408e3e3a7aSWarner Losh<p> 40418e3e3a7aSWarner LoshEach new thread has this area initialized with a copy 40428e3e3a7aSWarner Loshof the area of the main thread. 40438e3e3a7aSWarner Losh 40448e3e3a7aSWarner Losh 40458e3e3a7aSWarner Losh<p> 40468e3e3a7aSWarner LoshBy default, this area has the size of a pointer to void, 40478e3e3a7aSWarner Loshbut you can recompile Lua with a different size for this area. 40488e3e3a7aSWarner Losh(See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.) 40498e3e3a7aSWarner Losh 40508e3e3a7aSWarner Losh 40518e3e3a7aSWarner Losh 40528e3e3a7aSWarner Losh 40538e3e3a7aSWarner Losh 40548e3e3a7aSWarner Losh<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> 40558e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 40568e3e3a7aSWarner Losh<pre>int lua_getglobal (lua_State *L, const char *name);</pre> 40578e3e3a7aSWarner Losh 40588e3e3a7aSWarner Losh<p> 40598e3e3a7aSWarner LoshPushes onto the stack the value of the global <code>name</code>. 40608e3e3a7aSWarner LoshReturns the type of that value. 40618e3e3a7aSWarner Losh 40628e3e3a7aSWarner Losh 40638e3e3a7aSWarner Losh 40648e3e3a7aSWarner Losh 40658e3e3a7aSWarner Losh 40668e3e3a7aSWarner Losh<hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p> 40678e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 40688e3e3a7aSWarner Losh<pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre> 40698e3e3a7aSWarner Losh 40708e3e3a7aSWarner Losh<p> 40718e3e3a7aSWarner LoshPushes onto the stack the value <code>t[i]</code>, 40728e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index. 40738e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 40748e3e3a7aSWarner Loshfor the "index" event (see <a href="#2.4">§2.4</a>). 40758e3e3a7aSWarner Losh 40768e3e3a7aSWarner Losh 40778e3e3a7aSWarner Losh<p> 40788e3e3a7aSWarner LoshReturns the type of the pushed value. 40798e3e3a7aSWarner Losh 40808e3e3a7aSWarner Losh 40818e3e3a7aSWarner Losh 40828e3e3a7aSWarner Losh 40838e3e3a7aSWarner Losh 40848e3e3a7aSWarner Losh<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> 40858e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), –]</span> 40868e3e3a7aSWarner Losh<pre>int lua_getmetatable (lua_State *L, int index);</pre> 40878e3e3a7aSWarner Losh 40888e3e3a7aSWarner Losh<p> 40898e3e3a7aSWarner LoshIf the value at the given index has a metatable, 40908e3e3a7aSWarner Loshthe function pushes that metatable onto the stack and returns 1. 40918e3e3a7aSWarner LoshOtherwise, 40928e3e3a7aSWarner Loshthe function returns 0 and pushes nothing on the stack. 40938e3e3a7aSWarner Losh 40948e3e3a7aSWarner Losh 40958e3e3a7aSWarner Losh 40968e3e3a7aSWarner Losh 40978e3e3a7aSWarner Losh 40988e3e3a7aSWarner Losh<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> 40998e3e3a7aSWarner Losh<span class="apii">[-1, +1, <em>e</em>]</span> 41008e3e3a7aSWarner Losh<pre>int lua_gettable (lua_State *L, int index);</pre> 41018e3e3a7aSWarner Losh 41028e3e3a7aSWarner Losh<p> 41038e3e3a7aSWarner LoshPushes onto the stack the value <code>t[k]</code>, 41048e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index 41050495ed39SKyle Evansand <code>k</code> is the value on the top of the stack. 41068e3e3a7aSWarner Losh 41078e3e3a7aSWarner Losh 41088e3e3a7aSWarner Losh<p> 41098e3e3a7aSWarner LoshThis function pops the key from the stack, 41108e3e3a7aSWarner Loshpushing the resulting value in its place. 41118e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 41128e3e3a7aSWarner Loshfor the "index" event (see <a href="#2.4">§2.4</a>). 41138e3e3a7aSWarner Losh 41148e3e3a7aSWarner Losh 41158e3e3a7aSWarner Losh<p> 41168e3e3a7aSWarner LoshReturns the type of the pushed value. 41178e3e3a7aSWarner Losh 41188e3e3a7aSWarner Losh 41198e3e3a7aSWarner Losh 41208e3e3a7aSWarner Losh 41218e3e3a7aSWarner Losh 41228e3e3a7aSWarner Losh<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> 41238e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 41248e3e3a7aSWarner Losh<pre>int lua_gettop (lua_State *L);</pre> 41258e3e3a7aSWarner Losh 41268e3e3a7aSWarner Losh<p> 41278e3e3a7aSWarner LoshReturns the index of the top element in the stack. 41288e3e3a7aSWarner LoshBecause indices start at 1, 41298e3e3a7aSWarner Loshthis result is equal to the number of elements in the stack; 41308e3e3a7aSWarner Loshin particular, 0 means an empty stack. 41318e3e3a7aSWarner Losh 41328e3e3a7aSWarner Losh 41338e3e3a7aSWarner Losh 41348e3e3a7aSWarner Losh 41358e3e3a7aSWarner Losh 41360495ed39SKyle Evans<hr><h3><a name="lua_getiuservalue"><code>lua_getiuservalue</code></a></h3><p> 41378e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 41380495ed39SKyle Evans<pre>int lua_getiuservalue (lua_State *L, int index, int n);</pre> 41398e3e3a7aSWarner Losh 41408e3e3a7aSWarner Losh<p> 41410495ed39SKyle EvansPushes onto the stack the <code>n</code>-th user value associated with the 41420495ed39SKyle Evansfull userdata at the given index and 41430495ed39SKyle Evansreturns the type of the pushed value. 41448e3e3a7aSWarner Losh 41458e3e3a7aSWarner Losh 41468e3e3a7aSWarner Losh<p> 41470495ed39SKyle EvansIf the userdata does not have that value, 41480495ed39SKyle Evanspushes <b>nil</b> and returns <a href="#pdf-LUA_TNONE"><code>LUA_TNONE</code></a>. 41498e3e3a7aSWarner Losh 41508e3e3a7aSWarner Losh 41518e3e3a7aSWarner Losh 41528e3e3a7aSWarner Losh 41538e3e3a7aSWarner Losh 41548e3e3a7aSWarner Losh<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> 41558e3e3a7aSWarner Losh<span class="apii">[-1, +1, –]</span> 41568e3e3a7aSWarner Losh<pre>void lua_insert (lua_State *L, int index);</pre> 41578e3e3a7aSWarner Losh 41588e3e3a7aSWarner Losh<p> 41598e3e3a7aSWarner LoshMoves the top element into the given valid index, 41608e3e3a7aSWarner Loshshifting up the elements above this index to open space. 41618e3e3a7aSWarner LoshThis function cannot be called with a pseudo-index, 41628e3e3a7aSWarner Loshbecause a pseudo-index is not an actual stack position. 41638e3e3a7aSWarner Losh 41648e3e3a7aSWarner Losh 41658e3e3a7aSWarner Losh 41668e3e3a7aSWarner Losh 41678e3e3a7aSWarner Losh 41688e3e3a7aSWarner Losh<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> 41698e3e3a7aSWarner Losh<pre>typedef ... lua_Integer;</pre> 41708e3e3a7aSWarner Losh 41718e3e3a7aSWarner Losh<p> 41728e3e3a7aSWarner LoshThe type of integers in Lua. 41738e3e3a7aSWarner Losh 41748e3e3a7aSWarner Losh 41758e3e3a7aSWarner Losh<p> 41768e3e3a7aSWarner LoshBy default this type is <code>long long</code>, 41778e3e3a7aSWarner Losh(usually a 64-bit two-complement integer), 41788e3e3a7aSWarner Loshbut that can be changed to <code>long</code> or <code>int</code> 41798e3e3a7aSWarner Losh(usually a 32-bit two-complement integer). 41808e3e3a7aSWarner Losh(See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.) 41818e3e3a7aSWarner Losh 41828e3e3a7aSWarner Losh 41838e3e3a7aSWarner Losh<p> 41848e3e3a7aSWarner LoshLua also defines the constants 41858e3e3a7aSWarner Losh<a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>, 41868e3e3a7aSWarner Loshwith the minimum and the maximum values that fit in this type. 41878e3e3a7aSWarner Losh 41888e3e3a7aSWarner Losh 41898e3e3a7aSWarner Losh 41908e3e3a7aSWarner Losh 41918e3e3a7aSWarner Losh 41928e3e3a7aSWarner Losh<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> 41938e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 41948e3e3a7aSWarner Losh<pre>int lua_isboolean (lua_State *L, int index);</pre> 41958e3e3a7aSWarner Losh 41968e3e3a7aSWarner Losh<p> 41978e3e3a7aSWarner LoshReturns 1 if the value at the given index is a boolean, 41988e3e3a7aSWarner Loshand 0 otherwise. 41998e3e3a7aSWarner Losh 42008e3e3a7aSWarner Losh 42018e3e3a7aSWarner Losh 42028e3e3a7aSWarner Losh 42038e3e3a7aSWarner Losh 42048e3e3a7aSWarner Losh<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> 42058e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 42068e3e3a7aSWarner Losh<pre>int lua_iscfunction (lua_State *L, int index);</pre> 42078e3e3a7aSWarner Losh 42088e3e3a7aSWarner Losh<p> 42098e3e3a7aSWarner LoshReturns 1 if the value at the given index is a C function, 42108e3e3a7aSWarner Loshand 0 otherwise. 42118e3e3a7aSWarner Losh 42128e3e3a7aSWarner Losh 42138e3e3a7aSWarner Losh 42148e3e3a7aSWarner Losh 42158e3e3a7aSWarner Losh 42168e3e3a7aSWarner Losh<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> 42178e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 42188e3e3a7aSWarner Losh<pre>int lua_isfunction (lua_State *L, int index);</pre> 42198e3e3a7aSWarner Losh 42208e3e3a7aSWarner Losh<p> 42218e3e3a7aSWarner LoshReturns 1 if the value at the given index is a function 42228e3e3a7aSWarner Losh(either C or Lua), and 0 otherwise. 42238e3e3a7aSWarner Losh 42248e3e3a7aSWarner Losh 42258e3e3a7aSWarner Losh 42268e3e3a7aSWarner Losh 42278e3e3a7aSWarner Losh 42288e3e3a7aSWarner Losh<hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p> 42298e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 42308e3e3a7aSWarner Losh<pre>int lua_isinteger (lua_State *L, int index);</pre> 42318e3e3a7aSWarner Losh 42328e3e3a7aSWarner Losh<p> 42338e3e3a7aSWarner LoshReturns 1 if the value at the given index is an integer 42348e3e3a7aSWarner Losh(that is, the value is a number and is represented as an integer), 42358e3e3a7aSWarner Loshand 0 otherwise. 42368e3e3a7aSWarner Losh 42378e3e3a7aSWarner Losh 42388e3e3a7aSWarner Losh 42398e3e3a7aSWarner Losh 42408e3e3a7aSWarner Losh 42418e3e3a7aSWarner Losh<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> 42428e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 42438e3e3a7aSWarner Losh<pre>int lua_islightuserdata (lua_State *L, int index);</pre> 42448e3e3a7aSWarner Losh 42458e3e3a7aSWarner Losh<p> 42468e3e3a7aSWarner LoshReturns 1 if the value at the given index is a light userdata, 42478e3e3a7aSWarner Loshand 0 otherwise. 42488e3e3a7aSWarner Losh 42498e3e3a7aSWarner Losh 42508e3e3a7aSWarner Losh 42518e3e3a7aSWarner Losh 42528e3e3a7aSWarner Losh 42538e3e3a7aSWarner Losh<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> 42548e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 42558e3e3a7aSWarner Losh<pre>int lua_isnil (lua_State *L, int index);</pre> 42568e3e3a7aSWarner Losh 42578e3e3a7aSWarner Losh<p> 42588e3e3a7aSWarner LoshReturns 1 if the value at the given index is <b>nil</b>, 42598e3e3a7aSWarner Loshand 0 otherwise. 42608e3e3a7aSWarner Losh 42618e3e3a7aSWarner Losh 42628e3e3a7aSWarner Losh 42638e3e3a7aSWarner Losh 42648e3e3a7aSWarner Losh 42658e3e3a7aSWarner Losh<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> 42668e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 42678e3e3a7aSWarner Losh<pre>int lua_isnone (lua_State *L, int index);</pre> 42688e3e3a7aSWarner Losh 42698e3e3a7aSWarner Losh<p> 42708e3e3a7aSWarner LoshReturns 1 if the given index is not valid, 42718e3e3a7aSWarner Loshand 0 otherwise. 42728e3e3a7aSWarner Losh 42738e3e3a7aSWarner Losh 42748e3e3a7aSWarner Losh 42758e3e3a7aSWarner Losh 42768e3e3a7aSWarner Losh 42778e3e3a7aSWarner Losh<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> 42788e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 42798e3e3a7aSWarner Losh<pre>int lua_isnoneornil (lua_State *L, int index);</pre> 42808e3e3a7aSWarner Losh 42818e3e3a7aSWarner Losh<p> 42828e3e3a7aSWarner LoshReturns 1 if the given index is not valid 42838e3e3a7aSWarner Loshor if the value at this index is <b>nil</b>, 42848e3e3a7aSWarner Loshand 0 otherwise. 42858e3e3a7aSWarner Losh 42868e3e3a7aSWarner Losh 42878e3e3a7aSWarner Losh 42888e3e3a7aSWarner Losh 42898e3e3a7aSWarner Losh 42908e3e3a7aSWarner Losh<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> 42918e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 42928e3e3a7aSWarner Losh<pre>int lua_isnumber (lua_State *L, int index);</pre> 42938e3e3a7aSWarner Losh 42948e3e3a7aSWarner Losh<p> 42958e3e3a7aSWarner LoshReturns 1 if the value at the given index is a number 42968e3e3a7aSWarner Loshor a string convertible to a number, 42978e3e3a7aSWarner Loshand 0 otherwise. 42988e3e3a7aSWarner Losh 42998e3e3a7aSWarner Losh 43008e3e3a7aSWarner Losh 43018e3e3a7aSWarner Losh 43028e3e3a7aSWarner Losh 43038e3e3a7aSWarner Losh<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> 43048e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 43058e3e3a7aSWarner Losh<pre>int lua_isstring (lua_State *L, int index);</pre> 43068e3e3a7aSWarner Losh 43078e3e3a7aSWarner Losh<p> 43088e3e3a7aSWarner LoshReturns 1 if the value at the given index is a string 43098e3e3a7aSWarner Loshor a number (which is always convertible to a string), 43108e3e3a7aSWarner Loshand 0 otherwise. 43118e3e3a7aSWarner Losh 43128e3e3a7aSWarner Losh 43138e3e3a7aSWarner Losh 43148e3e3a7aSWarner Losh 43158e3e3a7aSWarner Losh 43168e3e3a7aSWarner Losh<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> 43178e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 43188e3e3a7aSWarner Losh<pre>int lua_istable (lua_State *L, int index);</pre> 43198e3e3a7aSWarner Losh 43208e3e3a7aSWarner Losh<p> 43218e3e3a7aSWarner LoshReturns 1 if the value at the given index is a table, 43228e3e3a7aSWarner Loshand 0 otherwise. 43238e3e3a7aSWarner Losh 43248e3e3a7aSWarner Losh 43258e3e3a7aSWarner Losh 43268e3e3a7aSWarner Losh 43278e3e3a7aSWarner Losh 43288e3e3a7aSWarner Losh<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> 43298e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 43308e3e3a7aSWarner Losh<pre>int lua_isthread (lua_State *L, int index);</pre> 43318e3e3a7aSWarner Losh 43328e3e3a7aSWarner Losh<p> 43338e3e3a7aSWarner LoshReturns 1 if the value at the given index is a thread, 43348e3e3a7aSWarner Loshand 0 otherwise. 43358e3e3a7aSWarner Losh 43368e3e3a7aSWarner Losh 43378e3e3a7aSWarner Losh 43388e3e3a7aSWarner Losh 43398e3e3a7aSWarner Losh 43408e3e3a7aSWarner Losh<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> 43418e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 43428e3e3a7aSWarner Losh<pre>int lua_isuserdata (lua_State *L, int index);</pre> 43438e3e3a7aSWarner Losh 43448e3e3a7aSWarner Losh<p> 43458e3e3a7aSWarner LoshReturns 1 if the value at the given index is a userdata 43468e3e3a7aSWarner Losh(either full or light), and 0 otherwise. 43478e3e3a7aSWarner Losh 43488e3e3a7aSWarner Losh 43498e3e3a7aSWarner Losh 43508e3e3a7aSWarner Losh 43518e3e3a7aSWarner Losh 43528e3e3a7aSWarner Losh<hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p> 43538e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 43548e3e3a7aSWarner Losh<pre>int lua_isyieldable (lua_State *L);</pre> 43558e3e3a7aSWarner Losh 43568e3e3a7aSWarner Losh<p> 43578e3e3a7aSWarner LoshReturns 1 if the given coroutine can yield, 43588e3e3a7aSWarner Loshand 0 otherwise. 43598e3e3a7aSWarner Losh 43608e3e3a7aSWarner Losh 43618e3e3a7aSWarner Losh 43628e3e3a7aSWarner Losh 43638e3e3a7aSWarner Losh 43648e3e3a7aSWarner Losh<hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3> 43658e3e3a7aSWarner Losh<pre>typedef ... lua_KContext;</pre> 43668e3e3a7aSWarner Losh 43678e3e3a7aSWarner Losh<p> 43688e3e3a7aSWarner LoshThe type for continuation-function contexts. 43698e3e3a7aSWarner LoshIt must be a numeric type. 43708e3e3a7aSWarner LoshThis type is defined as <code>intptr_t</code> 43718e3e3a7aSWarner Loshwhen <code>intptr_t</code> is available, 43728e3e3a7aSWarner Loshso that it can store pointers too. 43738e3e3a7aSWarner LoshOtherwise, it is defined as <code>ptrdiff_t</code>. 43748e3e3a7aSWarner Losh 43758e3e3a7aSWarner Losh 43768e3e3a7aSWarner Losh 43778e3e3a7aSWarner Losh 43788e3e3a7aSWarner Losh 43798e3e3a7aSWarner Losh<hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3> 43808e3e3a7aSWarner Losh<pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre> 43818e3e3a7aSWarner Losh 43828e3e3a7aSWarner Losh<p> 43830495ed39SKyle EvansType for continuation functions (see <a href="#4.5">§4.5</a>). 43848e3e3a7aSWarner Losh 43858e3e3a7aSWarner Losh 43868e3e3a7aSWarner Losh 43878e3e3a7aSWarner Losh 43888e3e3a7aSWarner Losh 43898e3e3a7aSWarner Losh<hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p> 43908e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 43918e3e3a7aSWarner Losh<pre>void lua_len (lua_State *L, int index);</pre> 43928e3e3a7aSWarner Losh 43938e3e3a7aSWarner Losh<p> 43948e3e3a7aSWarner LoshReturns the length of the value at the given index. 43958e3e3a7aSWarner LoshIt is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>) and 43968e3e3a7aSWarner Loshmay trigger a metamethod for the "length" event (see <a href="#2.4">§2.4</a>). 43978e3e3a7aSWarner LoshThe result is pushed on the stack. 43988e3e3a7aSWarner Losh 43998e3e3a7aSWarner Losh 44008e3e3a7aSWarner Losh 44018e3e3a7aSWarner Losh 44028e3e3a7aSWarner Losh 44038e3e3a7aSWarner Losh<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> 44048e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 44058e3e3a7aSWarner Losh<pre>int lua_load (lua_State *L, 44068e3e3a7aSWarner Losh lua_Reader reader, 44078e3e3a7aSWarner Losh void *data, 44088e3e3a7aSWarner Losh const char *chunkname, 44098e3e3a7aSWarner Losh const char *mode);</pre> 44108e3e3a7aSWarner Losh 44118e3e3a7aSWarner Losh<p> 44128e3e3a7aSWarner LoshLoads a Lua chunk without running it. 44138e3e3a7aSWarner LoshIf there are no errors, 44148e3e3a7aSWarner Losh<code>lua_load</code> pushes the compiled chunk as a Lua 44158e3e3a7aSWarner Loshfunction on top of the stack. 44168e3e3a7aSWarner LoshOtherwise, it pushes an error message. 44178e3e3a7aSWarner Losh 44188e3e3a7aSWarner Losh 44198e3e3a7aSWarner Losh<p> 44208e3e3a7aSWarner LoshThe <code>lua_load</code> function uses a user-supplied <code>reader</code> function 44218e3e3a7aSWarner Loshto read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). 44228e3e3a7aSWarner LoshThe <code>data</code> argument is an opaque value passed to the reader function. 44238e3e3a7aSWarner Losh 44248e3e3a7aSWarner Losh 44258e3e3a7aSWarner Losh<p> 44268e3e3a7aSWarner LoshThe <code>chunkname</code> argument gives a name to the chunk, 44270495ed39SKyle Evanswhich is used for error messages and in debug information (see <a href="#4.7">§4.7</a>). 44288e3e3a7aSWarner Losh 44298e3e3a7aSWarner Losh 44308e3e3a7aSWarner Losh<p> 44318e3e3a7aSWarner Losh<code>lua_load</code> automatically detects whether the chunk is text or binary 44328e3e3a7aSWarner Loshand loads it accordingly (see program <code>luac</code>). 44338e3e3a7aSWarner LoshThe string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>, 44348e3e3a7aSWarner Loshwith the addition that 44358e3e3a7aSWarner Losha <code>NULL</code> value is equivalent to the string "<code>bt</code>". 44368e3e3a7aSWarner Losh 44378e3e3a7aSWarner Losh 44388e3e3a7aSWarner Losh<p> 44398e3e3a7aSWarner Losh<code>lua_load</code> uses the stack internally, 44408e3e3a7aSWarner Loshso the reader function must always leave the stack 44418e3e3a7aSWarner Loshunmodified when returning. 44428e3e3a7aSWarner Losh 44438e3e3a7aSWarner Losh 44448e3e3a7aSWarner Losh<p> 44450495ed39SKyle Evans<code>lua_load</code> can return 44460495ed39SKyle 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>. 44470495ed39SKyle EvansThe function may also return other values corresponding to 44480495ed39SKyle Evanserrors raised by the read function (see <a href="#4.4.1">§4.4.1</a>). 44490495ed39SKyle Evans 44500495ed39SKyle Evans 44510495ed39SKyle Evans<p> 44528e3e3a7aSWarner LoshIf the resulting function has upvalues, 44538e3e3a7aSWarner Loshits first upvalue is set to the value of the global environment 44540495ed39SKyle Evansstored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.3">§4.3</a>). 44558e3e3a7aSWarner LoshWhen loading main chunks, 44568e3e3a7aSWarner Loshthis upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 44578e3e3a7aSWarner LoshOther upvalues are initialized with <b>nil</b>. 44588e3e3a7aSWarner Losh 44598e3e3a7aSWarner Losh 44608e3e3a7aSWarner Losh 44618e3e3a7aSWarner Losh 44628e3e3a7aSWarner Losh 44638e3e3a7aSWarner Losh<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> 44648e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 44658e3e3a7aSWarner Losh<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> 44668e3e3a7aSWarner Losh 44678e3e3a7aSWarner Losh<p> 44680495ed39SKyle EvansCreates a new independent state and returns its main thread. 44690495ed39SKyle EvansReturns <code>NULL</code> if it cannot create the state 44708e3e3a7aSWarner Losh(due to lack of memory). 44718e3e3a7aSWarner LoshThe argument <code>f</code> is the allocator function; 44720495ed39SKyle EvansLua will do all memory allocation for this state 44738e3e3a7aSWarner Loshthrough this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>). 44748e3e3a7aSWarner LoshThe second argument, <code>ud</code>, is an opaque pointer that Lua 44758e3e3a7aSWarner Loshpasses to the allocator in every call. 44768e3e3a7aSWarner Losh 44778e3e3a7aSWarner Losh 44788e3e3a7aSWarner Losh 44798e3e3a7aSWarner Losh 44808e3e3a7aSWarner Losh 44818e3e3a7aSWarner Losh<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> 44828e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 44838e3e3a7aSWarner Losh<pre>void lua_newtable (lua_State *L);</pre> 44848e3e3a7aSWarner Losh 44858e3e3a7aSWarner Losh<p> 44868e3e3a7aSWarner LoshCreates a new empty table and pushes it onto the stack. 44878e3e3a7aSWarner LoshIt is equivalent to <code>lua_createtable(L, 0, 0)</code>. 44888e3e3a7aSWarner Losh 44898e3e3a7aSWarner Losh 44908e3e3a7aSWarner Losh 44918e3e3a7aSWarner Losh 44928e3e3a7aSWarner Losh 44938e3e3a7aSWarner Losh<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> 44948e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 44958e3e3a7aSWarner Losh<pre>lua_State *lua_newthread (lua_State *L);</pre> 44968e3e3a7aSWarner Losh 44978e3e3a7aSWarner Losh<p> 44988e3e3a7aSWarner LoshCreates a new thread, pushes it on the stack, 44998e3e3a7aSWarner Loshand returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. 45008e3e3a7aSWarner LoshThe new thread returned by this function shares with the original thread 45018e3e3a7aSWarner Loshits global environment, 45028e3e3a7aSWarner Loshbut has an independent execution stack. 45038e3e3a7aSWarner Losh 45048e3e3a7aSWarner Losh 45058e3e3a7aSWarner Losh<p> 45068e3e3a7aSWarner LoshThreads are subject to garbage collection, 45078e3e3a7aSWarner Loshlike any Lua object. 45088e3e3a7aSWarner Losh 45098e3e3a7aSWarner Losh 45108e3e3a7aSWarner Losh 45118e3e3a7aSWarner Losh 45128e3e3a7aSWarner Losh 45130495ed39SKyle Evans<hr><h3><a name="lua_newuserdatauv"><code>lua_newuserdatauv</code></a></h3><p> 45148e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 45150495ed39SKyle Evans<pre>void *lua_newuserdatauv (lua_State *L, size_t size, int nuvalue);</pre> 45168e3e3a7aSWarner Losh 45178e3e3a7aSWarner Losh<p> 45180495ed39SKyle EvansThis function creates and pushes on the stack a new full userdata, 45190495ed39SKyle Evanswith <code>nuvalue</code> associated Lua values, called <code>user values</code>, 45200495ed39SKyle Evansplus an associated block of raw memory with <code>size</code> bytes. 45210495ed39SKyle Evans(The user values can be set and read with the functions 45220495ed39SKyle Evans<a href="#lua_setiuservalue"><code>lua_setiuservalue</code></a> and <a href="#lua_getiuservalue"><code>lua_getiuservalue</code></a>.) 45230495ed39SKyle Evans 45240495ed39SKyle Evans 45250495ed39SKyle Evans<p> 45260495ed39SKyle EvansThe function returns the address of the block of memory. 45270495ed39SKyle EvansLua ensures that this address is valid as long as 45280495ed39SKyle Evansthe corresponding userdata is alive (see <a href="#2.5">§2.5</a>). 45290495ed39SKyle EvansMoreover, if the userdata is marked for finalization (see <a href="#2.5.3">§2.5.3</a>), 45300495ed39SKyle Evansits address is valid at least until the call to its finalizer. 45318e3e3a7aSWarner Losh 45328e3e3a7aSWarner Losh 45338e3e3a7aSWarner Losh 45348e3e3a7aSWarner Losh 45358e3e3a7aSWarner Losh 45368e3e3a7aSWarner Losh<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> 45370495ed39SKyle Evans<span class="apii">[-1, +(2|0), <em>v</em>]</span> 45388e3e3a7aSWarner Losh<pre>int lua_next (lua_State *L, int index);</pre> 45398e3e3a7aSWarner Losh 45408e3e3a7aSWarner Losh<p> 45418e3e3a7aSWarner LoshPops a key from the stack, 45420495ed39SKyle Evansand pushes a key–value pair from the table at the given index, 45430495ed39SKyle Evansthe "next" pair after the given key. 45448e3e3a7aSWarner LoshIf there are no more elements in the table, 45450495ed39SKyle Evansthen <a href="#lua_next"><code>lua_next</code></a> returns 0 and pushes nothing. 45468e3e3a7aSWarner Losh 45478e3e3a7aSWarner Losh 45488e3e3a7aSWarner Losh<p> 45490495ed39SKyle EvansA typical table traversal looks like this: 45508e3e3a7aSWarner Losh 45518e3e3a7aSWarner Losh<pre> 45528e3e3a7aSWarner Losh /* table is in the stack at index 't' */ 45538e3e3a7aSWarner Losh lua_pushnil(L); /* first key */ 45548e3e3a7aSWarner Losh while (lua_next(L, t) != 0) { 45558e3e3a7aSWarner Losh /* uses 'key' (at index -2) and 'value' (at index -1) */ 45568e3e3a7aSWarner Losh printf("%s - %s\n", 45578e3e3a7aSWarner Losh lua_typename(L, lua_type(L, -2)), 45588e3e3a7aSWarner Losh lua_typename(L, lua_type(L, -1))); 45598e3e3a7aSWarner Losh /* removes 'value'; keeps 'key' for next iteration */ 45608e3e3a7aSWarner Losh lua_pop(L, 1); 45618e3e3a7aSWarner Losh } 45628e3e3a7aSWarner Losh</pre> 45638e3e3a7aSWarner Losh 45648e3e3a7aSWarner Losh<p> 45658e3e3a7aSWarner LoshWhile traversing a table, 45660495ed39SKyle Evansavoid calling <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, 45678e3e3a7aSWarner Loshunless you know that the key is actually a string. 45688e3e3a7aSWarner LoshRecall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change 45698e3e3a7aSWarner Loshthe value at the given index; 45708e3e3a7aSWarner Loshthis confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. 45718e3e3a7aSWarner Losh 45728e3e3a7aSWarner Losh 45738e3e3a7aSWarner Losh<p> 45740495ed39SKyle EvansThis function may raise an error if the given key 45750495ed39SKyle Evansis neither <b>nil</b> nor present in the table. 45768e3e3a7aSWarner LoshSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 45778e3e3a7aSWarner Loshthe table during its traversal. 45788e3e3a7aSWarner Losh 45798e3e3a7aSWarner Losh 45808e3e3a7aSWarner Losh 45818e3e3a7aSWarner Losh 45828e3e3a7aSWarner Losh 45838e3e3a7aSWarner Losh<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> 45848e3e3a7aSWarner Losh<pre>typedef ... lua_Number;</pre> 45858e3e3a7aSWarner Losh 45868e3e3a7aSWarner Losh<p> 45878e3e3a7aSWarner LoshThe type of floats in Lua. 45888e3e3a7aSWarner Losh 45898e3e3a7aSWarner Losh 45908e3e3a7aSWarner Losh<p> 45918e3e3a7aSWarner LoshBy default this type is double, 45928e3e3a7aSWarner Loshbut that can be changed to a single float or a long double. 45938e3e3a7aSWarner Losh(See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.) 45948e3e3a7aSWarner Losh 45958e3e3a7aSWarner Losh 45968e3e3a7aSWarner Losh 45978e3e3a7aSWarner Losh 45988e3e3a7aSWarner Losh 45998e3e3a7aSWarner Losh<hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3> 46008e3e3a7aSWarner Losh<pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre> 46018e3e3a7aSWarner Losh 46028e3e3a7aSWarner Losh<p> 46030495ed39SKyle EvansTries to convert a Lua float to a Lua integer; 46040495ed39SKyle Evansthe float <code>n</code> must have an integral value. 46058e3e3a7aSWarner LoshIf that value is within the range of Lua integers, 46068e3e3a7aSWarner Loshit is converted to an integer and assigned to <code>*p</code>. 46078e3e3a7aSWarner LoshThe macro results in a boolean indicating whether the 46088e3e3a7aSWarner Loshconversion was successful. 46098e3e3a7aSWarner Losh(Note that this range test can be tricky to do 46100495ed39SKyle Evanscorrectly without this macro, due to rounding.) 46118e3e3a7aSWarner Losh 46128e3e3a7aSWarner Losh 46138e3e3a7aSWarner Losh<p> 46148e3e3a7aSWarner LoshThis macro may evaluate its arguments more than once. 46158e3e3a7aSWarner Losh 46168e3e3a7aSWarner Losh 46178e3e3a7aSWarner Losh 46188e3e3a7aSWarner Losh 46198e3e3a7aSWarner Losh 46208e3e3a7aSWarner Losh<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> 46218e3e3a7aSWarner Losh<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 46228e3e3a7aSWarner Losh<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre> 46238e3e3a7aSWarner Losh 46248e3e3a7aSWarner Losh<p> 46250495ed39SKyle EvansCalls a function (or a callable object) in protected mode. 46268e3e3a7aSWarner Losh 46278e3e3a7aSWarner Losh 46288e3e3a7aSWarner Losh<p> 46298e3e3a7aSWarner LoshBoth <code>nargs</code> and <code>nresults</code> have the same meaning as 46308e3e3a7aSWarner Loshin <a href="#lua_call"><code>lua_call</code></a>. 46318e3e3a7aSWarner LoshIf there are no errors during the call, 46328e3e3a7aSWarner Losh<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. 46338e3e3a7aSWarner LoshHowever, if there is any error, 46348e3e3a7aSWarner Losh<a href="#lua_pcall"><code>lua_pcall</code></a> catches it, 46358e3e3a7aSWarner Loshpushes a single value on the stack (the error object), 46368e3e3a7aSWarner Loshand returns an error code. 46378e3e3a7aSWarner LoshLike <a href="#lua_call"><code>lua_call</code></a>, 46388e3e3a7aSWarner Losh<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function 46398e3e3a7aSWarner Loshand its arguments from the stack. 46408e3e3a7aSWarner Losh 46418e3e3a7aSWarner Losh 46428e3e3a7aSWarner Losh<p> 46438e3e3a7aSWarner LoshIf <code>msgh</code> is 0, 46448e3e3a7aSWarner Loshthen the error object returned on the stack 46458e3e3a7aSWarner Loshis exactly the original error object. 46468e3e3a7aSWarner LoshOtherwise, <code>msgh</code> is the stack index of a 46478e3e3a7aSWarner Losh<em>message handler</em>. 46488e3e3a7aSWarner Losh(This index cannot be a pseudo-index.) 46498e3e3a7aSWarner LoshIn case of runtime errors, 46500495ed39SKyle Evansthis handler will be called with the error object 46518e3e3a7aSWarner Loshand its return value will be the object 46528e3e3a7aSWarner Loshreturned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. 46538e3e3a7aSWarner Losh 46548e3e3a7aSWarner Losh 46558e3e3a7aSWarner Losh<p> 46568e3e3a7aSWarner LoshTypically, the message handler is used to add more debug 46578e3e3a7aSWarner Loshinformation to the error object, such as a stack traceback. 46588e3e3a7aSWarner LoshSuch information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, 46598e3e3a7aSWarner Loshsince by then the stack has unwound. 46608e3e3a7aSWarner Losh 46618e3e3a7aSWarner Losh 46628e3e3a7aSWarner Losh<p> 46630495ed39SKyle EvansThe <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following status codes: 46640495ed39SKyle 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>. 46658e3e3a7aSWarner Losh 46668e3e3a7aSWarner Losh 46678e3e3a7aSWarner Losh 46688e3e3a7aSWarner Losh 46698e3e3a7aSWarner Losh 46708e3e3a7aSWarner Losh<hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p> 46718e3e3a7aSWarner Losh<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 46728e3e3a7aSWarner Losh<pre>int lua_pcallk (lua_State *L, 46738e3e3a7aSWarner Losh int nargs, 46748e3e3a7aSWarner Losh int nresults, 46758e3e3a7aSWarner Losh int msgh, 46768e3e3a7aSWarner Losh lua_KContext ctx, 46778e3e3a7aSWarner Losh lua_KFunction k);</pre> 46788e3e3a7aSWarner Losh 46798e3e3a7aSWarner Losh<p> 46808e3e3a7aSWarner LoshThis function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>, 46810495ed39SKyle Evansexcept that it allows the called function to yield (see <a href="#4.5">§4.5</a>). 46828e3e3a7aSWarner Losh 46838e3e3a7aSWarner Losh 46848e3e3a7aSWarner Losh 46858e3e3a7aSWarner Losh 46868e3e3a7aSWarner Losh 46878e3e3a7aSWarner Losh<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> 46880495ed39SKyle Evans<span class="apii">[-n, +0, <em>e</em>]</span> 46898e3e3a7aSWarner Losh<pre>void lua_pop (lua_State *L, int n);</pre> 46908e3e3a7aSWarner Losh 46918e3e3a7aSWarner Losh<p> 46928e3e3a7aSWarner LoshPops <code>n</code> elements from the stack. 4693*8c784bb8SWarner LoshIt is implemented as a macro over <a href="#lua_settop"><code>lua_settop</code></a>. 46940495ed39SKyle Evans 46950495ed39SKyle Evans 46968e3e3a7aSWarner Losh 46978e3e3a7aSWarner Losh 46988e3e3a7aSWarner Losh 46998e3e3a7aSWarner Losh<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> 47008e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 47018e3e3a7aSWarner Losh<pre>void lua_pushboolean (lua_State *L, int b);</pre> 47028e3e3a7aSWarner Losh 47038e3e3a7aSWarner Losh<p> 47048e3e3a7aSWarner LoshPushes a boolean value with value <code>b</code> onto the stack. 47058e3e3a7aSWarner Losh 47068e3e3a7aSWarner Losh 47078e3e3a7aSWarner Losh 47088e3e3a7aSWarner Losh 47098e3e3a7aSWarner Losh 47108e3e3a7aSWarner Losh<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> 47118e3e3a7aSWarner Losh<span class="apii">[-n, +1, <em>m</em>]</span> 47128e3e3a7aSWarner Losh<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> 47138e3e3a7aSWarner Losh 47148e3e3a7aSWarner Losh<p> 47158e3e3a7aSWarner LoshPushes a new C closure onto the stack. 47160495ed39SKyle EvansThis function receives a pointer to a C function 47170495ed39SKyle Evansand pushes onto the stack a Lua value of type <code>function</code> that, 47180495ed39SKyle Evanswhen called, invokes the corresponding C function. 47190495ed39SKyle EvansThe parameter <code>n</code> tells how many upvalues this function will have 47200495ed39SKyle Evans(see <a href="#4.2">§4.2</a>). 47210495ed39SKyle Evans 47220495ed39SKyle Evans 47230495ed39SKyle Evans<p> 47240495ed39SKyle EvansAny function to be callable by Lua must 47250495ed39SKyle Evansfollow the correct protocol to receive its parameters 47260495ed39SKyle Evansand return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 47278e3e3a7aSWarner Losh 47288e3e3a7aSWarner Losh 47298e3e3a7aSWarner Losh<p> 47308e3e3a7aSWarner LoshWhen a C function is created, 47318e3e3a7aSWarner Loshit is possible to associate some values with it, 47320495ed39SKyle Evansthe so called upvalues; 47330495ed39SKyle Evansthese upvalues are then accessible to the function whenever it is called. 47340495ed39SKyle EvansThis association is called a C closure (see <a href="#4.2">§4.2</a>). 47350495ed39SKyle EvansTo create a C closure, 47360495ed39SKyle Evansfirst the initial values for its upvalues must be pushed onto the stack. 47370495ed39SKyle Evans(When there are multiple upvalues, the first value is pushed first.) 47388e3e3a7aSWarner LoshThen <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 47398e3e3a7aSWarner Loshis called to create and push the C function onto the stack, 47408e3e3a7aSWarner Loshwith the argument <code>n</code> telling how many values will be 47418e3e3a7aSWarner Loshassociated with the function. 47428e3e3a7aSWarner Losh<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. 47438e3e3a7aSWarner Losh 47448e3e3a7aSWarner Losh 47458e3e3a7aSWarner Losh<p> 47468e3e3a7aSWarner LoshThe maximum value for <code>n</code> is 255. 47478e3e3a7aSWarner Losh 47488e3e3a7aSWarner Losh 47498e3e3a7aSWarner Losh<p> 47508e3e3a7aSWarner LoshWhen <code>n</code> is zero, 47518e3e3a7aSWarner Loshthis function creates a <em>light C function</em>, 47528e3e3a7aSWarner Loshwhich is just a pointer to the C function. 47538e3e3a7aSWarner LoshIn that case, it never raises a memory error. 47548e3e3a7aSWarner Losh 47558e3e3a7aSWarner Losh 47568e3e3a7aSWarner Losh 47578e3e3a7aSWarner Losh 47588e3e3a7aSWarner Losh 47598e3e3a7aSWarner Losh<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> 47608e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 47618e3e3a7aSWarner Losh<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> 47628e3e3a7aSWarner Losh 47638e3e3a7aSWarner Losh<p> 47648e3e3a7aSWarner LoshPushes a C function onto the stack. 47650495ed39SKyle EvansThis function is equivalent to <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> with no upvalues. 47668e3e3a7aSWarner Losh 47678e3e3a7aSWarner Losh 47688e3e3a7aSWarner Losh 47698e3e3a7aSWarner Losh 47708e3e3a7aSWarner Losh 47718e3e3a7aSWarner Losh<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> 47720495ed39SKyle Evans<span class="apii">[-0, +1, <em>v</em>]</span> 47738e3e3a7aSWarner Losh<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> 47748e3e3a7aSWarner Losh 47758e3e3a7aSWarner Losh<p> 47768e3e3a7aSWarner LoshPushes onto the stack a formatted string 47770495ed39SKyle Evansand returns a pointer to this string (see <a href="#4.1.3">§4.1.3</a>). 47788e3e3a7aSWarner LoshIt is similar to the ISO C function <code>sprintf</code>, 47790495ed39SKyle Evansbut has two important differences. 47800495ed39SKyle EvansFirst, 47810495ed39SKyle Evansyou do not have to allocate space for the result; 47828e3e3a7aSWarner Loshthe result is a Lua string and Lua takes care of memory allocation 47838e3e3a7aSWarner Losh(and deallocation, through garbage collection). 47840495ed39SKyle EvansSecond, 47850495ed39SKyle Evansthe conversion specifiers are quite restricted. 47868e3e3a7aSWarner LoshThere are no flags, widths, or precisions. 47878e3e3a7aSWarner LoshThe conversion specifiers can only be 47888e3e3a7aSWarner Losh'<code>%%</code>' (inserts the character '<code>%</code>'), 47898e3e3a7aSWarner Losh'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), 47908e3e3a7aSWarner Losh'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), 47918e3e3a7aSWarner Losh'<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>), 47920495ed39SKyle Evans'<code>%p</code>' (inserts a pointer), 47938e3e3a7aSWarner Losh'<code>%d</code>' (inserts an <code>int</code>), 47948e3e3a7aSWarner Losh'<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and 47958e3e3a7aSWarner Losh'<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence). 47968e3e3a7aSWarner Losh 47978e3e3a7aSWarner Losh 47988e3e3a7aSWarner Losh<p> 47990495ed39SKyle EvansThis function may raise errors due to memory overflow 48000495ed39SKyle Evansor an invalid conversion specifier. 48018e3e3a7aSWarner Losh 48028e3e3a7aSWarner Losh 48038e3e3a7aSWarner Losh 48048e3e3a7aSWarner Losh 48058e3e3a7aSWarner Losh 48068e3e3a7aSWarner Losh<hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p> 48078e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 48088e3e3a7aSWarner Losh<pre>void lua_pushglobaltable (lua_State *L);</pre> 48098e3e3a7aSWarner Losh 48108e3e3a7aSWarner Losh<p> 48118e3e3a7aSWarner LoshPushes the global environment onto the stack. 48128e3e3a7aSWarner Losh 48138e3e3a7aSWarner Losh 48148e3e3a7aSWarner Losh 48158e3e3a7aSWarner Losh 48168e3e3a7aSWarner Losh 48178e3e3a7aSWarner Losh<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> 48188e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 48198e3e3a7aSWarner Losh<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> 48208e3e3a7aSWarner Losh 48218e3e3a7aSWarner Losh<p> 48228e3e3a7aSWarner LoshPushes an integer with value <code>n</code> onto the stack. 48238e3e3a7aSWarner Losh 48248e3e3a7aSWarner Losh 48258e3e3a7aSWarner Losh 48268e3e3a7aSWarner Losh 48278e3e3a7aSWarner Losh 48288e3e3a7aSWarner Losh<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> 48298e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 48308e3e3a7aSWarner Losh<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> 48318e3e3a7aSWarner Losh 48328e3e3a7aSWarner Losh<p> 48338e3e3a7aSWarner LoshPushes a light userdata onto the stack. 48348e3e3a7aSWarner Losh 48358e3e3a7aSWarner Losh 48368e3e3a7aSWarner Losh<p> 48378e3e3a7aSWarner LoshUserdata represent C values in Lua. 48388e3e3a7aSWarner LoshA <em>light userdata</em> represents a pointer, a <code>void*</code>. 48398e3e3a7aSWarner LoshIt is a value (like a number): 48408e3e3a7aSWarner Loshyou do not create it, it has no individual metatable, 48418e3e3a7aSWarner Loshand it is not collected (as it was never created). 48428e3e3a7aSWarner LoshA light userdata is equal to "any" 48438e3e3a7aSWarner Loshlight userdata with the same C address. 48448e3e3a7aSWarner Losh 48458e3e3a7aSWarner Losh 48468e3e3a7aSWarner Losh 48478e3e3a7aSWarner Losh 48488e3e3a7aSWarner Losh 48498e3e3a7aSWarner Losh<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> 48508e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 48518e3e3a7aSWarner Losh<pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre> 48528e3e3a7aSWarner Losh 48538e3e3a7aSWarner Losh<p> 48548e3e3a7aSWarner LoshThis macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>, 48558e3e3a7aSWarner Loshbut should be used only when <code>s</code> is a literal string. 48560495ed39SKyle Evans(Lua may optimize this case.) 48578e3e3a7aSWarner Losh 48588e3e3a7aSWarner Losh 48598e3e3a7aSWarner Losh 48608e3e3a7aSWarner Losh 48618e3e3a7aSWarner Losh 48628e3e3a7aSWarner Losh<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> 48638e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 48648e3e3a7aSWarner Losh<pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> 48658e3e3a7aSWarner Losh 48668e3e3a7aSWarner Losh<p> 48678e3e3a7aSWarner LoshPushes the string pointed to by <code>s</code> with size <code>len</code> 48688e3e3a7aSWarner Loshonto the stack. 48690495ed39SKyle EvansLua will make or reuse an internal copy of the given string, 48708e3e3a7aSWarner Loshso the memory at <code>s</code> can be freed or reused immediately after 48718e3e3a7aSWarner Loshthe function returns. 48728e3e3a7aSWarner LoshThe string can contain any binary data, 48738e3e3a7aSWarner Loshincluding embedded zeros. 48748e3e3a7aSWarner Losh 48758e3e3a7aSWarner Losh 48768e3e3a7aSWarner Losh<p> 48770495ed39SKyle EvansReturns a pointer to the internal copy of the string (see <a href="#4.1.3">§4.1.3</a>). 48788e3e3a7aSWarner Losh 48798e3e3a7aSWarner Losh 48808e3e3a7aSWarner Losh 48818e3e3a7aSWarner Losh 48828e3e3a7aSWarner Losh 48838e3e3a7aSWarner Losh<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> 48848e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 48858e3e3a7aSWarner Losh<pre>void lua_pushnil (lua_State *L);</pre> 48868e3e3a7aSWarner Losh 48878e3e3a7aSWarner Losh<p> 48888e3e3a7aSWarner LoshPushes a nil value onto the stack. 48898e3e3a7aSWarner Losh 48908e3e3a7aSWarner Losh 48918e3e3a7aSWarner Losh 48928e3e3a7aSWarner Losh 48938e3e3a7aSWarner Losh 48948e3e3a7aSWarner Losh<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> 48958e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 48968e3e3a7aSWarner Losh<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> 48978e3e3a7aSWarner Losh 48988e3e3a7aSWarner Losh<p> 48998e3e3a7aSWarner LoshPushes a float with value <code>n</code> onto the stack. 49008e3e3a7aSWarner Losh 49018e3e3a7aSWarner Losh 49028e3e3a7aSWarner Losh 49038e3e3a7aSWarner Losh 49048e3e3a7aSWarner Losh 49058e3e3a7aSWarner Losh<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> 49068e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 49078e3e3a7aSWarner Losh<pre>const char *lua_pushstring (lua_State *L, const char *s);</pre> 49088e3e3a7aSWarner Losh 49098e3e3a7aSWarner Losh<p> 49108e3e3a7aSWarner LoshPushes the zero-terminated string pointed to by <code>s</code> 49118e3e3a7aSWarner Loshonto the stack. 49120495ed39SKyle EvansLua will make or reuse an internal copy of the given string, 49138e3e3a7aSWarner Loshso the memory at <code>s</code> can be freed or reused immediately after 49148e3e3a7aSWarner Loshthe function returns. 49158e3e3a7aSWarner Losh 49168e3e3a7aSWarner Losh 49178e3e3a7aSWarner Losh<p> 49180495ed39SKyle EvansReturns a pointer to the internal copy of the string (see <a href="#4.1.3">§4.1.3</a>). 49198e3e3a7aSWarner Losh 49208e3e3a7aSWarner Losh 49218e3e3a7aSWarner Losh<p> 49228e3e3a7aSWarner LoshIf <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>. 49238e3e3a7aSWarner Losh 49248e3e3a7aSWarner Losh 49258e3e3a7aSWarner Losh 49268e3e3a7aSWarner Losh 49278e3e3a7aSWarner Losh 49288e3e3a7aSWarner Losh<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> 49298e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 49308e3e3a7aSWarner Losh<pre>int lua_pushthread (lua_State *L);</pre> 49318e3e3a7aSWarner Losh 49328e3e3a7aSWarner Losh<p> 49338e3e3a7aSWarner LoshPushes the thread represented by <code>L</code> onto the stack. 49348e3e3a7aSWarner LoshReturns 1 if this thread is the main thread of its state. 49358e3e3a7aSWarner Losh 49368e3e3a7aSWarner Losh 49378e3e3a7aSWarner Losh 49388e3e3a7aSWarner Losh 49398e3e3a7aSWarner Losh 49408e3e3a7aSWarner Losh<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> 49418e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 49428e3e3a7aSWarner Losh<pre>void lua_pushvalue (lua_State *L, int index);</pre> 49438e3e3a7aSWarner Losh 49448e3e3a7aSWarner Losh<p> 49458e3e3a7aSWarner LoshPushes a copy of the element at the given index 49468e3e3a7aSWarner Loshonto the stack. 49478e3e3a7aSWarner Losh 49488e3e3a7aSWarner Losh 49498e3e3a7aSWarner Losh 49508e3e3a7aSWarner Losh 49518e3e3a7aSWarner Losh 49528e3e3a7aSWarner Losh<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> 49530495ed39SKyle Evans<span class="apii">[-0, +1, <em>v</em>]</span> 49548e3e3a7aSWarner Losh<pre>const char *lua_pushvfstring (lua_State *L, 49558e3e3a7aSWarner Losh const char *fmt, 49568e3e3a7aSWarner Losh va_list argp);</pre> 49578e3e3a7aSWarner Losh 49588e3e3a7aSWarner Losh<p> 49598e3e3a7aSWarner LoshEquivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> 49608e3e3a7aSWarner Loshinstead of a variable number of arguments. 49618e3e3a7aSWarner Losh 49628e3e3a7aSWarner Losh 49638e3e3a7aSWarner Losh 49648e3e3a7aSWarner Losh 49658e3e3a7aSWarner Losh 49668e3e3a7aSWarner Losh<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> 49678e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 49688e3e3a7aSWarner Losh<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> 49698e3e3a7aSWarner Losh 49708e3e3a7aSWarner Losh<p> 49718e3e3a7aSWarner LoshReturns 1 if the two values in indices <code>index1</code> and 49728e3e3a7aSWarner Losh<code>index2</code> are primitively equal 49730495ed39SKyle Evans(that is, equal without calling the <code>__eq</code> metamethod). 49748e3e3a7aSWarner LoshOtherwise returns 0. 49758e3e3a7aSWarner LoshAlso returns 0 if any of the indices are not valid. 49768e3e3a7aSWarner Losh 49778e3e3a7aSWarner Losh 49788e3e3a7aSWarner Losh 49798e3e3a7aSWarner Losh 49808e3e3a7aSWarner Losh 49818e3e3a7aSWarner Losh<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> 49828e3e3a7aSWarner Losh<span class="apii">[-1, +1, –]</span> 49838e3e3a7aSWarner Losh<pre>int lua_rawget (lua_State *L, int index);</pre> 49848e3e3a7aSWarner Losh 49858e3e3a7aSWarner Losh<p> 49868e3e3a7aSWarner LoshSimilar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access 49878e3e3a7aSWarner Losh(i.e., without metamethods). 49888e3e3a7aSWarner Losh 49898e3e3a7aSWarner Losh 49908e3e3a7aSWarner Losh 49918e3e3a7aSWarner Losh 49928e3e3a7aSWarner Losh 49938e3e3a7aSWarner Losh<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> 49948e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 49958e3e3a7aSWarner Losh<pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre> 49968e3e3a7aSWarner Losh 49978e3e3a7aSWarner Losh<p> 49988e3e3a7aSWarner LoshPushes onto the stack the value <code>t[n]</code>, 49998e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index. 50008e3e3a7aSWarner LoshThe access is raw, 50010495ed39SKyle Evansthat is, it does not use the <code>__index</code> metavalue. 50028e3e3a7aSWarner Losh 50038e3e3a7aSWarner Losh 50048e3e3a7aSWarner Losh<p> 50058e3e3a7aSWarner LoshReturns the type of the pushed value. 50068e3e3a7aSWarner Losh 50078e3e3a7aSWarner Losh 50088e3e3a7aSWarner Losh 50098e3e3a7aSWarner Losh 50108e3e3a7aSWarner Losh 50118e3e3a7aSWarner Losh<hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p> 50128e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 50138e3e3a7aSWarner Losh<pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre> 50148e3e3a7aSWarner Losh 50158e3e3a7aSWarner Losh<p> 50168e3e3a7aSWarner LoshPushes onto the stack the value <code>t[k]</code>, 50178e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index and 50188e3e3a7aSWarner Losh<code>k</code> is the pointer <code>p</code> represented as a light userdata. 50198e3e3a7aSWarner LoshThe access is raw; 50200495ed39SKyle Evansthat is, it does not use the <code>__index</code> metavalue. 50218e3e3a7aSWarner Losh 50228e3e3a7aSWarner Losh 50238e3e3a7aSWarner Losh<p> 50248e3e3a7aSWarner LoshReturns the type of the pushed value. 50258e3e3a7aSWarner Losh 50268e3e3a7aSWarner Losh 50278e3e3a7aSWarner Losh 50288e3e3a7aSWarner Losh 50298e3e3a7aSWarner Losh 50308e3e3a7aSWarner Losh<hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p> 50318e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 50320495ed39SKyle Evans<pre>lua_Unsigned lua_rawlen (lua_State *L, int index);</pre> 50338e3e3a7aSWarner Losh 50348e3e3a7aSWarner Losh<p> 50358e3e3a7aSWarner LoshReturns the raw "length" of the value at the given index: 50368e3e3a7aSWarner Loshfor strings, this is the string length; 50378e3e3a7aSWarner Loshfor tables, this is the result of the length operator ('<code>#</code>') 50388e3e3a7aSWarner Loshwith no metamethods; 50398e3e3a7aSWarner Loshfor userdata, this is the size of the block of memory allocated 50400495ed39SKyle Evansfor the userdata. 50410495ed39SKyle EvansFor other values, this call returns 0. 50428e3e3a7aSWarner Losh 50438e3e3a7aSWarner Losh 50448e3e3a7aSWarner Losh 50458e3e3a7aSWarner Losh 50468e3e3a7aSWarner Losh 50478e3e3a7aSWarner Losh<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> 50488e3e3a7aSWarner Losh<span class="apii">[-2, +0, <em>m</em>]</span> 50498e3e3a7aSWarner Losh<pre>void lua_rawset (lua_State *L, int index);</pre> 50508e3e3a7aSWarner Losh 50518e3e3a7aSWarner Losh<p> 50528e3e3a7aSWarner LoshSimilar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment 50538e3e3a7aSWarner Losh(i.e., without metamethods). 50548e3e3a7aSWarner Losh 50558e3e3a7aSWarner Losh 50568e3e3a7aSWarner Losh 50578e3e3a7aSWarner Losh 50588e3e3a7aSWarner Losh 50598e3e3a7aSWarner Losh<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> 50608e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span> 50618e3e3a7aSWarner Losh<pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre> 50628e3e3a7aSWarner Losh 50638e3e3a7aSWarner Losh<p> 50648e3e3a7aSWarner LoshDoes the equivalent of <code>t[i] = v</code>, 50658e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index 50660495ed39SKyle Evansand <code>v</code> is the value on the top of the stack. 50678e3e3a7aSWarner Losh 50688e3e3a7aSWarner Losh 50698e3e3a7aSWarner Losh<p> 50708e3e3a7aSWarner LoshThis function pops the value from the stack. 50718e3e3a7aSWarner LoshThe assignment is raw, 50720495ed39SKyle Evansthat is, it does not use the <code>__newindex</code> metavalue. 50738e3e3a7aSWarner Losh 50748e3e3a7aSWarner Losh 50758e3e3a7aSWarner Losh 50768e3e3a7aSWarner Losh 50778e3e3a7aSWarner Losh 50788e3e3a7aSWarner Losh<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p> 50798e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span> 50808e3e3a7aSWarner Losh<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre> 50818e3e3a7aSWarner Losh 50828e3e3a7aSWarner Losh<p> 50838e3e3a7aSWarner LoshDoes the equivalent of <code>t[p] = v</code>, 50848e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index, 50858e3e3a7aSWarner Losh<code>p</code> is encoded as a light userdata, 50860495ed39SKyle Evansand <code>v</code> is the value on the top of the stack. 50878e3e3a7aSWarner Losh 50888e3e3a7aSWarner Losh 50898e3e3a7aSWarner Losh<p> 50908e3e3a7aSWarner LoshThis function pops the value from the stack. 50918e3e3a7aSWarner LoshThe assignment is raw, 50920495ed39SKyle Evansthat is, it does not use the <code>__newindex</code> metavalue. 50938e3e3a7aSWarner Losh 50948e3e3a7aSWarner Losh 50958e3e3a7aSWarner Losh 50968e3e3a7aSWarner Losh 50978e3e3a7aSWarner Losh 50988e3e3a7aSWarner Losh<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> 50998e3e3a7aSWarner Losh<pre>typedef const char * (*lua_Reader) (lua_State *L, 51008e3e3a7aSWarner Losh void *data, 51018e3e3a7aSWarner Losh size_t *size);</pre> 51028e3e3a7aSWarner Losh 51038e3e3a7aSWarner Losh<p> 51048e3e3a7aSWarner LoshThe reader function used by <a href="#lua_load"><code>lua_load</code></a>. 51050495ed39SKyle EvansEvery time <a href="#lua_load"><code>lua_load</code></a> needs another piece of the chunk, 51060495ed39SKyle Evansit calls the reader, 51078e3e3a7aSWarner Loshpassing along its <code>data</code> parameter. 51088e3e3a7aSWarner LoshThe reader must return a pointer to a block of memory 51098e3e3a7aSWarner Loshwith a new piece of the chunk 51108e3e3a7aSWarner Loshand set <code>size</code> to the block size. 51118e3e3a7aSWarner LoshThe block must exist until the reader function is called again. 51128e3e3a7aSWarner LoshTo signal the end of the chunk, 51138e3e3a7aSWarner Loshthe reader must return <code>NULL</code> or set <code>size</code> to zero. 51148e3e3a7aSWarner LoshThe reader function may return pieces of any size greater than zero. 51158e3e3a7aSWarner Losh 51168e3e3a7aSWarner Losh 51178e3e3a7aSWarner Losh 51188e3e3a7aSWarner Losh 51198e3e3a7aSWarner Losh 51208e3e3a7aSWarner Losh<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> 51218e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 51228e3e3a7aSWarner Losh<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre> 51238e3e3a7aSWarner Losh 51248e3e3a7aSWarner Losh<p> 51258e3e3a7aSWarner LoshSets the C function <code>f</code> as the new value of global <code>name</code>. 51268e3e3a7aSWarner LoshIt is defined as a macro: 51278e3e3a7aSWarner Losh 51288e3e3a7aSWarner Losh<pre> 51298e3e3a7aSWarner Losh #define lua_register(L,n,f) \ 51308e3e3a7aSWarner Losh (lua_pushcfunction(L, f), lua_setglobal(L, n)) 51318e3e3a7aSWarner Losh</pre> 51328e3e3a7aSWarner Losh 51338e3e3a7aSWarner Losh 51348e3e3a7aSWarner Losh 51358e3e3a7aSWarner Losh 51368e3e3a7aSWarner Losh<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> 51378e3e3a7aSWarner Losh<span class="apii">[-1, +0, –]</span> 51388e3e3a7aSWarner Losh<pre>void lua_remove (lua_State *L, int index);</pre> 51398e3e3a7aSWarner Losh 51408e3e3a7aSWarner Losh<p> 51418e3e3a7aSWarner LoshRemoves the element at the given valid index, 51428e3e3a7aSWarner Loshshifting down the elements above this index to fill the gap. 51438e3e3a7aSWarner LoshThis function cannot be called with a pseudo-index, 51448e3e3a7aSWarner Loshbecause a pseudo-index is not an actual stack position. 51458e3e3a7aSWarner Losh 51468e3e3a7aSWarner Losh 51478e3e3a7aSWarner Losh 51488e3e3a7aSWarner Losh 51498e3e3a7aSWarner Losh 51508e3e3a7aSWarner Losh<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> 51518e3e3a7aSWarner Losh<span class="apii">[-1, +0, –]</span> 51528e3e3a7aSWarner Losh<pre>void lua_replace (lua_State *L, int index);</pre> 51538e3e3a7aSWarner Losh 51548e3e3a7aSWarner Losh<p> 51558e3e3a7aSWarner LoshMoves the top element into the given valid index 51568e3e3a7aSWarner Loshwithout shifting any element 51578e3e3a7aSWarner Losh(therefore replacing the value at that given index), 51588e3e3a7aSWarner Loshand then pops the top element. 51598e3e3a7aSWarner Losh 51608e3e3a7aSWarner Losh 51618e3e3a7aSWarner Losh 51628e3e3a7aSWarner Losh 51638e3e3a7aSWarner Losh 51640495ed39SKyle Evans<hr><h3><a name="lua_resetthread"><code>lua_resetthread</code></a></h3><p> 51650495ed39SKyle Evans<span class="apii">[-0, +?, –]</span> 51660495ed39SKyle Evans<pre>int lua_resetthread (lua_State *L);</pre> 51670495ed39SKyle Evans 51680495ed39SKyle Evans<p> 51690495ed39SKyle EvansResets a thread, cleaning its call stack and closing all pending 51700495ed39SKyle Evansto-be-closed variables. 51710495ed39SKyle EvansReturns a status code: 5172*8c784bb8SWarner Losh<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for no errors in the thread 5173*8c784bb8SWarner Losh(either the original error that stopped the thread or 5174*8c784bb8SWarner Losherrors in closing methods), 51750495ed39SKyle Evansor an error status otherwise. 51760495ed39SKyle EvansIn case of error, 5177*8c784bb8SWarner Loshleaves the error object on the top of the stack. 51780495ed39SKyle Evans 51790495ed39SKyle Evans 51800495ed39SKyle Evans 51810495ed39SKyle Evans 51820495ed39SKyle Evans 51838e3e3a7aSWarner Losh<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> 51848e3e3a7aSWarner Losh<span class="apii">[-?, +?, –]</span> 51850495ed39SKyle Evans<pre>int lua_resume (lua_State *L, lua_State *from, int nargs, 51860495ed39SKyle Evans int *nresults);</pre> 51878e3e3a7aSWarner Losh 51888e3e3a7aSWarner Losh<p> 51898e3e3a7aSWarner LoshStarts and resumes a coroutine in the given thread <code>L</code>. 51908e3e3a7aSWarner Losh 51918e3e3a7aSWarner Losh 51928e3e3a7aSWarner Losh<p> 51938e3e3a7aSWarner LoshTo start a coroutine, 51940495ed39SKyle Evansyou push the main function plus any arguments 51950495ed39SKyle Evansonto the empty stack of the thread. 51968e3e3a7aSWarner Loshthen you call <a href="#lua_resume"><code>lua_resume</code></a>, 51978e3e3a7aSWarner Loshwith <code>nargs</code> being the number of arguments. 51988e3e3a7aSWarner LoshThis call returns when the coroutine suspends or finishes its execution. 51990495ed39SKyle EvansWhen it returns, 52000495ed39SKyle Evans<code>*nresults</code> is updated and 52010495ed39SKyle Evansthe top of the stack contains 52020495ed39SKyle Evansthe <code>*nresults</code> values passed to <a href="#lua_yield"><code>lua_yield</code></a> 52030495ed39SKyle Evansor returned by the body function. 52048e3e3a7aSWarner Losh<a href="#lua_resume"><code>lua_resume</code></a> returns 52058e3e3a7aSWarner Losh<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, 52068e3e3a7aSWarner Losh<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution 52078e3e3a7aSWarner Loshwithout errors, 52080495ed39SKyle Evansor an error code in case of errors (see <a href="#4.4.1">§4.4.1</a>). 52098e3e3a7aSWarner LoshIn case of errors, 52100495ed39SKyle Evansthe error object is on the top of the stack. 52118e3e3a7aSWarner Losh 52128e3e3a7aSWarner Losh 52138e3e3a7aSWarner Losh<p> 52148e3e3a7aSWarner LoshTo resume a coroutine, 52150495ed39SKyle Evansyou remove the <code>*nresults</code> yielded values from its stack, 52160495ed39SKyle Evanspush the values to be passed as results from <code>yield</code>, 52178e3e3a7aSWarner Loshand then call <a href="#lua_resume"><code>lua_resume</code></a>. 52188e3e3a7aSWarner Losh 52198e3e3a7aSWarner Losh 52208e3e3a7aSWarner Losh<p> 52218e3e3a7aSWarner LoshThe parameter <code>from</code> represents the coroutine that is resuming <code>L</code>. 52228e3e3a7aSWarner LoshIf there is no such coroutine, 52238e3e3a7aSWarner Loshthis parameter can be <code>NULL</code>. 52248e3e3a7aSWarner Losh 52258e3e3a7aSWarner Losh 52268e3e3a7aSWarner Losh 52278e3e3a7aSWarner Losh 52288e3e3a7aSWarner Losh 52298e3e3a7aSWarner Losh<hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p> 52308e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 52318e3e3a7aSWarner Losh<pre>void lua_rotate (lua_State *L, int idx, int n);</pre> 52328e3e3a7aSWarner Losh 52338e3e3a7aSWarner Losh<p> 52348e3e3a7aSWarner LoshRotates the stack elements between the valid index <code>idx</code> 52358e3e3a7aSWarner Loshand the top of the stack. 52368e3e3a7aSWarner LoshThe elements are rotated <code>n</code> positions in the direction of the top, 52378e3e3a7aSWarner Loshfor a positive <code>n</code>, 52388e3e3a7aSWarner Loshor <code>-n</code> positions in the direction of the bottom, 52398e3e3a7aSWarner Loshfor a negative <code>n</code>. 52408e3e3a7aSWarner LoshThe absolute value of <code>n</code> must not be greater than the size 52418e3e3a7aSWarner Loshof the slice being rotated. 52428e3e3a7aSWarner LoshThis function cannot be called with a pseudo-index, 52438e3e3a7aSWarner Loshbecause a pseudo-index is not an actual stack position. 52448e3e3a7aSWarner Losh 52458e3e3a7aSWarner Losh 52468e3e3a7aSWarner Losh 52478e3e3a7aSWarner Losh 52488e3e3a7aSWarner Losh 52498e3e3a7aSWarner Losh<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> 52508e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 52518e3e3a7aSWarner Losh<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> 52528e3e3a7aSWarner Losh 52538e3e3a7aSWarner Losh<p> 52548e3e3a7aSWarner LoshChanges the allocator function of a given state to <code>f</code> 52558e3e3a7aSWarner Loshwith user data <code>ud</code>. 52568e3e3a7aSWarner Losh 52578e3e3a7aSWarner Losh 52588e3e3a7aSWarner Losh 52598e3e3a7aSWarner Losh 52608e3e3a7aSWarner Losh 52618e3e3a7aSWarner Losh<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> 52628e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>e</em>]</span> 52638e3e3a7aSWarner Losh<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> 52648e3e3a7aSWarner Losh 52658e3e3a7aSWarner Losh<p> 52668e3e3a7aSWarner LoshDoes the equivalent to <code>t[k] = v</code>, 52678e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index 52680495ed39SKyle Evansand <code>v</code> is the value on the top of the stack. 52698e3e3a7aSWarner Losh 52708e3e3a7aSWarner Losh 52718e3e3a7aSWarner Losh<p> 52728e3e3a7aSWarner LoshThis function pops the value from the stack. 52738e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 52748e3e3a7aSWarner Loshfor the "newindex" event (see <a href="#2.4">§2.4</a>). 52758e3e3a7aSWarner Losh 52768e3e3a7aSWarner Losh 52778e3e3a7aSWarner Losh 52788e3e3a7aSWarner Losh 52798e3e3a7aSWarner Losh 52808e3e3a7aSWarner Losh<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> 52818e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>e</em>]</span> 52828e3e3a7aSWarner Losh<pre>void lua_setglobal (lua_State *L, const char *name);</pre> 52838e3e3a7aSWarner Losh 52848e3e3a7aSWarner Losh<p> 52858e3e3a7aSWarner LoshPops a value from the stack and 52868e3e3a7aSWarner Loshsets it as the new value of global <code>name</code>. 52878e3e3a7aSWarner Losh 52888e3e3a7aSWarner Losh 52898e3e3a7aSWarner Losh 52908e3e3a7aSWarner Losh 52918e3e3a7aSWarner Losh 52928e3e3a7aSWarner Losh<hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p> 52938e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>e</em>]</span> 52948e3e3a7aSWarner Losh<pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre> 52958e3e3a7aSWarner Losh 52968e3e3a7aSWarner Losh<p> 52978e3e3a7aSWarner LoshDoes the equivalent to <code>t[n] = v</code>, 52988e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index 52990495ed39SKyle Evansand <code>v</code> is the value on the top of the stack. 53008e3e3a7aSWarner Losh 53018e3e3a7aSWarner Losh 53028e3e3a7aSWarner Losh<p> 53038e3e3a7aSWarner LoshThis function pops the value from the stack. 53048e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 53058e3e3a7aSWarner Loshfor the "newindex" event (see <a href="#2.4">§2.4</a>). 53068e3e3a7aSWarner Losh 53078e3e3a7aSWarner Losh 53088e3e3a7aSWarner Losh 53098e3e3a7aSWarner Losh 53108e3e3a7aSWarner Losh 53110495ed39SKyle Evans<hr><h3><a name="lua_setiuservalue"><code>lua_setiuservalue</code></a></h3><p> 53128e3e3a7aSWarner Losh<span class="apii">[-1, +0, –]</span> 53130495ed39SKyle Evans<pre>int lua_setiuservalue (lua_State *L, int index, int n);</pre> 53148e3e3a7aSWarner Losh 53158e3e3a7aSWarner Losh<p> 53160495ed39SKyle EvansPops a value from the stack and sets it as 53170495ed39SKyle Evansthe new <code>n</code>-th user value associated to the 53180495ed39SKyle Evansfull userdata at the given index. 53190495ed39SKyle EvansReturns 0 if the userdata does not have that value. 53200495ed39SKyle Evans 53210495ed39SKyle Evans 53220495ed39SKyle Evans 53230495ed39SKyle Evans 53240495ed39SKyle Evans 53250495ed39SKyle Evans<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> 53260495ed39SKyle Evans<span class="apii">[-1, +0, –]</span> 53270495ed39SKyle Evans<pre>int lua_setmetatable (lua_State *L, int index);</pre> 53280495ed39SKyle Evans 53290495ed39SKyle Evans<p> 53300495ed39SKyle EvansPops a table or <b>nil</b> from the stack and 53310495ed39SKyle Evanssets that value as the new metatable for the value at the given index. 53320495ed39SKyle Evans(<b>nil</b> means no metatable.) 53330495ed39SKyle Evans 53340495ed39SKyle Evans 53350495ed39SKyle Evans<p> 53360495ed39SKyle Evans(For historical reasons, this function returns an <code>int</code>, 53370495ed39SKyle Evanswhich now is always 1.) 53388e3e3a7aSWarner Losh 53398e3e3a7aSWarner Losh 53408e3e3a7aSWarner Losh 53418e3e3a7aSWarner Losh 53428e3e3a7aSWarner Losh 53438e3e3a7aSWarner Losh<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> 53448e3e3a7aSWarner Losh<span class="apii">[-2, +0, <em>e</em>]</span> 53458e3e3a7aSWarner Losh<pre>void lua_settable (lua_State *L, int index);</pre> 53468e3e3a7aSWarner Losh 53478e3e3a7aSWarner Losh<p> 53488e3e3a7aSWarner LoshDoes the equivalent to <code>t[k] = v</code>, 53498e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index, 53500495ed39SKyle Evans<code>v</code> is the value on the top of the stack, 53518e3e3a7aSWarner Loshand <code>k</code> is the value just below the top. 53528e3e3a7aSWarner Losh 53538e3e3a7aSWarner Losh 53548e3e3a7aSWarner Losh<p> 53558e3e3a7aSWarner LoshThis function pops both the key and the value from the stack. 53568e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod 53578e3e3a7aSWarner Loshfor the "newindex" event (see <a href="#2.4">§2.4</a>). 53588e3e3a7aSWarner Losh 53598e3e3a7aSWarner Losh 53608e3e3a7aSWarner Losh 53618e3e3a7aSWarner Losh 53628e3e3a7aSWarner Losh 53638e3e3a7aSWarner Losh<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> 53640495ed39SKyle Evans<span class="apii">[-?, +?, <em>e</em>]</span> 53658e3e3a7aSWarner Losh<pre>void lua_settop (lua_State *L, int index);</pre> 53668e3e3a7aSWarner Losh 53678e3e3a7aSWarner Losh<p> 53688e3e3a7aSWarner LoshAccepts any index, or 0, 53698e3e3a7aSWarner Loshand sets the stack top to this index. 53700495ed39SKyle EvansIf the new top is greater than the old one, 53718e3e3a7aSWarner Loshthen the new elements are filled with <b>nil</b>. 53728e3e3a7aSWarner LoshIf <code>index</code> is 0, then all stack elements are removed. 53738e3e3a7aSWarner Losh 53748e3e3a7aSWarner Losh 53750495ed39SKyle Evans<p> 53760495ed39SKyle EvansThis function can run arbitrary code when removing an index 53770495ed39SKyle Evansmarked as to-be-closed from the stack. 53788e3e3a7aSWarner Losh 53798e3e3a7aSWarner Losh 53808e3e3a7aSWarner Losh 53810495ed39SKyle Evans 53820495ed39SKyle Evans 53830495ed39SKyle Evans<hr><h3><a name="lua_setwarnf"><code>lua_setwarnf</code></a></h3><p> 53840495ed39SKyle Evans<span class="apii">[-0, +0, –]</span> 53850495ed39SKyle Evans<pre>void lua_setwarnf (lua_State *L, lua_WarnFunction f, void *ud);</pre> 53868e3e3a7aSWarner Losh 53878e3e3a7aSWarner Losh<p> 53880495ed39SKyle EvansSets the warning function to be used by Lua to emit warnings 53890495ed39SKyle Evans(see <a href="#lua_WarnFunction"><code>lua_WarnFunction</code></a>). 53900495ed39SKyle EvansThe <code>ud</code> parameter sets the value <code>ud</code> passed to 53910495ed39SKyle Evansthe warning function. 53928e3e3a7aSWarner Losh 53938e3e3a7aSWarner Losh 53948e3e3a7aSWarner Losh 53958e3e3a7aSWarner Losh 53968e3e3a7aSWarner Losh 53978e3e3a7aSWarner Losh<hr><h3><a name="lua_State"><code>lua_State</code></a></h3> 53988e3e3a7aSWarner Losh<pre>typedef struct lua_State lua_State;</pre> 53998e3e3a7aSWarner Losh 54008e3e3a7aSWarner Losh<p> 54018e3e3a7aSWarner LoshAn opaque structure that points to a thread and indirectly 54028e3e3a7aSWarner Losh(through the thread) to the whole state of a Lua interpreter. 54038e3e3a7aSWarner LoshThe Lua library is fully reentrant: 54048e3e3a7aSWarner Loshit has no global variables. 54058e3e3a7aSWarner LoshAll information about a state is accessible through this structure. 54068e3e3a7aSWarner Losh 54078e3e3a7aSWarner Losh 54088e3e3a7aSWarner Losh<p> 54098e3e3a7aSWarner LoshA pointer to this structure must be passed as the first argument to 54108e3e3a7aSWarner Loshevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 54118e3e3a7aSWarner Loshwhich creates a Lua state from scratch. 54128e3e3a7aSWarner Losh 54138e3e3a7aSWarner Losh 54148e3e3a7aSWarner Losh 54158e3e3a7aSWarner Losh 54168e3e3a7aSWarner Losh 54178e3e3a7aSWarner Losh<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> 54188e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 54198e3e3a7aSWarner Losh<pre>int lua_status (lua_State *L);</pre> 54208e3e3a7aSWarner Losh 54218e3e3a7aSWarner Losh<p> 54228e3e3a7aSWarner LoshReturns the status of the thread <code>L</code>. 54238e3e3a7aSWarner Losh 54248e3e3a7aSWarner Losh 54258e3e3a7aSWarner Losh<p> 54260495ed39SKyle EvansThe status can be <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for a normal thread, 54278e3e3a7aSWarner Loshan error code if the thread finished the execution 54288e3e3a7aSWarner Loshof a <a href="#lua_resume"><code>lua_resume</code></a> with an error, 54290495ed39SKyle Evansor <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. 54308e3e3a7aSWarner Losh 54318e3e3a7aSWarner Losh 54328e3e3a7aSWarner Losh<p> 54330495ed39SKyle EvansYou can call functions only in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>. 54348e3e3a7aSWarner LoshYou can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> 54358e3e3a7aSWarner Losh(to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> 54368e3e3a7aSWarner Losh(to resume a coroutine). 54378e3e3a7aSWarner Losh 54388e3e3a7aSWarner Losh 54398e3e3a7aSWarner Losh 54408e3e3a7aSWarner Losh 54418e3e3a7aSWarner Losh 54428e3e3a7aSWarner Losh<hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p> 54438e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 54448e3e3a7aSWarner Losh<pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre> 54458e3e3a7aSWarner Losh 54468e3e3a7aSWarner Losh<p> 54478e3e3a7aSWarner LoshConverts the zero-terminated string <code>s</code> to a number, 54488e3e3a7aSWarner Loshpushes that number into the stack, 54498e3e3a7aSWarner Loshand returns the total size of the string, 54508e3e3a7aSWarner Loshthat is, its length plus one. 54518e3e3a7aSWarner LoshThe conversion can result in an integer or a float, 54528e3e3a7aSWarner Loshaccording to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 54530495ed39SKyle EvansThe string may have leading and trailing whitespaces and a sign. 54548e3e3a7aSWarner LoshIf the string is not a valid numeral, 54558e3e3a7aSWarner Loshreturns 0 and pushes nothing. 54568e3e3a7aSWarner Losh(Note that the result can be used as a boolean, 54578e3e3a7aSWarner Loshtrue if the conversion succeeds.) 54588e3e3a7aSWarner Losh 54598e3e3a7aSWarner Losh 54608e3e3a7aSWarner Losh 54618e3e3a7aSWarner Losh 54628e3e3a7aSWarner Losh 54638e3e3a7aSWarner Losh<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> 54648e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 54658e3e3a7aSWarner Losh<pre>int lua_toboolean (lua_State *L, int index);</pre> 54668e3e3a7aSWarner Losh 54678e3e3a7aSWarner Losh<p> 54688e3e3a7aSWarner LoshConverts the Lua value at the given index to a C boolean 54698e3e3a7aSWarner Loshvalue (0 or 1). 54708e3e3a7aSWarner LoshLike all tests in Lua, 54718e3e3a7aSWarner Losh<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value 54728e3e3a7aSWarner Loshdifferent from <b>false</b> and <b>nil</b>; 54738e3e3a7aSWarner Loshotherwise it returns false. 54748e3e3a7aSWarner Losh(If you want to accept only actual boolean values, 54758e3e3a7aSWarner Loshuse <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) 54768e3e3a7aSWarner Losh 54778e3e3a7aSWarner Losh 54788e3e3a7aSWarner Losh 54798e3e3a7aSWarner Losh 54808e3e3a7aSWarner Losh 54818e3e3a7aSWarner Losh<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> 54828e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 54838e3e3a7aSWarner Losh<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> 54848e3e3a7aSWarner Losh 54858e3e3a7aSWarner Losh<p> 54868e3e3a7aSWarner LoshConverts a value at the given index to a C function. 54878e3e3a7aSWarner LoshThat value must be a C function; 54888e3e3a7aSWarner Loshotherwise, returns <code>NULL</code>. 54898e3e3a7aSWarner Losh 54908e3e3a7aSWarner Losh 54918e3e3a7aSWarner Losh 54928e3e3a7aSWarner Losh 54938e3e3a7aSWarner Losh 54940495ed39SKyle Evans<hr><h3><a name="lua_toclose"><code>lua_toclose</code></a></h3><p> 54950495ed39SKyle Evans<span class="apii">[-0, +0, <em>m</em>]</span> 54960495ed39SKyle Evans<pre>void lua_toclose (lua_State *L, int index);</pre> 54970495ed39SKyle Evans 54980495ed39SKyle Evans<p> 54990495ed39SKyle EvansMarks the given index in the stack as a 5500*8c784bb8SWarner Loshto-be-closed slot (see <a href="#3.3.8">§3.3.8</a>). 55010495ed39SKyle EvansLike a to-be-closed variable in Lua, 5502*8c784bb8SWarner Loshthe value at that slot in the stack will be closed 55030495ed39SKyle Evanswhen it goes out of scope. 55040495ed39SKyle EvansHere, in the context of a C function, 55050495ed39SKyle Evansto go out of scope means that the running function returns to Lua, 5506*8c784bb8SWarner Loshor there is an error, 5507*8c784bb8SWarner Loshor the slot is removed from the stack through 5508*8c784bb8SWarner Losh<a href="#lua_settop"><code>lua_settop</code></a> or <a href="#lua_pop"><code>lua_pop</code></a>, 5509*8c784bb8SWarner Loshor there is a call to <a href="#lua_closeslot"><code>lua_closeslot</code></a>. 5510*8c784bb8SWarner LoshA slot marked as to-be-closed should not be removed from the stack 5511*8c784bb8SWarner 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>, 5512*8c784bb8SWarner Loshunless previously deactivated by <a href="#lua_closeslot"><code>lua_closeslot</code></a>. 55130495ed39SKyle Evans 55140495ed39SKyle Evans 55150495ed39SKyle Evans<p> 55160495ed39SKyle EvansThis function should not be called for an index 5517*8c784bb8SWarner Loshthat is equal to or below an active to-be-closed slot. 55180495ed39SKyle Evans 55190495ed39SKyle Evans 55200495ed39SKyle Evans<p> 55210495ed39SKyle EvansNote that, both in case of errors and of a regular return, 55220495ed39SKyle Evansby the time the <code>__close</code> metamethod runs, 55230495ed39SKyle Evansthe C stack was already unwound, 55240495ed39SKyle Evansso that any automatic C variable declared in the calling function 5525*8c784bb8SWarner Losh(e.g., a buffer) will be out of scope. 55260495ed39SKyle Evans 55270495ed39SKyle Evans 55280495ed39SKyle Evans 55290495ed39SKyle Evans 55300495ed39SKyle Evans 55318e3e3a7aSWarner Losh<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> 55328e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 55338e3e3a7aSWarner Losh<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> 55348e3e3a7aSWarner Losh 55358e3e3a7aSWarner Losh<p> 55368e3e3a7aSWarner LoshEquivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 55378e3e3a7aSWarner Losh 55388e3e3a7aSWarner Losh 55398e3e3a7aSWarner Losh 55408e3e3a7aSWarner Losh 55418e3e3a7aSWarner Losh 55428e3e3a7aSWarner Losh<hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p> 55438e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 55448e3e3a7aSWarner Losh<pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre> 55458e3e3a7aSWarner Losh 55468e3e3a7aSWarner Losh<p> 55478e3e3a7aSWarner LoshConverts the Lua value at the given index 55488e3e3a7aSWarner Loshto the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. 55498e3e3a7aSWarner LoshThe Lua value must be an integer, 55508e3e3a7aSWarner Loshor a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>); 55518e3e3a7aSWarner Loshotherwise, <code>lua_tointegerx</code> returns 0. 55528e3e3a7aSWarner Losh 55538e3e3a7aSWarner Losh 55548e3e3a7aSWarner Losh<p> 55558e3e3a7aSWarner LoshIf <code>isnum</code> is not <code>NULL</code>, 55568e3e3a7aSWarner Loshits referent is assigned a boolean value that 55578e3e3a7aSWarner Loshindicates whether the operation succeeded. 55588e3e3a7aSWarner Losh 55598e3e3a7aSWarner Losh 55608e3e3a7aSWarner Losh 55618e3e3a7aSWarner Losh 55628e3e3a7aSWarner Losh 55638e3e3a7aSWarner Losh<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> 55648e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span> 55658e3e3a7aSWarner Losh<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> 55668e3e3a7aSWarner Losh 55678e3e3a7aSWarner Losh<p> 55688e3e3a7aSWarner LoshConverts the Lua value at the given index to a C string. 55698e3e3a7aSWarner LoshIf <code>len</code> is not <code>NULL</code>, 55708e3e3a7aSWarner Loshit sets <code>*len</code> with the string length. 55718e3e3a7aSWarner LoshThe Lua value must be a string or a number; 55728e3e3a7aSWarner Loshotherwise, the function returns <code>NULL</code>. 55738e3e3a7aSWarner LoshIf the value is a number, 55748e3e3a7aSWarner Loshthen <code>lua_tolstring</code> also 55758e3e3a7aSWarner Losh<em>changes the actual value in the stack to a string</em>. 55768e3e3a7aSWarner Losh(This change confuses <a href="#lua_next"><code>lua_next</code></a> 55778e3e3a7aSWarner Loshwhen <code>lua_tolstring</code> is applied to keys during a table traversal.) 55788e3e3a7aSWarner Losh 55798e3e3a7aSWarner Losh 55808e3e3a7aSWarner Losh<p> 55818e3e3a7aSWarner Losh<code>lua_tolstring</code> returns a pointer 55820495ed39SKyle Evansto a string inside the Lua state (see <a href="#4.1.3">§4.1.3</a>). 55838e3e3a7aSWarner LoshThis string always has a zero ('<code>\0</code>') 55848e3e3a7aSWarner Loshafter its last character (as in C), 55858e3e3a7aSWarner Loshbut can contain other zeros in its body. 55868e3e3a7aSWarner Losh 55878e3e3a7aSWarner Losh 55888e3e3a7aSWarner Losh 55898e3e3a7aSWarner Losh 55908e3e3a7aSWarner Losh 55918e3e3a7aSWarner Losh<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> 55928e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 55938e3e3a7aSWarner Losh<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> 55948e3e3a7aSWarner Losh 55958e3e3a7aSWarner Losh<p> 55968e3e3a7aSWarner LoshEquivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 55978e3e3a7aSWarner Losh 55988e3e3a7aSWarner Losh 55998e3e3a7aSWarner Losh 56008e3e3a7aSWarner Losh 56018e3e3a7aSWarner Losh 56028e3e3a7aSWarner Losh<hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p> 56038e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 56048e3e3a7aSWarner Losh<pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre> 56058e3e3a7aSWarner Losh 56068e3e3a7aSWarner Losh<p> 56078e3e3a7aSWarner LoshConverts the Lua value at the given index 56088e3e3a7aSWarner Loshto the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). 56098e3e3a7aSWarner LoshThe Lua value must be a number or a string convertible to a number 56108e3e3a7aSWarner Losh(see <a href="#3.4.3">§3.4.3</a>); 56118e3e3a7aSWarner Loshotherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0. 56128e3e3a7aSWarner Losh 56138e3e3a7aSWarner Losh 56148e3e3a7aSWarner Losh<p> 56158e3e3a7aSWarner LoshIf <code>isnum</code> is not <code>NULL</code>, 56168e3e3a7aSWarner Loshits referent is assigned a boolean value that 56178e3e3a7aSWarner Loshindicates whether the operation succeeded. 56188e3e3a7aSWarner Losh 56198e3e3a7aSWarner Losh 56208e3e3a7aSWarner Losh 56218e3e3a7aSWarner Losh 56228e3e3a7aSWarner Losh 56238e3e3a7aSWarner Losh<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> 56248e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 56258e3e3a7aSWarner Losh<pre>const void *lua_topointer (lua_State *L, int index);</pre> 56268e3e3a7aSWarner Losh 56278e3e3a7aSWarner Losh<p> 56288e3e3a7aSWarner LoshConverts the value at the given index to a generic 56298e3e3a7aSWarner LoshC pointer (<code>void*</code>). 56300495ed39SKyle EvansThe value can be a userdata, a table, a thread, a string, or a function; 56318e3e3a7aSWarner Loshotherwise, <code>lua_topointer</code> returns <code>NULL</code>. 56328e3e3a7aSWarner LoshDifferent objects will give different pointers. 56338e3e3a7aSWarner LoshThere is no way to convert the pointer back to its original value. 56348e3e3a7aSWarner Losh 56358e3e3a7aSWarner Losh 56368e3e3a7aSWarner Losh<p> 56378e3e3a7aSWarner LoshTypically this function is used only for hashing and debug information. 56388e3e3a7aSWarner Losh 56398e3e3a7aSWarner Losh 56408e3e3a7aSWarner Losh 56418e3e3a7aSWarner Losh 56428e3e3a7aSWarner Losh 56438e3e3a7aSWarner Losh<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> 56448e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span> 56458e3e3a7aSWarner Losh<pre>const char *lua_tostring (lua_State *L, int index);</pre> 56468e3e3a7aSWarner Losh 56478e3e3a7aSWarner Losh<p> 56488e3e3a7aSWarner LoshEquivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. 56498e3e3a7aSWarner Losh 56508e3e3a7aSWarner Losh 56518e3e3a7aSWarner Losh 56528e3e3a7aSWarner Losh 56538e3e3a7aSWarner Losh 56548e3e3a7aSWarner Losh<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> 56558e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 56568e3e3a7aSWarner Losh<pre>lua_State *lua_tothread (lua_State *L, int index);</pre> 56578e3e3a7aSWarner Losh 56588e3e3a7aSWarner Losh<p> 56598e3e3a7aSWarner LoshConverts the value at the given index to a Lua thread 56608e3e3a7aSWarner Losh(represented as <code>lua_State*</code>). 56618e3e3a7aSWarner LoshThis value must be a thread; 56628e3e3a7aSWarner Loshotherwise, the function returns <code>NULL</code>. 56638e3e3a7aSWarner Losh 56648e3e3a7aSWarner Losh 56658e3e3a7aSWarner Losh 56668e3e3a7aSWarner Losh 56678e3e3a7aSWarner Losh 56688e3e3a7aSWarner Losh<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> 56698e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 56708e3e3a7aSWarner Losh<pre>void *lua_touserdata (lua_State *L, int index);</pre> 56718e3e3a7aSWarner Losh 56728e3e3a7aSWarner Losh<p> 56738e3e3a7aSWarner LoshIf the value at the given index is a full userdata, 56740495ed39SKyle Evansreturns its memory-block address. 56758e3e3a7aSWarner LoshIf the value is a light userdata, 56760495ed39SKyle Evansreturns its value (a pointer). 56778e3e3a7aSWarner LoshOtherwise, returns <code>NULL</code>. 56788e3e3a7aSWarner Losh 56798e3e3a7aSWarner Losh 56808e3e3a7aSWarner Losh 56818e3e3a7aSWarner Losh 56828e3e3a7aSWarner Losh 56838e3e3a7aSWarner Losh<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> 56848e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 56858e3e3a7aSWarner Losh<pre>int lua_type (lua_State *L, int index);</pre> 56868e3e3a7aSWarner Losh 56878e3e3a7aSWarner Losh<p> 56888e3e3a7aSWarner LoshReturns the type of the value in the given valid index, 56890495ed39SKyle Evansor <code>LUA_TNONE</code> for a non-valid but acceptable index. 56908e3e3a7aSWarner LoshThe types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants 56918e3e3a7aSWarner Loshdefined in <code>lua.h</code>: 56920495ed39SKyle Evans<a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a>, 56938e3e3a7aSWarner Losh<a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>, 56948e3e3a7aSWarner Losh<a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>, 56958e3e3a7aSWarner Losh<a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, 56968e3e3a7aSWarner Losh<a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, 56978e3e3a7aSWarner Losh<a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, 56988e3e3a7aSWarner Losh<a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, 56998e3e3a7aSWarner Losh<a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>, 57008e3e3a7aSWarner Loshand 57018e3e3a7aSWarner Losh<a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>. 57028e3e3a7aSWarner Losh 57038e3e3a7aSWarner Losh 57048e3e3a7aSWarner Losh 57058e3e3a7aSWarner Losh 57068e3e3a7aSWarner Losh 57078e3e3a7aSWarner Losh<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> 57088e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 57098e3e3a7aSWarner Losh<pre>const char *lua_typename (lua_State *L, int tp);</pre> 57108e3e3a7aSWarner Losh 57118e3e3a7aSWarner Losh<p> 57128e3e3a7aSWarner LoshReturns the name of the type encoded by the value <code>tp</code>, 57138e3e3a7aSWarner Loshwhich must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. 57148e3e3a7aSWarner Losh 57158e3e3a7aSWarner Losh 57168e3e3a7aSWarner Losh 57178e3e3a7aSWarner Losh 57188e3e3a7aSWarner Losh 57198e3e3a7aSWarner Losh<hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3> 57208e3e3a7aSWarner Losh<pre>typedef ... lua_Unsigned;</pre> 57218e3e3a7aSWarner Losh 57228e3e3a7aSWarner Losh<p> 57238e3e3a7aSWarner LoshThe unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>. 57248e3e3a7aSWarner Losh 57258e3e3a7aSWarner Losh 57268e3e3a7aSWarner Losh 57278e3e3a7aSWarner Losh 57288e3e3a7aSWarner Losh 57298e3e3a7aSWarner Losh<hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p> 57308e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 57318e3e3a7aSWarner Losh<pre>int lua_upvalueindex (int i);</pre> 57328e3e3a7aSWarner Losh 57338e3e3a7aSWarner Losh<p> 57348e3e3a7aSWarner LoshReturns the pseudo-index that represents the <code>i</code>-th upvalue of 57350495ed39SKyle Evansthe running function (see <a href="#4.2">§4.2</a>). 57360495ed39SKyle Evans<code>i</code> must be in the range <em>[1,256]</em>. 57378e3e3a7aSWarner Losh 57388e3e3a7aSWarner Losh 57398e3e3a7aSWarner Losh 57408e3e3a7aSWarner Losh 57418e3e3a7aSWarner Losh 57428e3e3a7aSWarner Losh<hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p> 57438e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 57440495ed39SKyle Evans<pre>lua_Number lua_version (lua_State *L);</pre> 57458e3e3a7aSWarner Losh 57468e3e3a7aSWarner Losh<p> 57470495ed39SKyle EvansReturns the version number of this core. 57480495ed39SKyle Evans 57490495ed39SKyle Evans 57500495ed39SKyle Evans 57510495ed39SKyle Evans 57520495ed39SKyle Evans 57530495ed39SKyle Evans<hr><h3><a name="lua_WarnFunction"><code>lua_WarnFunction</code></a></h3> 57540495ed39SKyle Evans<pre>typedef void (*lua_WarnFunction) (void *ud, const char *msg, int tocont);</pre> 57550495ed39SKyle Evans 57560495ed39SKyle Evans<p> 57570495ed39SKyle EvansThe type of warning functions, called by Lua to emit warnings. 57580495ed39SKyle EvansThe first parameter is an opaque pointer 57590495ed39SKyle Evansset by <a href="#lua_setwarnf"><code>lua_setwarnf</code></a>. 57600495ed39SKyle EvansThe second parameter is the warning message. 57610495ed39SKyle EvansThe third parameter is a boolean that 57620495ed39SKyle Evansindicates whether the message is 57630495ed39SKyle Evansto be continued by the message in the next call. 57640495ed39SKyle Evans 57650495ed39SKyle Evans 57660495ed39SKyle Evans<p> 57670495ed39SKyle EvansSee <a href="#pdf-warn"><code>warn</code></a> for more details about warnings. 57680495ed39SKyle Evans 57690495ed39SKyle Evans 57700495ed39SKyle Evans 57710495ed39SKyle Evans 57720495ed39SKyle Evans 57730495ed39SKyle Evans<hr><h3><a name="lua_warning"><code>lua_warning</code></a></h3><p> 57740495ed39SKyle Evans<span class="apii">[-0, +0, –]</span> 57750495ed39SKyle Evans<pre>void lua_warning (lua_State *L, const char *msg, int tocont);</pre> 57760495ed39SKyle Evans 57770495ed39SKyle Evans<p> 57780495ed39SKyle EvansEmits a warning with the given message. 57790495ed39SKyle EvansA message in a call with <code>tocont</code> true should be 57800495ed39SKyle Evanscontinued in another call to this function. 57810495ed39SKyle Evans 57820495ed39SKyle Evans 57830495ed39SKyle Evans<p> 57840495ed39SKyle EvansSee <a href="#pdf-warn"><code>warn</code></a> for more details about warnings. 57858e3e3a7aSWarner Losh 57868e3e3a7aSWarner Losh 57878e3e3a7aSWarner Losh 57888e3e3a7aSWarner Losh 57898e3e3a7aSWarner Losh 57908e3e3a7aSWarner Losh<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> 57918e3e3a7aSWarner Losh<pre>typedef int (*lua_Writer) (lua_State *L, 57928e3e3a7aSWarner Losh const void* p, 57938e3e3a7aSWarner Losh size_t sz, 57948e3e3a7aSWarner Losh void* ud);</pre> 57958e3e3a7aSWarner Losh 57968e3e3a7aSWarner Losh<p> 57978e3e3a7aSWarner LoshThe type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. 57980495ed39SKyle EvansEvery time <a href="#lua_dump"><code>lua_dump</code></a> produces another piece of chunk, 57990495ed39SKyle Evansit calls the writer, 58008e3e3a7aSWarner Loshpassing along the buffer to be written (<code>p</code>), 58018e3e3a7aSWarner Loshits size (<code>sz</code>), 58020495ed39SKyle Evansand the <code>ud</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. 58038e3e3a7aSWarner Losh 58048e3e3a7aSWarner Losh 58058e3e3a7aSWarner Losh<p> 58068e3e3a7aSWarner LoshThe writer returns an error code: 58078e3e3a7aSWarner Losh0 means no errors; 58088e3e3a7aSWarner Loshany other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from 58098e3e3a7aSWarner Loshcalling the writer again. 58108e3e3a7aSWarner Losh 58118e3e3a7aSWarner Losh 58128e3e3a7aSWarner Losh 58138e3e3a7aSWarner Losh 58148e3e3a7aSWarner Losh 58158e3e3a7aSWarner Losh<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> 58168e3e3a7aSWarner Losh<span class="apii">[-?, +?, –]</span> 58178e3e3a7aSWarner Losh<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> 58188e3e3a7aSWarner Losh 58198e3e3a7aSWarner Losh<p> 58208e3e3a7aSWarner LoshExchange values between different threads of the same state. 58218e3e3a7aSWarner Losh 58228e3e3a7aSWarner Losh 58238e3e3a7aSWarner Losh<p> 58248e3e3a7aSWarner LoshThis function pops <code>n</code> values from the stack <code>from</code>, 58258e3e3a7aSWarner Loshand pushes them onto the stack <code>to</code>. 58268e3e3a7aSWarner Losh 58278e3e3a7aSWarner Losh 58288e3e3a7aSWarner Losh 58298e3e3a7aSWarner Losh 58308e3e3a7aSWarner Losh 58318e3e3a7aSWarner Losh<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> 58320495ed39SKyle Evans<span class="apii">[-?, +?, <em>v</em>]</span> 58338e3e3a7aSWarner Losh<pre>int lua_yield (lua_State *L, int nresults);</pre> 58348e3e3a7aSWarner Losh 58358e3e3a7aSWarner Losh<p> 58368e3e3a7aSWarner LoshThis function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 58370495ed39SKyle Evansbut it has no continuation (see <a href="#4.5">§4.5</a>). 58388e3e3a7aSWarner LoshTherefore, when the thread resumes, 58398e3e3a7aSWarner Loshit continues the function that called 58408e3e3a7aSWarner Loshthe function calling <code>lua_yield</code>. 58410495ed39SKyle EvansTo avoid surprises, 58420495ed39SKyle Evansthis function should be called only in a tail call. 58438e3e3a7aSWarner Losh 58448e3e3a7aSWarner Losh 58458e3e3a7aSWarner Losh 58468e3e3a7aSWarner Losh 58478e3e3a7aSWarner Losh 58488e3e3a7aSWarner Losh<hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p> 58490495ed39SKyle Evans<span class="apii">[-?, +?, <em>v</em>]</span> 58508e3e3a7aSWarner Losh<pre>int lua_yieldk (lua_State *L, 58518e3e3a7aSWarner Losh int nresults, 58528e3e3a7aSWarner Losh lua_KContext ctx, 58538e3e3a7aSWarner Losh lua_KFunction k);</pre> 58548e3e3a7aSWarner Losh 58558e3e3a7aSWarner Losh<p> 58568e3e3a7aSWarner LoshYields a coroutine (thread). 58578e3e3a7aSWarner Losh 58588e3e3a7aSWarner Losh 58598e3e3a7aSWarner Losh<p> 58608e3e3a7aSWarner LoshWhen a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 58618e3e3a7aSWarner Loshthe running coroutine suspends its execution, 58628e3e3a7aSWarner Loshand the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. 58638e3e3a7aSWarner LoshThe parameter <code>nresults</code> is the number of values from the stack 58648e3e3a7aSWarner Loshthat will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. 58658e3e3a7aSWarner Losh 58668e3e3a7aSWarner Losh 58678e3e3a7aSWarner Losh<p> 58688e3e3a7aSWarner LoshWhen the coroutine is resumed again, 58698e3e3a7aSWarner LoshLua calls the given continuation function <code>k</code> to continue 58700495ed39SKyle Evansthe execution of the C function that yielded (see <a href="#4.5">§4.5</a>). 58718e3e3a7aSWarner LoshThis continuation function receives the same stack 58728e3e3a7aSWarner Loshfrom the previous function, 58738e3e3a7aSWarner Loshwith the <code>n</code> results removed and 58748e3e3a7aSWarner Loshreplaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>. 58758e3e3a7aSWarner LoshMoreover, 58768e3e3a7aSWarner Loshthe continuation function receives the value <code>ctx</code> 58778e3e3a7aSWarner Loshthat was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>. 58788e3e3a7aSWarner Losh 58798e3e3a7aSWarner Losh 58808e3e3a7aSWarner Losh<p> 58818e3e3a7aSWarner LoshUsually, this function does not return; 58828e3e3a7aSWarner Loshwhen the coroutine eventually resumes, 58838e3e3a7aSWarner Loshit continues executing the continuation function. 58848e3e3a7aSWarner LoshHowever, there is one special case, 58858e3e3a7aSWarner Loshwhich is when this function is called 58860495ed39SKyle Evansfrom inside a line or a count hook (see <a href="#4.7">§4.7</a>). 58878e3e3a7aSWarner LoshIn that case, <code>lua_yieldk</code> should be called with no continuation 58888e3e3a7aSWarner Losh(probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results, 58898e3e3a7aSWarner Loshand the hook should return immediately after the call. 58908e3e3a7aSWarner LoshLua will yield and, 58918e3e3a7aSWarner Loshwhen the coroutine resumes again, 58928e3e3a7aSWarner Loshit will continue the normal execution 58938e3e3a7aSWarner Loshof the (Lua) function that triggered the hook. 58948e3e3a7aSWarner Losh 58958e3e3a7aSWarner Losh 58968e3e3a7aSWarner Losh<p> 58978e3e3a7aSWarner LoshThis function can raise an error if it is called from a thread 58980495ed39SKyle Evanswith a pending C call with no continuation function 58990495ed39SKyle Evans(what is called a <em>C-call boundary</em>), 59008e3e3a7aSWarner Loshor it is called from a thread that is not running inside a resume 59010495ed39SKyle Evans(typically the main thread). 59028e3e3a7aSWarner Losh 59038e3e3a7aSWarner Losh 59048e3e3a7aSWarner Losh 59058e3e3a7aSWarner Losh 59068e3e3a7aSWarner Losh 59078e3e3a7aSWarner Losh 59088e3e3a7aSWarner Losh 59090495ed39SKyle Evans<h2>4.7 – <a name="4.7">The Debug Interface</a></h2> 59108e3e3a7aSWarner Losh 59118e3e3a7aSWarner Losh<p> 59128e3e3a7aSWarner LoshLua has no built-in debugging facilities. 59138e3e3a7aSWarner LoshInstead, it offers a special interface 59148e3e3a7aSWarner Loshby means of functions and <em>hooks</em>. 59158e3e3a7aSWarner LoshThis interface allows the construction of different 59168e3e3a7aSWarner Loshkinds of debuggers, profilers, and other tools 59178e3e3a7aSWarner Loshthat need "inside information" from the interpreter. 59188e3e3a7aSWarner Losh 59198e3e3a7aSWarner Losh 59208e3e3a7aSWarner Losh 59218e3e3a7aSWarner Losh<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> 59228e3e3a7aSWarner Losh<pre>typedef struct lua_Debug { 59238e3e3a7aSWarner Losh int event; 59248e3e3a7aSWarner Losh const char *name; /* (n) */ 59258e3e3a7aSWarner Losh const char *namewhat; /* (n) */ 59268e3e3a7aSWarner Losh const char *what; /* (S) */ 59278e3e3a7aSWarner Losh const char *source; /* (S) */ 59280495ed39SKyle Evans size_t srclen; /* (S) */ 59298e3e3a7aSWarner Losh int currentline; /* (l) */ 59308e3e3a7aSWarner Losh int linedefined; /* (S) */ 59318e3e3a7aSWarner Losh int lastlinedefined; /* (S) */ 59328e3e3a7aSWarner Losh unsigned char nups; /* (u) number of upvalues */ 59338e3e3a7aSWarner Losh unsigned char nparams; /* (u) number of parameters */ 59348e3e3a7aSWarner Losh char isvararg; /* (u) */ 59358e3e3a7aSWarner Losh char istailcall; /* (t) */ 59360495ed39SKyle Evans unsigned short ftransfer; /* (r) index of first value transferred */ 59370495ed39SKyle Evans unsigned short ntransfer; /* (r) number of transferred values */ 59388e3e3a7aSWarner Losh char short_src[LUA_IDSIZE]; /* (S) */ 59398e3e3a7aSWarner Losh /* private part */ 59408e3e3a7aSWarner Losh <em>other fields</em> 59418e3e3a7aSWarner Losh} lua_Debug;</pre> 59428e3e3a7aSWarner Losh 59438e3e3a7aSWarner Losh<p> 59448e3e3a7aSWarner LoshA structure used to carry different pieces of 59458e3e3a7aSWarner Loshinformation about a function or an activation record. 59468e3e3a7aSWarner Losh<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part 59478e3e3a7aSWarner Loshof this structure, for later use. 59488e3e3a7aSWarner LoshTo fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, 5949*8c784bb8SWarner Loshyou must call <a href="#lua_getinfo"><code>lua_getinfo</code></a> with an appropriate parameter. 5950*8c784bb8SWarner Losh(Specifically, to get a field, 5951*8c784bb8SWarner Loshyou must add the letter between parentheses in the field's comment 5952*8c784bb8SWarner Loshto the parameter <code>what</code> of <a href="#lua_getinfo"><code>lua_getinfo</code></a>.) 59538e3e3a7aSWarner Losh 59548e3e3a7aSWarner Losh 59558e3e3a7aSWarner Losh<p> 59568e3e3a7aSWarner LoshThe fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: 59578e3e3a7aSWarner Losh 59588e3e3a7aSWarner Losh<ul> 59598e3e3a7aSWarner Losh 59608e3e3a7aSWarner Losh<li><b><code>source</code>: </b> 59610495ed39SKyle Evansthe source of the chunk that created the function. 59628e3e3a7aSWarner LoshIf <code>source</code> starts with a '<code>@</code>', 59638e3e3a7aSWarner Loshit means that the function was defined in a file where 59648e3e3a7aSWarner Loshthe file name follows the '<code>@</code>'. 59658e3e3a7aSWarner LoshIf <code>source</code> starts with a '<code>=</code>', 59660495ed39SKyle Evansthe remainder of its contents describes the source in a user-dependent manner. 59678e3e3a7aSWarner LoshOtherwise, 59688e3e3a7aSWarner Loshthe function was defined in a string where 59698e3e3a7aSWarner Losh<code>source</code> is that string. 59708e3e3a7aSWarner Losh</li> 59718e3e3a7aSWarner Losh 59720495ed39SKyle Evans<li><b><code>srclen</code>: </b> 59730495ed39SKyle EvansThe length of the string <code>source</code>. 59740495ed39SKyle Evans</li> 59750495ed39SKyle Evans 59768e3e3a7aSWarner Losh<li><b><code>short_src</code>: </b> 59778e3e3a7aSWarner Losha "printable" version of <code>source</code>, to be used in error messages. 59788e3e3a7aSWarner Losh</li> 59798e3e3a7aSWarner Losh 59808e3e3a7aSWarner Losh<li><b><code>linedefined</code>: </b> 59818e3e3a7aSWarner Loshthe line number where the definition of the function starts. 59828e3e3a7aSWarner Losh</li> 59838e3e3a7aSWarner Losh 59848e3e3a7aSWarner Losh<li><b><code>lastlinedefined</code>: </b> 59858e3e3a7aSWarner Loshthe line number where the definition of the function ends. 59868e3e3a7aSWarner Losh</li> 59878e3e3a7aSWarner Losh 59888e3e3a7aSWarner Losh<li><b><code>what</code>: </b> 59898e3e3a7aSWarner Loshthe string <code>"Lua"</code> if the function is a Lua function, 59908e3e3a7aSWarner Losh<code>"C"</code> if it is a C function, 59918e3e3a7aSWarner Losh<code>"main"</code> if it is the main part of a chunk. 59928e3e3a7aSWarner Losh</li> 59938e3e3a7aSWarner Losh 59948e3e3a7aSWarner Losh<li><b><code>currentline</code>: </b> 59958e3e3a7aSWarner Loshthe current line where the given function is executing. 59968e3e3a7aSWarner LoshWhen no line information is available, 59978e3e3a7aSWarner Losh<code>currentline</code> is set to -1. 59988e3e3a7aSWarner Losh</li> 59998e3e3a7aSWarner Losh 60008e3e3a7aSWarner Losh<li><b><code>name</code>: </b> 60018e3e3a7aSWarner Losha reasonable name for the given function. 60028e3e3a7aSWarner LoshBecause functions in Lua are first-class values, 60038e3e3a7aSWarner Loshthey do not have a fixed name: 60048e3e3a7aSWarner Loshsome functions can be the value of multiple global variables, 60058e3e3a7aSWarner Loshwhile others can be stored only in a table field. 60068e3e3a7aSWarner LoshThe <code>lua_getinfo</code> function checks how the function was 60078e3e3a7aSWarner Loshcalled to find a suitable name. 60088e3e3a7aSWarner LoshIf it cannot find a name, 60098e3e3a7aSWarner Loshthen <code>name</code> is set to <code>NULL</code>. 60108e3e3a7aSWarner Losh</li> 60118e3e3a7aSWarner Losh 60128e3e3a7aSWarner Losh<li><b><code>namewhat</code>: </b> 60138e3e3a7aSWarner Loshexplains the <code>name</code> field. 60148e3e3a7aSWarner LoshThe value of <code>namewhat</code> can be 60158e3e3a7aSWarner Losh<code>"global"</code>, <code>"local"</code>, <code>"method"</code>, 60168e3e3a7aSWarner Losh<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), 60178e3e3a7aSWarner Loshaccording to how the function was called. 60188e3e3a7aSWarner Losh(Lua uses the empty string when no other option seems to apply.) 60198e3e3a7aSWarner Losh</li> 60208e3e3a7aSWarner Losh 60218e3e3a7aSWarner Losh<li><b><code>istailcall</code>: </b> 60228e3e3a7aSWarner Loshtrue if this function invocation was called by a tail call. 60238e3e3a7aSWarner LoshIn this case, the caller of this level is not in the stack. 60248e3e3a7aSWarner Losh</li> 60258e3e3a7aSWarner Losh 60268e3e3a7aSWarner Losh<li><b><code>nups</code>: </b> 60278e3e3a7aSWarner Loshthe number of upvalues of the function. 60288e3e3a7aSWarner Losh</li> 60298e3e3a7aSWarner Losh 60308e3e3a7aSWarner Losh<li><b><code>nparams</code>: </b> 60310495ed39SKyle Evansthe number of parameters of the function 60328e3e3a7aSWarner Losh(always 0 for C functions). 60338e3e3a7aSWarner Losh</li> 60348e3e3a7aSWarner Losh 60358e3e3a7aSWarner Losh<li><b><code>isvararg</code>: </b> 60368e3e3a7aSWarner Loshtrue if the function is a vararg function 60378e3e3a7aSWarner Losh(always true for C functions). 60388e3e3a7aSWarner Losh</li> 60398e3e3a7aSWarner Losh 60400495ed39SKyle Evans<li><b><code>ftransfer</code>: </b> 60410495ed39SKyle Evansthe index in the stack of the first value being "transferred", 60420495ed39SKyle Evansthat is, parameters in a call or return values in a return. 60430495ed39SKyle Evans(The other values are in consecutive indices.) 60440495ed39SKyle EvansUsing this index, you can access and modify these values 60450495ed39SKyle Evansthrough <a href="#lua_getlocal"><code>lua_getlocal</code></a> and <a href="#lua_setlocal"><code>lua_setlocal</code></a>. 60460495ed39SKyle EvansThis field is only meaningful during a 60470495ed39SKyle Evanscall hook, denoting the first parameter, 60480495ed39SKyle Evansor a return hook, denoting the first value being returned. 60490495ed39SKyle Evans(For call hooks, this value is always 1.) 60500495ed39SKyle Evans</li> 60510495ed39SKyle Evans 60520495ed39SKyle Evans<li><b><code>ntransfer</code>: </b> 60530495ed39SKyle EvansThe number of values being transferred (see previous item). 60540495ed39SKyle Evans(For calls of Lua functions, 60550495ed39SKyle Evansthis value is always equal to <code>nparams</code>.) 60560495ed39SKyle Evans</li> 60570495ed39SKyle Evans 60588e3e3a7aSWarner Losh</ul> 60598e3e3a7aSWarner Losh 60608e3e3a7aSWarner Losh 60618e3e3a7aSWarner Losh 60628e3e3a7aSWarner Losh 60638e3e3a7aSWarner Losh<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> 60648e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 60658e3e3a7aSWarner Losh<pre>lua_Hook lua_gethook (lua_State *L);</pre> 60668e3e3a7aSWarner Losh 60678e3e3a7aSWarner Losh<p> 60688e3e3a7aSWarner LoshReturns the current hook function. 60698e3e3a7aSWarner Losh 60708e3e3a7aSWarner Losh 60718e3e3a7aSWarner Losh 60728e3e3a7aSWarner Losh 60738e3e3a7aSWarner Losh 60748e3e3a7aSWarner Losh<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> 60758e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 60768e3e3a7aSWarner Losh<pre>int lua_gethookcount (lua_State *L);</pre> 60778e3e3a7aSWarner Losh 60788e3e3a7aSWarner Losh<p> 60798e3e3a7aSWarner LoshReturns the current hook count. 60808e3e3a7aSWarner Losh 60818e3e3a7aSWarner Losh 60828e3e3a7aSWarner Losh 60838e3e3a7aSWarner Losh 60848e3e3a7aSWarner Losh 60858e3e3a7aSWarner Losh<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> 60868e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 60878e3e3a7aSWarner Losh<pre>int lua_gethookmask (lua_State *L);</pre> 60888e3e3a7aSWarner Losh 60898e3e3a7aSWarner Losh<p> 60908e3e3a7aSWarner LoshReturns the current hook mask. 60918e3e3a7aSWarner Losh 60928e3e3a7aSWarner Losh 60938e3e3a7aSWarner Losh 60948e3e3a7aSWarner Losh 60958e3e3a7aSWarner Losh 60968e3e3a7aSWarner Losh<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> 60970495ed39SKyle Evans<span class="apii">[-(0|1), +(0|1|2), <em>m</em>]</span> 60988e3e3a7aSWarner Losh<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> 60998e3e3a7aSWarner Losh 61008e3e3a7aSWarner Losh<p> 61018e3e3a7aSWarner LoshGets information about a specific function or function invocation. 61028e3e3a7aSWarner Losh 61038e3e3a7aSWarner Losh 61048e3e3a7aSWarner Losh<p> 61058e3e3a7aSWarner LoshTo get information about a function invocation, 61068e3e3a7aSWarner Loshthe parameter <code>ar</code> must be a valid activation record that was 61078e3e3a7aSWarner Loshfilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 61088e3e3a7aSWarner Loshgiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 61098e3e3a7aSWarner Losh 61108e3e3a7aSWarner Losh 61118e3e3a7aSWarner Losh<p> 6112e112e9d2SKyle EvansTo get information about a function, you push it onto the stack 61138e3e3a7aSWarner Loshand start the <code>what</code> string with the character '<code>></code>'. 61148e3e3a7aSWarner Losh(In that case, 61158e3e3a7aSWarner Losh<code>lua_getinfo</code> pops the function from the top of the stack.) 61168e3e3a7aSWarner LoshFor instance, to know in which line a function <code>f</code> was defined, 61178e3e3a7aSWarner Loshyou can write the following code: 61188e3e3a7aSWarner Losh 61198e3e3a7aSWarner Losh<pre> 61208e3e3a7aSWarner Losh lua_Debug ar; 61218e3e3a7aSWarner Losh lua_getglobal(L, "f"); /* get global 'f' */ 61228e3e3a7aSWarner Losh lua_getinfo(L, ">S", &ar); 61238e3e3a7aSWarner Losh printf("%d\n", ar.linedefined); 61248e3e3a7aSWarner Losh</pre> 61258e3e3a7aSWarner Losh 61268e3e3a7aSWarner Losh<p> 61278e3e3a7aSWarner LoshEach character in the string <code>what</code> 61288e3e3a7aSWarner Loshselects some fields of the structure <code>ar</code> to be filled or 6129*8c784bb8SWarner Losha value to be pushed on the stack. 6130*8c784bb8SWarner Losh(These characters are also documented in the declaration of 6131*8c784bb8SWarner Loshthe structure <a href="#lua_Debug"><code>lua_Debug</code></a>, 6132*8c784bb8SWarner Loshbetween parentheses in the comments following each field.) 61338e3e3a7aSWarner Losh 61348e3e3a7aSWarner Losh<ul> 61358e3e3a7aSWarner Losh 6136*8c784bb8SWarner Losh<li><b>'<code>f</code>': </b> 6137*8c784bb8SWarner Loshpushes onto the stack the function that is 6138*8c784bb8SWarner Loshrunning at the given level; 6139*8c784bb8SWarner Losh</li> 6140*8c784bb8SWarner Losh 6141*8c784bb8SWarner Losh<li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>; 6142*8c784bb8SWarner Losh</li> 6143*8c784bb8SWarner Losh 6144*8c784bb8SWarner Losh<li><b>'<code>n</code>': </b> fills in the fields <code>name</code> and <code>namewhat</code>; 6145*8c784bb8SWarner Losh</li> 6146*8c784bb8SWarner Losh 6147*8c784bb8SWarner Losh<li><b>'<code>r</code>': </b> fills in the fields <code>ftransfer</code> and <code>ntransfer</code>; 61488e3e3a7aSWarner Losh</li> 61498e3e3a7aSWarner Losh 61508e3e3a7aSWarner Losh<li><b>'<code>S</code>': </b> 61518e3e3a7aSWarner Loshfills in the fields <code>source</code>, <code>short_src</code>, 61528e3e3a7aSWarner Losh<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; 61538e3e3a7aSWarner Losh</li> 61548e3e3a7aSWarner Losh 61558e3e3a7aSWarner Losh<li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>; 61568e3e3a7aSWarner Losh</li> 61578e3e3a7aSWarner Losh 61588e3e3a7aSWarner Losh<li><b>'<code>u</code>': </b> fills in the fields 61598e3e3a7aSWarner Losh<code>nups</code>, <code>nparams</code>, and <code>isvararg</code>; 61608e3e3a7aSWarner Losh</li> 61618e3e3a7aSWarner Losh 61628e3e3a7aSWarner Losh<li><b>'<code>L</code>': </b> 6163*8c784bb8SWarner Loshpushes onto the stack a table whose indices are 6164*8c784bb8SWarner Loshthe lines on the function with some associated code, 6165*8c784bb8SWarner Loshthat is, the lines where you can put a break point. 6166*8c784bb8SWarner Losh(Lines with no code include empty lines and comments.) 61678e3e3a7aSWarner LoshIf this option is given together with option '<code>f</code>', 61688e3e3a7aSWarner Loshits table is pushed after the function. 61690495ed39SKyle EvansThis is the only option that can raise a memory error. 61708e3e3a7aSWarner Losh</li> 61718e3e3a7aSWarner Losh 61728e3e3a7aSWarner Losh</ul> 61738e3e3a7aSWarner Losh 61748e3e3a7aSWarner Losh<p> 61750495ed39SKyle EvansThis function returns 0 to signal an invalid option in <code>what</code>; 61760495ed39SKyle Evanseven then the valid options are handled correctly. 61778e3e3a7aSWarner Losh 61788e3e3a7aSWarner Losh 61798e3e3a7aSWarner Losh 61808e3e3a7aSWarner Losh 61818e3e3a7aSWarner Losh 61828e3e3a7aSWarner Losh<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> 61838e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), –]</span> 61848e3e3a7aSWarner Losh<pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 61858e3e3a7aSWarner Losh 61868e3e3a7aSWarner Losh<p> 61870495ed39SKyle EvansGets information about a local variable or a temporary value 61880495ed39SKyle Evansof a given activation record or a given function. 61898e3e3a7aSWarner Losh 61908e3e3a7aSWarner Losh 61918e3e3a7aSWarner Losh<p> 61928e3e3a7aSWarner LoshIn the first case, 61938e3e3a7aSWarner Loshthe parameter <code>ar</code> must be a valid activation record that was 61948e3e3a7aSWarner Loshfilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 61958e3e3a7aSWarner Loshgiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 61968e3e3a7aSWarner LoshThe index <code>n</code> selects which local variable to inspect; 61978e3e3a7aSWarner Loshsee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices 61988e3e3a7aSWarner Loshand names. 61998e3e3a7aSWarner Losh 62008e3e3a7aSWarner Losh 62018e3e3a7aSWarner Losh<p> 62028e3e3a7aSWarner Losh<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack 62038e3e3a7aSWarner Loshand returns its name. 62048e3e3a7aSWarner Losh 62058e3e3a7aSWarner Losh 62068e3e3a7aSWarner Losh<p> 62078e3e3a7aSWarner LoshIn the second case, <code>ar</code> must be <code>NULL</code> and the function 62080495ed39SKyle Evansto be inspected must be on the top of the stack. 62098e3e3a7aSWarner LoshIn this case, only parameters of Lua functions are visible 62108e3e3a7aSWarner Losh(as there is no information about what variables are active) 62118e3e3a7aSWarner Loshand no values are pushed onto the stack. 62128e3e3a7aSWarner Losh 62138e3e3a7aSWarner Losh 62148e3e3a7aSWarner Losh<p> 62158e3e3a7aSWarner LoshReturns <code>NULL</code> (and pushes nothing) 62168e3e3a7aSWarner Loshwhen the index is greater than 62178e3e3a7aSWarner Loshthe number of active local variables. 62188e3e3a7aSWarner Losh 62198e3e3a7aSWarner Losh 62208e3e3a7aSWarner Losh 62218e3e3a7aSWarner Losh 62228e3e3a7aSWarner Losh 62238e3e3a7aSWarner Losh<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> 62248e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 62258e3e3a7aSWarner Losh<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> 62268e3e3a7aSWarner Losh 62278e3e3a7aSWarner Losh<p> 62288e3e3a7aSWarner LoshGets information about the interpreter runtime stack. 62298e3e3a7aSWarner Losh 62308e3e3a7aSWarner Losh 62318e3e3a7aSWarner Losh<p> 62328e3e3a7aSWarner LoshThis function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with 62338e3e3a7aSWarner Loshan identification of the <em>activation record</em> 62348e3e3a7aSWarner Loshof the function executing at a given level. 62358e3e3a7aSWarner LoshLevel 0 is the current running function, 62368e3e3a7aSWarner Loshwhereas level <em>n+1</em> is the function that has called level <em>n</em> 62370495ed39SKyle Evans(except for tail calls, which do not count in the stack). 62380495ed39SKyle EvansWhen called with a level greater than the stack depth, 62390495ed39SKyle Evans<a href="#lua_getstack"><code>lua_getstack</code></a> returns 0; 62400495ed39SKyle Evansotherwise it returns 1. 62418e3e3a7aSWarner Losh 62428e3e3a7aSWarner Losh 62438e3e3a7aSWarner Losh 62448e3e3a7aSWarner Losh 62458e3e3a7aSWarner Losh 62468e3e3a7aSWarner Losh<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> 62478e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), –]</span> 62488e3e3a7aSWarner Losh<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> 62498e3e3a7aSWarner Losh 62508e3e3a7aSWarner Losh<p> 62518e3e3a7aSWarner LoshGets information about the <code>n</code>-th upvalue 62528e3e3a7aSWarner Loshof the closure at index <code>funcindex</code>. 62538e3e3a7aSWarner LoshIt pushes the upvalue's value onto the stack 62548e3e3a7aSWarner Loshand returns its name. 62558e3e3a7aSWarner LoshReturns <code>NULL</code> (and pushes nothing) 62568e3e3a7aSWarner Loshwhen the index <code>n</code> is greater than the number of upvalues. 62578e3e3a7aSWarner Losh 62588e3e3a7aSWarner Losh 62598e3e3a7aSWarner Losh<p> 62600495ed39SKyle EvansSee <a href="#pdf-debug.getupvalue"><code>debug.getupvalue</code></a> for more information about upvalues. 62618e3e3a7aSWarner Losh 62628e3e3a7aSWarner Losh 62638e3e3a7aSWarner Losh 62648e3e3a7aSWarner Losh 62658e3e3a7aSWarner Losh 62668e3e3a7aSWarner Losh<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> 62678e3e3a7aSWarner Losh<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> 62688e3e3a7aSWarner Losh 62698e3e3a7aSWarner Losh<p> 62708e3e3a7aSWarner LoshType for debugging hook functions. 62718e3e3a7aSWarner Losh 62728e3e3a7aSWarner Losh 62738e3e3a7aSWarner Losh<p> 62748e3e3a7aSWarner LoshWhenever a hook is called, its <code>ar</code> argument has its field 62758e3e3a7aSWarner Losh<code>event</code> set to the specific event that triggered the hook. 62768e3e3a7aSWarner LoshLua identifies these events with the following constants: 62778e3e3a7aSWarner Losh<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, 62788e3e3a7aSWarner Losh<a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, 62798e3e3a7aSWarner Loshand <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. 62808e3e3a7aSWarner LoshMoreover, for line events, the field <code>currentline</code> is also set. 62818e3e3a7aSWarner LoshTo get the value of any other field in <code>ar</code>, 62828e3e3a7aSWarner Loshthe hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 62838e3e3a7aSWarner Losh 62848e3e3a7aSWarner Losh 62858e3e3a7aSWarner Losh<p> 62868e3e3a7aSWarner LoshFor call events, <code>event</code> can be <code>LUA_HOOKCALL</code>, 62878e3e3a7aSWarner Loshthe normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call; 62888e3e3a7aSWarner Loshin this case, there will be no corresponding return event. 62898e3e3a7aSWarner Losh 62908e3e3a7aSWarner Losh 62918e3e3a7aSWarner Losh<p> 62928e3e3a7aSWarner LoshWhile Lua is running a hook, it disables other calls to hooks. 62938e3e3a7aSWarner LoshTherefore, if a hook calls back Lua to execute a function or a chunk, 62948e3e3a7aSWarner Loshthis execution occurs without any calls to hooks. 62958e3e3a7aSWarner Losh 62968e3e3a7aSWarner Losh 62978e3e3a7aSWarner Losh<p> 62988e3e3a7aSWarner LoshHook functions cannot have continuations, 62998e3e3a7aSWarner Loshthat is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 63008e3e3a7aSWarner 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>. 63018e3e3a7aSWarner Losh 63028e3e3a7aSWarner Losh 63038e3e3a7aSWarner Losh<p> 63048e3e3a7aSWarner LoshHook functions can yield under the following conditions: 63058e3e3a7aSWarner LoshOnly count and line events can yield; 63068e3e3a7aSWarner Loshto yield, a hook function must finish its execution 63078e3e3a7aSWarner Loshcalling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero 63088e3e3a7aSWarner Losh(that is, with no values). 63098e3e3a7aSWarner Losh 63108e3e3a7aSWarner Losh 63118e3e3a7aSWarner Losh 63128e3e3a7aSWarner Losh 63138e3e3a7aSWarner Losh 63148e3e3a7aSWarner Losh<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> 63158e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 63168e3e3a7aSWarner Losh<pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> 63178e3e3a7aSWarner Losh 63188e3e3a7aSWarner Losh<p> 63198e3e3a7aSWarner LoshSets the debugging hook function. 63208e3e3a7aSWarner Losh 63218e3e3a7aSWarner Losh 63228e3e3a7aSWarner Losh<p> 63238e3e3a7aSWarner LoshArgument <code>f</code> is the hook function. 63248e3e3a7aSWarner Losh<code>mask</code> specifies on which events the hook will be called: 63258e3e3a7aSWarner Loshit is formed by a bitwise OR of the constants 63268e3e3a7aSWarner Losh<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, 63278e3e3a7aSWarner Losh<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, 63288e3e3a7aSWarner Losh<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, 63298e3e3a7aSWarner Loshand <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. 63308e3e3a7aSWarner LoshThe <code>count</code> argument is only meaningful when the mask 63318e3e3a7aSWarner Loshincludes <code>LUA_MASKCOUNT</code>. 63328e3e3a7aSWarner LoshFor each event, the hook is called as explained below: 63338e3e3a7aSWarner Losh 63348e3e3a7aSWarner Losh<ul> 63358e3e3a7aSWarner Losh 63368e3e3a7aSWarner Losh<li><b>The call hook: </b> is called when the interpreter calls a function. 63370495ed39SKyle EvansThe hook is called just after Lua enters the new function. 63388e3e3a7aSWarner Losh</li> 63398e3e3a7aSWarner Losh 63408e3e3a7aSWarner Losh<li><b>The return hook: </b> is called when the interpreter returns from a function. 63418e3e3a7aSWarner LoshThe hook is called just before Lua leaves the function. 63428e3e3a7aSWarner Losh</li> 63438e3e3a7aSWarner Losh 63448e3e3a7aSWarner Losh<li><b>The line hook: </b> is called when the interpreter is about to 63458e3e3a7aSWarner Loshstart the execution of a new line of code, 63468e3e3a7aSWarner Loshor when it jumps back in the code (even to the same line). 63470495ed39SKyle EvansThis event only happens while Lua is executing a Lua function. 63488e3e3a7aSWarner Losh</li> 63498e3e3a7aSWarner Losh 63508e3e3a7aSWarner Losh<li><b>The count hook: </b> is called after the interpreter executes every 63518e3e3a7aSWarner Losh<code>count</code> instructions. 63520495ed39SKyle EvansThis event only happens while Lua is executing a Lua function. 63538e3e3a7aSWarner Losh</li> 63548e3e3a7aSWarner Losh 63558e3e3a7aSWarner Losh</ul> 63568e3e3a7aSWarner Losh 63578e3e3a7aSWarner Losh<p> 63580495ed39SKyle EvansHooks are disabled by setting <code>mask</code> to zero. 63598e3e3a7aSWarner Losh 63608e3e3a7aSWarner Losh 63618e3e3a7aSWarner Losh 63628e3e3a7aSWarner Losh 63638e3e3a7aSWarner Losh 63648e3e3a7aSWarner Losh<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> 63658e3e3a7aSWarner Losh<span class="apii">[-(0|1), +0, –]</span> 63668e3e3a7aSWarner Losh<pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 63678e3e3a7aSWarner Losh 63688e3e3a7aSWarner Losh<p> 63698e3e3a7aSWarner LoshSets the value of a local variable of a given activation record. 63700495ed39SKyle EvansIt assigns the value on the top of the stack 63718e3e3a7aSWarner Loshto the variable and returns its name. 63728e3e3a7aSWarner LoshIt also pops the value from the stack. 63738e3e3a7aSWarner Losh 63748e3e3a7aSWarner Losh 63758e3e3a7aSWarner Losh<p> 63768e3e3a7aSWarner LoshReturns <code>NULL</code> (and pops nothing) 63778e3e3a7aSWarner Loshwhen the index is greater than 63788e3e3a7aSWarner Loshthe number of active local variables. 63798e3e3a7aSWarner Losh 63808e3e3a7aSWarner Losh 63818e3e3a7aSWarner Losh<p> 63820495ed39SKyle EvansParameters <code>ar</code> and <code>n</code> are as in the function <a href="#lua_getlocal"><code>lua_getlocal</code></a>. 63838e3e3a7aSWarner Losh 63848e3e3a7aSWarner Losh 63858e3e3a7aSWarner Losh 63868e3e3a7aSWarner Losh 63878e3e3a7aSWarner Losh 63888e3e3a7aSWarner Losh<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> 63898e3e3a7aSWarner Losh<span class="apii">[-(0|1), +0, –]</span> 63908e3e3a7aSWarner Losh<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> 63918e3e3a7aSWarner Losh 63928e3e3a7aSWarner Losh<p> 63938e3e3a7aSWarner LoshSets the value of a closure's upvalue. 63940495ed39SKyle EvansIt assigns the value on the top of the stack 63958e3e3a7aSWarner Loshto the upvalue and returns its name. 63968e3e3a7aSWarner LoshIt also pops the value from the stack. 63978e3e3a7aSWarner Losh 63988e3e3a7aSWarner Losh 63998e3e3a7aSWarner Losh<p> 64008e3e3a7aSWarner LoshReturns <code>NULL</code> (and pops nothing) 64018e3e3a7aSWarner Loshwhen the index <code>n</code> is greater than the number of upvalues. 64028e3e3a7aSWarner Losh 64038e3e3a7aSWarner Losh 64048e3e3a7aSWarner Losh<p> 64050495ed39SKyle EvansParameters <code>funcindex</code> and <code>n</code> are as in 64060495ed39SKyle Evansthe function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>. 64078e3e3a7aSWarner Losh 64088e3e3a7aSWarner Losh 64098e3e3a7aSWarner Losh 64108e3e3a7aSWarner Losh 64118e3e3a7aSWarner Losh 64128e3e3a7aSWarner Losh<hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p> 64138e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 64148e3e3a7aSWarner Losh<pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre> 64158e3e3a7aSWarner Losh 64168e3e3a7aSWarner Losh<p> 64178e3e3a7aSWarner LoshReturns a unique identifier for the upvalue numbered <code>n</code> 64188e3e3a7aSWarner Loshfrom the closure at index <code>funcindex</code>. 64198e3e3a7aSWarner Losh 64208e3e3a7aSWarner Losh 64218e3e3a7aSWarner Losh<p> 64228e3e3a7aSWarner LoshThese unique identifiers allow a program to check whether different 64238e3e3a7aSWarner Loshclosures share upvalues. 64248e3e3a7aSWarner LoshLua closures that share an upvalue 64258e3e3a7aSWarner Losh(that is, that access a same external local variable) 64268e3e3a7aSWarner Loshwill return identical ids for those upvalue indices. 64278e3e3a7aSWarner Losh 64288e3e3a7aSWarner Losh 64298e3e3a7aSWarner Losh<p> 64300495ed39SKyle EvansParameters <code>funcindex</code> and <code>n</code> are as in 64310495ed39SKyle Evansthe function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, 64328e3e3a7aSWarner Loshbut <code>n</code> cannot be greater than the number of upvalues. 64338e3e3a7aSWarner Losh 64348e3e3a7aSWarner Losh 64358e3e3a7aSWarner Losh 64368e3e3a7aSWarner Losh 64378e3e3a7aSWarner Losh 64388e3e3a7aSWarner Losh<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p> 64398e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 64408e3e3a7aSWarner Losh<pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1, 64418e3e3a7aSWarner Losh int funcindex2, int n2);</pre> 64428e3e3a7aSWarner Losh 64438e3e3a7aSWarner Losh<p> 64448e3e3a7aSWarner LoshMake the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code> 64458e3e3a7aSWarner Loshrefer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>. 64468e3e3a7aSWarner Losh 64478e3e3a7aSWarner Losh 64488e3e3a7aSWarner Losh 64498e3e3a7aSWarner Losh 64508e3e3a7aSWarner Losh 64518e3e3a7aSWarner Losh 64528e3e3a7aSWarner Losh 64538e3e3a7aSWarner Losh<h1>5 – <a name="5">The Auxiliary Library</a></h1> 64548e3e3a7aSWarner Losh 64550495ed39SKyle Evans 64560495ed39SKyle Evans 64578e3e3a7aSWarner Losh<p> 64588e3e3a7aSWarner Losh 64598e3e3a7aSWarner LoshThe <em>auxiliary library</em> provides several convenient functions 64608e3e3a7aSWarner Loshto interface C with Lua. 64618e3e3a7aSWarner LoshWhile the basic API provides the primitive functions for all 64628e3e3a7aSWarner Loshinteractions between C and Lua, 64638e3e3a7aSWarner Loshthe auxiliary library provides higher-level functions for some 64648e3e3a7aSWarner Loshcommon tasks. 64658e3e3a7aSWarner Losh 64668e3e3a7aSWarner Losh 64678e3e3a7aSWarner Losh<p> 64688e3e3a7aSWarner LoshAll functions and types from the auxiliary library 64698e3e3a7aSWarner Loshare defined in header file <code>lauxlib.h</code> and 64708e3e3a7aSWarner Loshhave a prefix <code>luaL_</code>. 64718e3e3a7aSWarner Losh 64728e3e3a7aSWarner Losh 64738e3e3a7aSWarner Losh<p> 64748e3e3a7aSWarner LoshAll functions in the auxiliary library are built on 64758e3e3a7aSWarner Loshtop of the basic API, 64768e3e3a7aSWarner Loshand so they provide nothing that cannot be done with that API. 64778e3e3a7aSWarner LoshNevertheless, the use of the auxiliary library ensures 64788e3e3a7aSWarner Loshmore consistency to your code. 64798e3e3a7aSWarner Losh 64808e3e3a7aSWarner Losh 64818e3e3a7aSWarner Losh<p> 64828e3e3a7aSWarner LoshSeveral functions in the auxiliary library use internally some 64838e3e3a7aSWarner Loshextra stack slots. 64848e3e3a7aSWarner LoshWhen a function in the auxiliary library uses less than five slots, 64858e3e3a7aSWarner Loshit does not check the stack size; 64868e3e3a7aSWarner Loshit simply assumes that there are enough slots. 64878e3e3a7aSWarner Losh 64888e3e3a7aSWarner Losh 64898e3e3a7aSWarner Losh<p> 64908e3e3a7aSWarner LoshSeveral functions in the auxiliary library are used to 64918e3e3a7aSWarner Loshcheck C function arguments. 64928e3e3a7aSWarner LoshBecause the error message is formatted for arguments 64938e3e3a7aSWarner Losh(e.g., "<code>bad argument #1</code>"), 64948e3e3a7aSWarner Loshyou should not use these functions for other stack values. 64958e3e3a7aSWarner Losh 64968e3e3a7aSWarner Losh 64978e3e3a7aSWarner Losh<p> 64988e3e3a7aSWarner LoshFunctions called <code>luaL_check*</code> 64998e3e3a7aSWarner Loshalways raise an error if the check is not satisfied. 65008e3e3a7aSWarner Losh 65018e3e3a7aSWarner Losh 65028e3e3a7aSWarner Losh 65030495ed39SKyle Evans 65040495ed39SKyle Evans 65058e3e3a7aSWarner Losh<h2>5.1 – <a name="5.1">Functions and Types</a></h2> 65068e3e3a7aSWarner Losh 65078e3e3a7aSWarner Losh<p> 65088e3e3a7aSWarner LoshHere we list all functions and types from the auxiliary library 65098e3e3a7aSWarner Loshin alphabetical order. 65108e3e3a7aSWarner Losh 65118e3e3a7aSWarner Losh 65128e3e3a7aSWarner Losh 65138e3e3a7aSWarner Losh<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> 65148e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 65158e3e3a7aSWarner Losh<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> 65168e3e3a7aSWarner Losh 65178e3e3a7aSWarner Losh<p> 65188e3e3a7aSWarner LoshAdds the byte <code>c</code> to the buffer <code>B</code> 65198e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 65208e3e3a7aSWarner Losh 65218e3e3a7aSWarner Losh 65228e3e3a7aSWarner Losh 65238e3e3a7aSWarner Losh 65248e3e3a7aSWarner Losh 65250495ed39SKyle Evans<hr><h3><a name="luaL_addgsub"><code>luaL_addgsub</code></a></h3><p> 6526*8c784bb8SWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 65270495ed39SKyle Evans<pre>const void luaL_addgsub (luaL_Buffer *B, const char *s, 65280495ed39SKyle Evans const char *p, const char *r);</pre> 65290495ed39SKyle Evans 65300495ed39SKyle Evans<p> 65310495ed39SKyle 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>), 65320495ed39SKyle Evansreplacing any occurrence of the string <code>p</code> 65330495ed39SKyle Evanswith the string <code>r</code>. 65340495ed39SKyle Evans 65350495ed39SKyle Evans 65360495ed39SKyle Evans 65370495ed39SKyle Evans 65380495ed39SKyle Evans 65398e3e3a7aSWarner Losh<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> 65408e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 65418e3e3a7aSWarner Losh<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> 65428e3e3a7aSWarner Losh 65438e3e3a7aSWarner Losh<p> 65448e3e3a7aSWarner LoshAdds the string pointed to by <code>s</code> with length <code>l</code> to 65458e3e3a7aSWarner Loshthe buffer <code>B</code> 65468e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 65478e3e3a7aSWarner LoshThe string can contain embedded zeros. 65488e3e3a7aSWarner Losh 65498e3e3a7aSWarner Losh 65508e3e3a7aSWarner Losh 65518e3e3a7aSWarner Losh 65528e3e3a7aSWarner Losh 65538e3e3a7aSWarner Losh<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> 65548e3e3a7aSWarner Losh<span class="apii">[-?, +?, –]</span> 65558e3e3a7aSWarner Losh<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> 65568e3e3a7aSWarner Losh 65578e3e3a7aSWarner Losh<p> 65580495ed39SKyle EvansAdds to the buffer <code>B</code> 65598e3e3a7aSWarner Losha string of length <code>n</code> previously copied to the 65608e3e3a7aSWarner Loshbuffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). 65618e3e3a7aSWarner Losh 65628e3e3a7aSWarner Losh 65638e3e3a7aSWarner Losh 65648e3e3a7aSWarner Losh 65658e3e3a7aSWarner Losh 65668e3e3a7aSWarner Losh<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> 65678e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 65688e3e3a7aSWarner Losh<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> 65698e3e3a7aSWarner Losh 65708e3e3a7aSWarner Losh<p> 65718e3e3a7aSWarner LoshAdds the zero-terminated string pointed to by <code>s</code> 65728e3e3a7aSWarner Loshto the buffer <code>B</code> 65738e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 65748e3e3a7aSWarner Losh 65758e3e3a7aSWarner Losh 65768e3e3a7aSWarner Losh 65778e3e3a7aSWarner Losh 65788e3e3a7aSWarner Losh 65798e3e3a7aSWarner Losh<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> 6580*8c784bb8SWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 65818e3e3a7aSWarner Losh<pre>void luaL_addvalue (luaL_Buffer *B);</pre> 65828e3e3a7aSWarner Losh 65838e3e3a7aSWarner Losh<p> 65840495ed39SKyle EvansAdds the value on the top of the stack 65858e3e3a7aSWarner Loshto the buffer <code>B</code> 65868e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 65878e3e3a7aSWarner LoshPops the value. 65888e3e3a7aSWarner Losh 65898e3e3a7aSWarner Losh 65908e3e3a7aSWarner Losh<p> 65918e3e3a7aSWarner LoshThis is the only function on string buffers that can (and must) 65928e3e3a7aSWarner Loshbe called with an extra element on the stack, 65938e3e3a7aSWarner Loshwhich is the value to be added to the buffer. 65948e3e3a7aSWarner Losh 65958e3e3a7aSWarner Losh 65968e3e3a7aSWarner Losh 65978e3e3a7aSWarner Losh 65988e3e3a7aSWarner Losh 65998e3e3a7aSWarner Losh<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> 66008e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 66018e3e3a7aSWarner Losh<pre>void luaL_argcheck (lua_State *L, 66028e3e3a7aSWarner Losh int cond, 66038e3e3a7aSWarner Losh int arg, 66048e3e3a7aSWarner Losh const char *extramsg);</pre> 66058e3e3a7aSWarner Losh 66068e3e3a7aSWarner Losh<p> 66078e3e3a7aSWarner LoshChecks whether <code>cond</code> is true. 66088e3e3a7aSWarner LoshIf it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>). 66098e3e3a7aSWarner Losh 66108e3e3a7aSWarner Losh 66118e3e3a7aSWarner Losh 66128e3e3a7aSWarner Losh 66138e3e3a7aSWarner Losh 66148e3e3a7aSWarner Losh<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> 66158e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 66168e3e3a7aSWarner Losh<pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre> 66178e3e3a7aSWarner Losh 66188e3e3a7aSWarner Losh<p> 66198e3e3a7aSWarner LoshRaises an error reporting a problem with argument <code>arg</code> 66208e3e3a7aSWarner Loshof the C function that called it, 66218e3e3a7aSWarner Loshusing a standard message 66228e3e3a7aSWarner Loshthat includes <code>extramsg</code> as a comment: 66238e3e3a7aSWarner Losh 66248e3e3a7aSWarner Losh<pre> 66258e3e3a7aSWarner Losh bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>) 66268e3e3a7aSWarner Losh</pre><p> 66278e3e3a7aSWarner LoshThis function never returns. 66288e3e3a7aSWarner Losh 66298e3e3a7aSWarner Losh 66308e3e3a7aSWarner Losh 66318e3e3a7aSWarner Losh 66328e3e3a7aSWarner Losh 66330495ed39SKyle Evans<hr><h3><a name="luaL_argexpected"><code>luaL_argexpected</code></a></h3><p> 66340495ed39SKyle Evans<span class="apii">[-0, +0, <em>v</em>]</span> 66350495ed39SKyle Evans<pre>void luaL_argexpected (lua_State *L, 66360495ed39SKyle Evans int cond, 66370495ed39SKyle Evans int arg, 66380495ed39SKyle Evans const char *tname);</pre> 66390495ed39SKyle Evans 66400495ed39SKyle Evans<p> 66410495ed39SKyle EvansChecks whether <code>cond</code> is true. 66420495ed39SKyle EvansIf it is not, raises an error about the type of the argument <code>arg</code> 66430495ed39SKyle Evanswith a standard message (see <a href="#luaL_typeerror"><code>luaL_typeerror</code></a>). 66440495ed39SKyle Evans 66450495ed39SKyle Evans 66460495ed39SKyle Evans 66470495ed39SKyle Evans 66480495ed39SKyle Evans 66498e3e3a7aSWarner Losh<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> 66508e3e3a7aSWarner Losh<pre>typedef struct luaL_Buffer luaL_Buffer;</pre> 66518e3e3a7aSWarner Losh 66528e3e3a7aSWarner Losh<p> 66538e3e3a7aSWarner LoshType for a <em>string buffer</em>. 66548e3e3a7aSWarner Losh 66558e3e3a7aSWarner Losh 66568e3e3a7aSWarner Losh<p> 66578e3e3a7aSWarner LoshA string buffer allows C code to build Lua strings piecemeal. 66588e3e3a7aSWarner LoshIts pattern of use is as follows: 66598e3e3a7aSWarner Losh 66608e3e3a7aSWarner Losh<ul> 66618e3e3a7aSWarner Losh 66628e3e3a7aSWarner Losh<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 66638e3e3a7aSWarner Losh 66648e3e3a7aSWarner Losh<li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> 66658e3e3a7aSWarner Losh 66668e3e3a7aSWarner Losh<li> 66678e3e3a7aSWarner LoshThen add string pieces to the buffer calling any of 66688e3e3a7aSWarner Loshthe <code>luaL_add*</code> functions. 66698e3e3a7aSWarner Losh</li> 66708e3e3a7aSWarner Losh 66718e3e3a7aSWarner Losh<li> 66728e3e3a7aSWarner LoshFinish by calling <code>luaL_pushresult(&b)</code>. 66738e3e3a7aSWarner LoshThis call leaves the final string on the top of the stack. 66748e3e3a7aSWarner Losh</li> 66758e3e3a7aSWarner Losh 66768e3e3a7aSWarner Losh</ul> 66778e3e3a7aSWarner Losh 66788e3e3a7aSWarner Losh<p> 66790495ed39SKyle EvansIf you know beforehand the maximum size of the resulting string, 66808e3e3a7aSWarner Loshyou can use the buffer like this: 66818e3e3a7aSWarner Losh 66828e3e3a7aSWarner Losh<ul> 66838e3e3a7aSWarner Losh 66848e3e3a7aSWarner Losh<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 66858e3e3a7aSWarner Losh 66868e3e3a7aSWarner Losh<li>Then initialize it and preallocate a space of 66878e3e3a7aSWarner Loshsize <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li> 66888e3e3a7aSWarner Losh 66890495ed39SKyle Evans<li>Then produce the string into that space.</li> 66908e3e3a7aSWarner Losh 66918e3e3a7aSWarner Losh<li> 66928e3e3a7aSWarner LoshFinish by calling <code>luaL_pushresultsize(&b, sz)</code>, 66938e3e3a7aSWarner Loshwhere <code>sz</code> is the total size of the resulting string 66940495ed39SKyle Evanscopied into that space (which may be less than or 66950495ed39SKyle Evansequal to the preallocated size). 66968e3e3a7aSWarner Losh</li> 66978e3e3a7aSWarner Losh 66988e3e3a7aSWarner Losh</ul> 66998e3e3a7aSWarner Losh 67008e3e3a7aSWarner Losh<p> 67018e3e3a7aSWarner LoshDuring its normal operation, 67028e3e3a7aSWarner Losha string buffer uses a variable number of stack slots. 67038e3e3a7aSWarner LoshSo, while using a buffer, you cannot assume that you know where 67048e3e3a7aSWarner Loshthe top of the stack is. 67058e3e3a7aSWarner LoshYou can use the stack between successive calls to buffer operations 67068e3e3a7aSWarner Loshas long as that use is balanced; 67078e3e3a7aSWarner Loshthat is, 67088e3e3a7aSWarner Loshwhen you call a buffer operation, 67098e3e3a7aSWarner Loshthe stack is at the same level 67108e3e3a7aSWarner Loshit was immediately after the previous buffer operation. 67118e3e3a7aSWarner Losh(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) 67120495ed39SKyle EvansAfter calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>, 67130495ed39SKyle Evansthe stack is back to its level when the buffer was initialized, 67148e3e3a7aSWarner Loshplus the final string on its top. 67158e3e3a7aSWarner Losh 67168e3e3a7aSWarner Losh 67178e3e3a7aSWarner Losh 67188e3e3a7aSWarner Losh 67198e3e3a7aSWarner Losh 67200495ed39SKyle Evans<hr><h3><a name="luaL_buffaddr"><code>luaL_buffaddr</code></a></h3><p> 67210495ed39SKyle Evans<span class="apii">[-0, +0, –]</span> 67220495ed39SKyle Evans<pre>char *luaL_buffaddr (luaL_Buffer *B);</pre> 67230495ed39SKyle Evans 67240495ed39SKyle Evans<p> 67250495ed39SKyle EvansReturns the address of the current content of buffer <code>B</code> 67260495ed39SKyle Evans(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 67270495ed39SKyle EvansNote that any addition to the buffer may invalidate this address. 67280495ed39SKyle Evans 67290495ed39SKyle Evans 67300495ed39SKyle Evans 67310495ed39SKyle Evans 67320495ed39SKyle Evans 67338e3e3a7aSWarner Losh<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> 6734*8c784bb8SWarner Losh<span class="apii">[-0, +?, –]</span> 67358e3e3a7aSWarner Losh<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> 67368e3e3a7aSWarner Losh 67378e3e3a7aSWarner Losh<p> 67380495ed39SKyle EvansInitializes a buffer <code>B</code> 67390495ed39SKyle Evans(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 67408e3e3a7aSWarner LoshThis function does not allocate any space; 67410495ed39SKyle Evansthe buffer must be declared as a variable. 67420495ed39SKyle Evans 67430495ed39SKyle Evans 67440495ed39SKyle Evans 67450495ed39SKyle Evans 67460495ed39SKyle Evans 67470495ed39SKyle Evans<hr><h3><a name="luaL_bufflen"><code>luaL_bufflen</code></a></h3><p> 67480495ed39SKyle Evans<span class="apii">[-0, +0, –]</span> 67490495ed39SKyle Evans<pre>size_t luaL_bufflen (luaL_Buffer *B);</pre> 67500495ed39SKyle Evans 67510495ed39SKyle Evans<p> 67520495ed39SKyle EvansReturns the length of the current content of buffer <code>B</code> 67538e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 67548e3e3a7aSWarner Losh 67558e3e3a7aSWarner Losh 67568e3e3a7aSWarner Losh 67578e3e3a7aSWarner Losh 67588e3e3a7aSWarner Losh 67598e3e3a7aSWarner Losh<hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p> 67608e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 67618e3e3a7aSWarner Losh<pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre> 67628e3e3a7aSWarner Losh 67638e3e3a7aSWarner Losh<p> 67648e3e3a7aSWarner LoshEquivalent to the sequence 67658e3e3a7aSWarner Losh<a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>. 67668e3e3a7aSWarner Losh 67678e3e3a7aSWarner Losh 67688e3e3a7aSWarner Losh 67698e3e3a7aSWarner Losh 67708e3e3a7aSWarner Losh 67710495ed39SKyle Evans<hr><h3><a name="luaL_buffsub"><code>luaL_buffsub</code></a></h3><p> 6772*8c784bb8SWarner Losh<span class="apii">[-?, +?, –]</span> 67730495ed39SKyle Evans<pre>void luaL_buffsub (luaL_Buffer *B, int n);</pre> 67740495ed39SKyle Evans 67750495ed39SKyle Evans<p> 67760495ed39SKyle EvansRemoves <code>n</code> bytes from the the buffer <code>B</code> 67770495ed39SKyle Evans(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 67780495ed39SKyle EvansThe buffer must have at least that many bytes. 67790495ed39SKyle Evans 67800495ed39SKyle Evans 67810495ed39SKyle Evans 67820495ed39SKyle Evans 67830495ed39SKyle Evans 67848e3e3a7aSWarner Losh<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> 67858e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), <em>e</em>]</span> 67868e3e3a7aSWarner Losh<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> 67878e3e3a7aSWarner Losh 67888e3e3a7aSWarner Losh<p> 67898e3e3a7aSWarner LoshCalls a metamethod. 67908e3e3a7aSWarner Losh 67918e3e3a7aSWarner Losh 67928e3e3a7aSWarner Losh<p> 67938e3e3a7aSWarner LoshIf the object at index <code>obj</code> has a metatable and this 67948e3e3a7aSWarner Loshmetatable has a field <code>e</code>, 67958e3e3a7aSWarner Loshthis function calls this field passing the object as its only argument. 67968e3e3a7aSWarner LoshIn this case this function returns true and pushes onto the 67978e3e3a7aSWarner Loshstack the value returned by the call. 67988e3e3a7aSWarner LoshIf there is no metatable or no metamethod, 67990495ed39SKyle Evansthis function returns false without pushing any value on the stack. 68008e3e3a7aSWarner Losh 68018e3e3a7aSWarner Losh 68028e3e3a7aSWarner Losh 68038e3e3a7aSWarner Losh 68048e3e3a7aSWarner Losh 68058e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> 68068e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 68078e3e3a7aSWarner Losh<pre>void luaL_checkany (lua_State *L, int arg);</pre> 68088e3e3a7aSWarner Losh 68098e3e3a7aSWarner Losh<p> 68108e3e3a7aSWarner LoshChecks whether the function has an argument 68118e3e3a7aSWarner Loshof any type (including <b>nil</b>) at position <code>arg</code>. 68128e3e3a7aSWarner Losh 68138e3e3a7aSWarner Losh 68148e3e3a7aSWarner Losh 68158e3e3a7aSWarner Losh 68168e3e3a7aSWarner Losh 68178e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> 68188e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 68198e3e3a7aSWarner Losh<pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre> 68208e3e3a7aSWarner Losh 68218e3e3a7aSWarner Losh<p> 68228e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is an integer 68238e3e3a7aSWarner Losh(or can be converted to an integer) 68240495ed39SKyle Evansand returns this integer. 68258e3e3a7aSWarner Losh 68268e3e3a7aSWarner Losh 68278e3e3a7aSWarner Losh 68288e3e3a7aSWarner Losh 68298e3e3a7aSWarner Losh 68308e3e3a7aSWarner Losh<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> 68318e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 68328e3e3a7aSWarner Losh<pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre> 68338e3e3a7aSWarner Losh 68348e3e3a7aSWarner Losh<p> 68358e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string 68368e3e3a7aSWarner Loshand returns this string; 68370495ed39SKyle Evansif <code>l</code> is not <code>NULL</code> fills its referent 68388e3e3a7aSWarner Loshwith the string's length. 68398e3e3a7aSWarner Losh 68408e3e3a7aSWarner Losh 68418e3e3a7aSWarner Losh<p> 68428e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 68438e3e3a7aSWarner Loshso all conversions and caveats of that function apply here. 68448e3e3a7aSWarner Losh 68458e3e3a7aSWarner Losh 68468e3e3a7aSWarner Losh 68478e3e3a7aSWarner Losh 68488e3e3a7aSWarner Losh 68498e3e3a7aSWarner Losh<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> 68508e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 68518e3e3a7aSWarner Losh<pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre> 68528e3e3a7aSWarner Losh 68538e3e3a7aSWarner Losh<p> 68548e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a number 68550495ed39SKyle Evansand returns this number converted to a <code>lua_Number</code>. 68568e3e3a7aSWarner Losh 68578e3e3a7aSWarner Losh 68588e3e3a7aSWarner Losh 68598e3e3a7aSWarner Losh 68608e3e3a7aSWarner Losh 68618e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> 68628e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 68638e3e3a7aSWarner Losh<pre>int luaL_checkoption (lua_State *L, 68648e3e3a7aSWarner Losh int arg, 68658e3e3a7aSWarner Losh const char *def, 68668e3e3a7aSWarner Losh const char *const lst[]);</pre> 68678e3e3a7aSWarner Losh 68688e3e3a7aSWarner Losh<p> 68698e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string and 68708e3e3a7aSWarner Loshsearches for this string in the array <code>lst</code> 68718e3e3a7aSWarner Losh(which must be NULL-terminated). 68728e3e3a7aSWarner LoshReturns the index in the array where the string was found. 68738e3e3a7aSWarner LoshRaises an error if the argument is not a string or 68748e3e3a7aSWarner Loshif the string cannot be found. 68758e3e3a7aSWarner Losh 68768e3e3a7aSWarner Losh 68778e3e3a7aSWarner Losh<p> 68788e3e3a7aSWarner LoshIf <code>def</code> is not <code>NULL</code>, 68798e3e3a7aSWarner Loshthe function uses <code>def</code> as a default value when 68808e3e3a7aSWarner Loshthere is no argument <code>arg</code> or when this argument is <b>nil</b>. 68818e3e3a7aSWarner Losh 68828e3e3a7aSWarner Losh 68838e3e3a7aSWarner Losh<p> 68848e3e3a7aSWarner LoshThis is a useful function for mapping strings to C enums. 68858e3e3a7aSWarner Losh(The usual convention in Lua libraries is 68868e3e3a7aSWarner Loshto use strings instead of numbers to select options.) 68878e3e3a7aSWarner Losh 68888e3e3a7aSWarner Losh 68898e3e3a7aSWarner Losh 68908e3e3a7aSWarner Losh 68918e3e3a7aSWarner Losh 68928e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> 68938e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 68948e3e3a7aSWarner Losh<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> 68958e3e3a7aSWarner Losh 68968e3e3a7aSWarner Losh<p> 68978e3e3a7aSWarner LoshGrows the stack size to <code>top + sz</code> elements, 68988e3e3a7aSWarner Loshraising an error if the stack cannot grow to that size. 68998e3e3a7aSWarner Losh<code>msg</code> is an additional text to go into the error message 69008e3e3a7aSWarner Losh(or <code>NULL</code> for no additional text). 69018e3e3a7aSWarner Losh 69028e3e3a7aSWarner Losh 69038e3e3a7aSWarner Losh 69048e3e3a7aSWarner Losh 69058e3e3a7aSWarner Losh 69068e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> 69078e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 69088e3e3a7aSWarner Losh<pre>const char *luaL_checkstring (lua_State *L, int arg);</pre> 69098e3e3a7aSWarner Losh 69108e3e3a7aSWarner Losh<p> 69118e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string 69128e3e3a7aSWarner Loshand returns this string. 69138e3e3a7aSWarner Losh 69148e3e3a7aSWarner Losh 69158e3e3a7aSWarner Losh<p> 69168e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 69178e3e3a7aSWarner Loshso all conversions and caveats of that function apply here. 69188e3e3a7aSWarner Losh 69198e3e3a7aSWarner Losh 69208e3e3a7aSWarner Losh 69218e3e3a7aSWarner Losh 69228e3e3a7aSWarner Losh 69238e3e3a7aSWarner Losh<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> 69248e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 69258e3e3a7aSWarner Losh<pre>void luaL_checktype (lua_State *L, int arg, int t);</pre> 69268e3e3a7aSWarner Losh 69278e3e3a7aSWarner Losh<p> 69288e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> has type <code>t</code>. 69298e3e3a7aSWarner LoshSee <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. 69308e3e3a7aSWarner Losh 69318e3e3a7aSWarner Losh 69328e3e3a7aSWarner Losh 69338e3e3a7aSWarner Losh 69348e3e3a7aSWarner Losh 69358e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> 69368e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 69378e3e3a7aSWarner Losh<pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre> 69388e3e3a7aSWarner Losh 69398e3e3a7aSWarner Losh<p> 69408e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a userdata 69418e3e3a7aSWarner Loshof the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and 69420495ed39SKyle Evansreturns the userdata's memory-block address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>). 69438e3e3a7aSWarner Losh 69448e3e3a7aSWarner Losh 69458e3e3a7aSWarner Losh 69468e3e3a7aSWarner Losh 69478e3e3a7aSWarner Losh 69488e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p> 69498e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 69508e3e3a7aSWarner Losh<pre>void luaL_checkversion (lua_State *L);</pre> 69518e3e3a7aSWarner Losh 69528e3e3a7aSWarner Losh<p> 69530495ed39SKyle EvansChecks whether the code making the call and the Lua library being called 69540495ed39SKyle Evansare using the same version of Lua and the same numeric types. 69558e3e3a7aSWarner Losh 69568e3e3a7aSWarner Losh 69578e3e3a7aSWarner Losh 69588e3e3a7aSWarner Losh 69598e3e3a7aSWarner Losh 69608e3e3a7aSWarner Losh<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> 69610495ed39SKyle Evans<span class="apii">[-0, +?, <em>m</em>]</span> 69628e3e3a7aSWarner Losh<pre>int luaL_dofile (lua_State *L, const char *filename);</pre> 69638e3e3a7aSWarner Losh 69648e3e3a7aSWarner Losh<p> 69658e3e3a7aSWarner LoshLoads and runs the given file. 69668e3e3a7aSWarner LoshIt is defined as the following macro: 69678e3e3a7aSWarner Losh 69688e3e3a7aSWarner Losh<pre> 69698e3e3a7aSWarner Losh (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) 69708e3e3a7aSWarner Losh</pre><p> 69710495ed39SKyle EvansIt returns <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if there are no errors, 69720495ed39SKyle Evansor an error code in case of errors (see <a href="#4.4.1">§4.4.1</a>). 69738e3e3a7aSWarner Losh 69748e3e3a7aSWarner Losh 69758e3e3a7aSWarner Losh 69768e3e3a7aSWarner Losh 69778e3e3a7aSWarner Losh 69788e3e3a7aSWarner Losh<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> 69798e3e3a7aSWarner Losh<span class="apii">[-0, +?, –]</span> 69808e3e3a7aSWarner Losh<pre>int luaL_dostring (lua_State *L, const char *str);</pre> 69818e3e3a7aSWarner Losh 69828e3e3a7aSWarner Losh<p> 69838e3e3a7aSWarner LoshLoads and runs the given string. 69848e3e3a7aSWarner LoshIt is defined as the following macro: 69858e3e3a7aSWarner Losh 69868e3e3a7aSWarner Losh<pre> 69878e3e3a7aSWarner Losh (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) 69888e3e3a7aSWarner Losh</pre><p> 69890495ed39SKyle EvansIt returns <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if there are no errors, 69900495ed39SKyle Evansor an error code in case of errors (see <a href="#4.4.1">§4.4.1</a>). 69918e3e3a7aSWarner Losh 69928e3e3a7aSWarner Losh 69938e3e3a7aSWarner Losh 69948e3e3a7aSWarner Losh 69958e3e3a7aSWarner Losh 69968e3e3a7aSWarner Losh<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> 69978e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 69988e3e3a7aSWarner Losh<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> 69998e3e3a7aSWarner Losh 70008e3e3a7aSWarner Losh<p> 70018e3e3a7aSWarner LoshRaises an error. 70028e3e3a7aSWarner LoshThe error message format is given by <code>fmt</code> 70038e3e3a7aSWarner Loshplus any extra arguments, 70048e3e3a7aSWarner Loshfollowing the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. 70058e3e3a7aSWarner LoshIt also adds at the beginning of the message the file name and 70068e3e3a7aSWarner Loshthe line number where the error occurred, 70078e3e3a7aSWarner Loshif this information is available. 70088e3e3a7aSWarner Losh 70098e3e3a7aSWarner Losh 70108e3e3a7aSWarner Losh<p> 70118e3e3a7aSWarner LoshThis function never returns, 70128e3e3a7aSWarner Loshbut it is an idiom to use it in C functions 70138e3e3a7aSWarner Loshas <code>return luaL_error(<em>args</em>)</code>. 70148e3e3a7aSWarner Losh 70158e3e3a7aSWarner Losh 70168e3e3a7aSWarner Losh 70178e3e3a7aSWarner Losh 70188e3e3a7aSWarner Losh 70198e3e3a7aSWarner Losh<hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p> 70208e3e3a7aSWarner Losh<span class="apii">[-0, +3, <em>m</em>]</span> 70218e3e3a7aSWarner Losh<pre>int luaL_execresult (lua_State *L, int stat);</pre> 70228e3e3a7aSWarner Losh 70238e3e3a7aSWarner Losh<p> 70248e3e3a7aSWarner LoshThis function produces the return values for 70258e3e3a7aSWarner Loshprocess-related functions in the standard library 70268e3e3a7aSWarner Losh(<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>). 70278e3e3a7aSWarner Losh 70288e3e3a7aSWarner Losh 70298e3e3a7aSWarner Losh 70308e3e3a7aSWarner Losh 70318e3e3a7aSWarner Losh 70328e3e3a7aSWarner Losh<hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p> 70338e3e3a7aSWarner Losh<span class="apii">[-0, +(1|3), <em>m</em>]</span> 70348e3e3a7aSWarner Losh<pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre> 70358e3e3a7aSWarner Losh 70368e3e3a7aSWarner Losh<p> 70378e3e3a7aSWarner LoshThis function produces the return values for 70388e3e3a7aSWarner Loshfile-related functions in the standard library 70398e3e3a7aSWarner 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.). 70408e3e3a7aSWarner Losh 70418e3e3a7aSWarner Losh 70428e3e3a7aSWarner Losh 70438e3e3a7aSWarner Losh 70448e3e3a7aSWarner Losh 70458e3e3a7aSWarner Losh<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> 70468e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), <em>m</em>]</span> 70478e3e3a7aSWarner Losh<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> 70488e3e3a7aSWarner Losh 70498e3e3a7aSWarner Losh<p> 70508e3e3a7aSWarner LoshPushes onto the stack the field <code>e</code> from the metatable 7051e112e9d2SKyle Evansof the object at index <code>obj</code> and returns the type of the pushed value. 70528e3e3a7aSWarner LoshIf the object does not have a metatable, 70538e3e3a7aSWarner Loshor if the metatable does not have this field, 70548e3e3a7aSWarner Loshpushes nothing and returns <code>LUA_TNIL</code>. 70558e3e3a7aSWarner Losh 70568e3e3a7aSWarner Losh 70578e3e3a7aSWarner Losh 70588e3e3a7aSWarner Losh 70598e3e3a7aSWarner Losh 70608e3e3a7aSWarner Losh<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> 70618e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 70628e3e3a7aSWarner Losh<pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre> 70638e3e3a7aSWarner Losh 70648e3e3a7aSWarner Losh<p> 70650495ed39SKyle EvansPushes onto the stack the metatable associated with the name <code>tname</code> 70660495ed39SKyle Evansin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>), 70670495ed39SKyle Evansor <b>nil</b> if there is no metatable associated with that name. 70688e3e3a7aSWarner LoshReturns the type of the pushed value. 70698e3e3a7aSWarner Losh 70708e3e3a7aSWarner Losh 70718e3e3a7aSWarner Losh 70728e3e3a7aSWarner Losh 70738e3e3a7aSWarner Losh 70748e3e3a7aSWarner Losh<hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p> 70758e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 70768e3e3a7aSWarner Losh<pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre> 70778e3e3a7aSWarner Losh 70788e3e3a7aSWarner Losh<p> 70798e3e3a7aSWarner LoshEnsures that the value <code>t[fname]</code>, 70808e3e3a7aSWarner Loshwhere <code>t</code> is the value at index <code>idx</code>, 70818e3e3a7aSWarner Loshis a table, 70828e3e3a7aSWarner Loshand pushes that table onto the stack. 70838e3e3a7aSWarner LoshReturns true if it finds a previous table there 70848e3e3a7aSWarner Loshand false if it creates a new table. 70858e3e3a7aSWarner Losh 70868e3e3a7aSWarner Losh 70878e3e3a7aSWarner Losh 70888e3e3a7aSWarner Losh 70898e3e3a7aSWarner Losh 70908e3e3a7aSWarner Losh<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> 70918e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 70928e3e3a7aSWarner Losh<pre>const char *luaL_gsub (lua_State *L, 70938e3e3a7aSWarner Losh const char *s, 70948e3e3a7aSWarner Losh const char *p, 70958e3e3a7aSWarner Losh const char *r);</pre> 70968e3e3a7aSWarner Losh 70978e3e3a7aSWarner Losh<p> 70980495ed39SKyle EvansCreates a copy of string <code>s</code>, 70990495ed39SKyle Evansreplacing any occurrence of the string <code>p</code> 71008e3e3a7aSWarner Loshwith the string <code>r</code>. 71018e3e3a7aSWarner LoshPushes the resulting string on the stack and returns it. 71028e3e3a7aSWarner Losh 71038e3e3a7aSWarner Losh 71048e3e3a7aSWarner Losh 71058e3e3a7aSWarner Losh 71068e3e3a7aSWarner Losh 71078e3e3a7aSWarner Losh<hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p> 71088e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 71098e3e3a7aSWarner Losh<pre>lua_Integer luaL_len (lua_State *L, int index);</pre> 71108e3e3a7aSWarner Losh 71118e3e3a7aSWarner Losh<p> 71128e3e3a7aSWarner LoshReturns the "length" of the value at the given index 71138e3e3a7aSWarner Loshas a number; 71148e3e3a7aSWarner Loshit is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). 71158e3e3a7aSWarner LoshRaises an error if the result of the operation is not an integer. 71160495ed39SKyle Evans(This case can only happen through metamethods.) 71178e3e3a7aSWarner Losh 71188e3e3a7aSWarner Losh 71198e3e3a7aSWarner Losh 71208e3e3a7aSWarner Losh 71218e3e3a7aSWarner Losh 71228e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> 71238e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 71248e3e3a7aSWarner Losh<pre>int luaL_loadbuffer (lua_State *L, 71258e3e3a7aSWarner Losh const char *buff, 71268e3e3a7aSWarner Losh size_t sz, 71278e3e3a7aSWarner Losh const char *name);</pre> 71288e3e3a7aSWarner Losh 71298e3e3a7aSWarner Losh<p> 71308e3e3a7aSWarner LoshEquivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>. 71318e3e3a7aSWarner Losh 71328e3e3a7aSWarner Losh 71338e3e3a7aSWarner Losh 71348e3e3a7aSWarner Losh 71358e3e3a7aSWarner Losh 71368e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p> 71378e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 71388e3e3a7aSWarner Losh<pre>int luaL_loadbufferx (lua_State *L, 71398e3e3a7aSWarner Losh const char *buff, 71408e3e3a7aSWarner Losh size_t sz, 71418e3e3a7aSWarner Losh const char *name, 71428e3e3a7aSWarner Losh const char *mode);</pre> 71438e3e3a7aSWarner Losh 71448e3e3a7aSWarner Losh<p> 71458e3e3a7aSWarner LoshLoads a buffer as a Lua chunk. 71468e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the 71478e3e3a7aSWarner Loshbuffer pointed to by <code>buff</code> with size <code>sz</code>. 71488e3e3a7aSWarner Losh 71498e3e3a7aSWarner Losh 71508e3e3a7aSWarner Losh<p> 71518e3e3a7aSWarner LoshThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 71528e3e3a7aSWarner Losh<code>name</code> is the chunk name, 71538e3e3a7aSWarner Loshused for debug information and error messages. 71540495ed39SKyle EvansThe string <code>mode</code> works as in the function <a href="#lua_load"><code>lua_load</code></a>. 71558e3e3a7aSWarner Losh 71568e3e3a7aSWarner Losh 71578e3e3a7aSWarner Losh 71588e3e3a7aSWarner Losh 71598e3e3a7aSWarner Losh 71608e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> 71618e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 71628e3e3a7aSWarner Losh<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> 71638e3e3a7aSWarner Losh 71648e3e3a7aSWarner Losh<p> 71658e3e3a7aSWarner LoshEquivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>. 71668e3e3a7aSWarner Losh 71678e3e3a7aSWarner Losh 71688e3e3a7aSWarner Losh 71698e3e3a7aSWarner Losh 71708e3e3a7aSWarner Losh 71718e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p> 71728e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 71738e3e3a7aSWarner Losh<pre>int luaL_loadfilex (lua_State *L, const char *filename, 71748e3e3a7aSWarner Losh const char *mode);</pre> 71758e3e3a7aSWarner Losh 71768e3e3a7aSWarner Losh<p> 71778e3e3a7aSWarner LoshLoads a file as a Lua chunk. 71788e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file 71798e3e3a7aSWarner Loshnamed <code>filename</code>. 71808e3e3a7aSWarner LoshIf <code>filename</code> is <code>NULL</code>, 71818e3e3a7aSWarner Loshthen it loads from the standard input. 71828e3e3a7aSWarner LoshThe first line in the file is ignored if it starts with a <code>#</code>. 71838e3e3a7aSWarner Losh 71848e3e3a7aSWarner Losh 71858e3e3a7aSWarner Losh<p> 71860495ed39SKyle EvansThe string <code>mode</code> works as in the function <a href="#lua_load"><code>lua_load</code></a>. 71878e3e3a7aSWarner Losh 71888e3e3a7aSWarner Losh 71898e3e3a7aSWarner Losh<p> 71900495ed39SKyle EvansThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a> 71910495ed39SKyle Evansor <a href="#pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> for file-related errors. 71928e3e3a7aSWarner Losh 71938e3e3a7aSWarner Losh 71948e3e3a7aSWarner Losh<p> 71958e3e3a7aSWarner LoshAs <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 71968e3e3a7aSWarner Loshit does not run it. 71978e3e3a7aSWarner Losh 71988e3e3a7aSWarner Losh 71998e3e3a7aSWarner Losh 72008e3e3a7aSWarner Losh 72018e3e3a7aSWarner Losh 72028e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> 72038e3e3a7aSWarner Losh<span class="apii">[-0, +1, –]</span> 72048e3e3a7aSWarner Losh<pre>int luaL_loadstring (lua_State *L, const char *s);</pre> 72058e3e3a7aSWarner Losh 72068e3e3a7aSWarner Losh<p> 72078e3e3a7aSWarner LoshLoads a string as a Lua chunk. 72088e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in 72098e3e3a7aSWarner Loshthe zero-terminated string <code>s</code>. 72108e3e3a7aSWarner Losh 72118e3e3a7aSWarner Losh 72128e3e3a7aSWarner Losh<p> 72138e3e3a7aSWarner LoshThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 72148e3e3a7aSWarner Losh 72158e3e3a7aSWarner Losh 72168e3e3a7aSWarner Losh<p> 72178e3e3a7aSWarner LoshAlso as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 72188e3e3a7aSWarner Loshit does not run it. 72198e3e3a7aSWarner Losh 72208e3e3a7aSWarner Losh 72218e3e3a7aSWarner Losh 72228e3e3a7aSWarner Losh 72238e3e3a7aSWarner Losh 72248e3e3a7aSWarner Losh<hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p> 72258e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 72268e3e3a7aSWarner Losh<pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre> 72278e3e3a7aSWarner Losh 72288e3e3a7aSWarner Losh<p> 72298e3e3a7aSWarner LoshCreates a new table and registers there 72300495ed39SKyle Evansthe functions in the list <code>l</code>. 72318e3e3a7aSWarner Losh 72328e3e3a7aSWarner Losh 72338e3e3a7aSWarner Losh<p> 72348e3e3a7aSWarner LoshIt is implemented as the following macro: 72358e3e3a7aSWarner Losh 72368e3e3a7aSWarner Losh<pre> 72378e3e3a7aSWarner Losh (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0)) 72388e3e3a7aSWarner Losh</pre><p> 72398e3e3a7aSWarner LoshThe array <code>l</code> must be the actual array, 72408e3e3a7aSWarner Loshnot a pointer to it. 72418e3e3a7aSWarner Losh 72428e3e3a7aSWarner Losh 72438e3e3a7aSWarner Losh 72448e3e3a7aSWarner Losh 72458e3e3a7aSWarner Losh 72468e3e3a7aSWarner Losh<hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p> 72478e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 72488e3e3a7aSWarner Losh<pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre> 72498e3e3a7aSWarner Losh 72508e3e3a7aSWarner Losh<p> 72518e3e3a7aSWarner LoshCreates a new table with a size optimized 72528e3e3a7aSWarner Loshto store all entries in the array <code>l</code> 72538e3e3a7aSWarner Losh(but does not actually store them). 72548e3e3a7aSWarner LoshIt is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> 72558e3e3a7aSWarner Losh(see <a href="#luaL_newlib"><code>luaL_newlib</code></a>). 72568e3e3a7aSWarner Losh 72578e3e3a7aSWarner Losh 72588e3e3a7aSWarner Losh<p> 72598e3e3a7aSWarner LoshIt is implemented as a macro. 72608e3e3a7aSWarner LoshThe array <code>l</code> must be the actual array, 72618e3e3a7aSWarner Loshnot a pointer to it. 72628e3e3a7aSWarner Losh 72638e3e3a7aSWarner Losh 72648e3e3a7aSWarner Losh 72658e3e3a7aSWarner Losh 72668e3e3a7aSWarner Losh 72678e3e3a7aSWarner Losh<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> 72688e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 72698e3e3a7aSWarner Losh<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> 72708e3e3a7aSWarner Losh 72718e3e3a7aSWarner Losh<p> 72728e3e3a7aSWarner LoshIf the registry already has the key <code>tname</code>, 72738e3e3a7aSWarner Loshreturns 0. 72748e3e3a7aSWarner LoshOtherwise, 72758e3e3a7aSWarner Loshcreates a new table to be used as a metatable for userdata, 72768e3e3a7aSWarner Loshadds to this new table the pair <code>__name = tname</code>, 72778e3e3a7aSWarner Loshadds to the registry the pair <code>[tname] = new table</code>, 72788e3e3a7aSWarner Loshand returns 1. 72798e3e3a7aSWarner Losh 72808e3e3a7aSWarner Losh 72818e3e3a7aSWarner Losh<p> 72820495ed39SKyle EvansIn both cases, 72830495ed39SKyle Evansthe function pushes onto the stack the final value associated 72848e3e3a7aSWarner Loshwith <code>tname</code> in the registry. 72858e3e3a7aSWarner Losh 72868e3e3a7aSWarner Losh 72878e3e3a7aSWarner Losh 72888e3e3a7aSWarner Losh 72898e3e3a7aSWarner Losh 72908e3e3a7aSWarner Losh<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> 72918e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 72928e3e3a7aSWarner Losh<pre>lua_State *luaL_newstate (void);</pre> 72938e3e3a7aSWarner Losh 72948e3e3a7aSWarner Losh<p> 72958e3e3a7aSWarner LoshCreates a new Lua state. 72968e3e3a7aSWarner LoshIt calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an 72970495ed39SKyle Evansallocator based on the standard C allocation functions 72980495ed39SKyle Evansand then sets a warning function and a panic function (see <a href="#4.4">§4.4</a>) 72990495ed39SKyle Evansthat print messages to the standard error output. 73008e3e3a7aSWarner Losh 73018e3e3a7aSWarner Losh 73028e3e3a7aSWarner Losh<p> 73038e3e3a7aSWarner LoshReturns the new state, 73048e3e3a7aSWarner Loshor <code>NULL</code> if there is a memory allocation error. 73058e3e3a7aSWarner Losh 73068e3e3a7aSWarner Losh 73078e3e3a7aSWarner Losh 73088e3e3a7aSWarner Losh 73098e3e3a7aSWarner Losh 73108e3e3a7aSWarner Losh<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> 73118e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span> 73128e3e3a7aSWarner Losh<pre>void luaL_openlibs (lua_State *L);</pre> 73138e3e3a7aSWarner Losh 73148e3e3a7aSWarner Losh<p> 73158e3e3a7aSWarner LoshOpens all standard Lua libraries into the given state. 73168e3e3a7aSWarner Losh 73178e3e3a7aSWarner Losh 73188e3e3a7aSWarner Losh 73198e3e3a7aSWarner Losh 73208e3e3a7aSWarner Losh 73218e3e3a7aSWarner Losh<hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p> 73220495ed39SKyle Evans<span class="apii">[-0, +0, –]</span> 73238e3e3a7aSWarner Losh<pre>T luaL_opt (L, func, arg, dflt);</pre> 73248e3e3a7aSWarner Losh 73258e3e3a7aSWarner Losh<p> 73268e3e3a7aSWarner LoshThis macro is defined as follows: 73278e3e3a7aSWarner Losh 73288e3e3a7aSWarner Losh<pre> 73298e3e3a7aSWarner Losh (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg))) 73308e3e3a7aSWarner Losh</pre><p> 73318e3e3a7aSWarner LoshIn words, if the argument <code>arg</code> is nil or absent, 73328e3e3a7aSWarner Loshthe macro results in the default <code>dflt</code>. 73338e3e3a7aSWarner LoshOtherwise, it results in the result of calling <code>func</code> 73348e3e3a7aSWarner Loshwith the state <code>L</code> and the argument index <code>arg</code> as 7335e112e9d2SKyle Evansarguments. 73368e3e3a7aSWarner LoshNote that it evaluates the expression <code>dflt</code> only if needed. 73378e3e3a7aSWarner Losh 73388e3e3a7aSWarner Losh 73398e3e3a7aSWarner Losh 73408e3e3a7aSWarner Losh 73418e3e3a7aSWarner Losh 73428e3e3a7aSWarner Losh<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> 73438e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 73448e3e3a7aSWarner Losh<pre>lua_Integer luaL_optinteger (lua_State *L, 73458e3e3a7aSWarner Losh int arg, 73468e3e3a7aSWarner Losh lua_Integer d);</pre> 73478e3e3a7aSWarner Losh 73488e3e3a7aSWarner Losh<p> 73498e3e3a7aSWarner LoshIf the function argument <code>arg</code> is an integer 73500495ed39SKyle Evans(or it is convertible to an integer), 73518e3e3a7aSWarner Loshreturns this integer. 73528e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>, 73538e3e3a7aSWarner Loshreturns <code>d</code>. 73548e3e3a7aSWarner LoshOtherwise, raises an error. 73558e3e3a7aSWarner Losh 73568e3e3a7aSWarner Losh 73578e3e3a7aSWarner Losh 73588e3e3a7aSWarner Losh 73598e3e3a7aSWarner Losh 73608e3e3a7aSWarner Losh<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> 73618e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 73628e3e3a7aSWarner Losh<pre>const char *luaL_optlstring (lua_State *L, 73638e3e3a7aSWarner Losh int arg, 73648e3e3a7aSWarner Losh const char *d, 73658e3e3a7aSWarner Losh size_t *l);</pre> 73668e3e3a7aSWarner Losh 73678e3e3a7aSWarner Losh<p> 73688e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a string, 73698e3e3a7aSWarner Loshreturns this string. 73708e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>, 73718e3e3a7aSWarner Loshreturns <code>d</code>. 73728e3e3a7aSWarner LoshOtherwise, raises an error. 73738e3e3a7aSWarner Losh 73748e3e3a7aSWarner Losh 73758e3e3a7aSWarner Losh<p> 73768e3e3a7aSWarner LoshIf <code>l</code> is not <code>NULL</code>, 73770495ed39SKyle Evansfills its referent with the result's length. 73788e3e3a7aSWarner LoshIf the result is <code>NULL</code> 73798e3e3a7aSWarner Losh(only possible when returning <code>d</code> and <code>d == NULL</code>), 73808e3e3a7aSWarner Loshits length is considered zero. 73818e3e3a7aSWarner Losh 73828e3e3a7aSWarner Losh 73838e3e3a7aSWarner Losh<p> 73848e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 73858e3e3a7aSWarner Loshso all conversions and caveats of that function apply here. 73868e3e3a7aSWarner Losh 73878e3e3a7aSWarner Losh 73888e3e3a7aSWarner Losh 73898e3e3a7aSWarner Losh 73908e3e3a7aSWarner Losh 73918e3e3a7aSWarner Losh<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> 73928e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 73938e3e3a7aSWarner Losh<pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre> 73948e3e3a7aSWarner Losh 73958e3e3a7aSWarner Losh<p> 73968e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a number, 73970495ed39SKyle Evansreturns this number as a <code>lua_Number</code>. 73988e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>, 73998e3e3a7aSWarner Loshreturns <code>d</code>. 74008e3e3a7aSWarner LoshOtherwise, raises an error. 74018e3e3a7aSWarner Losh 74028e3e3a7aSWarner Losh 74038e3e3a7aSWarner Losh 74048e3e3a7aSWarner Losh 74058e3e3a7aSWarner Losh 74068e3e3a7aSWarner Losh<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> 74078e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span> 74088e3e3a7aSWarner Losh<pre>const char *luaL_optstring (lua_State *L, 74098e3e3a7aSWarner Losh int arg, 74108e3e3a7aSWarner Losh const char *d);</pre> 74118e3e3a7aSWarner Losh 74128e3e3a7aSWarner Losh<p> 74138e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a string, 74148e3e3a7aSWarner Loshreturns this string. 74158e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>, 74168e3e3a7aSWarner Loshreturns <code>d</code>. 74178e3e3a7aSWarner LoshOtherwise, raises an error. 74188e3e3a7aSWarner Losh 74198e3e3a7aSWarner Losh 74208e3e3a7aSWarner Losh 74218e3e3a7aSWarner Losh 74228e3e3a7aSWarner Losh 74238e3e3a7aSWarner Losh<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> 74248e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 74258e3e3a7aSWarner Losh<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> 74268e3e3a7aSWarner Losh 74278e3e3a7aSWarner Losh<p> 74288e3e3a7aSWarner LoshEquivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a> 74298e3e3a7aSWarner Loshwith the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>. 74308e3e3a7aSWarner Losh 74318e3e3a7aSWarner Losh 74328e3e3a7aSWarner Losh 74338e3e3a7aSWarner Losh 74348e3e3a7aSWarner Losh 74358e3e3a7aSWarner Losh<hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p> 74368e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span> 74378e3e3a7aSWarner Losh<pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre> 74388e3e3a7aSWarner Losh 74398e3e3a7aSWarner Losh<p> 74408e3e3a7aSWarner LoshReturns an address to a space of size <code>sz</code> 74418e3e3a7aSWarner Loshwhere you can copy a string to be added to buffer <code>B</code> 74428e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 74438e3e3a7aSWarner LoshAfter copying the string into this space you must call 74448e3e3a7aSWarner Losh<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add 74458e3e3a7aSWarner Loshit to the buffer. 74468e3e3a7aSWarner Losh 74478e3e3a7aSWarner Losh 74488e3e3a7aSWarner Losh 74498e3e3a7aSWarner Losh 74508e3e3a7aSWarner Losh 74510495ed39SKyle Evans<hr><h3><a name="luaL_pushfail"><code>luaL_pushfail</code></a></h3><p> 74520495ed39SKyle Evans<span class="apii">[-0, +1, –]</span> 74530495ed39SKyle Evans<pre>void luaL_pushfail (lua_State *L);</pre> 74540495ed39SKyle Evans 74550495ed39SKyle Evans<p> 74560495ed39SKyle EvansPushes the <b>fail</b> value onto the stack (see <a href="#6">§6</a>). 74570495ed39SKyle Evans 74580495ed39SKyle Evans 74590495ed39SKyle Evans 74600495ed39SKyle Evans 74610495ed39SKyle Evans 74628e3e3a7aSWarner Losh<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> 74638e3e3a7aSWarner Losh<span class="apii">[-?, +1, <em>m</em>]</span> 74648e3e3a7aSWarner Losh<pre>void luaL_pushresult (luaL_Buffer *B);</pre> 74658e3e3a7aSWarner Losh 74668e3e3a7aSWarner Losh<p> 74678e3e3a7aSWarner LoshFinishes the use of buffer <code>B</code> leaving the final string on 74688e3e3a7aSWarner Loshthe top of the stack. 74698e3e3a7aSWarner Losh 74708e3e3a7aSWarner Losh 74718e3e3a7aSWarner Losh 74728e3e3a7aSWarner Losh 74738e3e3a7aSWarner Losh 74748e3e3a7aSWarner Losh<hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p> 74758e3e3a7aSWarner Losh<span class="apii">[-?, +1, <em>m</em>]</span> 74768e3e3a7aSWarner Losh<pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre> 74778e3e3a7aSWarner Losh 74788e3e3a7aSWarner Losh<p> 74798e3e3a7aSWarner LoshEquivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>. 74808e3e3a7aSWarner Losh 74818e3e3a7aSWarner Losh 74828e3e3a7aSWarner Losh 74838e3e3a7aSWarner Losh 74848e3e3a7aSWarner Losh 74858e3e3a7aSWarner Losh<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> 74868e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span> 74878e3e3a7aSWarner Losh<pre>int luaL_ref (lua_State *L, int t);</pre> 74888e3e3a7aSWarner Losh 74898e3e3a7aSWarner Losh<p> 74908e3e3a7aSWarner LoshCreates and returns a <em>reference</em>, 74918e3e3a7aSWarner Loshin the table at index <code>t</code>, 74920495ed39SKyle Evansfor the object on the top of the stack (and pops the object). 74938e3e3a7aSWarner Losh 74948e3e3a7aSWarner Losh 74958e3e3a7aSWarner Losh<p> 74968e3e3a7aSWarner LoshA reference is a unique integer key. 74970495ed39SKyle EvansAs long as you do not manually add integer keys into the table <code>t</code>, 74988e3e3a7aSWarner Losh<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. 74990495ed39SKyle EvansYou can retrieve an object referred by the reference <code>r</code> 75008e3e3a7aSWarner Loshby calling <code>lua_rawgeti(L, t, r)</code>. 75010495ed39SKyle EvansThe function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference. 75028e3e3a7aSWarner Losh 75038e3e3a7aSWarner Losh 75048e3e3a7aSWarner Losh<p> 75050495ed39SKyle EvansIf the object on the top of the stack is <b>nil</b>, 75068e3e3a7aSWarner Losh<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>. 75078e3e3a7aSWarner LoshThe constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different 75088e3e3a7aSWarner Loshfrom any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. 75098e3e3a7aSWarner Losh 75108e3e3a7aSWarner Losh 75118e3e3a7aSWarner Losh 75128e3e3a7aSWarner Losh 75138e3e3a7aSWarner Losh 75148e3e3a7aSWarner Losh<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> 75158e3e3a7aSWarner Losh<pre>typedef struct luaL_Reg { 75168e3e3a7aSWarner Losh const char *name; 75178e3e3a7aSWarner Losh lua_CFunction func; 75188e3e3a7aSWarner Losh} luaL_Reg;</pre> 75198e3e3a7aSWarner Losh 75208e3e3a7aSWarner Losh<p> 75218e3e3a7aSWarner LoshType for arrays of functions to be registered by 75228e3e3a7aSWarner Losh<a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>. 75238e3e3a7aSWarner Losh<code>name</code> is the function name and <code>func</code> is a pointer to 75248e3e3a7aSWarner Loshthe function. 75258e3e3a7aSWarner LoshAny array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry 75268e3e3a7aSWarner Loshin which both <code>name</code> and <code>func</code> are <code>NULL</code>. 75278e3e3a7aSWarner Losh 75288e3e3a7aSWarner Losh 75298e3e3a7aSWarner Losh 75308e3e3a7aSWarner Losh 75318e3e3a7aSWarner Losh 75328e3e3a7aSWarner Losh<hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p> 75338e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 75348e3e3a7aSWarner Losh<pre>void luaL_requiref (lua_State *L, const char *modname, 75358e3e3a7aSWarner Losh lua_CFunction openf, int glb);</pre> 75368e3e3a7aSWarner Losh 75378e3e3a7aSWarner Losh<p> 75380495ed39SKyle EvansIf <code>package.loaded[modname]</code> is not true, 75390495ed39SKyle Evanscalls the function <code>openf</code> with the string <code>modname</code> as an argument 75400495ed39SKyle Evansand sets the call result to <code>package.loaded[modname]</code>, 75418e3e3a7aSWarner Loshas if that function has been called through <a href="#pdf-require"><code>require</code></a>. 75428e3e3a7aSWarner Losh 75438e3e3a7aSWarner Losh 75448e3e3a7aSWarner Losh<p> 75458e3e3a7aSWarner LoshIf <code>glb</code> is true, 75460495ed39SKyle Evansalso stores the module into the global <code>modname</code>. 75478e3e3a7aSWarner Losh 75488e3e3a7aSWarner Losh 75498e3e3a7aSWarner Losh<p> 75508e3e3a7aSWarner LoshLeaves a copy of the module on the stack. 75518e3e3a7aSWarner Losh 75528e3e3a7aSWarner Losh 75538e3e3a7aSWarner Losh 75548e3e3a7aSWarner Losh 75558e3e3a7aSWarner Losh 75568e3e3a7aSWarner Losh<hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p> 75578e3e3a7aSWarner Losh<span class="apii">[-nup, +0, <em>m</em>]</span> 75588e3e3a7aSWarner Losh<pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre> 75598e3e3a7aSWarner Losh 75608e3e3a7aSWarner Losh<p> 75618e3e3a7aSWarner LoshRegisters all functions in the array <code>l</code> 75628e3e3a7aSWarner Losh(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack 75638e3e3a7aSWarner Losh(below optional upvalues, see next). 75648e3e3a7aSWarner Losh 75658e3e3a7aSWarner Losh 75668e3e3a7aSWarner Losh<p> 75678e3e3a7aSWarner LoshWhen <code>nup</code> is not zero, 75680495ed39SKyle Evansall functions are created with <code>nup</code> upvalues, 75690495ed39SKyle Evansinitialized with copies of the <code>nup</code> values 75700495ed39SKyle Evanspreviously pushed on the stack 75718e3e3a7aSWarner Loshon top of the library table. 75728e3e3a7aSWarner LoshThese values are popped from the stack after the registration. 75738e3e3a7aSWarner Losh 75748e3e3a7aSWarner Losh 7575*8c784bb8SWarner Losh<p> 7576*8c784bb8SWarner LoshA function with a <code>NULL</code> value represents a placeholder, 7577*8c784bb8SWarner Loshwhich is filled with <b>false</b>. 7578*8c784bb8SWarner Losh 7579*8c784bb8SWarner Losh 75808e3e3a7aSWarner Losh 75818e3e3a7aSWarner Losh 75828e3e3a7aSWarner Losh 75838e3e3a7aSWarner Losh<hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p> 75848e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 75858e3e3a7aSWarner Losh<pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre> 75868e3e3a7aSWarner Losh 75878e3e3a7aSWarner Losh<p> 75880495ed39SKyle EvansSets the metatable of the object on the top of the stack 75898e3e3a7aSWarner Loshas the metatable associated with name <code>tname</code> 75908e3e3a7aSWarner Loshin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 75918e3e3a7aSWarner Losh 75928e3e3a7aSWarner Losh 75938e3e3a7aSWarner Losh 75948e3e3a7aSWarner Losh 75958e3e3a7aSWarner Losh 75968e3e3a7aSWarner Losh<hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3> 75978e3e3a7aSWarner Losh<pre>typedef struct luaL_Stream { 75988e3e3a7aSWarner Losh FILE *f; 75998e3e3a7aSWarner Losh lua_CFunction closef; 76008e3e3a7aSWarner Losh} luaL_Stream;</pre> 76018e3e3a7aSWarner Losh 76028e3e3a7aSWarner Losh<p> 76030495ed39SKyle EvansThe standard representation for file handles 76040495ed39SKyle Evansused by the standard I/O library. 76058e3e3a7aSWarner Losh 76068e3e3a7aSWarner Losh 76078e3e3a7aSWarner Losh<p> 76088e3e3a7aSWarner LoshA file handle is implemented as a full userdata, 76098e3e3a7aSWarner Loshwith a metatable called <code>LUA_FILEHANDLE</code> 76108e3e3a7aSWarner Losh(where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name). 76118e3e3a7aSWarner LoshThe metatable is created by the I/O library 76128e3e3a7aSWarner Losh(see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 76138e3e3a7aSWarner Losh 76148e3e3a7aSWarner Losh 76158e3e3a7aSWarner Losh<p> 76168e3e3a7aSWarner LoshThis userdata must start with the structure <code>luaL_Stream</code>; 76178e3e3a7aSWarner Loshit can contain other data after this initial structure. 76180495ed39SKyle EvansThe field <code>f</code> points to the corresponding C stream 76198e3e3a7aSWarner Losh(or it can be <code>NULL</code> to indicate an incompletely created handle). 76200495ed39SKyle EvansThe field <code>closef</code> points to a Lua function 76218e3e3a7aSWarner Loshthat will be called to close the stream 76228e3e3a7aSWarner Loshwhen the handle is closed or collected; 76238e3e3a7aSWarner Loshthis function receives the file handle as its sole argument and 76240495ed39SKyle Evansmust return either a true value, in case of success, 76250495ed39SKyle Evansor a false value plus an error message, in case of error. 76268e3e3a7aSWarner LoshOnce Lua calls this field, 76278e3e3a7aSWarner Loshit changes the field value to <code>NULL</code> 76288e3e3a7aSWarner Loshto signal that the handle is closed. 76298e3e3a7aSWarner Losh 76308e3e3a7aSWarner Losh 76318e3e3a7aSWarner Losh 76328e3e3a7aSWarner Losh 76338e3e3a7aSWarner Losh 76348e3e3a7aSWarner Losh<hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p> 76358e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span> 76368e3e3a7aSWarner Losh<pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre> 76378e3e3a7aSWarner Losh 76388e3e3a7aSWarner Losh<p> 76398e3e3a7aSWarner LoshThis function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>, 76408e3e3a7aSWarner Loshexcept that, when the test fails, 76418e3e3a7aSWarner Loshit returns <code>NULL</code> instead of raising an error. 76428e3e3a7aSWarner Losh 76438e3e3a7aSWarner Losh 76448e3e3a7aSWarner Losh 76458e3e3a7aSWarner Losh 76468e3e3a7aSWarner Losh 76478e3e3a7aSWarner Losh<hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p> 76488e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span> 76498e3e3a7aSWarner Losh<pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre> 76508e3e3a7aSWarner Losh 76518e3e3a7aSWarner Losh<p> 76528e3e3a7aSWarner LoshConverts any Lua value at the given index to a C string 76538e3e3a7aSWarner Loshin a reasonable format. 76548e3e3a7aSWarner LoshThe resulting string is pushed onto the stack and also 76550495ed39SKyle Evansreturned by the function (see <a href="#4.1.3">§4.1.3</a>). 76568e3e3a7aSWarner LoshIf <code>len</code> is not <code>NULL</code>, 76578e3e3a7aSWarner Loshthe function also sets <code>*len</code> with the string length. 76588e3e3a7aSWarner Losh 76598e3e3a7aSWarner Losh 76608e3e3a7aSWarner Losh<p> 76618e3e3a7aSWarner LoshIf the value has a metatable with a <code>__tostring</code> field, 76628e3e3a7aSWarner Loshthen <code>luaL_tolstring</code> calls the corresponding metamethod 76638e3e3a7aSWarner Loshwith the value as argument, 76648e3e3a7aSWarner Loshand uses the result of the call as its result. 76658e3e3a7aSWarner Losh 76668e3e3a7aSWarner Losh 76678e3e3a7aSWarner Losh 76688e3e3a7aSWarner Losh 76698e3e3a7aSWarner Losh 76708e3e3a7aSWarner Losh<hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p> 76718e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 76728e3e3a7aSWarner Losh<pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, 76738e3e3a7aSWarner Losh int level);</pre> 76748e3e3a7aSWarner Losh 76758e3e3a7aSWarner Losh<p> 76768e3e3a7aSWarner LoshCreates and pushes a traceback of the stack <code>L1</code>. 76770495ed39SKyle EvansIf <code>msg</code> is not <code>NULL</code>, it is appended 76788e3e3a7aSWarner Loshat the beginning of the traceback. 76798e3e3a7aSWarner LoshThe <code>level</code> parameter tells at which level 76808e3e3a7aSWarner Loshto start the traceback. 76818e3e3a7aSWarner Losh 76828e3e3a7aSWarner Losh 76838e3e3a7aSWarner Losh 76848e3e3a7aSWarner Losh 76858e3e3a7aSWarner Losh 76860495ed39SKyle Evans<hr><h3><a name="luaL_typeerror"><code>luaL_typeerror</code></a></h3><p> 76870495ed39SKyle Evans<span class="apii">[-0, +0, <em>v</em>]</span> 76880495ed39SKyle Evans<pre>const char *luaL_typeerror (lua_State *L, 76890495ed39SKyle Evans int arg, 76900495ed39SKyle Evans const char *tname);</pre> 76910495ed39SKyle Evans 76920495ed39SKyle Evans<p> 76930495ed39SKyle EvansRaises a type error for the argument <code>arg</code> 76940495ed39SKyle Evansof the C function that called it, 76950495ed39SKyle Evansusing a standard message; 76960495ed39SKyle Evans<code>tname</code> is a "name" for the expected type. 76970495ed39SKyle EvansThis function never returns. 76980495ed39SKyle Evans 76990495ed39SKyle Evans 77000495ed39SKyle Evans 77010495ed39SKyle Evans 77020495ed39SKyle Evans 77038e3e3a7aSWarner Losh<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> 77048e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 77058e3e3a7aSWarner Losh<pre>const char *luaL_typename (lua_State *L, int index);</pre> 77068e3e3a7aSWarner Losh 77078e3e3a7aSWarner Losh<p> 77088e3e3a7aSWarner LoshReturns the name of the type of the value at the given index. 77098e3e3a7aSWarner Losh 77108e3e3a7aSWarner Losh 77118e3e3a7aSWarner Losh 77128e3e3a7aSWarner Losh 77138e3e3a7aSWarner Losh 77148e3e3a7aSWarner Losh<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> 77158e3e3a7aSWarner Losh<span class="apii">[-0, +0, –]</span> 77168e3e3a7aSWarner Losh<pre>void luaL_unref (lua_State *L, int t, int ref);</pre> 77178e3e3a7aSWarner Losh 77188e3e3a7aSWarner Losh<p> 77190495ed39SKyle EvansReleases the reference <code>ref</code> from the table at index <code>t</code> 77208e3e3a7aSWarner Losh(see <a href="#luaL_ref"><code>luaL_ref</code></a>). 77218e3e3a7aSWarner LoshThe entry is removed from the table, 77228e3e3a7aSWarner Loshso that the referred object can be collected. 77238e3e3a7aSWarner LoshThe reference <code>ref</code> is also freed to be used again. 77248e3e3a7aSWarner Losh 77258e3e3a7aSWarner Losh 77268e3e3a7aSWarner Losh<p> 77278e3e3a7aSWarner 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>, 77288e3e3a7aSWarner Losh<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. 77298e3e3a7aSWarner Losh 77308e3e3a7aSWarner Losh 77318e3e3a7aSWarner Losh 77328e3e3a7aSWarner Losh 77338e3e3a7aSWarner Losh 77348e3e3a7aSWarner Losh<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> 77358e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span> 77368e3e3a7aSWarner Losh<pre>void luaL_where (lua_State *L, int lvl);</pre> 77378e3e3a7aSWarner Losh 77388e3e3a7aSWarner Losh<p> 77398e3e3a7aSWarner LoshPushes onto the stack a string identifying the current position 77408e3e3a7aSWarner Loshof the control at level <code>lvl</code> in the call stack. 77418e3e3a7aSWarner LoshTypically this string has the following format: 77428e3e3a7aSWarner Losh 77438e3e3a7aSWarner Losh<pre> 77448e3e3a7aSWarner Losh <em>chunkname</em>:<em>currentline</em>: 77458e3e3a7aSWarner Losh</pre><p> 77468e3e3a7aSWarner LoshLevel 0 is the running function, 77478e3e3a7aSWarner Loshlevel 1 is the function that called the running function, 77488e3e3a7aSWarner Loshetc. 77498e3e3a7aSWarner Losh 77508e3e3a7aSWarner Losh 77518e3e3a7aSWarner Losh<p> 77528e3e3a7aSWarner LoshThis function is used to build a prefix for error messages. 77538e3e3a7aSWarner Losh 77548e3e3a7aSWarner Losh 77558e3e3a7aSWarner Losh 77568e3e3a7aSWarner Losh 77578e3e3a7aSWarner Losh 77588e3e3a7aSWarner Losh 77598e3e3a7aSWarner Losh 77600495ed39SKyle Evans<h1>6 – <a name="6">The Standard Libraries</a></h1> 77610495ed39SKyle Evans 77620495ed39SKyle Evans 77638e3e3a7aSWarner Losh 77648e3e3a7aSWarner Losh<p> 77658e3e3a7aSWarner LoshThe standard Lua libraries provide useful functions 77660495ed39SKyle Evansthat are implemented in C through the C API. 77678e3e3a7aSWarner LoshSome of these functions provide essential services to the language 77688e3e3a7aSWarner Losh(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); 77690495ed39SKyle Evansothers provide access to outside services (e.g., I/O); 77708e3e3a7aSWarner Loshand others could be implemented in Lua itself, 77710495ed39SKyle Evansbut that for different reasons 77728e3e3a7aSWarner Loshdeserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). 77738e3e3a7aSWarner Losh 77748e3e3a7aSWarner Losh 77758e3e3a7aSWarner Losh<p> 77768e3e3a7aSWarner LoshAll libraries are implemented through the official C API 77778e3e3a7aSWarner Loshand are provided as separate C modules. 77780495ed39SKyle EvansUnless otherwise noted, 77790495ed39SKyle Evansthese library functions do not adjust its number of arguments 77800495ed39SKyle Evansto its expected parameters. 77810495ed39SKyle EvansFor instance, a function documented as <code>foo(arg)</code> 77820495ed39SKyle Evansshould not be called without an argument. 77830495ed39SKyle Evans 77840495ed39SKyle Evans 77850495ed39SKyle Evans<p> 77860495ed39SKyle EvansThe notation <b>fail</b> means a false value representing 77870495ed39SKyle Evanssome kind of failure. 77880495ed39SKyle Evans(Currently, <b>fail</b> is equal to <b>nil</b>, 77890495ed39SKyle Evansbut that may change in future versions. 77900495ed39SKyle EvansThe recommendation is to always test the success of these functions 77910495ed39SKyle Evanswith <code>(not status)</code>, instead of <code>(status == nil)</code>.) 77920495ed39SKyle Evans 77930495ed39SKyle Evans 77940495ed39SKyle Evans<p> 77958e3e3a7aSWarner LoshCurrently, Lua has the following standard libraries: 77968e3e3a7aSWarner Losh 77978e3e3a7aSWarner Losh<ul> 77988e3e3a7aSWarner Losh 77998e3e3a7aSWarner Losh<li>basic library (<a href="#6.1">§6.1</a>);</li> 78008e3e3a7aSWarner Losh 78018e3e3a7aSWarner Losh<li>coroutine library (<a href="#6.2">§6.2</a>);</li> 78028e3e3a7aSWarner Losh 78038e3e3a7aSWarner Losh<li>package library (<a href="#6.3">§6.3</a>);</li> 78048e3e3a7aSWarner Losh 78058e3e3a7aSWarner Losh<li>string manipulation (<a href="#6.4">§6.4</a>);</li> 78068e3e3a7aSWarner Losh 78078e3e3a7aSWarner Losh<li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li> 78088e3e3a7aSWarner Losh 78098e3e3a7aSWarner Losh<li>table manipulation (<a href="#6.6">§6.6</a>);</li> 78108e3e3a7aSWarner Losh 78118e3e3a7aSWarner Losh<li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li> 78128e3e3a7aSWarner Losh 78138e3e3a7aSWarner Losh<li>input and output (<a href="#6.8">§6.8</a>);</li> 78148e3e3a7aSWarner Losh 78158e3e3a7aSWarner Losh<li>operating system facilities (<a href="#6.9">§6.9</a>);</li> 78168e3e3a7aSWarner Losh 78178e3e3a7aSWarner Losh<li>debug facilities (<a href="#6.10">§6.10</a>).</li> 78188e3e3a7aSWarner Losh 78198e3e3a7aSWarner Losh</ul><p> 78208e3e3a7aSWarner LoshExcept for the basic and the package libraries, 78218e3e3a7aSWarner Losheach library provides all its functions as fields of a global table 78228e3e3a7aSWarner Loshor as methods of its objects. 78238e3e3a7aSWarner Losh 78248e3e3a7aSWarner Losh 78258e3e3a7aSWarner Losh<p> 78268e3e3a7aSWarner LoshTo have access to these libraries, 78278e3e3a7aSWarner Loshthe C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, 78288e3e3a7aSWarner Loshwhich opens all standard libraries. 78298e3e3a7aSWarner LoshAlternatively, 78308e3e3a7aSWarner Loshthe host program can open them individually by using 78318e3e3a7aSWarner Losh<a href="#luaL_requiref"><code>luaL_requiref</code></a> to call 78328e3e3a7aSWarner Losh<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), 78338e3e3a7aSWarner Losh<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), 78348e3e3a7aSWarner Losh<a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library), 78358e3e3a7aSWarner Losh<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), 78360495ed39SKyle Evans<a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF-8 library), 78378e3e3a7aSWarner Losh<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), 78388e3e3a7aSWarner Losh<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), 78398e3e3a7aSWarner Losh<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), 78408e3e3a7aSWarner Losh<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library), 78418e3e3a7aSWarner Loshand <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). 78428e3e3a7aSWarner LoshThese functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>. 78438e3e3a7aSWarner Losh 78448e3e3a7aSWarner Losh 78458e3e3a7aSWarner Losh 78460495ed39SKyle Evans 78470495ed39SKyle Evans 78488e3e3a7aSWarner Losh<h2>6.1 – <a name="6.1">Basic Functions</a></h2> 78498e3e3a7aSWarner Losh 78508e3e3a7aSWarner Losh<p> 78518e3e3a7aSWarner LoshThe basic library provides core functions to Lua. 78528e3e3a7aSWarner LoshIf you do not include this library in your application, 78538e3e3a7aSWarner Loshyou should check carefully whether you need to provide 78548e3e3a7aSWarner Loshimplementations for some of its facilities. 78558e3e3a7aSWarner Losh 78568e3e3a7aSWarner Losh 78578e3e3a7aSWarner Losh<p> 78588e3e3a7aSWarner Losh<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> 78598e3e3a7aSWarner Losh 78608e3e3a7aSWarner Losh 78618e3e3a7aSWarner Losh<p> 78620495ed39SKyle EvansRaises an error if 78638e3e3a7aSWarner Loshthe value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); 78648e3e3a7aSWarner Loshotherwise, returns all its arguments. 78658e3e3a7aSWarner LoshIn case of error, 78668e3e3a7aSWarner Losh<code>message</code> is the error object; 78678e3e3a7aSWarner Loshwhen absent, it defaults to "<code>assertion failed!</code>" 78688e3e3a7aSWarner Losh 78698e3e3a7aSWarner Losh 78708e3e3a7aSWarner Losh 78718e3e3a7aSWarner Losh 78728e3e3a7aSWarner Losh<p> 78738e3e3a7aSWarner Losh<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3> 78748e3e3a7aSWarner Losh 78758e3e3a7aSWarner Losh 78768e3e3a7aSWarner Losh<p> 78778e3e3a7aSWarner LoshThis function is a generic interface to the garbage collector. 78788e3e3a7aSWarner LoshIt performs different functions according to its first argument, <code>opt</code>: 78798e3e3a7aSWarner Losh 78808e3e3a7aSWarner Losh<ul> 78818e3e3a7aSWarner Losh 78828e3e3a7aSWarner Losh<li><b>"<code>collect</code>": </b> 78830495ed39SKyle EvansPerforms a full garbage-collection cycle. 78848e3e3a7aSWarner LoshThis is the default option. 78858e3e3a7aSWarner Losh</li> 78868e3e3a7aSWarner Losh 78878e3e3a7aSWarner Losh<li><b>"<code>stop</code>": </b> 78880495ed39SKyle EvansStops automatic execution of the garbage collector. 78898e3e3a7aSWarner LoshThe collector will run only when explicitly invoked, 78908e3e3a7aSWarner Loshuntil a call to restart it. 78918e3e3a7aSWarner Losh</li> 78928e3e3a7aSWarner Losh 78938e3e3a7aSWarner Losh<li><b>"<code>restart</code>": </b> 78940495ed39SKyle EvansRestarts automatic execution of the garbage collector. 78958e3e3a7aSWarner Losh</li> 78968e3e3a7aSWarner Losh 78978e3e3a7aSWarner Losh<li><b>"<code>count</code>": </b> 78980495ed39SKyle EvansReturns the total memory in use by Lua in Kbytes. 78998e3e3a7aSWarner LoshThe value has a fractional part, 79008e3e3a7aSWarner Loshso that it multiplied by 1024 79010495ed39SKyle Evansgives the exact number of bytes in use by Lua. 79028e3e3a7aSWarner Losh</li> 79038e3e3a7aSWarner Losh 79048e3e3a7aSWarner Losh<li><b>"<code>step</code>": </b> 79050495ed39SKyle EvansPerforms a garbage-collection step. 79068e3e3a7aSWarner LoshThe step "size" is controlled by <code>arg</code>. 79078e3e3a7aSWarner LoshWith a zero value, 79088e3e3a7aSWarner Loshthe collector will perform one basic (indivisible) step. 79098e3e3a7aSWarner LoshFor non-zero values, 79108e3e3a7aSWarner Loshthe collector will perform as if that amount of memory 79110495ed39SKyle Evans(in Kbytes) had been allocated by Lua. 79128e3e3a7aSWarner LoshReturns <b>true</b> if the step finished a collection cycle. 79138e3e3a7aSWarner Losh</li> 79148e3e3a7aSWarner Losh 79158e3e3a7aSWarner Losh<li><b>"<code>isrunning</code>": </b> 79160495ed39SKyle EvansReturns a boolean that tells whether the collector is running 79178e3e3a7aSWarner Losh(i.e., not stopped). 79188e3e3a7aSWarner Losh</li> 79198e3e3a7aSWarner Losh 79200495ed39SKyle Evans<li><b>"<code>incremental</code>": </b> 79210495ed39SKyle EvansChange the collector mode to incremental. 79220495ed39SKyle EvansThis option can be followed by three numbers: 79230495ed39SKyle Evansthe garbage-collector pause, 79240495ed39SKyle Evansthe step multiplier, 79250495ed39SKyle Evansand the step size (see <a href="#2.5.1">§2.5.1</a>). 79260495ed39SKyle EvansA zero means to not change that value. 79270495ed39SKyle Evans</li> 79280495ed39SKyle Evans 79290495ed39SKyle Evans<li><b>"<code>generational</code>": </b> 79300495ed39SKyle EvansChange the collector mode to generational. 79310495ed39SKyle EvansThis option can be followed by two numbers: 79320495ed39SKyle Evansthe garbage-collector minor multiplier 79330495ed39SKyle Evansand the major multiplier (see <a href="#2.5.2">§2.5.2</a>). 79340495ed39SKyle EvansA zero means to not change that value. 79350495ed39SKyle Evans</li> 79360495ed39SKyle Evans 79370495ed39SKyle Evans</ul><p> 79380495ed39SKyle EvansSee <a href="#2.5">§2.5</a> for more details about garbage collection 79390495ed39SKyle Evansand some of these options. 79400495ed39SKyle Evans 79418e3e3a7aSWarner Losh 7942*8c784bb8SWarner Losh<p> 7943*8c784bb8SWarner LoshThis function should not be called by a finalizer. 7944*8c784bb8SWarner Losh 7945*8c784bb8SWarner Losh 79468e3e3a7aSWarner Losh 79478e3e3a7aSWarner Losh 79488e3e3a7aSWarner Losh<p> 79498e3e3a7aSWarner Losh<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> 79500495ed39SKyle EvansOpens the named file and executes its content as a Lua chunk. 79518e3e3a7aSWarner LoshWhen called without arguments, 79520495ed39SKyle Evans<code>dofile</code> executes the content of the standard input (<code>stdin</code>). 79538e3e3a7aSWarner LoshReturns all values returned by the chunk. 79548e3e3a7aSWarner LoshIn case of errors, <code>dofile</code> propagates the error 79550495ed39SKyle Evansto its caller. 79560495ed39SKyle Evans(That is, <code>dofile</code> does not run in protected mode.) 79578e3e3a7aSWarner Losh 79588e3e3a7aSWarner Losh 79598e3e3a7aSWarner Losh 79608e3e3a7aSWarner Losh 79618e3e3a7aSWarner Losh<p> 79628e3e3a7aSWarner Losh<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> 7963*8c784bb8SWarner LoshRaises an error (see <a href="#2.3">§2.3</a>) with <code>message</code> as the error object. 79640495ed39SKyle EvansThis function never returns. 79658e3e3a7aSWarner Losh 79668e3e3a7aSWarner Losh 79678e3e3a7aSWarner Losh<p> 79688e3e3a7aSWarner LoshUsually, <code>error</code> adds some information about the error position 79698e3e3a7aSWarner Loshat the beginning of the message, if the message is a string. 79708e3e3a7aSWarner LoshThe <code>level</code> argument specifies how to get the error position. 79718e3e3a7aSWarner LoshWith level 1 (the default), the error position is where the 79728e3e3a7aSWarner Losh<code>error</code> function was called. 79738e3e3a7aSWarner LoshLevel 2 points the error to where the function 79748e3e3a7aSWarner Loshthat called <code>error</code> was called; and so on. 79758e3e3a7aSWarner LoshPassing a level 0 avoids the addition of error position information 79768e3e3a7aSWarner Loshto the message. 79778e3e3a7aSWarner Losh 79788e3e3a7aSWarner Losh 79798e3e3a7aSWarner Losh 79808e3e3a7aSWarner Losh 79818e3e3a7aSWarner Losh<p> 79828e3e3a7aSWarner Losh<hr><h3><a name="pdf-_G"><code>_G</code></a></h3> 79838e3e3a7aSWarner LoshA global variable (not a function) that 79848e3e3a7aSWarner Loshholds the global environment (see <a href="#2.2">§2.2</a>). 79858e3e3a7aSWarner LoshLua itself does not use this variable; 79868e3e3a7aSWarner Loshchanging its value does not affect any environment, 79878e3e3a7aSWarner Loshnor vice versa. 79888e3e3a7aSWarner Losh 79898e3e3a7aSWarner Losh 79908e3e3a7aSWarner Losh 79918e3e3a7aSWarner Losh 79928e3e3a7aSWarner Losh<p> 79938e3e3a7aSWarner Losh<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> 79948e3e3a7aSWarner Losh 79958e3e3a7aSWarner Losh 79968e3e3a7aSWarner Losh<p> 79978e3e3a7aSWarner LoshIf <code>object</code> does not have a metatable, returns <b>nil</b>. 79988e3e3a7aSWarner LoshOtherwise, 79998e3e3a7aSWarner Loshif the object's metatable has a <code>__metatable</code> field, 80008e3e3a7aSWarner Loshreturns the associated value. 80018e3e3a7aSWarner LoshOtherwise, returns the metatable of the given object. 80028e3e3a7aSWarner Losh 80038e3e3a7aSWarner Losh 80048e3e3a7aSWarner Losh 80058e3e3a7aSWarner Losh 80068e3e3a7aSWarner Losh<p> 80078e3e3a7aSWarner Losh<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> 80088e3e3a7aSWarner Losh 80098e3e3a7aSWarner Losh 80108e3e3a7aSWarner Losh<p> 80118e3e3a7aSWarner LoshReturns three values (an iterator function, the table <code>t</code>, and 0) 80128e3e3a7aSWarner Loshso that the construction 80138e3e3a7aSWarner Losh 80148e3e3a7aSWarner Losh<pre> 80158e3e3a7aSWarner Losh for i,v in ipairs(t) do <em>body</em> end 80168e3e3a7aSWarner Losh</pre><p> 80178e3e3a7aSWarner Loshwill iterate over the key–value pairs 80188e3e3a7aSWarner Losh(<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., 80190495ed39SKyle Evansup to the first absent index. 80208e3e3a7aSWarner Losh 80218e3e3a7aSWarner Losh 80228e3e3a7aSWarner Losh 80238e3e3a7aSWarner Losh 80248e3e3a7aSWarner Losh<p> 80258e3e3a7aSWarner Losh<hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3> 80268e3e3a7aSWarner Losh 80278e3e3a7aSWarner Losh 80288e3e3a7aSWarner Losh<p> 80298e3e3a7aSWarner LoshLoads a chunk. 80308e3e3a7aSWarner Losh 80318e3e3a7aSWarner Losh 80328e3e3a7aSWarner Losh<p> 80338e3e3a7aSWarner LoshIf <code>chunk</code> is a string, the chunk is this string. 80348e3e3a7aSWarner LoshIf <code>chunk</code> is a function, 80358e3e3a7aSWarner Losh<code>load</code> calls it repeatedly to get the chunk pieces. 80368e3e3a7aSWarner LoshEach call to <code>chunk</code> must return a string that concatenates 80378e3e3a7aSWarner Loshwith previous results. 80388e3e3a7aSWarner LoshA return of an empty string, <b>nil</b>, or no value signals the end of the chunk. 80398e3e3a7aSWarner Losh 80408e3e3a7aSWarner Losh 80418e3e3a7aSWarner Losh<p> 80428e3e3a7aSWarner LoshIf there are no syntactic errors, 80430495ed39SKyle Evans<code>load</code> returns the compiled chunk as a function; 80440495ed39SKyle Evansotherwise, it returns <b>fail</b> plus the error message. 80458e3e3a7aSWarner Losh 80468e3e3a7aSWarner Losh 80478e3e3a7aSWarner Losh<p> 80480495ed39SKyle EvansWhen you load a main chunk, 80498e3e3a7aSWarner Loshthe resulting function will always have exactly one upvalue, 80508e3e3a7aSWarner Loshthe <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 80518e3e3a7aSWarner LoshHowever, 80528e3e3a7aSWarner Loshwhen you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>), 80530495ed39SKyle Evansthe resulting function can have an arbitrary number of upvalues, 80540495ed39SKyle Evansand there is no guarantee that its first upvalue will be 80550495ed39SKyle Evansthe <code>_ENV</code> variable. 80560495ed39SKyle Evans(A non-main function may not even have an <code>_ENV</code> upvalue.) 80570495ed39SKyle Evans 80580495ed39SKyle Evans 80590495ed39SKyle Evans<p> 80600495ed39SKyle EvansRegardless, if the resulting function has any upvalues, 80610495ed39SKyle Evansits first upvalue is set to the value of <code>env</code>, 80620495ed39SKyle Evansif that parameter is given, 80630495ed39SKyle Evansor to the value of the global environment. 80640495ed39SKyle EvansOther upvalues are initialized with <b>nil</b>. 80658e3e3a7aSWarner LoshAll upvalues are fresh, that is, 80668e3e3a7aSWarner Loshthey are not shared with any other function. 80678e3e3a7aSWarner Losh 80688e3e3a7aSWarner Losh 80698e3e3a7aSWarner Losh<p> 80708e3e3a7aSWarner Losh<code>chunkname</code> is used as the name of the chunk for error messages 80710495ed39SKyle Evansand debug information (see <a href="#4.7">§4.7</a>). 80728e3e3a7aSWarner LoshWhen absent, 80738e3e3a7aSWarner Loshit defaults to <code>chunk</code>, if <code>chunk</code> is a string, 80748e3e3a7aSWarner Loshor to "<code>=(load)</code>" otherwise. 80758e3e3a7aSWarner Losh 80768e3e3a7aSWarner Losh 80778e3e3a7aSWarner Losh<p> 80788e3e3a7aSWarner LoshThe string <code>mode</code> controls whether the chunk can be text or binary 80798e3e3a7aSWarner Losh(that is, a precompiled chunk). 80808e3e3a7aSWarner LoshIt may be the string "<code>b</code>" (only binary chunks), 80818e3e3a7aSWarner Losh"<code>t</code>" (only text chunks), 80828e3e3a7aSWarner Loshor "<code>bt</code>" (both binary and text). 80838e3e3a7aSWarner LoshThe default is "<code>bt</code>". 80848e3e3a7aSWarner Losh 80858e3e3a7aSWarner Losh 80868e3e3a7aSWarner Losh<p> 80870495ed39SKyle EvansIt is safe to load malformed binary chunks; 80880495ed39SKyle Evans<code>load</code> signals an appropriate error. 80890495ed39SKyle EvansHowever, 80900495ed39SKyle EvansLua does not check the consistency of the code inside binary chunks; 80910495ed39SKyle Evansrunning maliciously crafted bytecode can crash the interpreter. 80928e3e3a7aSWarner Losh 80938e3e3a7aSWarner Losh 80948e3e3a7aSWarner Losh 80958e3e3a7aSWarner Losh 80968e3e3a7aSWarner Losh<p> 80978e3e3a7aSWarner Losh<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3> 80988e3e3a7aSWarner Losh 80998e3e3a7aSWarner Losh 81008e3e3a7aSWarner Losh<p> 81018e3e3a7aSWarner LoshSimilar to <a href="#pdf-load"><code>load</code></a>, 81028e3e3a7aSWarner Loshbut gets the chunk from file <code>filename</code> 81038e3e3a7aSWarner Loshor from the standard input, 81048e3e3a7aSWarner Loshif no file name is given. 81058e3e3a7aSWarner Losh 81068e3e3a7aSWarner Losh 81078e3e3a7aSWarner Losh 81088e3e3a7aSWarner Losh 81098e3e3a7aSWarner Losh<p> 81108e3e3a7aSWarner Losh<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> 81118e3e3a7aSWarner Losh 81128e3e3a7aSWarner Losh 81138e3e3a7aSWarner Losh<p> 81148e3e3a7aSWarner LoshAllows a program to traverse all fields of a table. 81158e3e3a7aSWarner LoshIts first argument is a table and its second argument 81168e3e3a7aSWarner Loshis an index in this table. 81170495ed39SKyle EvansA call to <code>next</code> returns the next index of the table 81188e3e3a7aSWarner Loshand its associated value. 81198e3e3a7aSWarner LoshWhen called with <b>nil</b> as its second argument, 81208e3e3a7aSWarner Losh<code>next</code> returns an initial index 81218e3e3a7aSWarner Loshand its associated value. 81228e3e3a7aSWarner LoshWhen called with the last index, 81238e3e3a7aSWarner Loshor with <b>nil</b> in an empty table, 81248e3e3a7aSWarner Losh<code>next</code> returns <b>nil</b>. 81258e3e3a7aSWarner LoshIf the second argument is absent, then it is interpreted as <b>nil</b>. 81268e3e3a7aSWarner LoshIn particular, 81278e3e3a7aSWarner Loshyou can use <code>next(t)</code> to check whether a table is empty. 81288e3e3a7aSWarner Losh 81298e3e3a7aSWarner Losh 81308e3e3a7aSWarner Losh<p> 81318e3e3a7aSWarner LoshThe order in which the indices are enumerated is not specified, 81328e3e3a7aSWarner Losh<em>even for numeric indices</em>. 81338e3e3a7aSWarner Losh(To traverse a table in numerical order, 81348e3e3a7aSWarner Loshuse a numerical <b>for</b>.) 81358e3e3a7aSWarner Losh 81368e3e3a7aSWarner Losh 81378e3e3a7aSWarner Losh<p> 8138*8c784bb8SWarner LoshYou should not assign any value to a non-existent field in a table 8139*8c784bb8SWarner Loshduring its traversal. 81408e3e3a7aSWarner LoshYou may however modify existing fields. 81410495ed39SKyle EvansIn particular, you may set existing fields to nil. 81428e3e3a7aSWarner Losh 81438e3e3a7aSWarner Losh 81448e3e3a7aSWarner Losh 81458e3e3a7aSWarner Losh 81468e3e3a7aSWarner Losh<p> 81478e3e3a7aSWarner Losh<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> 81488e3e3a7aSWarner Losh 81498e3e3a7aSWarner Losh 81508e3e3a7aSWarner Losh<p> 81518e3e3a7aSWarner LoshIf <code>t</code> has a metamethod <code>__pairs</code>, 81528e3e3a7aSWarner Loshcalls it with <code>t</code> as argument and returns the first three 81538e3e3a7aSWarner Loshresults from the call. 81548e3e3a7aSWarner Losh 81558e3e3a7aSWarner Losh 81568e3e3a7aSWarner Losh<p> 81578e3e3a7aSWarner LoshOtherwise, 81588e3e3a7aSWarner Loshreturns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, 81598e3e3a7aSWarner Loshso that the construction 81608e3e3a7aSWarner Losh 81618e3e3a7aSWarner Losh<pre> 81628e3e3a7aSWarner Losh for k,v in pairs(t) do <em>body</em> end 81638e3e3a7aSWarner Losh</pre><p> 81648e3e3a7aSWarner Loshwill iterate over all key–value pairs of table <code>t</code>. 81658e3e3a7aSWarner Losh 81668e3e3a7aSWarner Losh 81678e3e3a7aSWarner Losh<p> 81688e3e3a7aSWarner LoshSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 81698e3e3a7aSWarner Loshthe table during its traversal. 81708e3e3a7aSWarner Losh 81718e3e3a7aSWarner Losh 81728e3e3a7aSWarner Losh 81738e3e3a7aSWarner Losh 81748e3e3a7aSWarner Losh<p> 81758e3e3a7aSWarner Losh<hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3> 81768e3e3a7aSWarner Losh 81778e3e3a7aSWarner Losh 81788e3e3a7aSWarner Losh<p> 81790495ed39SKyle EvansCalls the function <code>f</code> with 81808e3e3a7aSWarner Loshthe given arguments in <em>protected mode</em>. 81818e3e3a7aSWarner LoshThis means that any error inside <code>f</code> is not propagated; 81828e3e3a7aSWarner Loshinstead, <code>pcall</code> catches the error 81838e3e3a7aSWarner Loshand returns a status code. 81848e3e3a7aSWarner LoshIts first result is the status code (a boolean), 8185*8c784bb8SWarner Loshwhich is <b>true</b> if the call succeeds without errors. 81868e3e3a7aSWarner LoshIn such case, <code>pcall</code> also returns all results from the call, 81878e3e3a7aSWarner Loshafter this first result. 81880495ed39SKyle EvansIn case of any error, <code>pcall</code> returns <b>false</b> plus the error object. 81890495ed39SKyle EvansNote that errors caught by <code>pcall</code> do not call a message handler. 81908e3e3a7aSWarner Losh 81918e3e3a7aSWarner Losh 81928e3e3a7aSWarner Losh 81938e3e3a7aSWarner Losh 81948e3e3a7aSWarner Losh<p> 81958e3e3a7aSWarner Losh<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> 81968e3e3a7aSWarner LoshReceives any number of arguments 81978e3e3a7aSWarner Loshand prints their values to <code>stdout</code>, 81980495ed39SKyle Evansconverting each argument to a string 81990495ed39SKyle Evansfollowing the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 82000495ed39SKyle Evans 82010495ed39SKyle Evans 82020495ed39SKyle Evans<p> 82030495ed39SKyle EvansThe function <code>print</code> is not intended for formatted output, 82048e3e3a7aSWarner Loshbut only as a quick way to show a value, 82058e3e3a7aSWarner Loshfor instance for debugging. 82068e3e3a7aSWarner LoshFor complete control over the output, 82078e3e3a7aSWarner Loshuse <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. 82088e3e3a7aSWarner Losh 82098e3e3a7aSWarner Losh 82108e3e3a7aSWarner Losh 82118e3e3a7aSWarner Losh 82128e3e3a7aSWarner Losh<p> 82138e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> 82148e3e3a7aSWarner LoshChecks whether <code>v1</code> is equal to <code>v2</code>, 82158e3e3a7aSWarner Loshwithout invoking the <code>__eq</code> metamethod. 82168e3e3a7aSWarner LoshReturns a boolean. 82178e3e3a7aSWarner Losh 82188e3e3a7aSWarner Losh 82198e3e3a7aSWarner Losh 82208e3e3a7aSWarner Losh 82218e3e3a7aSWarner Losh<p> 82228e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> 82238e3e3a7aSWarner LoshGets the real value of <code>table[index]</code>, 82240495ed39SKyle Evanswithout using the <code>__index</code> metavalue. 82258e3e3a7aSWarner Losh<code>table</code> must be a table; 82268e3e3a7aSWarner Losh<code>index</code> may be any value. 82278e3e3a7aSWarner Losh 82288e3e3a7aSWarner Losh 82298e3e3a7aSWarner Losh 82308e3e3a7aSWarner Losh 82318e3e3a7aSWarner Losh<p> 82328e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3> 82338e3e3a7aSWarner LoshReturns the length of the object <code>v</code>, 82348e3e3a7aSWarner Loshwhich must be a table or a string, 82358e3e3a7aSWarner Loshwithout invoking the <code>__len</code> metamethod. 82368e3e3a7aSWarner LoshReturns an integer. 82378e3e3a7aSWarner Losh 82388e3e3a7aSWarner Losh 82398e3e3a7aSWarner Losh 82408e3e3a7aSWarner Losh 82418e3e3a7aSWarner Losh<p> 82428e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> 82438e3e3a7aSWarner LoshSets the real value of <code>table[index]</code> to <code>value</code>, 82440495ed39SKyle Evanswithout using the <code>__newindex</code> metavalue. 82458e3e3a7aSWarner Losh<code>table</code> must be a table, 82468e3e3a7aSWarner Losh<code>index</code> any value different from <b>nil</b> and NaN, 82478e3e3a7aSWarner Loshand <code>value</code> any Lua value. 82488e3e3a7aSWarner Losh 82498e3e3a7aSWarner Losh 82508e3e3a7aSWarner Losh<p> 82518e3e3a7aSWarner LoshThis function returns <code>table</code>. 82528e3e3a7aSWarner Losh 82538e3e3a7aSWarner Losh 82548e3e3a7aSWarner Losh 82558e3e3a7aSWarner Losh 82568e3e3a7aSWarner Losh<p> 82578e3e3a7aSWarner Losh<hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> 82588e3e3a7aSWarner Losh 82598e3e3a7aSWarner Losh 82608e3e3a7aSWarner Losh<p> 82618e3e3a7aSWarner LoshIf <code>index</code> is a number, 82628e3e3a7aSWarner Loshreturns all arguments after argument number <code>index</code>; 82638e3e3a7aSWarner Losha negative number indexes from the end (-1 is the last argument). 82648e3e3a7aSWarner LoshOtherwise, <code>index</code> must be the string <code>"#"</code>, 82658e3e3a7aSWarner Loshand <code>select</code> returns the total number of extra arguments it received. 82668e3e3a7aSWarner Losh 82678e3e3a7aSWarner Losh 82688e3e3a7aSWarner Losh 82698e3e3a7aSWarner Losh 82708e3e3a7aSWarner Losh<p> 82718e3e3a7aSWarner Losh<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> 82728e3e3a7aSWarner Losh 82738e3e3a7aSWarner Losh 82748e3e3a7aSWarner Losh<p> 82758e3e3a7aSWarner LoshSets the metatable for the given table. 82768e3e3a7aSWarner LoshIf <code>metatable</code> is <b>nil</b>, 82778e3e3a7aSWarner Loshremoves the metatable of the given table. 82788e3e3a7aSWarner LoshIf the original metatable has a <code>__metatable</code> field, 82798e3e3a7aSWarner Loshraises an error. 82808e3e3a7aSWarner Losh 82818e3e3a7aSWarner Losh 82828e3e3a7aSWarner Losh<p> 82838e3e3a7aSWarner LoshThis function returns <code>table</code>. 82848e3e3a7aSWarner Losh 82858e3e3a7aSWarner Losh 82860495ed39SKyle Evans<p> 82870495ed39SKyle EvansTo change the metatable of other types from Lua code, 82880495ed39SKyle Evansyou must use the debug library (<a href="#6.10">§6.10</a>). 82890495ed39SKyle Evans 82900495ed39SKyle Evans 82918e3e3a7aSWarner Losh 82928e3e3a7aSWarner Losh 82938e3e3a7aSWarner Losh<p> 82948e3e3a7aSWarner Losh<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> 82958e3e3a7aSWarner Losh 82968e3e3a7aSWarner Losh 82978e3e3a7aSWarner Losh<p> 82988e3e3a7aSWarner LoshWhen called with no <code>base</code>, 82998e3e3a7aSWarner Losh<code>tonumber</code> tries to convert its argument to a number. 83008e3e3a7aSWarner LoshIf the argument is already a number or 83018e3e3a7aSWarner Losha string convertible to a number, 83028e3e3a7aSWarner Loshthen <code>tonumber</code> returns this number; 83030495ed39SKyle Evansotherwise, it returns <b>fail</b>. 83048e3e3a7aSWarner Losh 83058e3e3a7aSWarner Losh 83068e3e3a7aSWarner Losh<p> 83078e3e3a7aSWarner LoshThe conversion of strings can result in integers or floats, 83088e3e3a7aSWarner Loshaccording to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 83090495ed39SKyle EvansThe string may have leading and trailing spaces and a sign. 83108e3e3a7aSWarner Losh 83118e3e3a7aSWarner Losh 83128e3e3a7aSWarner Losh<p> 83138e3e3a7aSWarner LoshWhen called with <code>base</code>, 83148e3e3a7aSWarner Loshthen <code>e</code> must be a string to be interpreted as 83158e3e3a7aSWarner Loshan integer numeral in that base. 83168e3e3a7aSWarner LoshThe base may be any integer between 2 and 36, inclusive. 83178e3e3a7aSWarner LoshIn bases above 10, the letter '<code>A</code>' (in either upper or lower case) 83188e3e3a7aSWarner Loshrepresents 10, '<code>B</code>' represents 11, and so forth, 83198e3e3a7aSWarner Loshwith '<code>Z</code>' representing 35. 83208e3e3a7aSWarner LoshIf the string <code>e</code> is not a valid numeral in the given base, 83210495ed39SKyle Evansthe function returns <b>fail</b>. 83228e3e3a7aSWarner Losh 83238e3e3a7aSWarner Losh 83248e3e3a7aSWarner Losh 83258e3e3a7aSWarner Losh 83268e3e3a7aSWarner Losh<p> 83278e3e3a7aSWarner Losh<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3> 83280495ed39SKyle Evans 83290495ed39SKyle Evans 83300495ed39SKyle Evans<p> 83318e3e3a7aSWarner LoshReceives a value of any type and 83328e3e3a7aSWarner Loshconverts it to a string in a human-readable format. 83338e3e3a7aSWarner Losh 83348e3e3a7aSWarner Losh 83358e3e3a7aSWarner Losh<p> 83368e3e3a7aSWarner LoshIf the metatable of <code>v</code> has a <code>__tostring</code> field, 83378e3e3a7aSWarner Loshthen <code>tostring</code> calls the corresponding value 83388e3e3a7aSWarner Loshwith <code>v</code> as argument, 83398e3e3a7aSWarner Loshand uses the result of the call as its result. 83400495ed39SKyle EvansOtherwise, if the metatable of <code>v</code> has a <code>__name</code> field 83410495ed39SKyle Evanswith a string value, 83420495ed39SKyle Evans<code>tostring</code> may use that string in its final result. 83430495ed39SKyle Evans 83440495ed39SKyle Evans 83450495ed39SKyle Evans<p> 83460495ed39SKyle EvansFor complete control of how numbers are converted, 83470495ed39SKyle Evansuse <a href="#pdf-string.format"><code>string.format</code></a>. 83488e3e3a7aSWarner Losh 83498e3e3a7aSWarner Losh 83508e3e3a7aSWarner Losh 83518e3e3a7aSWarner Losh 83528e3e3a7aSWarner Losh<p> 83538e3e3a7aSWarner Losh<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> 83540495ed39SKyle Evans 83550495ed39SKyle Evans 83560495ed39SKyle Evans<p> 83578e3e3a7aSWarner LoshReturns the type of its only argument, coded as a string. 83588e3e3a7aSWarner LoshThe possible results of this function are 83598e3e3a7aSWarner Losh"<code>nil</code>" (a string, not the value <b>nil</b>), 83608e3e3a7aSWarner Losh"<code>number</code>", 83618e3e3a7aSWarner Losh"<code>string</code>", 83628e3e3a7aSWarner Losh"<code>boolean</code>", 83638e3e3a7aSWarner Losh"<code>table</code>", 83648e3e3a7aSWarner Losh"<code>function</code>", 83658e3e3a7aSWarner Losh"<code>thread</code>", 83668e3e3a7aSWarner Loshand "<code>userdata</code>". 83678e3e3a7aSWarner Losh 83688e3e3a7aSWarner Losh 83698e3e3a7aSWarner Losh 83708e3e3a7aSWarner Losh 83718e3e3a7aSWarner Losh<p> 83728e3e3a7aSWarner Losh<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> 83738e3e3a7aSWarner Losh 83748e3e3a7aSWarner Losh 83758e3e3a7aSWarner Losh<p> 83768e3e3a7aSWarner LoshA global variable (not a function) that 83778e3e3a7aSWarner Loshholds a string containing the running Lua version. 83780495ed39SKyle EvansThe current value of this variable is "<code>Lua 5.4</code>". 83790495ed39SKyle Evans 83800495ed39SKyle Evans 83810495ed39SKyle Evans 83820495ed39SKyle Evans 83830495ed39SKyle Evans<p> 83840495ed39SKyle Evans<hr><h3><a name="pdf-warn"><code>warn (msg1, ···)</code></a></h3> 83850495ed39SKyle Evans 83860495ed39SKyle Evans 83870495ed39SKyle Evans<p> 83880495ed39SKyle EvansEmits a warning with a message composed by the concatenation 83890495ed39SKyle Evansof all its arguments (which should be strings). 83900495ed39SKyle Evans 83910495ed39SKyle Evans 83920495ed39SKyle Evans<p> 83930495ed39SKyle EvansBy convention, 83940495ed39SKyle Evansa one-piece message starting with '<code>@</code>' 83950495ed39SKyle Evansis intended to be a <em>control message</em>, 83960495ed39SKyle Evanswhich is a message to the warning system itself. 83970495ed39SKyle EvansIn particular, the standard warning function in Lua 83980495ed39SKyle Evansrecognizes the control messages "<code>@off</code>", 83990495ed39SKyle Evansto stop the emission of warnings, 84000495ed39SKyle Evansand "<code>@on</code>", to (re)start the emission; 84010495ed39SKyle Evansit ignores unknown control messages. 84028e3e3a7aSWarner Losh 84038e3e3a7aSWarner Losh 84048e3e3a7aSWarner Losh 84058e3e3a7aSWarner Losh 84068e3e3a7aSWarner Losh<p> 84078e3e3a7aSWarner Losh<hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3> 84088e3e3a7aSWarner Losh 84098e3e3a7aSWarner Losh 84108e3e3a7aSWarner Losh<p> 84118e3e3a7aSWarner LoshThis function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, 84128e3e3a7aSWarner Loshexcept that it sets a new message handler <code>msgh</code>. 84138e3e3a7aSWarner Losh 84148e3e3a7aSWarner Losh 84158e3e3a7aSWarner Losh 84168e3e3a7aSWarner Losh 84178e3e3a7aSWarner Losh 84188e3e3a7aSWarner Losh 84198e3e3a7aSWarner Losh 84208e3e3a7aSWarner Losh<h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2> 84218e3e3a7aSWarner Losh 84228e3e3a7aSWarner Losh<p> 84238e3e3a7aSWarner LoshThis library comprises the operations to manipulate coroutines, 84248e3e3a7aSWarner Loshwhich come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. 84258e3e3a7aSWarner LoshSee <a href="#2.6">§2.6</a> for a general description of coroutines. 84268e3e3a7aSWarner Losh 84278e3e3a7aSWarner Losh 84288e3e3a7aSWarner Losh<p> 84290495ed39SKyle Evans<hr><h3><a name="pdf-coroutine.close"><code>coroutine.close (co)</code></a></h3> 84300495ed39SKyle Evans 84310495ed39SKyle Evans 84320495ed39SKyle Evans<p> 84330495ed39SKyle EvansCloses coroutine <code>co</code>, 84340495ed39SKyle Evansthat is, 84350495ed39SKyle Evanscloses all its pending to-be-closed variables 84360495ed39SKyle Evansand puts the coroutine in a dead state. 84370495ed39SKyle EvansThe given coroutine must be dead or suspended. 8438*8c784bb8SWarner LoshIn case of error 8439*8c784bb8SWarner Losh(either the original error that stopped the coroutine or 8440*8c784bb8SWarner Losherrors in closing methods), 84410495ed39SKyle Evansreturns <b>false</b> plus the error object; 84420495ed39SKyle Evansotherwise returns <b>true</b>. 84430495ed39SKyle Evans 84440495ed39SKyle Evans 84450495ed39SKyle Evans 84460495ed39SKyle Evans 84470495ed39SKyle Evans<p> 84488e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> 84498e3e3a7aSWarner Losh 84508e3e3a7aSWarner Losh 84518e3e3a7aSWarner Losh<p> 84528e3e3a7aSWarner LoshCreates a new coroutine, with body <code>f</code>. 84538e3e3a7aSWarner Losh<code>f</code> must be a function. 84548e3e3a7aSWarner LoshReturns this new coroutine, 84558e3e3a7aSWarner Loshan object with type <code>"thread"</code>. 84568e3e3a7aSWarner Losh 84578e3e3a7aSWarner Losh 84588e3e3a7aSWarner Losh 84598e3e3a7aSWarner Losh 84608e3e3a7aSWarner Losh<p> 84610495ed39SKyle Evans<hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ([co])</code></a></h3> 84628e3e3a7aSWarner Losh 84638e3e3a7aSWarner Losh 84648e3e3a7aSWarner Losh<p> 8465*8c784bb8SWarner LoshReturns <b>true</b> when the coroutine <code>co</code> can yield. 84660495ed39SKyle EvansThe default for <code>co</code> is the running coroutine. 84678e3e3a7aSWarner Losh 84688e3e3a7aSWarner Losh 84698e3e3a7aSWarner Losh<p> 84700495ed39SKyle EvansA coroutine is yieldable if it is not the main thread and 84718e3e3a7aSWarner Loshit is not inside a non-yieldable C function. 84728e3e3a7aSWarner Losh 84738e3e3a7aSWarner Losh 84748e3e3a7aSWarner Losh 84758e3e3a7aSWarner Losh 84768e3e3a7aSWarner Losh<p> 84778e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> 84788e3e3a7aSWarner Losh 84798e3e3a7aSWarner Losh 84808e3e3a7aSWarner Losh<p> 84818e3e3a7aSWarner LoshStarts or continues the execution of coroutine <code>co</code>. 84828e3e3a7aSWarner LoshThe first time you resume a coroutine, 84838e3e3a7aSWarner Loshit starts running its body. 84848e3e3a7aSWarner LoshThe values <code>val1</code>, ... are passed 84858e3e3a7aSWarner Loshas the arguments to the body function. 84868e3e3a7aSWarner LoshIf the coroutine has yielded, 84878e3e3a7aSWarner Losh<code>resume</code> restarts it; 84888e3e3a7aSWarner Loshthe values <code>val1</code>, ... are passed 84898e3e3a7aSWarner Loshas the results from the yield. 84908e3e3a7aSWarner Losh 84918e3e3a7aSWarner Losh 84928e3e3a7aSWarner Losh<p> 84938e3e3a7aSWarner LoshIf the coroutine runs without any errors, 84948e3e3a7aSWarner Losh<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> 84958e3e3a7aSWarner Losh(when the coroutine yields) or any values returned by the body function 84968e3e3a7aSWarner Losh(when the coroutine terminates). 84978e3e3a7aSWarner LoshIf there is any error, 84988e3e3a7aSWarner Losh<code>resume</code> returns <b>false</b> plus the error message. 84998e3e3a7aSWarner Losh 85008e3e3a7aSWarner Losh 85018e3e3a7aSWarner Losh 85028e3e3a7aSWarner Losh 85038e3e3a7aSWarner Losh<p> 85048e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> 85058e3e3a7aSWarner Losh 85068e3e3a7aSWarner Losh 85078e3e3a7aSWarner Losh<p> 85088e3e3a7aSWarner LoshReturns the running coroutine plus a boolean, 8509*8c784bb8SWarner Losh<b>true</b> when the running coroutine is the main one. 85108e3e3a7aSWarner Losh 85118e3e3a7aSWarner Losh 85128e3e3a7aSWarner Losh 85138e3e3a7aSWarner Losh 85148e3e3a7aSWarner Losh<p> 85158e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> 85168e3e3a7aSWarner Losh 85178e3e3a7aSWarner Losh 85188e3e3a7aSWarner Losh<p> 85190495ed39SKyle EvansReturns the status of the coroutine <code>co</code>, as a string: 85208e3e3a7aSWarner Losh<code>"running"</code>, 85210495ed39SKyle Evansif the coroutine is running 85220495ed39SKyle Evans(that is, it is the one that called <code>status</code>); 85238e3e3a7aSWarner Losh<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, 85248e3e3a7aSWarner Loshor if it has not started running yet; 85258e3e3a7aSWarner Losh<code>"normal"</code> if the coroutine is active but not running 85268e3e3a7aSWarner Losh(that is, it has resumed another coroutine); 85278e3e3a7aSWarner Loshand <code>"dead"</code> if the coroutine has finished its body function, 85288e3e3a7aSWarner Loshor if it has stopped with an error. 85298e3e3a7aSWarner Losh 85308e3e3a7aSWarner Losh 85318e3e3a7aSWarner Losh 85328e3e3a7aSWarner Losh 85338e3e3a7aSWarner Losh<p> 85348e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> 85358e3e3a7aSWarner Losh 85368e3e3a7aSWarner Losh 85378e3e3a7aSWarner Losh<p> 85380495ed39SKyle EvansCreates a new coroutine, with body <code>f</code>; 85398e3e3a7aSWarner Losh<code>f</code> must be a function. 85408e3e3a7aSWarner LoshReturns a function that resumes the coroutine each time it is called. 85410495ed39SKyle EvansAny arguments passed to this function behave as the 85428e3e3a7aSWarner Loshextra arguments to <code>resume</code>. 85430495ed39SKyle EvansThe function returns the same values returned by <code>resume</code>, 85448e3e3a7aSWarner Loshexcept the first boolean. 85450495ed39SKyle EvansIn case of error, 85460495ed39SKyle Evansthe function closes the coroutine and propagates the error. 85478e3e3a7aSWarner Losh 85488e3e3a7aSWarner Losh 85498e3e3a7aSWarner Losh 85508e3e3a7aSWarner Losh 85518e3e3a7aSWarner Losh<p> 85528e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> 85538e3e3a7aSWarner Losh 85548e3e3a7aSWarner Losh 85558e3e3a7aSWarner Losh<p> 85568e3e3a7aSWarner LoshSuspends the execution of the calling coroutine. 85578e3e3a7aSWarner LoshAny arguments to <code>yield</code> are passed as extra results to <code>resume</code>. 85588e3e3a7aSWarner Losh 85598e3e3a7aSWarner Losh 85608e3e3a7aSWarner Losh 85618e3e3a7aSWarner Losh 85628e3e3a7aSWarner Losh 85638e3e3a7aSWarner Losh 85648e3e3a7aSWarner Losh 85658e3e3a7aSWarner Losh<h2>6.3 – <a name="6.3">Modules</a></h2> 85668e3e3a7aSWarner Losh 85678e3e3a7aSWarner Losh<p> 85688e3e3a7aSWarner LoshThe package library provides basic 85698e3e3a7aSWarner Loshfacilities for loading modules in Lua. 85708e3e3a7aSWarner LoshIt exports one function directly in the global environment: 85718e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a>. 85720495ed39SKyle EvansEverything else is exported in the table <a name="pdf-package"><code>package</code></a>. 85738e3e3a7aSWarner Losh 85748e3e3a7aSWarner Losh 85758e3e3a7aSWarner Losh<p> 85768e3e3a7aSWarner Losh<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> 85778e3e3a7aSWarner Losh 85788e3e3a7aSWarner Losh 85798e3e3a7aSWarner Losh<p> 85808e3e3a7aSWarner LoshLoads the given module. 85818e3e3a7aSWarner LoshThe function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table 85828e3e3a7aSWarner Loshto determine whether <code>modname</code> is already loaded. 85838e3e3a7aSWarner LoshIf it is, then <code>require</code> returns the value stored 85848e3e3a7aSWarner Loshat <code>package.loaded[modname]</code>. 85850495ed39SKyle Evans(The absence of a second result in this case 85860495ed39SKyle Evanssignals that this call did not have to load the module.) 85878e3e3a7aSWarner LoshOtherwise, it tries to find a <em>loader</em> for the module. 85888e3e3a7aSWarner Losh 85898e3e3a7aSWarner Losh 85908e3e3a7aSWarner Losh<p> 85918e3e3a7aSWarner LoshTo find a loader, 85920495ed39SKyle Evans<code>require</code> is guided by the table <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 85930495ed39SKyle EvansEach item in this table is a search function, 85940495ed39SKyle Evansthat searches for the module in a particular way. 85950495ed39SKyle EvansBy changing this table, 85968e3e3a7aSWarner Loshwe can change how <code>require</code> looks for a module. 85978e3e3a7aSWarner LoshThe following explanation is based on the default configuration 85988e3e3a7aSWarner Loshfor <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 85998e3e3a7aSWarner Losh 86008e3e3a7aSWarner Losh 86018e3e3a7aSWarner Losh<p> 86028e3e3a7aSWarner LoshFirst <code>require</code> queries <code>package.preload[modname]</code>. 86038e3e3a7aSWarner LoshIf it has a value, 86048e3e3a7aSWarner Loshthis value (which must be a function) is the loader. 86058e3e3a7aSWarner LoshOtherwise <code>require</code> searches for a Lua loader using the 86068e3e3a7aSWarner Loshpath stored in <a href="#pdf-package.path"><code>package.path</code></a>. 86078e3e3a7aSWarner LoshIf that also fails, it searches for a C loader using the 86088e3e3a7aSWarner Loshpath stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 86098e3e3a7aSWarner LoshIf that also fails, 86108e3e3a7aSWarner Loshit tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>). 86118e3e3a7aSWarner Losh 86128e3e3a7aSWarner Losh 86138e3e3a7aSWarner Losh<p> 86148e3e3a7aSWarner LoshOnce a loader is found, 86158e3e3a7aSWarner Losh<code>require</code> calls the loader with two arguments: 86160495ed39SKyle Evans<code>modname</code> and an extra value, 86170495ed39SKyle Evansa <em>loader data</em>, 86180495ed39SKyle Evansalso returned by the searcher. 86190495ed39SKyle EvansThe loader data can be any value useful to the module; 86200495ed39SKyle Evansfor the default searchers, 86210495ed39SKyle Evansit indicates where the loader was found. 86220495ed39SKyle Evans(For instance, if the loader came from a file, 86230495ed39SKyle Evansthis extra value is the file path.) 86248e3e3a7aSWarner LoshIf the loader returns any non-nil value, 86258e3e3a7aSWarner Losh<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. 86268e3e3a7aSWarner LoshIf the loader does not return a non-nil value and 86278e3e3a7aSWarner Loshhas not assigned any value to <code>package.loaded[modname]</code>, 86288e3e3a7aSWarner Loshthen <code>require</code> assigns <b>true</b> to this entry. 86298e3e3a7aSWarner LoshIn any case, <code>require</code> returns the 86308e3e3a7aSWarner Loshfinal value of <code>package.loaded[modname]</code>. 86310495ed39SKyle EvansBesides that value, <code>require</code> also returns as a second result 86320495ed39SKyle Evansthe loader data returned by the searcher, 86330495ed39SKyle Evanswhich indicates how <code>require</code> found the module. 86348e3e3a7aSWarner Losh 86358e3e3a7aSWarner Losh 86368e3e3a7aSWarner Losh<p> 86378e3e3a7aSWarner LoshIf there is any error loading or running the module, 86388e3e3a7aSWarner Loshor if it cannot find any loader for the module, 86398e3e3a7aSWarner Loshthen <code>require</code> raises an error. 86408e3e3a7aSWarner Losh 86418e3e3a7aSWarner Losh 86428e3e3a7aSWarner Losh 86438e3e3a7aSWarner Losh 86448e3e3a7aSWarner Losh<p> 86458e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3> 86468e3e3a7aSWarner Losh 86478e3e3a7aSWarner Losh 86488e3e3a7aSWarner Losh<p> 86498e3e3a7aSWarner LoshA string describing some compile-time configurations for packages. 86508e3e3a7aSWarner LoshThis string is a sequence of lines: 86518e3e3a7aSWarner Losh 86528e3e3a7aSWarner Losh<ul> 86538e3e3a7aSWarner Losh 86548e3e3a7aSWarner Losh<li>The first line is the directory separator string. 86558e3e3a7aSWarner LoshDefault is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li> 86568e3e3a7aSWarner Losh 86578e3e3a7aSWarner Losh<li>The second line is the character that separates templates in a path. 86588e3e3a7aSWarner LoshDefault is '<code>;</code>'.</li> 86598e3e3a7aSWarner Losh 86608e3e3a7aSWarner Losh<li>The third line is the string that marks the 86618e3e3a7aSWarner Loshsubstitution points in a template. 86628e3e3a7aSWarner LoshDefault is '<code>?</code>'.</li> 86638e3e3a7aSWarner Losh 86648e3e3a7aSWarner Losh<li>The fourth line is a string that, in a path in Windows, 86658e3e3a7aSWarner Loshis replaced by the executable's directory. 86668e3e3a7aSWarner LoshDefault is '<code>!</code>'.</li> 86678e3e3a7aSWarner Losh 86688e3e3a7aSWarner Losh<li>The fifth line is a mark to ignore all text after it 86698e3e3a7aSWarner Loshwhen building the <code>luaopen_</code> function name. 86708e3e3a7aSWarner LoshDefault is '<code>-</code>'.</li> 86718e3e3a7aSWarner Losh 86728e3e3a7aSWarner Losh</ul> 86738e3e3a7aSWarner Losh 86748e3e3a7aSWarner Losh 86758e3e3a7aSWarner Losh 86768e3e3a7aSWarner Losh<p> 86778e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> 86788e3e3a7aSWarner Losh 86798e3e3a7aSWarner Losh 86808e3e3a7aSWarner Losh<p> 86810495ed39SKyle EvansA string with the path used by <a href="#pdf-require"><code>require</code></a> 86820495ed39SKyle Evansto search for a C loader. 86838e3e3a7aSWarner Losh 86848e3e3a7aSWarner Losh 86858e3e3a7aSWarner Losh<p> 86868e3e3a7aSWarner LoshLua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way 86878e3e3a7aSWarner Loshit initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, 86880495ed39SKyle Evansusing the environment variable <a name="pdf-LUA_CPATH_5_4"><code>LUA_CPATH_5_4</code></a>, 86898e3e3a7aSWarner Loshor the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>, 86908e3e3a7aSWarner Loshor a default path defined in <code>luaconf.h</code>. 86918e3e3a7aSWarner Losh 86928e3e3a7aSWarner Losh 86938e3e3a7aSWarner Losh 86948e3e3a7aSWarner Losh 86958e3e3a7aSWarner Losh<p> 86968e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> 86978e3e3a7aSWarner Losh 86988e3e3a7aSWarner Losh 86998e3e3a7aSWarner Losh<p> 87008e3e3a7aSWarner LoshA table used by <a href="#pdf-require"><code>require</code></a> to control which 87018e3e3a7aSWarner Loshmodules are already loaded. 87028e3e3a7aSWarner LoshWhen you require a module <code>modname</code> and 87038e3e3a7aSWarner Losh<code>package.loaded[modname]</code> is not false, 87048e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a> simply returns the value stored there. 87058e3e3a7aSWarner Losh 87068e3e3a7aSWarner Losh 87078e3e3a7aSWarner Losh<p> 87088e3e3a7aSWarner LoshThis variable is only a reference to the real table; 87098e3e3a7aSWarner Loshassignments to this variable do not change the 87108e3e3a7aSWarner Loshtable used by <a href="#pdf-require"><code>require</code></a>. 87118e3e3a7aSWarner Losh 87128e3e3a7aSWarner Losh 87138e3e3a7aSWarner Losh 87148e3e3a7aSWarner Losh 87158e3e3a7aSWarner Losh<p> 87168e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> 87178e3e3a7aSWarner Losh 87188e3e3a7aSWarner Losh 87198e3e3a7aSWarner Losh<p> 87208e3e3a7aSWarner LoshDynamically links the host program with the C library <code>libname</code>. 87218e3e3a7aSWarner Losh 87228e3e3a7aSWarner Losh 87238e3e3a7aSWarner Losh<p> 87248e3e3a7aSWarner LoshIf <code>funcname</code> is "<code>*</code>", 87258e3e3a7aSWarner Loshthen it only links with the library, 87268e3e3a7aSWarner Loshmaking the symbols exported by the library 87278e3e3a7aSWarner Loshavailable to other dynamically linked libraries. 87288e3e3a7aSWarner LoshOtherwise, 87298e3e3a7aSWarner Loshit looks for a function <code>funcname</code> inside the library 87308e3e3a7aSWarner Loshand returns this function as a C function. 87318e3e3a7aSWarner LoshSo, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype 87328e3e3a7aSWarner Losh(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 87338e3e3a7aSWarner Losh 87348e3e3a7aSWarner Losh 87358e3e3a7aSWarner Losh<p> 87368e3e3a7aSWarner LoshThis is a low-level function. 87378e3e3a7aSWarner LoshIt completely bypasses the package and module system. 87388e3e3a7aSWarner LoshUnlike <a href="#pdf-require"><code>require</code></a>, 87398e3e3a7aSWarner Loshit does not perform any path searching and 87408e3e3a7aSWarner Loshdoes not automatically adds extensions. 87418e3e3a7aSWarner Losh<code>libname</code> must be the complete file name of the C library, 87428e3e3a7aSWarner Loshincluding if necessary a path and an extension. 87438e3e3a7aSWarner Losh<code>funcname</code> must be the exact name exported by the C library 87448e3e3a7aSWarner Losh(which may depend on the C compiler and linker used). 87458e3e3a7aSWarner Losh 87468e3e3a7aSWarner Losh 87478e3e3a7aSWarner Losh<p> 87488e3e3a7aSWarner LoshThis function is not supported by Standard C. 87498e3e3a7aSWarner LoshAs such, it is only available on some platforms 87508e3e3a7aSWarner Losh(Windows, Linux, Mac OS X, Solaris, BSD, 87518e3e3a7aSWarner Loshplus other Unix systems that support the <code>dlfcn</code> standard). 87528e3e3a7aSWarner Losh 87538e3e3a7aSWarner Losh 87540495ed39SKyle Evans<p> 87550495ed39SKyle EvansThis function is inherently insecure, 87560495ed39SKyle Evansas it allows Lua to call any function in any readable dynamic 87570495ed39SKyle Evanslibrary in the system. 87580495ed39SKyle Evans(Lua calls any function assuming the function 87590495ed39SKyle Evanshas a proper prototype and respects a proper protocol 87600495ed39SKyle Evans(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 87610495ed39SKyle EvansTherefore, 87620495ed39SKyle Evanscalling an arbitrary function in an arbitrary dynamic library 87630495ed39SKyle Evansmore often than not results in an access violation.) 87640495ed39SKyle Evans 87650495ed39SKyle Evans 87668e3e3a7aSWarner Losh 87678e3e3a7aSWarner Losh 87688e3e3a7aSWarner Losh<p> 87698e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> 87708e3e3a7aSWarner Losh 87718e3e3a7aSWarner Losh 87728e3e3a7aSWarner Losh<p> 87730495ed39SKyle EvansA string with the path used by <a href="#pdf-require"><code>require</code></a> 87740495ed39SKyle Evansto search for a Lua loader. 87758e3e3a7aSWarner Losh 87768e3e3a7aSWarner Losh 87778e3e3a7aSWarner Losh<p> 87788e3e3a7aSWarner LoshAt start-up, Lua initializes this variable with 87790495ed39SKyle Evansthe value of the environment variable <a name="pdf-LUA_PATH_5_4"><code>LUA_PATH_5_4</code></a> or 87808e3e3a7aSWarner Loshthe environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or 87818e3e3a7aSWarner Loshwith a default path defined in <code>luaconf.h</code>, 87828e3e3a7aSWarner Loshif those environment variables are not defined. 87830495ed39SKyle EvansA "<code>;;</code>" in the value of the environment variable 87848e3e3a7aSWarner Loshis replaced by the default path. 87858e3e3a7aSWarner Losh 87868e3e3a7aSWarner Losh 87878e3e3a7aSWarner Losh 87888e3e3a7aSWarner Losh 87898e3e3a7aSWarner Losh<p> 87908e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> 87918e3e3a7aSWarner Losh 87928e3e3a7aSWarner Losh 87938e3e3a7aSWarner Losh<p> 87948e3e3a7aSWarner LoshA table to store loaders for specific modules 87958e3e3a7aSWarner Losh(see <a href="#pdf-require"><code>require</code></a>). 87968e3e3a7aSWarner Losh 87978e3e3a7aSWarner Losh 87988e3e3a7aSWarner Losh<p> 87998e3e3a7aSWarner LoshThis variable is only a reference to the real table; 88008e3e3a7aSWarner Loshassignments to this variable do not change the 88018e3e3a7aSWarner Loshtable used by <a href="#pdf-require"><code>require</code></a>. 88028e3e3a7aSWarner Losh 88038e3e3a7aSWarner Losh 88048e3e3a7aSWarner Losh 88058e3e3a7aSWarner Losh 88068e3e3a7aSWarner Losh<p> 88078e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3> 88088e3e3a7aSWarner Losh 88098e3e3a7aSWarner Losh 88108e3e3a7aSWarner Losh<p> 88110495ed39SKyle EvansA table used by <a href="#pdf-require"><code>require</code></a> to control how to find modules. 88128e3e3a7aSWarner Losh 88138e3e3a7aSWarner Losh 88148e3e3a7aSWarner Losh<p> 88158e3e3a7aSWarner LoshEach entry in this table is a <em>searcher function</em>. 88168e3e3a7aSWarner LoshWhen looking for a module, 88178e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, 88188e3e3a7aSWarner Loshwith the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its 88190495ed39SKyle Evanssole argument. 88200495ed39SKyle EvansIf the searcher finds the module, 88210495ed39SKyle Evansit returns another function, the module <em>loader</em>, 88220495ed39SKyle Evansplus an extra value, a <em>loader data</em>, 88230495ed39SKyle Evansthat will be passed to that loader and 88240495ed39SKyle Evansreturned as a second result by <a href="#pdf-require"><code>require</code></a>. 88250495ed39SKyle EvansIf it cannot find the module, 88260495ed39SKyle Evansit returns a string explaining why 88278e3e3a7aSWarner Losh(or <b>nil</b> if it has nothing to say). 88288e3e3a7aSWarner Losh 88298e3e3a7aSWarner Losh 88308e3e3a7aSWarner Losh<p> 88318e3e3a7aSWarner LoshLua initializes this table with four searcher functions. 88328e3e3a7aSWarner Losh 88338e3e3a7aSWarner Losh 88348e3e3a7aSWarner Losh<p> 88358e3e3a7aSWarner LoshThe first searcher simply looks for a loader in the 88368e3e3a7aSWarner Losh<a href="#pdf-package.preload"><code>package.preload</code></a> table. 88378e3e3a7aSWarner Losh 88388e3e3a7aSWarner Losh 88398e3e3a7aSWarner Losh<p> 88408e3e3a7aSWarner LoshThe second searcher looks for a loader as a Lua library, 88418e3e3a7aSWarner Loshusing the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. 88428e3e3a7aSWarner LoshThe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 88438e3e3a7aSWarner Losh 88448e3e3a7aSWarner Losh 88458e3e3a7aSWarner Losh<p> 88468e3e3a7aSWarner LoshThe third searcher looks for a loader as a C library, 88478e3e3a7aSWarner Loshusing the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 88488e3e3a7aSWarner LoshAgain, 88498e3e3a7aSWarner Loshthe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 88508e3e3a7aSWarner LoshFor instance, 88518e3e3a7aSWarner Loshif the C path is the string 88528e3e3a7aSWarner Losh 88538e3e3a7aSWarner Losh<pre> 88548e3e3a7aSWarner Losh "./?.so;./?.dll;/usr/local/?/init.so" 88558e3e3a7aSWarner Losh</pre><p> 88568e3e3a7aSWarner Loshthe searcher for module <code>foo</code> 88578e3e3a7aSWarner Loshwill try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, 88588e3e3a7aSWarner Loshand <code>/usr/local/foo/init.so</code>, in that order. 88598e3e3a7aSWarner LoshOnce it finds a C library, 88608e3e3a7aSWarner Loshthis searcher first uses a dynamic link facility to link the 88618e3e3a7aSWarner Loshapplication with the library. 88628e3e3a7aSWarner LoshThen it tries to find a C function inside the library to 88638e3e3a7aSWarner Loshbe used as the loader. 88648e3e3a7aSWarner LoshThe name of this C function is the string "<code>luaopen_</code>" 88658e3e3a7aSWarner Loshconcatenated with a copy of the module name where each dot 88668e3e3a7aSWarner Loshis replaced by an underscore. 88678e3e3a7aSWarner LoshMoreover, if the module name has a hyphen, 88688e3e3a7aSWarner Loshits suffix after (and including) the first hyphen is removed. 88698e3e3a7aSWarner LoshFor instance, if the module name is <code>a.b.c-v2.1</code>, 88708e3e3a7aSWarner Loshthe function name will be <code>luaopen_a_b_c</code>. 88718e3e3a7aSWarner Losh 88728e3e3a7aSWarner Losh 88738e3e3a7aSWarner Losh<p> 88748e3e3a7aSWarner LoshThe fourth searcher tries an <em>all-in-one loader</em>. 88758e3e3a7aSWarner LoshIt searches the C path for a library for 88768e3e3a7aSWarner Loshthe root name of the given module. 88778e3e3a7aSWarner LoshFor instance, when requiring <code>a.b.c</code>, 88788e3e3a7aSWarner Loshit will search for a C library for <code>a</code>. 88798e3e3a7aSWarner LoshIf found, it looks into it for an open function for 88808e3e3a7aSWarner Loshthe submodule; 88818e3e3a7aSWarner Loshin our example, that would be <code>luaopen_a_b_c</code>. 88828e3e3a7aSWarner LoshWith this facility, a package can pack several C submodules 88838e3e3a7aSWarner Loshinto one single library, 88848e3e3a7aSWarner Loshwith each submodule keeping its original open function. 88858e3e3a7aSWarner Losh 88868e3e3a7aSWarner Losh 88878e3e3a7aSWarner Losh<p> 88888e3e3a7aSWarner LoshAll searchers except the first one (preload) return as the extra value 88890495ed39SKyle Evansthe file path where the module was found, 88908e3e3a7aSWarner Loshas returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 88910495ed39SKyle EvansThe first searcher always returns the string "<code>:preload:</code>". 88920495ed39SKyle Evans 88930495ed39SKyle Evans 88940495ed39SKyle Evans<p> 88950495ed39SKyle EvansSearchers should raise no errors and have no side effects in Lua. 88960495ed39SKyle Evans(They may have side effects in C, 88970495ed39SKyle Evansfor instance by linking the application with a library.) 88988e3e3a7aSWarner Losh 88998e3e3a7aSWarner Losh 89008e3e3a7aSWarner Losh 89018e3e3a7aSWarner Losh 89028e3e3a7aSWarner Losh<p> 89038e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3> 89048e3e3a7aSWarner Losh 89058e3e3a7aSWarner Losh 89068e3e3a7aSWarner Losh<p> 89078e3e3a7aSWarner LoshSearches for the given <code>name</code> in the given <code>path</code>. 89088e3e3a7aSWarner Losh 89098e3e3a7aSWarner Losh 89108e3e3a7aSWarner Losh<p> 89118e3e3a7aSWarner LoshA path is a string containing a sequence of 89128e3e3a7aSWarner Losh<em>templates</em> separated by semicolons. 89138e3e3a7aSWarner LoshFor each template, 89148e3e3a7aSWarner Loshthe function replaces each interrogation mark (if any) 89158e3e3a7aSWarner Loshin the template with a copy of <code>name</code> 89168e3e3a7aSWarner Loshwherein all occurrences of <code>sep</code> 89178e3e3a7aSWarner Losh(a dot, by default) 89188e3e3a7aSWarner Loshwere replaced by <code>rep</code> 89198e3e3a7aSWarner Losh(the system's directory separator, by default), 89208e3e3a7aSWarner Loshand then tries to open the resulting file name. 89218e3e3a7aSWarner Losh 89228e3e3a7aSWarner Losh 89238e3e3a7aSWarner Losh<p> 89248e3e3a7aSWarner LoshFor instance, if the path is the string 89258e3e3a7aSWarner Losh 89268e3e3a7aSWarner Losh<pre> 89278e3e3a7aSWarner Losh "./?.lua;./?.lc;/usr/local/?/init.lua" 89288e3e3a7aSWarner Losh</pre><p> 89298e3e3a7aSWarner Loshthe search for the name <code>foo.a</code> 89308e3e3a7aSWarner Loshwill try to open the files 89318e3e3a7aSWarner Losh<code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and 89328e3e3a7aSWarner Losh<code>/usr/local/foo/a/init.lua</code>, in that order. 89338e3e3a7aSWarner Losh 89348e3e3a7aSWarner Losh 89358e3e3a7aSWarner Losh<p> 89368e3e3a7aSWarner LoshReturns the resulting name of the first file that it can 89378e3e3a7aSWarner Loshopen in read mode (after closing the file), 89380495ed39SKyle Evansor <b>fail</b> plus an error message if none succeeds. 89398e3e3a7aSWarner Losh(This error message lists all file names it tried to open.) 89408e3e3a7aSWarner Losh 89418e3e3a7aSWarner Losh 89428e3e3a7aSWarner Losh 89438e3e3a7aSWarner Losh 89448e3e3a7aSWarner Losh 89458e3e3a7aSWarner Losh 89468e3e3a7aSWarner Losh 89478e3e3a7aSWarner Losh<h2>6.4 – <a name="6.4">String Manipulation</a></h2> 89488e3e3a7aSWarner Losh 89490495ed39SKyle Evans 89500495ed39SKyle Evans 89518e3e3a7aSWarner Losh<p> 89528e3e3a7aSWarner LoshThis library provides generic functions for string manipulation, 89538e3e3a7aSWarner Loshsuch as finding and extracting substrings, and pattern matching. 89548e3e3a7aSWarner LoshWhen indexing a string in Lua, the first character is at position 1 89558e3e3a7aSWarner Losh(not at 0, as in C). 89568e3e3a7aSWarner LoshIndices are allowed to be negative and are interpreted as indexing backwards, 89578e3e3a7aSWarner Loshfrom the end of the string. 89588e3e3a7aSWarner LoshThus, the last character is at position -1, and so on. 89598e3e3a7aSWarner Losh 89608e3e3a7aSWarner Losh 89618e3e3a7aSWarner Losh<p> 89628e3e3a7aSWarner LoshThe string library provides all its functions inside the table 89638e3e3a7aSWarner Losh<a name="pdf-string"><code>string</code></a>. 89648e3e3a7aSWarner LoshIt also sets a metatable for strings 89658e3e3a7aSWarner Loshwhere the <code>__index</code> field points to the <code>string</code> table. 89668e3e3a7aSWarner LoshTherefore, you can use the string functions in object-oriented style. 89678e3e3a7aSWarner LoshFor instance, <code>string.byte(s,i)</code> 89688e3e3a7aSWarner Loshcan be written as <code>s:byte(i)</code>. 89698e3e3a7aSWarner Losh 89708e3e3a7aSWarner Losh 89718e3e3a7aSWarner Losh<p> 89728e3e3a7aSWarner LoshThe string library assumes one-byte character encodings. 89738e3e3a7aSWarner Losh 89748e3e3a7aSWarner Losh 89758e3e3a7aSWarner Losh<p> 89768e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> 89778e3e3a7aSWarner LoshReturns the internal numeric codes of the characters <code>s[i]</code>, 89788e3e3a7aSWarner Losh<code>s[i+1]</code>, ..., <code>s[j]</code>. 89798e3e3a7aSWarner LoshThe default value for <code>i</code> is 1; 89808e3e3a7aSWarner Loshthe default value for <code>j</code> is <code>i</code>. 89818e3e3a7aSWarner LoshThese indices are corrected 89828e3e3a7aSWarner Loshfollowing the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>. 89838e3e3a7aSWarner Losh 89848e3e3a7aSWarner Losh 89858e3e3a7aSWarner Losh<p> 89868e3e3a7aSWarner LoshNumeric codes are not necessarily portable across platforms. 89878e3e3a7aSWarner Losh 89888e3e3a7aSWarner Losh 89898e3e3a7aSWarner Losh 89908e3e3a7aSWarner Losh 89918e3e3a7aSWarner Losh<p> 89928e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> 89938e3e3a7aSWarner LoshReceives zero or more integers. 89948e3e3a7aSWarner LoshReturns a string with length equal to the number of arguments, 89958e3e3a7aSWarner Loshin which each character has the internal numeric code equal 89968e3e3a7aSWarner Loshto its corresponding argument. 89978e3e3a7aSWarner Losh 89988e3e3a7aSWarner Losh 89998e3e3a7aSWarner Losh<p> 90008e3e3a7aSWarner LoshNumeric codes are not necessarily portable across platforms. 90018e3e3a7aSWarner Losh 90028e3e3a7aSWarner Losh 90038e3e3a7aSWarner Losh 90048e3e3a7aSWarner Losh 90058e3e3a7aSWarner Losh<p> 90068e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3> 90078e3e3a7aSWarner Losh 90088e3e3a7aSWarner Losh 90098e3e3a7aSWarner Losh<p> 90108e3e3a7aSWarner LoshReturns a string containing a binary representation 90118e3e3a7aSWarner Losh(a <em>binary chunk</em>) 90128e3e3a7aSWarner Loshof the given function, 90138e3e3a7aSWarner Loshso that a later <a href="#pdf-load"><code>load</code></a> on this string returns 90148e3e3a7aSWarner Losha copy of the function (but with new upvalues). 90158e3e3a7aSWarner LoshIf <code>strip</code> is a true value, 90168e3e3a7aSWarner Loshthe binary representation may not include all debug information 90178e3e3a7aSWarner Loshabout the function, 90188e3e3a7aSWarner Loshto save space. 90198e3e3a7aSWarner Losh 90208e3e3a7aSWarner Losh 90218e3e3a7aSWarner Losh<p> 90228e3e3a7aSWarner LoshFunctions with upvalues have only their number of upvalues saved. 90238e3e3a7aSWarner LoshWhen (re)loaded, 90240495ed39SKyle Evansthose upvalues receive fresh instances. 90250495ed39SKyle Evans(See the <a href="#pdf-load"><code>load</code></a> function for details about 90260495ed39SKyle Evanshow these upvalues are initialized. 90270495ed39SKyle EvansYou can use the debug library to serialize 90288e3e3a7aSWarner Loshand reload the upvalues of a function 90298e3e3a7aSWarner Loshin a way adequate to your needs.) 90308e3e3a7aSWarner Losh 90318e3e3a7aSWarner Losh 90328e3e3a7aSWarner Losh 90338e3e3a7aSWarner Losh 90348e3e3a7aSWarner Losh<p> 90358e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> 90368e3e3a7aSWarner Losh 90378e3e3a7aSWarner Losh 90388e3e3a7aSWarner Losh<p> 90398e3e3a7aSWarner LoshLooks for the first match of 90408e3e3a7aSWarner Losh<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 90418e3e3a7aSWarner LoshIf it finds a match, then <code>find</code> returns the indices of <code>s</code> 90428e3e3a7aSWarner Loshwhere this occurrence starts and ends; 90430495ed39SKyle Evansotherwise, it returns <b>fail</b>. 90448e3e3a7aSWarner LoshA third, optional numeric argument <code>init</code> specifies 90458e3e3a7aSWarner Loshwhere to start the search; 90468e3e3a7aSWarner Loshits default value is 1 and can be negative. 9047*8c784bb8SWarner LoshA <b>true</b> as a fourth, optional argument <code>plain</code> 90488e3e3a7aSWarner Loshturns off the pattern matching facilities, 90498e3e3a7aSWarner Loshso the function does a plain "find substring" operation, 90508e3e3a7aSWarner Loshwith no characters in <code>pattern</code> being considered magic. 90518e3e3a7aSWarner Losh 90528e3e3a7aSWarner Losh 90538e3e3a7aSWarner Losh<p> 90548e3e3a7aSWarner LoshIf the pattern has captures, 90558e3e3a7aSWarner Loshthen in a successful match 90568e3e3a7aSWarner Loshthe captured values are also returned, 90578e3e3a7aSWarner Loshafter the two indices. 90588e3e3a7aSWarner Losh 90598e3e3a7aSWarner Losh 90608e3e3a7aSWarner Losh 90618e3e3a7aSWarner Losh 90628e3e3a7aSWarner Losh<p> 90638e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> 90648e3e3a7aSWarner Losh 90658e3e3a7aSWarner Losh 90668e3e3a7aSWarner Losh<p> 90678e3e3a7aSWarner LoshReturns a formatted version of its variable number of arguments 90680495ed39SKyle Evansfollowing the description given in its first argument, 90690495ed39SKyle Evanswhich must be a string. 90708e3e3a7aSWarner LoshThe format string follows the same rules as the ISO C function <code>sprintf</code>. 90710495ed39SKyle EvansThe only differences are that the conversion specifiers and modifiers 9072*8c784bb8SWarner Losh<code>F</code>, <code>n</code>, <code>*</code>, <code>h</code>, <code>L</code>, and <code>l</code> are not supported 90730495ed39SKyle Evansand that there is an extra specifier, <code>q</code>. 9074*8c784bb8SWarner LoshBoth width and precision, when present, 9075*8c784bb8SWarner Loshare limited to two digits. 90768e3e3a7aSWarner Losh 90778e3e3a7aSWarner Losh 90788e3e3a7aSWarner Losh<p> 90790495ed39SKyle EvansThe specifier <code>q</code> formats booleans, nil, numbers, and strings 90800495ed39SKyle Evansin a way that the result is a valid constant in Lua source code. 90810495ed39SKyle EvansBooleans and nil are written in the obvious way 90820495ed39SKyle Evans(<code>true</code>, <code>false</code>, <code>nil</code>). 90830495ed39SKyle EvansFloats are written in hexadecimal, 90840495ed39SKyle Evansto preserve full precision. 90850495ed39SKyle EvansA string is written between double quotes, 90868e3e3a7aSWarner Loshusing escape sequences when necessary to ensure that 90878e3e3a7aSWarner Loshit can safely be read back by the Lua interpreter. 90888e3e3a7aSWarner LoshFor instance, the call 90898e3e3a7aSWarner Losh 90908e3e3a7aSWarner Losh<pre> 90918e3e3a7aSWarner Losh string.format('%q', 'a string with "quotes" and \n new line') 90928e3e3a7aSWarner Losh</pre><p> 90938e3e3a7aSWarner Loshmay produce the string: 90948e3e3a7aSWarner Losh 90958e3e3a7aSWarner Losh<pre> 90968e3e3a7aSWarner Losh "a string with \"quotes\" and \ 90978e3e3a7aSWarner Losh new line" 90980495ed39SKyle Evans</pre><p> 9099*8c784bb8SWarner LoshThis specifier does not support modifiers (flags, width, precision). 91000495ed39SKyle Evans 91018e3e3a7aSWarner Losh 91028e3e3a7aSWarner Losh<p> 91030495ed39SKyle EvansThe conversion specifiers 91048e3e3a7aSWarner Losh<code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>, 91058e3e3a7aSWarner Losh<code>G</code>, and <code>g</code> all expect a number as argument. 91060495ed39SKyle EvansThe specifiers <code>c</code>, <code>d</code>, 91078e3e3a7aSWarner Losh<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> 91088e3e3a7aSWarner Loshexpect an integer. 91098e3e3a7aSWarner LoshWhen Lua is compiled with a C89 compiler, 91100495ed39SKyle Evansthe specifiers <code>A</code> and <code>a</code> (hexadecimal floats) 91110495ed39SKyle Evansdo not support modifiers. 91128e3e3a7aSWarner Losh 91138e3e3a7aSWarner Losh 91148e3e3a7aSWarner Losh<p> 91150495ed39SKyle EvansThe specifier <code>s</code> expects a string; 91168e3e3a7aSWarner Loshif its argument is not a string, 91178e3e3a7aSWarner Loshit is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 91180495ed39SKyle EvansIf the specifier has any modifier, 91190495ed39SKyle Evansthe corresponding string argument should not contain embedded zeros. 91200495ed39SKyle Evans 91210495ed39SKyle Evans 91220495ed39SKyle Evans<p> 91230495ed39SKyle EvansThe specifier <code>p</code> formats the pointer 91240495ed39SKyle Evansreturned by <a href="#lua_topointer"><code>lua_topointer</code></a>. 91250495ed39SKyle EvansThat gives a unique string identifier for tables, userdata, 91260495ed39SKyle Evansthreads, strings, and functions. 91270495ed39SKyle EvansFor other values (numbers, nil, booleans), 91280495ed39SKyle Evansthis specifier results in a string representing 91290495ed39SKyle Evansthe pointer <code>NULL</code>. 91308e3e3a7aSWarner Losh 91318e3e3a7aSWarner Losh 91328e3e3a7aSWarner Losh 91338e3e3a7aSWarner Losh 91348e3e3a7aSWarner Losh<p> 91350495ed39SKyle Evans<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern [, init])</code></a></h3> 91368e3e3a7aSWarner LoshReturns an iterator function that, 91378e3e3a7aSWarner Losheach time it is called, 91388e3e3a7aSWarner Loshreturns the next captures from <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) 91398e3e3a7aSWarner Loshover the string <code>s</code>. 91408e3e3a7aSWarner LoshIf <code>pattern</code> specifies no captures, 91418e3e3a7aSWarner Loshthen the whole match is produced in each call. 91420495ed39SKyle EvansA third, optional numeric argument <code>init</code> specifies 91430495ed39SKyle Evanswhere to start the search; 91440495ed39SKyle Evansits default value is 1 and can be negative. 91458e3e3a7aSWarner Losh 91468e3e3a7aSWarner Losh 91478e3e3a7aSWarner Losh<p> 91488e3e3a7aSWarner LoshAs an example, the following loop 91498e3e3a7aSWarner Loshwill iterate over all the words from string <code>s</code>, 91508e3e3a7aSWarner Loshprinting one per line: 91518e3e3a7aSWarner Losh 91528e3e3a7aSWarner Losh<pre> 91538e3e3a7aSWarner Losh s = "hello world from Lua" 91548e3e3a7aSWarner Losh for w in string.gmatch(s, "%a+") do 91558e3e3a7aSWarner Losh print(w) 91568e3e3a7aSWarner Losh end 91578e3e3a7aSWarner Losh</pre><p> 91588e3e3a7aSWarner LoshThe next example collects all pairs <code>key=value</code> from the 91598e3e3a7aSWarner Loshgiven string into a table: 91608e3e3a7aSWarner Losh 91618e3e3a7aSWarner Losh<pre> 91628e3e3a7aSWarner Losh t = {} 91638e3e3a7aSWarner Losh s = "from=world, to=Lua" 91648e3e3a7aSWarner Losh for k, v in string.gmatch(s, "(%w+)=(%w+)") do 91658e3e3a7aSWarner Losh t[k] = v 91668e3e3a7aSWarner Losh end 91678e3e3a7aSWarner Losh</pre> 91688e3e3a7aSWarner Losh 91698e3e3a7aSWarner Losh<p> 91708e3e3a7aSWarner LoshFor this function, a caret '<code>^</code>' at the start of a pattern does not 91718e3e3a7aSWarner Loshwork as an anchor, as this would prevent the iteration. 91728e3e3a7aSWarner Losh 91738e3e3a7aSWarner Losh 91748e3e3a7aSWarner Losh 91758e3e3a7aSWarner Losh 91768e3e3a7aSWarner Losh<p> 91778e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> 91788e3e3a7aSWarner LoshReturns a copy of <code>s</code> 91798e3e3a7aSWarner Loshin which all (or the first <code>n</code>, if given) 91808e3e3a7aSWarner Loshoccurrences of the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) have been 91818e3e3a7aSWarner Loshreplaced by a replacement string specified by <code>repl</code>, 91828e3e3a7aSWarner Loshwhich can be a string, a table, or a function. 91838e3e3a7aSWarner Losh<code>gsub</code> also returns, as its second value, 91848e3e3a7aSWarner Loshthe total number of matches that occurred. 91858e3e3a7aSWarner LoshThe name <code>gsub</code> comes from <em>Global SUBstitution</em>. 91868e3e3a7aSWarner Losh 91878e3e3a7aSWarner Losh 91888e3e3a7aSWarner Losh<p> 91898e3e3a7aSWarner LoshIf <code>repl</code> is a string, then its value is used for replacement. 91908e3e3a7aSWarner LoshThe character <code>%</code> works as an escape character: 91918e3e3a7aSWarner Loshany sequence in <code>repl</code> of the form <code>%<em>d</em></code>, 91928e3e3a7aSWarner Loshwith <em>d</em> between 1 and 9, 91930495ed39SKyle Evansstands for the value of the <em>d</em>-th captured substring; 91940495ed39SKyle Evansthe sequence <code>%0</code> stands for the whole match; 91950495ed39SKyle Evansthe sequence <code>%%</code> stands for a single <code>%</code>. 91968e3e3a7aSWarner Losh 91978e3e3a7aSWarner Losh 91988e3e3a7aSWarner Losh<p> 91998e3e3a7aSWarner LoshIf <code>repl</code> is a table, then the table is queried for every match, 92008e3e3a7aSWarner Loshusing the first capture as the key. 92018e3e3a7aSWarner Losh 92028e3e3a7aSWarner Losh 92038e3e3a7aSWarner Losh<p> 92048e3e3a7aSWarner LoshIf <code>repl</code> is a function, then this function is called every time a 92058e3e3a7aSWarner Loshmatch occurs, with all captured substrings passed as arguments, 92068e3e3a7aSWarner Loshin order. 92078e3e3a7aSWarner Losh 92088e3e3a7aSWarner Losh 92098e3e3a7aSWarner Losh<p> 92108e3e3a7aSWarner LoshIn any case, 92118e3e3a7aSWarner Loshif the pattern specifies no captures, 92128e3e3a7aSWarner Loshthen it behaves as if the whole pattern was inside a capture. 92138e3e3a7aSWarner Losh 92148e3e3a7aSWarner Losh 92158e3e3a7aSWarner Losh<p> 92168e3e3a7aSWarner LoshIf the value returned by the table query or by the function call 92178e3e3a7aSWarner Loshis a string or a number, 92188e3e3a7aSWarner Loshthen it is used as the replacement string; 92198e3e3a7aSWarner Loshotherwise, if it is <b>false</b> or <b>nil</b>, 92208e3e3a7aSWarner Loshthen there is no replacement 92218e3e3a7aSWarner Losh(that is, the original match is kept in the string). 92228e3e3a7aSWarner Losh 92238e3e3a7aSWarner Losh 92248e3e3a7aSWarner Losh<p> 92258e3e3a7aSWarner LoshHere are some examples: 92268e3e3a7aSWarner Losh 92278e3e3a7aSWarner Losh<pre> 92288e3e3a7aSWarner Losh x = string.gsub("hello world", "(%w+)", "%1 %1") 92298e3e3a7aSWarner Losh --> x="hello hello world world" 92308e3e3a7aSWarner Losh 92318e3e3a7aSWarner Losh x = string.gsub("hello world", "%w+", "%0 %0", 1) 92328e3e3a7aSWarner Losh --> x="hello hello world" 92338e3e3a7aSWarner Losh 92348e3e3a7aSWarner Losh x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 92358e3e3a7aSWarner Losh --> x="world hello Lua from" 92368e3e3a7aSWarner Losh 92378e3e3a7aSWarner Losh x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) 92388e3e3a7aSWarner Losh --> x="home = /home/roberto, user = roberto" 92398e3e3a7aSWarner Losh 92408e3e3a7aSWarner Losh x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 92418e3e3a7aSWarner Losh return load(s)() 92428e3e3a7aSWarner Losh end) 92438e3e3a7aSWarner Losh --> x="4+5 = 9" 92448e3e3a7aSWarner Losh 92450495ed39SKyle Evans local t = {name="lua", version="5.4"} 92468e3e3a7aSWarner Losh x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 92470495ed39SKyle Evans --> x="lua-5.4.tar.gz" 92488e3e3a7aSWarner Losh</pre> 92498e3e3a7aSWarner Losh 92508e3e3a7aSWarner Losh 92518e3e3a7aSWarner Losh 92528e3e3a7aSWarner Losh<p> 92538e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> 92540495ed39SKyle Evans 92550495ed39SKyle Evans 92560495ed39SKyle Evans<p> 92578e3e3a7aSWarner LoshReceives a string and returns its length. 92588e3e3a7aSWarner LoshThe empty string <code>""</code> has length 0. 92598e3e3a7aSWarner LoshEmbedded zeros are counted, 92608e3e3a7aSWarner Loshso <code>"a\000bc\000"</code> has length 5. 92618e3e3a7aSWarner Losh 92628e3e3a7aSWarner Losh 92638e3e3a7aSWarner Losh 92648e3e3a7aSWarner Losh 92658e3e3a7aSWarner Losh<p> 92668e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> 92670495ed39SKyle Evans 92680495ed39SKyle Evans 92690495ed39SKyle Evans<p> 92708e3e3a7aSWarner LoshReceives a string and returns a copy of this string with all 92718e3e3a7aSWarner Loshuppercase letters changed to lowercase. 92728e3e3a7aSWarner LoshAll other characters are left unchanged. 92738e3e3a7aSWarner LoshThe definition of what an uppercase letter is depends on the current locale. 92748e3e3a7aSWarner Losh 92758e3e3a7aSWarner Losh 92768e3e3a7aSWarner Losh 92778e3e3a7aSWarner Losh 92788e3e3a7aSWarner Losh<p> 92798e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> 92800495ed39SKyle Evans 92810495ed39SKyle Evans 92820495ed39SKyle Evans<p> 92838e3e3a7aSWarner LoshLooks for the first <em>match</em> of 92840495ed39SKyle Evansthe <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 92858e3e3a7aSWarner LoshIf it finds one, then <code>match</code> returns 92868e3e3a7aSWarner Loshthe captures from the pattern; 92870495ed39SKyle Evansotherwise it returns <b>fail</b>. 92888e3e3a7aSWarner LoshIf <code>pattern</code> specifies no captures, 92898e3e3a7aSWarner Loshthen the whole match is returned. 92908e3e3a7aSWarner LoshA third, optional numeric argument <code>init</code> specifies 92918e3e3a7aSWarner Loshwhere to start the search; 92928e3e3a7aSWarner Loshits default value is 1 and can be negative. 92938e3e3a7aSWarner Losh 92948e3e3a7aSWarner Losh 92958e3e3a7aSWarner Losh 92968e3e3a7aSWarner Losh 92978e3e3a7aSWarner Losh<p> 92988e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, ···)</code></a></h3> 92998e3e3a7aSWarner Losh 93008e3e3a7aSWarner Losh 93018e3e3a7aSWarner Losh<p> 93028e3e3a7aSWarner LoshReturns a binary string containing the values <code>v1</code>, <code>v2</code>, etc. 93030495ed39SKyle Evansserialized in binary form (packed) 93048e3e3a7aSWarner Loshaccording to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 93058e3e3a7aSWarner Losh 93068e3e3a7aSWarner Losh 93078e3e3a7aSWarner Losh 93088e3e3a7aSWarner Losh 93098e3e3a7aSWarner Losh<p> 93108e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3> 93118e3e3a7aSWarner Losh 93128e3e3a7aSWarner Losh 93138e3e3a7aSWarner Losh<p> 93148e3e3a7aSWarner LoshReturns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a> 93158e3e3a7aSWarner Loshwith the given format. 93168e3e3a7aSWarner LoshThe format string cannot have the variable-length options 93178e3e3a7aSWarner Losh'<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">§6.4.2</a>). 93188e3e3a7aSWarner Losh 93198e3e3a7aSWarner Losh 93208e3e3a7aSWarner Losh 93218e3e3a7aSWarner Losh 93228e3e3a7aSWarner Losh<p> 93238e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3> 93240495ed39SKyle Evans 93250495ed39SKyle Evans 93260495ed39SKyle Evans<p> 93278e3e3a7aSWarner LoshReturns a string that is the concatenation of <code>n</code> copies of 93288e3e3a7aSWarner Loshthe string <code>s</code> separated by the string <code>sep</code>. 93298e3e3a7aSWarner LoshThe default value for <code>sep</code> is the empty string 93308e3e3a7aSWarner Losh(that is, no separator). 93318e3e3a7aSWarner LoshReturns the empty string if <code>n</code> is not positive. 93328e3e3a7aSWarner Losh 93338e3e3a7aSWarner Losh 93348e3e3a7aSWarner Losh<p> 93358e3e3a7aSWarner Losh(Note that it is very easy to exhaust the memory of your machine 93368e3e3a7aSWarner Loshwith a single call to this function.) 93378e3e3a7aSWarner Losh 93388e3e3a7aSWarner Losh 93398e3e3a7aSWarner Losh 93408e3e3a7aSWarner Losh 93418e3e3a7aSWarner Losh<p> 93428e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> 93430495ed39SKyle Evans 93440495ed39SKyle Evans 93450495ed39SKyle Evans<p> 93468e3e3a7aSWarner LoshReturns a string that is the string <code>s</code> reversed. 93478e3e3a7aSWarner Losh 93488e3e3a7aSWarner Losh 93498e3e3a7aSWarner Losh 93508e3e3a7aSWarner Losh 93518e3e3a7aSWarner Losh<p> 93528e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> 93530495ed39SKyle Evans 93540495ed39SKyle Evans 93550495ed39SKyle Evans<p> 93568e3e3a7aSWarner LoshReturns the substring of <code>s</code> that 93578e3e3a7aSWarner Loshstarts at <code>i</code> and continues until <code>j</code>; 93588e3e3a7aSWarner Losh<code>i</code> and <code>j</code> can be negative. 93598e3e3a7aSWarner LoshIf <code>j</code> is absent, then it is assumed to be equal to -1 93608e3e3a7aSWarner Losh(which is the same as the string length). 93618e3e3a7aSWarner LoshIn particular, 93628e3e3a7aSWarner Loshthe call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 93638e3e3a7aSWarner Loshwith length <code>j</code>, 93648e3e3a7aSWarner Loshand <code>string.sub(s, -i)</code> (for a positive <code>i</code>) 93658e3e3a7aSWarner Loshreturns a suffix of <code>s</code> 93668e3e3a7aSWarner Loshwith length <code>i</code>. 93678e3e3a7aSWarner Losh 93688e3e3a7aSWarner Losh 93698e3e3a7aSWarner Losh<p> 93708e3e3a7aSWarner LoshIf, after the translation of negative indices, 93718e3e3a7aSWarner Losh<code>i</code> is less than 1, 93728e3e3a7aSWarner Loshit is corrected to 1. 93738e3e3a7aSWarner LoshIf <code>j</code> is greater than the string length, 93748e3e3a7aSWarner Loshit is corrected to that length. 93758e3e3a7aSWarner LoshIf, after these corrections, 93768e3e3a7aSWarner Losh<code>i</code> is greater than <code>j</code>, 93778e3e3a7aSWarner Loshthe function returns the empty string. 93788e3e3a7aSWarner Losh 93798e3e3a7aSWarner Losh 93808e3e3a7aSWarner Losh 93818e3e3a7aSWarner Losh 93828e3e3a7aSWarner Losh<p> 93838e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3> 93848e3e3a7aSWarner Losh 93858e3e3a7aSWarner Losh 93868e3e3a7aSWarner Losh<p> 93878e3e3a7aSWarner LoshReturns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>) 93888e3e3a7aSWarner Loshaccording to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 93898e3e3a7aSWarner LoshAn optional <code>pos</code> marks where 93908e3e3a7aSWarner Loshto start reading in <code>s</code> (default is 1). 93918e3e3a7aSWarner LoshAfter the read values, 93928e3e3a7aSWarner Loshthis function also returns the index of the first unread byte in <code>s</code>. 93938e3e3a7aSWarner Losh 93948e3e3a7aSWarner Losh 93958e3e3a7aSWarner Losh 93968e3e3a7aSWarner Losh 93978e3e3a7aSWarner Losh<p> 93988e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> 93990495ed39SKyle Evans 94000495ed39SKyle Evans 94010495ed39SKyle Evans<p> 94028e3e3a7aSWarner LoshReceives a string and returns a copy of this string with all 94038e3e3a7aSWarner Loshlowercase letters changed to uppercase. 94048e3e3a7aSWarner LoshAll other characters are left unchanged. 94058e3e3a7aSWarner LoshThe definition of what a lowercase letter is depends on the current locale. 94068e3e3a7aSWarner Losh 94078e3e3a7aSWarner Losh 94088e3e3a7aSWarner Losh 94098e3e3a7aSWarner Losh 94108e3e3a7aSWarner Losh 94110495ed39SKyle Evans 94120495ed39SKyle Evans 94138e3e3a7aSWarner Losh<h3>6.4.1 – <a name="6.4.1">Patterns</a></h3> 94148e3e3a7aSWarner Losh 94150495ed39SKyle Evans 94160495ed39SKyle Evans 94178e3e3a7aSWarner Losh<p> 94188e3e3a7aSWarner LoshPatterns in Lua are described by regular strings, 94198e3e3a7aSWarner Loshwhich are interpreted as patterns by the pattern-matching functions 94208e3e3a7aSWarner Losh<a href="#pdf-string.find"><code>string.find</code></a>, 94218e3e3a7aSWarner Losh<a href="#pdf-string.gmatch"><code>string.gmatch</code></a>, 94228e3e3a7aSWarner Losh<a href="#pdf-string.gsub"><code>string.gsub</code></a>, 94238e3e3a7aSWarner Loshand <a href="#pdf-string.match"><code>string.match</code></a>. 94248e3e3a7aSWarner LoshThis section describes the syntax and the meaning 94258e3e3a7aSWarner Losh(that is, what they match) of these strings. 94268e3e3a7aSWarner Losh 94278e3e3a7aSWarner Losh 94288e3e3a7aSWarner Losh 94290495ed39SKyle Evans 94300495ed39SKyle Evans 94318e3e3a7aSWarner Losh<h4>Character Class:</h4><p> 94328e3e3a7aSWarner LoshA <em>character class</em> is used to represent a set of characters. 94338e3e3a7aSWarner LoshThe following combinations are allowed in describing a character class: 94348e3e3a7aSWarner Losh 94358e3e3a7aSWarner Losh<ul> 94368e3e3a7aSWarner Losh 94378e3e3a7aSWarner Losh<li><b><em>x</em>: </b> 94388e3e3a7aSWarner Losh(where <em>x</em> is not one of the <em>magic characters</em> 94398e3e3a7aSWarner Losh<code>^$()%.[]*+-?</code>) 94408e3e3a7aSWarner Loshrepresents the character <em>x</em> itself. 94418e3e3a7aSWarner Losh</li> 94428e3e3a7aSWarner Losh 94438e3e3a7aSWarner Losh<li><b><code>.</code>: </b> (a dot) represents all characters.</li> 94448e3e3a7aSWarner Losh 94458e3e3a7aSWarner Losh<li><b><code>%a</code>: </b> represents all letters.</li> 94468e3e3a7aSWarner Losh 94478e3e3a7aSWarner Losh<li><b><code>%c</code>: </b> represents all control characters.</li> 94488e3e3a7aSWarner Losh 94498e3e3a7aSWarner Losh<li><b><code>%d</code>: </b> represents all digits.</li> 94508e3e3a7aSWarner Losh 94518e3e3a7aSWarner Losh<li><b><code>%g</code>: </b> represents all printable characters except space.</li> 94528e3e3a7aSWarner Losh 94538e3e3a7aSWarner Losh<li><b><code>%l</code>: </b> represents all lowercase letters.</li> 94548e3e3a7aSWarner Losh 94558e3e3a7aSWarner Losh<li><b><code>%p</code>: </b> represents all punctuation characters.</li> 94568e3e3a7aSWarner Losh 94578e3e3a7aSWarner Losh<li><b><code>%s</code>: </b> represents all space characters.</li> 94588e3e3a7aSWarner Losh 94598e3e3a7aSWarner Losh<li><b><code>%u</code>: </b> represents all uppercase letters.</li> 94608e3e3a7aSWarner Losh 94618e3e3a7aSWarner Losh<li><b><code>%w</code>: </b> represents all alphanumeric characters.</li> 94628e3e3a7aSWarner Losh 94638e3e3a7aSWarner Losh<li><b><code>%x</code>: </b> represents all hexadecimal digits.</li> 94648e3e3a7aSWarner Losh 94658e3e3a7aSWarner Losh<li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character) 94668e3e3a7aSWarner Loshrepresents the character <em>x</em>. 94678e3e3a7aSWarner LoshThis is the standard way to escape the magic characters. 94688e3e3a7aSWarner LoshAny non-alphanumeric character 94698e3e3a7aSWarner Losh(including all punctuation characters, even the non-magical) 94700495ed39SKyle Evanscan be preceded by a '<code>%</code>' to represent itself in a pattern. 94718e3e3a7aSWarner Losh</li> 94728e3e3a7aSWarner Losh 94738e3e3a7aSWarner Losh<li><b><code>[<em>set</em>]</code>: </b> 94748e3e3a7aSWarner Loshrepresents the class which is the union of all 94758e3e3a7aSWarner Loshcharacters in <em>set</em>. 94768e3e3a7aSWarner LoshA range of characters can be specified by 94778e3e3a7aSWarner Loshseparating the end characters of the range, 94788e3e3a7aSWarner Loshin ascending order, with a '<code>-</code>'. 94798e3e3a7aSWarner LoshAll classes <code>%</code><em>x</em> described above can also be used as 94808e3e3a7aSWarner Loshcomponents in <em>set</em>. 94818e3e3a7aSWarner LoshAll other characters in <em>set</em> represent themselves. 94828e3e3a7aSWarner LoshFor example, <code>[%w_]</code> (or <code>[_%w]</code>) 94838e3e3a7aSWarner Loshrepresents all alphanumeric characters plus the underscore, 94848e3e3a7aSWarner Losh<code>[0-7]</code> represents the octal digits, 94858e3e3a7aSWarner Loshand <code>[0-7%l%-]</code> represents the octal digits plus 94868e3e3a7aSWarner Loshthe lowercase letters plus the '<code>-</code>' character. 94878e3e3a7aSWarner Losh 94888e3e3a7aSWarner Losh 94898e3e3a7aSWarner Losh<p> 94908e3e3a7aSWarner LoshYou can put a closing square bracket in a set 94918e3e3a7aSWarner Loshby positioning it as the first character in the set. 9492e112e9d2SKyle EvansYou can put a hyphen in a set 94938e3e3a7aSWarner Loshby positioning it as the first or the last character in the set. 94948e3e3a7aSWarner Losh(You can also use an escape for both cases.) 94958e3e3a7aSWarner Losh 94968e3e3a7aSWarner Losh 94978e3e3a7aSWarner Losh<p> 94988e3e3a7aSWarner LoshThe interaction between ranges and classes is not defined. 94998e3e3a7aSWarner LoshTherefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> 95008e3e3a7aSWarner Loshhave no meaning. 95018e3e3a7aSWarner Losh</li> 95028e3e3a7aSWarner Losh 95038e3e3a7aSWarner Losh<li><b><code>[^<em>set</em>]</code>: </b> 95048e3e3a7aSWarner Loshrepresents the complement of <em>set</em>, 95058e3e3a7aSWarner Loshwhere <em>set</em> is interpreted as above. 95068e3e3a7aSWarner Losh</li> 95078e3e3a7aSWarner Losh 95088e3e3a7aSWarner Losh</ul><p> 95098e3e3a7aSWarner LoshFor all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), 95108e3e3a7aSWarner Loshthe corresponding uppercase letter represents the complement of the class. 95118e3e3a7aSWarner LoshFor instance, <code>%S</code> represents all non-space characters. 95128e3e3a7aSWarner Losh 95138e3e3a7aSWarner Losh 95148e3e3a7aSWarner Losh<p> 95158e3e3a7aSWarner LoshThe definitions of letter, space, and other character groups 95168e3e3a7aSWarner Loshdepend on the current locale. 95178e3e3a7aSWarner LoshIn particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. 95188e3e3a7aSWarner Losh 95198e3e3a7aSWarner Losh 95208e3e3a7aSWarner Losh 95218e3e3a7aSWarner Losh 95228e3e3a7aSWarner Losh 95238e3e3a7aSWarner Losh<h4>Pattern Item:</h4><p> 95248e3e3a7aSWarner LoshA <em>pattern item</em> can be 95258e3e3a7aSWarner Losh 95268e3e3a7aSWarner Losh<ul> 95278e3e3a7aSWarner Losh 95288e3e3a7aSWarner Losh<li> 95298e3e3a7aSWarner Losha single character class, 95308e3e3a7aSWarner Loshwhich matches any single character in the class; 95318e3e3a7aSWarner Losh</li> 95328e3e3a7aSWarner Losh 95338e3e3a7aSWarner Losh<li> 95348e3e3a7aSWarner Losha single character class followed by '<code>*</code>', 95350495ed39SKyle Evanswhich matches sequences of zero or more characters in the class. 95368e3e3a7aSWarner LoshThese repetition items will always match the longest possible sequence; 95378e3e3a7aSWarner Losh</li> 95388e3e3a7aSWarner Losh 95398e3e3a7aSWarner Losh<li> 95408e3e3a7aSWarner Losha single character class followed by '<code>+</code>', 95410495ed39SKyle Evanswhich matches sequences of one or more characters in the class. 95428e3e3a7aSWarner LoshThese repetition items will always match the longest possible sequence; 95438e3e3a7aSWarner Losh</li> 95448e3e3a7aSWarner Losh 95458e3e3a7aSWarner Losh<li> 95468e3e3a7aSWarner Losha single character class followed by '<code>-</code>', 95470495ed39SKyle Evanswhich also matches sequences of zero or more characters in the class. 95488e3e3a7aSWarner LoshUnlike '<code>*</code>', 95498e3e3a7aSWarner Loshthese repetition items will always match the shortest possible sequence; 95508e3e3a7aSWarner Losh</li> 95518e3e3a7aSWarner Losh 95528e3e3a7aSWarner Losh<li> 95538e3e3a7aSWarner Losha single character class followed by '<code>?</code>', 95548e3e3a7aSWarner Loshwhich matches zero or one occurrence of a character in the class. 95558e3e3a7aSWarner LoshIt always matches one occurrence if possible; 95568e3e3a7aSWarner Losh</li> 95578e3e3a7aSWarner Losh 95588e3e3a7aSWarner Losh<li> 95598e3e3a7aSWarner Losh<code>%<em>n</em></code>, for <em>n</em> between 1 and 9; 95608e3e3a7aSWarner Loshsuch item matches a substring equal to the <em>n</em>-th captured string 95618e3e3a7aSWarner Losh(see below); 95628e3e3a7aSWarner Losh</li> 95638e3e3a7aSWarner Losh 95648e3e3a7aSWarner Losh<li> 95658e3e3a7aSWarner Losh<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; 95668e3e3a7aSWarner Loshsuch item matches strings that start with <em>x</em>, end with <em>y</em>, 95678e3e3a7aSWarner Loshand where the <em>x</em> and <em>y</em> are <em>balanced</em>. 95688e3e3a7aSWarner LoshThis means that, if one reads the string from left to right, 95698e3e3a7aSWarner Loshcounting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, 95708e3e3a7aSWarner Loshthe ending <em>y</em> is the first <em>y</em> where the count reaches 0. 95718e3e3a7aSWarner LoshFor instance, the item <code>%b()</code> matches expressions with 95728e3e3a7aSWarner Loshbalanced parentheses. 95738e3e3a7aSWarner Losh</li> 95748e3e3a7aSWarner Losh 95758e3e3a7aSWarner Losh<li> 95768e3e3a7aSWarner Losh<code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>; 95778e3e3a7aSWarner Loshsuch item matches an empty string at any position such that 95788e3e3a7aSWarner Loshthe next character belongs to <em>set</em> 95798e3e3a7aSWarner Loshand the previous character does not belong to <em>set</em>. 95808e3e3a7aSWarner LoshThe set <em>set</em> is interpreted as previously described. 95818e3e3a7aSWarner LoshThe beginning and the end of the subject are handled as if 95828e3e3a7aSWarner Loshthey were the character '<code>\0</code>'. 95838e3e3a7aSWarner Losh</li> 95848e3e3a7aSWarner Losh 95858e3e3a7aSWarner Losh</ul> 95868e3e3a7aSWarner Losh 95878e3e3a7aSWarner Losh 95888e3e3a7aSWarner Losh 95898e3e3a7aSWarner Losh 95908e3e3a7aSWarner Losh<h4>Pattern:</h4><p> 95918e3e3a7aSWarner LoshA <em>pattern</em> is a sequence of pattern items. 95928e3e3a7aSWarner LoshA caret '<code>^</code>' at the beginning of a pattern anchors the match at the 95938e3e3a7aSWarner Loshbeginning of the subject string. 95948e3e3a7aSWarner LoshA '<code>$</code>' at the end of a pattern anchors the match at the 95958e3e3a7aSWarner Loshend of the subject string. 95968e3e3a7aSWarner LoshAt other positions, 95978e3e3a7aSWarner Losh'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. 95988e3e3a7aSWarner Losh 95998e3e3a7aSWarner Losh 96008e3e3a7aSWarner Losh 96018e3e3a7aSWarner Losh 96028e3e3a7aSWarner Losh 96038e3e3a7aSWarner Losh<h4>Captures:</h4><p> 96048e3e3a7aSWarner LoshA pattern can contain sub-patterns enclosed in parentheses; 96058e3e3a7aSWarner Loshthey describe <em>captures</em>. 96068e3e3a7aSWarner LoshWhen a match succeeds, the substrings of the subject string 96078e3e3a7aSWarner Loshthat match captures are stored (<em>captured</em>) for future use. 96088e3e3a7aSWarner LoshCaptures are numbered according to their left parentheses. 96098e3e3a7aSWarner LoshFor instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, 96108e3e3a7aSWarner Loshthe part of the string matching <code>"a*(.)%w(%s*)"</code> is 96110495ed39SKyle Evansstored as the first capture, and therefore has number 1; 96128e3e3a7aSWarner Loshthe character matching "<code>.</code>" is captured with number 2, 96138e3e3a7aSWarner Loshand the part matching "<code>%s*</code>" has number 3. 96148e3e3a7aSWarner Losh 96158e3e3a7aSWarner Losh 96168e3e3a7aSWarner Losh<p> 96170495ed39SKyle EvansAs a special case, the capture <code>()</code> captures 96188e3e3a7aSWarner Loshthe current string position (a number). 96198e3e3a7aSWarner LoshFor instance, if we apply the pattern <code>"()aa()"</code> on the 96208e3e3a7aSWarner Loshstring <code>"flaaap"</code>, there will be two captures: 3 and 5. 96218e3e3a7aSWarner Losh 96228e3e3a7aSWarner Losh 96238e3e3a7aSWarner Losh 96248e3e3a7aSWarner Losh 96258e3e3a7aSWarner Losh 96260495ed39SKyle Evans<h4>Multiple matches:</h4><p> 96270495ed39SKyle 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> 96280495ed39SKyle Evansmatch multiple occurrences of the given pattern in the subject. 96290495ed39SKyle EvansFor these functions, 96300495ed39SKyle Evansa new match is considered valid only 96310495ed39SKyle Evansif it ends at least one byte after the end of the previous match. 96320495ed39SKyle EvansIn other words, the pattern machine never accepts the 96330495ed39SKyle Evansempty string as a match immediately after another match. 96340495ed39SKyle EvansAs an example, 96350495ed39SKyle Evansconsider the results of the following code: 96360495ed39SKyle Evans 96370495ed39SKyle Evans<pre> 96380495ed39SKyle Evans > string.gsub("abc", "()a*()", print); 96390495ed39SKyle Evans --> 1 2 96400495ed39SKyle Evans --> 3 3 96410495ed39SKyle Evans --> 4 4 96420495ed39SKyle Evans</pre><p> 96430495ed39SKyle EvansThe second and third results come from Lua matching an empty 96440495ed39SKyle Evansstring after '<code>b</code>' and another one after '<code>c</code>'. 96450495ed39SKyle EvansLua does not match an empty string after '<code>a</code>', 96460495ed39SKyle Evansbecause it would end at the same position of the previous match. 96470495ed39SKyle Evans 96480495ed39SKyle Evans 96490495ed39SKyle Evans 96500495ed39SKyle Evans 96510495ed39SKyle Evans 96528e3e3a7aSWarner Losh 96538e3e3a7aSWarner Losh 96548e3e3a7aSWarner Losh<h3>6.4.2 – <a name="6.4.2">Format Strings for Pack and Unpack</a></h3> 96558e3e3a7aSWarner Losh 96568e3e3a7aSWarner Losh<p> 96578e3e3a7aSWarner LoshThe first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>, 96588e3e3a7aSWarner Losh<a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a> 96598e3e3a7aSWarner Loshis a format string, 96608e3e3a7aSWarner Loshwhich describes the layout of the structure being created or read. 96618e3e3a7aSWarner Losh 96628e3e3a7aSWarner Losh 96638e3e3a7aSWarner Losh<p> 96648e3e3a7aSWarner LoshA format string is a sequence of conversion options. 96658e3e3a7aSWarner LoshThe conversion options are as follows: 96668e3e3a7aSWarner Losh 96678e3e3a7aSWarner Losh<ul> 96688e3e3a7aSWarner Losh<li><b><code><</code>: </b>sets little endian</li> 96698e3e3a7aSWarner Losh<li><b><code>></code>: </b>sets big endian</li> 96708e3e3a7aSWarner Losh<li><b><code>=</code>: </b>sets native endian</li> 96718e3e3a7aSWarner Losh<li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code> 96728e3e3a7aSWarner Losh(default is native alignment)</li> 96738e3e3a7aSWarner Losh<li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li> 96748e3e3a7aSWarner Losh<li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li> 96758e3e3a7aSWarner Losh<li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li> 96768e3e3a7aSWarner Losh<li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li> 96778e3e3a7aSWarner Losh<li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li> 96788e3e3a7aSWarner Losh<li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li> 96798e3e3a7aSWarner Losh<li><b><code>j</code>: </b>a <code>lua_Integer</code></li> 96808e3e3a7aSWarner Losh<li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li> 96818e3e3a7aSWarner Losh<li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li> 96828e3e3a7aSWarner Losh<li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes 96838e3e3a7aSWarner Losh(default is native size)</li> 96848e3e3a7aSWarner Losh<li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes 96858e3e3a7aSWarner Losh(default is native size)</li> 96868e3e3a7aSWarner Losh<li><b><code>f</code>: </b>a <code>float</code> (native size)</li> 96878e3e3a7aSWarner Losh<li><b><code>d</code>: </b>a <code>double</code> (native size)</li> 96888e3e3a7aSWarner Losh<li><b><code>n</code>: </b>a <code>lua_Number</code></li> 96898e3e3a7aSWarner Losh<li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li> 96908e3e3a7aSWarner Losh<li><b><code>z</code>: </b>a zero-terminated string</li> 96918e3e3a7aSWarner Losh<li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length 96928e3e3a7aSWarner Loshcoded as an unsigned integer with <code>n</code> bytes 96938e3e3a7aSWarner Losh(default is a <code>size_t</code>)</li> 96948e3e3a7aSWarner Losh<li><b><code>x</code>: </b>one byte of padding</li> 96958e3e3a7aSWarner Losh<li><b><code>X<em>op</em></code>: </b>an empty item that aligns 96968e3e3a7aSWarner Loshaccording to option <code>op</code> 96978e3e3a7aSWarner Losh(which is otherwise ignored)</li> 96980495ed39SKyle Evans<li><b>'<code> </code>': </b>(space) ignored</li> 96998e3e3a7aSWarner Losh</ul><p> 97008e3e3a7aSWarner Losh(A "<code>[<em>n</em>]</code>" means an optional integral numeral.) 97018e3e3a7aSWarner LoshExcept for padding, spaces, and configurations 97028e3e3a7aSWarner Losh(options "<code>xX <=>!</code>"), 97030495ed39SKyle Evanseach option corresponds to an argument in <a href="#pdf-string.pack"><code>string.pack</code></a> 97040495ed39SKyle Evansor a result in <a href="#pdf-string.unpack"><code>string.unpack</code></a>. 97058e3e3a7aSWarner Losh 97068e3e3a7aSWarner Losh 97078e3e3a7aSWarner Losh<p> 97088e3e3a7aSWarner 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>", 97098e3e3a7aSWarner Losh<code>n</code> can be any integer between 1 and 16. 97108e3e3a7aSWarner LoshAll integral options check overflows; 97118e3e3a7aSWarner Losh<a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size; 97128e3e3a7aSWarner Losh<a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer. 97130495ed39SKyle EvansFor the unsigned options, 97140495ed39SKyle EvansLua integers are treated as unsigned values too. 97158e3e3a7aSWarner Losh 97168e3e3a7aSWarner Losh 97178e3e3a7aSWarner Losh<p> 97188e3e3a7aSWarner LoshAny format string starts as if prefixed by "<code>!1=</code>", 97198e3e3a7aSWarner Loshthat is, 97208e3e3a7aSWarner Loshwith maximum alignment of 1 (no alignment) 97218e3e3a7aSWarner Loshand native endianness. 97228e3e3a7aSWarner Losh 97238e3e3a7aSWarner Losh 97248e3e3a7aSWarner Losh<p> 97250495ed39SKyle EvansNative endianness assumes that the whole system is 97260495ed39SKyle Evanseither big or little endian. 97270495ed39SKyle EvansThe packing functions will not emulate correctly the behavior 97280495ed39SKyle Evansof mixed-endian formats. 97290495ed39SKyle Evans 97300495ed39SKyle Evans 97310495ed39SKyle Evans<p> 97328e3e3a7aSWarner LoshAlignment works as follows: 97338e3e3a7aSWarner LoshFor each option, 97348e3e3a7aSWarner Loshthe format gets extra padding until the data starts 97358e3e3a7aSWarner Loshat an offset that is a multiple of the minimum between the 97368e3e3a7aSWarner Loshoption size and the maximum alignment; 97378e3e3a7aSWarner Loshthis minimum must be a power of 2. 97388e3e3a7aSWarner LoshOptions "<code>c</code>" and "<code>z</code>" are not aligned; 97398e3e3a7aSWarner Loshoption "<code>s</code>" follows the alignment of its starting integer. 97408e3e3a7aSWarner Losh 97418e3e3a7aSWarner Losh 97428e3e3a7aSWarner Losh<p> 97438e3e3a7aSWarner LoshAll padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a> 97440495ed39SKyle Evansand ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>. 97458e3e3a7aSWarner Losh 97468e3e3a7aSWarner Losh 97478e3e3a7aSWarner Losh 97488e3e3a7aSWarner Losh 97498e3e3a7aSWarner Losh 97508e3e3a7aSWarner Losh 97518e3e3a7aSWarner Losh 97528e3e3a7aSWarner Losh<h2>6.5 – <a name="6.5">UTF-8 Support</a></h2> 97538e3e3a7aSWarner Losh 97548e3e3a7aSWarner Losh<p> 97558e3e3a7aSWarner LoshThis library provides basic support for UTF-8 encoding. 97568e3e3a7aSWarner LoshIt provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>. 97578e3e3a7aSWarner LoshThis library does not provide any support for Unicode other 97588e3e3a7aSWarner Loshthan the handling of the encoding. 97598e3e3a7aSWarner LoshAny operation that needs the meaning of a character, 97608e3e3a7aSWarner Loshsuch as character classification, is outside its scope. 97618e3e3a7aSWarner Losh 97628e3e3a7aSWarner Losh 97638e3e3a7aSWarner Losh<p> 97648e3e3a7aSWarner LoshUnless stated otherwise, 97658e3e3a7aSWarner Loshall functions that expect a byte position as a parameter 97668e3e3a7aSWarner Loshassume that the given position is either the start of a byte sequence 97678e3e3a7aSWarner Loshor one plus the length of the subject string. 97688e3e3a7aSWarner LoshAs in the string library, 97698e3e3a7aSWarner Loshnegative indices count from the end of the string. 97708e3e3a7aSWarner Losh 97718e3e3a7aSWarner Losh 97728e3e3a7aSWarner Losh<p> 97730495ed39SKyle EvansFunctions that create byte sequences 97740495ed39SKyle Evansaccept all values up to <code>0x7FFFFFFF</code>, 97750495ed39SKyle Evansas defined in the original UTF-8 specification; 97760495ed39SKyle Evansthat implies byte sequences of up to six bytes. 97770495ed39SKyle Evans 97780495ed39SKyle Evans 97790495ed39SKyle Evans<p> 97800495ed39SKyle EvansFunctions that interpret byte sequences only accept 97810495ed39SKyle Evansvalid sequences (well formed and not overlong). 97820495ed39SKyle EvansBy default, they only accept byte sequences 97830495ed39SKyle Evansthat result in valid Unicode code points, 97840495ed39SKyle Evansrejecting values greater than <code>10FFFF</code> and surrogates. 97850495ed39SKyle EvansA boolean argument <code>lax</code>, when available, 97860495ed39SKyle Evanslifts these checks, 97870495ed39SKyle Evansso that all values up to <code>0x7FFFFFFF</code> are accepted. 97880495ed39SKyle Evans(Not well formed and overlong sequences are still rejected.) 97890495ed39SKyle Evans 97900495ed39SKyle Evans 97910495ed39SKyle Evans<p> 97928e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3> 97930495ed39SKyle Evans 97940495ed39SKyle Evans 97950495ed39SKyle Evans<p> 97968e3e3a7aSWarner LoshReceives zero or more integers, 97978e3e3a7aSWarner Loshconverts each one to its corresponding UTF-8 byte sequence 97988e3e3a7aSWarner Loshand returns a string with the concatenation of all these sequences. 97998e3e3a7aSWarner Losh 98008e3e3a7aSWarner Losh 98018e3e3a7aSWarner Losh 98028e3e3a7aSWarner Losh 98038e3e3a7aSWarner Losh<p> 98048e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3> 98050495ed39SKyle Evans 98060495ed39SKyle Evans 98070495ed39SKyle Evans<p> 98080495ed39SKyle EvansThe pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xFD][\x80-\xBF]*</code>" 98098e3e3a7aSWarner Losh(see <a href="#6.4.1">§6.4.1</a>), 98108e3e3a7aSWarner Loshwhich matches exactly one UTF-8 byte sequence, 98118e3e3a7aSWarner Loshassuming that the subject is a valid UTF-8 string. 98128e3e3a7aSWarner Losh 98138e3e3a7aSWarner Losh 98148e3e3a7aSWarner Losh 98158e3e3a7aSWarner Losh 98168e3e3a7aSWarner Losh<p> 98170495ed39SKyle Evans<hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s [, lax])</code></a></h3> 98188e3e3a7aSWarner Losh 98198e3e3a7aSWarner Losh 98208e3e3a7aSWarner Losh<p> 98218e3e3a7aSWarner LoshReturns values so that the construction 98228e3e3a7aSWarner Losh 98238e3e3a7aSWarner Losh<pre> 98248e3e3a7aSWarner Losh for p, c in utf8.codes(s) do <em>body</em> end 98258e3e3a7aSWarner Losh</pre><p> 98260495ed39SKyle Evanswill iterate over all UTF-8 characters in string <code>s</code>, 98278e3e3a7aSWarner Loshwith <code>p</code> being the position (in bytes) and <code>c</code> the code point 98288e3e3a7aSWarner Loshof each character. 98298e3e3a7aSWarner LoshIt raises an error if it meets any invalid byte sequence. 98308e3e3a7aSWarner Losh 98318e3e3a7aSWarner Losh 98328e3e3a7aSWarner Losh 98338e3e3a7aSWarner Losh 98348e3e3a7aSWarner Losh<p> 98350495ed39SKyle Evans<hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j [, lax]]])</code></a></h3> 98360495ed39SKyle Evans 98370495ed39SKyle Evans 98380495ed39SKyle Evans<p> 98398e3e3a7aSWarner LoshReturns the code points (as integers) from all characters in <code>s</code> 98408e3e3a7aSWarner Loshthat start between byte position <code>i</code> and <code>j</code> (both included). 98418e3e3a7aSWarner LoshThe default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>. 98428e3e3a7aSWarner LoshIt raises an error if it meets any invalid byte sequence. 98438e3e3a7aSWarner Losh 98448e3e3a7aSWarner Losh 98458e3e3a7aSWarner Losh 98468e3e3a7aSWarner Losh 98478e3e3a7aSWarner Losh<p> 98480495ed39SKyle Evans<hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j [, lax]]])</code></a></h3> 98490495ed39SKyle Evans 98500495ed39SKyle Evans 98510495ed39SKyle Evans<p> 98528e3e3a7aSWarner LoshReturns the number of UTF-8 characters in string <code>s</code> 98538e3e3a7aSWarner Loshthat start between positions <code>i</code> and <code>j</code> (both inclusive). 98548e3e3a7aSWarner LoshThe default for <code>i</code> is 1 and for <code>j</code> is -1. 98558e3e3a7aSWarner LoshIf it finds any invalid byte sequence, 98560495ed39SKyle Evansreturns <b>fail</b> plus the position of the first invalid byte. 98578e3e3a7aSWarner Losh 98588e3e3a7aSWarner Losh 98598e3e3a7aSWarner Losh 98608e3e3a7aSWarner Losh 98618e3e3a7aSWarner Losh<p> 98628e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3> 98630495ed39SKyle Evans 98640495ed39SKyle Evans 98650495ed39SKyle Evans<p> 98668e3e3a7aSWarner LoshReturns the position (in bytes) where the encoding of the 98678e3e3a7aSWarner Losh<code>n</code>-th character of <code>s</code> 98688e3e3a7aSWarner Losh(counting from position <code>i</code>) starts. 98698e3e3a7aSWarner LoshA negative <code>n</code> gets characters before position <code>i</code>. 98708e3e3a7aSWarner LoshThe default for <code>i</code> is 1 when <code>n</code> is non-negative 98718e3e3a7aSWarner Loshand <code>#s + 1</code> otherwise, 98728e3e3a7aSWarner Loshso that <code>utf8.offset(s, -n)</code> gets the offset of the 98738e3e3a7aSWarner Losh<code>n</code>-th character from the end of the string. 98748e3e3a7aSWarner LoshIf the specified character is neither in the subject 98758e3e3a7aSWarner Loshnor right after its end, 98760495ed39SKyle Evansthe function returns <b>fail</b>. 98778e3e3a7aSWarner Losh 98788e3e3a7aSWarner Losh 98798e3e3a7aSWarner Losh<p> 98808e3e3a7aSWarner LoshAs a special case, 98818e3e3a7aSWarner Loshwhen <code>n</code> is 0 the function returns the start of the encoding 98828e3e3a7aSWarner Loshof the character that contains the <code>i</code>-th byte of <code>s</code>. 98838e3e3a7aSWarner Losh 98848e3e3a7aSWarner Losh 98858e3e3a7aSWarner Losh<p> 98868e3e3a7aSWarner LoshThis function assumes that <code>s</code> is a valid UTF-8 string. 98878e3e3a7aSWarner Losh 98888e3e3a7aSWarner Losh 98898e3e3a7aSWarner Losh 98908e3e3a7aSWarner Losh 98918e3e3a7aSWarner Losh 98928e3e3a7aSWarner Losh 98938e3e3a7aSWarner Losh 98948e3e3a7aSWarner Losh<h2>6.6 – <a name="6.6">Table Manipulation</a></h2> 98958e3e3a7aSWarner Losh 98968e3e3a7aSWarner Losh<p> 98978e3e3a7aSWarner LoshThis library provides generic functions for table manipulation. 98988e3e3a7aSWarner LoshIt provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. 98998e3e3a7aSWarner Losh 99008e3e3a7aSWarner Losh 99018e3e3a7aSWarner Losh<p> 99028e3e3a7aSWarner LoshRemember that, whenever an operation needs the length of a table, 99038e3e3a7aSWarner Loshall caveats about the length operator apply (see <a href="#3.4.7">§3.4.7</a>). 99048e3e3a7aSWarner LoshAll functions ignore non-numeric keys 99058e3e3a7aSWarner Loshin the tables given as arguments. 99068e3e3a7aSWarner Losh 99078e3e3a7aSWarner Losh 99088e3e3a7aSWarner Losh<p> 99098e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3> 99108e3e3a7aSWarner Losh 99118e3e3a7aSWarner Losh 99128e3e3a7aSWarner Losh<p> 99138e3e3a7aSWarner LoshGiven a list where all elements are strings or numbers, 99148e3e3a7aSWarner Loshreturns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>. 99158e3e3a7aSWarner LoshThe default value for <code>sep</code> is the empty string, 99168e3e3a7aSWarner Loshthe default for <code>i</code> is 1, 99178e3e3a7aSWarner Loshand the default for <code>j</code> is <code>#list</code>. 99188e3e3a7aSWarner LoshIf <code>i</code> is greater than <code>j</code>, returns the empty string. 99198e3e3a7aSWarner Losh 99208e3e3a7aSWarner Losh 99218e3e3a7aSWarner Losh 99228e3e3a7aSWarner Losh 99238e3e3a7aSWarner Losh<p> 99248e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3> 99258e3e3a7aSWarner Losh 99268e3e3a7aSWarner Losh 99278e3e3a7aSWarner Losh<p> 99288e3e3a7aSWarner LoshInserts element <code>value</code> at position <code>pos</code> in <code>list</code>, 99298e3e3a7aSWarner Loshshifting up the elements 99308e3e3a7aSWarner Losh<code>list[pos], list[pos+1], ···, list[#list]</code>. 99318e3e3a7aSWarner LoshThe default value for <code>pos</code> is <code>#list+1</code>, 99328e3e3a7aSWarner Loshso that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end 99330495ed39SKyle Evansof the list <code>t</code>. 99348e3e3a7aSWarner Losh 99358e3e3a7aSWarner Losh 99368e3e3a7aSWarner Losh 99378e3e3a7aSWarner Losh 99388e3e3a7aSWarner Losh<p> 99398e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3> 99408e3e3a7aSWarner Losh 99418e3e3a7aSWarner Losh 99428e3e3a7aSWarner Losh<p> 99430495ed39SKyle EvansMoves elements from the table <code>a1</code> to the table <code>a2</code>, 99448e3e3a7aSWarner Loshperforming the equivalent to the following 99458e3e3a7aSWarner Loshmultiple assignment: 99468e3e3a7aSWarner Losh<code>a2[t],··· = a1[f],···,a1[e]</code>. 99478e3e3a7aSWarner LoshThe default for <code>a2</code> is <code>a1</code>. 99488e3e3a7aSWarner LoshThe destination range can overlap with the source range. 99498e3e3a7aSWarner LoshThe number of elements to be moved must fit in a Lua integer. 99508e3e3a7aSWarner Losh 99518e3e3a7aSWarner Losh 99528e3e3a7aSWarner Losh<p> 99538e3e3a7aSWarner LoshReturns the destination table <code>a2</code>. 99548e3e3a7aSWarner Losh 99558e3e3a7aSWarner Losh 99568e3e3a7aSWarner Losh 99578e3e3a7aSWarner Losh 99588e3e3a7aSWarner Losh<p> 99598e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3> 99608e3e3a7aSWarner Losh 99618e3e3a7aSWarner Losh 99628e3e3a7aSWarner Losh<p> 9963e112e9d2SKyle EvansReturns a new table with all arguments stored into keys 1, 2, etc. 9964e112e9d2SKyle Evansand with a field "<code>n</code>" with the total number of arguments. 99650495ed39SKyle EvansNote that the resulting table may not be a sequence, 99660495ed39SKyle Evansif some arguments are <b>nil</b>. 99678e3e3a7aSWarner Losh 99688e3e3a7aSWarner Losh 99698e3e3a7aSWarner Losh 99708e3e3a7aSWarner Losh 99718e3e3a7aSWarner Losh<p> 99728e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3> 99738e3e3a7aSWarner Losh 99748e3e3a7aSWarner Losh 99758e3e3a7aSWarner Losh<p> 99768e3e3a7aSWarner LoshRemoves from <code>list</code> the element at position <code>pos</code>, 99778e3e3a7aSWarner Loshreturning the value of the removed element. 99788e3e3a7aSWarner LoshWhen <code>pos</code> is an integer between 1 and <code>#list</code>, 99798e3e3a7aSWarner Loshit shifts down the elements 99808e3e3a7aSWarner Losh<code>list[pos+1], list[pos+2], ···, list[#list]</code> 99818e3e3a7aSWarner Loshand erases element <code>list[#list]</code>; 99828e3e3a7aSWarner LoshThe index <code>pos</code> can also be 0 when <code>#list</code> is 0, 99830495ed39SKyle Evansor <code>#list + 1</code>. 99848e3e3a7aSWarner Losh 99858e3e3a7aSWarner Losh 99868e3e3a7aSWarner Losh<p> 99878e3e3a7aSWarner LoshThe default value for <code>pos</code> is <code>#list</code>, 99888e3e3a7aSWarner Loshso that a call <code>table.remove(l)</code> removes the last element 99890495ed39SKyle Evansof the list <code>l</code>. 99908e3e3a7aSWarner Losh 99918e3e3a7aSWarner Losh 99928e3e3a7aSWarner Losh 99938e3e3a7aSWarner Losh 99948e3e3a7aSWarner Losh<p> 99958e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3> 99968e3e3a7aSWarner Losh 99978e3e3a7aSWarner Losh 99988e3e3a7aSWarner Losh<p> 99990495ed39SKyle EvansSorts the list elements in a given order, <em>in-place</em>, 100008e3e3a7aSWarner Loshfrom <code>list[1]</code> to <code>list[#list]</code>. 100018e3e3a7aSWarner LoshIf <code>comp</code> is given, 100028e3e3a7aSWarner Loshthen it must be a function that receives two list elements 100038e3e3a7aSWarner Loshand returns true when the first element must come 10004*8c784bb8SWarner Loshbefore the second in the final order, 10005*8c784bb8SWarner Loshso that, after the sort, 10006*8c784bb8SWarner Losh<code>i <= j</code> implies <code>not comp(list[j],list[i])</code>. 100078e3e3a7aSWarner LoshIf <code>comp</code> is not given, 100088e3e3a7aSWarner Loshthen the standard Lua operator <code><</code> is used instead. 100098e3e3a7aSWarner Losh 100108e3e3a7aSWarner Losh 100118e3e3a7aSWarner Losh<p> 10012*8c784bb8SWarner LoshThe <code>comp</code> function must define a consistent order; 10013*8c784bb8SWarner Loshmore formally, the function must define a strict weak order. 10014*8c784bb8SWarner Losh(A weak order is similar to a total order, 10015*8c784bb8SWarner Loshbut it can equate different elements for comparison purposes.) 100168e3e3a7aSWarner Losh 100178e3e3a7aSWarner Losh 100188e3e3a7aSWarner Losh<p> 100198e3e3a7aSWarner LoshThe sort algorithm is not stable: 10020*8c784bb8SWarner LoshDifferent elements considered equal by the given order 100218e3e3a7aSWarner Loshmay have their relative positions changed by the sort. 100228e3e3a7aSWarner Losh 100238e3e3a7aSWarner Losh 100248e3e3a7aSWarner Losh 100258e3e3a7aSWarner Losh 100268e3e3a7aSWarner Losh<p> 100278e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3> 100288e3e3a7aSWarner Losh 100298e3e3a7aSWarner Losh 100308e3e3a7aSWarner Losh<p> 100318e3e3a7aSWarner LoshReturns the elements from the given list. 100328e3e3a7aSWarner LoshThis function is equivalent to 100338e3e3a7aSWarner Losh 100348e3e3a7aSWarner Losh<pre> 100358e3e3a7aSWarner Losh return list[i], list[i+1], ···, list[j] 100368e3e3a7aSWarner Losh</pre><p> 100378e3e3a7aSWarner LoshBy default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>. 100388e3e3a7aSWarner Losh 100398e3e3a7aSWarner Losh 100408e3e3a7aSWarner Losh 100418e3e3a7aSWarner Losh 100428e3e3a7aSWarner Losh 100438e3e3a7aSWarner Losh 100448e3e3a7aSWarner Losh 100458e3e3a7aSWarner Losh<h2>6.7 – <a name="6.7">Mathematical Functions</a></h2> 100468e3e3a7aSWarner Losh 100478e3e3a7aSWarner Losh<p> 100488e3e3a7aSWarner LoshThis library provides basic mathematical functions. 100498e3e3a7aSWarner LoshIt provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>. 100508e3e3a7aSWarner LoshFunctions with the annotation "<code>integer/float</code>" give 100518e3e3a7aSWarner Loshinteger results for integer arguments 100520495ed39SKyle Evansand float results for non-integer arguments. 100530495ed39SKyle EvansThe rounding functions 100540495ed39SKyle 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> 100558e3e3a7aSWarner Loshreturn an integer when the result fits in the range of an integer, 100568e3e3a7aSWarner Loshor a float otherwise. 100578e3e3a7aSWarner Losh 100588e3e3a7aSWarner Losh 100598e3e3a7aSWarner Losh<p> 100608e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> 100618e3e3a7aSWarner Losh 100628e3e3a7aSWarner Losh 100638e3e3a7aSWarner Losh<p> 100640495ed39SKyle EvansReturns the maximum value between <code>x</code> and <code>-x</code>. (integer/float) 100658e3e3a7aSWarner Losh 100668e3e3a7aSWarner Losh 100678e3e3a7aSWarner Losh 100688e3e3a7aSWarner Losh 100698e3e3a7aSWarner Losh<p> 100708e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> 100718e3e3a7aSWarner Losh 100728e3e3a7aSWarner Losh 100738e3e3a7aSWarner Losh<p> 100748e3e3a7aSWarner LoshReturns the arc cosine of <code>x</code> (in radians). 100758e3e3a7aSWarner Losh 100768e3e3a7aSWarner Losh 100778e3e3a7aSWarner Losh 100788e3e3a7aSWarner Losh 100798e3e3a7aSWarner Losh<p> 100808e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> 100818e3e3a7aSWarner Losh 100828e3e3a7aSWarner Losh 100838e3e3a7aSWarner Losh<p> 100848e3e3a7aSWarner LoshReturns the arc sine of <code>x</code> (in radians). 100858e3e3a7aSWarner Losh 100868e3e3a7aSWarner Losh 100878e3e3a7aSWarner Losh 100888e3e3a7aSWarner Losh 100898e3e3a7aSWarner Losh<p> 100908e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3> 100918e3e3a7aSWarner Losh 100928e3e3a7aSWarner Losh 100938e3e3a7aSWarner Losh<p> 100948e3e3a7aSWarner Losh 100958e3e3a7aSWarner LoshReturns the arc tangent of <code>y/x</code> (in radians), 10096e112e9d2SKyle Evansbut uses the signs of both arguments to find the 100978e3e3a7aSWarner Loshquadrant of the result. 100980495ed39SKyle EvansIt also handles correctly the case of <code>x</code> being zero. 100998e3e3a7aSWarner Losh 101008e3e3a7aSWarner Losh 101018e3e3a7aSWarner Losh<p> 101028e3e3a7aSWarner LoshThe default value for <code>x</code> is 1, 101038e3e3a7aSWarner Loshso that the call <code>math.atan(y)</code> 101048e3e3a7aSWarner Loshreturns the arc tangent of <code>y</code>. 101058e3e3a7aSWarner Losh 101068e3e3a7aSWarner Losh 101078e3e3a7aSWarner Losh 101088e3e3a7aSWarner Losh 101098e3e3a7aSWarner Losh<p> 101108e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> 101118e3e3a7aSWarner Losh 101128e3e3a7aSWarner Losh 101138e3e3a7aSWarner Losh<p> 101140495ed39SKyle EvansReturns the smallest integral value greater than or equal to <code>x</code>. 101158e3e3a7aSWarner Losh 101168e3e3a7aSWarner Losh 101178e3e3a7aSWarner Losh 101188e3e3a7aSWarner Losh 101198e3e3a7aSWarner Losh<p> 101208e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> 101218e3e3a7aSWarner Losh 101228e3e3a7aSWarner Losh 101238e3e3a7aSWarner Losh<p> 101248e3e3a7aSWarner LoshReturns the cosine of <code>x</code> (assumed to be in radians). 101258e3e3a7aSWarner Losh 101268e3e3a7aSWarner Losh 101278e3e3a7aSWarner Losh 101288e3e3a7aSWarner Losh 101298e3e3a7aSWarner Losh<p> 101308e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> 101318e3e3a7aSWarner Losh 101328e3e3a7aSWarner Losh 101338e3e3a7aSWarner Losh<p> 101348e3e3a7aSWarner LoshConverts the angle <code>x</code> from radians to degrees. 101358e3e3a7aSWarner Losh 101368e3e3a7aSWarner Losh 101378e3e3a7aSWarner Losh 101388e3e3a7aSWarner Losh 101398e3e3a7aSWarner Losh<p> 101408e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> 101418e3e3a7aSWarner Losh 101428e3e3a7aSWarner Losh 101438e3e3a7aSWarner Losh<p> 101448e3e3a7aSWarner LoshReturns the value <em>e<sup>x</sup></em> 101458e3e3a7aSWarner Losh(where <code>e</code> is the base of natural logarithms). 101468e3e3a7aSWarner Losh 101478e3e3a7aSWarner Losh 101488e3e3a7aSWarner Losh 101498e3e3a7aSWarner Losh 101508e3e3a7aSWarner Losh<p> 101518e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> 101528e3e3a7aSWarner Losh 101538e3e3a7aSWarner Losh 101548e3e3a7aSWarner Losh<p> 101550495ed39SKyle EvansReturns the largest integral value less than or equal to <code>x</code>. 101568e3e3a7aSWarner Losh 101578e3e3a7aSWarner Losh 101588e3e3a7aSWarner Losh 101598e3e3a7aSWarner Losh 101608e3e3a7aSWarner Losh<p> 101618e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> 101628e3e3a7aSWarner Losh 101638e3e3a7aSWarner Losh 101648e3e3a7aSWarner Losh<p> 101658e3e3a7aSWarner LoshReturns the remainder of the division of <code>x</code> by <code>y</code> 101668e3e3a7aSWarner Loshthat rounds the quotient towards zero. (integer/float) 101678e3e3a7aSWarner Losh 101688e3e3a7aSWarner Losh 101698e3e3a7aSWarner Losh 101708e3e3a7aSWarner Losh 101718e3e3a7aSWarner Losh<p> 101728e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> 101738e3e3a7aSWarner Losh 101748e3e3a7aSWarner Losh 101758e3e3a7aSWarner Losh<p> 101768e3e3a7aSWarner LoshThe float value <code>HUGE_VAL</code>, 101770495ed39SKyle Evansa value greater than any other numeric value. 101788e3e3a7aSWarner Losh 101798e3e3a7aSWarner Losh 101808e3e3a7aSWarner Losh 101818e3e3a7aSWarner Losh 101828e3e3a7aSWarner Losh<p> 101838e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3> 101848e3e3a7aSWarner Losh 101858e3e3a7aSWarner Losh 101868e3e3a7aSWarner Losh<p> 101878e3e3a7aSWarner LoshReturns the logarithm of <code>x</code> in the given base. 101888e3e3a7aSWarner LoshThe default for <code>base</code> is <em>e</em> 101898e3e3a7aSWarner Losh(so that the function returns the natural logarithm of <code>x</code>). 101908e3e3a7aSWarner Losh 101918e3e3a7aSWarner Losh 101928e3e3a7aSWarner Losh 101938e3e3a7aSWarner Losh 101948e3e3a7aSWarner Losh<p> 101958e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> 101968e3e3a7aSWarner Losh 101978e3e3a7aSWarner Losh 101988e3e3a7aSWarner Losh<p> 101998e3e3a7aSWarner LoshReturns the argument with the maximum value, 102000495ed39SKyle Evansaccording to the Lua operator <code><</code>. 102018e3e3a7aSWarner Losh 102028e3e3a7aSWarner Losh 102038e3e3a7aSWarner Losh 102048e3e3a7aSWarner Losh 102058e3e3a7aSWarner Losh<p> 102068e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3> 102078e3e3a7aSWarner LoshAn integer with the maximum value for an integer. 102088e3e3a7aSWarner Losh 102098e3e3a7aSWarner Losh 102108e3e3a7aSWarner Losh 102118e3e3a7aSWarner Losh 102128e3e3a7aSWarner Losh<p> 102138e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> 102148e3e3a7aSWarner Losh 102158e3e3a7aSWarner Losh 102168e3e3a7aSWarner Losh<p> 102178e3e3a7aSWarner LoshReturns the argument with the minimum value, 102180495ed39SKyle Evansaccording to the Lua operator <code><</code>. 102198e3e3a7aSWarner Losh 102208e3e3a7aSWarner Losh 102218e3e3a7aSWarner Losh 102228e3e3a7aSWarner Losh 102238e3e3a7aSWarner Losh<p> 102248e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3> 102258e3e3a7aSWarner LoshAn integer with the minimum value for an integer. 102268e3e3a7aSWarner Losh 102278e3e3a7aSWarner Losh 102288e3e3a7aSWarner Losh 102298e3e3a7aSWarner Losh 102308e3e3a7aSWarner Losh<p> 102318e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> 102328e3e3a7aSWarner Losh 102338e3e3a7aSWarner Losh 102348e3e3a7aSWarner Losh<p> 102358e3e3a7aSWarner LoshReturns the integral part of <code>x</code> and the fractional part of <code>x</code>. 102368e3e3a7aSWarner LoshIts second result is always a float. 102378e3e3a7aSWarner Losh 102388e3e3a7aSWarner Losh 102398e3e3a7aSWarner Losh 102408e3e3a7aSWarner Losh 102418e3e3a7aSWarner Losh<p> 102428e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> 102438e3e3a7aSWarner Losh 102448e3e3a7aSWarner Losh 102458e3e3a7aSWarner Losh<p> 102468e3e3a7aSWarner LoshThe value of <em>π</em>. 102478e3e3a7aSWarner Losh 102488e3e3a7aSWarner Losh 102498e3e3a7aSWarner Losh 102508e3e3a7aSWarner Losh 102518e3e3a7aSWarner Losh<p> 102528e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> 102538e3e3a7aSWarner Losh 102548e3e3a7aSWarner Losh 102558e3e3a7aSWarner Losh<p> 102568e3e3a7aSWarner LoshConverts the angle <code>x</code> from degrees to radians. 102578e3e3a7aSWarner Losh 102588e3e3a7aSWarner Losh 102598e3e3a7aSWarner Losh 102608e3e3a7aSWarner Losh 102618e3e3a7aSWarner Losh<p> 102628e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> 102638e3e3a7aSWarner Losh 102648e3e3a7aSWarner Losh 102658e3e3a7aSWarner Losh<p> 102668e3e3a7aSWarner LoshWhen called without arguments, 102678e3e3a7aSWarner Loshreturns a pseudo-random float with uniform distribution 102688e3e3a7aSWarner Loshin the range <em>[0,1)</em>. 102698e3e3a7aSWarner LoshWhen called with two integers <code>m</code> and <code>n</code>, 102708e3e3a7aSWarner Losh<code>math.random</code> returns a pseudo-random integer 102718e3e3a7aSWarner Loshwith uniform distribution in the range <em>[m, n]</em>. 102720495ed39SKyle EvansThe call <code>math.random(n)</code>, for a positive <code>n</code>, 102730495ed39SKyle Evansis equivalent to <code>math.random(1,n)</code>. 102740495ed39SKyle EvansThe call <code>math.random(0)</code> produces an integer with 102750495ed39SKyle Evansall bits (pseudo)random. 102768e3e3a7aSWarner Losh 102778e3e3a7aSWarner Losh 102788e3e3a7aSWarner Losh<p> 102790495ed39SKyle EvansThis function uses the <code>xoshiro256**</code> algorithm to produce 102800495ed39SKyle Evanspseudo-random 64-bit integers, 102810495ed39SKyle Evanswhich are the results of calls with argument 0. 102820495ed39SKyle EvansOther results (ranges and floats) 102830495ed39SKyle Evansare unbiased extracted from these integers. 102840495ed39SKyle Evans 102850495ed39SKyle Evans 102860495ed39SKyle Evans<p> 102870495ed39SKyle EvansLua initializes its pseudo-random generator with the equivalent of 102880495ed39SKyle Evansa call to <a href="#pdf-math.randomseed"><code>math.randomseed</code></a> with no arguments, 102890495ed39SKyle Evansso that <code>math.random</code> should generate 102900495ed39SKyle Evansdifferent sequences of results each time the program runs. 102918e3e3a7aSWarner Losh 102928e3e3a7aSWarner Losh 102938e3e3a7aSWarner Losh 102948e3e3a7aSWarner Losh 102958e3e3a7aSWarner Losh<p> 102960495ed39SKyle Evans<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed ([x [, y]])</code></a></h3> 102978e3e3a7aSWarner Losh 102988e3e3a7aSWarner Losh 102998e3e3a7aSWarner Losh<p> 103000495ed39SKyle EvansWhen called with at least one argument, 103010495ed39SKyle Evansthe integer parameters <code>x</code> and <code>y</code> are 103020495ed39SKyle Evansjoined into a 128-bit <em>seed</em> that 103030495ed39SKyle Evansis used to reinitialize the pseudo-random generator; 103048e3e3a7aSWarner Loshequal seeds produce equal sequences of numbers. 103050495ed39SKyle EvansThe default for <code>y</code> is zero. 103060495ed39SKyle Evans 103070495ed39SKyle Evans 103080495ed39SKyle Evans<p> 103090495ed39SKyle EvansWhen called with no arguments, 103100495ed39SKyle EvansLua generates a seed with 103110495ed39SKyle Evansa weak attempt for randomness. 103120495ed39SKyle Evans 103130495ed39SKyle Evans 103140495ed39SKyle Evans<p> 103150495ed39SKyle EvansThis function returns the two seed components 103160495ed39SKyle Evansthat were effectively used, 103170495ed39SKyle Evansso that setting them again repeats the sequence. 103180495ed39SKyle Evans 103190495ed39SKyle Evans 103200495ed39SKyle Evans<p> 103210495ed39SKyle EvansTo ensure a required level of randomness to the initial state 103220495ed39SKyle Evans(or contrarily, to have a deterministic sequence, 103230495ed39SKyle Evansfor instance when debugging a program), 103240495ed39SKyle Evansyou should call <a href="#pdf-math.randomseed"><code>math.randomseed</code></a> with explicit arguments. 103258e3e3a7aSWarner Losh 103268e3e3a7aSWarner Losh 103278e3e3a7aSWarner Losh 103288e3e3a7aSWarner Losh 103298e3e3a7aSWarner Losh<p> 103308e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> 103318e3e3a7aSWarner Losh 103328e3e3a7aSWarner Losh 103338e3e3a7aSWarner Losh<p> 103348e3e3a7aSWarner LoshReturns the sine of <code>x</code> (assumed to be in radians). 103358e3e3a7aSWarner Losh 103368e3e3a7aSWarner Losh 103378e3e3a7aSWarner Losh 103388e3e3a7aSWarner Losh 103398e3e3a7aSWarner Losh<p> 103408e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> 103418e3e3a7aSWarner Losh 103428e3e3a7aSWarner Losh 103438e3e3a7aSWarner Losh<p> 103448e3e3a7aSWarner LoshReturns the square root of <code>x</code>. 103458e3e3a7aSWarner Losh(You can also use the expression <code>x^0.5</code> to compute this value.) 103468e3e3a7aSWarner Losh 103478e3e3a7aSWarner Losh 103488e3e3a7aSWarner Losh 103498e3e3a7aSWarner Losh 103508e3e3a7aSWarner Losh<p> 103518e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> 103528e3e3a7aSWarner Losh 103538e3e3a7aSWarner Losh 103548e3e3a7aSWarner Losh<p> 103558e3e3a7aSWarner LoshReturns the tangent of <code>x</code> (assumed to be in radians). 103568e3e3a7aSWarner Losh 103578e3e3a7aSWarner Losh 103588e3e3a7aSWarner Losh 103598e3e3a7aSWarner Losh 103608e3e3a7aSWarner Losh<p> 103618e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3> 103628e3e3a7aSWarner Losh 103638e3e3a7aSWarner Losh 103648e3e3a7aSWarner Losh<p> 103658e3e3a7aSWarner LoshIf the value <code>x</code> is convertible to an integer, 103668e3e3a7aSWarner Loshreturns that integer. 103670495ed39SKyle EvansOtherwise, returns <b>fail</b>. 103688e3e3a7aSWarner Losh 103698e3e3a7aSWarner Losh 103708e3e3a7aSWarner Losh 103718e3e3a7aSWarner Losh 103728e3e3a7aSWarner Losh<p> 103738e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3> 103748e3e3a7aSWarner Losh 103758e3e3a7aSWarner Losh 103768e3e3a7aSWarner Losh<p> 103778e3e3a7aSWarner LoshReturns "<code>integer</code>" if <code>x</code> is an integer, 103788e3e3a7aSWarner Losh"<code>float</code>" if it is a float, 103790495ed39SKyle Evansor <b>fail</b> if <code>x</code> is not a number. 103808e3e3a7aSWarner Losh 103818e3e3a7aSWarner Losh 103828e3e3a7aSWarner Losh 103838e3e3a7aSWarner Losh 103848e3e3a7aSWarner Losh<p> 103858e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3> 103868e3e3a7aSWarner Losh 103878e3e3a7aSWarner Losh 103888e3e3a7aSWarner Losh<p> 103898e3e3a7aSWarner LoshReturns a boolean, 10390*8c784bb8SWarner Losh<b>true</b> if and only if integer <code>m</code> is below integer <code>n</code> when 103918e3e3a7aSWarner Loshthey are compared as unsigned integers. 103928e3e3a7aSWarner Losh 103938e3e3a7aSWarner Losh 103948e3e3a7aSWarner Losh 103958e3e3a7aSWarner Losh 103968e3e3a7aSWarner Losh 103978e3e3a7aSWarner Losh 103988e3e3a7aSWarner Losh 103998e3e3a7aSWarner Losh<h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2> 104008e3e3a7aSWarner Losh 104018e3e3a7aSWarner Losh<p> 104028e3e3a7aSWarner LoshThe I/O library provides two different styles for file manipulation. 104038e3e3a7aSWarner LoshThe first one uses implicit file handles; 104048e3e3a7aSWarner Loshthat is, there are operations to set a default input file and a 104058e3e3a7aSWarner Loshdefault output file, 104060495ed39SKyle Evansand all input/output operations are done over these default files. 104078e3e3a7aSWarner LoshThe second style uses explicit file handles. 104088e3e3a7aSWarner Losh 104098e3e3a7aSWarner Losh 104108e3e3a7aSWarner Losh<p> 104118e3e3a7aSWarner LoshWhen using implicit file handles, 104128e3e3a7aSWarner Loshall operations are supplied by table <a name="pdf-io"><code>io</code></a>. 104138e3e3a7aSWarner LoshWhen using explicit file handles, 104148e3e3a7aSWarner Loshthe operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle 104158e3e3a7aSWarner Loshand then all operations are supplied as methods of the file handle. 104168e3e3a7aSWarner Losh 104178e3e3a7aSWarner Losh 104188e3e3a7aSWarner Losh<p> 104190495ed39SKyle EvansThe metatable for file handles provides metamethods 104200495ed39SKyle Evansfor <code>__gc</code> and <code>__close</code> that try 104210495ed39SKyle Evansto close the file when called. 104220495ed39SKyle Evans 104230495ed39SKyle Evans 104240495ed39SKyle Evans<p> 104258e3e3a7aSWarner LoshThe table <code>io</code> also provides 104268e3e3a7aSWarner Loshthree predefined file handles with their usual meanings from C: 104278e3e3a7aSWarner 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>. 104288e3e3a7aSWarner LoshThe I/O library never closes these files. 104298e3e3a7aSWarner Losh 104308e3e3a7aSWarner Losh 104318e3e3a7aSWarner Losh<p> 104328e3e3a7aSWarner LoshUnless otherwise stated, 104330495ed39SKyle Evansall I/O functions return <b>fail</b> on failure, 104340495ed39SKyle Evansplus an error message as a second result and 104350495ed39SKyle Evansa system-dependent error code as a third result, 104360495ed39SKyle Evansand some non-false value on success. 104370495ed39SKyle EvansOn non-POSIX systems, 104388e3e3a7aSWarner Loshthe computation of the error message and error code 104398e3e3a7aSWarner Loshin case of errors 104408e3e3a7aSWarner Loshmay be not thread safe, 104418e3e3a7aSWarner Loshbecause they rely on the global C variable <code>errno</code>. 104428e3e3a7aSWarner Losh 104438e3e3a7aSWarner Losh 104448e3e3a7aSWarner Losh<p> 104458e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> 104468e3e3a7aSWarner Losh 104478e3e3a7aSWarner Losh 104488e3e3a7aSWarner Losh<p> 104498e3e3a7aSWarner LoshEquivalent to <code>file:close()</code>. 104508e3e3a7aSWarner LoshWithout a <code>file</code>, closes the default output file. 104518e3e3a7aSWarner Losh 104528e3e3a7aSWarner Losh 104538e3e3a7aSWarner Losh 104548e3e3a7aSWarner Losh 104558e3e3a7aSWarner Losh<p> 104568e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> 104578e3e3a7aSWarner Losh 104588e3e3a7aSWarner Losh 104598e3e3a7aSWarner Losh<p> 104608e3e3a7aSWarner LoshEquivalent to <code>io.output():flush()</code>. 104618e3e3a7aSWarner Losh 104628e3e3a7aSWarner Losh 104638e3e3a7aSWarner Losh 104648e3e3a7aSWarner Losh 104658e3e3a7aSWarner Losh<p> 104668e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> 104678e3e3a7aSWarner Losh 104688e3e3a7aSWarner Losh 104698e3e3a7aSWarner Losh<p> 104708e3e3a7aSWarner LoshWhen called with a file name, it opens the named file (in text mode), 104718e3e3a7aSWarner Loshand sets its handle as the default input file. 104728e3e3a7aSWarner LoshWhen called with a file handle, 104738e3e3a7aSWarner Loshit simply sets this file handle as the default input file. 10474e112e9d2SKyle EvansWhen called without arguments, 104758e3e3a7aSWarner Loshit returns the current default input file. 104768e3e3a7aSWarner Losh 104778e3e3a7aSWarner Losh 104788e3e3a7aSWarner Losh<p> 104798e3e3a7aSWarner LoshIn case of errors this function raises the error, 104808e3e3a7aSWarner Loshinstead of returning an error code. 104818e3e3a7aSWarner Losh 104828e3e3a7aSWarner Losh 104838e3e3a7aSWarner Losh 104848e3e3a7aSWarner Losh 104858e3e3a7aSWarner Losh<p> 104868e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, ···])</code></a></h3> 104878e3e3a7aSWarner Losh 104888e3e3a7aSWarner Losh 104898e3e3a7aSWarner Losh<p> 104908e3e3a7aSWarner LoshOpens the given file name in read mode 104918e3e3a7aSWarner Loshand returns an iterator function that 104928e3e3a7aSWarner Loshworks like <code>file:lines(···)</code> over the opened file. 104930495ed39SKyle EvansWhen the iterator function fails to read any value, 104940495ed39SKyle Evansit automatically closes the file. 104950495ed39SKyle EvansBesides the iterator function, 104960495ed39SKyle Evans<code>io.lines</code> returns three other values: 104970495ed39SKyle Evanstwo <b>nil</b> values as placeholders, 104980495ed39SKyle Evansplus the created file handle. 104990495ed39SKyle EvansTherefore, when used in a generic <b>for</b> loop, 105000495ed39SKyle Evansthe file is closed also if the loop is interrupted by an 105010495ed39SKyle Evanserror or a <b>break</b>. 105028e3e3a7aSWarner Losh 105038e3e3a7aSWarner Losh 105048e3e3a7aSWarner Losh<p> 105058e3e3a7aSWarner LoshThe call <code>io.lines()</code> (with no file name) is equivalent 105060495ed39SKyle Evansto <code>io.input():lines("l")</code>; 105078e3e3a7aSWarner Loshthat is, it iterates over the lines of the default input file. 10508e112e9d2SKyle EvansIn this case, the iterator does not close the file when the loop ends. 105098e3e3a7aSWarner Losh 105108e3e3a7aSWarner Losh 105118e3e3a7aSWarner Losh<p> 105120495ed39SKyle EvansIn case of errors opening the file, 105130495ed39SKyle Evansthis function raises the error, 105148e3e3a7aSWarner Loshinstead of returning an error code. 105158e3e3a7aSWarner Losh 105168e3e3a7aSWarner Losh 105178e3e3a7aSWarner Losh 105188e3e3a7aSWarner Losh 105198e3e3a7aSWarner Losh<p> 105208e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> 105218e3e3a7aSWarner Losh 105228e3e3a7aSWarner Losh 105238e3e3a7aSWarner Losh<p> 105248e3e3a7aSWarner LoshThis function opens a file, 105258e3e3a7aSWarner Loshin the mode specified in the string <code>mode</code>. 105268e3e3a7aSWarner LoshIn case of success, 105278e3e3a7aSWarner Loshit returns a new file handle. 105288e3e3a7aSWarner Losh 105298e3e3a7aSWarner Losh 105308e3e3a7aSWarner Losh<p> 105318e3e3a7aSWarner LoshThe <code>mode</code> string can be any of the following: 105328e3e3a7aSWarner Losh 105338e3e3a7aSWarner Losh<ul> 105348e3e3a7aSWarner Losh<li><b>"<code>r</code>": </b> read mode (the default);</li> 105358e3e3a7aSWarner Losh<li><b>"<code>w</code>": </b> write mode;</li> 105368e3e3a7aSWarner Losh<li><b>"<code>a</code>": </b> append mode;</li> 105378e3e3a7aSWarner Losh<li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li> 105388e3e3a7aSWarner Losh<li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li> 105398e3e3a7aSWarner Losh<li><b>"<code>a+</code>": </b> append update mode, previous data is preserved, 105408e3e3a7aSWarner Losh writing is only allowed at the end of file.</li> 105418e3e3a7aSWarner Losh</ul><p> 105428e3e3a7aSWarner LoshThe <code>mode</code> string can also have a '<code>b</code>' at the end, 105438e3e3a7aSWarner Loshwhich is needed in some systems to open the file in binary mode. 105448e3e3a7aSWarner Losh 105458e3e3a7aSWarner Losh 105468e3e3a7aSWarner Losh 105478e3e3a7aSWarner Losh 105488e3e3a7aSWarner Losh<p> 105498e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> 105508e3e3a7aSWarner Losh 105518e3e3a7aSWarner Losh 105528e3e3a7aSWarner Losh<p> 105538e3e3a7aSWarner LoshSimilar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. 105548e3e3a7aSWarner Losh 105558e3e3a7aSWarner Losh 105568e3e3a7aSWarner Losh 105578e3e3a7aSWarner Losh 105588e3e3a7aSWarner Losh<p> 105598e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> 105608e3e3a7aSWarner Losh 105618e3e3a7aSWarner Losh 105628e3e3a7aSWarner Losh<p> 105638e3e3a7aSWarner LoshThis function is system dependent and is not available 105648e3e3a7aSWarner Loshon all platforms. 105658e3e3a7aSWarner Losh 105668e3e3a7aSWarner Losh 105678e3e3a7aSWarner Losh<p> 105680495ed39SKyle EvansStarts the program <code>prog</code> in a separated process and returns 105698e3e3a7aSWarner Losha file handle that you can use to read data from this program 105708e3e3a7aSWarner Losh(if <code>mode</code> is <code>"r"</code>, the default) 105718e3e3a7aSWarner Loshor to write data to this program 105728e3e3a7aSWarner Losh(if <code>mode</code> is <code>"w"</code>). 105738e3e3a7aSWarner Losh 105748e3e3a7aSWarner Losh 105758e3e3a7aSWarner Losh 105768e3e3a7aSWarner Losh 105778e3e3a7aSWarner Losh<p> 105788e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> 105798e3e3a7aSWarner Losh 105808e3e3a7aSWarner Losh 105818e3e3a7aSWarner Losh<p> 105828e3e3a7aSWarner LoshEquivalent to <code>io.input():read(···)</code>. 105838e3e3a7aSWarner Losh 105848e3e3a7aSWarner Losh 105858e3e3a7aSWarner Losh 105868e3e3a7aSWarner Losh 105878e3e3a7aSWarner Losh<p> 105888e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> 105898e3e3a7aSWarner Losh 105908e3e3a7aSWarner Losh 105918e3e3a7aSWarner Losh<p> 105928e3e3a7aSWarner LoshIn case of success, 105938e3e3a7aSWarner Loshreturns a handle for a temporary file. 105948e3e3a7aSWarner LoshThis file is opened in update mode 105958e3e3a7aSWarner Loshand it is automatically removed when the program ends. 105968e3e3a7aSWarner Losh 105978e3e3a7aSWarner Losh 105988e3e3a7aSWarner Losh 105998e3e3a7aSWarner Losh 106008e3e3a7aSWarner Losh<p> 106018e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> 106028e3e3a7aSWarner Losh 106038e3e3a7aSWarner Losh 106048e3e3a7aSWarner Losh<p> 106058e3e3a7aSWarner LoshChecks whether <code>obj</code> is a valid file handle. 106068e3e3a7aSWarner LoshReturns the string <code>"file"</code> if <code>obj</code> is an open file handle, 106078e3e3a7aSWarner Losh<code>"closed file"</code> if <code>obj</code> is a closed file handle, 106080495ed39SKyle Evansor <b>fail</b> if <code>obj</code> is not a file handle. 106098e3e3a7aSWarner Losh 106108e3e3a7aSWarner Losh 106118e3e3a7aSWarner Losh 106128e3e3a7aSWarner Losh 106138e3e3a7aSWarner Losh<p> 106148e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> 106158e3e3a7aSWarner Losh 106168e3e3a7aSWarner Losh 106178e3e3a7aSWarner Losh<p> 106188e3e3a7aSWarner LoshEquivalent to <code>io.output():write(···)</code>. 106198e3e3a7aSWarner Losh 106208e3e3a7aSWarner Losh 106218e3e3a7aSWarner Losh 106228e3e3a7aSWarner Losh 106238e3e3a7aSWarner Losh<p> 106248e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> 106258e3e3a7aSWarner Losh 106268e3e3a7aSWarner Losh 106278e3e3a7aSWarner Losh<p> 106288e3e3a7aSWarner LoshCloses <code>file</code>. 106298e3e3a7aSWarner LoshNote that files are automatically closed when 106308e3e3a7aSWarner Loshtheir handles are garbage collected, 106318e3e3a7aSWarner Loshbut that takes an unpredictable amount of time to happen. 106328e3e3a7aSWarner Losh 106338e3e3a7aSWarner Losh 106348e3e3a7aSWarner Losh<p> 106358e3e3a7aSWarner LoshWhen closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>, 106368e3e3a7aSWarner Losh<a href="#pdf-file:close"><code>file:close</code></a> returns the same values 106378e3e3a7aSWarner Loshreturned by <a href="#pdf-os.execute"><code>os.execute</code></a>. 106388e3e3a7aSWarner Losh 106398e3e3a7aSWarner Losh 106408e3e3a7aSWarner Losh 106418e3e3a7aSWarner Losh 106428e3e3a7aSWarner Losh<p> 106438e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> 106448e3e3a7aSWarner Losh 106458e3e3a7aSWarner Losh 106468e3e3a7aSWarner Losh<p> 106478e3e3a7aSWarner LoshSaves any written data to <code>file</code>. 106488e3e3a7aSWarner Losh 106498e3e3a7aSWarner Losh 106508e3e3a7aSWarner Losh 106518e3e3a7aSWarner Losh 106528e3e3a7aSWarner Losh<p> 106538e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3> 106548e3e3a7aSWarner Losh 106558e3e3a7aSWarner Losh 106568e3e3a7aSWarner Losh<p> 106578e3e3a7aSWarner LoshReturns an iterator function that, 106588e3e3a7aSWarner Losheach time it is called, 106598e3e3a7aSWarner Loshreads the file according to the given formats. 106608e3e3a7aSWarner LoshWhen no format is given, 106618e3e3a7aSWarner Loshuses "<code>l</code>" as a default. 106628e3e3a7aSWarner LoshAs an example, the construction 106638e3e3a7aSWarner Losh 106648e3e3a7aSWarner Losh<pre> 106658e3e3a7aSWarner Losh for c in file:lines(1) do <em>body</em> end 106668e3e3a7aSWarner Losh</pre><p> 106678e3e3a7aSWarner Loshwill iterate over all characters of the file, 106688e3e3a7aSWarner Loshstarting at the current position. 106698e3e3a7aSWarner LoshUnlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file 106708e3e3a7aSWarner Loshwhen the loop ends. 106718e3e3a7aSWarner Losh 106728e3e3a7aSWarner Losh 106738e3e3a7aSWarner Losh 106748e3e3a7aSWarner Losh 106758e3e3a7aSWarner Losh<p> 106768e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> 106778e3e3a7aSWarner Losh 106788e3e3a7aSWarner Losh 106798e3e3a7aSWarner Losh<p> 106808e3e3a7aSWarner LoshReads the file <code>file</code>, 106818e3e3a7aSWarner Loshaccording to the given formats, which specify what to read. 106828e3e3a7aSWarner LoshFor each format, 106838e3e3a7aSWarner Loshthe function returns a string or a number with the characters read, 106840495ed39SKyle Evansor <b>fail</b> if it cannot read data with the specified format. 106858e3e3a7aSWarner Losh(In this latter case, 106868e3e3a7aSWarner Loshthe function does not read subsequent formats.) 106870495ed39SKyle EvansWhen called without arguments, 106888e3e3a7aSWarner Loshit uses a default format that reads the next line 106898e3e3a7aSWarner Losh(see below). 106908e3e3a7aSWarner Losh 106918e3e3a7aSWarner Losh 106928e3e3a7aSWarner Losh<p> 106938e3e3a7aSWarner LoshThe available formats are 106948e3e3a7aSWarner Losh 106958e3e3a7aSWarner Losh<ul> 106968e3e3a7aSWarner Losh 106978e3e3a7aSWarner Losh<li><b>"<code>n</code>": </b> 106988e3e3a7aSWarner Loshreads a numeral and returns it as a float or an integer, 106998e3e3a7aSWarner Loshfollowing the lexical conventions of Lua. 107000495ed39SKyle Evans(The numeral may have leading whitespaces and a sign.) 107018e3e3a7aSWarner LoshThis format always reads the longest input sequence that 107028e3e3a7aSWarner Loshis a valid prefix for a numeral; 107038e3e3a7aSWarner Loshif that prefix does not form a valid numeral 107040495ed39SKyle Evans(e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>") 107050495ed39SKyle Evansor it is too long (more than 200 characters), 107060495ed39SKyle Evansit is discarded and the format returns <b>fail</b>. 107078e3e3a7aSWarner Losh</li> 107088e3e3a7aSWarner Losh 107098e3e3a7aSWarner Losh<li><b>"<code>a</code>": </b> 107108e3e3a7aSWarner Loshreads the whole file, starting at the current position. 107110495ed39SKyle EvansOn end of file, it returns the empty string; 107120495ed39SKyle Evansthis format never fails. 107138e3e3a7aSWarner Losh</li> 107148e3e3a7aSWarner Losh 107158e3e3a7aSWarner Losh<li><b>"<code>l</code>": </b> 107168e3e3a7aSWarner Loshreads the next line skipping the end of line, 107170495ed39SKyle Evansreturning <b>fail</b> on end of file. 107188e3e3a7aSWarner LoshThis is the default format. 107198e3e3a7aSWarner Losh</li> 107208e3e3a7aSWarner Losh 107218e3e3a7aSWarner Losh<li><b>"<code>L</code>": </b> 107228e3e3a7aSWarner Loshreads the next line keeping the end-of-line character (if present), 107230495ed39SKyle Evansreturning <b>fail</b> on end of file. 107248e3e3a7aSWarner Losh</li> 107258e3e3a7aSWarner Losh 107268e3e3a7aSWarner Losh<li><b><em>number</em>: </b> 107278e3e3a7aSWarner Loshreads a string with up to this number of bytes, 107280495ed39SKyle Evansreturning <b>fail</b> on end of file. 107298e3e3a7aSWarner LoshIf <code>number</code> is zero, 107308e3e3a7aSWarner Loshit reads nothing and returns an empty string, 107310495ed39SKyle Evansor <b>fail</b> on end of file. 107328e3e3a7aSWarner Losh</li> 107338e3e3a7aSWarner Losh 107348e3e3a7aSWarner Losh</ul><p> 107358e3e3a7aSWarner LoshThe formats "<code>l</code>" and "<code>L</code>" should be used only for text files. 107368e3e3a7aSWarner Losh 107378e3e3a7aSWarner Losh 107388e3e3a7aSWarner Losh 107398e3e3a7aSWarner Losh 107408e3e3a7aSWarner Losh<p> 107418e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3> 107428e3e3a7aSWarner Losh 107438e3e3a7aSWarner Losh 107448e3e3a7aSWarner Losh<p> 107458e3e3a7aSWarner LoshSets and gets the file position, 107468e3e3a7aSWarner Loshmeasured from the beginning of the file, 107478e3e3a7aSWarner Loshto the position given by <code>offset</code> plus a base 107488e3e3a7aSWarner Loshspecified by the string <code>whence</code>, as follows: 107498e3e3a7aSWarner Losh 107508e3e3a7aSWarner Losh<ul> 107518e3e3a7aSWarner Losh<li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li> 107528e3e3a7aSWarner Losh<li><b>"<code>cur</code>": </b> base is current position;</li> 107538e3e3a7aSWarner Losh<li><b>"<code>end</code>": </b> base is end of file;</li> 107548e3e3a7aSWarner Losh</ul><p> 107558e3e3a7aSWarner LoshIn case of success, <code>seek</code> returns the final file position, 107568e3e3a7aSWarner Loshmeasured in bytes from the beginning of the file. 107570495ed39SKyle EvansIf <code>seek</code> fails, it returns <b>fail</b>, 107588e3e3a7aSWarner Loshplus a string describing the error. 107598e3e3a7aSWarner Losh 107608e3e3a7aSWarner Losh 107618e3e3a7aSWarner Losh<p> 107628e3e3a7aSWarner LoshThe default value for <code>whence</code> is <code>"cur"</code>, 107638e3e3a7aSWarner Loshand for <code>offset</code> is 0. 107648e3e3a7aSWarner LoshTherefore, the call <code>file:seek()</code> returns the current 107658e3e3a7aSWarner Loshfile position, without changing it; 107668e3e3a7aSWarner Loshthe call <code>file:seek("set")</code> sets the position to the 107678e3e3a7aSWarner Loshbeginning of the file (and returns 0); 107688e3e3a7aSWarner Loshand the call <code>file:seek("end")</code> sets the position to the 107698e3e3a7aSWarner Loshend of the file, and returns its size. 107708e3e3a7aSWarner Losh 107718e3e3a7aSWarner Losh 107728e3e3a7aSWarner Losh 107738e3e3a7aSWarner Losh 107748e3e3a7aSWarner Losh<p> 107758e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> 107768e3e3a7aSWarner Losh 107778e3e3a7aSWarner Losh 107788e3e3a7aSWarner Losh<p> 107790495ed39SKyle EvansSets the buffering mode for a file. 107808e3e3a7aSWarner LoshThere are three available modes: 107818e3e3a7aSWarner Losh 107828e3e3a7aSWarner Losh<ul> 107830495ed39SKyle Evans<li><b>"<code>no</code>": </b> no buffering.</li> 107840495ed39SKyle Evans<li><b>"<code>full</code>": </b> full buffering.</li> 107850495ed39SKyle Evans<li><b>"<code>line</code>": </b> line buffering.</li> 107860495ed39SKyle Evans</ul> 107878e3e3a7aSWarner Losh 107880495ed39SKyle Evans<p> 107890495ed39SKyle EvansFor the last two cases, 107900495ed39SKyle Evans<code>size</code> is a hint for the size of the buffer, in bytes. 107918e3e3a7aSWarner LoshThe default is an appropriate size. 107928e3e3a7aSWarner Losh 107938e3e3a7aSWarner Losh 107940495ed39SKyle Evans<p> 107950495ed39SKyle EvansThe specific behavior of each mode is non portable; 107960495ed39SKyle Evanscheck the underlying ISO C function <code>setvbuf</code> in your platform for 107970495ed39SKyle Evansmore details. 107980495ed39SKyle Evans 107990495ed39SKyle Evans 108008e3e3a7aSWarner Losh 108018e3e3a7aSWarner Losh 108028e3e3a7aSWarner Losh<p> 108038e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> 108048e3e3a7aSWarner Losh 108058e3e3a7aSWarner Losh 108068e3e3a7aSWarner Losh<p> 108078e3e3a7aSWarner LoshWrites the value of each of its arguments to <code>file</code>. 108088e3e3a7aSWarner LoshThe arguments must be strings or numbers. 108098e3e3a7aSWarner Losh 108108e3e3a7aSWarner Losh 108118e3e3a7aSWarner Losh<p> 108128e3e3a7aSWarner LoshIn case of success, this function returns <code>file</code>. 108138e3e3a7aSWarner Losh 108148e3e3a7aSWarner Losh 108158e3e3a7aSWarner Losh 108168e3e3a7aSWarner Losh 108178e3e3a7aSWarner Losh 108188e3e3a7aSWarner Losh 108198e3e3a7aSWarner Losh 108208e3e3a7aSWarner Losh<h2>6.9 – <a name="6.9">Operating System Facilities</a></h2> 108218e3e3a7aSWarner Losh 108228e3e3a7aSWarner Losh<p> 108238e3e3a7aSWarner LoshThis library is implemented through table <a name="pdf-os"><code>os</code></a>. 108248e3e3a7aSWarner Losh 108258e3e3a7aSWarner Losh 108268e3e3a7aSWarner Losh<p> 108278e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> 108288e3e3a7aSWarner Losh 108298e3e3a7aSWarner Losh 108308e3e3a7aSWarner Losh<p> 108318e3e3a7aSWarner LoshReturns an approximation of the amount in seconds of CPU time 108320495ed39SKyle Evansused by the program, 108330495ed39SKyle Evansas returned by the underlying ISO C function <code>clock</code>. 108348e3e3a7aSWarner Losh 108358e3e3a7aSWarner Losh 108368e3e3a7aSWarner Losh 108378e3e3a7aSWarner Losh 108388e3e3a7aSWarner Losh<p> 108398e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> 108408e3e3a7aSWarner Losh 108418e3e3a7aSWarner Losh 108428e3e3a7aSWarner Losh<p> 108438e3e3a7aSWarner LoshReturns a string or a table containing date and time, 108448e3e3a7aSWarner Loshformatted according to the given string <code>format</code>. 108458e3e3a7aSWarner Losh 108468e3e3a7aSWarner Losh 108478e3e3a7aSWarner Losh<p> 108488e3e3a7aSWarner LoshIf the <code>time</code> argument is present, 108498e3e3a7aSWarner Loshthis is the time to be formatted 108508e3e3a7aSWarner Losh(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). 108518e3e3a7aSWarner LoshOtherwise, <code>date</code> formats the current time. 108528e3e3a7aSWarner Losh 108538e3e3a7aSWarner Losh 108548e3e3a7aSWarner Losh<p> 108558e3e3a7aSWarner LoshIf <code>format</code> starts with '<code>!</code>', 108568e3e3a7aSWarner Loshthen the date is formatted in Coordinated Universal Time. 108578e3e3a7aSWarner LoshAfter this optional character, 108588e3e3a7aSWarner Loshif <code>format</code> is the string "<code>*t</code>", 108598e3e3a7aSWarner Loshthen <code>date</code> returns a table with the following fields: 108608e3e3a7aSWarner Losh<code>year</code>, <code>month</code> (1–12), <code>day</code> (1–31), 108610495ed39SKyle Evans<code>hour</code> (0–23), <code>min</code> (0–59), 108620495ed39SKyle Evans<code>sec</code> (0–61, due to leap seconds), 108638e3e3a7aSWarner Losh<code>wday</code> (weekday, 1–7, Sunday is 1), 108648e3e3a7aSWarner Losh<code>yday</code> (day of the year, 1–366), 108658e3e3a7aSWarner Loshand <code>isdst</code> (daylight saving flag, a boolean). 108668e3e3a7aSWarner LoshThis last field may be absent 108678e3e3a7aSWarner Loshif the information is not available. 108688e3e3a7aSWarner Losh 108698e3e3a7aSWarner Losh 108708e3e3a7aSWarner Losh<p> 108718e3e3a7aSWarner LoshIf <code>format</code> is not "<code>*t</code>", 108728e3e3a7aSWarner Loshthen <code>date</code> returns the date as a string, 108738e3e3a7aSWarner Loshformatted according to the same rules as the ISO C function <code>strftime</code>. 108748e3e3a7aSWarner Losh 108758e3e3a7aSWarner Losh 108768e3e3a7aSWarner Losh<p> 108770495ed39SKyle EvansIf <code>format</code> is absent, it defaults to "<code>%c</code>", 108780495ed39SKyle Evanswhich gives a human-readable date and time representation 108790495ed39SKyle Evansusing the current locale. 108808e3e3a7aSWarner Losh 108818e3e3a7aSWarner Losh 108828e3e3a7aSWarner Losh<p> 108830495ed39SKyle EvansOn non-POSIX systems, 108848e3e3a7aSWarner Loshthis function may be not thread safe 108858e3e3a7aSWarner Loshbecause of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>. 108868e3e3a7aSWarner Losh 108878e3e3a7aSWarner Losh 108888e3e3a7aSWarner Losh 108898e3e3a7aSWarner Losh 108908e3e3a7aSWarner Losh<p> 108918e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> 108928e3e3a7aSWarner Losh 108938e3e3a7aSWarner Losh 108948e3e3a7aSWarner Losh<p> 108958e3e3a7aSWarner LoshReturns the difference, in seconds, 108968e3e3a7aSWarner Loshfrom time <code>t1</code> to time <code>t2</code> 108978e3e3a7aSWarner Losh(where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>). 108988e3e3a7aSWarner LoshIn POSIX, Windows, and some other systems, 108998e3e3a7aSWarner Loshthis value is exactly <code>t2</code><em>-</em><code>t1</code>. 109008e3e3a7aSWarner Losh 109018e3e3a7aSWarner Losh 109028e3e3a7aSWarner Losh 109038e3e3a7aSWarner Losh 109048e3e3a7aSWarner Losh<p> 109058e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> 109068e3e3a7aSWarner Losh 109078e3e3a7aSWarner Losh 109088e3e3a7aSWarner Losh<p> 109098e3e3a7aSWarner LoshThis function is equivalent to the ISO C function <code>system</code>. 109108e3e3a7aSWarner LoshIt passes <code>command</code> to be executed by an operating system shell. 109118e3e3a7aSWarner LoshIts first result is <b>true</b> 109128e3e3a7aSWarner Loshif the command terminated successfully, 109130495ed39SKyle Evansor <b>fail</b> otherwise. 109148e3e3a7aSWarner LoshAfter this first result 109158e3e3a7aSWarner Loshthe function returns a string plus a number, 109168e3e3a7aSWarner Loshas follows: 109178e3e3a7aSWarner Losh 109188e3e3a7aSWarner Losh<ul> 109198e3e3a7aSWarner Losh 109208e3e3a7aSWarner Losh<li><b>"<code>exit</code>": </b> 109218e3e3a7aSWarner Loshthe command terminated normally; 109228e3e3a7aSWarner Loshthe following number is the exit status of the command. 109238e3e3a7aSWarner Losh</li> 109248e3e3a7aSWarner Losh 109258e3e3a7aSWarner Losh<li><b>"<code>signal</code>": </b> 109268e3e3a7aSWarner Loshthe command was terminated by a signal; 109278e3e3a7aSWarner Loshthe following number is the signal that terminated the command. 109288e3e3a7aSWarner Losh</li> 109298e3e3a7aSWarner Losh 109308e3e3a7aSWarner Losh</ul> 109318e3e3a7aSWarner Losh 109328e3e3a7aSWarner Losh<p> 109338e3e3a7aSWarner LoshWhen called without a <code>command</code>, 109348e3e3a7aSWarner Losh<code>os.execute</code> returns a boolean that is true if a shell is available. 109358e3e3a7aSWarner Losh 109368e3e3a7aSWarner Losh 109378e3e3a7aSWarner Losh 109388e3e3a7aSWarner Losh 109398e3e3a7aSWarner Losh<p> 109408e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3> 109418e3e3a7aSWarner Losh 109428e3e3a7aSWarner Losh 109438e3e3a7aSWarner Losh<p> 109448e3e3a7aSWarner LoshCalls the ISO C function <code>exit</code> to terminate the host program. 109458e3e3a7aSWarner LoshIf <code>code</code> is <b>true</b>, 109468e3e3a7aSWarner Loshthe returned status is <code>EXIT_SUCCESS</code>; 109478e3e3a7aSWarner Loshif <code>code</code> is <b>false</b>, 109488e3e3a7aSWarner Loshthe returned status is <code>EXIT_FAILURE</code>; 109498e3e3a7aSWarner Loshif <code>code</code> is a number, 109508e3e3a7aSWarner Loshthe returned status is this number. 109518e3e3a7aSWarner LoshThe default value for <code>code</code> is <b>true</b>. 109528e3e3a7aSWarner Losh 109538e3e3a7aSWarner Losh 109548e3e3a7aSWarner Losh<p> 109558e3e3a7aSWarner LoshIf the optional second argument <code>close</code> is true, 109568e3e3a7aSWarner Loshcloses the Lua state before exiting. 109578e3e3a7aSWarner Losh 109588e3e3a7aSWarner Losh 109598e3e3a7aSWarner Losh 109608e3e3a7aSWarner Losh 109618e3e3a7aSWarner Losh<p> 109628e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> 109638e3e3a7aSWarner Losh 109648e3e3a7aSWarner Losh 109658e3e3a7aSWarner Losh<p> 109660495ed39SKyle EvansReturns the value of the process environment variable <code>varname</code> 109670495ed39SKyle Evansor <b>fail</b> if the variable is not defined. 109688e3e3a7aSWarner Losh 109698e3e3a7aSWarner Losh 109708e3e3a7aSWarner Losh 109718e3e3a7aSWarner Losh 109728e3e3a7aSWarner Losh<p> 109738e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> 109748e3e3a7aSWarner Losh 109758e3e3a7aSWarner Losh 109768e3e3a7aSWarner Losh<p> 109778e3e3a7aSWarner LoshDeletes the file (or empty directory, on POSIX systems) 109788e3e3a7aSWarner Loshwith the given name. 109790495ed39SKyle EvansIf this function fails, it returns <b>fail</b> 109808e3e3a7aSWarner Loshplus a string describing the error and the error code. 109818e3e3a7aSWarner LoshOtherwise, it returns true. 109828e3e3a7aSWarner Losh 109838e3e3a7aSWarner Losh 109848e3e3a7aSWarner Losh 109858e3e3a7aSWarner Losh 109868e3e3a7aSWarner Losh<p> 109878e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> 109888e3e3a7aSWarner Losh 109898e3e3a7aSWarner Losh 109908e3e3a7aSWarner Losh<p> 109918e3e3a7aSWarner LoshRenames the file or directory named <code>oldname</code> to <code>newname</code>. 109920495ed39SKyle EvansIf this function fails, it returns <b>fail</b>, 109938e3e3a7aSWarner Loshplus a string describing the error and the error code. 109948e3e3a7aSWarner LoshOtherwise, it returns true. 109958e3e3a7aSWarner Losh 109968e3e3a7aSWarner Losh 109978e3e3a7aSWarner Losh 109988e3e3a7aSWarner Losh 109998e3e3a7aSWarner Losh<p> 110008e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> 110018e3e3a7aSWarner Losh 110028e3e3a7aSWarner Losh 110038e3e3a7aSWarner Losh<p> 110048e3e3a7aSWarner LoshSets the current locale of the program. 110058e3e3a7aSWarner Losh<code>locale</code> is a system-dependent string specifying a locale; 110068e3e3a7aSWarner Losh<code>category</code> is an optional string describing which category to change: 110078e3e3a7aSWarner Losh<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, 110088e3e3a7aSWarner Losh<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; 110098e3e3a7aSWarner Loshthe default category is <code>"all"</code>. 110108e3e3a7aSWarner LoshThe function returns the name of the new locale, 110110495ed39SKyle Evansor <b>fail</b> if the request cannot be honored. 110128e3e3a7aSWarner Losh 110138e3e3a7aSWarner Losh 110148e3e3a7aSWarner Losh<p> 110158e3e3a7aSWarner LoshIf <code>locale</code> is the empty string, 110168e3e3a7aSWarner Loshthe current locale is set to an implementation-defined native locale. 110178e3e3a7aSWarner LoshIf <code>locale</code> is the string "<code>C</code>", 110188e3e3a7aSWarner Loshthe current locale is set to the standard C locale. 110198e3e3a7aSWarner Losh 110208e3e3a7aSWarner Losh 110218e3e3a7aSWarner Losh<p> 110228e3e3a7aSWarner LoshWhen called with <b>nil</b> as the first argument, 110238e3e3a7aSWarner Loshthis function only returns the name of the current locale 110248e3e3a7aSWarner Loshfor the given category. 110258e3e3a7aSWarner Losh 110268e3e3a7aSWarner Losh 110278e3e3a7aSWarner Losh<p> 110288e3e3a7aSWarner LoshThis function may be not thread safe 110298e3e3a7aSWarner Loshbecause of its reliance on C function <code>setlocale</code>. 110308e3e3a7aSWarner Losh 110318e3e3a7aSWarner Losh 110328e3e3a7aSWarner Losh 110338e3e3a7aSWarner Losh 110348e3e3a7aSWarner Losh<p> 110358e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> 110368e3e3a7aSWarner Losh 110378e3e3a7aSWarner Losh 110388e3e3a7aSWarner Losh<p> 110398e3e3a7aSWarner LoshReturns the current time when called without arguments, 110408e3e3a7aSWarner Loshor a time representing the local date and time specified by the given table. 110418e3e3a7aSWarner LoshThis table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, 110428e3e3a7aSWarner Loshand may have fields 110438e3e3a7aSWarner Losh<code>hour</code> (default is 12), 110448e3e3a7aSWarner Losh<code>min</code> (default is 0), 110458e3e3a7aSWarner Losh<code>sec</code> (default is 0), 110468e3e3a7aSWarner Loshand <code>isdst</code> (default is <b>nil</b>). 110478e3e3a7aSWarner LoshOther fields are ignored. 110488e3e3a7aSWarner LoshFor a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function. 110498e3e3a7aSWarner Losh 110508e3e3a7aSWarner Losh 110518e3e3a7aSWarner Losh<p> 110520495ed39SKyle EvansWhen the function is called, 110530495ed39SKyle Evansthe values in these fields do not need to be inside their valid ranges. 110548e3e3a7aSWarner LoshFor instance, if <code>sec</code> is -10, 110550495ed39SKyle Evansit means 10 seconds before the time specified by the other fields; 110568e3e3a7aSWarner Loshif <code>hour</code> is 1000, 110570495ed39SKyle Evansit means 1000 hours after the time specified by the other fields. 110588e3e3a7aSWarner Losh 110598e3e3a7aSWarner Losh 110608e3e3a7aSWarner Losh<p> 110618e3e3a7aSWarner LoshThe returned value is a number, whose meaning depends on your system. 110628e3e3a7aSWarner LoshIn POSIX, Windows, and some other systems, 110638e3e3a7aSWarner Loshthis number counts the number 110648e3e3a7aSWarner Loshof seconds since some given start time (the "epoch"). 110658e3e3a7aSWarner LoshIn other systems, the meaning is not specified, 110668e3e3a7aSWarner Loshand the number returned by <code>time</code> can be used only as an argument to 110678e3e3a7aSWarner Losh<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. 110688e3e3a7aSWarner Losh 110698e3e3a7aSWarner Losh 110700495ed39SKyle Evans<p> 110710495ed39SKyle EvansWhen called with a table, 110720495ed39SKyle Evans<code>os.time</code> also normalizes all the fields 110730495ed39SKyle Evansdocumented in the <a href="#pdf-os.date"><code>os.date</code></a> function, 110740495ed39SKyle Evansso that they represent the same time as before the call 110750495ed39SKyle Evansbut with values inside their valid ranges. 110760495ed39SKyle Evans 110770495ed39SKyle Evans 110788e3e3a7aSWarner Losh 110798e3e3a7aSWarner Losh 110808e3e3a7aSWarner Losh<p> 110818e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> 110828e3e3a7aSWarner Losh 110838e3e3a7aSWarner Losh 110848e3e3a7aSWarner Losh<p> 110858e3e3a7aSWarner LoshReturns a string with a file name that can 110868e3e3a7aSWarner Loshbe used for a temporary file. 110878e3e3a7aSWarner LoshThe file must be explicitly opened before its use 110888e3e3a7aSWarner Loshand explicitly removed when no longer needed. 110898e3e3a7aSWarner Losh 110908e3e3a7aSWarner Losh 110918e3e3a7aSWarner Losh<p> 11092e112e9d2SKyle EvansIn POSIX systems, 110938e3e3a7aSWarner Loshthis function also creates a file with that name, 110948e3e3a7aSWarner Loshto avoid security risks. 110958e3e3a7aSWarner Losh(Someone else might create the file with wrong permissions 110968e3e3a7aSWarner Loshin the time between getting the name and creating the file.) 110978e3e3a7aSWarner LoshYou still have to open the file to use it 110988e3e3a7aSWarner Loshand to remove it (even if you do not use it). 110998e3e3a7aSWarner Losh 111008e3e3a7aSWarner Losh 111018e3e3a7aSWarner Losh<p> 111028e3e3a7aSWarner LoshWhen possible, 111038e3e3a7aSWarner Loshyou may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, 111048e3e3a7aSWarner Loshwhich automatically removes the file when the program ends. 111058e3e3a7aSWarner Losh 111068e3e3a7aSWarner Losh 111078e3e3a7aSWarner Losh 111088e3e3a7aSWarner Losh 111098e3e3a7aSWarner Losh 111108e3e3a7aSWarner Losh 111118e3e3a7aSWarner Losh 111128e3e3a7aSWarner Losh<h2>6.10 – <a name="6.10">The Debug Library</a></h2> 111138e3e3a7aSWarner Losh 111148e3e3a7aSWarner Losh<p> 111158e3e3a7aSWarner LoshThis library provides 111160495ed39SKyle Evansthe functionality of the debug interface (<a href="#4.7">§4.7</a>) to Lua programs. 111178e3e3a7aSWarner LoshYou should exert care when using this library. 111188e3e3a7aSWarner LoshSeveral of its functions 111198e3e3a7aSWarner Loshviolate basic assumptions about Lua code 111208e3e3a7aSWarner Losh(e.g., that variables local to a function 111218e3e3a7aSWarner Loshcannot be accessed from outside; 111228e3e3a7aSWarner Loshthat userdata metatables cannot be changed by Lua code; 111238e3e3a7aSWarner Loshthat Lua programs do not crash) 111248e3e3a7aSWarner Loshand therefore can compromise otherwise secure code. 111258e3e3a7aSWarner LoshMoreover, some functions in this library may be slow. 111268e3e3a7aSWarner Losh 111278e3e3a7aSWarner Losh 111288e3e3a7aSWarner Losh<p> 111298e3e3a7aSWarner LoshAll functions in this library are provided 111308e3e3a7aSWarner Loshinside the <a name="pdf-debug"><code>debug</code></a> table. 111318e3e3a7aSWarner LoshAll functions that operate over a thread 111328e3e3a7aSWarner Loshhave an optional first argument which is the 111338e3e3a7aSWarner Loshthread to operate over. 111348e3e3a7aSWarner LoshThe default is always the current thread. 111358e3e3a7aSWarner Losh 111368e3e3a7aSWarner Losh 111378e3e3a7aSWarner Losh<p> 111388e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> 111398e3e3a7aSWarner Losh 111408e3e3a7aSWarner Losh 111418e3e3a7aSWarner Losh<p> 111428e3e3a7aSWarner LoshEnters an interactive mode with the user, 111438e3e3a7aSWarner Loshrunning each string that the user enters. 111448e3e3a7aSWarner LoshUsing simple commands and other debug facilities, 111458e3e3a7aSWarner Loshthe user can inspect global and local variables, 111468e3e3a7aSWarner Loshchange their values, evaluate expressions, and so on. 111478e3e3a7aSWarner LoshA line containing only the word <code>cont</code> finishes this function, 111488e3e3a7aSWarner Loshso that the caller continues its execution. 111498e3e3a7aSWarner Losh 111508e3e3a7aSWarner Losh 111518e3e3a7aSWarner Losh<p> 111528e3e3a7aSWarner LoshNote that commands for <code>debug.debug</code> are not lexically nested 111538e3e3a7aSWarner Loshwithin any function and so have no direct access to local variables. 111548e3e3a7aSWarner Losh 111558e3e3a7aSWarner Losh 111568e3e3a7aSWarner Losh 111578e3e3a7aSWarner Losh 111588e3e3a7aSWarner Losh<p> 111598e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> 111608e3e3a7aSWarner Losh 111618e3e3a7aSWarner Losh 111628e3e3a7aSWarner Losh<p> 111638e3e3a7aSWarner LoshReturns the current hook settings of the thread, as three values: 111648e3e3a7aSWarner Loshthe current hook function, the current hook mask, 111650495ed39SKyle Evansand the current hook count, 111660495ed39SKyle Evansas set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function. 111670495ed39SKyle Evans 111680495ed39SKyle Evans 111690495ed39SKyle Evans<p> 111700495ed39SKyle EvansReturns <b>fail</b> if there is no active hook. 111718e3e3a7aSWarner Losh 111728e3e3a7aSWarner Losh 111738e3e3a7aSWarner Losh 111748e3e3a7aSWarner Losh 111758e3e3a7aSWarner Losh<p> 111768e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> 111778e3e3a7aSWarner Losh 111788e3e3a7aSWarner Losh 111798e3e3a7aSWarner Losh<p> 111808e3e3a7aSWarner LoshReturns a table with information about a function. 111818e3e3a7aSWarner LoshYou can give the function directly 111828e3e3a7aSWarner Loshor you can give a number as the value of <code>f</code>, 111838e3e3a7aSWarner Loshwhich means the function running at level <code>f</code> of the call stack 111848e3e3a7aSWarner Loshof the given thread: 111858e3e3a7aSWarner Loshlevel 0 is the current function (<code>getinfo</code> itself); 111868e3e3a7aSWarner Loshlevel 1 is the function that called <code>getinfo</code> 111870495ed39SKyle Evans(except for tail calls, which do not count in the stack); 111888e3e3a7aSWarner Loshand so on. 111890495ed39SKyle EvansIf <code>f</code> is a number greater than the number of active functions, 111900495ed39SKyle Evansthen <code>getinfo</code> returns <b>fail</b>. 111918e3e3a7aSWarner Losh 111928e3e3a7aSWarner Losh 111938e3e3a7aSWarner Losh<p> 111948e3e3a7aSWarner LoshThe returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, 111958e3e3a7aSWarner Loshwith the string <code>what</code> describing which fields to fill in. 111968e3e3a7aSWarner LoshThe default for <code>what</code> is to get all information available, 111978e3e3a7aSWarner Loshexcept the table of valid lines. 111988e3e3a7aSWarner LoshIf present, 111998e3e3a7aSWarner Loshthe option '<code>f</code>' 112008e3e3a7aSWarner Loshadds a field named <code>func</code> with the function itself. 112018e3e3a7aSWarner LoshIf present, 112028e3e3a7aSWarner Loshthe option '<code>L</code>' 112038e3e3a7aSWarner Loshadds a field named <code>activelines</code> with the table of 112048e3e3a7aSWarner Loshvalid lines. 112058e3e3a7aSWarner Losh 112068e3e3a7aSWarner Losh 112078e3e3a7aSWarner Losh<p> 112088e3e3a7aSWarner LoshFor instance, the expression <code>debug.getinfo(1,"n").name</code> returns 112098e3e3a7aSWarner Losha name for the current function, 112108e3e3a7aSWarner Loshif a reasonable name can be found, 112118e3e3a7aSWarner Loshand the expression <code>debug.getinfo(print)</code> 112128e3e3a7aSWarner Loshreturns a table with all available information 112138e3e3a7aSWarner Loshabout the <a href="#pdf-print"><code>print</code></a> function. 112148e3e3a7aSWarner Losh 112158e3e3a7aSWarner Losh 112168e3e3a7aSWarner Losh 112178e3e3a7aSWarner Losh 112188e3e3a7aSWarner Losh<p> 112198e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3> 112208e3e3a7aSWarner Losh 112218e3e3a7aSWarner Losh 112228e3e3a7aSWarner Losh<p> 112238e3e3a7aSWarner LoshThis function returns the name and the value of the local variable 112248e3e3a7aSWarner Loshwith index <code>local</code> of the function at level <code>f</code> of the stack. 112258e3e3a7aSWarner LoshThis function accesses not only explicit local variables, 112260495ed39SKyle Evansbut also parameters and temporary values. 112278e3e3a7aSWarner Losh 112288e3e3a7aSWarner Losh 112298e3e3a7aSWarner Losh<p> 112308e3e3a7aSWarner LoshThe first parameter or local variable has index 1, and so on, 112318e3e3a7aSWarner Loshfollowing the order that they are declared in the code, 112328e3e3a7aSWarner Loshcounting only the variables that are active 112338e3e3a7aSWarner Loshin the current scope of the function. 112340495ed39SKyle EvansCompile-time constants may not appear in this listing, 112350495ed39SKyle Evansif they were optimized away by the compiler. 11236e112e9d2SKyle EvansNegative indices refer to vararg arguments; 11237e112e9d2SKyle Evans-1 is the first vararg argument. 112380495ed39SKyle EvansThe function returns <b>fail</b> 112390495ed39SKyle Evansif there is no variable with the given index, 112408e3e3a7aSWarner Loshand raises an error when called with a level out of range. 112418e3e3a7aSWarner Losh(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) 112428e3e3a7aSWarner Losh 112438e3e3a7aSWarner Losh 112448e3e3a7aSWarner Losh<p> 112458e3e3a7aSWarner LoshVariable names starting with '<code>(</code>' (open parenthesis) 112468e3e3a7aSWarner Loshrepresent variables with no known names 112478e3e3a7aSWarner Losh(internal variables such as loop control variables, 112488e3e3a7aSWarner Loshand variables from chunks saved without debug information). 112498e3e3a7aSWarner Losh 112508e3e3a7aSWarner Losh 112518e3e3a7aSWarner Losh<p> 112528e3e3a7aSWarner LoshThe parameter <code>f</code> may also be a function. 112538e3e3a7aSWarner LoshIn that case, <code>getlocal</code> returns only the name of function parameters. 112548e3e3a7aSWarner Losh 112558e3e3a7aSWarner Losh 112568e3e3a7aSWarner Losh 112578e3e3a7aSWarner Losh 112588e3e3a7aSWarner Losh<p> 112598e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3> 112608e3e3a7aSWarner Losh 112618e3e3a7aSWarner Losh 112628e3e3a7aSWarner Losh<p> 112638e3e3a7aSWarner LoshReturns the metatable of the given <code>value</code> 112648e3e3a7aSWarner Loshor <b>nil</b> if it does not have a metatable. 112658e3e3a7aSWarner Losh 112668e3e3a7aSWarner Losh 112678e3e3a7aSWarner Losh 112688e3e3a7aSWarner Losh 112698e3e3a7aSWarner Losh<p> 112708e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> 112718e3e3a7aSWarner Losh 112728e3e3a7aSWarner Losh 112738e3e3a7aSWarner Losh<p> 112740495ed39SKyle EvansReturns the registry table (see <a href="#4.3">§4.3</a>). 112758e3e3a7aSWarner Losh 112768e3e3a7aSWarner Losh 112778e3e3a7aSWarner Losh 112788e3e3a7aSWarner Losh 112798e3e3a7aSWarner Losh<p> 112808e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3> 112818e3e3a7aSWarner Losh 112828e3e3a7aSWarner Losh 112838e3e3a7aSWarner Losh<p> 112848e3e3a7aSWarner LoshThis function returns the name and the value of the upvalue 112858e3e3a7aSWarner Loshwith index <code>up</code> of the function <code>f</code>. 112860495ed39SKyle EvansThe function returns <b>fail</b> 112870495ed39SKyle Evansif there is no upvalue with the given index. 112888e3e3a7aSWarner Losh 112898e3e3a7aSWarner Losh 112908e3e3a7aSWarner Losh<p> 112910495ed39SKyle Evans(For Lua functions, 112920495ed39SKyle Evansupvalues are the external local variables that the function uses, 112930495ed39SKyle Evansand that are consequently included in its closure.) 112940495ed39SKyle Evans 112950495ed39SKyle Evans 112960495ed39SKyle Evans<p> 112970495ed39SKyle EvansFor C functions, this function uses the empty string <code>""</code> 112980495ed39SKyle Evansas a name for all upvalues. 112990495ed39SKyle Evans 113000495ed39SKyle Evans 113010495ed39SKyle Evans<p> 113020495ed39SKyle EvansVariable name '<code>?</code>' (interrogation mark) 113030495ed39SKyle Evansrepresents variables with no known names 113048e3e3a7aSWarner Losh(variables from chunks saved without debug information). 113058e3e3a7aSWarner Losh 113068e3e3a7aSWarner Losh 113078e3e3a7aSWarner Losh 113088e3e3a7aSWarner Losh 113098e3e3a7aSWarner Losh<p> 113100495ed39SKyle Evans<hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u, n)</code></a></h3> 113118e3e3a7aSWarner Losh 113128e3e3a7aSWarner Losh 113138e3e3a7aSWarner Losh<p> 113140495ed39SKyle EvansReturns the <code>n</code>-th user value associated 113150495ed39SKyle Evansto the userdata <code>u</code> plus a boolean, 113160495ed39SKyle Evans<b>false</b> if the userdata does not have that value. 113178e3e3a7aSWarner Losh 113188e3e3a7aSWarner Losh 113198e3e3a7aSWarner Losh 113208e3e3a7aSWarner Losh 113218e3e3a7aSWarner Losh<p> 113228e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> 113238e3e3a7aSWarner Losh 113248e3e3a7aSWarner Losh 113258e3e3a7aSWarner Losh<p> 113260495ed39SKyle EvansSets the given function as the debug hook. 113278e3e3a7aSWarner LoshThe string <code>mask</code> and the number <code>count</code> describe 113288e3e3a7aSWarner Loshwhen the hook will be called. 113298e3e3a7aSWarner LoshThe string mask may have any combination of the following characters, 113308e3e3a7aSWarner Loshwith the given meaning: 113318e3e3a7aSWarner Losh 113328e3e3a7aSWarner Losh<ul> 113338e3e3a7aSWarner Losh<li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li> 113348e3e3a7aSWarner Losh<li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li> 113358e3e3a7aSWarner Losh<li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li> 113368e3e3a7aSWarner Losh</ul><p> 113378e3e3a7aSWarner LoshMoreover, 113388e3e3a7aSWarner Loshwith a <code>count</code> different from zero, 113398e3e3a7aSWarner Loshthe hook is called also after every <code>count</code> instructions. 113408e3e3a7aSWarner Losh 113418e3e3a7aSWarner Losh 113428e3e3a7aSWarner Losh<p> 113438e3e3a7aSWarner LoshWhen called without arguments, 113448e3e3a7aSWarner Losh<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. 113458e3e3a7aSWarner Losh 113468e3e3a7aSWarner Losh 113478e3e3a7aSWarner Losh<p> 113480495ed39SKyle EvansWhen the hook is called, its first parameter is a string 113498e3e3a7aSWarner Loshdescribing the event that has triggered its call: 113500495ed39SKyle Evans<code>"call"</code>, <code>"tail call"</code>, <code>"return"</code>, 113518e3e3a7aSWarner Losh<code>"line"</code>, and <code>"count"</code>. 113528e3e3a7aSWarner LoshFor line events, 113538e3e3a7aSWarner Loshthe hook also gets the new line number as its second parameter. 113548e3e3a7aSWarner LoshInside a hook, 113558e3e3a7aSWarner Loshyou can call <code>getinfo</code> with level 2 to get more information about 113560495ed39SKyle Evansthe running function. 113570495ed39SKyle Evans(Level 0 is the <code>getinfo</code> function, 113580495ed39SKyle Evansand level 1 is the hook function.) 113598e3e3a7aSWarner Losh 113608e3e3a7aSWarner Losh 113618e3e3a7aSWarner Losh 113628e3e3a7aSWarner Losh 113638e3e3a7aSWarner Losh<p> 113648e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> 113658e3e3a7aSWarner Losh 113668e3e3a7aSWarner Losh 113678e3e3a7aSWarner Losh<p> 113688e3e3a7aSWarner LoshThis function assigns the value <code>value</code> to the local variable 113698e3e3a7aSWarner Loshwith index <code>local</code> of the function at level <code>level</code> of the stack. 113700495ed39SKyle EvansThe function returns <b>fail</b> if there is no local 113718e3e3a7aSWarner Loshvariable with the given index, 113728e3e3a7aSWarner Loshand raises an error when called with a <code>level</code> out of range. 113738e3e3a7aSWarner Losh(You can call <code>getinfo</code> to check whether the level is valid.) 113748e3e3a7aSWarner LoshOtherwise, it returns the name of the local variable. 113758e3e3a7aSWarner Losh 113768e3e3a7aSWarner Losh 113778e3e3a7aSWarner Losh<p> 113788e3e3a7aSWarner LoshSee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about 113798e3e3a7aSWarner Loshvariable indices and names. 113808e3e3a7aSWarner Losh 113818e3e3a7aSWarner Losh 113828e3e3a7aSWarner Losh 113838e3e3a7aSWarner Losh 113848e3e3a7aSWarner Losh<p> 113858e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> 113868e3e3a7aSWarner Losh 113878e3e3a7aSWarner Losh 113888e3e3a7aSWarner Losh<p> 113898e3e3a7aSWarner LoshSets the metatable for the given <code>value</code> to the given <code>table</code> 113908e3e3a7aSWarner Losh(which can be <b>nil</b>). 113918e3e3a7aSWarner LoshReturns <code>value</code>. 113928e3e3a7aSWarner Losh 113938e3e3a7aSWarner Losh 113948e3e3a7aSWarner Losh 113958e3e3a7aSWarner Losh 113968e3e3a7aSWarner Losh<p> 113978e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> 113988e3e3a7aSWarner Losh 113998e3e3a7aSWarner Losh 114008e3e3a7aSWarner Losh<p> 114018e3e3a7aSWarner LoshThis function assigns the value <code>value</code> to the upvalue 114028e3e3a7aSWarner Loshwith index <code>up</code> of the function <code>f</code>. 114030495ed39SKyle EvansThe function returns <b>fail</b> if there is no upvalue 114048e3e3a7aSWarner Loshwith the given index. 114058e3e3a7aSWarner LoshOtherwise, it returns the name of the upvalue. 114068e3e3a7aSWarner Losh 114078e3e3a7aSWarner Losh 114080495ed39SKyle Evans<p> 114090495ed39SKyle EvansSee <a href="#pdf-debug.getupvalue"><code>debug.getupvalue</code></a> for more information about upvalues. 114100495ed39SKyle Evans 114110495ed39SKyle Evans 114128e3e3a7aSWarner Losh 114138e3e3a7aSWarner Losh 114148e3e3a7aSWarner Losh<p> 114150495ed39SKyle Evans<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value, n)</code></a></h3> 114168e3e3a7aSWarner Losh 114178e3e3a7aSWarner Losh 114188e3e3a7aSWarner Losh<p> 114198e3e3a7aSWarner LoshSets the given <code>value</code> as 114200495ed39SKyle Evansthe <code>n</code>-th user value associated to the given <code>udata</code>. 114218e3e3a7aSWarner Losh<code>udata</code> must be a full userdata. 114228e3e3a7aSWarner Losh 114238e3e3a7aSWarner Losh 114248e3e3a7aSWarner Losh<p> 114250495ed39SKyle EvansReturns <code>udata</code>, 114260495ed39SKyle Evansor <b>fail</b> if the userdata does not have that value. 114278e3e3a7aSWarner Losh 114288e3e3a7aSWarner Losh 114298e3e3a7aSWarner Losh 114308e3e3a7aSWarner Losh 114318e3e3a7aSWarner Losh<p> 114328e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> 114338e3e3a7aSWarner Losh 114348e3e3a7aSWarner Losh 114358e3e3a7aSWarner Losh<p> 114368e3e3a7aSWarner LoshIf <code>message</code> is present but is neither a string nor <b>nil</b>, 114378e3e3a7aSWarner Loshthis function returns <code>message</code> without further processing. 114388e3e3a7aSWarner LoshOtherwise, 114398e3e3a7aSWarner Loshit returns a string with a traceback of the call stack. 114408e3e3a7aSWarner LoshThe optional <code>message</code> string is appended 114418e3e3a7aSWarner Loshat the beginning of the traceback. 114428e3e3a7aSWarner LoshAn optional <code>level</code> number tells at which level 114438e3e3a7aSWarner Loshto start the traceback 114448e3e3a7aSWarner Losh(default is 1, the function calling <code>traceback</code>). 114458e3e3a7aSWarner Losh 114468e3e3a7aSWarner Losh 114478e3e3a7aSWarner Losh 114488e3e3a7aSWarner Losh 114498e3e3a7aSWarner Losh<p> 114508e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3> 114518e3e3a7aSWarner Losh 114528e3e3a7aSWarner Losh 114538e3e3a7aSWarner Losh<p> 114548e3e3a7aSWarner LoshReturns a unique identifier (as a light userdata) 114558e3e3a7aSWarner Loshfor the upvalue numbered <code>n</code> 114568e3e3a7aSWarner Loshfrom the given function. 114578e3e3a7aSWarner Losh 114588e3e3a7aSWarner Losh 114598e3e3a7aSWarner Losh<p> 114608e3e3a7aSWarner LoshThese unique identifiers allow a program to check whether different 114618e3e3a7aSWarner Loshclosures share upvalues. 114628e3e3a7aSWarner LoshLua closures that share an upvalue 114638e3e3a7aSWarner Losh(that is, that access a same external local variable) 114648e3e3a7aSWarner Loshwill return identical ids for those upvalue indices. 114658e3e3a7aSWarner Losh 114668e3e3a7aSWarner Losh 114678e3e3a7aSWarner Losh 114688e3e3a7aSWarner Losh 114698e3e3a7aSWarner Losh<p> 114708e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3> 114718e3e3a7aSWarner Losh 114728e3e3a7aSWarner Losh 114738e3e3a7aSWarner Losh<p> 114748e3e3a7aSWarner LoshMake the <code>n1</code>-th upvalue of the Lua closure <code>f1</code> 114758e3e3a7aSWarner Loshrefer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>. 114768e3e3a7aSWarner Losh 114778e3e3a7aSWarner Losh 114788e3e3a7aSWarner Losh 114798e3e3a7aSWarner Losh 114808e3e3a7aSWarner Losh 114818e3e3a7aSWarner Losh 114828e3e3a7aSWarner Losh 114838e3e3a7aSWarner Losh<h1>7 – <a name="7">Lua Standalone</a></h1> 114848e3e3a7aSWarner Losh 114858e3e3a7aSWarner Losh<p> 114868e3e3a7aSWarner LoshAlthough Lua has been designed as an extension language, 114878e3e3a7aSWarner Loshto be embedded in a host C program, 114888e3e3a7aSWarner Loshit is also frequently used as a standalone language. 114898e3e3a7aSWarner LoshAn interpreter for Lua as a standalone language, 114908e3e3a7aSWarner Loshcalled simply <code>lua</code>, 114918e3e3a7aSWarner Loshis provided with the standard distribution. 114928e3e3a7aSWarner LoshThe standalone interpreter includes 114930495ed39SKyle Evansall standard libraries. 114948e3e3a7aSWarner LoshIts usage is: 114958e3e3a7aSWarner Losh 114968e3e3a7aSWarner Losh<pre> 114978e3e3a7aSWarner Losh lua [options] [script [args]] 114988e3e3a7aSWarner Losh</pre><p> 114998e3e3a7aSWarner LoshThe options are: 115008e3e3a7aSWarner Losh 115018e3e3a7aSWarner Losh<ul> 115020495ed39SKyle Evans<li><b><code>-e <em>stat</em></code>: </b> execute string <em>stat</em>;</li> 115030495ed39SKyle Evans<li><b><code>-i</code>: </b> enter interactive mode after running <em>script</em>;</li> 115040495ed39SKyle Evans<li><b><code>-l <em>mod</em></code>: </b> "require" <em>mod</em> and assign the 115050495ed39SKyle Evans result to global <em>mod</em>;</li> 115060495ed39SKyle Evans<li><b><code>-v</code>: </b> print version information;</li> 115070495ed39SKyle Evans<li><b><code>-E</code>: </b> ignore environment variables;</li> 115080495ed39SKyle Evans<li><b><code>-W</code>: </b> turn warnings on;</li> 115090495ed39SKyle Evans<li><b><code>--</code>: </b> stop handling options;</li> 115100495ed39SKyle Evans<li><b><code>-</code>: </b> execute <code>stdin</code> as a file and stop handling options.</li> 115118e3e3a7aSWarner Losh</ul><p> 115128e3e3a7aSWarner LoshAfter handling its options, <code>lua</code> runs the given <em>script</em>. 115138e3e3a7aSWarner LoshWhen called without arguments, 115148e3e3a7aSWarner Losh<code>lua</code> behaves as <code>lua -v -i</code> 115158e3e3a7aSWarner Loshwhen the standard input (<code>stdin</code>) is a terminal, 115168e3e3a7aSWarner Loshand as <code>lua -</code> otherwise. 115178e3e3a7aSWarner Losh 115188e3e3a7aSWarner Losh 115198e3e3a7aSWarner Losh<p> 115200495ed39SKyle EvansWhen called without the option <code>-E</code>, 115210495ed39SKyle Evansthe interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_4"><code>LUA_INIT_5_4</code></a> 115228e3e3a7aSWarner Losh(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined) 115238e3e3a7aSWarner Loshbefore running any argument. 115248e3e3a7aSWarner LoshIf the variable content has the format <code>@<em>filename</em></code>, 115258e3e3a7aSWarner Loshthen <code>lua</code> executes the file. 115268e3e3a7aSWarner LoshOtherwise, <code>lua</code> executes the string itself. 115278e3e3a7aSWarner Losh 115288e3e3a7aSWarner Losh 115298e3e3a7aSWarner Losh<p> 115300495ed39SKyle EvansWhen called with the option <code>-E</code>, 115310495ed39SKyle EvansLua does not consult any environment variables. 115320495ed39SKyle EvansIn particular, 115330495ed39SKyle Evansthe values of <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a> 115340495ed39SKyle Evansare set with the default paths defined in <code>luaconf.h</code>. 115358e3e3a7aSWarner Losh 115368e3e3a7aSWarner Losh 115378e3e3a7aSWarner Losh<p> 115380495ed39SKyle EvansThe options <code>-e</code>, <code>-l</code>, and <code>-W</code> are handled in 115390495ed39SKyle Evansthe order they appear. 115408e3e3a7aSWarner LoshFor instance, an invocation like 115418e3e3a7aSWarner Losh 115428e3e3a7aSWarner Losh<pre> 115430495ed39SKyle Evans $ lua -e 'a=1' -llib1 script.lua 115448e3e3a7aSWarner Losh</pre><p> 115450495ed39SKyle Evanswill first set <code>a</code> to 1, then require the library <code>lib1</code>, 115468e3e3a7aSWarner Loshand finally run the file <code>script.lua</code> with no arguments. 115478e3e3a7aSWarner Losh(Here <code>$</code> is the shell prompt. Your prompt may be different.) 115488e3e3a7aSWarner Losh 115498e3e3a7aSWarner Losh 115508e3e3a7aSWarner Losh<p> 115518e3e3a7aSWarner LoshBefore running any code, 115528e3e3a7aSWarner Losh<code>lua</code> collects all command-line arguments 115538e3e3a7aSWarner Loshin a global table called <code>arg</code>. 115548e3e3a7aSWarner LoshThe script name goes to index 0, 115558e3e3a7aSWarner Loshthe first argument after the script name goes to index 1, 115568e3e3a7aSWarner Loshand so on. 115578e3e3a7aSWarner LoshAny arguments before the script name 115588e3e3a7aSWarner Losh(that is, the interpreter name plus its options) 115598e3e3a7aSWarner Loshgo to negative indices. 115608e3e3a7aSWarner LoshFor instance, in the call 115618e3e3a7aSWarner Losh 115628e3e3a7aSWarner Losh<pre> 115638e3e3a7aSWarner Losh $ lua -la b.lua t1 t2 115648e3e3a7aSWarner Losh</pre><p> 115658e3e3a7aSWarner Loshthe table is like this: 115668e3e3a7aSWarner Losh 115678e3e3a7aSWarner Losh<pre> 115688e3e3a7aSWarner Losh arg = { [-2] = "lua", [-1] = "-la", 115698e3e3a7aSWarner Losh [0] = "b.lua", 115708e3e3a7aSWarner Losh [1] = "t1", [2] = "t2" } 115718e3e3a7aSWarner Losh</pre><p> 115728e3e3a7aSWarner LoshIf there is no script in the call, 115738e3e3a7aSWarner Loshthe interpreter name goes to index 0, 115748e3e3a7aSWarner Loshfollowed by the other arguments. 115758e3e3a7aSWarner LoshFor instance, the call 115768e3e3a7aSWarner Losh 115778e3e3a7aSWarner Losh<pre> 115788e3e3a7aSWarner Losh $ lua -e "print(arg[1])" 115798e3e3a7aSWarner Losh</pre><p> 115808e3e3a7aSWarner Loshwill print "<code>-e</code>". 115818e3e3a7aSWarner LoshIf there is a script, 11582e112e9d2SKyle Evansthe script is called with arguments 115838e3e3a7aSWarner Losh<code>arg[1]</code>, ···, <code>arg[#arg]</code>. 115840495ed39SKyle EvansLike all chunks in Lua, 115850495ed39SKyle Evansthe script is compiled as a vararg function. 115868e3e3a7aSWarner Losh 115878e3e3a7aSWarner Losh 115888e3e3a7aSWarner Losh<p> 115898e3e3a7aSWarner LoshIn interactive mode, 115908e3e3a7aSWarner LoshLua repeatedly prompts and waits for a line. 115918e3e3a7aSWarner LoshAfter reading a line, 115928e3e3a7aSWarner LoshLua first try to interpret the line as an expression. 115938e3e3a7aSWarner LoshIf it succeeds, it prints its value. 115948e3e3a7aSWarner LoshOtherwise, it interprets the line as a statement. 115958e3e3a7aSWarner LoshIf you write an incomplete statement, 115968e3e3a7aSWarner Loshthe interpreter waits for its completion 115978e3e3a7aSWarner Loshby issuing a different prompt. 115988e3e3a7aSWarner Losh 115998e3e3a7aSWarner Losh 116008e3e3a7aSWarner Losh<p> 116018e3e3a7aSWarner LoshIf the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, 116028e3e3a7aSWarner Loshthen its value is used as the prompt. 116038e3e3a7aSWarner LoshSimilarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, 116048e3e3a7aSWarner Loshits value is used as the secondary prompt 116058e3e3a7aSWarner Losh(issued during incomplete statements). 116068e3e3a7aSWarner Losh 116078e3e3a7aSWarner Losh 116088e3e3a7aSWarner Losh<p> 116098e3e3a7aSWarner LoshIn case of unprotected errors in the script, 116108e3e3a7aSWarner Loshthe interpreter reports the error to the standard error stream. 116118e3e3a7aSWarner LoshIf the error object is not a string but 116128e3e3a7aSWarner Loshhas a metamethod <code>__tostring</code>, 116138e3e3a7aSWarner Loshthe interpreter calls this metamethod to produce the final message. 116148e3e3a7aSWarner LoshOtherwise, the interpreter converts the error object to a string 116158e3e3a7aSWarner Loshand adds a stack traceback to it. 116160495ed39SKyle EvansWhen warnings are on, 116170495ed39SKyle Evansthey are simply printed in the standard error output. 116188e3e3a7aSWarner Losh 116198e3e3a7aSWarner Losh 116208e3e3a7aSWarner Losh<p> 116218e3e3a7aSWarner LoshWhen finishing normally, 116228e3e3a7aSWarner Loshthe interpreter closes its main Lua state 116238e3e3a7aSWarner Losh(see <a href="#lua_close"><code>lua_close</code></a>). 116248e3e3a7aSWarner LoshThe script can avoid this step by 116258e3e3a7aSWarner Loshcalling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate. 116268e3e3a7aSWarner Losh 116278e3e3a7aSWarner Losh 116288e3e3a7aSWarner Losh<p> 116298e3e3a7aSWarner LoshTo allow the use of Lua as a 116308e3e3a7aSWarner Loshscript interpreter in Unix systems, 116310495ed39SKyle EvansLua skips the first line of a file chunk if it starts with <code>#</code>. 116328e3e3a7aSWarner LoshTherefore, Lua scripts can be made into executable programs 116338e3e3a7aSWarner Loshby using <code>chmod +x</code> and the <code>#!</code> form, 116348e3e3a7aSWarner Loshas in 116358e3e3a7aSWarner Losh 116368e3e3a7aSWarner Losh<pre> 116378e3e3a7aSWarner Losh #!/usr/local/bin/lua 116388e3e3a7aSWarner Losh</pre><p> 116390495ed39SKyle EvansOf course, 116408e3e3a7aSWarner Loshthe location of the Lua interpreter may be different in your machine. 116418e3e3a7aSWarner LoshIf <code>lua</code> is in your <code>PATH</code>, 116428e3e3a7aSWarner Loshthen 116438e3e3a7aSWarner Losh 116448e3e3a7aSWarner Losh<pre> 116458e3e3a7aSWarner Losh #!/usr/bin/env lua 116468e3e3a7aSWarner Losh</pre><p> 116470495ed39SKyle Evansis a more portable solution. 116488e3e3a7aSWarner Losh 116498e3e3a7aSWarner Losh 116508e3e3a7aSWarner Losh 116518e3e3a7aSWarner Losh<h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> 116528e3e3a7aSWarner Losh 116530495ed39SKyle Evans 116540495ed39SKyle Evans 116558e3e3a7aSWarner Losh<p> 116568e3e3a7aSWarner LoshHere we list the incompatibilities that you may find when moving a program 116570495ed39SKyle Evansfrom Lua 5.3 to Lua 5.4. 116580495ed39SKyle Evans 116590495ed39SKyle Evans 116600495ed39SKyle Evans<p> 116618e3e3a7aSWarner LoshYou can avoid some incompatibilities by compiling Lua with 116628e3e3a7aSWarner Loshappropriate options (see file <code>luaconf.h</code>). 116638e3e3a7aSWarner LoshHowever, 116648e3e3a7aSWarner Loshall these compatibility options will be removed in the future. 116650495ed39SKyle EvansMore often than not, 116660495ed39SKyle Evanscompatibility issues arise when these compatibility options 116670495ed39SKyle Evansare removed. 116680495ed39SKyle EvansSo, whenever you have the chance, 116690495ed39SKyle Evansyou should try to test your code with a version of Lua compiled 116700495ed39SKyle Evanswith all compatibility options turned off. 116710495ed39SKyle EvansThat will ease transitions to newer versions of Lua. 116728e3e3a7aSWarner Losh 116738e3e3a7aSWarner Losh 116748e3e3a7aSWarner Losh<p> 116758e3e3a7aSWarner LoshLua versions can always change the C API in ways that 116768e3e3a7aSWarner Loshdo not imply source-code changes in a program, 116778e3e3a7aSWarner Loshsuch as the numeric values for constants 116788e3e3a7aSWarner Loshor the implementation of functions as macros. 116798e3e3a7aSWarner LoshTherefore, 116800495ed39SKyle Evansyou should never assume that binaries are compatible between 116818e3e3a7aSWarner Loshdifferent Lua versions. 116828e3e3a7aSWarner LoshAlways recompile clients of the Lua API when 116838e3e3a7aSWarner Loshusing a new version. 116848e3e3a7aSWarner Losh 116858e3e3a7aSWarner Losh 116868e3e3a7aSWarner Losh<p> 116878e3e3a7aSWarner LoshSimilarly, Lua versions can always change the internal representation 116888e3e3a7aSWarner Loshof precompiled chunks; 116898e3e3a7aSWarner Loshprecompiled chunks are not compatible between different Lua versions. 116908e3e3a7aSWarner Losh 116918e3e3a7aSWarner Losh 116928e3e3a7aSWarner Losh<p> 116938e3e3a7aSWarner LoshThe standard paths in the official distribution may 116948e3e3a7aSWarner Loshchange between versions. 116958e3e3a7aSWarner Losh 116968e3e3a7aSWarner Losh 116978e3e3a7aSWarner Losh 116980495ed39SKyle Evans 116990495ed39SKyle Evans 117000495ed39SKyle Evans<h2>8.1 – <a name="8.1">Incompatibilities in the Language</a></h2> 117018e3e3a7aSWarner Losh<ul> 117028e3e3a7aSWarner Losh 117038e3e3a7aSWarner Losh<li> 117040495ed39SKyle EvansThe coercion of strings to numbers in 117050495ed39SKyle Evansarithmetic and bitwise operations 117060495ed39SKyle Evanshas been removed from the core language. 117070495ed39SKyle EvansThe string library does a similar job 117080495ed39SKyle Evansfor arithmetic (but not for bitwise) operations 117090495ed39SKyle Evansusing the string metamethods. 117100495ed39SKyle EvansHowever, unlike in previous versions, 117110495ed39SKyle Evansthe new implementation preserves the implicit type of the numeral 117120495ed39SKyle Evansin the string. 117130495ed39SKyle EvansFor instance, the result of <code>"1" + "2"</code> now is an integer, 117140495ed39SKyle Evansnot a float. 117158e3e3a7aSWarner Losh</li> 117168e3e3a7aSWarner Losh 117178e3e3a7aSWarner Losh<li> 117180495ed39SKyle EvansLiteral decimal integer constants that overflow are read as floats, 117190495ed39SKyle Evansinstead of wrapping around. 117200495ed39SKyle EvansYou can use hexadecimal notation for such constants if you 117210495ed39SKyle Evanswant the old behavior 117220495ed39SKyle Evans(reading them as integers with wrap around). 117238e3e3a7aSWarner Losh</li> 117248e3e3a7aSWarner Losh 117258e3e3a7aSWarner Losh<li> 117260495ed39SKyle EvansThe use of the <code>__lt</code> metamethod to emulate <code>__le</code> 117270495ed39SKyle Evanshas been removed. 117280495ed39SKyle EvansWhen needed, this metamethod must be explicitly defined. 117290495ed39SKyle Evans</li> 117300495ed39SKyle Evans 117310495ed39SKyle Evans<li> 117320495ed39SKyle EvansThe semantics of the numerical <b>for</b> loop 117330495ed39SKyle Evansover integers changed in some details. 117340495ed39SKyle EvansIn particular, the control variable never wraps around. 117350495ed39SKyle Evans</li> 117360495ed39SKyle Evans 117370495ed39SKyle Evans<li> 117380495ed39SKyle EvansA label for a <b>goto</b> cannot be declared where a label with the same 117390495ed39SKyle Evansname is visible, even if this other label is declared in an enclosing 117400495ed39SKyle Evansblock. 117410495ed39SKyle Evans</li> 117420495ed39SKyle Evans 117430495ed39SKyle Evans<li> 117440495ed39SKyle EvansWhen finalizing an object, 117450495ed39SKyle EvansLua does not ignore <code>__gc</code> metamethods that are not functions. 117460495ed39SKyle EvansAny value will be called, if present. 117470495ed39SKyle Evans(Non-callable values will generate a warning, 117480495ed39SKyle Evanslike any other error when calling a finalizer.) 117498e3e3a7aSWarner Losh</li> 117508e3e3a7aSWarner Losh 117518e3e3a7aSWarner Losh</ul> 117528e3e3a7aSWarner Losh 117538e3e3a7aSWarner Losh 117548e3e3a7aSWarner Losh 117558e3e3a7aSWarner Losh 117560495ed39SKyle Evans<h2>8.2 – <a name="8.2">Incompatibilities in the Libraries</a></h2> 117578e3e3a7aSWarner Losh<ul> 117588e3e3a7aSWarner Losh 117598e3e3a7aSWarner Losh<li> 117600495ed39SKyle EvansThe function <a href="#pdf-print"><code>print</code></a> does not call <a href="#pdf-tostring"><code>tostring</code></a> 117610495ed39SKyle Evansto format its arguments; 117620495ed39SKyle Evansinstead, it has this functionality hardwired. 117630495ed39SKyle EvansYou should use <code>__tostring</code> to modify how values are printed. 117648e3e3a7aSWarner Losh</li> 117658e3e3a7aSWarner Losh 117668e3e3a7aSWarner Losh<li> 117670495ed39SKyle EvansThe pseudo-random number generator used by the function <a href="#pdf-math.random"><code>math.random</code></a> 117680495ed39SKyle Evansnow starts with a somewhat random seed. 117690495ed39SKyle EvansMoreover, it uses a different algorithm. 117708e3e3a7aSWarner Losh</li> 117718e3e3a7aSWarner Losh 117728e3e3a7aSWarner Losh<li> 117730495ed39SKyle EvansBy default, the decoding functions in the <a href="#pdf-utf8"><code>utf8</code></a> library 117740495ed39SKyle Evansdo not accept surrogates as valid code points. 117750495ed39SKyle EvansAn extra parameter in these functions makes them more permissive. 117768e3e3a7aSWarner Losh</li> 117778e3e3a7aSWarner Losh 117788e3e3a7aSWarner Losh<li> 117790495ed39SKyle EvansThe options "<code>setpause</code>" and "<code>setstepmul</code>" 117800495ed39SKyle Evansof the function <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> are deprecated. 117810495ed39SKyle EvansYou should use the new option "<code>incremental</code>" to set them. 117828e3e3a7aSWarner Losh</li> 117838e3e3a7aSWarner Losh 117848e3e3a7aSWarner Losh<li> 117850495ed39SKyle EvansThe function <a href="#pdf-io.lines"><code>io.lines</code></a> now returns four values, 117860495ed39SKyle Evansinstead of just one. 117870495ed39SKyle EvansThat can be a problem when it is used as the sole 117880495ed39SKyle Evansargument to another function that has optional parameters, 117890495ed39SKyle Evanssuch as in <code>load(io.lines(filename, "L"))</code>. 117900495ed39SKyle EvansTo fix that issue, 117910495ed39SKyle Evansyou can wrap the call into parentheses, 117920495ed39SKyle Evansto adjust its number of results to one. 117938e3e3a7aSWarner Losh</li> 117948e3e3a7aSWarner Losh 117958e3e3a7aSWarner Losh</ul> 117968e3e3a7aSWarner Losh 117978e3e3a7aSWarner Losh 117988e3e3a7aSWarner Losh 117998e3e3a7aSWarner Losh 118000495ed39SKyle Evans<h2>8.3 – <a name="8.3">Incompatibilities in the API</a></h2> 118018e3e3a7aSWarner Losh 118028e3e3a7aSWarner Losh 118038e3e3a7aSWarner Losh<ul> 118048e3e3a7aSWarner Losh 118058e3e3a7aSWarner Losh<li> 118060495ed39SKyle EvansFull userdata now has an arbitrary number of associated user values. 118070495ed39SKyle EvansTherefore, the functions <code>lua_newuserdata</code>, 118080495ed39SKyle Evans<code>lua_setuservalue</code>, and <code>lua_getuservalue</code> were 118090495ed39SKyle Evansreplaced by <a href="#lua_newuserdatauv"><code>lua_newuserdatauv</code></a>, 118100495ed39SKyle Evans<a href="#lua_setiuservalue"><code>lua_setiuservalue</code></a>, and <a href="#lua_getiuservalue"><code>lua_getiuservalue</code></a>, 118110495ed39SKyle Evanswhich have an extra argument. 118120495ed39SKyle Evans 118130495ed39SKyle Evans 118140495ed39SKyle Evans<p> 118150495ed39SKyle EvansFor compatibility, the old names still work as macros assuming 118160495ed39SKyle Evansone single user value. 118170495ed39SKyle EvansNote, however, that userdata with zero user values 118180495ed39SKyle Evansare more efficient memory-wise. 118198e3e3a7aSWarner Losh</li> 118208e3e3a7aSWarner Losh 118218e3e3a7aSWarner Losh<li> 118220495ed39SKyle EvansThe function <a href="#lua_resume"><code>lua_resume</code></a> has an extra parameter. 118230495ed39SKyle EvansThis out parameter returns the number of values on 118240495ed39SKyle Evansthe top of the stack that were yielded or returned by the coroutine. 118250495ed39SKyle Evans(In previous versions, 118260495ed39SKyle Evansthose values were the entire stack.) 118278e3e3a7aSWarner Losh</li> 118288e3e3a7aSWarner Losh 118298e3e3a7aSWarner Losh<li> 118300495ed39SKyle EvansThe function <a href="#lua_version"><code>lua_version</code></a> returns the version number, 118310495ed39SKyle Evansinstead of an address of the version number. 118320495ed39SKyle EvansThe Lua core should work correctly with libraries using their 118330495ed39SKyle Evansown static copies of the same core, 118340495ed39SKyle Evansso there is no need to check whether they are using the same 118350495ed39SKyle Evansaddress space. 118368e3e3a7aSWarner Losh</li> 118378e3e3a7aSWarner Losh 118388e3e3a7aSWarner Losh<li> 118390495ed39SKyle EvansThe constant <code>LUA_ERRGCMM</code> was removed. 118400495ed39SKyle EvansErrors in finalizers are never propagated; 118410495ed39SKyle Evansinstead, they generate a warning. 118420495ed39SKyle Evans</li> 118430495ed39SKyle Evans 118440495ed39SKyle Evans<li> 118450495ed39SKyle EvansThe options <code>LUA_GCSETPAUSE</code> and <code>LUA_GCSETSTEPMUL</code> 118460495ed39SKyle Evansof the function <a href="#lua_gc"><code>lua_gc</code></a> are deprecated. 118470495ed39SKyle EvansYou should use the new option <code>LUA_GCINC</code> to set them. 118488e3e3a7aSWarner Losh</li> 118498e3e3a7aSWarner Losh 118508e3e3a7aSWarner Losh</ul> 118518e3e3a7aSWarner Losh 118528e3e3a7aSWarner Losh 118538e3e3a7aSWarner Losh 118548e3e3a7aSWarner Losh 118558e3e3a7aSWarner Losh<h1>9 – <a name="9">The Complete Syntax of Lua</a></h1> 118568e3e3a7aSWarner Losh 118578e3e3a7aSWarner Losh<p> 118588e3e3a7aSWarner LoshHere is the complete syntax of Lua in extended BNF. 118598e3e3a7aSWarner LoshAs usual in extended BNF, 118608e3e3a7aSWarner Losh{A} means 0 or more As, 118618e3e3a7aSWarner Loshand [A] means an optional A. 118628e3e3a7aSWarner Losh(For operator precedences, see <a href="#3.4.8">§3.4.8</a>; 118638e3e3a7aSWarner Loshfor a description of the terminals 118648e3e3a7aSWarner LoshName, Numeral, 118658e3e3a7aSWarner Loshand LiteralString, see <a href="#3.1">§3.1</a>.) 118668e3e3a7aSWarner Losh 118678e3e3a7aSWarner Losh 118688e3e3a7aSWarner Losh 118698e3e3a7aSWarner Losh 118708e3e3a7aSWarner Losh<pre> 118718e3e3a7aSWarner Losh 118728e3e3a7aSWarner Losh chunk ::= block 118738e3e3a7aSWarner Losh 118748e3e3a7aSWarner Losh block ::= {stat} [retstat] 118758e3e3a7aSWarner Losh 118768e3e3a7aSWarner Losh stat ::= ‘<b>;</b>’ | 118778e3e3a7aSWarner Losh varlist ‘<b>=</b>’ explist | 118788e3e3a7aSWarner Losh functioncall | 118798e3e3a7aSWarner Losh label | 118808e3e3a7aSWarner Losh <b>break</b> | 118818e3e3a7aSWarner Losh <b>goto</b> Name | 118828e3e3a7aSWarner Losh <b>do</b> block <b>end</b> | 118838e3e3a7aSWarner Losh <b>while</b> exp <b>do</b> block <b>end</b> | 118848e3e3a7aSWarner Losh <b>repeat</b> block <b>until</b> exp | 118858e3e3a7aSWarner Losh <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 118868e3e3a7aSWarner Losh <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> | 118878e3e3a7aSWarner Losh <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 118888e3e3a7aSWarner Losh <b>function</b> funcname funcbody | 118898e3e3a7aSWarner Losh <b>local</b> <b>function</b> Name funcbody | 118900495ed39SKyle Evans <b>local</b> attnamelist [‘<b>=</b>’ explist] 118910495ed39SKyle Evans 118920495ed39SKyle Evans attnamelist ::= Name attrib {‘<b>,</b>’ Name attrib} 118930495ed39SKyle Evans 118940495ed39SKyle Evans attrib ::= [‘<b><</b>’ Name ‘<b>></b>’] 118958e3e3a7aSWarner Losh 118968e3e3a7aSWarner Losh retstat ::= <b>return</b> [explist] [‘<b>;</b>’] 118978e3e3a7aSWarner Losh 118988e3e3a7aSWarner Losh label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 118998e3e3a7aSWarner Losh 119008e3e3a7aSWarner Losh funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 119018e3e3a7aSWarner Losh 119028e3e3a7aSWarner Losh varlist ::= var {‘<b>,</b>’ var} 119038e3e3a7aSWarner Losh 119048e3e3a7aSWarner Losh var ::= Name | prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | prefixexp ‘<b>.</b>’ Name 119058e3e3a7aSWarner Losh 119068e3e3a7aSWarner Losh namelist ::= Name {‘<b>,</b>’ Name} 119078e3e3a7aSWarner Losh 119088e3e3a7aSWarner Losh explist ::= exp {‘<b>,</b>’ exp} 119098e3e3a7aSWarner Losh 119108e3e3a7aSWarner Losh exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | ‘<b>...</b>’ | functiondef | 119118e3e3a7aSWarner Losh prefixexp | tableconstructor | exp binop exp | unop exp 119128e3e3a7aSWarner Losh 119138e3e3a7aSWarner Losh prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 119148e3e3a7aSWarner Losh 119158e3e3a7aSWarner Losh functioncall ::= prefixexp args | prefixexp ‘<b>:</b>’ Name args 119168e3e3a7aSWarner Losh 119178e3e3a7aSWarner Losh args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | tableconstructor | LiteralString 119188e3e3a7aSWarner Losh 119198e3e3a7aSWarner Losh functiondef ::= <b>function</b> funcbody 119208e3e3a7aSWarner Losh 119218e3e3a7aSWarner Losh funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 119228e3e3a7aSWarner Losh 119238e3e3a7aSWarner Losh parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 119248e3e3a7aSWarner Losh 119258e3e3a7aSWarner Losh tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 119268e3e3a7aSWarner Losh 119278e3e3a7aSWarner Losh fieldlist ::= field {fieldsep field} [fieldsep] 119288e3e3a7aSWarner Losh 119298e3e3a7aSWarner Losh field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 119308e3e3a7aSWarner Losh 119318e3e3a7aSWarner Losh fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 119328e3e3a7aSWarner Losh 119338e3e3a7aSWarner Losh binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</b>’ | ‘<b>//</b>’ | ‘<b>^</b>’ | ‘<b>%</b>’ | 119348e3e3a7aSWarner Losh ‘<b>&</b>’ | ‘<b>~</b>’ | ‘<b>|</b>’ | ‘<b>>></b>’ | ‘<b><<</b>’ | ‘<b>..</b>’ | 119358e3e3a7aSWarner Losh ‘<b><</b>’ | ‘<b><=</b>’ | ‘<b>></b>’ | ‘<b>>=</b>’ | ‘<b>==</b>’ | ‘<b>~=</b>’ | 119368e3e3a7aSWarner Losh <b>and</b> | <b>or</b> 119378e3e3a7aSWarner Losh 119388e3e3a7aSWarner Losh unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’ | ‘<b>~</b>’ 119398e3e3a7aSWarner Losh 119408e3e3a7aSWarner Losh</pre> 119418e3e3a7aSWarner Losh 119428e3e3a7aSWarner Losh<p> 119438e3e3a7aSWarner Losh 119448e3e3a7aSWarner Losh 119458e3e3a7aSWarner Losh 119468e3e3a7aSWarner Losh 119478e3e3a7aSWarner Losh 119488e3e3a7aSWarner Losh 119498e3e3a7aSWarner Losh 119508e3e3a7aSWarner Losh<P CLASS="footer"> 119518e3e3a7aSWarner LoshLast update: 11952*8c784bb8SWarner LoshThu Jan 13 11:33:16 UTC 2022 119538e3e3a7aSWarner Losh</P> 119548e3e3a7aSWarner Losh<!-- 11955*8c784bb8SWarner LoshLast change: revised for Lua 5.4.4 119568e3e3a7aSWarner Losh--> 119578e3e3a7aSWarner Losh 119588e3e3a7aSWarner Losh</body></html> 119598e3e3a7aSWarner Losh 11960
