xref: /freebsd/contrib/lua/doc/manual.html (revision 3068d706eabe99f930fb01d3cbfd74ff1f0eb5a2) 
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>
13*3068d706SWarner Losh<A HREF="https://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*3068d706SWarner LoshCopyright &copy; 2020&ndash;2025 Lua.org, PUC-Rio.
238e3e3a7aSWarner LoshFreely available under the terms of the
24*3068d706SWarner Losh<a href="https://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&middot;
308e3e3a7aSWarner Losh<A HREF="contents.html#index">index</A>
318e3e3a7aSWarner Losh&middot;
32*3068d706SWarner Losh<A HREF="https://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 &ndash; <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>,
66a9490b81SWarner Loshthe common subset of standard&nbsp;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&nbsp;functions to be called by Lua code.
848e3e3a7aSWarner LoshThrough the use of C&nbsp;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 &ndash; <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 &ndash; <a name="2.1">Values and Types</a></h2>
1198e3e3a7aSWarner Losh
1208e3e3a7aSWarner Losh<p>
1210495ed39SKyle EvansLua is a dynamically typed language.
1228e3e3a7aSWarner LoshThis means that
1238e3e3a7aSWarner Loshvariables do not have types; only values do.
1248e3e3a7aSWarner LoshThere are no type definitions in the language.
1258e3e3a7aSWarner LoshAll values carry their own type.
1268e3e3a7aSWarner Losh
1278e3e3a7aSWarner Losh
1288e3e3a7aSWarner Losh<p>
1290495ed39SKyle EvansAll values in Lua are first-class values.
1308e3e3a7aSWarner LoshThis means that all values can be stored in variables,
1318e3e3a7aSWarner Loshpassed as arguments to other functions, and returned as results.
1328e3e3a7aSWarner Losh
1338e3e3a7aSWarner Losh
1348e3e3a7aSWarner Losh<p>
1358e3e3a7aSWarner LoshThere are eight basic types in Lua:
1368e3e3a7aSWarner Losh<em>nil</em>, <em>boolean</em>, <em>number</em>,
1378e3e3a7aSWarner Losh<em>string</em>, <em>function</em>, <em>userdata</em>,
1388e3e3a7aSWarner Losh<em>thread</em>, and <em>table</em>.
1398e3e3a7aSWarner LoshThe type <em>nil</em> has one single value, <b>nil</b>,
1408e3e3a7aSWarner Loshwhose main property is to be different from any other value;
1410495ed39SKyle Evansit often represents the absence of a useful value.
1428e3e3a7aSWarner LoshThe type <em>boolean</em> has two values, <b>false</b> and <b>true</b>.
1438e3e3a7aSWarner LoshBoth <b>nil</b> and <b>false</b> make a condition false;
1440495ed39SKyle Evansthey are collectively called <em>false values</em>.
1450495ed39SKyle EvansAny other value makes a condition true.
1468c784bb8SWarner LoshDespite its name,
1478c784bb8SWarner Losh<b>false</b> is frequently used as an alternative to <b>nil</b>,
1488c784bb8SWarner Loshwith the key difference that <b>false</b> behaves
1498c784bb8SWarner Loshlike a regular value in a table,
1508c784bb8SWarner Loshwhile a <b>nil</b> in a table represents an absent key.
1518e3e3a7aSWarner Losh
1528e3e3a7aSWarner Losh
1538e3e3a7aSWarner Losh<p>
1540495ed39SKyle EvansThe type <em>number</em> represents both
1550495ed39SKyle Evansinteger numbers and real (floating-point) numbers,
1560495ed39SKyle Evansusing two subtypes: <em>integer</em> and <em>float</em>.
1578e3e3a7aSWarner LoshStandard Lua uses 64-bit integers and double-precision (64-bit) floats,
1588e3e3a7aSWarner Loshbut you can also compile Lua so that it
1598e3e3a7aSWarner Loshuses 32-bit integers and/or single-precision (32-bit) floats.
1608e3e3a7aSWarner LoshThe option with 32 bits for both integers and floats
1618e3e3a7aSWarner Loshis particularly attractive
1628e3e3a7aSWarner Loshfor small machines and embedded systems.
1638e3e3a7aSWarner Losh(See macro <code>LUA_32BITS</code> in file <code>luaconf.h</code>.)
1648e3e3a7aSWarner Losh
1658e3e3a7aSWarner Losh
1668e3e3a7aSWarner Losh<p>
1670495ed39SKyle EvansUnless stated otherwise,
1680495ed39SKyle Evansany overflow when manipulating integer values <em>wrap around</em>,
1690495ed39SKyle Evansaccording to the usual rules of two-complement arithmetic.
1700495ed39SKyle Evans(In other words,
1710495ed39SKyle Evansthe actual result is the unique representable integer
1720495ed39SKyle Evansthat is equal modulo <em>2<sup>n</sup></em> to the mathematical result,
1730495ed39SKyle Evanswhere <em>n</em> is the number of bits of the integer type.)
1740495ed39SKyle Evans
1750495ed39SKyle Evans
1760495ed39SKyle Evans<p>
1770495ed39SKyle EvansLua has explicit rules about when each subtype is used,
1780495ed39SKyle Evansbut it also converts between them automatically as needed (see <a href="#3.4.3">&sect;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">&sect;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&nbsp;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&nbsp;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">&sect;2.4</a>).
2168e3e3a7aSWarner LoshUserdata values cannot be created or modified in Lua,
2178e3e3a7aSWarner Loshonly through the C&nbsp;API.
2180495ed39SKyle EvansThis guarantees the integrity of data owned by
2190495ed39SKyle Evansthe host program and C&nbsp;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">&sect;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">&sect;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">&sect;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 &ndash; <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">&sect;3.2</a> and <a href="#3.3.3">&sect;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">&sect;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">&sect;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">&sect;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 &ndash; <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&nbsp;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,
394*3068d706SWarner Loshbut programs can 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)
404*3068d706SWarner Loshyou can 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 &ndash; <a name="2.4">Metatables and Metamethods</a></h2>
4338e3e3a7aSWarner Losh
4348e3e3a7aSWarner Losh<p>
4358e3e3a7aSWarner LoshEvery value in Lua can have a <em>metatable</em>.
4368e3e3a7aSWarner LoshThis <em>metatable</em> is an ordinary Lua table
4378e3e3a7aSWarner Loshthat defines the behavior of the original value
4380495ed39SKyle Evansunder certain events.
4398e3e3a7aSWarner LoshYou can change several aspects of the behavior
4400495ed39SKyle Evansof a value by setting specific fields in its metatable.
4418e3e3a7aSWarner LoshFor instance, when a non-numeric value is the operand of an addition,
4428c784bb8SWarner LoshLua checks for a function in the field <code>__add</code> of the value's metatable.
4438e3e3a7aSWarner LoshIf it finds one,
4448e3e3a7aSWarner LoshLua calls this function to perform the addition.
4458e3e3a7aSWarner Losh
4468e3e3a7aSWarner Losh
4478e3e3a7aSWarner Losh<p>
4488e3e3a7aSWarner LoshThe key for each event in a metatable is a string
4498e3e3a7aSWarner Loshwith the event name prefixed by two underscores;
4500495ed39SKyle Evansthe corresponding value is called a <em>metavalue</em>.
4510495ed39SKyle EvansFor most events, the metavalue must be a function,
4520495ed39SKyle Evanswhich is then called a <em>metamethod</em>.
4530495ed39SKyle EvansIn the previous example, the key is the string "<code>__add</code>"
4548e3e3a7aSWarner Loshand the metamethod is the function that performs the addition.
455e112e9d2SKyle EvansUnless stated otherwise,
456*3068d706SWarner Losha metamethod can 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">&sect;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">&sect;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>&amp;</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">&sect;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>&lt;&lt;</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>&gt;&gt;</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">&sect;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>&lt;</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>&lt;=</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">&sect;2.5.3</a>),
6900495ed39SKyle Evans<code>__close</code> (see <a href="#3.3.8">&sect;3.3.8</a>),
6910495ed39SKyle Evans<code>__mode</code> (see <a href="#2.5.4">&sect;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">&sect;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 &ndash; <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">&sect;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&nbsp;code,
7610495ed39SKyle Evansit never collects objects accessible through the registry (see <a href="#4.3">&sect;4.3</a>),
7620495ed39SKyle Evanswhich includes the global environment (see <a href="#2.2">&sect;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&nbsp;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 &ndash; <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&nbsp;Kbytes.
8440495ed39SKyle Evans
8450495ed39SKyle Evans
8460495ed39SKyle Evans
8470495ed39SKyle Evans
8480495ed39SKyle Evans
8490495ed39SKyle Evans<h3>2.5.2 &ndash; <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 &ndash; <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&nbsp;API,
8948e3e3a7aSWarner Loshfor full userdata (see <a href="#2.4">&sect;2.4</a>).
8950495ed39SKyle EvansThese metamethods, called <em>finalizers</em>,
8960495ed39SKyle Evansare called when the garbage collector detects that the
8970495ed39SKyle Evanscorresponding table or userdata is dead.
8988e3e3a7aSWarner LoshFinalizers allow you to coordinate Lua's garbage collection
8990495ed39SKyle Evanswith external resource management such as closing files,
9000495ed39SKyle Evansnetwork or database connections,
9010495ed39SKyle Evansor freeing your own memory.
9028e3e3a7aSWarner Losh
9038e3e3a7aSWarner Losh
9048e3e3a7aSWarner Losh<p>
9058e3e3a7aSWarner LoshFor an object (table or userdata) to be finalized when collected,
9068e3e3a7aSWarner Loshyou must <em>mark</em> it for finalization.
9078e3e3a7aSWarner Losh
9088e3e3a7aSWarner LoshYou mark an object for finalization when you set its metatable
9098c784bb8SWarner Loshand the metatable has a <code>__gc</code> metamethod.
9108e3e3a7aSWarner LoshNote that if you set a metatable without a <code>__gc</code> field
9118e3e3a7aSWarner Loshand later create that field in the metatable,
9128e3e3a7aSWarner Loshthe object will not be marked for finalization.
9138e3e3a7aSWarner Losh
9148e3e3a7aSWarner Losh
9158e3e3a7aSWarner Losh<p>
9160495ed39SKyle EvansWhen a marked object becomes dead,
9178e3e3a7aSWarner Loshit is not collected immediately by the garbage collector.
9188e3e3a7aSWarner LoshInstead, Lua puts it in a list.
9198e3e3a7aSWarner LoshAfter the collection,
9208e3e3a7aSWarner LoshLua goes through that list.
9218e3e3a7aSWarner LoshFor each object in the list,
9228e3e3a7aSWarner Loshit checks the object's <code>__gc</code> metamethod:
9230495ed39SKyle EvansIf it is present,
9240495ed39SKyle EvansLua calls it with the object as its single argument.
9258e3e3a7aSWarner Losh
9268e3e3a7aSWarner Losh
9278e3e3a7aSWarner Losh<p>
9288e3e3a7aSWarner LoshAt the end of each garbage-collection cycle,
9290495ed39SKyle Evansthe finalizers are called in
9308e3e3a7aSWarner Loshthe reverse order that the objects were marked for finalization,
9318e3e3a7aSWarner Loshamong those collected in that cycle;
9328e3e3a7aSWarner Loshthat is, the first finalizer to be called is the one associated
9338e3e3a7aSWarner Loshwith the object marked last in the program.
9348e3e3a7aSWarner LoshThe execution of each finalizer may occur at any point during
9358e3e3a7aSWarner Loshthe execution of the regular code.
9368e3e3a7aSWarner Losh
9378e3e3a7aSWarner Losh
9388e3e3a7aSWarner Losh<p>
9398e3e3a7aSWarner LoshBecause the object being collected must still be used by the finalizer,
9408e3e3a7aSWarner Loshthat object (and other objects accessible only through it)
9418e3e3a7aSWarner Loshmust be <em>resurrected</em> by Lua.
9428e3e3a7aSWarner LoshUsually, this resurrection is transient,
9438e3e3a7aSWarner Loshand the object memory is freed in the next garbage-collection cycle.
9448e3e3a7aSWarner LoshHowever, if the finalizer stores the object in some global place
9458e3e3a7aSWarner Losh(e.g., a global variable),
9468e3e3a7aSWarner Loshthen the resurrection is permanent.
9478e3e3a7aSWarner LoshMoreover, if the finalizer marks a finalizing object for finalization again,
9488e3e3a7aSWarner Loshits finalizer will be called again in the next cycle where the
9490495ed39SKyle Evansobject is dead.
9508e3e3a7aSWarner LoshIn any case,
9518e3e3a7aSWarner Loshthe object memory is freed only in a GC cycle where
9520495ed39SKyle Evansthe object is dead and not marked for finalization.
9538e3e3a7aSWarner Losh
9548e3e3a7aSWarner Losh
9558e3e3a7aSWarner Losh<p>
9568e3e3a7aSWarner LoshWhen you close a state (see <a href="#lua_close"><code>lua_close</code></a>),
9578e3e3a7aSWarner LoshLua calls the finalizers of all objects marked for finalization,
9588e3e3a7aSWarner Loshfollowing the reverse order that they were marked.
9598e3e3a7aSWarner LoshIf any finalizer marks objects for collection during that phase,
9608e3e3a7aSWarner Loshthese marks have no effect.
9618e3e3a7aSWarner Losh
9628e3e3a7aSWarner Losh
9630495ed39SKyle Evans<p>
9648c784bb8SWarner LoshFinalizers cannot yield nor run the garbage collector.
9658c784bb8SWarner LoshBecause they can run in unpredictable times,
9660495ed39SKyle Evansit is good practice to restrict each finalizer
9670495ed39SKyle Evansto the minimum necessary to properly release
9680495ed39SKyle Evansits associated resource.
9690495ed39SKyle Evans
9700495ed39SKyle Evans
9710495ed39SKyle Evans<p>
9720495ed39SKyle EvansAny error while running a finalizer generates a warning;
9730495ed39SKyle Evansthe error is not propagated.
9748e3e3a7aSWarner Losh
9758e3e3a7aSWarner Losh
9768e3e3a7aSWarner Losh
9770495ed39SKyle Evans
9780495ed39SKyle Evans
9790495ed39SKyle Evans<h3>2.5.4 &ndash; <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&nbsp;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 &ndash; <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 &ndash; <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>}&nbsp;means&nbsp;0 or more <em>a</em>'s, and
12028e3e3a7aSWarner Losh[<em>a</em>]&nbsp;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 &lsquo;<b>=</b>&rsquo;.
12068e3e3a7aSWarner LoshThe complete syntax of Lua can be found in <a href="#9">&sect;9</a>
12078e3e3a7aSWarner Loshat the end of this manual.
12088e3e3a7aSWarner Losh
12098e3e3a7aSWarner Losh
12108e3e3a7aSWarner Losh
12110495ed39SKyle Evans
12120495ed39SKyle Evans
12138e3e3a7aSWarner Losh<h2>3.1 &ndash; <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     &amp;     ~     |     &lt;&lt;    &gt;&gt;    //
12638e3e3a7aSWarner Losh     ==    ~=    &lt;=    &gt;=    &lt;     &gt;     =
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&nbsp;0 is written as <code>[[</code>,
13268e3e3a7aSWarner Loshan opening long bracket of level&nbsp;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&nbsp;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&nbsp;97,
13488e3e3a7aSWarner Loshnewline is coded as&nbsp;10, and '<code>1</code>' is coded as&nbsp;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,
1382a9490b81SWarner Loshmarked by a letter '<code>p</code>' or '<code>P</code>' and written in decimal.
1383a9490b81SWarner Losh(For instance, <code>0x1.fp10</code> denotes 1984,
1384a9490b81SWarner Loshwhich is <em>0x1f / 16</em> multiplied by <em>2<sup>10</sup></em>.)
13850495ed39SKyle Evans
13860495ed39SKyle Evans
13870495ed39SKyle Evans<p>
13888e3e3a7aSWarner LoshA numeric constant with a radix point or an exponent
13898e3e3a7aSWarner Loshdenotes a float;
13908e3e3a7aSWarner Loshotherwise,
13910495ed39SKyle Evansif its value fits in an integer or it is a hexadecimal constant,
13920495ed39SKyle Evansit denotes an integer;
13930495ed39SKyle Evansotherwise (that is, a decimal integer numeral that overflows),
13940495ed39SKyle Evansit denotes a float.
13950495ed39SKyle EvansHexadecimal numerals with neither a radix point nor an exponent
13960495ed39SKyle Evansalways denote an integer value;
13970495ed39SKyle Evansif the value overflows, it <em>wraps around</em>
13980495ed39SKyle Evansto fit into a valid integer.
13990495ed39SKyle Evans
14000495ed39SKyle Evans
14010495ed39SKyle Evans<p>
14028e3e3a7aSWarner LoshExamples of valid integer constants are
14038e3e3a7aSWarner Losh
14048e3e3a7aSWarner Losh<pre>
14058e3e3a7aSWarner Losh     3   345   0xff   0xBEBADA
14068e3e3a7aSWarner Losh</pre><p>
14078e3e3a7aSWarner LoshExamples of valid float constants are
14088e3e3a7aSWarner Losh
14098e3e3a7aSWarner Losh<pre>
14108e3e3a7aSWarner Losh     3.0     3.1416     314.16e-2     0.31416E1     34e1
14118e3e3a7aSWarner Losh     0x0.1E  0xA23p-4   0X1.921FB54442D18P+1
14128e3e3a7aSWarner Losh</pre>
14138e3e3a7aSWarner Losh
14148e3e3a7aSWarner Losh<p>
14158e3e3a7aSWarner LoshA <em>comment</em> starts with a double hyphen (<code>--</code>)
14168e3e3a7aSWarner Loshanywhere outside a string.
14178e3e3a7aSWarner LoshIf the text immediately after <code>--</code> is not an opening long bracket,
14188e3e3a7aSWarner Loshthe comment is a <em>short comment</em>,
14198e3e3a7aSWarner Loshwhich runs until the end of the line.
14208e3e3a7aSWarner LoshOtherwise, it is a <em>long comment</em>,
14218e3e3a7aSWarner Loshwhich runs until the corresponding closing long bracket.
14228e3e3a7aSWarner Losh
14238e3e3a7aSWarner Losh
14248e3e3a7aSWarner Losh
14258e3e3a7aSWarner Losh
14268e3e3a7aSWarner Losh
14278e3e3a7aSWarner Losh<h2>3.2 &ndash; <a name="3.2">Variables</a></h2>
14288e3e3a7aSWarner Losh
14298e3e3a7aSWarner Losh<p>
14308e3e3a7aSWarner LoshVariables are places that store values.
14318e3e3a7aSWarner LoshThere are three kinds of variables in Lua:
14328e3e3a7aSWarner Loshglobal variables, local variables, and table fields.
14338e3e3a7aSWarner Losh
14348e3e3a7aSWarner Losh
14358e3e3a7aSWarner Losh<p>
14368e3e3a7aSWarner LoshA single name can denote a global variable or a local variable
14378e3e3a7aSWarner Losh(or a function's formal parameter,
14388e3e3a7aSWarner Loshwhich is a particular kind of local variable):
14398e3e3a7aSWarner Losh
14408e3e3a7aSWarner Losh<pre>
14418e3e3a7aSWarner Losh	var ::= Name
14428e3e3a7aSWarner Losh</pre><p>
14430495ed39SKyle EvansName denotes identifiers (see <a href="#3.1">&sect;3.1</a>).
14448e3e3a7aSWarner Losh
14458e3e3a7aSWarner Losh
14468e3e3a7aSWarner Losh<p>
14478e3e3a7aSWarner LoshAny variable name is assumed to be global unless explicitly declared
14488e3e3a7aSWarner Loshas a local (see <a href="#3.3.7">&sect;3.3.7</a>).
14498e3e3a7aSWarner LoshLocal variables are <em>lexically scoped</em>:
14508e3e3a7aSWarner Loshlocal variables can be freely accessed by functions
14518e3e3a7aSWarner Loshdefined inside their scope (see <a href="#3.5">&sect;3.5</a>).
14528e3e3a7aSWarner Losh
14538e3e3a7aSWarner Losh
14548e3e3a7aSWarner Losh<p>
14558e3e3a7aSWarner LoshBefore the first assignment to a variable, its value is <b>nil</b>.
14568e3e3a7aSWarner Losh
14578e3e3a7aSWarner Losh
14588e3e3a7aSWarner Losh<p>
14598e3e3a7aSWarner LoshSquare brackets are used to index a table:
14608e3e3a7aSWarner Losh
14618e3e3a7aSWarner Losh<pre>
14628e3e3a7aSWarner Losh	var ::= prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo;
14638e3e3a7aSWarner Losh</pre><p>
1464e112e9d2SKyle EvansThe meaning of accesses to table fields can be changed via metatables
1465e112e9d2SKyle Evans(see <a href="#2.4">&sect;2.4</a>).
14668e3e3a7aSWarner Losh
14678e3e3a7aSWarner Losh
14688e3e3a7aSWarner Losh<p>
14698e3e3a7aSWarner LoshThe syntax <code>var.Name</code> is just syntactic sugar for
14708e3e3a7aSWarner Losh<code>var["Name"]</code>:
14718e3e3a7aSWarner Losh
14728e3e3a7aSWarner Losh<pre>
14738e3e3a7aSWarner Losh	var ::= prefixexp &lsquo;<b>.</b>&rsquo; Name
14748e3e3a7aSWarner Losh</pre>
14758e3e3a7aSWarner Losh
14768e3e3a7aSWarner Losh<p>
14778e3e3a7aSWarner LoshAn access to a global variable <code>x</code>
14788e3e3a7aSWarner Loshis equivalent to <code>_ENV.x</code>.
14798e3e3a7aSWarner LoshDue to the way that chunks are compiled,
14800495ed39SKyle Evansthe variable <code>_ENV</code> itself is never global (see <a href="#2.2">&sect;2.2</a>).
14818e3e3a7aSWarner Losh
14828e3e3a7aSWarner Losh
14838e3e3a7aSWarner Losh
14848e3e3a7aSWarner Losh
14858e3e3a7aSWarner Losh
14868e3e3a7aSWarner Losh<h2>3.3 &ndash; <a name="3.3">Statements</a></h2>
14878e3e3a7aSWarner Losh
14880495ed39SKyle Evans
14890495ed39SKyle Evans
14908e3e3a7aSWarner Losh<p>
14918e3e3a7aSWarner LoshLua supports an almost conventional set of statements,
14920495ed39SKyle Evanssimilar to those in other conventional languages.
14938e3e3a7aSWarner LoshThis set includes
14940495ed39SKyle Evansblocks, assignments, control structures, function calls,
14958e3e3a7aSWarner Loshand variable declarations.
14968e3e3a7aSWarner Losh
14978e3e3a7aSWarner Losh
14988e3e3a7aSWarner Losh
14990495ed39SKyle Evans
15000495ed39SKyle Evans
15018e3e3a7aSWarner Losh<h3>3.3.1 &ndash; <a name="3.3.1">Blocks</a></h3>
15028e3e3a7aSWarner Losh
15038e3e3a7aSWarner Losh<p>
15048e3e3a7aSWarner LoshA block is a list of statements,
15058e3e3a7aSWarner Loshwhich are executed sequentially:
15068e3e3a7aSWarner Losh
15078e3e3a7aSWarner Losh<pre>
15088e3e3a7aSWarner Losh	block ::= {stat}
15098e3e3a7aSWarner Losh</pre><p>
15108e3e3a7aSWarner LoshLua has <em>empty statements</em>
15118e3e3a7aSWarner Loshthat allow you to separate statements with semicolons,
15128e3e3a7aSWarner Loshstart a block with a semicolon
15138e3e3a7aSWarner Loshor write two semicolons in sequence:
15148e3e3a7aSWarner Losh
15158e3e3a7aSWarner Losh<pre>
15168e3e3a7aSWarner Losh	stat ::= &lsquo;<b>;</b>&rsquo;
15178e3e3a7aSWarner Losh</pre>
15188e3e3a7aSWarner Losh
15198e3e3a7aSWarner Losh<p>
15200495ed39SKyle EvansBoth function calls and assignments
15218e3e3a7aSWarner Loshcan start with an open parenthesis.
15228e3e3a7aSWarner LoshThis possibility leads to an ambiguity in Lua's grammar.
15238e3e3a7aSWarner LoshConsider the following fragment:
15248e3e3a7aSWarner Losh
15258e3e3a7aSWarner Losh<pre>
15268e3e3a7aSWarner Losh     a = b + c
15278e3e3a7aSWarner Losh     (print or io.write)('done')
15288e3e3a7aSWarner Losh</pre><p>
15290495ed39SKyle EvansThe grammar could see this fragment in two ways:
15308e3e3a7aSWarner Losh
15318e3e3a7aSWarner Losh<pre>
15328e3e3a7aSWarner Losh     a = b + c(print or io.write)('done')
15338e3e3a7aSWarner Losh
15348e3e3a7aSWarner Losh     a = b + c; (print or io.write)('done')
15358e3e3a7aSWarner Losh</pre><p>
15368e3e3a7aSWarner LoshThe current parser always sees such constructions
15378e3e3a7aSWarner Loshin the first way,
15388e3e3a7aSWarner Loshinterpreting the open parenthesis
15398e3e3a7aSWarner Loshas the start of the arguments to a call.
15408e3e3a7aSWarner LoshTo avoid this ambiguity,
15418e3e3a7aSWarner Loshit is a good practice to always precede with a semicolon
15428e3e3a7aSWarner Loshstatements that start with a parenthesis:
15438e3e3a7aSWarner Losh
15448e3e3a7aSWarner Losh<pre>
15458e3e3a7aSWarner Losh     ;(print or io.write)('done')
15468e3e3a7aSWarner Losh</pre>
15478e3e3a7aSWarner Losh
15488e3e3a7aSWarner Losh<p>
15498e3e3a7aSWarner LoshA block can be explicitly delimited to produce a single statement:
15508e3e3a7aSWarner Losh
15518e3e3a7aSWarner Losh<pre>
15528e3e3a7aSWarner Losh	stat ::= <b>do</b> block <b>end</b>
15538e3e3a7aSWarner Losh</pre><p>
15548e3e3a7aSWarner LoshExplicit blocks are useful
15558e3e3a7aSWarner Loshto control the scope of variable declarations.
15568e3e3a7aSWarner LoshExplicit blocks are also sometimes used to
15578e3e3a7aSWarner Loshadd a <b>return</b> statement in the middle
15588e3e3a7aSWarner Loshof another block (see <a href="#3.3.4">&sect;3.3.4</a>).
15598e3e3a7aSWarner Losh
15608e3e3a7aSWarner Losh
15618e3e3a7aSWarner Losh
15628e3e3a7aSWarner Losh
15638e3e3a7aSWarner Losh
15648e3e3a7aSWarner Losh<h3>3.3.2 &ndash; <a name="3.3.2">Chunks</a></h3>
15658e3e3a7aSWarner Losh
15668e3e3a7aSWarner Losh<p>
15678e3e3a7aSWarner LoshThe unit of compilation of Lua is called a <em>chunk</em>.
15688e3e3a7aSWarner LoshSyntactically,
15698e3e3a7aSWarner Losha chunk is simply a block:
15708e3e3a7aSWarner Losh
15718e3e3a7aSWarner Losh<pre>
15728e3e3a7aSWarner Losh	chunk ::= block
15738e3e3a7aSWarner Losh</pre>
15748e3e3a7aSWarner Losh
15758e3e3a7aSWarner Losh<p>
15768e3e3a7aSWarner LoshLua handles a chunk as the body of an anonymous function
15778e3e3a7aSWarner Loshwith a variable number of arguments
15788e3e3a7aSWarner Losh(see <a href="#3.4.11">&sect;3.4.11</a>).
15798e3e3a7aSWarner LoshAs such, chunks can define local variables,
15808e3e3a7aSWarner Loshreceive arguments, and return values.
15818e3e3a7aSWarner LoshMoreover, such anonymous function is compiled as in the
15828e3e3a7aSWarner Loshscope of an external local variable called <code>_ENV</code> (see <a href="#2.2">&sect;2.2</a>).
15830495ed39SKyle EvansThe resulting function always has <code>_ENV</code> as its only external variable,
15848e3e3a7aSWarner Losheven if it does not use that variable.
15858e3e3a7aSWarner Losh
15868e3e3a7aSWarner Losh
15878e3e3a7aSWarner Losh<p>
15888e3e3a7aSWarner LoshA chunk can be stored in a file or in a string inside the host program.
15898e3e3a7aSWarner LoshTo execute a chunk,
15908e3e3a7aSWarner LoshLua first <em>loads</em> it,
15918e3e3a7aSWarner Loshprecompiling the chunk's code into instructions for a virtual machine,
15928e3e3a7aSWarner Loshand then Lua executes the compiled code
15938e3e3a7aSWarner Loshwith an interpreter for the virtual machine.
15948e3e3a7aSWarner Losh
15958e3e3a7aSWarner Losh
15968e3e3a7aSWarner Losh<p>
15978e3e3a7aSWarner LoshChunks can also be precompiled into binary form;
15980495ed39SKyle Evanssee the program <code>luac</code> and the function <a href="#pdf-string.dump"><code>string.dump</code></a> for details.
15998e3e3a7aSWarner LoshPrograms in source and compiled forms are interchangeable;
16008e3e3a7aSWarner LoshLua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>).
16018e3e3a7aSWarner Losh
16028e3e3a7aSWarner Losh
16038e3e3a7aSWarner Losh
16048e3e3a7aSWarner Losh
16058e3e3a7aSWarner Losh
16068e3e3a7aSWarner Losh<h3>3.3.3 &ndash; <a name="3.3.3">Assignment</a></h3>
16078e3e3a7aSWarner Losh
16088e3e3a7aSWarner Losh<p>
16098e3e3a7aSWarner LoshLua allows multiple assignments.
16108e3e3a7aSWarner LoshTherefore, the syntax for assignment
16118e3e3a7aSWarner Loshdefines a list of variables on the left side
16128e3e3a7aSWarner Loshand a list of expressions on the right side.
16138e3e3a7aSWarner LoshThe elements in both lists are separated by commas:
16148e3e3a7aSWarner Losh
16158e3e3a7aSWarner Losh<pre>
16168e3e3a7aSWarner Losh	stat ::= varlist &lsquo;<b>=</b>&rsquo; explist
16178e3e3a7aSWarner Losh	varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
16188e3e3a7aSWarner Losh	explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
16198e3e3a7aSWarner Losh</pre><p>
16208e3e3a7aSWarner LoshExpressions are discussed in <a href="#3.4">&sect;3.4</a>.
16218e3e3a7aSWarner Losh
16228e3e3a7aSWarner Losh
16238e3e3a7aSWarner Losh<p>
16248e3e3a7aSWarner LoshBefore the assignment,
16258e3e3a7aSWarner Loshthe list of values is <em>adjusted</em> to the length of
1626a9490b81SWarner Loshthe list of variables (see <a href="#3.4.12">&sect;3.4.12</a>).
16278e3e3a7aSWarner Losh
16288e3e3a7aSWarner Losh
16298e3e3a7aSWarner Losh<p>
16308c784bb8SWarner LoshIf a variable is both assigned and read
16318c784bb8SWarner Loshinside a multiple assignment,
1632a9490b81SWarner LoshLua ensures that all reads get the value of the variable
16338c784bb8SWarner Loshbefore the assignment.
16348e3e3a7aSWarner LoshThus the code
16358e3e3a7aSWarner Losh
16368e3e3a7aSWarner Losh<pre>
16378e3e3a7aSWarner Losh     i = 3
16388e3e3a7aSWarner Losh     i, a[i] = i+1, 20
16398e3e3a7aSWarner Losh</pre><p>
16408e3e3a7aSWarner Loshsets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
16418e3e3a7aSWarner Loshbecause the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
16428e3e3a7aSWarner Loshbefore it is assigned&nbsp;4.
16438e3e3a7aSWarner LoshSimilarly, the line
16448e3e3a7aSWarner Losh
16458e3e3a7aSWarner Losh<pre>
16468e3e3a7aSWarner Losh     x, y = y, x
16478e3e3a7aSWarner Losh</pre><p>
16488e3e3a7aSWarner Loshexchanges the values of <code>x</code> and <code>y</code>,
16498e3e3a7aSWarner Loshand
16508e3e3a7aSWarner Losh
16518e3e3a7aSWarner Losh<pre>
16528e3e3a7aSWarner Losh     x, y, z = y, z, x
16538e3e3a7aSWarner Losh</pre><p>
16548e3e3a7aSWarner Loshcyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>.
16558e3e3a7aSWarner Losh
16568e3e3a7aSWarner Losh
16578e3e3a7aSWarner Losh<p>
16588c784bb8SWarner LoshNote that this guarantee covers only accesses
16598c784bb8SWarner Loshsyntactically inside the assignment statement.
16608c784bb8SWarner LoshIf a function or a metamethod called during the assignment
16618c784bb8SWarner Loshchanges the value of a variable,
16628c784bb8SWarner LoshLua gives no guarantees about the order of that access.
16638c784bb8SWarner Losh
16648c784bb8SWarner Losh
16658c784bb8SWarner Losh<p>
16668e3e3a7aSWarner LoshAn assignment to a global name <code>x = val</code>
16678e3e3a7aSWarner Loshis equivalent to the assignment
16688e3e3a7aSWarner Losh<code>_ENV.x = val</code> (see <a href="#2.2">&sect;2.2</a>).
16698e3e3a7aSWarner Losh
16708e3e3a7aSWarner Losh
1671e112e9d2SKyle Evans<p>
1672e112e9d2SKyle EvansThe meaning of assignments to table fields and
1673e112e9d2SKyle Evansglobal variables (which are actually table fields, too)
1674e112e9d2SKyle Evanscan be changed via metatables (see <a href="#2.4">&sect;2.4</a>).
1675e112e9d2SKyle Evans
1676e112e9d2SKyle Evans
16778e3e3a7aSWarner Losh
16788e3e3a7aSWarner Losh
16798e3e3a7aSWarner Losh
16808e3e3a7aSWarner Losh<h3>3.3.4 &ndash; <a name="3.3.4">Control Structures</a></h3><p>
16818e3e3a7aSWarner LoshThe control structures
16828e3e3a7aSWarner Losh<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
16838e3e3a7aSWarner Loshfamiliar syntax:
16848e3e3a7aSWarner Losh
16858e3e3a7aSWarner Losh
16868e3e3a7aSWarner Losh
16878e3e3a7aSWarner Losh
16888e3e3a7aSWarner Losh<pre>
16898e3e3a7aSWarner Losh	stat ::= <b>while</b> exp <b>do</b> block <b>end</b>
16908e3e3a7aSWarner Losh	stat ::= <b>repeat</b> block <b>until</b> exp
16918e3e3a7aSWarner Losh	stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b>
16928e3e3a7aSWarner Losh</pre><p>
16938e3e3a7aSWarner LoshLua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">&sect;3.3.5</a>).
16948e3e3a7aSWarner Losh
16958e3e3a7aSWarner Losh
16968e3e3a7aSWarner Losh<p>
16978e3e3a7aSWarner LoshThe condition expression of a
16988e3e3a7aSWarner Loshcontrol structure can return any value.
16990495ed39SKyle EvansBoth <b>false</b> and <b>nil</b> test false.
17000495ed39SKyle EvansAll values different from <b>nil</b> and <b>false</b> test true.
17010495ed39SKyle EvansIn particular, the number 0 and the empty string also test true.
17028e3e3a7aSWarner Losh
17038e3e3a7aSWarner Losh
17048e3e3a7aSWarner Losh<p>
17058e3e3a7aSWarner LoshIn the <b>repeat</b>&ndash;<b>until</b> loop,
17068e3e3a7aSWarner Loshthe inner block does not end at the <b>until</b> keyword,
17078e3e3a7aSWarner Loshbut only after the condition.
17088e3e3a7aSWarner LoshSo, the condition can refer to local variables
17098e3e3a7aSWarner Loshdeclared inside the loop block.
17108e3e3a7aSWarner Losh
17118e3e3a7aSWarner Losh
17128e3e3a7aSWarner Losh<p>
17138e3e3a7aSWarner LoshThe <b>goto</b> statement transfers the program control to a label.
17148e3e3a7aSWarner LoshFor syntactical reasons,
17158e3e3a7aSWarner Loshlabels in Lua are considered statements too:
17168e3e3a7aSWarner Losh
17178e3e3a7aSWarner Losh
17188e3e3a7aSWarner Losh
17198e3e3a7aSWarner Losh<pre>
17208e3e3a7aSWarner Losh	stat ::= <b>goto</b> Name
17218e3e3a7aSWarner Losh	stat ::= label
17228e3e3a7aSWarner Losh	label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
17238e3e3a7aSWarner Losh</pre>
17248e3e3a7aSWarner Losh
17258e3e3a7aSWarner Losh<p>
17268e3e3a7aSWarner LoshA label is visible in the entire block where it is defined,
17270495ed39SKyle Evansexcept inside nested functions.
1728*3068d706SWarner LoshA goto can jump to any visible label as long as it does not
17298e3e3a7aSWarner Loshenter into the scope of a local variable.
17300495ed39SKyle EvansA label should not be declared
17310495ed39SKyle Evanswhere a label with the same name is visible,
17320495ed39SKyle Evanseven if this other label has been declared in an enclosing block.
17338e3e3a7aSWarner Losh
17348e3e3a7aSWarner Losh
17358e3e3a7aSWarner Losh<p>
17368e3e3a7aSWarner LoshThe <b>break</b> statement terminates the execution of a
17378e3e3a7aSWarner Losh<b>while</b>, <b>repeat</b>, or <b>for</b> loop,
17388e3e3a7aSWarner Loshskipping to the next statement after the loop:
17398e3e3a7aSWarner Losh
17408e3e3a7aSWarner Losh
17418e3e3a7aSWarner Losh<pre>
17428e3e3a7aSWarner Losh	stat ::= <b>break</b>
17438e3e3a7aSWarner Losh</pre><p>
17448e3e3a7aSWarner LoshA <b>break</b> ends the innermost enclosing loop.
17458e3e3a7aSWarner Losh
17468e3e3a7aSWarner Losh
17478e3e3a7aSWarner Losh<p>
17488e3e3a7aSWarner LoshThe <b>return</b> statement is used to return values
17498e3e3a7aSWarner Loshfrom a function or a chunk
17500495ed39SKyle Evans(which is handled as an anonymous function).
17518e3e3a7aSWarner Losh
17528e3e3a7aSWarner LoshFunctions can return more than one value,
17538e3e3a7aSWarner Loshso the syntax for the <b>return</b> statement is
17548e3e3a7aSWarner Losh
17558e3e3a7aSWarner Losh<pre>
17568e3e3a7aSWarner Losh	stat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
17578e3e3a7aSWarner Losh</pre>
17588e3e3a7aSWarner Losh
17598e3e3a7aSWarner Losh<p>
17608e3e3a7aSWarner LoshThe <b>return</b> statement can only be written
17618e3e3a7aSWarner Loshas the last statement of a block.
17620495ed39SKyle EvansIf it is necessary to <b>return</b> in the middle of a block,
17638e3e3a7aSWarner Loshthen an explicit inner block can be used,
17648e3e3a7aSWarner Loshas in the idiom <code>do return end</code>,
17658e3e3a7aSWarner Loshbecause now <b>return</b> is the last statement in its (inner) block.
17668e3e3a7aSWarner Losh
17678e3e3a7aSWarner Losh
17688e3e3a7aSWarner Losh
17698e3e3a7aSWarner Losh
17708e3e3a7aSWarner Losh
17718e3e3a7aSWarner Losh<h3>3.3.5 &ndash; <a name="3.3.5">For Statement</a></h3>
17728e3e3a7aSWarner Losh
17738e3e3a7aSWarner Losh<p>
17748e3e3a7aSWarner Losh
17758e3e3a7aSWarner LoshThe <b>for</b> statement has two forms:
17768e3e3a7aSWarner Loshone numerical and one generic.
17778e3e3a7aSWarner Losh
17788e3e3a7aSWarner Losh
17790495ed39SKyle Evans
17800495ed39SKyle Evans<h4>The numerical <b>for</b> loop</h4>
17810495ed39SKyle Evans
17828e3e3a7aSWarner Losh<p>
17838e3e3a7aSWarner LoshThe numerical <b>for</b> loop repeats a block of code while a
17840495ed39SKyle Evanscontrol variable goes through an arithmetic progression.
17858e3e3a7aSWarner LoshIt has the following syntax:
17868e3e3a7aSWarner Losh
17878e3e3a7aSWarner Losh<pre>
17888e3e3a7aSWarner Losh	stat ::= <b>for</b> Name &lsquo;<b>=</b>&rsquo; exp &lsquo;<b>,</b>&rsquo; exp [&lsquo;<b>,</b>&rsquo; exp] <b>do</b> block <b>end</b>
17898e3e3a7aSWarner Losh</pre><p>
17900495ed39SKyle EvansThe given identifier (Name) defines the control variable,
17910495ed39SKyle Evanswhich is a new variable local to the loop body (<em>block</em>).
17928e3e3a7aSWarner Losh
17938e3e3a7aSWarner Losh
17948e3e3a7aSWarner Losh<p>
17950495ed39SKyle EvansThe loop starts by evaluating once the three control expressions.
17960495ed39SKyle EvansTheir values are called respectively
17970495ed39SKyle Evansthe <em>initial value</em>, the <em>limit</em>, and the <em>step</em>.
17980495ed39SKyle EvansIf the step is absent, it defaults to&nbsp;1.
17998e3e3a7aSWarner Losh
18008e3e3a7aSWarner Losh
18010495ed39SKyle Evans<p>
18020495ed39SKyle EvansIf both the initial value and the step are integers,
18030495ed39SKyle Evansthe loop is done with integers;
18040495ed39SKyle Evansnote that the limit may not be an integer.
18050495ed39SKyle EvansOtherwise, the three values are converted to
18060495ed39SKyle Evansfloats and the loop is done with floats.
18070495ed39SKyle EvansBeware of floating-point accuracy in this case.
18088e3e3a7aSWarner Losh
18098e3e3a7aSWarner Losh
18100495ed39SKyle Evans<p>
18110495ed39SKyle EvansAfter that initialization,
18120495ed39SKyle Evansthe loop body is repeated with the value of the control variable
18130495ed39SKyle Evansgoing through an arithmetic progression,
18140495ed39SKyle Evansstarting at the initial value,
18150495ed39SKyle Evanswith a common difference given by the step.
18160495ed39SKyle EvansA negative step makes a decreasing sequence;
18170495ed39SKyle Evansa step equal to zero raises an error.
18180495ed39SKyle EvansThe loop continues while the value is less than
18190495ed39SKyle Evansor equal to the limit
18200495ed39SKyle Evans(greater than or equal to for a negative step).
18210495ed39SKyle EvansIf the initial value is already greater than the limit
18220495ed39SKyle Evans(or less than, if the step is negative),
18230495ed39SKyle Evansthe body is not executed.
18248e3e3a7aSWarner Losh
18258e3e3a7aSWarner Losh
18260495ed39SKyle Evans<p>
18270495ed39SKyle EvansFor integer loops,
18280495ed39SKyle Evansthe control variable never wraps around;
18290495ed39SKyle Evansinstead, the loop ends in case of an overflow.
18300495ed39SKyle Evans
18310495ed39SKyle Evans
18320495ed39SKyle Evans<p>
18330495ed39SKyle EvansYou should not change the value of the control variable
18340495ed39SKyle Evansduring the loop.
18358e3e3a7aSWarner LoshIf you need its value after the loop,
18368e3e3a7aSWarner Loshassign it to another variable before exiting the loop.
18378e3e3a7aSWarner Losh
18380495ed39SKyle Evans
18390495ed39SKyle Evans
18400495ed39SKyle Evans
18410495ed39SKyle Evans
18420495ed39SKyle Evans<h4>The generic <b>for</b> loop</h4>
18438e3e3a7aSWarner Losh
18448e3e3a7aSWarner Losh<p>
18458e3e3a7aSWarner LoshThe generic <b>for</b> statement works over functions,
18468e3e3a7aSWarner Loshcalled <em>iterators</em>.
18478e3e3a7aSWarner LoshOn each iteration, the iterator function is called to produce a new value,
18488e3e3a7aSWarner Loshstopping when this new value is <b>nil</b>.
18498e3e3a7aSWarner LoshThe generic <b>for</b> loop has the following syntax:
18508e3e3a7aSWarner Losh
18518e3e3a7aSWarner Losh<pre>
18528e3e3a7aSWarner Losh	stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b>
18538e3e3a7aSWarner Losh	namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
18548e3e3a7aSWarner Losh</pre><p>
18558e3e3a7aSWarner LoshA <b>for</b> statement like
18568e3e3a7aSWarner Losh
18578e3e3a7aSWarner Losh<pre>
18580495ed39SKyle Evans     for <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> in <em>explist</em> do <em>body</em> end
18598e3e3a7aSWarner Losh</pre><p>
18600495ed39SKyle Evansworks as follows.
18618e3e3a7aSWarner Losh
18628e3e3a7aSWarner Losh
18630495ed39SKyle Evans<p>
18640495ed39SKyle EvansThe names <em>var_i</em> declare loop variables local to the loop body.
18650495ed39SKyle EvansThe first of these variables is the <em>control variable</em>.
18668e3e3a7aSWarner Losh
18670495ed39SKyle Evans
18680495ed39SKyle Evans<p>
18690495ed39SKyle EvansThe loop starts by evaluating <em>explist</em>
18700495ed39SKyle Evansto produce four values:
18710495ed39SKyle Evansan <em>iterator function</em>,
18728e3e3a7aSWarner Losha <em>state</em>,
18730495ed39SKyle Evansan initial value for the control variable,
18740495ed39SKyle Evansand a <em>closing value</em>.
18758e3e3a7aSWarner Losh
18768e3e3a7aSWarner Losh
18770495ed39SKyle Evans<p>
18780495ed39SKyle EvansThen, at each iteration,
18790495ed39SKyle EvansLua calls the iterator function with two arguments:
18800495ed39SKyle Evansthe state and the control variable.
18810495ed39SKyle EvansThe results from this call are then assigned to the loop variables,
18820495ed39SKyle Evansfollowing the rules of multiple assignments (see <a href="#3.3.3">&sect;3.3.3</a>).
18830495ed39SKyle EvansIf the control variable becomes <b>nil</b>,
18840495ed39SKyle Evansthe loop terminates.
18850495ed39SKyle EvansOtherwise, the body is executed and the loop goes
18860495ed39SKyle Evansto the next iteration.
18878e3e3a7aSWarner Losh
18888e3e3a7aSWarner Losh
18890495ed39SKyle Evans<p>
18900495ed39SKyle EvansThe closing value behaves like a
18910495ed39SKyle Evansto-be-closed variable (see <a href="#3.3.8">&sect;3.3.8</a>),
18920495ed39SKyle Evanswhich can be used to release resources when the loop ends.
18930495ed39SKyle EvansOtherwise, it does not interfere with the loop.
18940495ed39SKyle Evans
18950495ed39SKyle Evans
18960495ed39SKyle Evans<p>
18970495ed39SKyle EvansYou should not change the value of the control variable
18980495ed39SKyle Evansduring the loop.
18990495ed39SKyle Evans
19000495ed39SKyle Evans
19010495ed39SKyle Evans
19028e3e3a7aSWarner Losh
19038e3e3a7aSWarner Losh
19048e3e3a7aSWarner Losh
19058e3e3a7aSWarner Losh
19068e3e3a7aSWarner Losh<h3>3.3.6 &ndash; <a name="3.3.6">Function Calls as Statements</a></h3><p>
19078e3e3a7aSWarner LoshTo allow possible side-effects,
19088e3e3a7aSWarner Loshfunction calls can be executed as statements:
19098e3e3a7aSWarner Losh
19108e3e3a7aSWarner Losh<pre>
19118e3e3a7aSWarner Losh	stat ::= functioncall
19128e3e3a7aSWarner Losh</pre><p>
19138e3e3a7aSWarner LoshIn this case, all returned values are thrown away.
19148e3e3a7aSWarner LoshFunction calls are explained in <a href="#3.4.10">&sect;3.4.10</a>.
19158e3e3a7aSWarner Losh
19168e3e3a7aSWarner Losh
19178e3e3a7aSWarner Losh
19188e3e3a7aSWarner Losh
19198e3e3a7aSWarner Losh
19208e3e3a7aSWarner Losh<h3>3.3.7 &ndash; <a name="3.3.7">Local Declarations</a></h3><p>
19218e3e3a7aSWarner LoshLocal variables can be declared anywhere inside a block.
19220495ed39SKyle EvansThe declaration can include an initialization:
19238e3e3a7aSWarner Losh
19248e3e3a7aSWarner Losh<pre>
19250495ed39SKyle Evans	stat ::= <b>local</b> attnamelist [&lsquo;<b>=</b>&rsquo; explist]
19260495ed39SKyle Evans	attnamelist ::=  Name attrib {&lsquo;<b>,</b>&rsquo; Name attrib}
19278e3e3a7aSWarner Losh</pre><p>
19288e3e3a7aSWarner LoshIf present, an initial assignment has the same semantics
19298e3e3a7aSWarner Loshof a multiple assignment (see <a href="#3.3.3">&sect;3.3.3</a>).
19308e3e3a7aSWarner LoshOtherwise, all variables are initialized with <b>nil</b>.
19318e3e3a7aSWarner Losh
19328e3e3a7aSWarner Losh
19338e3e3a7aSWarner Losh<p>
19340495ed39SKyle EvansEach variable name may be postfixed by an attribute
19350495ed39SKyle Evans(a name between angle brackets):
19360495ed39SKyle Evans
19370495ed39SKyle Evans<pre>
19380495ed39SKyle Evans	attrib ::= [&lsquo;<b>&lt;</b>&rsquo; Name &lsquo;<b>&gt;</b>&rsquo;]
19390495ed39SKyle Evans</pre><p>
19400495ed39SKyle EvansThere are two possible attributes:
19410495ed39SKyle Evans<code>const</code>, which declares a constant variable,
19420495ed39SKyle Evansthat is, a variable that cannot be assigned to
19430495ed39SKyle Evansafter its initialization;
19440495ed39SKyle Evansand <code>close</code>, which declares a to-be-closed variable (see <a href="#3.3.8">&sect;3.3.8</a>).
19450495ed39SKyle EvansA list of variables can contain at most one to-be-closed variable.
19460495ed39SKyle Evans
19470495ed39SKyle Evans
19480495ed39SKyle Evans<p>
19498e3e3a7aSWarner LoshA chunk is also a block (see <a href="#3.3.2">&sect;3.3.2</a>),
19508e3e3a7aSWarner Loshand so local variables can be declared in a chunk outside any explicit block.
19518e3e3a7aSWarner Losh
19528e3e3a7aSWarner Losh
19538e3e3a7aSWarner Losh<p>
19548e3e3a7aSWarner LoshThe visibility rules for local variables are explained in <a href="#3.5">&sect;3.5</a>.
19558e3e3a7aSWarner Losh
19568e3e3a7aSWarner Losh
19578e3e3a7aSWarner Losh
19588e3e3a7aSWarner Losh
19598e3e3a7aSWarner Losh
19600495ed39SKyle Evans<h3>3.3.8 &ndash; <a name="3.3.8">To-be-closed Variables</a></h3>
19610495ed39SKyle Evans
19620495ed39SKyle Evans<p>
19630495ed39SKyle EvansA to-be-closed variable behaves like a constant local variable,
19640495ed39SKyle Evansexcept that its value is <em>closed</em> whenever the variable
19650495ed39SKyle Evansgoes out of scope, including normal block termination,
19660495ed39SKyle Evansexiting its block by <b>break</b>/<b>goto</b>/<b>return</b>,
19670495ed39SKyle Evansor exiting by an error.
19680495ed39SKyle Evans
19690495ed39SKyle Evans
19700495ed39SKyle Evans<p>
19710495ed39SKyle EvansHere, to <em>close</em> a value means
19720495ed39SKyle Evansto call its <code>__close</code> metamethod.
19730495ed39SKyle EvansWhen calling the metamethod,
19740495ed39SKyle Evansthe value itself is passed as the first argument
19750495ed39SKyle Evansand the error object that caused the exit (if any)
19760495ed39SKyle Evansis passed as a second argument;
19770495ed39SKyle Evansif there was no error, the second argument is <b>nil</b>.
19780495ed39SKyle Evans
19790495ed39SKyle Evans
19800495ed39SKyle Evans<p>
19810495ed39SKyle EvansThe value assigned to a to-be-closed variable
19820495ed39SKyle Evansmust have a <code>__close</code> metamethod
19830495ed39SKyle Evansor be a false value.
19840495ed39SKyle Evans(<b>nil</b> and <b>false</b> are ignored as to-be-closed values.)
19850495ed39SKyle Evans
19860495ed39SKyle Evans
19870495ed39SKyle Evans<p>
19880495ed39SKyle EvansIf several to-be-closed variables go out of scope at the same event,
19890495ed39SKyle Evansthey are closed in the reverse order that they were declared.
19900495ed39SKyle Evans
19910495ed39SKyle Evans
19920495ed39SKyle Evans<p>
19930495ed39SKyle EvansIf there is any error while running a closing method,
19940495ed39SKyle Evansthat error is handled like an error in the regular code
19950495ed39SKyle Evanswhere the variable was defined.
19960495ed39SKyle EvansAfter an error,
19970495ed39SKyle Evansthe other pending closing methods will still be called.
19980495ed39SKyle Evans
19990495ed39SKyle Evans
20000495ed39SKyle Evans<p>
20010495ed39SKyle EvansIf a coroutine yields and is never resumed again,
20020495ed39SKyle Evanssome variables may never go out of scope,
20030495ed39SKyle Evansand therefore they will never be closed.
20040495ed39SKyle Evans(These variables are the ones created inside the coroutine
20050495ed39SKyle Evansand in scope at the point where the coroutine yielded.)
20060495ed39SKyle EvansSimilarly, if a coroutine ends with an error,
20070495ed39SKyle Evansit does not unwind its stack,
20080495ed39SKyle Evansso it does not close any variable.
20090495ed39SKyle EvansIn both cases,
20100495ed39SKyle Evansyou can either use finalizers
20110495ed39SKyle Evansor call <a href="#pdf-coroutine.close"><code>coroutine.close</code></a> to close the variables.
20120495ed39SKyle EvansHowever, if the coroutine was created
20130495ed39SKyle Evansthrough <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a>,
20140495ed39SKyle Evansthen its corresponding function will close the coroutine
20150495ed39SKyle Evansin case of errors.
20160495ed39SKyle Evans
20170495ed39SKyle Evans
20180495ed39SKyle Evans
20190495ed39SKyle Evans
20200495ed39SKyle Evans
20218e3e3a7aSWarner Losh
20228e3e3a7aSWarner Losh
20238e3e3a7aSWarner Losh<h2>3.4 &ndash; <a name="3.4">Expressions</a></h2>
20248e3e3a7aSWarner Losh
20250495ed39SKyle Evans
20260495ed39SKyle Evans
20278e3e3a7aSWarner Losh<p>
20288e3e3a7aSWarner LoshThe basic expressions in Lua are the following:
20298e3e3a7aSWarner Losh
20308e3e3a7aSWarner Losh<pre>
20318e3e3a7aSWarner Losh	exp ::= prefixexp
20328e3e3a7aSWarner Losh	exp ::= <b>nil</b> | <b>false</b> | <b>true</b>
20338e3e3a7aSWarner Losh	exp ::= Numeral
20348e3e3a7aSWarner Losh	exp ::= LiteralString
20358e3e3a7aSWarner Losh	exp ::= functiondef
20368e3e3a7aSWarner Losh	exp ::= tableconstructor
20378e3e3a7aSWarner Losh	exp ::= &lsquo;<b>...</b>&rsquo;
20388e3e3a7aSWarner Losh	exp ::= exp binop exp
20398e3e3a7aSWarner Losh	exp ::= unop exp
20408e3e3a7aSWarner Losh	prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
20418e3e3a7aSWarner Losh</pre>
20428e3e3a7aSWarner Losh
20438e3e3a7aSWarner Losh<p>
20448e3e3a7aSWarner LoshNumerals and literal strings are explained in <a href="#3.1">&sect;3.1</a>;
20458e3e3a7aSWarner Loshvariables are explained in <a href="#3.2">&sect;3.2</a>;
20468e3e3a7aSWarner Loshfunction definitions are explained in <a href="#3.4.11">&sect;3.4.11</a>;
20478e3e3a7aSWarner Loshfunction calls are explained in <a href="#3.4.10">&sect;3.4.10</a>;
20488e3e3a7aSWarner Loshtable constructors are explained in <a href="#3.4.9">&sect;3.4.9</a>.
20498e3e3a7aSWarner LoshVararg expressions,
20508e3e3a7aSWarner Loshdenoted by three dots ('<code>...</code>'), can only be used when
2051a9490b81SWarner Loshdirectly inside a variadic function;
20528e3e3a7aSWarner Loshthey are explained in <a href="#3.4.11">&sect;3.4.11</a>.
20538e3e3a7aSWarner Losh
20548e3e3a7aSWarner Losh
20558e3e3a7aSWarner Losh<p>
20568e3e3a7aSWarner LoshBinary operators comprise arithmetic operators (see <a href="#3.4.1">&sect;3.4.1</a>),
20578e3e3a7aSWarner Loshbitwise operators (see <a href="#3.4.2">&sect;3.4.2</a>),
20588e3e3a7aSWarner Loshrelational operators (see <a href="#3.4.4">&sect;3.4.4</a>), logical operators (see <a href="#3.4.5">&sect;3.4.5</a>),
20598e3e3a7aSWarner Loshand the concatenation operator (see <a href="#3.4.6">&sect;3.4.6</a>).
20608e3e3a7aSWarner LoshUnary operators comprise the unary minus (see <a href="#3.4.1">&sect;3.4.1</a>),
20618e3e3a7aSWarner Loshthe unary bitwise NOT (see <a href="#3.4.2">&sect;3.4.2</a>),
20628e3e3a7aSWarner Loshthe unary logical <b>not</b> (see <a href="#3.4.5">&sect;3.4.5</a>),
20638e3e3a7aSWarner Loshand the unary <em>length operator</em> (see <a href="#3.4.7">&sect;3.4.7</a>).
20648e3e3a7aSWarner Losh
20658e3e3a7aSWarner Losh
20668e3e3a7aSWarner Losh
20670495ed39SKyle Evans
20680495ed39SKyle Evans
20698e3e3a7aSWarner Losh<h3>3.4.1 &ndash; <a name="3.4.1">Arithmetic Operators</a></h3><p>
20708e3e3a7aSWarner LoshLua supports the following arithmetic operators:
20718e3e3a7aSWarner Losh
20728e3e3a7aSWarner Losh<ul>
20738e3e3a7aSWarner Losh<li><b><code>+</code>: </b>addition</li>
20748e3e3a7aSWarner Losh<li><b><code>-</code>: </b>subtraction</li>
20758e3e3a7aSWarner Losh<li><b><code>*</code>: </b>multiplication</li>
20768e3e3a7aSWarner Losh<li><b><code>/</code>: </b>float division</li>
20778e3e3a7aSWarner Losh<li><b><code>//</code>: </b>floor division</li>
20788e3e3a7aSWarner Losh<li><b><code>%</code>: </b>modulo</li>
20798e3e3a7aSWarner Losh<li><b><code>^</code>: </b>exponentiation</li>
20808e3e3a7aSWarner Losh<li><b><code>-</code>: </b>unary minus</li>
20818e3e3a7aSWarner Losh</ul>
20828e3e3a7aSWarner Losh
20838e3e3a7aSWarner Losh<p>
20848e3e3a7aSWarner LoshWith the exception of exponentiation and float division,
20858e3e3a7aSWarner Loshthe arithmetic operators work as follows:
20868e3e3a7aSWarner LoshIf both operands are integers,
20878e3e3a7aSWarner Loshthe operation is performed over integers and the result is an integer.
20880495ed39SKyle EvansOtherwise, if both operands are numbers,
20898e3e3a7aSWarner Loshthen they are converted to floats,
20900495ed39SKyle Evansthe operation is performed following the machine's rules
20918e3e3a7aSWarner Loshfor floating-point arithmetic
20928e3e3a7aSWarner Losh(usually the IEEE 754 standard),
20938e3e3a7aSWarner Loshand the result is a float.
20940495ed39SKyle Evans(The string library coerces strings to numbers in
20950495ed39SKyle Evansarithmetic operations; see <a href="#3.4.3">&sect;3.4.3</a> for details.)
20968e3e3a7aSWarner Losh
20978e3e3a7aSWarner Losh
20988e3e3a7aSWarner Losh<p>
20998e3e3a7aSWarner LoshExponentiation and float division (<code>/</code>)
21008e3e3a7aSWarner Loshalways convert their operands to floats
21018e3e3a7aSWarner Loshand the result is always a float.
21028e3e3a7aSWarner LoshExponentiation uses the ISO&nbsp;C function <code>pow</code>,
21038e3e3a7aSWarner Loshso that it works for non-integer exponents too.
21048e3e3a7aSWarner Losh
21058e3e3a7aSWarner Losh
21068e3e3a7aSWarner Losh<p>
21078e3e3a7aSWarner LoshFloor division (<code>//</code>) is a division
21088e3e3a7aSWarner Loshthat rounds the quotient towards minus infinity,
21090495ed39SKyle Evansresulting in the floor of the division of its operands.
21108e3e3a7aSWarner Losh
21118e3e3a7aSWarner Losh
21128e3e3a7aSWarner Losh<p>
21138e3e3a7aSWarner LoshModulo is defined as the remainder of a division
21148e3e3a7aSWarner Loshthat rounds the quotient towards minus infinity (floor division).
21158e3e3a7aSWarner Losh
21168e3e3a7aSWarner Losh
21178e3e3a7aSWarner Losh<p>
21188e3e3a7aSWarner LoshIn case of overflows in integer arithmetic,
21190495ed39SKyle Evansall operations <em>wrap around</em>.
21208e3e3a7aSWarner Losh
21218e3e3a7aSWarner Losh
21228e3e3a7aSWarner Losh
21238e3e3a7aSWarner Losh<h3>3.4.2 &ndash; <a name="3.4.2">Bitwise Operators</a></h3><p>
21248e3e3a7aSWarner LoshLua supports the following bitwise operators:
21258e3e3a7aSWarner Losh
21268e3e3a7aSWarner Losh<ul>
21278e3e3a7aSWarner Losh<li><b><code>&amp;</code>: </b>bitwise AND</li>
21288e3e3a7aSWarner Losh<li><b><code>&#124;</code>: </b>bitwise OR</li>
21298e3e3a7aSWarner Losh<li><b><code>~</code>: </b>bitwise exclusive OR</li>
21308e3e3a7aSWarner Losh<li><b><code>&gt;&gt;</code>: </b>right shift</li>
21318e3e3a7aSWarner Losh<li><b><code>&lt;&lt;</code>: </b>left shift</li>
21328e3e3a7aSWarner Losh<li><b><code>~</code>: </b>unary bitwise NOT</li>
21338e3e3a7aSWarner Losh</ul>
21348e3e3a7aSWarner Losh
21358e3e3a7aSWarner Losh<p>
21368e3e3a7aSWarner LoshAll bitwise operations convert its operands to integers
21378e3e3a7aSWarner Losh(see <a href="#3.4.3">&sect;3.4.3</a>),
21388e3e3a7aSWarner Loshoperate on all bits of those integers,
21398e3e3a7aSWarner Loshand result in an integer.
21408e3e3a7aSWarner Losh
21418e3e3a7aSWarner Losh
21428e3e3a7aSWarner Losh<p>
21438e3e3a7aSWarner LoshBoth right and left shifts fill the vacant bits with zeros.
21448e3e3a7aSWarner LoshNegative displacements shift to the other direction;
21458e3e3a7aSWarner Loshdisplacements with absolute values equal to or higher than
21468e3e3a7aSWarner Loshthe number of bits in an integer
21478e3e3a7aSWarner Loshresult in zero (as all bits are shifted out).
21488e3e3a7aSWarner Losh
21498e3e3a7aSWarner Losh
21508e3e3a7aSWarner Losh
21518e3e3a7aSWarner Losh
21528e3e3a7aSWarner Losh
21538e3e3a7aSWarner Losh<h3>3.4.3 &ndash; <a name="3.4.3">Coercions and Conversions</a></h3><p>
21548e3e3a7aSWarner LoshLua provides some automatic conversions between some
21558e3e3a7aSWarner Loshtypes and representations at run time.
21568e3e3a7aSWarner LoshBitwise operators always convert float operands to integers.
21578e3e3a7aSWarner LoshExponentiation and float division
21588e3e3a7aSWarner Loshalways convert integer operands to floats.
21598e3e3a7aSWarner LoshAll other arithmetic operations applied to mixed numbers
21600495ed39SKyle Evans(integers and floats) convert the integer operand to a float.
21618e3e3a7aSWarner LoshThe C API also converts both integers to floats and
21628e3e3a7aSWarner Loshfloats to integers, as needed.
21638e3e3a7aSWarner LoshMoreover, string concatenation accepts numbers as arguments,
21648e3e3a7aSWarner Loshbesides strings.
21658e3e3a7aSWarner Losh
21668e3e3a7aSWarner Losh
21678e3e3a7aSWarner Losh<p>
21688e3e3a7aSWarner LoshIn a conversion from integer to float,
21698e3e3a7aSWarner Loshif the integer value has an exact representation as a float,
21708e3e3a7aSWarner Loshthat is the result.
21718e3e3a7aSWarner LoshOtherwise,
21728e3e3a7aSWarner Loshthe conversion gets the nearest higher or
21738e3e3a7aSWarner Loshthe nearest lower representable value.
21748e3e3a7aSWarner LoshThis kind of conversion never fails.
21758e3e3a7aSWarner Losh
21768e3e3a7aSWarner Losh
21778e3e3a7aSWarner Losh<p>
21788e3e3a7aSWarner LoshThe conversion from float to integer
21798e3e3a7aSWarner Loshchecks whether the float has an exact representation as an integer
21808e3e3a7aSWarner Losh(that is, the float has an integral value and
21818e3e3a7aSWarner Loshit is in the range of integer representation).
21828e3e3a7aSWarner LoshIf it does, that representation is the result.
21838e3e3a7aSWarner LoshOtherwise, the conversion fails.
21848e3e3a7aSWarner Losh
21858e3e3a7aSWarner Losh
21868e3e3a7aSWarner Losh<p>
21870495ed39SKyle EvansSeveral places in Lua coerce strings to numbers when necessary.
21880495ed39SKyle EvansIn particular,
21890495ed39SKyle Evansthe string library sets metamethods that try to coerce
21900495ed39SKyle Evansstrings to numbers in all arithmetic operations.
21910495ed39SKyle EvansIf the conversion fails,
21920495ed39SKyle Evansthe library calls the metamethod of the other operand
21930495ed39SKyle Evans(if present) or it raises an error.
21940495ed39SKyle EvansNote that bitwise operators do not do this coercion.
21958e3e3a7aSWarner Losh
21968e3e3a7aSWarner Losh
21978e3e3a7aSWarner Losh<p>
2198a9490b81SWarner LoshIt is always a good practice not to rely on the
2199a9490b81SWarner Loshimplicit coercions from strings to numbers,
2200a9490b81SWarner Loshas they are not always applied;
22010495ed39SKyle Evansin particular, <code>"1"==1</code> is false and <code>"1"&lt;1</code> raises an error
22020495ed39SKyle Evans(see <a href="#3.4.4">&sect;3.4.4</a>).
22030495ed39SKyle EvansThese coercions exist mainly for compatibility and may be removed
22040495ed39SKyle Evansin future versions of the language.
22050495ed39SKyle Evans
22060495ed39SKyle Evans
22070495ed39SKyle Evans<p>
22080495ed39SKyle EvansA string is converted to an integer or a float
22090495ed39SKyle Evansfollowing its syntax and the rules of the Lua lexer.
22100495ed39SKyle EvansThe string may have also leading and trailing whitespaces and a sign.
22118e3e3a7aSWarner LoshAll conversions from strings to numbers
22128e3e3a7aSWarner Loshaccept both a dot and the current locale mark
22138e3e3a7aSWarner Loshas the radix character.
22148e3e3a7aSWarner Losh(The Lua lexer, however, accepts only a dot.)
22150495ed39SKyle EvansIf the string is not a valid numeral,
22160495ed39SKyle Evansthe conversion fails.
22170495ed39SKyle EvansIf necessary, the result of this first step is then converted
22180495ed39SKyle Evansto a specific number subtype following the previous rules
22190495ed39SKyle Evansfor conversions between floats and integers.
22208e3e3a7aSWarner Losh
22218e3e3a7aSWarner Losh
22228e3e3a7aSWarner Losh<p>
22238e3e3a7aSWarner LoshThe conversion from numbers to strings uses a
22248e3e3a7aSWarner Loshnon-specified human-readable format.
22250495ed39SKyle EvansTo convert numbers to strings in any specific way,
22260495ed39SKyle Evansuse the function <a href="#pdf-string.format"><code>string.format</code></a>.
22278e3e3a7aSWarner Losh
22288e3e3a7aSWarner Losh
22298e3e3a7aSWarner Losh
22308e3e3a7aSWarner Losh
22318e3e3a7aSWarner Losh
22328e3e3a7aSWarner Losh<h3>3.4.4 &ndash; <a name="3.4.4">Relational Operators</a></h3><p>
22338e3e3a7aSWarner LoshLua supports the following relational operators:
22348e3e3a7aSWarner Losh
22358e3e3a7aSWarner Losh<ul>
22368e3e3a7aSWarner Losh<li><b><code>==</code>: </b>equality</li>
22378e3e3a7aSWarner Losh<li><b><code>~=</code>: </b>inequality</li>
22388e3e3a7aSWarner Losh<li><b><code>&lt;</code>: </b>less than</li>
22398e3e3a7aSWarner Losh<li><b><code>&gt;</code>: </b>greater than</li>
22408e3e3a7aSWarner Losh<li><b><code>&lt;=</code>: </b>less or equal</li>
22418e3e3a7aSWarner Losh<li><b><code>&gt;=</code>: </b>greater or equal</li>
22428e3e3a7aSWarner Losh</ul><p>
22438e3e3a7aSWarner LoshThese operators always result in <b>false</b> or <b>true</b>.
22448e3e3a7aSWarner Losh
22458e3e3a7aSWarner Losh
22468e3e3a7aSWarner Losh<p>
22478e3e3a7aSWarner LoshEquality (<code>==</code>) first compares the type of its operands.
22488e3e3a7aSWarner LoshIf the types are different, then the result is <b>false</b>.
22498e3e3a7aSWarner LoshOtherwise, the values of the operands are compared.
22500495ed39SKyle EvansStrings are equal if they have the same byte content.
22518e3e3a7aSWarner LoshNumbers are equal if they denote the same mathematical value.
22528e3e3a7aSWarner Losh
22538e3e3a7aSWarner Losh
22548e3e3a7aSWarner Losh<p>
22558e3e3a7aSWarner LoshTables, userdata, and threads
22568e3e3a7aSWarner Loshare compared by reference:
22578e3e3a7aSWarner Loshtwo objects are considered equal only if they are the same object.
22588e3e3a7aSWarner LoshEvery time you create a new object
22590495ed39SKyle Evans(a table, a userdata, or a thread),
22608e3e3a7aSWarner Loshthis new object is different from any previously existing object.
22610495ed39SKyle EvansA function is always equal to itself.
22620495ed39SKyle EvansFunctions with any detectable difference
22638e3e3a7aSWarner Losh(different behavior, different definition) are always different.
22640495ed39SKyle EvansFunctions created at different times but with no detectable differences
2265e112e9d2SKyle Evansmay be classified as equal or not
2266e112e9d2SKyle Evans(depending on internal caching details).
22678e3e3a7aSWarner Losh
22688e3e3a7aSWarner Losh
22698e3e3a7aSWarner Losh<p>
22708e3e3a7aSWarner LoshYou can change the way that Lua compares tables and userdata
22710495ed39SKyle Evansby using the <code>__eq</code> metamethod (see <a href="#2.4">&sect;2.4</a>).
22728e3e3a7aSWarner Losh
22738e3e3a7aSWarner Losh
22748e3e3a7aSWarner Losh<p>
22758e3e3a7aSWarner LoshEquality comparisons do not convert strings to numbers
22768e3e3a7aSWarner Loshor vice versa.
22778e3e3a7aSWarner LoshThus, <code>"0"==0</code> evaluates to <b>false</b>,
22788e3e3a7aSWarner Loshand <code>t[0]</code> and <code>t["0"]</code> denote different
22798e3e3a7aSWarner Loshentries in a table.
22808e3e3a7aSWarner Losh
22818e3e3a7aSWarner Losh
22828e3e3a7aSWarner Losh<p>
22838e3e3a7aSWarner LoshThe operator <code>~=</code> is exactly the negation of equality (<code>==</code>).
22848e3e3a7aSWarner Losh
22858e3e3a7aSWarner Losh
22868e3e3a7aSWarner Losh<p>
22878e3e3a7aSWarner LoshThe order operators work as follows.
22888e3e3a7aSWarner LoshIf both arguments are numbers,
22890495ed39SKyle Evansthen they are compared according to their mathematical values,
22900495ed39SKyle Evansregardless of their subtypes.
22918e3e3a7aSWarner LoshOtherwise, if both arguments are strings,
22928e3e3a7aSWarner Loshthen their values are compared according to the current locale.
22930495ed39SKyle EvansOtherwise, Lua tries to call the <code>__lt</code> or the <code>__le</code>
22948e3e3a7aSWarner Loshmetamethod (see <a href="#2.4">&sect;2.4</a>).
22958e3e3a7aSWarner LoshA comparison <code>a &gt; b</code> is translated to <code>b &lt; a</code>
22968e3e3a7aSWarner Loshand <code>a &gt;= b</code> is translated to <code>b &lt;= a</code>.
22978e3e3a7aSWarner Losh
22988e3e3a7aSWarner Losh
22998e3e3a7aSWarner Losh<p>
23008e3e3a7aSWarner LoshFollowing the IEEE 754 standard,
23010495ed39SKyle Evansthe special value NaN is considered neither less than,
23020495ed39SKyle Evansnor equal to, nor greater than any value, including itself.
23038e3e3a7aSWarner Losh
23048e3e3a7aSWarner Losh
23058e3e3a7aSWarner Losh
23068e3e3a7aSWarner Losh
23078e3e3a7aSWarner Losh
23088e3e3a7aSWarner Losh<h3>3.4.5 &ndash; <a name="3.4.5">Logical Operators</a></h3><p>
23098e3e3a7aSWarner LoshThe logical operators in Lua are
23108e3e3a7aSWarner Losh<b>and</b>, <b>or</b>, and <b>not</b>.
23118e3e3a7aSWarner LoshLike the control structures (see <a href="#3.3.4">&sect;3.3.4</a>),
23128e3e3a7aSWarner Loshall logical operators consider both <b>false</b> and <b>nil</b> as false
23138e3e3a7aSWarner Loshand anything else as true.
23148e3e3a7aSWarner Losh
23158e3e3a7aSWarner Losh
23168e3e3a7aSWarner Losh<p>
23178e3e3a7aSWarner LoshThe negation operator <b>not</b> always returns <b>false</b> or <b>true</b>.
23188e3e3a7aSWarner LoshThe conjunction operator <b>and</b> returns its first argument
23198e3e3a7aSWarner Loshif this value is <b>false</b> or <b>nil</b>;
23208e3e3a7aSWarner Loshotherwise, <b>and</b> returns its second argument.
23218e3e3a7aSWarner LoshThe disjunction operator <b>or</b> returns its first argument
23228e3e3a7aSWarner Loshif this value is different from <b>nil</b> and <b>false</b>;
23238e3e3a7aSWarner Loshotherwise, <b>or</b> returns its second argument.
23248e3e3a7aSWarner LoshBoth <b>and</b> and <b>or</b> use short-circuit evaluation;
23258e3e3a7aSWarner Loshthat is,
23268e3e3a7aSWarner Loshthe second operand is evaluated only if necessary.
23278e3e3a7aSWarner LoshHere are some examples:
23288e3e3a7aSWarner Losh
23298e3e3a7aSWarner Losh<pre>
23308e3e3a7aSWarner Losh     10 or 20            --&gt; 10
23318e3e3a7aSWarner Losh     10 or error()       --&gt; 10
23328e3e3a7aSWarner Losh     nil or "a"          --&gt; "a"
23338e3e3a7aSWarner Losh     nil and 10          --&gt; nil
23348e3e3a7aSWarner Losh     false and error()   --&gt; false
23358e3e3a7aSWarner Losh     false and nil       --&gt; false
23368e3e3a7aSWarner Losh     false or nil        --&gt; nil
23378e3e3a7aSWarner Losh     10 and 20           --&gt; 20
23380495ed39SKyle Evans</pre>
23398e3e3a7aSWarner Losh
23408e3e3a7aSWarner Losh
23418e3e3a7aSWarner Losh
23428e3e3a7aSWarner Losh
23438e3e3a7aSWarner Losh<h3>3.4.6 &ndash; <a name="3.4.6">Concatenation</a></h3><p>
23448e3e3a7aSWarner LoshThe string concatenation operator in Lua is
23458e3e3a7aSWarner Loshdenoted by two dots ('<code>..</code>').
23460495ed39SKyle EvansIf both operands are strings or numbers,
23470495ed39SKyle Evansthen the numbers are converted to strings
23480495ed39SKyle Evansin a non-specified format (see <a href="#3.4.3">&sect;3.4.3</a>).
23498e3e3a7aSWarner LoshOtherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">&sect;2.4</a>).
23508e3e3a7aSWarner Losh
23518e3e3a7aSWarner Losh
23528e3e3a7aSWarner Losh
23538e3e3a7aSWarner Losh
23548e3e3a7aSWarner Losh
23558e3e3a7aSWarner Losh<h3>3.4.7 &ndash; <a name="3.4.7">The Length Operator</a></h3>
23568e3e3a7aSWarner Losh
23578e3e3a7aSWarner Losh<p>
23588e3e3a7aSWarner LoshThe length operator is denoted by the unary prefix operator <code>#</code>.
23598e3e3a7aSWarner Losh
23608e3e3a7aSWarner Losh
23618e3e3a7aSWarner Losh<p>
23620495ed39SKyle EvansThe length of a string is its number of bytes.
23630495ed39SKyle Evans(That is the usual meaning of string length when each
23640495ed39SKyle Evanscharacter is one byte.)
23658e3e3a7aSWarner Losh
23668e3e3a7aSWarner Losh
23678e3e3a7aSWarner Losh<p>
23688e3e3a7aSWarner LoshThe length operator applied on a table
23698e3e3a7aSWarner Loshreturns a border in that table.
23708c784bb8SWarner LoshA <em>border</em> in a table <code>t</code> is any non-negative integer
23718e3e3a7aSWarner Loshthat satisfies the following condition:
23728e3e3a7aSWarner Losh
23738e3e3a7aSWarner Losh<pre>
23748c784bb8SWarner Losh     (border == 0 or t[border] ~= nil) and
23758c784bb8SWarner Losh     (t[border + 1] == nil or border == math.maxinteger)
23768e3e3a7aSWarner Losh</pre><p>
23778e3e3a7aSWarner LoshIn words,
23788c784bb8SWarner Losha border is any positive integer index present in the table
23798c784bb8SWarner Loshthat is followed by an absent index,
23808c784bb8SWarner Loshplus two limit cases:
23818c784bb8SWarner Loshzero, when index 1 is absent;
23828c784bb8SWarner Loshand the maximum value for an integer, when that index is present.
23838c784bb8SWarner LoshNote that keys that are not positive integers
23848c784bb8SWarner Loshdo not interfere with borders.
23858e3e3a7aSWarner Losh
23868e3e3a7aSWarner Losh
23878e3e3a7aSWarner Losh<p>
23888e3e3a7aSWarner LoshA table with exactly one border is called a <em>sequence</em>.
23898e3e3a7aSWarner LoshFor instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence,
23908e3e3a7aSWarner Loshas it has only one border (5).
23918e3e3a7aSWarner LoshThe table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5),
23928e3e3a7aSWarner Loshand therefore it is not a sequence.
23930495ed39SKyle Evans(The <b>nil</b> at index 4 is called a <em>hole</em>.)
23948e3e3a7aSWarner LoshThe table <code>{nil, 20, 30, nil, nil, 60, nil}</code>
23958c784bb8SWarner Loshhas three borders (0, 3, and 6),
23968e3e3a7aSWarner Loshso it is not a sequence, too.
23978e3e3a7aSWarner LoshThe table <code>{}</code> is a sequence with border 0.
23988e3e3a7aSWarner Losh
23998e3e3a7aSWarner Losh
24008e3e3a7aSWarner Losh<p>
24018e3e3a7aSWarner LoshWhen <code>t</code> is a sequence,
24028e3e3a7aSWarner Losh<code>#t</code> returns its only border,
24038e3e3a7aSWarner Loshwhich corresponds to the intuitive notion of the length of the sequence.
24048e3e3a7aSWarner LoshWhen <code>t</code> is not a sequence,
24058e3e3a7aSWarner Losh<code>#t</code> can return any of its borders.
24068e3e3a7aSWarner Losh(The exact one depends on details of
24078e3e3a7aSWarner Loshthe internal representation of the table,
24088e3e3a7aSWarner Loshwhich in turn can depend on how the table was populated and
24098e3e3a7aSWarner Loshthe memory addresses of its non-numeric keys.)
24108e3e3a7aSWarner Losh
24118e3e3a7aSWarner Losh
24128e3e3a7aSWarner Losh<p>
24138e3e3a7aSWarner LoshThe computation of the length of a table
24148e3e3a7aSWarner Loshhas a guaranteed worst time of <em>O(log n)</em>,
24158c784bb8SWarner Loshwhere <em>n</em> is the largest integer key in the table.
24168e3e3a7aSWarner Losh
24178e3e3a7aSWarner Losh
24188e3e3a7aSWarner Losh<p>
24198e3e3a7aSWarner LoshA program can modify the behavior of the length operator for
24208e3e3a7aSWarner Loshany value but strings through the <code>__len</code> metamethod (see <a href="#2.4">&sect;2.4</a>).
24218e3e3a7aSWarner Losh
24228e3e3a7aSWarner Losh
24238e3e3a7aSWarner Losh
24248e3e3a7aSWarner Losh
24258e3e3a7aSWarner Losh
24268e3e3a7aSWarner Losh<h3>3.4.8 &ndash; <a name="3.4.8">Precedence</a></h3><p>
24278e3e3a7aSWarner LoshOperator precedence in Lua follows the table below,
24288e3e3a7aSWarner Loshfrom lower to higher priority:
24298e3e3a7aSWarner Losh
24308e3e3a7aSWarner Losh<pre>
24318e3e3a7aSWarner Losh     or
24328e3e3a7aSWarner Losh     and
24338e3e3a7aSWarner Losh     &lt;     &gt;     &lt;=    &gt;=    ~=    ==
24348e3e3a7aSWarner Losh     |
24358e3e3a7aSWarner Losh     ~
24368e3e3a7aSWarner Losh     &amp;
24378e3e3a7aSWarner Losh     &lt;&lt;    &gt;&gt;
24388e3e3a7aSWarner Losh     ..
24398e3e3a7aSWarner Losh     +     -
24408e3e3a7aSWarner Losh     *     /     //    %
24418e3e3a7aSWarner Losh     unary operators (not   #     -     ~)
24428e3e3a7aSWarner Losh     ^
24438e3e3a7aSWarner Losh</pre><p>
24448e3e3a7aSWarner LoshAs usual,
24458e3e3a7aSWarner Loshyou can use parentheses to change the precedences of an expression.
24468e3e3a7aSWarner LoshThe concatenation ('<code>..</code>') and exponentiation ('<code>^</code>')
24478e3e3a7aSWarner Loshoperators are right associative.
24488e3e3a7aSWarner LoshAll other binary operators are left associative.
24498e3e3a7aSWarner Losh
24508e3e3a7aSWarner Losh
24518e3e3a7aSWarner Losh
24528e3e3a7aSWarner Losh
24538e3e3a7aSWarner Losh
24548e3e3a7aSWarner Losh<h3>3.4.9 &ndash; <a name="3.4.9">Table Constructors</a></h3><p>
24558e3e3a7aSWarner LoshTable constructors are expressions that create tables.
24568e3e3a7aSWarner LoshEvery time a constructor is evaluated, a new table is created.
24578e3e3a7aSWarner LoshA constructor can be used to create an empty table
24588e3e3a7aSWarner Loshor to create a table and initialize some of its fields.
24598e3e3a7aSWarner LoshThe general syntax for constructors is
24608e3e3a7aSWarner Losh
24618e3e3a7aSWarner Losh<pre>
24628e3e3a7aSWarner Losh	tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
24638e3e3a7aSWarner Losh	fieldlist ::= field {fieldsep field} [fieldsep]
24648e3e3a7aSWarner Losh	field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
24658e3e3a7aSWarner Losh	fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
24668e3e3a7aSWarner Losh</pre>
24678e3e3a7aSWarner Losh
24688e3e3a7aSWarner Losh<p>
24698e3e3a7aSWarner LoshEach field of the form <code>[exp1] = exp2</code> adds to the new table an entry
24708e3e3a7aSWarner Loshwith key <code>exp1</code> and value <code>exp2</code>.
24718e3e3a7aSWarner LoshA field of the form <code>name = exp</code> is equivalent to
24728e3e3a7aSWarner Losh<code>["name"] = exp</code>.
24730495ed39SKyle EvansFields of the form <code>exp</code> are equivalent to
24748e3e3a7aSWarner Losh<code>[i] = exp</code>, where <code>i</code> are consecutive integers
24750495ed39SKyle Evansstarting with 1;
24760495ed39SKyle Evansfields in the other formats do not affect this counting.
24778e3e3a7aSWarner LoshFor example,
24788e3e3a7aSWarner Losh
24798e3e3a7aSWarner Losh<pre>
24808e3e3a7aSWarner Losh     a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
24818e3e3a7aSWarner Losh</pre><p>
24828e3e3a7aSWarner Loshis equivalent to
24838e3e3a7aSWarner Losh
24848e3e3a7aSWarner Losh<pre>
24858e3e3a7aSWarner Losh     do
24868e3e3a7aSWarner Losh       local t = {}
24878e3e3a7aSWarner Losh       t[f(1)] = g
24888e3e3a7aSWarner Losh       t[1] = "x"         -- 1st exp
24898e3e3a7aSWarner Losh       t[2] = "y"         -- 2nd exp
24908e3e3a7aSWarner Losh       t.x = 1            -- t["x"] = 1
24918e3e3a7aSWarner Losh       t[3] = f(x)        -- 3rd exp
24928e3e3a7aSWarner Losh       t[30] = 23
24938e3e3a7aSWarner Losh       t[4] = 45          -- 4th exp
24948e3e3a7aSWarner Losh       a = t
24958e3e3a7aSWarner Losh     end
24968e3e3a7aSWarner Losh</pre>
24978e3e3a7aSWarner Losh
24988e3e3a7aSWarner Losh<p>
24998e3e3a7aSWarner LoshThe order of the assignments in a constructor is undefined.
25008e3e3a7aSWarner Losh(This order would be relevant only when there are repeated keys.)
25018e3e3a7aSWarner Losh
25028e3e3a7aSWarner Losh
25038e3e3a7aSWarner Losh<p>
25048e3e3a7aSWarner LoshIf the last field in the list has the form <code>exp</code>
2505a9490b81SWarner Loshand the expression is a multires expression,
25068e3e3a7aSWarner Loshthen all values returned by this expression enter the list consecutively
2507a9490b81SWarner Losh(see <a href="#3.4.12">&sect;3.4.12</a>).
25088e3e3a7aSWarner Losh
25098e3e3a7aSWarner Losh
25108e3e3a7aSWarner Losh<p>
25118e3e3a7aSWarner LoshThe field list can have an optional trailing separator,
25128e3e3a7aSWarner Loshas a convenience for machine-generated code.
25138e3e3a7aSWarner Losh
25148e3e3a7aSWarner Losh
25158e3e3a7aSWarner Losh
25168e3e3a7aSWarner Losh
25178e3e3a7aSWarner Losh
25188e3e3a7aSWarner Losh<h3>3.4.10 &ndash; <a name="3.4.10">Function Calls</a></h3><p>
25198e3e3a7aSWarner LoshA function call in Lua has the following syntax:
25208e3e3a7aSWarner Losh
25218e3e3a7aSWarner Losh<pre>
25228e3e3a7aSWarner Losh	functioncall ::= prefixexp args
25238e3e3a7aSWarner Losh</pre><p>
25248e3e3a7aSWarner LoshIn a function call,
25258e3e3a7aSWarner Loshfirst prefixexp and args are evaluated.
25268e3e3a7aSWarner LoshIf the value of prefixexp has type <em>function</em>,
25278e3e3a7aSWarner Loshthen this function is called
25288e3e3a7aSWarner Loshwith the given arguments.
25290495ed39SKyle EvansOtherwise, if present,
25300495ed39SKyle Evansthe prefixexp <code>__call</code> metamethod is called:
25310495ed39SKyle Evansits first argument is the value of prefixexp,
25328e3e3a7aSWarner Loshfollowed by the original call arguments
25338e3e3a7aSWarner Losh(see <a href="#2.4">&sect;2.4</a>).
25348e3e3a7aSWarner Losh
25358e3e3a7aSWarner Losh
25368e3e3a7aSWarner Losh<p>
25378e3e3a7aSWarner LoshThe form
25388e3e3a7aSWarner Losh
25398e3e3a7aSWarner Losh<pre>
25408e3e3a7aSWarner Losh	functioncall ::= prefixexp &lsquo;<b>:</b>&rsquo; Name args
25418e3e3a7aSWarner Losh</pre><p>
25420495ed39SKyle Evanscan be used to emulate methods.
25438e3e3a7aSWarner LoshA call <code>v:name(<em>args</em>)</code>
25448e3e3a7aSWarner Loshis syntactic sugar for <code>v.name(v,<em>args</em>)</code>,
25458e3e3a7aSWarner Loshexcept that <code>v</code> is evaluated only once.
25468e3e3a7aSWarner Losh
25478e3e3a7aSWarner Losh
25488e3e3a7aSWarner Losh<p>
25498e3e3a7aSWarner LoshArguments have the following syntax:
25508e3e3a7aSWarner Losh
25518e3e3a7aSWarner Losh<pre>
25528e3e3a7aSWarner Losh	args ::= &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo;
25538e3e3a7aSWarner Losh	args ::= tableconstructor
25548e3e3a7aSWarner Losh	args ::= LiteralString
25558e3e3a7aSWarner Losh</pre><p>
25568e3e3a7aSWarner LoshAll argument expressions are evaluated before the call.
25578e3e3a7aSWarner LoshA call of the form <code>f{<em>fields</em>}</code> is
25588e3e3a7aSWarner Loshsyntactic sugar for <code>f({<em>fields</em>})</code>;
25598e3e3a7aSWarner Loshthat is, the argument list is a single new table.
25608e3e3a7aSWarner LoshA call of the form <code>f'<em>string</em>'</code>
25618e3e3a7aSWarner Losh(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>)
25628e3e3a7aSWarner Loshis syntactic sugar for <code>f('<em>string</em>')</code>;
25638e3e3a7aSWarner Loshthat is, the argument list is a single literal string.
25648e3e3a7aSWarner Losh
25658e3e3a7aSWarner Losh
25668e3e3a7aSWarner Losh<p>
25670495ed39SKyle EvansA call of the form <code>return <em>functioncall</em></code> not in the
25680495ed39SKyle Evansscope of a to-be-closed variable is called a <em>tail call</em>.
25698e3e3a7aSWarner LoshLua implements <em>proper tail calls</em>
25708e3e3a7aSWarner Losh(or <em>proper tail recursion</em>):
2571a9490b81SWarner LoshIn a tail call,
25728e3e3a7aSWarner Loshthe called function reuses the stack entry of the calling function.
25738e3e3a7aSWarner LoshTherefore, there is no limit on the number of nested tail calls that
25748e3e3a7aSWarner Losha program can execute.
25758e3e3a7aSWarner LoshHowever, a tail call erases any debug information about the
25768e3e3a7aSWarner Loshcalling function.
25778e3e3a7aSWarner LoshNote that a tail call only happens with a particular syntax,
25780495ed39SKyle Evanswhere the <b>return</b> has one single function call as argument,
25790495ed39SKyle Evansand it is outside the scope of any to-be-closed variable.
25800495ed39SKyle EvansThis syntax makes the calling function return exactly
25810495ed39SKyle Evansthe returns of the called function,
25820495ed39SKyle Evanswithout any intervening action.
25838e3e3a7aSWarner LoshSo, none of the following examples are tail calls:
25848e3e3a7aSWarner Losh
25858e3e3a7aSWarner Losh<pre>
25868e3e3a7aSWarner Losh     return (f(x))        -- results adjusted to 1
25870495ed39SKyle Evans     return 2 * f(x)      -- result multiplied by 2
25888e3e3a7aSWarner Losh     return x, f(x)       -- additional results
25898e3e3a7aSWarner Losh     f(x); return         -- results discarded
25908e3e3a7aSWarner Losh     return x or f(x)     -- results adjusted to 1
25918e3e3a7aSWarner Losh</pre>
25928e3e3a7aSWarner Losh
25938e3e3a7aSWarner Losh
25948e3e3a7aSWarner Losh
25958e3e3a7aSWarner Losh
25968e3e3a7aSWarner Losh<h3>3.4.11 &ndash; <a name="3.4.11">Function Definitions</a></h3>
25978e3e3a7aSWarner Losh
25988e3e3a7aSWarner Losh<p>
25998e3e3a7aSWarner LoshThe syntax for function definition is
26008e3e3a7aSWarner Losh
26018e3e3a7aSWarner Losh<pre>
26028e3e3a7aSWarner Losh	functiondef ::= <b>function</b> funcbody
26038e3e3a7aSWarner Losh	funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
26048e3e3a7aSWarner Losh</pre>
26058e3e3a7aSWarner Losh
26068e3e3a7aSWarner Losh<p>
26078e3e3a7aSWarner LoshThe following syntactic sugar simplifies function definitions:
26088e3e3a7aSWarner Losh
26098e3e3a7aSWarner Losh<pre>
26108e3e3a7aSWarner Losh	stat ::= <b>function</b> funcname funcbody
26118e3e3a7aSWarner Losh	stat ::= <b>local</b> <b>function</b> Name funcbody
26128e3e3a7aSWarner Losh	funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
26138e3e3a7aSWarner Losh</pre><p>
26148e3e3a7aSWarner LoshThe statement
26158e3e3a7aSWarner Losh
26168e3e3a7aSWarner Losh<pre>
26178e3e3a7aSWarner Losh     function f () <em>body</em> end
26188e3e3a7aSWarner Losh</pre><p>
26198e3e3a7aSWarner Loshtranslates to
26208e3e3a7aSWarner Losh
26218e3e3a7aSWarner Losh<pre>
26228e3e3a7aSWarner Losh     f = function () <em>body</em> end
26238e3e3a7aSWarner Losh</pre><p>
26248e3e3a7aSWarner LoshThe statement
26258e3e3a7aSWarner Losh
26268e3e3a7aSWarner Losh<pre>
26278e3e3a7aSWarner Losh     function t.a.b.c.f () <em>body</em> end
26288e3e3a7aSWarner Losh</pre><p>
26298e3e3a7aSWarner Loshtranslates to
26308e3e3a7aSWarner Losh
26318e3e3a7aSWarner Losh<pre>
26328e3e3a7aSWarner Losh     t.a.b.c.f = function () <em>body</em> end
26338e3e3a7aSWarner Losh</pre><p>
26348e3e3a7aSWarner LoshThe statement
26358e3e3a7aSWarner Losh
26368e3e3a7aSWarner Losh<pre>
26378e3e3a7aSWarner Losh     local function f () <em>body</em> end
26388e3e3a7aSWarner Losh</pre><p>
26398e3e3a7aSWarner Loshtranslates to
26408e3e3a7aSWarner Losh
26418e3e3a7aSWarner Losh<pre>
26428e3e3a7aSWarner Losh     local f; f = function () <em>body</em> end
26438e3e3a7aSWarner Losh</pre><p>
26448e3e3a7aSWarner Loshnot to
26458e3e3a7aSWarner Losh
26468e3e3a7aSWarner Losh<pre>
26478e3e3a7aSWarner Losh     local f = function () <em>body</em> end
26488e3e3a7aSWarner Losh</pre><p>
26498e3e3a7aSWarner Losh(This only makes a difference when the body of the function
26508e3e3a7aSWarner Loshcontains references to <code>f</code>.)
26518e3e3a7aSWarner Losh
26528e3e3a7aSWarner Losh
26538e3e3a7aSWarner Losh<p>
26548e3e3a7aSWarner LoshA function definition is an executable expression,
26558e3e3a7aSWarner Loshwhose value has type <em>function</em>.
26568e3e3a7aSWarner LoshWhen Lua precompiles a chunk,
26570495ed39SKyle Evansall its function bodies are precompiled too,
26580495ed39SKyle Evansbut they are not created yet.
26598e3e3a7aSWarner LoshThen, whenever Lua executes the function definition,
26608e3e3a7aSWarner Loshthe function is <em>instantiated</em> (or <em>closed</em>).
26610495ed39SKyle EvansThis function instance, or <em>closure</em>,
26628e3e3a7aSWarner Loshis the final value of the expression.
26638e3e3a7aSWarner Losh
26648e3e3a7aSWarner Losh
26658e3e3a7aSWarner Losh<p>
26668e3e3a7aSWarner LoshParameters act as local variables that are
26678e3e3a7aSWarner Loshinitialized with the argument values:
26688e3e3a7aSWarner Losh
26698e3e3a7aSWarner Losh<pre>
26708e3e3a7aSWarner Losh	parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
26718e3e3a7aSWarner Losh</pre><p>
26720495ed39SKyle EvansWhen a Lua function is called,
26730495ed39SKyle Evansit adjusts its list of arguments to
2674a9490b81SWarner Loshthe length of its list of parameters (see <a href="#3.4.12">&sect;3.4.12</a>),
2675a9490b81SWarner Loshunless the function is a <em>variadic function</em>,
26768e3e3a7aSWarner Loshwhich is indicated by three dots ('<code>...</code>')
26778e3e3a7aSWarner Loshat the end of its parameter list.
2678a9490b81SWarner LoshA variadic function does not adjust its argument list;
26798e3e3a7aSWarner Loshinstead, it collects all extra arguments and supplies them
26808e3e3a7aSWarner Loshto the function through a <em>vararg expression</em>,
26818e3e3a7aSWarner Loshwhich is also written as three dots.
26828e3e3a7aSWarner LoshThe value of this expression is a list of all actual extra arguments,
2683a9490b81SWarner Loshsimilar to a function with multiple results (see <a href="#3.4.12">&sect;3.4.12</a>).
26848e3e3a7aSWarner Losh
26858e3e3a7aSWarner Losh
26868e3e3a7aSWarner Losh<p>
26878e3e3a7aSWarner LoshAs an example, consider the following definitions:
26888e3e3a7aSWarner Losh
26898e3e3a7aSWarner Losh<pre>
26908e3e3a7aSWarner Losh     function f(a, b) end
26918e3e3a7aSWarner Losh     function g(a, b, ...) end
26928e3e3a7aSWarner Losh     function r() return 1,2,3 end
26938e3e3a7aSWarner Losh</pre><p>
26948e3e3a7aSWarner LoshThen, we have the following mapping from arguments to parameters and
26958e3e3a7aSWarner Loshto the vararg expression:
26968e3e3a7aSWarner Losh
26978e3e3a7aSWarner Losh<pre>
26988e3e3a7aSWarner Losh     CALL             PARAMETERS
26998e3e3a7aSWarner Losh
27008e3e3a7aSWarner Losh     f(3)             a=3, b=nil
27018e3e3a7aSWarner Losh     f(3, 4)          a=3, b=4
27028e3e3a7aSWarner Losh     f(3, 4, 5)       a=3, b=4
27038e3e3a7aSWarner Losh     f(r(), 10)       a=1, b=10
27048e3e3a7aSWarner Losh     f(r())           a=1, b=2
27058e3e3a7aSWarner Losh
27068e3e3a7aSWarner Losh     g(3)             a=3, b=nil, ... --&gt;  (nothing)
27078e3e3a7aSWarner Losh     g(3, 4)          a=3, b=4,   ... --&gt;  (nothing)
27088e3e3a7aSWarner Losh     g(3, 4, 5, 8)    a=3, b=4,   ... --&gt;  5  8
27098e3e3a7aSWarner Losh     g(5, r())        a=5, b=1,   ... --&gt;  2  3
27108e3e3a7aSWarner Losh</pre>
27118e3e3a7aSWarner Losh
27128e3e3a7aSWarner Losh<p>
27138e3e3a7aSWarner LoshResults are returned using the <b>return</b> statement (see <a href="#3.3.4">&sect;3.3.4</a>).
27148e3e3a7aSWarner LoshIf control reaches the end of a function
27158e3e3a7aSWarner Loshwithout encountering a <b>return</b> statement,
27168e3e3a7aSWarner Loshthen the function returns with no results.
27178e3e3a7aSWarner Losh
27188e3e3a7aSWarner Losh
27198e3e3a7aSWarner Losh<p>
27208e3e3a7aSWarner Losh
27218e3e3a7aSWarner LoshThere is a system-dependent limit on the number of values
27228e3e3a7aSWarner Loshthat a function may return.
27230495ed39SKyle EvansThis limit is guaranteed to be greater than 1000.
27248e3e3a7aSWarner Losh
27258e3e3a7aSWarner Losh
27268e3e3a7aSWarner Losh<p>
27278e3e3a7aSWarner LoshThe <em>colon</em> syntax
27280495ed39SKyle Evansis used to emulate <em>methods</em>,
27290495ed39SKyle Evansadding an implicit extra parameter <code>self</code> to the function.
27308e3e3a7aSWarner LoshThus, the statement
27318e3e3a7aSWarner Losh
27328e3e3a7aSWarner Losh<pre>
27338e3e3a7aSWarner Losh     function t.a.b.c:f (<em>params</em>) <em>body</em> end
27348e3e3a7aSWarner Losh</pre><p>
27358e3e3a7aSWarner Loshis syntactic sugar for
27368e3e3a7aSWarner Losh
27378e3e3a7aSWarner Losh<pre>
27388e3e3a7aSWarner Losh     t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end
27398e3e3a7aSWarner Losh</pre>
27408e3e3a7aSWarner Losh
27418e3e3a7aSWarner Losh
27428e3e3a7aSWarner Losh
27438e3e3a7aSWarner Losh
2744a9490b81SWarner Losh<h3>3.4.12 &ndash; <a name="3.4.12">Lists of expressions, multiple results,
2745a9490b81SWarner Loshand adjustment</a></h3>
2746a9490b81SWarner Losh
2747a9490b81SWarner Losh<p>
2748a9490b81SWarner LoshBoth function calls and vararg expressions can result in multiple values.
2749a9490b81SWarner LoshThese expressions are called <em>multires expressions</em>.
2750a9490b81SWarner Losh
2751a9490b81SWarner Losh
2752a9490b81SWarner Losh<p>
2753a9490b81SWarner LoshWhen a multires expression is used as the last element
2754a9490b81SWarner Loshof a list of expressions,
2755a9490b81SWarner Loshall results from the expression are added to the
2756a9490b81SWarner Loshlist of values produced by the list of expressions.
2757a9490b81SWarner LoshNote that a single expression
2758a9490b81SWarner Loshin a place that expects a list of expressions
2759a9490b81SWarner Loshis the last expression in that (singleton) list.
2760a9490b81SWarner Losh
2761a9490b81SWarner Losh
2762a9490b81SWarner Losh<p>
2763a9490b81SWarner LoshThese are the places where Lua expects a list of expressions:
2764a9490b81SWarner Losh
2765a9490b81SWarner Losh<ul>
2766a9490b81SWarner Losh
2767a9490b81SWarner Losh<li>A <b>return</b> statement,
2768a9490b81SWarner Loshfor instance <code>return e1, e2, e3</code> (see <a href="#3.3.4">&sect;3.3.4</a>).</li>
2769a9490b81SWarner Losh
2770a9490b81SWarner Losh<li>A table constructor,
2771a9490b81SWarner Loshfor instance <code>{e1, e2, e3}</code> (see <a href="#3.4.9">&sect;3.4.9</a>).</li>
2772a9490b81SWarner Losh
2773a9490b81SWarner Losh<li>The arguments of a function call,
2774a9490b81SWarner Loshfor instance <code>foo(e1, e2, e3)</code> (see <a href="#3.4.10">&sect;3.4.10</a>).</li>
2775a9490b81SWarner Losh
2776a9490b81SWarner Losh<li>A multiple assignment,
2777a9490b81SWarner Loshfor instance <code>a , b, c = e1, e2, e3</code> (see <a href="#3.3.3">&sect;3.3.3</a>).</li>
2778a9490b81SWarner Losh
2779a9490b81SWarner Losh<li>A local declaration,
2780a9490b81SWarner Loshfor instance <code>local a , b, c = e1, e2, e3</code> (see <a href="#3.3.7">&sect;3.3.7</a>).</li>
2781a9490b81SWarner Losh
2782a9490b81SWarner Losh<li>The initial values in a generic <b>for</b> loop,
2783a9490b81SWarner Loshfor instance <code>for k in e1, e2, e3 do ... end</code> (see <a href="#3.3.5">&sect;3.3.5</a>).</li>
2784a9490b81SWarner Losh
2785a9490b81SWarner Losh</ul><p>
2786a9490b81SWarner LoshIn the last four cases,
2787a9490b81SWarner Loshthe list of values from the list of expressions
2788a9490b81SWarner Loshmust be <em>adjusted</em> to a specific length:
2789a9490b81SWarner Loshthe number of parameters in a call to a non-variadic function
2790a9490b81SWarner Losh(see <a href="#3.4.11">&sect;3.4.11</a>),
2791a9490b81SWarner Loshthe number of variables in a multiple assignment or
2792a9490b81SWarner Losha local declaration,
2793a9490b81SWarner Loshand exactly four values for a generic <b>for</b> loop.
2794a9490b81SWarner LoshThe <em>adjustment</em> follows these rules:
2795a9490b81SWarner LoshIf there are more values than needed,
2796a9490b81SWarner Loshthe extra values are thrown away;
2797a9490b81SWarner Loshif there are fewer values than needed,
2798a9490b81SWarner Loshthe list is extended with <b>nil</b>'s.
2799a9490b81SWarner LoshWhen the list of expressions ends with a multires expression,
2800a9490b81SWarner Loshall results from that expression enter the list of values
2801a9490b81SWarner Loshbefore the adjustment.
2802a9490b81SWarner Losh
2803a9490b81SWarner Losh
2804a9490b81SWarner Losh<p>
2805a9490b81SWarner LoshWhen a multires expression is used
2806a9490b81SWarner Loshin a list of expressions without being the last element,
2807a9490b81SWarner Loshor in a place where the syntax expects a single expression,
2808a9490b81SWarner LoshLua adjusts the result list of that expression to one element.
2809a9490b81SWarner LoshAs a particular case,
2810a9490b81SWarner Loshthe syntax expects a single expression inside a parenthesized expression;
2811a9490b81SWarner Loshtherefore, adding parentheses around a multires expression
2812a9490b81SWarner Loshforces it to produce exactly one result.
2813a9490b81SWarner Losh
2814a9490b81SWarner Losh
2815a9490b81SWarner Losh<p>
2816a9490b81SWarner LoshWe seldom need to use a vararg expression in a place
2817a9490b81SWarner Loshwhere the syntax expects a single expression.
2818a9490b81SWarner Losh(Usually it is simpler to add a regular parameter before
2819a9490b81SWarner Loshthe variadic part and use that parameter.)
2820a9490b81SWarner LoshWhen there is such a need,
2821a9490b81SWarner Loshwe recommend assigning the vararg expression
2822a9490b81SWarner Loshto a single variable and using that variable
2823a9490b81SWarner Loshin its place.
2824a9490b81SWarner Losh
2825a9490b81SWarner Losh
2826a9490b81SWarner Losh<p>
2827a9490b81SWarner LoshHere are some examples of uses of mutlres expressions.
2828a9490b81SWarner LoshIn all cases, when the construction needs
2829a9490b81SWarner Losh"the n-th result" and there is no such result,
2830a9490b81SWarner Loshit uses a <b>nil</b>.
2831a9490b81SWarner Losh
2832a9490b81SWarner Losh<pre>
2833a9490b81SWarner Losh     print(x, f())      -- prints x and all results from f().
2834a9490b81SWarner Losh     print(x, (f()))    -- prints x and the first result from f().
2835a9490b81SWarner Losh     print(f(), x)      -- prints the first result from f() and x.
2836a9490b81SWarner Losh     print(1 + f())     -- prints 1 added to the first result from f().
2837a9490b81SWarner Losh     local x = ...      -- x gets the first vararg argument.
2838a9490b81SWarner Losh     x,y = ...          -- x gets the first vararg argument,
2839a9490b81SWarner Losh                        -- y gets the second vararg argument.
2840a9490b81SWarner Losh     x,y,z = w, f()     -- x gets w, y gets the first result from f(),
2841a9490b81SWarner Losh                        -- z gets the second result from f().
2842a9490b81SWarner Losh     x,y,z = f()        -- x gets the first result from f(),
2843a9490b81SWarner Losh                        -- y gets the second result from f(),
2844a9490b81SWarner Losh                        -- z gets the third result from f().
2845a9490b81SWarner Losh     x,y,z = f(), g()   -- x gets the first result from f(),
2846a9490b81SWarner Losh                        -- y gets the first result from g(),
2847a9490b81SWarner Losh                        -- z gets the second result from g().
2848a9490b81SWarner Losh     x,y,z = (f())      -- x gets the first result from f(), y and z get nil.
2849a9490b81SWarner Losh     return f()         -- returns all results from f().
2850a9490b81SWarner Losh     return x, ...      -- returns x and all received vararg arguments.
2851a9490b81SWarner Losh     return x,y,f()     -- returns x, y, and all results from f().
2852a9490b81SWarner Losh     {f()}              -- creates a list with all results from f().
2853a9490b81SWarner Losh     {...}              -- creates a list with all vararg arguments.
2854a9490b81SWarner Losh     {f(), 5}           -- creates a list with the first result from f() and 5.
2855a9490b81SWarner Losh</pre>
2856a9490b81SWarner Losh
2857a9490b81SWarner Losh
2858a9490b81SWarner Losh
2859a9490b81SWarner Losh
28608e3e3a7aSWarner Losh
28618e3e3a7aSWarner Losh
28628e3e3a7aSWarner Losh<h2>3.5 &ndash; <a name="3.5">Visibility Rules</a></h2>
28638e3e3a7aSWarner Losh
28648e3e3a7aSWarner Losh<p>
28658e3e3a7aSWarner Losh
28668e3e3a7aSWarner LoshLua is a lexically scoped language.
28678e3e3a7aSWarner LoshThe scope of a local variable begins at the first statement after
28688e3e3a7aSWarner Loshits declaration and lasts until the last non-void statement
28698e3e3a7aSWarner Loshof the innermost block that includes the declaration.
2870a9490b81SWarner Losh(<em>Void statements</em> are labels and empty statements.)
28718e3e3a7aSWarner LoshConsider the following example:
28728e3e3a7aSWarner Losh
28738e3e3a7aSWarner Losh<pre>
28748e3e3a7aSWarner Losh     x = 10                -- global variable
28758e3e3a7aSWarner Losh     do                    -- new block
28768e3e3a7aSWarner Losh       local x = x         -- new 'x', with value 10
28778e3e3a7aSWarner Losh       print(x)            --&gt; 10
28788e3e3a7aSWarner Losh       x = x+1
28798e3e3a7aSWarner Losh       do                  -- another block
28808e3e3a7aSWarner Losh         local x = x+1     -- another 'x'
28818e3e3a7aSWarner Losh         print(x)          --&gt; 12
28828e3e3a7aSWarner Losh       end
28838e3e3a7aSWarner Losh       print(x)            --&gt; 11
28848e3e3a7aSWarner Losh     end
28858e3e3a7aSWarner Losh     print(x)              --&gt; 10  (the global one)
28868e3e3a7aSWarner Losh</pre>
28878e3e3a7aSWarner Losh
28888e3e3a7aSWarner Losh<p>
28898e3e3a7aSWarner LoshNotice that, in a declaration like <code>local x = x</code>,
28908e3e3a7aSWarner Loshthe new <code>x</code> being declared is not in scope yet,
28918e3e3a7aSWarner Loshand so the second <code>x</code> refers to the outside variable.
28928e3e3a7aSWarner Losh
28938e3e3a7aSWarner Losh
28948e3e3a7aSWarner Losh<p>
28958e3e3a7aSWarner LoshBecause of the lexical scoping rules,
28968e3e3a7aSWarner Loshlocal variables can be freely accessed by functions
28978e3e3a7aSWarner Loshdefined inside their scope.
28980495ed39SKyle EvansA local variable used by an inner function is called an <em>upvalue</em>
28990495ed39SKyle Evans(or <em>external local variable</em>, or simply <em>external variable</em>)
29008e3e3a7aSWarner Loshinside the inner function.
29018e3e3a7aSWarner Losh
29028e3e3a7aSWarner Losh
29038e3e3a7aSWarner Losh<p>
29048e3e3a7aSWarner LoshNotice that each execution of a <b>local</b> statement
29058e3e3a7aSWarner Loshdefines new local variables.
29068e3e3a7aSWarner LoshConsider the following example:
29078e3e3a7aSWarner Losh
29088e3e3a7aSWarner Losh<pre>
29098e3e3a7aSWarner Losh     a = {}
29108e3e3a7aSWarner Losh     local x = 20
29118e3e3a7aSWarner Losh     for i = 1, 10 do
29128e3e3a7aSWarner Losh       local y = 0
29138e3e3a7aSWarner Losh       a[i] = function () y = y + 1; return x + y end
29148e3e3a7aSWarner Losh     end
29158e3e3a7aSWarner Losh</pre><p>
29168e3e3a7aSWarner LoshThe loop creates ten closures
29178e3e3a7aSWarner Losh(that is, ten instances of the anonymous function).
29188e3e3a7aSWarner LoshEach of these closures uses a different <code>y</code> variable,
29198e3e3a7aSWarner Loshwhile all of them share the same <code>x</code>.
29208e3e3a7aSWarner Losh
29218e3e3a7aSWarner Losh
29228e3e3a7aSWarner Losh
29238e3e3a7aSWarner Losh
29248e3e3a7aSWarner Losh
29258e3e3a7aSWarner Losh<h1>4 &ndash; <a name="4">The Application Program Interface</a></h1>
29268e3e3a7aSWarner Losh
29270495ed39SKyle Evans
29280495ed39SKyle Evans
29298e3e3a7aSWarner Losh<p>
29308e3e3a7aSWarner Losh
29318e3e3a7aSWarner LoshThis section describes the C&nbsp;API for Lua, that is,
29328e3e3a7aSWarner Loshthe set of C&nbsp;functions available to the host program to communicate
29338e3e3a7aSWarner Loshwith Lua.
29348e3e3a7aSWarner LoshAll API functions and related types and constants
29358e3e3a7aSWarner Loshare declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>.
29368e3e3a7aSWarner Losh
29378e3e3a7aSWarner Losh
29388e3e3a7aSWarner Losh<p>
29398e3e3a7aSWarner LoshEven when we use the term "function",
29408e3e3a7aSWarner Loshany facility in the API may be provided as a macro instead.
29418e3e3a7aSWarner LoshExcept where stated otherwise,
29428e3e3a7aSWarner Loshall such macros use each of their arguments exactly once
29438e3e3a7aSWarner Losh(except for the first argument, which is always a Lua state),
29448e3e3a7aSWarner Loshand so do not generate any hidden side-effects.
29458e3e3a7aSWarner Losh
29468e3e3a7aSWarner Losh
29478e3e3a7aSWarner Losh<p>
29488e3e3a7aSWarner LoshAs in most C&nbsp;libraries,
29490495ed39SKyle Evansthe Lua API functions do not check their arguments
29500495ed39SKyle Evansfor validity or consistency.
29518e3e3a7aSWarner LoshHowever, you can change this behavior by compiling Lua
29528e3e3a7aSWarner Loshwith the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined.
29538e3e3a7aSWarner Losh
29548e3e3a7aSWarner Losh
29558e3e3a7aSWarner Losh<p>
29568e3e3a7aSWarner LoshThe Lua library is fully reentrant:
29578e3e3a7aSWarner Loshit has no global variables.
29588e3e3a7aSWarner LoshIt keeps all information it needs in a dynamic structure,
29598e3e3a7aSWarner Loshcalled the <em>Lua state</em>.
29608e3e3a7aSWarner Losh
29618e3e3a7aSWarner Losh
29628e3e3a7aSWarner Losh<p>
29638e3e3a7aSWarner LoshEach Lua state has one or more threads,
29648e3e3a7aSWarner Loshwhich correspond to independent, cooperative lines of execution.
29658e3e3a7aSWarner LoshThe type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread.
29668e3e3a7aSWarner Losh(Indirectly, through the thread, it also refers to the
29678e3e3a7aSWarner LoshLua state associated to the thread.)
29688e3e3a7aSWarner Losh
29698e3e3a7aSWarner Losh
29708e3e3a7aSWarner Losh<p>
29718e3e3a7aSWarner LoshA pointer to a thread must be passed as the first argument to
29728e3e3a7aSWarner Loshevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
29738e3e3a7aSWarner Loshwhich creates a Lua state from scratch and returns a pointer
29748e3e3a7aSWarner Loshto the <em>main thread</em> in the new state.
29758e3e3a7aSWarner Losh
29768e3e3a7aSWarner Losh
29778e3e3a7aSWarner Losh
29780495ed39SKyle Evans
29790495ed39SKyle Evans
29808e3e3a7aSWarner Losh<h2>4.1 &ndash; <a name="4.1">The Stack</a></h2>
29818e3e3a7aSWarner Losh
29820495ed39SKyle Evans
29830495ed39SKyle Evans
29848e3e3a7aSWarner Losh<p>
29858e3e3a7aSWarner LoshLua uses a <em>virtual stack</em> to pass values to and from C.
29868e3e3a7aSWarner LoshEach element in this stack represents a Lua value
29878e3e3a7aSWarner Losh(<b>nil</b>, number, string, etc.).
29888e3e3a7aSWarner LoshFunctions in the API can access this stack through the
29898e3e3a7aSWarner LoshLua state parameter that they receive.
29908e3e3a7aSWarner Losh
29918e3e3a7aSWarner Losh
29928e3e3a7aSWarner Losh<p>
29938e3e3a7aSWarner LoshWhenever Lua calls C, the called function gets a new stack,
29948e3e3a7aSWarner Loshwhich is independent of previous stacks and of stacks of
29958e3e3a7aSWarner LoshC&nbsp;functions that are still active.
29968e3e3a7aSWarner LoshThis stack initially contains any arguments to the C&nbsp;function
29978e3e3a7aSWarner Loshand it is where the C&nbsp;function can store temporary
29988e3e3a7aSWarner LoshLua values and must push its results
29998e3e3a7aSWarner Loshto be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
30008e3e3a7aSWarner Losh
30018e3e3a7aSWarner Losh
30028e3e3a7aSWarner Losh<p>
30038e3e3a7aSWarner LoshFor convenience,
30048e3e3a7aSWarner Loshmost query operations in the API do not follow a strict stack discipline.
30058e3e3a7aSWarner LoshInstead, they can refer to any element in the stack
30068e3e3a7aSWarner Loshby using an <em>index</em>:
30070495ed39SKyle EvansA positive index represents an absolute stack position,
30080495ed39SKyle Evansstarting at&nbsp;1 as the bottom of the stack;
30098e3e3a7aSWarner Losha negative index represents an offset relative to the top of the stack.
30108e3e3a7aSWarner LoshMore specifically, if the stack has <em>n</em> elements,
30118e3e3a7aSWarner Loshthen index&nbsp;1 represents the first element
30128e3e3a7aSWarner Losh(that is, the element that was pushed onto the stack first)
30138e3e3a7aSWarner Loshand
30148e3e3a7aSWarner Loshindex&nbsp;<em>n</em> represents the last element;
30158e3e3a7aSWarner Loshindex&nbsp;-1 also represents the last element
30168e3e3a7aSWarner Losh(that is, the element at the&nbsp;top)
30178e3e3a7aSWarner Loshand index <em>-n</em> represents the first element.
30188e3e3a7aSWarner Losh
30198e3e3a7aSWarner Losh
30208e3e3a7aSWarner Losh
30218e3e3a7aSWarner Losh
30228e3e3a7aSWarner Losh
30230495ed39SKyle Evans<h3>4.1.1 &ndash; <a name="4.1.1">Stack Size</a></h3>
30248e3e3a7aSWarner Losh
30258e3e3a7aSWarner Losh<p>
30268e3e3a7aSWarner LoshWhen you interact with the Lua API,
30278e3e3a7aSWarner Loshyou are responsible for ensuring consistency.
30288e3e3a7aSWarner LoshIn particular,
30298e3e3a7aSWarner Losh<em>you are responsible for controlling stack overflow</em>.
30300495ed39SKyle EvansWhen you call any API function,
30310495ed39SKyle Evansyou must ensure the stack has enough room to accommodate the results.
30320495ed39SKyle Evans
30330495ed39SKyle Evans
30340495ed39SKyle Evans<p>
30350495ed39SKyle EvansThere is one exception to the above rule:
30360495ed39SKyle EvansWhen you call a Lua function
30370495ed39SKyle Evanswithout a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>),
30380495ed39SKyle EvansLua ensures that the stack has enough space for all results.
30390495ed39SKyle EvansHowever, it does not ensure any extra space.
30400495ed39SKyle EvansSo, before pushing anything on the stack after such a call
30410495ed39SKyle Evansyou should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>.
30428e3e3a7aSWarner Losh
30438e3e3a7aSWarner Losh
30448e3e3a7aSWarner Losh<p>
30458e3e3a7aSWarner LoshWhenever Lua calls C,
30468e3e3a7aSWarner Loshit ensures that the stack has space for
30470495ed39SKyle Evansat least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra elements;
30480495ed39SKyle Evansthat is, you can safely push up to <code>LUA_MINSTACK</code> values into it.
30498e3e3a7aSWarner Losh<code>LUA_MINSTACK</code> is defined as 20,
30508e3e3a7aSWarner Loshso that usually you do not have to worry about stack space
30518e3e3a7aSWarner Loshunless your code has loops pushing elements onto the stack.
30520495ed39SKyle EvansWhenever necessary,
30530495ed39SKyle Evansyou can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a>
30540495ed39SKyle Evansto ensure that the stack has enough space for pushing new elements.
30558e3e3a7aSWarner Losh
30568e3e3a7aSWarner Losh
30578e3e3a7aSWarner Losh
30588e3e3a7aSWarner Losh
30598e3e3a7aSWarner Losh
30600495ed39SKyle Evans<h3>4.1.2 &ndash; <a name="4.1.2">Valid and Acceptable Indices</a></h3>
30618e3e3a7aSWarner Losh
30628e3e3a7aSWarner Losh<p>
30638e3e3a7aSWarner LoshAny function in the API that receives stack indices
30648e3e3a7aSWarner Loshworks only with <em>valid indices</em> or <em>acceptable indices</em>.
30658e3e3a7aSWarner Losh
30668e3e3a7aSWarner Losh
30678e3e3a7aSWarner Losh<p>
30688e3e3a7aSWarner LoshA <em>valid index</em> is an index that refers to a
30698e3e3a7aSWarner Loshposition that stores a modifiable Lua value.
30708e3e3a7aSWarner LoshIt comprises stack indices between&nbsp;1 and the stack top
30718e3e3a7aSWarner Losh(<code>1 &le; abs(index) &le; top</code>)
30728e3e3a7aSWarner Losh
30738e3e3a7aSWarner Loshplus <em>pseudo-indices</em>,
30748e3e3a7aSWarner Loshwhich represent some positions that are accessible to C&nbsp;code
30758e3e3a7aSWarner Loshbut that are not in the stack.
30760495ed39SKyle EvansPseudo-indices are used to access the registry (see <a href="#4.3">&sect;4.3</a>)
30770495ed39SKyle Evansand the upvalues of a C&nbsp;function (see <a href="#4.2">&sect;4.2</a>).
30788e3e3a7aSWarner Losh
30798e3e3a7aSWarner Losh
30808e3e3a7aSWarner Losh<p>
30818e3e3a7aSWarner LoshFunctions that do not need a specific mutable position,
30828e3e3a7aSWarner Loshbut only a value (e.g., query functions),
30838e3e3a7aSWarner Loshcan be called with acceptable indices.
30848e3e3a7aSWarner LoshAn <em>acceptable index</em> can be any valid index,
30858e3e3a7aSWarner Loshbut it also can be any positive index after the stack top
30868e3e3a7aSWarner Loshwithin the space allocated for the stack,
30878e3e3a7aSWarner Loshthat is, indices up to the stack size.
30888e3e3a7aSWarner Losh(Note that 0 is never an acceptable index.)
30890495ed39SKyle EvansIndices to upvalues (see <a href="#4.2">&sect;4.2</a>) greater than the real number
30900495ed39SKyle Evansof upvalues in the current C&nbsp;function are also acceptable (but invalid).
30918e3e3a7aSWarner LoshExcept when noted otherwise,
30928e3e3a7aSWarner Loshfunctions in the API work with acceptable indices.
30938e3e3a7aSWarner Losh
30948e3e3a7aSWarner Losh
30958e3e3a7aSWarner Losh<p>
30968e3e3a7aSWarner LoshAcceptable indices serve to avoid extra tests
30978e3e3a7aSWarner Loshagainst the stack top when querying the stack.
30988e3e3a7aSWarner LoshFor instance, a C&nbsp;function can query its third argument
30990495ed39SKyle Evanswithout the need to check whether there is a third argument,
31008e3e3a7aSWarner Loshthat is, without the need to check whether 3 is a valid index.
31018e3e3a7aSWarner Losh
31028e3e3a7aSWarner Losh
31038e3e3a7aSWarner Losh<p>
31048e3e3a7aSWarner LoshFor functions that can be called with acceptable indices,
31058e3e3a7aSWarner Loshany non-valid index is treated as if it
31068e3e3a7aSWarner Loshcontains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>,
31078e3e3a7aSWarner Loshwhich behaves like a nil value.
31088e3e3a7aSWarner Losh
31098e3e3a7aSWarner Losh
31108e3e3a7aSWarner Losh
31118e3e3a7aSWarner Losh
31128e3e3a7aSWarner Losh
31130495ed39SKyle Evans<h3>4.1.3 &ndash; <a name="4.1.3">Pointers to strings</a></h3>
31140495ed39SKyle Evans
31150495ed39SKyle Evans<p>
31160495ed39SKyle EvansSeveral functions in the API return pointers (<code>const char*</code>)
31170495ed39SKyle Evansto Lua strings in the stack.
31180495ed39SKyle Evans(See <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>,
31190495ed39SKyle Evans<a href="#lua_pushstring"><code>lua_pushstring</code></a>, and <a href="#lua_tolstring"><code>lua_tolstring</code></a>.
31200495ed39SKyle EvansSee also <a href="#luaL_checklstring"><code>luaL_checklstring</code></a>, <a href="#luaL_checkstring"><code>luaL_checkstring</code></a>,
31210495ed39SKyle Evansand <a href="#luaL_tolstring"><code>luaL_tolstring</code></a> in the auxiliary library.)
31220495ed39SKyle Evans
31230495ed39SKyle Evans
31240495ed39SKyle Evans<p>
31250495ed39SKyle EvansIn general,
31260495ed39SKyle EvansLua's garbage collection can free or move internal memory
31270495ed39SKyle Evansand then invalidate pointers to internal strings.
31280495ed39SKyle EvansTo allow a safe use of these pointers,
3129a9490b81SWarner Loshthe API guarantees that any pointer to a string in a stack index
31300495ed39SKyle Evansis valid while the string value at that index is not removed from the stack.
31310495ed39SKyle Evans(It can be moved to another index, though.)
31320495ed39SKyle EvansWhen the index is a pseudo-index (referring to an upvalue),
31330495ed39SKyle Evansthe pointer is valid while the corresponding call is active and
31340495ed39SKyle Evansthe corresponding upvalue is not modified.
31350495ed39SKyle Evans
31360495ed39SKyle Evans
31370495ed39SKyle Evans<p>
31380495ed39SKyle EvansSome functions in the debug interface
31390495ed39SKyle Evansalso return pointers to strings,
31400495ed39SKyle Evansnamely <a href="#lua_getlocal"><code>lua_getlocal</code></a>, <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>,
31410495ed39SKyle Evans<a href="#lua_setlocal"><code>lua_setlocal</code></a>, and <a href="#lua_setupvalue"><code>lua_setupvalue</code></a>.
31420495ed39SKyle EvansFor these functions, the pointer is guaranteed to
31430495ed39SKyle Evansbe valid while the caller function is active and
31440495ed39SKyle Evansthe given closure (if one was given) is in the stack.
31450495ed39SKyle Evans
31460495ed39SKyle Evans
31470495ed39SKyle Evans<p>
31480495ed39SKyle EvansExcept for these guarantees,
31490495ed39SKyle Evansthe garbage collector is free to invalidate
31500495ed39SKyle Evansany pointer to internal strings.
31510495ed39SKyle Evans
31520495ed39SKyle Evans
31530495ed39SKyle Evans
31540495ed39SKyle Evans
31550495ed39SKyle Evans
31560495ed39SKyle Evans
31570495ed39SKyle Evans
31580495ed39SKyle Evans<h2>4.2 &ndash; <a name="4.2">C Closures</a></h2>
31598e3e3a7aSWarner Losh
31608e3e3a7aSWarner Losh<p>
31618e3e3a7aSWarner LoshWhen a C&nbsp;function is created,
31628e3e3a7aSWarner Loshit is possible to associate some values with it,
31638e3e3a7aSWarner Loshthus creating a <em>C&nbsp;closure</em>
31648e3e3a7aSWarner Losh(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>);
31658e3e3a7aSWarner Loshthese values are called <em>upvalues</em> and are
31668e3e3a7aSWarner Loshaccessible to the function whenever it is called.
31678e3e3a7aSWarner Losh
31688e3e3a7aSWarner Losh
31698e3e3a7aSWarner Losh<p>
31708e3e3a7aSWarner LoshWhenever a C&nbsp;function is called,
31718e3e3a7aSWarner Loshits upvalues are located at specific pseudo-indices.
31728e3e3a7aSWarner LoshThese pseudo-indices are produced by the macro
31738e3e3a7aSWarner Losh<a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>.
31748e3e3a7aSWarner LoshThe first upvalue associated with a function is at index
31758e3e3a7aSWarner Losh<code>lua_upvalueindex(1)</code>, and so on.
31768e3e3a7aSWarner LoshAny access to <code>lua_upvalueindex(<em>n</em>)</code>,
31778e3e3a7aSWarner Loshwhere <em>n</em> is greater than the number of upvalues of the
31788e3e3a7aSWarner Loshcurrent function
31798e3e3a7aSWarner Losh(but not greater than 256,
31808e3e3a7aSWarner Loshwhich is one plus the maximum number of upvalues in a closure),
31818e3e3a7aSWarner Loshproduces an acceptable but invalid index.
31828e3e3a7aSWarner Losh
31838e3e3a7aSWarner Losh
31840495ed39SKyle Evans<p>
31850495ed39SKyle EvansA C&nbsp;closure can also change the values
31860495ed39SKyle Evansof its corresponding upvalues.
31878e3e3a7aSWarner Losh
31888e3e3a7aSWarner Losh
31898e3e3a7aSWarner Losh
31900495ed39SKyle Evans
31910495ed39SKyle Evans
31920495ed39SKyle Evans<h2>4.3 &ndash; <a name="4.3">Registry</a></h2>
31938e3e3a7aSWarner Losh
31948e3e3a7aSWarner Losh<p>
31958e3e3a7aSWarner LoshLua provides a <em>registry</em>,
31968e3e3a7aSWarner Losha predefined table that can be used by any C&nbsp;code to
31978e3e3a7aSWarner Loshstore whatever Lua values it needs to store.
31980495ed39SKyle EvansThe registry table is always accessible at pseudo-index
31998e3e3a7aSWarner Losh<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>.
32008e3e3a7aSWarner LoshAny C&nbsp;library can store data into this table,
32018e3e3a7aSWarner Loshbut it must take care to choose keys
32028e3e3a7aSWarner Loshthat are different from those used
32038e3e3a7aSWarner Loshby other libraries, to avoid collisions.
32048e3e3a7aSWarner LoshTypically, you should use as key a string containing your library name,
32058e3e3a7aSWarner Loshor a light userdata with the address of a C&nbsp;object in your code,
32068e3e3a7aSWarner Loshor any Lua object created by your code.
32078e3e3a7aSWarner LoshAs with variable names,
32088e3e3a7aSWarner Loshstring keys starting with an underscore followed by
32098e3e3a7aSWarner Loshuppercase letters are reserved for Lua.
32108e3e3a7aSWarner Losh
32118e3e3a7aSWarner Losh
32128e3e3a7aSWarner Losh<p>
32138e3e3a7aSWarner LoshThe integer keys in the registry are used
32148e3e3a7aSWarner Loshby the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>)
32158e3e3a7aSWarner Loshand by some predefined values.
32160495ed39SKyle EvansTherefore, integer keys in the registry
32170495ed39SKyle Evansmust not be used for other purposes.
32188e3e3a7aSWarner Losh
32198e3e3a7aSWarner Losh
32208e3e3a7aSWarner Losh<p>
32218e3e3a7aSWarner LoshWhen you create a new Lua state,
32228e3e3a7aSWarner Loshits registry comes with some predefined values.
32238e3e3a7aSWarner LoshThese predefined values are indexed with integer keys
32248e3e3a7aSWarner Loshdefined as constants in <code>lua.h</code>.
32258e3e3a7aSWarner LoshThe following constants are defined:
32268e3e3a7aSWarner Losh
32278e3e3a7aSWarner Losh<ul>
32288e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has
32298e3e3a7aSWarner Loshthe main thread of the state.
32308e3e3a7aSWarner Losh(The main thread is the one created together with the state.)
32318e3e3a7aSWarner Losh</li>
32328e3e3a7aSWarner Losh
32338e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has
32348e3e3a7aSWarner Loshthe global environment.
32358e3e3a7aSWarner Losh</li>
32368e3e3a7aSWarner Losh</ul>
32378e3e3a7aSWarner Losh
32388e3e3a7aSWarner Losh
32398e3e3a7aSWarner Losh
32408e3e3a7aSWarner Losh
32410495ed39SKyle Evans<h2>4.4 &ndash; <a name="4.4">Error Handling in C</a></h2>
32420495ed39SKyle Evans
32430495ed39SKyle Evans
32448e3e3a7aSWarner Losh
32458e3e3a7aSWarner Losh<p>
32468e3e3a7aSWarner LoshInternally, Lua uses the C <code>longjmp</code> facility to handle errors.
32478e3e3a7aSWarner Losh(Lua will use exceptions if you compile it as C++;
32488e3e3a7aSWarner Loshsearch for <code>LUAI_THROW</code> in the source code for details.)
32490495ed39SKyle EvansWhen Lua faces any error,
32500495ed39SKyle Evanssuch as a memory allocation error or a type error,
32518e3e3a7aSWarner Loshit <em>raises</em> an error;
32528e3e3a7aSWarner Loshthat is, it does a long jump.
32538e3e3a7aSWarner LoshA <em>protected environment</em> uses <code>setjmp</code>
32548e3e3a7aSWarner Loshto set a recovery point;
32558e3e3a7aSWarner Loshany error jumps to the most recent active recovery point.
32568e3e3a7aSWarner Losh
32578e3e3a7aSWarner Losh
32588e3e3a7aSWarner Losh<p>
32590495ed39SKyle EvansInside a C&nbsp;function you can raise an error explicitly
32600495ed39SKyle Evansby calling <a href="#lua_error"><code>lua_error</code></a>.
32618e3e3a7aSWarner Losh
32628e3e3a7aSWarner Losh
32638e3e3a7aSWarner Losh<p>
32648e3e3a7aSWarner LoshMost functions in the API can raise an error,
32658e3e3a7aSWarner Loshfor instance due to a memory allocation error.
32668e3e3a7aSWarner LoshThe documentation for each function indicates whether
32678e3e3a7aSWarner Loshit can raise errors.
32688e3e3a7aSWarner Losh
32698e3e3a7aSWarner Losh
32708e3e3a7aSWarner Losh<p>
32718e3e3a7aSWarner LoshIf an error happens outside any protected environment,
32728e3e3a7aSWarner LoshLua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>)
32738e3e3a7aSWarner Loshand then calls <code>abort</code>,
32748e3e3a7aSWarner Loshthus exiting the host application.
32758e3e3a7aSWarner LoshYour panic function can avoid this exit by
32768e3e3a7aSWarner Loshnever returning
32778e3e3a7aSWarner Losh(e.g., doing a long jump to your own recovery point outside Lua).
32788e3e3a7aSWarner Losh
32798e3e3a7aSWarner Losh
32808e3e3a7aSWarner Losh<p>
32818e3e3a7aSWarner LoshThe panic function,
32828e3e3a7aSWarner Loshas its name implies,
32838e3e3a7aSWarner Loshis a mechanism of last resort.
32848e3e3a7aSWarner LoshPrograms should avoid it.
32858e3e3a7aSWarner LoshAs a general rule,
32868e3e3a7aSWarner Loshwhen a C&nbsp;function is called by Lua with a Lua state,
32878e3e3a7aSWarner Loshit can do whatever it wants on that Lua state,
32888e3e3a7aSWarner Loshas it should be already protected.
32898e3e3a7aSWarner LoshHowever,
32908e3e3a7aSWarner Loshwhen C code operates on other Lua states
32910495ed39SKyle Evans(e.g., a Lua-state argument to the function,
32928e3e3a7aSWarner Losha Lua state stored in the registry, or
32938e3e3a7aSWarner Loshthe result of <a href="#lua_newthread"><code>lua_newthread</code></a>),
32948e3e3a7aSWarner Loshit should use them only in API calls that cannot raise errors.
32958e3e3a7aSWarner Losh
32968e3e3a7aSWarner Losh
32978e3e3a7aSWarner Losh<p>
32988e3e3a7aSWarner LoshThe panic function runs as if it were a message handler (see <a href="#2.3">&sect;2.3</a>);
32990495ed39SKyle Evansin particular, the error object is on the top of the stack.
33008e3e3a7aSWarner LoshHowever, there is no guarantee about stack space.
33018e3e3a7aSWarner LoshTo push anything on the stack,
33020495ed39SKyle Evansthe panic function must first check the available space (see <a href="#4.1.1">&sect;4.1.1</a>).
33038e3e3a7aSWarner Losh
33048e3e3a7aSWarner Losh
33058e3e3a7aSWarner Losh
33068e3e3a7aSWarner Losh
33078e3e3a7aSWarner Losh
33080495ed39SKyle Evans<h3>4.4.1 &ndash; <a name="4.4.1">Status Codes</a></h3>
33090495ed39SKyle Evans
33100495ed39SKyle Evans<p>
33110495ed39SKyle EvansSeveral functions that report errors in the API use the following
33120495ed39SKyle Evansstatus codes to indicate different kinds of errors or other conditions:
33130495ed39SKyle Evans
33140495ed39SKyle Evans<ul>
33150495ed39SKyle Evans
33160495ed39SKyle Evans<li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> no errors.</li>
33170495ed39SKyle Evans
33180495ed39SKyle Evans<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b> a runtime error.</li>
33190495ed39SKyle Evans
33200495ed39SKyle Evans<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
33210495ed39SKyle Evansmemory allocation error.
33220495ed39SKyle EvansFor such errors, Lua does not call the message handler.
33230495ed39SKyle Evans</li>
33240495ed39SKyle Evans
33250495ed39SKyle Evans<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b> error while running the message handler.</li>
33260495ed39SKyle Evans
33270495ed39SKyle Evans<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> syntax error during precompilation.</li>
33280495ed39SKyle Evans
33290495ed39SKyle Evans<li><b><a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a>: </b> the thread (coroutine) yields.</li>
33300495ed39SKyle Evans
33310495ed39SKyle Evans<li><b><a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>: </b> a file-related error;
33320495ed39SKyle Evanse.g., it cannot open or read the file.</li>
33330495ed39SKyle Evans
33340495ed39SKyle Evans</ul><p>
33350495ed39SKyle EvansThese constants are defined in the header file <code>lua.h</code>.
33360495ed39SKyle Evans
33370495ed39SKyle Evans
33380495ed39SKyle Evans
33390495ed39SKyle Evans
33400495ed39SKyle Evans
33410495ed39SKyle Evans
33420495ed39SKyle Evans
33430495ed39SKyle Evans<h2>4.5 &ndash; <a name="4.5">Handling Yields in C</a></h2>
33448e3e3a7aSWarner Losh
33458e3e3a7aSWarner Losh<p>
33468e3e3a7aSWarner LoshInternally, Lua uses the C <code>longjmp</code> facility to yield a coroutine.
33478e3e3a7aSWarner LoshTherefore, if a C&nbsp;function <code>foo</code> calls an API function
33488e3e3a7aSWarner Loshand this API function yields
33498e3e3a7aSWarner Losh(directly or indirectly by calling another function that yields),
33508e3e3a7aSWarner LoshLua cannot return to <code>foo</code> any more,
33510495ed39SKyle Evansbecause the <code>longjmp</code> removes its frame from the C&nbsp;stack.
33528e3e3a7aSWarner Losh
33538e3e3a7aSWarner Losh
33548e3e3a7aSWarner Losh<p>
33558e3e3a7aSWarner LoshTo avoid this kind of problem,
33568e3e3a7aSWarner LoshLua raises an error whenever it tries to yield across an API call,
33578e3e3a7aSWarner Loshexcept for three functions:
33588e3e3a7aSWarner Losh<a href="#lua_yieldk"><code>lua_yieldk</code></a>, <a href="#lua_callk"><code>lua_callk</code></a>, and <a href="#lua_pcallk"><code>lua_pcallk</code></a>.
33598e3e3a7aSWarner LoshAll those functions receive a <em>continuation function</em>
33608e3e3a7aSWarner Losh(as a parameter named <code>k</code>) to continue execution after a yield.
33618e3e3a7aSWarner Losh
33628e3e3a7aSWarner Losh
33638e3e3a7aSWarner Losh<p>
33648e3e3a7aSWarner LoshWe need to set some terminology to explain continuations.
33658e3e3a7aSWarner LoshWe have a C&nbsp;function called from Lua which we will call
33668e3e3a7aSWarner Loshthe <em>original function</em>.
33678e3e3a7aSWarner LoshThis original function then calls one of those three functions in the C API,
33688e3e3a7aSWarner Loshwhich we will call the <em>callee function</em>,
33698e3e3a7aSWarner Loshthat then yields the current thread.
33700495ed39SKyle EvansThis can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
33718e3e3a7aSWarner Loshor when the callee function is either <a href="#lua_callk"><code>lua_callk</code></a> or <a href="#lua_pcallk"><code>lua_pcallk</code></a>
33720495ed39SKyle Evansand the function called by them yields.
33738e3e3a7aSWarner Losh
33748e3e3a7aSWarner Losh
33758e3e3a7aSWarner Losh<p>
33768e3e3a7aSWarner LoshSuppose the running thread yields while executing the callee function.
33778e3e3a7aSWarner LoshAfter the thread resumes,
33788e3e3a7aSWarner Loshit eventually will finish running the callee function.
33798e3e3a7aSWarner LoshHowever,
33808e3e3a7aSWarner Loshthe callee function cannot return to the original function,
33810495ed39SKyle Evansbecause its frame in the C&nbsp;stack was destroyed by the yield.
33828e3e3a7aSWarner LoshInstead, Lua calls a <em>continuation function</em>,
33838e3e3a7aSWarner Loshwhich was given as an argument to the callee function.
33848e3e3a7aSWarner LoshAs the name implies,
33858e3e3a7aSWarner Loshthe continuation function should continue the task
33868e3e3a7aSWarner Loshof the original function.
33878e3e3a7aSWarner Losh
33888e3e3a7aSWarner Losh
33898e3e3a7aSWarner Losh<p>
33908e3e3a7aSWarner LoshAs an illustration, consider the following function:
33918e3e3a7aSWarner Losh
33928e3e3a7aSWarner Losh<pre>
33938e3e3a7aSWarner Losh     int original_function (lua_State *L) {
33948e3e3a7aSWarner Losh       ...     /* code 1 */
33958e3e3a7aSWarner Losh       status = lua_pcall(L, n, m, h);  /* calls Lua */
33968e3e3a7aSWarner Losh       ...     /* code 2 */
33978e3e3a7aSWarner Losh     }
33988e3e3a7aSWarner Losh</pre><p>
33998e3e3a7aSWarner LoshNow we want to allow
34008e3e3a7aSWarner Loshthe Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield.
34018e3e3a7aSWarner LoshFirst, we can rewrite our function like here:
34028e3e3a7aSWarner Losh
34038e3e3a7aSWarner Losh<pre>
34048e3e3a7aSWarner Losh     int k (lua_State *L, int status, lua_KContext ctx) {
34058e3e3a7aSWarner Losh       ...  /* code 2 */
34068e3e3a7aSWarner Losh     }
34078e3e3a7aSWarner Losh
34088e3e3a7aSWarner Losh     int original_function (lua_State *L) {
34098e3e3a7aSWarner Losh       ...     /* code 1 */
34108e3e3a7aSWarner Losh       return k(L, lua_pcall(L, n, m, h), ctx);
34118e3e3a7aSWarner Losh     }
34128e3e3a7aSWarner Losh</pre><p>
34138e3e3a7aSWarner LoshIn the above code,
34148e3e3a7aSWarner Loshthe new function <code>k</code> is a
34158e3e3a7aSWarner Losh<em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>),
34168e3e3a7aSWarner Loshwhich should do all the work that the original function
34178e3e3a7aSWarner Loshwas doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>.
34188e3e3a7aSWarner LoshNow, we must inform Lua that it must call <code>k</code> if the Lua code
34198e3e3a7aSWarner Loshbeing executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way
34208e3e3a7aSWarner Losh(errors or yielding),
34218e3e3a7aSWarner Loshso we rewrite the code as here,
34228e3e3a7aSWarner Loshreplacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>:
34238e3e3a7aSWarner Losh
34248e3e3a7aSWarner Losh<pre>
34258e3e3a7aSWarner Losh     int original_function (lua_State *L) {
34268e3e3a7aSWarner Losh       ...     /* code 1 */
34278e3e3a7aSWarner Losh       return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
34288e3e3a7aSWarner Losh     }
34298e3e3a7aSWarner Losh</pre><p>
34308e3e3a7aSWarner LoshNote the external, explicit call to the continuation:
34318e3e3a7aSWarner LoshLua will call the continuation only if needed, that is,
34328e3e3a7aSWarner Loshin case of errors or resuming after a yield.
34338e3e3a7aSWarner LoshIf the called function returns normally without ever yielding,
34348e3e3a7aSWarner Losh<a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally.
34358e3e3a7aSWarner Losh(Of course, instead of calling the continuation in that case,
34368e3e3a7aSWarner Loshyou can do the equivalent work directly inside the original function.)
34378e3e3a7aSWarner Losh
34388e3e3a7aSWarner Losh
34398e3e3a7aSWarner Losh<p>
34408e3e3a7aSWarner LoshBesides the Lua state,
34418e3e3a7aSWarner Loshthe continuation function has two other parameters:
34420495ed39SKyle Evansthe final status of the call and the context value (<code>ctx</code>) that
34438e3e3a7aSWarner Loshwas passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>.
34440495ed39SKyle EvansLua does not use this context value;
34458e3e3a7aSWarner Loshit only passes this value from the original function to the
34460495ed39SKyle Evanscontinuation function.
34478e3e3a7aSWarner LoshFor <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
34488e3e3a7aSWarner Loshthe status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
34498e3e3a7aSWarner Loshexcept that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield
34508e3e3a7aSWarner Losh(instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>).
34518e3e3a7aSWarner LoshFor <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>,
34528e3e3a7aSWarner Loshthe status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation.
34538e3e3a7aSWarner Losh(For these two functions,
34548e3e3a7aSWarner LoshLua will not call the continuation in case of errors,
34558e3e3a7aSWarner Loshbecause they do not handle errors.)
34568e3e3a7aSWarner LoshSimilarly, when using <a href="#lua_callk"><code>lua_callk</code></a>,
34578e3e3a7aSWarner Loshyou should call the continuation function
34588e3e3a7aSWarner Loshwith <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status.
34598e3e3a7aSWarner Losh(For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling
34608e3e3a7aSWarner Loshdirectly the continuation function,
34618e3e3a7aSWarner Loshbecause <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.)
34628e3e3a7aSWarner Losh
34638e3e3a7aSWarner Losh
34648e3e3a7aSWarner Losh<p>
34658e3e3a7aSWarner LoshLua treats the continuation function as if it were the original function.
34668e3e3a7aSWarner LoshThe continuation function receives the same Lua stack
34678e3e3a7aSWarner Loshfrom the original function,
34688e3e3a7aSWarner Loshin the same state it would be if the callee function had returned.
34698e3e3a7aSWarner Losh(For instance,
34708e3e3a7aSWarner Loshafter a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are
34718e3e3a7aSWarner Loshremoved from the stack and replaced by the results from the call.)
34728e3e3a7aSWarner LoshIt also has the same upvalues.
34738e3e3a7aSWarner LoshWhatever it returns is handled by Lua as if it were the return
34748e3e3a7aSWarner Loshof the original function.
34758e3e3a7aSWarner Losh
34768e3e3a7aSWarner Losh
34778e3e3a7aSWarner Losh
34788e3e3a7aSWarner Losh
34798e3e3a7aSWarner Losh
34800495ed39SKyle Evans<h2>4.6 &ndash; <a name="4.6">Functions and Types</a></h2>
34818e3e3a7aSWarner Losh
34828e3e3a7aSWarner Losh<p>
34838e3e3a7aSWarner LoshHere we list all functions and types from the C&nbsp;API in
34848e3e3a7aSWarner Loshalphabetical order.
34858e3e3a7aSWarner LoshEach function has an indicator like this:
34868e3e3a7aSWarner Losh<span class="apii">[-o, +p, <em>x</em>]</span>
34878e3e3a7aSWarner Losh
34888e3e3a7aSWarner Losh
34898e3e3a7aSWarner Losh<p>
34908e3e3a7aSWarner LoshThe first field, <code>o</code>,
34918e3e3a7aSWarner Loshis how many elements the function pops from the stack.
34928e3e3a7aSWarner LoshThe second field, <code>p</code>,
34938e3e3a7aSWarner Loshis how many elements the function pushes onto the stack.
34948e3e3a7aSWarner Losh(Any function always pushes its results after popping its arguments.)
34958e3e3a7aSWarner LoshA field in the form <code>x|y</code> means the function can push (or pop)
34968e3e3a7aSWarner Losh<code>x</code> or <code>y</code> elements,
34978e3e3a7aSWarner Loshdepending on the situation;
34988e3e3a7aSWarner Loshan interrogation mark '<code>?</code>' means that
34998e3e3a7aSWarner Loshwe cannot know how many elements the function pops/pushes
35000495ed39SKyle Evansby looking only at its arguments.
35010495ed39SKyle Evans(For instance, they may depend on what is in the stack.)
35028e3e3a7aSWarner LoshThe third field, <code>x</code>,
35038e3e3a7aSWarner Loshtells whether the function may raise errors:
35048e3e3a7aSWarner Losh'<code>-</code>' means the function never raises any error;
35050495ed39SKyle Evans'<code>m</code>' means the function may raise only out-of-memory errors;
35060495ed39SKyle Evans'<code>v</code>' means the function may raise the errors explained in the text;
35070495ed39SKyle Evans'<code>e</code>' means the function can run arbitrary Lua code,
35080495ed39SKyle Evanseither directly or through metamethods,
35090495ed39SKyle Evansand therefore may raise any errors.
35108e3e3a7aSWarner Losh
35118e3e3a7aSWarner Losh
35128e3e3a7aSWarner Losh
35138e3e3a7aSWarner Losh<hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p>
35148e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
35158e3e3a7aSWarner Losh<pre>int lua_absindex (lua_State *L, int idx);</pre>
35168e3e3a7aSWarner Losh
35178e3e3a7aSWarner Losh<p>
35188e3e3a7aSWarner LoshConverts the acceptable index <code>idx</code>
35198e3e3a7aSWarner Loshinto an equivalent absolute index
35200495ed39SKyle Evans(that is, one that does not depend on the stack size).
35218e3e3a7aSWarner Losh
35228e3e3a7aSWarner Losh
35238e3e3a7aSWarner Losh
35248e3e3a7aSWarner Losh
35258e3e3a7aSWarner Losh
35268e3e3a7aSWarner Losh<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3>
35278e3e3a7aSWarner Losh<pre>typedef void * (*lua_Alloc) (void *ud,
35288e3e3a7aSWarner Losh                             void *ptr,
35298e3e3a7aSWarner Losh                             size_t osize,
35308e3e3a7aSWarner Losh                             size_t nsize);</pre>
35318e3e3a7aSWarner Losh
35328e3e3a7aSWarner Losh<p>
35338e3e3a7aSWarner LoshThe type of the memory-allocation function used by Lua states.
35348e3e3a7aSWarner LoshThe allocator function must provide a
35358e3e3a7aSWarner Loshfunctionality similar to <code>realloc</code>,
35368e3e3a7aSWarner Loshbut not exactly the same.
35378e3e3a7aSWarner LoshIts arguments are
35388e3e3a7aSWarner Losh<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>;
35398e3e3a7aSWarner Losh<code>ptr</code>, a pointer to the block being allocated/reallocated/freed;
35408e3e3a7aSWarner Losh<code>osize</code>, the original size of the block or some code about what
35418e3e3a7aSWarner Loshis being allocated;
35428e3e3a7aSWarner Loshand <code>nsize</code>, the new size of the block.
35438e3e3a7aSWarner Losh
35448e3e3a7aSWarner Losh
35458e3e3a7aSWarner Losh<p>
35468e3e3a7aSWarner LoshWhen <code>ptr</code> is not <code>NULL</code>,
35478e3e3a7aSWarner Losh<code>osize</code> is the size of the block pointed by <code>ptr</code>,
35488e3e3a7aSWarner Loshthat is, the size given when it was allocated or reallocated.
35498e3e3a7aSWarner Losh
35508e3e3a7aSWarner Losh
35518e3e3a7aSWarner Losh<p>
35528e3e3a7aSWarner LoshWhen <code>ptr</code> is <code>NULL</code>,
35538e3e3a7aSWarner Losh<code>osize</code> encodes the kind of object that Lua is allocating.
35548e3e3a7aSWarner Losh<code>osize</code> is any of
35558e3e3a7aSWarner Losh<a href="#pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, <a href="#pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, <a href="#pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>,
35568e3e3a7aSWarner Losh<a href="#pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, or <a href="#pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a> when (and only when)
35578e3e3a7aSWarner LoshLua is creating a new object of that type.
35588e3e3a7aSWarner LoshWhen <code>osize</code> is some other value,
35598e3e3a7aSWarner LoshLua is allocating memory for something else.
35608e3e3a7aSWarner Losh
35618e3e3a7aSWarner Losh
35628e3e3a7aSWarner Losh<p>
35638e3e3a7aSWarner LoshLua assumes the following behavior from the allocator function:
35648e3e3a7aSWarner Losh
35658e3e3a7aSWarner Losh
35668e3e3a7aSWarner Losh<p>
35678e3e3a7aSWarner LoshWhen <code>nsize</code> is zero,
35688e3e3a7aSWarner Loshthe allocator must behave like <code>free</code>
35690495ed39SKyle Evansand then return <code>NULL</code>.
35708e3e3a7aSWarner Losh
35718e3e3a7aSWarner Losh
35728e3e3a7aSWarner Losh<p>
35738e3e3a7aSWarner LoshWhen <code>nsize</code> is not zero,
35748e3e3a7aSWarner Loshthe allocator must behave like <code>realloc</code>.
35750495ed39SKyle EvansIn particular, the allocator returns <code>NULL</code>
35768e3e3a7aSWarner Loshif and only if it cannot fulfill the request.
35778e3e3a7aSWarner Losh
35788e3e3a7aSWarner Losh
35798e3e3a7aSWarner Losh<p>
35808e3e3a7aSWarner LoshHere is a simple implementation for the allocator function.
35818e3e3a7aSWarner LoshIt is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>.
35828e3e3a7aSWarner Losh
35838e3e3a7aSWarner Losh<pre>
35848e3e3a7aSWarner Losh     static void *l_alloc (void *ud, void *ptr, size_t osize,
35858e3e3a7aSWarner Losh                                                size_t nsize) {
35868e3e3a7aSWarner Losh       (void)ud;  (void)osize;  /* not used */
35878e3e3a7aSWarner Losh       if (nsize == 0) {
35888e3e3a7aSWarner Losh         free(ptr);
35898e3e3a7aSWarner Losh         return NULL;
35908e3e3a7aSWarner Losh       }
35918e3e3a7aSWarner Losh       else
35928e3e3a7aSWarner Losh         return realloc(ptr, nsize);
35938e3e3a7aSWarner Losh     }
35948e3e3a7aSWarner Losh</pre><p>
3595a9490b81SWarner LoshNote that ISO&nbsp;C ensures
35968e3e3a7aSWarner Loshthat <code>free(NULL)</code> has no effect and that
35978e3e3a7aSWarner Losh<code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>.
35988e3e3a7aSWarner Losh
35998e3e3a7aSWarner Losh
36008e3e3a7aSWarner Losh
36018e3e3a7aSWarner Losh
36028e3e3a7aSWarner Losh
36038e3e3a7aSWarner Losh<hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p>
36048e3e3a7aSWarner Losh<span class="apii">[-(2|1), +1, <em>e</em>]</span>
36058e3e3a7aSWarner Losh<pre>void lua_arith (lua_State *L, int op);</pre>
36068e3e3a7aSWarner Losh
36078e3e3a7aSWarner Losh<p>
36088e3e3a7aSWarner LoshPerforms an arithmetic or bitwise operation over the two values
36098e3e3a7aSWarner Losh(or one, in the case of negations)
36108e3e3a7aSWarner Loshat the top of the stack,
36110495ed39SKyle Evanswith the value on the top being the second operand,
36128e3e3a7aSWarner Loshpops these values, and pushes the result of the operation.
36138e3e3a7aSWarner LoshThe function follows the semantics of the corresponding Lua operator
36148e3e3a7aSWarner Losh(that is, it may call metamethods).
36158e3e3a7aSWarner Losh
36168e3e3a7aSWarner Losh
36178e3e3a7aSWarner Losh<p>
36188e3e3a7aSWarner LoshThe value of <code>op</code> must be one of the following constants:
36198e3e3a7aSWarner Losh
36208e3e3a7aSWarner Losh<ul>
36218e3e3a7aSWarner Losh
36228e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li>
36238e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li>
36248e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li>
36258e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li>
36268e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li>
36278e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li>
36288e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li>
36298e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li>
36308e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li>
36318e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&amp;</code>)</li>
36328e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li>
36338e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li>
36348e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code>&lt;&lt;</code>)</li>
36358e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>&gt;&gt;</code>)</li>
36368e3e3a7aSWarner Losh
36378e3e3a7aSWarner Losh</ul>
36388e3e3a7aSWarner Losh
36398e3e3a7aSWarner Losh
36408e3e3a7aSWarner Losh
36418e3e3a7aSWarner Losh
36428e3e3a7aSWarner Losh<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p>
36438e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
36448e3e3a7aSWarner Losh<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre>
36458e3e3a7aSWarner Losh
36468e3e3a7aSWarner Losh<p>
36470495ed39SKyle EvansSets a new panic function and returns the old one (see <a href="#4.4">&sect;4.4</a>).
36488e3e3a7aSWarner Losh
36498e3e3a7aSWarner Losh
36508e3e3a7aSWarner Losh
36518e3e3a7aSWarner Losh
36528e3e3a7aSWarner Losh
36538e3e3a7aSWarner Losh<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p>
36548e3e3a7aSWarner Losh<span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span>
36558e3e3a7aSWarner Losh<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre>
36568e3e3a7aSWarner Losh
36578e3e3a7aSWarner Losh<p>
36588e3e3a7aSWarner LoshCalls a function.
36590495ed39SKyle EvansLike regular Lua calls,
36600495ed39SKyle Evans<code>lua_call</code> respects the <code>__call</code> metamethod.
36610495ed39SKyle EvansSo, here the word "function"
36620495ed39SKyle Evansmeans any callable value.
36638e3e3a7aSWarner Losh
36648e3e3a7aSWarner Losh
36658e3e3a7aSWarner Losh<p>
36660495ed39SKyle EvansTo do a call you must use the following protocol:
36678e3e3a7aSWarner Loshfirst, the function to be called is pushed onto the stack;
36680495ed39SKyle Evansthen, the arguments to the call are pushed
36698e3e3a7aSWarner Loshin direct order;
36708e3e3a7aSWarner Loshthat is, the first argument is pushed first.
36718e3e3a7aSWarner LoshFinally you call <a href="#lua_call"><code>lua_call</code></a>;
36728e3e3a7aSWarner Losh<code>nargs</code> is the number of arguments that you pushed onto the stack.
36730495ed39SKyle EvansWhen the function returns,
36740495ed39SKyle Evansall arguments and the function value are popped
36750495ed39SKyle Evansand the call results are pushed onto the stack.
36768e3e3a7aSWarner LoshThe number of results is adjusted to <code>nresults</code>,
36778e3e3a7aSWarner Loshunless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>.
36788e3e3a7aSWarner LoshIn this case, all results from the function are pushed;
36798e3e3a7aSWarner LoshLua takes care that the returned values fit into the stack space,
36808e3e3a7aSWarner Loshbut it does not ensure any extra space in the stack.
36818e3e3a7aSWarner LoshThe function results are pushed onto the stack in direct order
36828e3e3a7aSWarner Losh(the first result is pushed first),
36838e3e3a7aSWarner Loshso that after the call the last result is on the top of the stack.
36848e3e3a7aSWarner Losh
36858e3e3a7aSWarner Losh
36868e3e3a7aSWarner Losh<p>
36870495ed39SKyle EvansAny error while calling and running the function is propagated upwards
36888e3e3a7aSWarner Losh(with a <code>longjmp</code>).
36898e3e3a7aSWarner Losh
36908e3e3a7aSWarner Losh
36918e3e3a7aSWarner Losh<p>
36928e3e3a7aSWarner LoshThe following example shows how the host program can do the
36938e3e3a7aSWarner Loshequivalent to this Lua code:
36948e3e3a7aSWarner Losh
36958e3e3a7aSWarner Losh<pre>
36968e3e3a7aSWarner Losh     a = f("how", t.x, 14)
36978e3e3a7aSWarner Losh</pre><p>
36988e3e3a7aSWarner LoshHere it is in&nbsp;C:
36998e3e3a7aSWarner Losh
37008e3e3a7aSWarner Losh<pre>
37018e3e3a7aSWarner Losh     lua_getglobal(L, "f");                  /* function to be called */
37028e3e3a7aSWarner Losh     lua_pushliteral(L, "how");                       /* 1st argument */
37038e3e3a7aSWarner Losh     lua_getglobal(L, "t");                    /* table to be indexed */
37048e3e3a7aSWarner Losh     lua_getfield(L, -1, "x");        /* push result of t.x (2nd arg) */
37058e3e3a7aSWarner Losh     lua_remove(L, -2);                  /* remove 't' from the stack */
37068e3e3a7aSWarner Losh     lua_pushinteger(L, 14);                          /* 3rd argument */
37078e3e3a7aSWarner Losh     lua_call(L, 3, 1);     /* call 'f' with 3 arguments and 1 result */
37088e3e3a7aSWarner Losh     lua_setglobal(L, "a");                         /* set global 'a' */
37098e3e3a7aSWarner Losh</pre><p>
37108e3e3a7aSWarner LoshNote that the code above is <em>balanced</em>:
37118e3e3a7aSWarner Loshat its end, the stack is back to its original configuration.
37128e3e3a7aSWarner LoshThis is considered good programming practice.
37138e3e3a7aSWarner Losh
37148e3e3a7aSWarner Losh
37158e3e3a7aSWarner Losh
37168e3e3a7aSWarner Losh
37178e3e3a7aSWarner Losh
37188e3e3a7aSWarner Losh<hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p>
37198e3e3a7aSWarner Losh<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span>
37208e3e3a7aSWarner Losh<pre>void lua_callk (lua_State *L,
37218e3e3a7aSWarner Losh                int nargs,
37228e3e3a7aSWarner Losh                int nresults,
37238e3e3a7aSWarner Losh                lua_KContext ctx,
37248e3e3a7aSWarner Losh                lua_KFunction k);</pre>
37258e3e3a7aSWarner Losh
37268e3e3a7aSWarner Losh<p>
37278e3e3a7aSWarner LoshThis function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>,
37280495ed39SKyle Evansbut allows the called function to yield (see <a href="#4.5">&sect;4.5</a>).
37298e3e3a7aSWarner Losh
37308e3e3a7aSWarner Losh
37318e3e3a7aSWarner Losh
37328e3e3a7aSWarner Losh
37338e3e3a7aSWarner Losh
37348e3e3a7aSWarner Losh<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3>
37358e3e3a7aSWarner Losh<pre>typedef int (*lua_CFunction) (lua_State *L);</pre>
37368e3e3a7aSWarner Losh
37378e3e3a7aSWarner Losh<p>
37388e3e3a7aSWarner LoshType for C&nbsp;functions.
37398e3e3a7aSWarner Losh
37408e3e3a7aSWarner Losh
37418e3e3a7aSWarner Losh<p>
37428e3e3a7aSWarner LoshIn order to communicate properly with Lua,
37438e3e3a7aSWarner Losha C&nbsp;function must use the following protocol,
37448e3e3a7aSWarner Loshwhich defines the way parameters and results are passed:
37458e3e3a7aSWarner Losha C&nbsp;function receives its arguments from Lua in its stack
37468e3e3a7aSWarner Loshin direct order (the first argument is pushed first).
37478e3e3a7aSWarner LoshSo, when the function starts,
37488e3e3a7aSWarner Losh<code>lua_gettop(L)</code> returns the number of arguments received by the function.
37498e3e3a7aSWarner LoshThe first argument (if any) is at index 1
37508e3e3a7aSWarner Loshand its last argument is at index <code>lua_gettop(L)</code>.
37518e3e3a7aSWarner LoshTo return values to Lua, a C&nbsp;function just pushes them onto the stack,
37528e3e3a7aSWarner Loshin direct order (the first result is pushed first),
37530495ed39SKyle Evansand returns in C the number of results.
37548e3e3a7aSWarner LoshAny other value in the stack below the results will be properly
37558e3e3a7aSWarner Loshdiscarded by Lua.
37568e3e3a7aSWarner LoshLike a Lua function, a C&nbsp;function called by Lua can also return
37578e3e3a7aSWarner Loshmany results.
37588e3e3a7aSWarner Losh
37598e3e3a7aSWarner Losh
37608e3e3a7aSWarner Losh<p>
37618e3e3a7aSWarner LoshAs an example, the following function receives a variable number
37628e3e3a7aSWarner Loshof numeric arguments and returns their average and their sum:
37638e3e3a7aSWarner Losh
37648e3e3a7aSWarner Losh<pre>
37658e3e3a7aSWarner Losh     static int foo (lua_State *L) {
37668e3e3a7aSWarner Losh       int n = lua_gettop(L);    /* number of arguments */
37678e3e3a7aSWarner Losh       lua_Number sum = 0.0;
37688e3e3a7aSWarner Losh       int i;
37698e3e3a7aSWarner Losh       for (i = 1; i &lt;= n; i++) {
37708e3e3a7aSWarner Losh         if (!lua_isnumber(L, i)) {
37718e3e3a7aSWarner Losh           lua_pushliteral(L, "incorrect argument");
37728e3e3a7aSWarner Losh           lua_error(L);
37738e3e3a7aSWarner Losh         }
37748e3e3a7aSWarner Losh         sum += lua_tonumber(L, i);
37758e3e3a7aSWarner Losh       }
37768e3e3a7aSWarner Losh       lua_pushnumber(L, sum/n);        /* first result */
37778e3e3a7aSWarner Losh       lua_pushnumber(L, sum);         /* second result */
37788e3e3a7aSWarner Losh       return 2;                   /* number of results */
37798e3e3a7aSWarner Losh     }
37808e3e3a7aSWarner Losh</pre>
37818e3e3a7aSWarner Losh
37828e3e3a7aSWarner Losh
37838e3e3a7aSWarner Losh
37848e3e3a7aSWarner Losh
37858e3e3a7aSWarner Losh<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p>
37868e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
37878e3e3a7aSWarner Losh<pre>int lua_checkstack (lua_State *L, int n);</pre>
37888e3e3a7aSWarner Losh
37898e3e3a7aSWarner Losh<p>
37900495ed39SKyle EvansEnsures that the stack has space for at least <code>n</code> extra elements,
37910495ed39SKyle Evansthat is, that you can safely push up to <code>n</code> values into it.
37928e3e3a7aSWarner LoshIt returns false if it cannot fulfill the request,
37938e3e3a7aSWarner Losheither because it would cause the stack
37940495ed39SKyle Evansto be greater than a fixed maximum size
37958e3e3a7aSWarner Losh(typically at least several thousand elements) or
37968e3e3a7aSWarner Loshbecause it cannot allocate memory for the extra space.
37978e3e3a7aSWarner LoshThis function never shrinks the stack;
37980495ed39SKyle Evansif the stack already has space for the extra elements,
37998e3e3a7aSWarner Loshit is left unchanged.
38008e3e3a7aSWarner Losh
38018e3e3a7aSWarner Losh
38028e3e3a7aSWarner Losh
38038e3e3a7aSWarner Losh
38048e3e3a7aSWarner Losh
38058e3e3a7aSWarner Losh<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p>
38068e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
38078e3e3a7aSWarner Losh<pre>void lua_close (lua_State *L);</pre>
38088e3e3a7aSWarner Losh
38098e3e3a7aSWarner Losh<p>
38100495ed39SKyle EvansClose all active to-be-closed variables in the main thread,
38110495ed39SKyle Evansrelease all objects in the given Lua state
38120495ed39SKyle Evans(calling the corresponding garbage-collection metamethods, if any),
38138e3e3a7aSWarner Loshand frees all dynamic memory used by this state.
38140495ed39SKyle Evans
38150495ed39SKyle Evans
38160495ed39SKyle Evans<p>
38170495ed39SKyle EvansOn several platforms, you may not need to call this function,
38188e3e3a7aSWarner Loshbecause all resources are naturally released when the host program ends.
38198e3e3a7aSWarner LoshOn the other hand, long-running programs that create multiple states,
38208e3e3a7aSWarner Loshsuch as daemons or web servers,
38218e3e3a7aSWarner Loshwill probably need to close states as soon as they are not needed.
38228e3e3a7aSWarner Losh
38238e3e3a7aSWarner Losh
38248e3e3a7aSWarner Losh
38258e3e3a7aSWarner Losh
38268e3e3a7aSWarner Losh
38278c784bb8SWarner Losh<hr><h3><a name="lua_closeslot"><code>lua_closeslot</code></a></h3><p>
38288c784bb8SWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span>
38298c784bb8SWarner Losh<pre>void lua_closeslot (lua_State *L, int index);</pre>
38308c784bb8SWarner Losh
38318c784bb8SWarner Losh<p>
38328c784bb8SWarner LoshClose the to-be-closed slot at the given index and set its value to <b>nil</b>.
38338c784bb8SWarner LoshThe index must be the last index previously marked to be closed
38348c784bb8SWarner Losh(see <a href="#lua_toclose"><code>lua_toclose</code></a>) that is still active (that is, not closed yet).
38358c784bb8SWarner Losh
38368c784bb8SWarner Losh
38378c784bb8SWarner Losh<p>
38388c784bb8SWarner LoshA <code>__close</code> metamethod cannot yield
38398c784bb8SWarner Loshwhen called through this function.
38408c784bb8SWarner Losh
38418c784bb8SWarner Losh
38428c784bb8SWarner Losh<p>
3843a9490b81SWarner Losh(This function was introduced in release&nbsp;5.4.3.)
3844a9490b81SWarner Losh
3845a9490b81SWarner Losh
3846a9490b81SWarner Losh
3847a9490b81SWarner Losh
3848a9490b81SWarner Losh
3849a9490b81SWarner Losh<hr><h3><a name="lua_closethread"><code>lua_closethread</code></a></h3><p>
3850a9490b81SWarner Losh<span class="apii">[-0, +?, &ndash;]</span>
3851a9490b81SWarner Losh<pre>int lua_closethread (lua_State *L, lua_State *from);</pre>
3852a9490b81SWarner Losh
3853a9490b81SWarner Losh<p>
3854a9490b81SWarner LoshResets a thread, cleaning its call stack and closing all pending
3855a9490b81SWarner Loshto-be-closed variables.
3856a9490b81SWarner LoshReturns a status code:
3857a9490b81SWarner Losh<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for no errors in the thread
3858a9490b81SWarner Losh(either the original error that stopped the thread or
3859a9490b81SWarner Losherrors in closing methods),
3860a9490b81SWarner Loshor an error status otherwise.
3861a9490b81SWarner LoshIn case of error,
3862a9490b81SWarner Loshleaves the error object on the top of the stack.
3863a9490b81SWarner Losh
3864a9490b81SWarner Losh
3865a9490b81SWarner Losh<p>
3866a9490b81SWarner LoshThe parameter <code>from</code> represents the coroutine that is resetting <code>L</code>.
3867a9490b81SWarner LoshIf there is no such coroutine,
3868a9490b81SWarner Loshthis parameter can be <code>NULL</code>.
3869a9490b81SWarner Losh
3870a9490b81SWarner Losh
3871a9490b81SWarner Losh<p>
3872a9490b81SWarner Losh(This function was introduced in release&nbsp;5.4.6.)
38738c784bb8SWarner Losh
38748c784bb8SWarner Losh
38758c784bb8SWarner Losh
38768c784bb8SWarner Losh
38778c784bb8SWarner Losh
38788e3e3a7aSWarner Losh<hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p>
38798e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span>
38808e3e3a7aSWarner Losh<pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre>
38818e3e3a7aSWarner Losh
38828e3e3a7aSWarner Losh<p>
38838e3e3a7aSWarner LoshCompares two Lua values.
38848e3e3a7aSWarner LoshReturns 1 if the value at index <code>index1</code> satisfies <code>op</code>
38858e3e3a7aSWarner Loshwhen compared with the value at index <code>index2</code>,
38868e3e3a7aSWarner Loshfollowing the semantics of the corresponding Lua operator
38878e3e3a7aSWarner Losh(that is, it may call metamethods).
38888e3e3a7aSWarner LoshOtherwise returns&nbsp;0.
38898e3e3a7aSWarner LoshAlso returns&nbsp;0 if any of the indices is not valid.
38908e3e3a7aSWarner Losh
38918e3e3a7aSWarner Losh
38928e3e3a7aSWarner Losh<p>
38938e3e3a7aSWarner LoshThe value of <code>op</code> must be one of the following constants:
38948e3e3a7aSWarner Losh
38958e3e3a7aSWarner Losh<ul>
38968e3e3a7aSWarner Losh
38978e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li>
38988e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code>&lt;</code>)</li>
38998e3e3a7aSWarner Losh<li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code>&lt;=</code>)</li>
39008e3e3a7aSWarner Losh
39018e3e3a7aSWarner Losh</ul>
39028e3e3a7aSWarner Losh
39038e3e3a7aSWarner Losh
39048e3e3a7aSWarner Losh
39058e3e3a7aSWarner Losh
39068e3e3a7aSWarner Losh<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p>
39078e3e3a7aSWarner Losh<span class="apii">[-n, +1, <em>e</em>]</span>
39088e3e3a7aSWarner Losh<pre>void lua_concat (lua_State *L, int n);</pre>
39098e3e3a7aSWarner Losh
39108e3e3a7aSWarner Losh<p>
39118e3e3a7aSWarner LoshConcatenates the <code>n</code> values at the top of the stack,
39120495ed39SKyle Evanspops them, and leaves the result on the top.
39138e3e3a7aSWarner LoshIf <code>n</code>&nbsp;is&nbsp;1, the result is the single value on the stack
39148e3e3a7aSWarner Losh(that is, the function does nothing);
39158e3e3a7aSWarner Loshif <code>n</code> is 0, the result is the empty string.
39168e3e3a7aSWarner LoshConcatenation is performed following the usual semantics of Lua
39178e3e3a7aSWarner Losh(see <a href="#3.4.6">&sect;3.4.6</a>).
39188e3e3a7aSWarner Losh
39198e3e3a7aSWarner Losh
39208e3e3a7aSWarner Losh
39218e3e3a7aSWarner Losh
39228e3e3a7aSWarner Losh
39238e3e3a7aSWarner Losh<hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p>
39248e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
39258e3e3a7aSWarner Losh<pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre>
39268e3e3a7aSWarner Losh
39278e3e3a7aSWarner Losh<p>
39288e3e3a7aSWarner LoshCopies the element at index <code>fromidx</code>
39298e3e3a7aSWarner Loshinto the valid index <code>toidx</code>,
39308e3e3a7aSWarner Loshreplacing the value at that position.
39318e3e3a7aSWarner LoshValues at other positions are not affected.
39328e3e3a7aSWarner Losh
39338e3e3a7aSWarner Losh
39348e3e3a7aSWarner Losh
39358e3e3a7aSWarner Losh
39368e3e3a7aSWarner Losh
39378e3e3a7aSWarner Losh<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p>
39388e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
39398e3e3a7aSWarner Losh<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre>
39408e3e3a7aSWarner Losh
39418e3e3a7aSWarner Losh<p>
39428e3e3a7aSWarner LoshCreates a new empty table and pushes it onto the stack.
39438e3e3a7aSWarner LoshParameter <code>narr</code> is a hint for how many elements the table
39448e3e3a7aSWarner Loshwill have as a sequence;
39458e3e3a7aSWarner Loshparameter <code>nrec</code> is a hint for how many other elements
39468e3e3a7aSWarner Loshthe table will have.
39478e3e3a7aSWarner LoshLua may use these hints to preallocate memory for the new table.
39480495ed39SKyle EvansThis preallocation may help performance when you know in advance
39498e3e3a7aSWarner Loshhow many elements the table will have.
39508e3e3a7aSWarner LoshOtherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>.
39518e3e3a7aSWarner Losh
39528e3e3a7aSWarner Losh
39538e3e3a7aSWarner Losh
39548e3e3a7aSWarner Losh
39558e3e3a7aSWarner Losh
39568e3e3a7aSWarner Losh<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p>
39578e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
39588e3e3a7aSWarner Losh<pre>int lua_dump (lua_State *L,
39598e3e3a7aSWarner Losh                        lua_Writer writer,
39608e3e3a7aSWarner Losh                        void *data,
39618e3e3a7aSWarner Losh                        int strip);</pre>
39628e3e3a7aSWarner Losh
39638e3e3a7aSWarner Losh<p>
39648e3e3a7aSWarner LoshDumps a function as a binary chunk.
39658e3e3a7aSWarner LoshReceives a Lua function on the top of the stack
39668e3e3a7aSWarner Loshand produces a binary chunk that,
39678e3e3a7aSWarner Loshif loaded again,
39688e3e3a7aSWarner Loshresults in a function equivalent to the one dumped.
39698e3e3a7aSWarner LoshAs it produces parts of the chunk,
39708e3e3a7aSWarner Losh<a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>)
39718e3e3a7aSWarner Loshwith the given <code>data</code>
39728e3e3a7aSWarner Loshto write them.
39738e3e3a7aSWarner Losh
39748e3e3a7aSWarner Losh
39758e3e3a7aSWarner Losh<p>
39768e3e3a7aSWarner LoshIf <code>strip</code> is true,
39778e3e3a7aSWarner Loshthe binary representation may not include all debug information
39788e3e3a7aSWarner Loshabout the function,
39798e3e3a7aSWarner Loshto save space.
39808e3e3a7aSWarner Losh
39818e3e3a7aSWarner Losh
39828e3e3a7aSWarner Losh<p>
39838e3e3a7aSWarner LoshThe value returned is the error code returned by the last
39848e3e3a7aSWarner Loshcall to the writer;
39858e3e3a7aSWarner Losh0&nbsp;means no errors.
39868e3e3a7aSWarner Losh
39878e3e3a7aSWarner Losh
39888e3e3a7aSWarner Losh<p>
39898e3e3a7aSWarner LoshThis function does not pop the Lua function from the stack.
39908e3e3a7aSWarner Losh
39918e3e3a7aSWarner Losh
39928e3e3a7aSWarner Losh
39938e3e3a7aSWarner Losh
39948e3e3a7aSWarner Losh
39958e3e3a7aSWarner Losh<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p>
39968e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>v</em>]</span>
39978e3e3a7aSWarner Losh<pre>int lua_error (lua_State *L);</pre>
39988e3e3a7aSWarner Losh
39998e3e3a7aSWarner Losh<p>
40000495ed39SKyle EvansRaises a Lua error,
40010495ed39SKyle Evansusing the value on the top of the stack as the error object.
40028e3e3a7aSWarner LoshThis function does a long jump,
40038e3e3a7aSWarner Loshand therefore never returns
40048e3e3a7aSWarner Losh(see <a href="#luaL_error"><code>luaL_error</code></a>).
40058e3e3a7aSWarner Losh
40068e3e3a7aSWarner Losh
40078e3e3a7aSWarner Losh
40088e3e3a7aSWarner Losh
40098e3e3a7aSWarner Losh
40108e3e3a7aSWarner Losh<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p>
40110495ed39SKyle Evans<span class="apii">[-0, +0, &ndash;]</span>
40120495ed39SKyle Evans<pre>int lua_gc (lua_State *L, int what, ...);</pre>
40138e3e3a7aSWarner Losh
40148e3e3a7aSWarner Losh<p>
40158e3e3a7aSWarner LoshControls the garbage collector.
40168e3e3a7aSWarner Losh
40178e3e3a7aSWarner Losh
40188e3e3a7aSWarner Losh<p>
40198e3e3a7aSWarner LoshThis function performs several tasks,
40200495ed39SKyle Evansaccording to the value of the parameter <code>what</code>.
40210495ed39SKyle EvansFor options that need extra arguments,
40220495ed39SKyle Evansthey are listed after the option.
40238e3e3a7aSWarner Losh
40248e3e3a7aSWarner Losh<ul>
40258e3e3a7aSWarner Losh
40260495ed39SKyle Evans<li><b><code>LUA_GCCOLLECT</code>: </b>
40270495ed39SKyle EvansPerforms a full garbage-collection cycle.
40280495ed39SKyle Evans</li>
40290495ed39SKyle Evans
40308e3e3a7aSWarner Losh<li><b><code>LUA_GCSTOP</code>: </b>
40310495ed39SKyle EvansStops the garbage collector.
40328e3e3a7aSWarner Losh</li>
40338e3e3a7aSWarner Losh
40348e3e3a7aSWarner Losh<li><b><code>LUA_GCRESTART</code>: </b>
40350495ed39SKyle EvansRestarts the garbage collector.
40368e3e3a7aSWarner Losh</li>
40378e3e3a7aSWarner Losh
40388e3e3a7aSWarner Losh<li><b><code>LUA_GCCOUNT</code>: </b>
40390495ed39SKyle EvansReturns the current amount of memory (in Kbytes) in use by Lua.
40408e3e3a7aSWarner Losh</li>
40418e3e3a7aSWarner Losh
40428e3e3a7aSWarner Losh<li><b><code>LUA_GCCOUNTB</code>: </b>
40430495ed39SKyle EvansReturns the remainder of dividing the current amount of bytes of
40448e3e3a7aSWarner Loshmemory in use by Lua by 1024.
40458e3e3a7aSWarner Losh</li>
40468e3e3a7aSWarner Losh
40470495ed39SKyle Evans<li><b><code>LUA_GCSTEP</code> <code>(int stepsize)</code>: </b>
40480495ed39SKyle EvansPerforms an incremental step of garbage collection,
40490495ed39SKyle Evanscorresponding to the allocation of <code>stepsize</code> Kbytes.
40508e3e3a7aSWarner Losh</li>
40518e3e3a7aSWarner Losh
40528e3e3a7aSWarner Losh<li><b><code>LUA_GCISRUNNING</code>: </b>
40530495ed39SKyle EvansReturns a boolean that tells whether the collector is running
40548e3e3a7aSWarner Losh(i.e., not stopped).
40558e3e3a7aSWarner Losh</li>
40568e3e3a7aSWarner Losh
40570495ed39SKyle Evans<li><b><code>LUA_GCINC</code> (int pause, int stepmul, stepsize): </b>
40580495ed39SKyle EvansChanges the collector to incremental mode
40590495ed39SKyle Evanswith the given parameters (see <a href="#2.5.1">&sect;2.5.1</a>).
40600495ed39SKyle EvansReturns the previous mode (<code>LUA_GCGEN</code> or <code>LUA_GCINC</code>).
40610495ed39SKyle Evans</li>
40628e3e3a7aSWarner Losh
40630495ed39SKyle Evans<li><b><code>LUA_GCGEN</code> (int minormul, int majormul): </b>
40640495ed39SKyle EvansChanges the collector to generational mode
40650495ed39SKyle Evanswith the given parameters (see <a href="#2.5.2">&sect;2.5.2</a>).
40660495ed39SKyle EvansReturns the previous mode (<code>LUA_GCGEN</code> or <code>LUA_GCINC</code>).
40670495ed39SKyle Evans</li>
40680495ed39SKyle Evans
40690495ed39SKyle Evans</ul><p>
40708e3e3a7aSWarner LoshFor more details about these options,
40718e3e3a7aSWarner Loshsee <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>.
40728e3e3a7aSWarner Losh
40738e3e3a7aSWarner Losh
40748c784bb8SWarner Losh<p>
40758c784bb8SWarner LoshThis function should not be called by a finalizer.
40768c784bb8SWarner Losh
40778c784bb8SWarner Losh
40788e3e3a7aSWarner Losh
40798e3e3a7aSWarner Losh
40808e3e3a7aSWarner Losh
40818e3e3a7aSWarner Losh<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p>
40828e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
40838e3e3a7aSWarner Losh<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre>
40848e3e3a7aSWarner Losh
40858e3e3a7aSWarner Losh<p>
40868e3e3a7aSWarner LoshReturns the memory-allocation function of a given state.
40878e3e3a7aSWarner LoshIf <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the
40888e3e3a7aSWarner Loshopaque pointer given when the memory-allocator function was set.
40898e3e3a7aSWarner Losh
40908e3e3a7aSWarner Losh
40918e3e3a7aSWarner Losh
40928e3e3a7aSWarner Losh
40938e3e3a7aSWarner Losh
40948e3e3a7aSWarner Losh<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p>
40958e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span>
40968e3e3a7aSWarner Losh<pre>int lua_getfield (lua_State *L, int index, const char *k);</pre>
40978e3e3a7aSWarner Losh
40988e3e3a7aSWarner Losh<p>
40998e3e3a7aSWarner LoshPushes onto the stack the value <code>t[k]</code>,
41008e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index.
41018e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod
41028e3e3a7aSWarner Loshfor the "index" event (see <a href="#2.4">&sect;2.4</a>).
41038e3e3a7aSWarner Losh
41048e3e3a7aSWarner Losh
41058e3e3a7aSWarner Losh<p>
41068e3e3a7aSWarner LoshReturns the type of the pushed value.
41078e3e3a7aSWarner Losh
41088e3e3a7aSWarner Losh
41098e3e3a7aSWarner Losh
41108e3e3a7aSWarner Losh
41118e3e3a7aSWarner Losh
41128e3e3a7aSWarner Losh<hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p>
41138e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
41148e3e3a7aSWarner Losh<pre>void *lua_getextraspace (lua_State *L);</pre>
41158e3e3a7aSWarner Losh
41168e3e3a7aSWarner Losh<p>
41178e3e3a7aSWarner LoshReturns a pointer to a raw memory area associated with the
41188e3e3a7aSWarner Loshgiven Lua state.
41198e3e3a7aSWarner LoshThe application can use this area for any purpose;
41208e3e3a7aSWarner LoshLua does not use it for anything.
41218e3e3a7aSWarner Losh
41228e3e3a7aSWarner Losh
41238e3e3a7aSWarner Losh<p>
41248e3e3a7aSWarner LoshEach new thread has this area initialized with a copy
41258e3e3a7aSWarner Loshof the area of the main thread.
41268e3e3a7aSWarner Losh
41278e3e3a7aSWarner Losh
41288e3e3a7aSWarner Losh<p>
41298e3e3a7aSWarner LoshBy default, this area has the size of a pointer to void,
41308e3e3a7aSWarner Loshbut you can recompile Lua with a different size for this area.
41318e3e3a7aSWarner Losh(See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.)
41328e3e3a7aSWarner Losh
41338e3e3a7aSWarner Losh
41348e3e3a7aSWarner Losh
41358e3e3a7aSWarner Losh
41368e3e3a7aSWarner Losh
41378e3e3a7aSWarner Losh<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p>
41388e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span>
41398e3e3a7aSWarner Losh<pre>int lua_getglobal (lua_State *L, const char *name);</pre>
41408e3e3a7aSWarner Losh
41418e3e3a7aSWarner Losh<p>
41428e3e3a7aSWarner LoshPushes onto the stack the value of the global <code>name</code>.
41438e3e3a7aSWarner LoshReturns the type of that value.
41448e3e3a7aSWarner Losh
41458e3e3a7aSWarner Losh
41468e3e3a7aSWarner Losh
41478e3e3a7aSWarner Losh
41488e3e3a7aSWarner Losh
41498e3e3a7aSWarner Losh<hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p>
41508e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span>
41518e3e3a7aSWarner Losh<pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre>
41528e3e3a7aSWarner Losh
41538e3e3a7aSWarner Losh<p>
41548e3e3a7aSWarner LoshPushes onto the stack the value <code>t[i]</code>,
41558e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index.
41568e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod
41578e3e3a7aSWarner Loshfor the "index" event (see <a href="#2.4">&sect;2.4</a>).
41588e3e3a7aSWarner Losh
41598e3e3a7aSWarner Losh
41608e3e3a7aSWarner Losh<p>
41618e3e3a7aSWarner LoshReturns the type of the pushed value.
41628e3e3a7aSWarner Losh
41638e3e3a7aSWarner Losh
41648e3e3a7aSWarner Losh
41658e3e3a7aSWarner Losh
41668e3e3a7aSWarner Losh
41678e3e3a7aSWarner Losh<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p>
41688e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), &ndash;]</span>
41698e3e3a7aSWarner Losh<pre>int lua_getmetatable (lua_State *L, int index);</pre>
41708e3e3a7aSWarner Losh
41718e3e3a7aSWarner Losh<p>
41728e3e3a7aSWarner LoshIf the value at the given index has a metatable,
41738e3e3a7aSWarner Loshthe function pushes that metatable onto the stack and returns&nbsp;1.
41748e3e3a7aSWarner LoshOtherwise,
41758e3e3a7aSWarner Loshthe function returns&nbsp;0 and pushes nothing on the stack.
41768e3e3a7aSWarner Losh
41778e3e3a7aSWarner Losh
41788e3e3a7aSWarner Losh
41798e3e3a7aSWarner Losh
41808e3e3a7aSWarner Losh
41818e3e3a7aSWarner Losh<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p>
41828e3e3a7aSWarner Losh<span class="apii">[-1, +1, <em>e</em>]</span>
41838e3e3a7aSWarner Losh<pre>int lua_gettable (lua_State *L, int index);</pre>
41848e3e3a7aSWarner Losh
41858e3e3a7aSWarner Losh<p>
41868e3e3a7aSWarner LoshPushes onto the stack the value <code>t[k]</code>,
41878e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index
41880495ed39SKyle Evansand <code>k</code> is the value on the top of the stack.
41898e3e3a7aSWarner Losh
41908e3e3a7aSWarner Losh
41918e3e3a7aSWarner Losh<p>
41928e3e3a7aSWarner LoshThis function pops the key from the stack,
41938e3e3a7aSWarner Loshpushing the resulting value in its place.
41948e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod
41958e3e3a7aSWarner Loshfor the "index" event (see <a href="#2.4">&sect;2.4</a>).
41968e3e3a7aSWarner Losh
41978e3e3a7aSWarner Losh
41988e3e3a7aSWarner Losh<p>
41998e3e3a7aSWarner LoshReturns the type of the pushed value.
42008e3e3a7aSWarner Losh
42018e3e3a7aSWarner Losh
42028e3e3a7aSWarner Losh
42038e3e3a7aSWarner Losh
42048e3e3a7aSWarner Losh
42058e3e3a7aSWarner Losh<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p>
42068e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
42078e3e3a7aSWarner Losh<pre>int lua_gettop (lua_State *L);</pre>
42088e3e3a7aSWarner Losh
42098e3e3a7aSWarner Losh<p>
42108e3e3a7aSWarner LoshReturns the index of the top element in the stack.
42118e3e3a7aSWarner LoshBecause indices start at&nbsp;1,
42128e3e3a7aSWarner Loshthis result is equal to the number of elements in the stack;
42138e3e3a7aSWarner Loshin particular, 0&nbsp;means an empty stack.
42148e3e3a7aSWarner Losh
42158e3e3a7aSWarner Losh
42168e3e3a7aSWarner Losh
42178e3e3a7aSWarner Losh
42188e3e3a7aSWarner Losh
42190495ed39SKyle Evans<hr><h3><a name="lua_getiuservalue"><code>lua_getiuservalue</code></a></h3><p>
42208e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
42210495ed39SKyle Evans<pre>int lua_getiuservalue (lua_State *L, int index, int n);</pre>
42228e3e3a7aSWarner Losh
42238e3e3a7aSWarner Losh<p>
42240495ed39SKyle EvansPushes onto the stack the <code>n</code>-th user value associated with the
42250495ed39SKyle Evansfull userdata at the given index and
42260495ed39SKyle Evansreturns the type of the pushed value.
42278e3e3a7aSWarner Losh
42288e3e3a7aSWarner Losh
42298e3e3a7aSWarner Losh<p>
42300495ed39SKyle EvansIf the userdata does not have that value,
42310495ed39SKyle Evanspushes <b>nil</b> and returns <a href="#pdf-LUA_TNONE"><code>LUA_TNONE</code></a>.
42328e3e3a7aSWarner Losh
42338e3e3a7aSWarner Losh
42348e3e3a7aSWarner Losh
42358e3e3a7aSWarner Losh
42368e3e3a7aSWarner Losh
42378e3e3a7aSWarner Losh<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p>
42388e3e3a7aSWarner Losh<span class="apii">[-1, +1, &ndash;]</span>
42398e3e3a7aSWarner Losh<pre>void lua_insert (lua_State *L, int index);</pre>
42408e3e3a7aSWarner Losh
42418e3e3a7aSWarner Losh<p>
42428e3e3a7aSWarner LoshMoves the top element into the given valid index,
42438e3e3a7aSWarner Loshshifting up the elements above this index to open space.
42448e3e3a7aSWarner LoshThis function cannot be called with a pseudo-index,
42458e3e3a7aSWarner Loshbecause a pseudo-index is not an actual stack position.
42468e3e3a7aSWarner Losh
42478e3e3a7aSWarner Losh
42488e3e3a7aSWarner Losh
42498e3e3a7aSWarner Losh
42508e3e3a7aSWarner Losh
42518e3e3a7aSWarner Losh<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3>
42528e3e3a7aSWarner Losh<pre>typedef ... lua_Integer;</pre>
42538e3e3a7aSWarner Losh
42548e3e3a7aSWarner Losh<p>
42558e3e3a7aSWarner LoshThe type of integers in Lua.
42568e3e3a7aSWarner Losh
42578e3e3a7aSWarner Losh
42588e3e3a7aSWarner Losh<p>
42598e3e3a7aSWarner LoshBy default this type is <code>long long</code>,
42608e3e3a7aSWarner Losh(usually a 64-bit two-complement integer),
42618e3e3a7aSWarner Loshbut that can be changed to <code>long</code> or <code>int</code>
42628e3e3a7aSWarner Losh(usually a 32-bit two-complement integer).
42638e3e3a7aSWarner Losh(See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.)
42648e3e3a7aSWarner Losh
42658e3e3a7aSWarner Losh
42668e3e3a7aSWarner Losh<p>
42678e3e3a7aSWarner LoshLua also defines the constants
42688e3e3a7aSWarner Losh<a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>,
42698e3e3a7aSWarner Loshwith the minimum and the maximum values that fit in this type.
42708e3e3a7aSWarner Losh
42718e3e3a7aSWarner Losh
42728e3e3a7aSWarner Losh
42738e3e3a7aSWarner Losh
42748e3e3a7aSWarner Losh
42758e3e3a7aSWarner Losh<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p>
42768e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
42778e3e3a7aSWarner Losh<pre>int lua_isboolean (lua_State *L, int index);</pre>
42788e3e3a7aSWarner Losh
42798e3e3a7aSWarner Losh<p>
42808e3e3a7aSWarner LoshReturns 1 if the value at the given index is a boolean,
42818e3e3a7aSWarner Loshand 0&nbsp;otherwise.
42828e3e3a7aSWarner Losh
42838e3e3a7aSWarner Losh
42848e3e3a7aSWarner Losh
42858e3e3a7aSWarner Losh
42868e3e3a7aSWarner Losh
42878e3e3a7aSWarner Losh<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p>
42888e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
42898e3e3a7aSWarner Losh<pre>int lua_iscfunction (lua_State *L, int index);</pre>
42908e3e3a7aSWarner Losh
42918e3e3a7aSWarner Losh<p>
42928e3e3a7aSWarner LoshReturns 1 if the value at the given index is a C&nbsp;function,
42938e3e3a7aSWarner Loshand 0&nbsp;otherwise.
42948e3e3a7aSWarner Losh
42958e3e3a7aSWarner Losh
42968e3e3a7aSWarner Losh
42978e3e3a7aSWarner Losh
42988e3e3a7aSWarner Losh
42998e3e3a7aSWarner Losh<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p>
43008e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
43018e3e3a7aSWarner Losh<pre>int lua_isfunction (lua_State *L, int index);</pre>
43028e3e3a7aSWarner Losh
43038e3e3a7aSWarner Losh<p>
43048e3e3a7aSWarner LoshReturns 1 if the value at the given index is a function
43058e3e3a7aSWarner Losh(either C or Lua), and 0&nbsp;otherwise.
43068e3e3a7aSWarner Losh
43078e3e3a7aSWarner Losh
43088e3e3a7aSWarner Losh
43098e3e3a7aSWarner Losh
43108e3e3a7aSWarner Losh
43118e3e3a7aSWarner Losh<hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p>
43128e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
43138e3e3a7aSWarner Losh<pre>int lua_isinteger (lua_State *L, int index);</pre>
43148e3e3a7aSWarner Losh
43158e3e3a7aSWarner Losh<p>
43168e3e3a7aSWarner LoshReturns 1 if the value at the given index is an integer
43178e3e3a7aSWarner Losh(that is, the value is a number and is represented as an integer),
43188e3e3a7aSWarner Loshand 0&nbsp;otherwise.
43198e3e3a7aSWarner Losh
43208e3e3a7aSWarner Losh
43218e3e3a7aSWarner Losh
43228e3e3a7aSWarner Losh
43238e3e3a7aSWarner Losh
43248e3e3a7aSWarner Losh<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p>
43258e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
43268e3e3a7aSWarner Losh<pre>int lua_islightuserdata (lua_State *L, int index);</pre>
43278e3e3a7aSWarner Losh
43288e3e3a7aSWarner Losh<p>
43298e3e3a7aSWarner LoshReturns 1 if the value at the given index is a light userdata,
43308e3e3a7aSWarner Loshand 0&nbsp;otherwise.
43318e3e3a7aSWarner Losh
43328e3e3a7aSWarner Losh
43338e3e3a7aSWarner Losh
43348e3e3a7aSWarner Losh
43358e3e3a7aSWarner Losh
43368e3e3a7aSWarner Losh<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p>
43378e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
43388e3e3a7aSWarner Losh<pre>int lua_isnil (lua_State *L, int index);</pre>
43398e3e3a7aSWarner Losh
43408e3e3a7aSWarner Losh<p>
43418e3e3a7aSWarner LoshReturns 1 if the value at the given index is <b>nil</b>,
43428e3e3a7aSWarner Loshand 0&nbsp;otherwise.
43438e3e3a7aSWarner Losh
43448e3e3a7aSWarner Losh
43458e3e3a7aSWarner Losh
43468e3e3a7aSWarner Losh
43478e3e3a7aSWarner Losh
43488e3e3a7aSWarner Losh<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p>
43498e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
43508e3e3a7aSWarner Losh<pre>int lua_isnone (lua_State *L, int index);</pre>
43518e3e3a7aSWarner Losh
43528e3e3a7aSWarner Losh<p>
43538e3e3a7aSWarner LoshReturns 1 if the given index is not valid,
43548e3e3a7aSWarner Loshand 0&nbsp;otherwise.
43558e3e3a7aSWarner Losh
43568e3e3a7aSWarner Losh
43578e3e3a7aSWarner Losh
43588e3e3a7aSWarner Losh
43598e3e3a7aSWarner Losh
43608e3e3a7aSWarner Losh<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p>
43618e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
43628e3e3a7aSWarner Losh<pre>int lua_isnoneornil (lua_State *L, int index);</pre>
43638e3e3a7aSWarner Losh
43648e3e3a7aSWarner Losh<p>
43658e3e3a7aSWarner LoshReturns 1 if the given index is not valid
43668e3e3a7aSWarner Loshor if the value at this index is <b>nil</b>,
43678e3e3a7aSWarner Loshand 0&nbsp;otherwise.
43688e3e3a7aSWarner Losh
43698e3e3a7aSWarner Losh
43708e3e3a7aSWarner Losh
43718e3e3a7aSWarner Losh
43728e3e3a7aSWarner Losh
43738e3e3a7aSWarner Losh<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p>
43748e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
43758e3e3a7aSWarner Losh<pre>int lua_isnumber (lua_State *L, int index);</pre>
43768e3e3a7aSWarner Losh
43778e3e3a7aSWarner Losh<p>
43788e3e3a7aSWarner LoshReturns 1 if the value at the given index is a number
43798e3e3a7aSWarner Loshor a string convertible to a number,
43808e3e3a7aSWarner Loshand 0&nbsp;otherwise.
43818e3e3a7aSWarner Losh
43828e3e3a7aSWarner Losh
43838e3e3a7aSWarner Losh
43848e3e3a7aSWarner Losh
43858e3e3a7aSWarner Losh
43868e3e3a7aSWarner Losh<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p>
43878e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
43888e3e3a7aSWarner Losh<pre>int lua_isstring (lua_State *L, int index);</pre>
43898e3e3a7aSWarner Losh
43908e3e3a7aSWarner Losh<p>
43918e3e3a7aSWarner LoshReturns 1 if the value at the given index is a string
43928e3e3a7aSWarner Loshor a number (which is always convertible to a string),
43938e3e3a7aSWarner Loshand 0&nbsp;otherwise.
43948e3e3a7aSWarner Losh
43958e3e3a7aSWarner Losh
43968e3e3a7aSWarner Losh
43978e3e3a7aSWarner Losh
43988e3e3a7aSWarner Losh
43998e3e3a7aSWarner Losh<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p>
44008e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
44018e3e3a7aSWarner Losh<pre>int lua_istable (lua_State *L, int index);</pre>
44028e3e3a7aSWarner Losh
44038e3e3a7aSWarner Losh<p>
44048e3e3a7aSWarner LoshReturns 1 if the value at the given index is a table,
44058e3e3a7aSWarner Loshand 0&nbsp;otherwise.
44068e3e3a7aSWarner Losh
44078e3e3a7aSWarner Losh
44088e3e3a7aSWarner Losh
44098e3e3a7aSWarner Losh
44108e3e3a7aSWarner Losh
44118e3e3a7aSWarner Losh<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p>
44128e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
44138e3e3a7aSWarner Losh<pre>int lua_isthread (lua_State *L, int index);</pre>
44148e3e3a7aSWarner Losh
44158e3e3a7aSWarner Losh<p>
44168e3e3a7aSWarner LoshReturns 1 if the value at the given index is a thread,
44178e3e3a7aSWarner Loshand 0&nbsp;otherwise.
44188e3e3a7aSWarner Losh
44198e3e3a7aSWarner Losh
44208e3e3a7aSWarner Losh
44218e3e3a7aSWarner Losh
44228e3e3a7aSWarner Losh
44238e3e3a7aSWarner Losh<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p>
44248e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
44258e3e3a7aSWarner Losh<pre>int lua_isuserdata (lua_State *L, int index);</pre>
44268e3e3a7aSWarner Losh
44278e3e3a7aSWarner Losh<p>
44288e3e3a7aSWarner LoshReturns 1 if the value at the given index is a userdata
44298e3e3a7aSWarner Losh(either full or light), and 0&nbsp;otherwise.
44308e3e3a7aSWarner Losh
44318e3e3a7aSWarner Losh
44328e3e3a7aSWarner Losh
44338e3e3a7aSWarner Losh
44348e3e3a7aSWarner Losh
44358e3e3a7aSWarner Losh<hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p>
44368e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
44378e3e3a7aSWarner Losh<pre>int lua_isyieldable (lua_State *L);</pre>
44388e3e3a7aSWarner Losh
44398e3e3a7aSWarner Losh<p>
44408e3e3a7aSWarner LoshReturns 1 if the given coroutine can yield,
44418e3e3a7aSWarner Loshand 0&nbsp;otherwise.
44428e3e3a7aSWarner Losh
44438e3e3a7aSWarner Losh
44448e3e3a7aSWarner Losh
44458e3e3a7aSWarner Losh
44468e3e3a7aSWarner Losh
44478e3e3a7aSWarner Losh<hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3>
44488e3e3a7aSWarner Losh<pre>typedef ... lua_KContext;</pre>
44498e3e3a7aSWarner Losh
44508e3e3a7aSWarner Losh<p>
44518e3e3a7aSWarner LoshThe type for continuation-function contexts.
44528e3e3a7aSWarner LoshIt must be a numeric type.
44538e3e3a7aSWarner LoshThis type is defined as <code>intptr_t</code>
44548e3e3a7aSWarner Loshwhen <code>intptr_t</code> is available,
44558e3e3a7aSWarner Loshso that it can store pointers too.
44568e3e3a7aSWarner LoshOtherwise, it is defined as <code>ptrdiff_t</code>.
44578e3e3a7aSWarner Losh
44588e3e3a7aSWarner Losh
44598e3e3a7aSWarner Losh
44608e3e3a7aSWarner Losh
44618e3e3a7aSWarner Losh
44628e3e3a7aSWarner Losh<hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3>
44638e3e3a7aSWarner Losh<pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre>
44648e3e3a7aSWarner Losh
44658e3e3a7aSWarner Losh<p>
44660495ed39SKyle EvansType for continuation functions (see <a href="#4.5">&sect;4.5</a>).
44678e3e3a7aSWarner Losh
44688e3e3a7aSWarner Losh
44698e3e3a7aSWarner Losh
44708e3e3a7aSWarner Losh
44718e3e3a7aSWarner Losh
44728e3e3a7aSWarner Losh<hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p>
44738e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span>
44748e3e3a7aSWarner Losh<pre>void lua_len (lua_State *L, int index);</pre>
44758e3e3a7aSWarner Losh
44768e3e3a7aSWarner Losh<p>
44778e3e3a7aSWarner LoshReturns the length of the value at the given index.
44788e3e3a7aSWarner LoshIt is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">&sect;3.4.7</a>) and
44798e3e3a7aSWarner Loshmay trigger a metamethod for the "length" event (see <a href="#2.4">&sect;2.4</a>).
44808e3e3a7aSWarner LoshThe result is pushed on the stack.
44818e3e3a7aSWarner Losh
44828e3e3a7aSWarner Losh
44838e3e3a7aSWarner Losh
44848e3e3a7aSWarner Losh
44858e3e3a7aSWarner Losh
44868e3e3a7aSWarner Losh<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p>
44878e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
44888e3e3a7aSWarner Losh<pre>int lua_load (lua_State *L,
44898e3e3a7aSWarner Losh              lua_Reader reader,
44908e3e3a7aSWarner Losh              void *data,
44918e3e3a7aSWarner Losh              const char *chunkname,
44928e3e3a7aSWarner Losh              const char *mode);</pre>
44938e3e3a7aSWarner Losh
44948e3e3a7aSWarner Losh<p>
44958e3e3a7aSWarner LoshLoads a Lua chunk without running it.
44968e3e3a7aSWarner LoshIf there are no errors,
44978e3e3a7aSWarner Losh<code>lua_load</code> pushes the compiled chunk as a Lua
44988e3e3a7aSWarner Loshfunction on top of the stack.
44998e3e3a7aSWarner LoshOtherwise, it pushes an error message.
45008e3e3a7aSWarner Losh
45018e3e3a7aSWarner Losh
45028e3e3a7aSWarner Losh<p>
45038e3e3a7aSWarner LoshThe <code>lua_load</code> function uses a user-supplied <code>reader</code> function
45048e3e3a7aSWarner Loshto read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>).
45058e3e3a7aSWarner LoshThe <code>data</code> argument is an opaque value passed to the reader function.
45068e3e3a7aSWarner Losh
45078e3e3a7aSWarner Losh
45088e3e3a7aSWarner Losh<p>
45098e3e3a7aSWarner LoshThe <code>chunkname</code> argument gives a name to the chunk,
45100495ed39SKyle Evanswhich is used for error messages and in debug information (see <a href="#4.7">&sect;4.7</a>).
45118e3e3a7aSWarner Losh
45128e3e3a7aSWarner Losh
45138e3e3a7aSWarner Losh<p>
45148e3e3a7aSWarner Losh<code>lua_load</code> automatically detects whether the chunk is text or binary
45158e3e3a7aSWarner Loshand loads it accordingly (see program <code>luac</code>).
45168e3e3a7aSWarner LoshThe string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>,
45178e3e3a7aSWarner Loshwith the addition that
45188e3e3a7aSWarner Losha <code>NULL</code> value is equivalent to the string "<code>bt</code>".
45198e3e3a7aSWarner Losh
45208e3e3a7aSWarner Losh
45218e3e3a7aSWarner Losh<p>
45228e3e3a7aSWarner Losh<code>lua_load</code> uses the stack internally,
45238e3e3a7aSWarner Loshso the reader function must always leave the stack
45248e3e3a7aSWarner Loshunmodified when returning.
45258e3e3a7aSWarner Losh
45268e3e3a7aSWarner Losh
45278e3e3a7aSWarner Losh<p>
45280495ed39SKyle Evans<code>lua_load</code> can return
45290495ed39SKyle Evans<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>, <a href="#pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>, or <a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>.
45300495ed39SKyle EvansThe function may also return other values corresponding to
45310495ed39SKyle Evanserrors raised by the read function (see <a href="#4.4.1">&sect;4.4.1</a>).
45320495ed39SKyle Evans
45330495ed39SKyle Evans
45340495ed39SKyle Evans<p>
45358e3e3a7aSWarner LoshIf the resulting function has upvalues,
45368e3e3a7aSWarner Loshits first upvalue is set to the value of the global environment
45370495ed39SKyle Evansstored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.3">&sect;4.3</a>).
45388e3e3a7aSWarner LoshWhen loading main chunks,
45398e3e3a7aSWarner Loshthis upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">&sect;2.2</a>).
45408e3e3a7aSWarner LoshOther upvalues are initialized with <b>nil</b>.
45418e3e3a7aSWarner Losh
45428e3e3a7aSWarner Losh
45438e3e3a7aSWarner Losh
45448e3e3a7aSWarner Losh
45458e3e3a7aSWarner Losh
45468e3e3a7aSWarner Losh<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p>
45478e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
45488e3e3a7aSWarner Losh<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre>
45498e3e3a7aSWarner Losh
45508e3e3a7aSWarner Losh<p>
45510495ed39SKyle EvansCreates a new independent state and returns its main thread.
45520495ed39SKyle EvansReturns <code>NULL</code> if it cannot create the state
45538e3e3a7aSWarner Losh(due to lack of memory).
45548e3e3a7aSWarner LoshThe argument <code>f</code> is the allocator function;
45550495ed39SKyle EvansLua will do all memory allocation for this state
45568e3e3a7aSWarner Loshthrough this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>).
45578e3e3a7aSWarner LoshThe second argument, <code>ud</code>, is an opaque pointer that Lua
45588e3e3a7aSWarner Loshpasses to the allocator in every call.
45598e3e3a7aSWarner Losh
45608e3e3a7aSWarner Losh
45618e3e3a7aSWarner Losh
45628e3e3a7aSWarner Losh
45638e3e3a7aSWarner Losh
45648e3e3a7aSWarner Losh<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p>
45658e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
45668e3e3a7aSWarner Losh<pre>void lua_newtable (lua_State *L);</pre>
45678e3e3a7aSWarner Losh
45688e3e3a7aSWarner Losh<p>
45698e3e3a7aSWarner LoshCreates a new empty table and pushes it onto the stack.
45708e3e3a7aSWarner LoshIt is equivalent to <code>lua_createtable(L, 0, 0)</code>.
45718e3e3a7aSWarner Losh
45728e3e3a7aSWarner Losh
45738e3e3a7aSWarner Losh
45748e3e3a7aSWarner Losh
45758e3e3a7aSWarner Losh
45768e3e3a7aSWarner Losh<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p>
45778e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
45788e3e3a7aSWarner Losh<pre>lua_State *lua_newthread (lua_State *L);</pre>
45798e3e3a7aSWarner Losh
45808e3e3a7aSWarner Losh<p>
45818e3e3a7aSWarner LoshCreates a new thread, pushes it on the stack,
45828e3e3a7aSWarner Loshand returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread.
45838e3e3a7aSWarner LoshThe new thread returned by this function shares with the original thread
45848e3e3a7aSWarner Loshits global environment,
45858e3e3a7aSWarner Loshbut has an independent execution stack.
45868e3e3a7aSWarner Losh
45878e3e3a7aSWarner Losh
45888e3e3a7aSWarner Losh<p>
45898e3e3a7aSWarner LoshThreads are subject to garbage collection,
45908e3e3a7aSWarner Loshlike any Lua object.
45918e3e3a7aSWarner Losh
45928e3e3a7aSWarner Losh
45938e3e3a7aSWarner Losh
45948e3e3a7aSWarner Losh
45958e3e3a7aSWarner Losh
45960495ed39SKyle Evans<hr><h3><a name="lua_newuserdatauv"><code>lua_newuserdatauv</code></a></h3><p>
45978e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
45980495ed39SKyle Evans<pre>void *lua_newuserdatauv (lua_State *L, size_t size, int nuvalue);</pre>
45998e3e3a7aSWarner Losh
46008e3e3a7aSWarner Losh<p>
46010495ed39SKyle EvansThis function creates and pushes on the stack a new full userdata,
46020495ed39SKyle Evanswith <code>nuvalue</code> associated Lua values, called <code>user values</code>,
46030495ed39SKyle Evansplus an associated block of raw memory with <code>size</code> bytes.
46040495ed39SKyle Evans(The user values can be set and read with the functions
46050495ed39SKyle Evans<a href="#lua_setiuservalue"><code>lua_setiuservalue</code></a> and <a href="#lua_getiuservalue"><code>lua_getiuservalue</code></a>.)
46060495ed39SKyle Evans
46070495ed39SKyle Evans
46080495ed39SKyle Evans<p>
46090495ed39SKyle EvansThe function returns the address of the block of memory.
46100495ed39SKyle EvansLua ensures that this address is valid as long as
46110495ed39SKyle Evansthe corresponding userdata is alive (see <a href="#2.5">&sect;2.5</a>).
46120495ed39SKyle EvansMoreover, if the userdata is marked for finalization (see <a href="#2.5.3">&sect;2.5.3</a>),
46130495ed39SKyle Evansits address is valid at least until the call to its finalizer.
46148e3e3a7aSWarner Losh
46158e3e3a7aSWarner Losh
46168e3e3a7aSWarner Losh
46178e3e3a7aSWarner Losh
46188e3e3a7aSWarner Losh
46198e3e3a7aSWarner Losh<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p>
46200495ed39SKyle Evans<span class="apii">[-1, +(2|0), <em>v</em>]</span>
46218e3e3a7aSWarner Losh<pre>int lua_next (lua_State *L, int index);</pre>
46228e3e3a7aSWarner Losh
46238e3e3a7aSWarner Losh<p>
46248e3e3a7aSWarner LoshPops a key from the stack,
46250495ed39SKyle Evansand pushes a key&ndash;value pair from the table at the given index,
46260495ed39SKyle Evansthe "next" pair after the given key.
46278e3e3a7aSWarner LoshIf there are no more elements in the table,
4628a9490b81SWarner Loshthen <a href="#lua_next"><code>lua_next</code></a> returns&nbsp;0 and pushes nothing.
46298e3e3a7aSWarner Losh
46308e3e3a7aSWarner Losh
46318e3e3a7aSWarner Losh<p>
46320495ed39SKyle EvansA typical table traversal looks like this:
46338e3e3a7aSWarner Losh
46348e3e3a7aSWarner Losh<pre>
46358e3e3a7aSWarner Losh     /* table is in the stack at index 't' */
46368e3e3a7aSWarner Losh     lua_pushnil(L);  /* first key */
46378e3e3a7aSWarner Losh     while (lua_next(L, t) != 0) {
46388e3e3a7aSWarner Losh       /* uses 'key' (at index -2) and 'value' (at index -1) */
46398e3e3a7aSWarner Losh       printf("%s - %s\n",
46408e3e3a7aSWarner Losh              lua_typename(L, lua_type(L, -2)),
46418e3e3a7aSWarner Losh              lua_typename(L, lua_type(L, -1)));
46428e3e3a7aSWarner Losh       /* removes 'value'; keeps 'key' for next iteration */
46438e3e3a7aSWarner Losh       lua_pop(L, 1);
46448e3e3a7aSWarner Losh     }
46458e3e3a7aSWarner Losh</pre>
46468e3e3a7aSWarner Losh
46478e3e3a7aSWarner Losh<p>
46488e3e3a7aSWarner LoshWhile traversing a table,
46490495ed39SKyle Evansavoid calling <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key,
46508e3e3a7aSWarner Loshunless you know that the key is actually a string.
46518e3e3a7aSWarner LoshRecall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change
46528e3e3a7aSWarner Loshthe value at the given index;
46538e3e3a7aSWarner Loshthis confuses the next call to <a href="#lua_next"><code>lua_next</code></a>.
46548e3e3a7aSWarner Losh
46558e3e3a7aSWarner Losh
46568e3e3a7aSWarner Losh<p>
46570495ed39SKyle EvansThis function may raise an error if the given key
46580495ed39SKyle Evansis neither <b>nil</b> nor present in the table.
46598e3e3a7aSWarner LoshSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
46608e3e3a7aSWarner Loshthe table during its traversal.
46618e3e3a7aSWarner Losh
46628e3e3a7aSWarner Losh
46638e3e3a7aSWarner Losh
46648e3e3a7aSWarner Losh
46658e3e3a7aSWarner Losh
46668e3e3a7aSWarner Losh<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3>
46678e3e3a7aSWarner Losh<pre>typedef ... lua_Number;</pre>
46688e3e3a7aSWarner Losh
46698e3e3a7aSWarner Losh<p>
46708e3e3a7aSWarner LoshThe type of floats in Lua.
46718e3e3a7aSWarner Losh
46728e3e3a7aSWarner Losh
46738e3e3a7aSWarner Losh<p>
46748e3e3a7aSWarner LoshBy default this type is double,
46758e3e3a7aSWarner Loshbut that can be changed to a single float or a long double.
46768e3e3a7aSWarner Losh(See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.)
46778e3e3a7aSWarner Losh
46788e3e3a7aSWarner Losh
46798e3e3a7aSWarner Losh
46808e3e3a7aSWarner Losh
46818e3e3a7aSWarner Losh
46828e3e3a7aSWarner Losh<hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3>
46838e3e3a7aSWarner Losh<pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre>
46848e3e3a7aSWarner Losh
46858e3e3a7aSWarner Losh<p>
46860495ed39SKyle EvansTries to convert a Lua float to a Lua integer;
46870495ed39SKyle Evansthe float <code>n</code> must have an integral value.
46888e3e3a7aSWarner LoshIf that value is within the range of Lua integers,
46898e3e3a7aSWarner Loshit is converted to an integer and assigned to <code>*p</code>.
46908e3e3a7aSWarner LoshThe macro results in a boolean indicating whether the
46918e3e3a7aSWarner Loshconversion was successful.
46928e3e3a7aSWarner Losh(Note that this range test can be tricky to do
46930495ed39SKyle Evanscorrectly without this macro, due to rounding.)
46948e3e3a7aSWarner Losh
46958e3e3a7aSWarner Losh
46968e3e3a7aSWarner Losh<p>
46978e3e3a7aSWarner LoshThis macro may evaluate its arguments more than once.
46988e3e3a7aSWarner Losh
46998e3e3a7aSWarner Losh
47008e3e3a7aSWarner Losh
47018e3e3a7aSWarner Losh
47028e3e3a7aSWarner Losh
47038e3e3a7aSWarner Losh<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p>
47048e3e3a7aSWarner Losh<span class="apii">[-(nargs + 1), +(nresults|1), &ndash;]</span>
47058e3e3a7aSWarner Losh<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre>
47068e3e3a7aSWarner Losh
47078e3e3a7aSWarner Losh<p>
47080495ed39SKyle EvansCalls a function (or a callable object) in protected mode.
47098e3e3a7aSWarner Losh
47108e3e3a7aSWarner Losh
47118e3e3a7aSWarner Losh<p>
47128e3e3a7aSWarner LoshBoth <code>nargs</code> and <code>nresults</code> have the same meaning as
47138e3e3a7aSWarner Loshin <a href="#lua_call"><code>lua_call</code></a>.
47148e3e3a7aSWarner LoshIf there are no errors during the call,
47158e3e3a7aSWarner Losh<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>.
47168e3e3a7aSWarner LoshHowever, if there is any error,
47178e3e3a7aSWarner Losh<a href="#lua_pcall"><code>lua_pcall</code></a> catches it,
47188e3e3a7aSWarner Loshpushes a single value on the stack (the error object),
47198e3e3a7aSWarner Loshand returns an error code.
47208e3e3a7aSWarner LoshLike <a href="#lua_call"><code>lua_call</code></a>,
47218e3e3a7aSWarner Losh<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function
47228e3e3a7aSWarner Loshand its arguments from the stack.
47238e3e3a7aSWarner Losh
47248e3e3a7aSWarner Losh
47258e3e3a7aSWarner Losh<p>
47268e3e3a7aSWarner LoshIf <code>msgh</code> is 0,
47278e3e3a7aSWarner Loshthen the error object returned on the stack
47288e3e3a7aSWarner Loshis exactly the original error object.
47298e3e3a7aSWarner LoshOtherwise, <code>msgh</code> is the stack index of a
47308e3e3a7aSWarner Losh<em>message handler</em>.
47318e3e3a7aSWarner Losh(This index cannot be a pseudo-index.)
47328e3e3a7aSWarner LoshIn case of runtime errors,
47330495ed39SKyle Evansthis handler will be called with the error object
47348e3e3a7aSWarner Loshand its return value will be the object
47358e3e3a7aSWarner Loshreturned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>.
47368e3e3a7aSWarner Losh
47378e3e3a7aSWarner Losh
47388e3e3a7aSWarner Losh<p>
47398e3e3a7aSWarner LoshTypically, the message handler is used to add more debug
47408e3e3a7aSWarner Loshinformation to the error object, such as a stack traceback.
47418e3e3a7aSWarner LoshSuch information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>,
47428e3e3a7aSWarner Loshsince by then the stack has unwound.
47438e3e3a7aSWarner Losh
47448e3e3a7aSWarner Losh
47458e3e3a7aSWarner Losh<p>
47460495ed39SKyle EvansThe <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following status codes:
47470495ed39SKyle Evans<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>, <a href="#pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>, <a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>, or <a href="#pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>.
47488e3e3a7aSWarner Losh
47498e3e3a7aSWarner Losh
47508e3e3a7aSWarner Losh
47518e3e3a7aSWarner Losh
47528e3e3a7aSWarner Losh
47538e3e3a7aSWarner Losh<hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p>
47548e3e3a7aSWarner Losh<span class="apii">[-(nargs + 1), +(nresults|1), &ndash;]</span>
47558e3e3a7aSWarner Losh<pre>int lua_pcallk (lua_State *L,
47568e3e3a7aSWarner Losh                int nargs,
47578e3e3a7aSWarner Losh                int nresults,
47588e3e3a7aSWarner Losh                int msgh,
47598e3e3a7aSWarner Losh                lua_KContext ctx,
47608e3e3a7aSWarner Losh                lua_KFunction k);</pre>
47618e3e3a7aSWarner Losh
47628e3e3a7aSWarner Losh<p>
47638e3e3a7aSWarner LoshThis function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>,
47640495ed39SKyle Evansexcept that it allows the called function to yield (see <a href="#4.5">&sect;4.5</a>).
47658e3e3a7aSWarner Losh
47668e3e3a7aSWarner Losh
47678e3e3a7aSWarner Losh
47688e3e3a7aSWarner Losh
47698e3e3a7aSWarner Losh
47708e3e3a7aSWarner Losh<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p>
47710495ed39SKyle Evans<span class="apii">[-n, +0, <em>e</em>]</span>
47728e3e3a7aSWarner Losh<pre>void lua_pop (lua_State *L, int n);</pre>
47738e3e3a7aSWarner Losh
47748e3e3a7aSWarner Losh<p>
47758e3e3a7aSWarner LoshPops <code>n</code> elements from the stack.
47768c784bb8SWarner LoshIt is implemented as a macro over <a href="#lua_settop"><code>lua_settop</code></a>.
47770495ed39SKyle Evans
47780495ed39SKyle Evans
47798e3e3a7aSWarner Losh
47808e3e3a7aSWarner Losh
47818e3e3a7aSWarner Losh
47828e3e3a7aSWarner Losh<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p>
47838e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
47848e3e3a7aSWarner Losh<pre>void lua_pushboolean (lua_State *L, int b);</pre>
47858e3e3a7aSWarner Losh
47868e3e3a7aSWarner Losh<p>
47878e3e3a7aSWarner LoshPushes a boolean value with value <code>b</code> onto the stack.
47888e3e3a7aSWarner Losh
47898e3e3a7aSWarner Losh
47908e3e3a7aSWarner Losh
47918e3e3a7aSWarner Losh
47928e3e3a7aSWarner Losh
47938e3e3a7aSWarner Losh<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p>
47948e3e3a7aSWarner Losh<span class="apii">[-n, +1, <em>m</em>]</span>
47958e3e3a7aSWarner Losh<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre>
47968e3e3a7aSWarner Losh
47978e3e3a7aSWarner Losh<p>
47988e3e3a7aSWarner LoshPushes a new C&nbsp;closure onto the stack.
47990495ed39SKyle EvansThis function receives a pointer to a C&nbsp;function
48000495ed39SKyle Evansand pushes onto the stack a Lua value of type <code>function</code> that,
48010495ed39SKyle Evanswhen called, invokes the corresponding C&nbsp;function.
48020495ed39SKyle EvansThe parameter <code>n</code> tells how many upvalues this function will have
48030495ed39SKyle Evans(see <a href="#4.2">&sect;4.2</a>).
48040495ed39SKyle Evans
48050495ed39SKyle Evans
48060495ed39SKyle Evans<p>
48070495ed39SKyle EvansAny function to be callable by Lua must
48080495ed39SKyle Evansfollow the correct protocol to receive its parameters
48090495ed39SKyle Evansand return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
48108e3e3a7aSWarner Losh
48118e3e3a7aSWarner Losh
48128e3e3a7aSWarner Losh<p>
48138e3e3a7aSWarner LoshWhen a C&nbsp;function is created,
48148e3e3a7aSWarner Loshit is possible to associate some values with it,
48150495ed39SKyle Evansthe so called upvalues;
48160495ed39SKyle Evansthese upvalues are then accessible to the function whenever it is called.
48170495ed39SKyle EvansThis association is called a C&nbsp;closure (see <a href="#4.2">&sect;4.2</a>).
48180495ed39SKyle EvansTo create a C&nbsp;closure,
48190495ed39SKyle Evansfirst the initial values for its upvalues must be pushed onto the stack.
48200495ed39SKyle Evans(When there are multiple upvalues, the first value is pushed first.)
48218e3e3a7aSWarner LoshThen <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>
48228e3e3a7aSWarner Loshis called to create and push the C&nbsp;function onto the stack,
48238e3e3a7aSWarner Loshwith the argument <code>n</code> telling how many values will be
48248e3e3a7aSWarner Loshassociated with the function.
48258e3e3a7aSWarner Losh<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack.
48268e3e3a7aSWarner Losh
48278e3e3a7aSWarner Losh
48288e3e3a7aSWarner Losh<p>
48298e3e3a7aSWarner LoshThe maximum value for <code>n</code> is 255.
48308e3e3a7aSWarner Losh
48318e3e3a7aSWarner Losh
48328e3e3a7aSWarner Losh<p>
48338e3e3a7aSWarner LoshWhen <code>n</code> is zero,
48348e3e3a7aSWarner Loshthis function creates a <em>light C&nbsp;function</em>,
48358e3e3a7aSWarner Loshwhich is just a pointer to the C&nbsp;function.
48368e3e3a7aSWarner LoshIn that case, it never raises a memory error.
48378e3e3a7aSWarner Losh
48388e3e3a7aSWarner Losh
48398e3e3a7aSWarner Losh
48408e3e3a7aSWarner Losh
48418e3e3a7aSWarner Losh
48428e3e3a7aSWarner Losh<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p>
48438e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
48448e3e3a7aSWarner Losh<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre>
48458e3e3a7aSWarner Losh
48468e3e3a7aSWarner Losh<p>
48478e3e3a7aSWarner LoshPushes a C&nbsp;function onto the stack.
48480495ed39SKyle EvansThis function is equivalent to <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> with no upvalues.
48498e3e3a7aSWarner Losh
48508e3e3a7aSWarner Losh
48518e3e3a7aSWarner Losh
48528e3e3a7aSWarner Losh
48538e3e3a7aSWarner Losh
48548e3e3a7aSWarner Losh<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p>
48550495ed39SKyle Evans<span class="apii">[-0, +1, <em>v</em>]</span>
48568e3e3a7aSWarner Losh<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre>
48578e3e3a7aSWarner Losh
48588e3e3a7aSWarner Losh<p>
48598e3e3a7aSWarner LoshPushes onto the stack a formatted string
48600495ed39SKyle Evansand returns a pointer to this string (see <a href="#4.1.3">&sect;4.1.3</a>).
48618e3e3a7aSWarner LoshIt is similar to the ISO&nbsp;C function <code>sprintf</code>,
48620495ed39SKyle Evansbut has two important differences.
48630495ed39SKyle EvansFirst,
48640495ed39SKyle Evansyou do not have to allocate space for the result;
48658e3e3a7aSWarner Loshthe result is a Lua string and Lua takes care of memory allocation
48668e3e3a7aSWarner Losh(and deallocation, through garbage collection).
48670495ed39SKyle EvansSecond,
48680495ed39SKyle Evansthe conversion specifiers are quite restricted.
48698e3e3a7aSWarner LoshThere are no flags, widths, or precisions.
48708e3e3a7aSWarner LoshThe conversion specifiers can only be
48718e3e3a7aSWarner Losh'<code>%%</code>' (inserts the character '<code>%</code>'),
48728e3e3a7aSWarner Losh'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions),
48738e3e3a7aSWarner Losh'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>),
48748e3e3a7aSWarner Losh'<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>),
48750495ed39SKyle Evans'<code>%p</code>' (inserts a pointer),
48768e3e3a7aSWarner Losh'<code>%d</code>' (inserts an <code>int</code>),
48778e3e3a7aSWarner Losh'<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and
48788e3e3a7aSWarner Losh'<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence).
48798e3e3a7aSWarner Losh
48808e3e3a7aSWarner Losh
48818e3e3a7aSWarner Losh<p>
48820495ed39SKyle EvansThis function may raise errors due to memory overflow
48830495ed39SKyle Evansor an invalid conversion specifier.
48848e3e3a7aSWarner Losh
48858e3e3a7aSWarner Losh
48868e3e3a7aSWarner Losh
48878e3e3a7aSWarner Losh
48888e3e3a7aSWarner Losh
48898e3e3a7aSWarner Losh<hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p>
48908e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
48918e3e3a7aSWarner Losh<pre>void lua_pushglobaltable (lua_State *L);</pre>
48928e3e3a7aSWarner Losh
48938e3e3a7aSWarner Losh<p>
48948e3e3a7aSWarner LoshPushes the global environment onto the stack.
48958e3e3a7aSWarner Losh
48968e3e3a7aSWarner Losh
48978e3e3a7aSWarner Losh
48988e3e3a7aSWarner Losh
48998e3e3a7aSWarner Losh
49008e3e3a7aSWarner Losh<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p>
49018e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
49028e3e3a7aSWarner Losh<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre>
49038e3e3a7aSWarner Losh
49048e3e3a7aSWarner Losh<p>
49058e3e3a7aSWarner LoshPushes an integer with value <code>n</code> onto the stack.
49068e3e3a7aSWarner Losh
49078e3e3a7aSWarner Losh
49088e3e3a7aSWarner Losh
49098e3e3a7aSWarner Losh
49108e3e3a7aSWarner Losh
49118e3e3a7aSWarner Losh<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p>
49128e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
49138e3e3a7aSWarner Losh<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre>
49148e3e3a7aSWarner Losh
49158e3e3a7aSWarner Losh<p>
49168e3e3a7aSWarner LoshPushes a light userdata onto the stack.
49178e3e3a7aSWarner Losh
49188e3e3a7aSWarner Losh
49198e3e3a7aSWarner Losh<p>
49208e3e3a7aSWarner LoshUserdata represent C&nbsp;values in Lua.
49218e3e3a7aSWarner LoshA <em>light userdata</em> represents a pointer, a <code>void*</code>.
49228e3e3a7aSWarner LoshIt is a value (like a number):
49238e3e3a7aSWarner Loshyou do not create it, it has no individual metatable,
49248e3e3a7aSWarner Loshand it is not collected (as it was never created).
49258e3e3a7aSWarner LoshA light userdata is equal to "any"
49268e3e3a7aSWarner Loshlight userdata with the same C&nbsp;address.
49278e3e3a7aSWarner Losh
49288e3e3a7aSWarner Losh
49298e3e3a7aSWarner Losh
49308e3e3a7aSWarner Losh
49318e3e3a7aSWarner Losh
49328e3e3a7aSWarner Losh<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p>
49338e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
49348e3e3a7aSWarner Losh<pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre>
49358e3e3a7aSWarner Losh
49368e3e3a7aSWarner Losh<p>
49378e3e3a7aSWarner LoshThis macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>,
49388e3e3a7aSWarner Loshbut should be used only when <code>s</code> is a literal string.
49390495ed39SKyle Evans(Lua may optimize this case.)
49408e3e3a7aSWarner Losh
49418e3e3a7aSWarner Losh
49428e3e3a7aSWarner Losh
49438e3e3a7aSWarner Losh
49448e3e3a7aSWarner Losh
49458e3e3a7aSWarner Losh<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p>
49468e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
49478e3e3a7aSWarner Losh<pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre>
49488e3e3a7aSWarner Losh
49498e3e3a7aSWarner Losh<p>
49508e3e3a7aSWarner LoshPushes the string pointed to by <code>s</code> with size <code>len</code>
49518e3e3a7aSWarner Loshonto the stack.
49520495ed39SKyle EvansLua will make or reuse an internal copy of the given string,
49538e3e3a7aSWarner Loshso the memory at <code>s</code> can be freed or reused immediately after
49548e3e3a7aSWarner Loshthe function returns.
49558e3e3a7aSWarner LoshThe string can contain any binary data,
49568e3e3a7aSWarner Loshincluding embedded zeros.
49578e3e3a7aSWarner Losh
49588e3e3a7aSWarner Losh
49598e3e3a7aSWarner Losh<p>
49600495ed39SKyle EvansReturns a pointer to the internal copy of the string (see <a href="#4.1.3">&sect;4.1.3</a>).
49618e3e3a7aSWarner Losh
49628e3e3a7aSWarner Losh
49638e3e3a7aSWarner Losh
49648e3e3a7aSWarner Losh
49658e3e3a7aSWarner Losh
49668e3e3a7aSWarner Losh<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p>
49678e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
49688e3e3a7aSWarner Losh<pre>void lua_pushnil (lua_State *L);</pre>
49698e3e3a7aSWarner Losh
49708e3e3a7aSWarner Losh<p>
49718e3e3a7aSWarner LoshPushes a nil value onto the stack.
49728e3e3a7aSWarner Losh
49738e3e3a7aSWarner Losh
49748e3e3a7aSWarner Losh
49758e3e3a7aSWarner Losh
49768e3e3a7aSWarner Losh
49778e3e3a7aSWarner Losh<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p>
49788e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
49798e3e3a7aSWarner Losh<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre>
49808e3e3a7aSWarner Losh
49818e3e3a7aSWarner Losh<p>
49828e3e3a7aSWarner LoshPushes a float with value <code>n</code> onto the stack.
49838e3e3a7aSWarner Losh
49848e3e3a7aSWarner Losh
49858e3e3a7aSWarner Losh
49868e3e3a7aSWarner Losh
49878e3e3a7aSWarner Losh
49888e3e3a7aSWarner Losh<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p>
49898e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
49908e3e3a7aSWarner Losh<pre>const char *lua_pushstring (lua_State *L, const char *s);</pre>
49918e3e3a7aSWarner Losh
49928e3e3a7aSWarner Losh<p>
49938e3e3a7aSWarner LoshPushes the zero-terminated string pointed to by <code>s</code>
49948e3e3a7aSWarner Loshonto the stack.
49950495ed39SKyle EvansLua will make or reuse an internal copy of the given string,
49968e3e3a7aSWarner Loshso the memory at <code>s</code> can be freed or reused immediately after
49978e3e3a7aSWarner Loshthe function returns.
49988e3e3a7aSWarner Losh
49998e3e3a7aSWarner Losh
50008e3e3a7aSWarner Losh<p>
50010495ed39SKyle EvansReturns a pointer to the internal copy of the string (see <a href="#4.1.3">&sect;4.1.3</a>).
50028e3e3a7aSWarner Losh
50038e3e3a7aSWarner Losh
50048e3e3a7aSWarner Losh<p>
50058e3e3a7aSWarner LoshIf <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>.
50068e3e3a7aSWarner Losh
50078e3e3a7aSWarner Losh
50088e3e3a7aSWarner Losh
50098e3e3a7aSWarner Losh
50108e3e3a7aSWarner Losh
50118e3e3a7aSWarner Losh<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p>
50128e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
50138e3e3a7aSWarner Losh<pre>int lua_pushthread (lua_State *L);</pre>
50148e3e3a7aSWarner Losh
50158e3e3a7aSWarner Losh<p>
50168e3e3a7aSWarner LoshPushes the thread represented by <code>L</code> onto the stack.
50178e3e3a7aSWarner LoshReturns 1 if this thread is the main thread of its state.
50188e3e3a7aSWarner Losh
50198e3e3a7aSWarner Losh
50208e3e3a7aSWarner Losh
50218e3e3a7aSWarner Losh
50228e3e3a7aSWarner Losh
50238e3e3a7aSWarner Losh<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p>
50248e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
50258e3e3a7aSWarner Losh<pre>void lua_pushvalue (lua_State *L, int index);</pre>
50268e3e3a7aSWarner Losh
50278e3e3a7aSWarner Losh<p>
50288e3e3a7aSWarner LoshPushes a copy of the element at the given index
50298e3e3a7aSWarner Loshonto the stack.
50308e3e3a7aSWarner Losh
50318e3e3a7aSWarner Losh
50328e3e3a7aSWarner Losh
50338e3e3a7aSWarner Losh
50348e3e3a7aSWarner Losh
50358e3e3a7aSWarner Losh<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p>
50360495ed39SKyle Evans<span class="apii">[-0, +1, <em>v</em>]</span>
50378e3e3a7aSWarner Losh<pre>const char *lua_pushvfstring (lua_State *L,
50388e3e3a7aSWarner Losh                              const char *fmt,
50398e3e3a7aSWarner Losh                              va_list argp);</pre>
50408e3e3a7aSWarner Losh
50418e3e3a7aSWarner Losh<p>
50428e3e3a7aSWarner LoshEquivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code>
50438e3e3a7aSWarner Loshinstead of a variable number of arguments.
50448e3e3a7aSWarner Losh
50458e3e3a7aSWarner Losh
50468e3e3a7aSWarner Losh
50478e3e3a7aSWarner Losh
50488e3e3a7aSWarner Losh
50498e3e3a7aSWarner Losh<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p>
50508e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
50518e3e3a7aSWarner Losh<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre>
50528e3e3a7aSWarner Losh
50538e3e3a7aSWarner Losh<p>
50548e3e3a7aSWarner LoshReturns 1 if the two values in indices <code>index1</code> and
50558e3e3a7aSWarner Losh<code>index2</code> are primitively equal
50560495ed39SKyle Evans(that is, equal without calling the <code>__eq</code> metamethod).
50578e3e3a7aSWarner LoshOtherwise returns&nbsp;0.
50588e3e3a7aSWarner LoshAlso returns&nbsp;0 if any of the indices are not valid.
50598e3e3a7aSWarner Losh
50608e3e3a7aSWarner Losh
50618e3e3a7aSWarner Losh
50628e3e3a7aSWarner Losh
50638e3e3a7aSWarner Losh
50648e3e3a7aSWarner Losh<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p>
50658e3e3a7aSWarner Losh<span class="apii">[-1, +1, &ndash;]</span>
50668e3e3a7aSWarner Losh<pre>int lua_rawget (lua_State *L, int index);</pre>
50678e3e3a7aSWarner Losh
50688e3e3a7aSWarner Losh<p>
50698e3e3a7aSWarner LoshSimilar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access
50708e3e3a7aSWarner Losh(i.e., without metamethods).
5071a9490b81SWarner LoshThe value at <code>index</code> must be a table.
50728e3e3a7aSWarner Losh
50738e3e3a7aSWarner Losh
50748e3e3a7aSWarner Losh
50758e3e3a7aSWarner Losh
50768e3e3a7aSWarner Losh
50778e3e3a7aSWarner Losh<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p>
50788e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
50798e3e3a7aSWarner Losh<pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre>
50808e3e3a7aSWarner Losh
50818e3e3a7aSWarner Losh<p>
50828e3e3a7aSWarner LoshPushes onto the stack the value <code>t[n]</code>,
50838e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index.
50848e3e3a7aSWarner LoshThe access is raw,
50850495ed39SKyle Evansthat is, it does not use the <code>__index</code> metavalue.
50868e3e3a7aSWarner Losh
50878e3e3a7aSWarner Losh
50888e3e3a7aSWarner Losh<p>
50898e3e3a7aSWarner LoshReturns the type of the pushed value.
50908e3e3a7aSWarner Losh
50918e3e3a7aSWarner Losh
50928e3e3a7aSWarner Losh
50938e3e3a7aSWarner Losh
50948e3e3a7aSWarner Losh
50958e3e3a7aSWarner Losh<hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p>
50968e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
50978e3e3a7aSWarner Losh<pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre>
50988e3e3a7aSWarner Losh
50998e3e3a7aSWarner Losh<p>
51008e3e3a7aSWarner LoshPushes onto the stack the value <code>t[k]</code>,
51018e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index and
51028e3e3a7aSWarner Losh<code>k</code> is the pointer <code>p</code> represented as a light userdata.
51038e3e3a7aSWarner LoshThe access is raw;
51040495ed39SKyle Evansthat is, it does not use the <code>__index</code> metavalue.
51058e3e3a7aSWarner Losh
51068e3e3a7aSWarner Losh
51078e3e3a7aSWarner Losh<p>
51088e3e3a7aSWarner LoshReturns the type of the pushed value.
51098e3e3a7aSWarner Losh
51108e3e3a7aSWarner Losh
51118e3e3a7aSWarner Losh
51128e3e3a7aSWarner Losh
51138e3e3a7aSWarner Losh
51148e3e3a7aSWarner Losh<hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p>
51158e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
51160495ed39SKyle Evans<pre>lua_Unsigned lua_rawlen (lua_State *L, int index);</pre>
51178e3e3a7aSWarner Losh
51188e3e3a7aSWarner Losh<p>
51198e3e3a7aSWarner LoshReturns the raw "length" of the value at the given index:
51208e3e3a7aSWarner Loshfor strings, this is the string length;
51218e3e3a7aSWarner Loshfor tables, this is the result of the length operator ('<code>#</code>')
51228e3e3a7aSWarner Loshwith no metamethods;
51238e3e3a7aSWarner Loshfor userdata, this is the size of the block of memory allocated
51240495ed39SKyle Evansfor the userdata.
51250495ed39SKyle EvansFor other values, this call returns&nbsp;0.
51268e3e3a7aSWarner Losh
51278e3e3a7aSWarner Losh
51288e3e3a7aSWarner Losh
51298e3e3a7aSWarner Losh
51308e3e3a7aSWarner Losh
51318e3e3a7aSWarner Losh<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p>
51328e3e3a7aSWarner Losh<span class="apii">[-2, +0, <em>m</em>]</span>
51338e3e3a7aSWarner Losh<pre>void lua_rawset (lua_State *L, int index);</pre>
51348e3e3a7aSWarner Losh
51358e3e3a7aSWarner Losh<p>
51368e3e3a7aSWarner LoshSimilar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment
51378e3e3a7aSWarner Losh(i.e., without metamethods).
5138a9490b81SWarner LoshThe value at <code>index</code> must be a table.
51398e3e3a7aSWarner Losh
51408e3e3a7aSWarner Losh
51418e3e3a7aSWarner Losh
51428e3e3a7aSWarner Losh
51438e3e3a7aSWarner Losh
51448e3e3a7aSWarner Losh<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p>
51458e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span>
51468e3e3a7aSWarner Losh<pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre>
51478e3e3a7aSWarner Losh
51488e3e3a7aSWarner Losh<p>
51498e3e3a7aSWarner LoshDoes the equivalent of <code>t[i] = v</code>,
51508e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index
51510495ed39SKyle Evansand <code>v</code> is the value on the top of the stack.
51528e3e3a7aSWarner Losh
51538e3e3a7aSWarner Losh
51548e3e3a7aSWarner Losh<p>
51558e3e3a7aSWarner LoshThis function pops the value from the stack.
51568e3e3a7aSWarner LoshThe assignment is raw,
51570495ed39SKyle Evansthat is, it does not use the <code>__newindex</code> metavalue.
51588e3e3a7aSWarner Losh
51598e3e3a7aSWarner Losh
51608e3e3a7aSWarner Losh
51618e3e3a7aSWarner Losh
51628e3e3a7aSWarner Losh
51638e3e3a7aSWarner Losh<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p>
51648e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span>
51658e3e3a7aSWarner Losh<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre>
51668e3e3a7aSWarner Losh
51678e3e3a7aSWarner Losh<p>
51688e3e3a7aSWarner LoshDoes the equivalent of <code>t[p] = v</code>,
51698e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index,
51708e3e3a7aSWarner Losh<code>p</code> is encoded as a light userdata,
51710495ed39SKyle Evansand <code>v</code> is the value on the top of the stack.
51728e3e3a7aSWarner Losh
51738e3e3a7aSWarner Losh
51748e3e3a7aSWarner Losh<p>
51758e3e3a7aSWarner LoshThis function pops the value from the stack.
51768e3e3a7aSWarner LoshThe assignment is raw,
51770495ed39SKyle Evansthat is, it does not use the <code>__newindex</code> metavalue.
51788e3e3a7aSWarner Losh
51798e3e3a7aSWarner Losh
51808e3e3a7aSWarner Losh
51818e3e3a7aSWarner Losh
51828e3e3a7aSWarner Losh
51838e3e3a7aSWarner Losh<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3>
51848e3e3a7aSWarner Losh<pre>typedef const char * (*lua_Reader) (lua_State *L,
51858e3e3a7aSWarner Losh                                    void *data,
51868e3e3a7aSWarner Losh                                    size_t *size);</pre>
51878e3e3a7aSWarner Losh
51888e3e3a7aSWarner Losh<p>
51898e3e3a7aSWarner LoshThe reader function used by <a href="#lua_load"><code>lua_load</code></a>.
51900495ed39SKyle EvansEvery time <a href="#lua_load"><code>lua_load</code></a> needs another piece of the chunk,
51910495ed39SKyle Evansit calls the reader,
51928e3e3a7aSWarner Loshpassing along its <code>data</code> parameter.
51938e3e3a7aSWarner LoshThe reader must return a pointer to a block of memory
51948e3e3a7aSWarner Loshwith a new piece of the chunk
51958e3e3a7aSWarner Loshand set <code>size</code> to the block size.
51968e3e3a7aSWarner LoshThe block must exist until the reader function is called again.
51978e3e3a7aSWarner LoshTo signal the end of the chunk,
51988e3e3a7aSWarner Loshthe reader must return <code>NULL</code> or set <code>size</code> to zero.
51998e3e3a7aSWarner LoshThe reader function may return pieces of any size greater than zero.
52008e3e3a7aSWarner Losh
52018e3e3a7aSWarner Losh
52028e3e3a7aSWarner Losh
52038e3e3a7aSWarner Losh
52048e3e3a7aSWarner Losh
52058e3e3a7aSWarner Losh<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p>
52068e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span>
52078e3e3a7aSWarner Losh<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre>
52088e3e3a7aSWarner Losh
52098e3e3a7aSWarner Losh<p>
52108e3e3a7aSWarner LoshSets the C&nbsp;function <code>f</code> as the new value of global <code>name</code>.
52118e3e3a7aSWarner LoshIt is defined as a macro:
52128e3e3a7aSWarner Losh
52138e3e3a7aSWarner Losh<pre>
52148e3e3a7aSWarner Losh     #define lua_register(L,n,f) \
52158e3e3a7aSWarner Losh            (lua_pushcfunction(L, f), lua_setglobal(L, n))
52168e3e3a7aSWarner Losh</pre>
52178e3e3a7aSWarner Losh
52188e3e3a7aSWarner Losh
52198e3e3a7aSWarner Losh
52208e3e3a7aSWarner Losh
52218e3e3a7aSWarner Losh<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p>
52228e3e3a7aSWarner Losh<span class="apii">[-1, +0, &ndash;]</span>
52238e3e3a7aSWarner Losh<pre>void lua_remove (lua_State *L, int index);</pre>
52248e3e3a7aSWarner Losh
52258e3e3a7aSWarner Losh<p>
52268e3e3a7aSWarner LoshRemoves the element at the given valid index,
52278e3e3a7aSWarner Loshshifting down the elements above this index to fill the gap.
52288e3e3a7aSWarner LoshThis function cannot be called with a pseudo-index,
52298e3e3a7aSWarner Loshbecause a pseudo-index is not an actual stack position.
52308e3e3a7aSWarner Losh
52318e3e3a7aSWarner Losh
52328e3e3a7aSWarner Losh
52338e3e3a7aSWarner Losh
52348e3e3a7aSWarner Losh
52358e3e3a7aSWarner Losh<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p>
52368e3e3a7aSWarner Losh<span class="apii">[-1, +0, &ndash;]</span>
52378e3e3a7aSWarner Losh<pre>void lua_replace (lua_State *L, int index);</pre>
52388e3e3a7aSWarner Losh
52398e3e3a7aSWarner Losh<p>
52408e3e3a7aSWarner LoshMoves the top element into the given valid index
52418e3e3a7aSWarner Loshwithout shifting any element
52428e3e3a7aSWarner Losh(therefore replacing the value at that given index),
52438e3e3a7aSWarner Loshand then pops the top element.
52448e3e3a7aSWarner Losh
52458e3e3a7aSWarner Losh
52468e3e3a7aSWarner Losh
52478e3e3a7aSWarner Losh
52488e3e3a7aSWarner Losh
52490495ed39SKyle Evans<hr><h3><a name="lua_resetthread"><code>lua_resetthread</code></a></h3><p>
52500495ed39SKyle Evans<span class="apii">[-0, +?, &ndash;]</span>
52510495ed39SKyle Evans<pre>int lua_resetthread (lua_State *L);</pre>
52520495ed39SKyle Evans
52530495ed39SKyle Evans<p>
5254a9490b81SWarner LoshThis function is deprecated;
5255a9490b81SWarner Loshit is equivalent to <a href="#lua_closethread"><code>lua_closethread</code></a> with
5256a9490b81SWarner Losh<code>from</code> being <code>NULL</code>.
52570495ed39SKyle Evans
52580495ed39SKyle Evans
52590495ed39SKyle Evans
52600495ed39SKyle Evans
52610495ed39SKyle Evans
52628e3e3a7aSWarner Losh<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p>
52638e3e3a7aSWarner Losh<span class="apii">[-?, +?, &ndash;]</span>
52640495ed39SKyle Evans<pre>int lua_resume (lua_State *L, lua_State *from, int nargs,
52650495ed39SKyle Evans                          int *nresults);</pre>
52668e3e3a7aSWarner Losh
52678e3e3a7aSWarner Losh<p>
52688e3e3a7aSWarner LoshStarts and resumes a coroutine in the given thread <code>L</code>.
52698e3e3a7aSWarner Losh
52708e3e3a7aSWarner Losh
52718e3e3a7aSWarner Losh<p>
52728e3e3a7aSWarner LoshTo start a coroutine,
52730495ed39SKyle Evansyou push the main function plus any arguments
52740495ed39SKyle Evansonto the empty stack of the thread.
52758e3e3a7aSWarner Loshthen you call <a href="#lua_resume"><code>lua_resume</code></a>,
52768e3e3a7aSWarner Loshwith <code>nargs</code> being the number of arguments.
52778e3e3a7aSWarner LoshThis call returns when the coroutine suspends or finishes its execution.
52780495ed39SKyle EvansWhen it returns,
52790495ed39SKyle Evans<code>*nresults</code> is updated and
52800495ed39SKyle Evansthe top of the stack contains
52810495ed39SKyle Evansthe <code>*nresults</code> values passed to <a href="#lua_yield"><code>lua_yield</code></a>
52820495ed39SKyle Evansor returned by the body function.
52838e3e3a7aSWarner Losh<a href="#lua_resume"><code>lua_resume</code></a> returns
52848e3e3a7aSWarner Losh<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields,
52858e3e3a7aSWarner Losh<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution
52868e3e3a7aSWarner Loshwithout errors,
52870495ed39SKyle Evansor an error code in case of errors (see <a href="#4.4.1">&sect;4.4.1</a>).
52888e3e3a7aSWarner LoshIn case of errors,
52890495ed39SKyle Evansthe error object is on the top of the stack.
52908e3e3a7aSWarner Losh
52918e3e3a7aSWarner Losh
52928e3e3a7aSWarner Losh<p>
52938e3e3a7aSWarner LoshTo resume a coroutine,
52940495ed39SKyle Evansyou remove the <code>*nresults</code> yielded values from its stack,
52950495ed39SKyle Evanspush the values to be passed as results from <code>yield</code>,
52968e3e3a7aSWarner Loshand then call <a href="#lua_resume"><code>lua_resume</code></a>.
52978e3e3a7aSWarner Losh
52988e3e3a7aSWarner Losh
52998e3e3a7aSWarner Losh<p>
53008e3e3a7aSWarner LoshThe parameter <code>from</code> represents the coroutine that is resuming <code>L</code>.
53018e3e3a7aSWarner LoshIf there is no such coroutine,
53028e3e3a7aSWarner Loshthis parameter can be <code>NULL</code>.
53038e3e3a7aSWarner Losh
53048e3e3a7aSWarner Losh
53058e3e3a7aSWarner Losh
53068e3e3a7aSWarner Losh
53078e3e3a7aSWarner Losh
53088e3e3a7aSWarner Losh<hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p>
53098e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
53108e3e3a7aSWarner Losh<pre>void lua_rotate (lua_State *L, int idx, int n);</pre>
53118e3e3a7aSWarner Losh
53128e3e3a7aSWarner Losh<p>
53138e3e3a7aSWarner LoshRotates the stack elements between the valid index <code>idx</code>
53148e3e3a7aSWarner Loshand the top of the stack.
53158e3e3a7aSWarner LoshThe elements are rotated <code>n</code> positions in the direction of the top,
53168e3e3a7aSWarner Loshfor a positive <code>n</code>,
53178e3e3a7aSWarner Loshor <code>-n</code> positions in the direction of the bottom,
53188e3e3a7aSWarner Loshfor a negative <code>n</code>.
53198e3e3a7aSWarner LoshThe absolute value of <code>n</code> must not be greater than the size
53208e3e3a7aSWarner Loshof the slice being rotated.
53218e3e3a7aSWarner LoshThis function cannot be called with a pseudo-index,
53228e3e3a7aSWarner Loshbecause a pseudo-index is not an actual stack position.
53238e3e3a7aSWarner Losh
53248e3e3a7aSWarner Losh
53258e3e3a7aSWarner Losh
53268e3e3a7aSWarner Losh
53278e3e3a7aSWarner Losh
53288e3e3a7aSWarner Losh<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p>
53298e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
53308e3e3a7aSWarner Losh<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre>
53318e3e3a7aSWarner Losh
53328e3e3a7aSWarner Losh<p>
53338e3e3a7aSWarner LoshChanges the allocator function of a given state to <code>f</code>
53348e3e3a7aSWarner Loshwith user data <code>ud</code>.
53358e3e3a7aSWarner Losh
53368e3e3a7aSWarner Losh
53378e3e3a7aSWarner Losh
53388e3e3a7aSWarner Losh
53398e3e3a7aSWarner Losh
53408e3e3a7aSWarner Losh<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p>
53418e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>e</em>]</span>
53428e3e3a7aSWarner Losh<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre>
53438e3e3a7aSWarner Losh
53448e3e3a7aSWarner Losh<p>
53458e3e3a7aSWarner LoshDoes the equivalent to <code>t[k] = v</code>,
53468e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index
53470495ed39SKyle Evansand <code>v</code> is the value on the top of the stack.
53488e3e3a7aSWarner Losh
53498e3e3a7aSWarner Losh
53508e3e3a7aSWarner Losh<p>
53518e3e3a7aSWarner LoshThis function pops the value from the stack.
53528e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod
53538e3e3a7aSWarner Loshfor the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
53548e3e3a7aSWarner Losh
53558e3e3a7aSWarner Losh
53568e3e3a7aSWarner Losh
53578e3e3a7aSWarner Losh
53588e3e3a7aSWarner Losh
53598e3e3a7aSWarner Losh<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p>
53608e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>e</em>]</span>
53618e3e3a7aSWarner Losh<pre>void lua_setglobal (lua_State *L, const char *name);</pre>
53628e3e3a7aSWarner Losh
53638e3e3a7aSWarner Losh<p>
53648e3e3a7aSWarner LoshPops a value from the stack and
53658e3e3a7aSWarner Loshsets it as the new value of global <code>name</code>.
53668e3e3a7aSWarner Losh
53678e3e3a7aSWarner Losh
53688e3e3a7aSWarner Losh
53698e3e3a7aSWarner Losh
53708e3e3a7aSWarner Losh
53718e3e3a7aSWarner Losh<hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p>
53728e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>e</em>]</span>
53738e3e3a7aSWarner Losh<pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre>
53748e3e3a7aSWarner Losh
53758e3e3a7aSWarner Losh<p>
53768e3e3a7aSWarner LoshDoes the equivalent to <code>t[n] = v</code>,
53778e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index
53780495ed39SKyle Evansand <code>v</code> is the value on the top of the stack.
53798e3e3a7aSWarner Losh
53808e3e3a7aSWarner Losh
53818e3e3a7aSWarner Losh<p>
53828e3e3a7aSWarner LoshThis function pops the value from the stack.
53838e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod
53848e3e3a7aSWarner Loshfor the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
53858e3e3a7aSWarner Losh
53868e3e3a7aSWarner Losh
53878e3e3a7aSWarner Losh
53888e3e3a7aSWarner Losh
53898e3e3a7aSWarner Losh
53900495ed39SKyle Evans<hr><h3><a name="lua_setiuservalue"><code>lua_setiuservalue</code></a></h3><p>
53918e3e3a7aSWarner Losh<span class="apii">[-1, +0, &ndash;]</span>
53920495ed39SKyle Evans<pre>int lua_setiuservalue (lua_State *L, int index, int n);</pre>
53938e3e3a7aSWarner Losh
53948e3e3a7aSWarner Losh<p>
53950495ed39SKyle EvansPops a value from the stack and sets it as
53960495ed39SKyle Evansthe new <code>n</code>-th user value associated to the
53970495ed39SKyle Evansfull userdata at the given index.
53980495ed39SKyle EvansReturns 0 if the userdata does not have that value.
53990495ed39SKyle Evans
54000495ed39SKyle Evans
54010495ed39SKyle Evans
54020495ed39SKyle Evans
54030495ed39SKyle Evans
54040495ed39SKyle Evans<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p>
54050495ed39SKyle Evans<span class="apii">[-1, +0, &ndash;]</span>
54060495ed39SKyle Evans<pre>int lua_setmetatable (lua_State *L, int index);</pre>
54070495ed39SKyle Evans
54080495ed39SKyle Evans<p>
54090495ed39SKyle EvansPops a table or <b>nil</b> from the stack and
54100495ed39SKyle Evanssets that value as the new metatable for the value at the given index.
54110495ed39SKyle Evans(<b>nil</b> means no metatable.)
54120495ed39SKyle Evans
54130495ed39SKyle Evans
54140495ed39SKyle Evans<p>
54150495ed39SKyle Evans(For historical reasons, this function returns an <code>int</code>,
54160495ed39SKyle Evanswhich now is always 1.)
54178e3e3a7aSWarner Losh
54188e3e3a7aSWarner Losh
54198e3e3a7aSWarner Losh
54208e3e3a7aSWarner Losh
54218e3e3a7aSWarner Losh
54228e3e3a7aSWarner Losh<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p>
54238e3e3a7aSWarner Losh<span class="apii">[-2, +0, <em>e</em>]</span>
54248e3e3a7aSWarner Losh<pre>void lua_settable (lua_State *L, int index);</pre>
54258e3e3a7aSWarner Losh
54268e3e3a7aSWarner Losh<p>
54278e3e3a7aSWarner LoshDoes the equivalent to <code>t[k] = v</code>,
54288e3e3a7aSWarner Loshwhere <code>t</code> is the value at the given index,
54290495ed39SKyle Evans<code>v</code> is the value on the top of the stack,
54308e3e3a7aSWarner Loshand <code>k</code> is the value just below the top.
54318e3e3a7aSWarner Losh
54328e3e3a7aSWarner Losh
54338e3e3a7aSWarner Losh<p>
54348e3e3a7aSWarner LoshThis function pops both the key and the value from the stack.
54358e3e3a7aSWarner LoshAs in Lua, this function may trigger a metamethod
54368e3e3a7aSWarner Loshfor the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
54378e3e3a7aSWarner Losh
54388e3e3a7aSWarner Losh
54398e3e3a7aSWarner Losh
54408e3e3a7aSWarner Losh
54418e3e3a7aSWarner Losh
54428e3e3a7aSWarner Losh<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p>
54430495ed39SKyle Evans<span class="apii">[-?, +?, <em>e</em>]</span>
54448e3e3a7aSWarner Losh<pre>void lua_settop (lua_State *L, int index);</pre>
54458e3e3a7aSWarner Losh
54468e3e3a7aSWarner Losh<p>
54478e3e3a7aSWarner LoshAccepts any index, or&nbsp;0,
54488e3e3a7aSWarner Loshand sets the stack top to this index.
54490495ed39SKyle EvansIf the new top is greater than the old one,
54508e3e3a7aSWarner Loshthen the new elements are filled with <b>nil</b>.
54518e3e3a7aSWarner LoshIf <code>index</code> is&nbsp;0, then all stack elements are removed.
54528e3e3a7aSWarner Losh
54538e3e3a7aSWarner Losh
54540495ed39SKyle Evans<p>
54550495ed39SKyle EvansThis function can run arbitrary code when removing an index
54560495ed39SKyle Evansmarked as to-be-closed from the stack.
54578e3e3a7aSWarner Losh
54588e3e3a7aSWarner Losh
54598e3e3a7aSWarner Losh
54600495ed39SKyle Evans
54610495ed39SKyle Evans
54620495ed39SKyle Evans<hr><h3><a name="lua_setwarnf"><code>lua_setwarnf</code></a></h3><p>
54630495ed39SKyle Evans<span class="apii">[-0, +0, &ndash;]</span>
54640495ed39SKyle Evans<pre>void lua_setwarnf (lua_State *L, lua_WarnFunction f, void *ud);</pre>
54658e3e3a7aSWarner Losh
54668e3e3a7aSWarner Losh<p>
54670495ed39SKyle EvansSets the warning function to be used by Lua to emit warnings
54680495ed39SKyle Evans(see <a href="#lua_WarnFunction"><code>lua_WarnFunction</code></a>).
54690495ed39SKyle EvansThe <code>ud</code> parameter sets the value <code>ud</code> passed to
54700495ed39SKyle Evansthe warning function.
54718e3e3a7aSWarner Losh
54728e3e3a7aSWarner Losh
54738e3e3a7aSWarner Losh
54748e3e3a7aSWarner Losh
54758e3e3a7aSWarner Losh
54768e3e3a7aSWarner Losh<hr><h3><a name="lua_State"><code>lua_State</code></a></h3>
54778e3e3a7aSWarner Losh<pre>typedef struct lua_State lua_State;</pre>
54788e3e3a7aSWarner Losh
54798e3e3a7aSWarner Losh<p>
54808e3e3a7aSWarner LoshAn opaque structure that points to a thread and indirectly
54818e3e3a7aSWarner Losh(through the thread) to the whole state of a Lua interpreter.
54828e3e3a7aSWarner LoshThe Lua library is fully reentrant:
54838e3e3a7aSWarner Loshit has no global variables.
54848e3e3a7aSWarner LoshAll information about a state is accessible through this structure.
54858e3e3a7aSWarner Losh
54868e3e3a7aSWarner Losh
54878e3e3a7aSWarner Losh<p>
54888e3e3a7aSWarner LoshA pointer to this structure must be passed as the first argument to
54898e3e3a7aSWarner Loshevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
54908e3e3a7aSWarner Loshwhich creates a Lua state from scratch.
54918e3e3a7aSWarner Losh
54928e3e3a7aSWarner Losh
54938e3e3a7aSWarner Losh
54948e3e3a7aSWarner Losh
54958e3e3a7aSWarner Losh
54968e3e3a7aSWarner Losh<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p>
54978e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
54988e3e3a7aSWarner Losh<pre>int lua_status (lua_State *L);</pre>
54998e3e3a7aSWarner Losh
55008e3e3a7aSWarner Losh<p>
55018e3e3a7aSWarner LoshReturns the status of the thread <code>L</code>.
55028e3e3a7aSWarner Losh
55038e3e3a7aSWarner Losh
55048e3e3a7aSWarner Losh<p>
55050495ed39SKyle EvansThe status can be <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for a normal thread,
55068e3e3a7aSWarner Loshan error code if the thread finished the execution
55078e3e3a7aSWarner Loshof a <a href="#lua_resume"><code>lua_resume</code></a> with an error,
55080495ed39SKyle Evansor <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended.
55098e3e3a7aSWarner Losh
55108e3e3a7aSWarner Losh
55118e3e3a7aSWarner Losh<p>
55120495ed39SKyle EvansYou can call functions only in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>.
55138e3e3a7aSWarner LoshYou can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>
55148e3e3a7aSWarner Losh(to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a>
55158e3e3a7aSWarner Losh(to resume a coroutine).
55168e3e3a7aSWarner Losh
55178e3e3a7aSWarner Losh
55188e3e3a7aSWarner Losh
55198e3e3a7aSWarner Losh
55208e3e3a7aSWarner Losh
55218e3e3a7aSWarner Losh<hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p>
55228e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
55238e3e3a7aSWarner Losh<pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre>
55248e3e3a7aSWarner Losh
55258e3e3a7aSWarner Losh<p>
55268e3e3a7aSWarner LoshConverts the zero-terminated string <code>s</code> to a number,
55278e3e3a7aSWarner Loshpushes that number into the stack,
55288e3e3a7aSWarner Loshand returns the total size of the string,
55298e3e3a7aSWarner Loshthat is, its length plus one.
55308e3e3a7aSWarner LoshThe conversion can result in an integer or a float,
55318e3e3a7aSWarner Loshaccording to the lexical conventions of Lua (see <a href="#3.1">&sect;3.1</a>).
55320495ed39SKyle EvansThe string may have leading and trailing whitespaces and a sign.
55338e3e3a7aSWarner LoshIf the string is not a valid numeral,
55348e3e3a7aSWarner Loshreturns 0 and pushes nothing.
55358e3e3a7aSWarner Losh(Note that the result can be used as a boolean,
55368e3e3a7aSWarner Loshtrue if the conversion succeeds.)
55378e3e3a7aSWarner Losh
55388e3e3a7aSWarner Losh
55398e3e3a7aSWarner Losh
55408e3e3a7aSWarner Losh
55418e3e3a7aSWarner Losh
55428e3e3a7aSWarner Losh<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p>
55438e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
55448e3e3a7aSWarner Losh<pre>int lua_toboolean (lua_State *L, int index);</pre>
55458e3e3a7aSWarner Losh
55468e3e3a7aSWarner Losh<p>
55478e3e3a7aSWarner LoshConverts the Lua value at the given index to a C&nbsp;boolean
55488e3e3a7aSWarner Loshvalue (0&nbsp;or&nbsp;1).
55498e3e3a7aSWarner LoshLike all tests in Lua,
55508e3e3a7aSWarner Losh<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value
55518e3e3a7aSWarner Loshdifferent from <b>false</b> and <b>nil</b>;
55528e3e3a7aSWarner Loshotherwise it returns false.
55538e3e3a7aSWarner Losh(If you want to accept only actual boolean values,
55548e3e3a7aSWarner Loshuse <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.)
55558e3e3a7aSWarner Losh
55568e3e3a7aSWarner Losh
55578e3e3a7aSWarner Losh
55588e3e3a7aSWarner Losh
55598e3e3a7aSWarner Losh
55608e3e3a7aSWarner Losh<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p>
55618e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
55628e3e3a7aSWarner Losh<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre>
55638e3e3a7aSWarner Losh
55648e3e3a7aSWarner Losh<p>
55658e3e3a7aSWarner LoshConverts a value at the given index to a C&nbsp;function.
55668e3e3a7aSWarner LoshThat value must be a C&nbsp;function;
55678e3e3a7aSWarner Loshotherwise, returns <code>NULL</code>.
55688e3e3a7aSWarner Losh
55698e3e3a7aSWarner Losh
55708e3e3a7aSWarner Losh
55718e3e3a7aSWarner Losh
55728e3e3a7aSWarner Losh
55730495ed39SKyle Evans<hr><h3><a name="lua_toclose"><code>lua_toclose</code></a></h3><p>
5574*3068d706SWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
55750495ed39SKyle Evans<pre>void lua_toclose (lua_State *L, int index);</pre>
55760495ed39SKyle Evans
55770495ed39SKyle Evans<p>
55780495ed39SKyle EvansMarks the given index in the stack as a
55798c784bb8SWarner Loshto-be-closed slot (see <a href="#3.3.8">&sect;3.3.8</a>).
55800495ed39SKyle EvansLike a to-be-closed variable in Lua,
55818c784bb8SWarner Loshthe value at that slot in the stack will be closed
55820495ed39SKyle Evanswhen it goes out of scope.
55830495ed39SKyle EvansHere, in the context of a C function,
55840495ed39SKyle Evansto go out of scope means that the running function returns to Lua,
55858c784bb8SWarner Loshor there is an error,
55868c784bb8SWarner Loshor the slot is removed from the stack through
55878c784bb8SWarner Losh<a href="#lua_settop"><code>lua_settop</code></a> or <a href="#lua_pop"><code>lua_pop</code></a>,
55888c784bb8SWarner Loshor there is a call to <a href="#lua_closeslot"><code>lua_closeslot</code></a>.
55898c784bb8SWarner LoshA slot marked as to-be-closed should not be removed from the stack
55908c784bb8SWarner Loshby any other function in the API except <a href="#lua_settop"><code>lua_settop</code></a> or <a href="#lua_pop"><code>lua_pop</code></a>,
55918c784bb8SWarner Loshunless previously deactivated by <a href="#lua_closeslot"><code>lua_closeslot</code></a>.
55920495ed39SKyle Evans
55930495ed39SKyle Evans
55940495ed39SKyle Evans<p>
5595*3068d706SWarner LoshThis function raises an error if the value at the given slot
5596*3068d706SWarner Loshneither has a <code>__close</code> metamethod nor is a false value.
5597*3068d706SWarner Losh
5598*3068d706SWarner Losh
5599*3068d706SWarner Losh<p>
56000495ed39SKyle EvansThis function should not be called for an index
56018c784bb8SWarner Loshthat is equal to or below an active to-be-closed slot.
56020495ed39SKyle Evans
56030495ed39SKyle Evans
56040495ed39SKyle Evans<p>
56050495ed39SKyle EvansNote that, both in case of errors and of a regular return,
56060495ed39SKyle Evansby the time the <code>__close</code> metamethod runs,
56070495ed39SKyle Evansthe C&nbsp;stack was already unwound,
56080495ed39SKyle Evansso that any automatic C&nbsp;variable declared in the calling function
56098c784bb8SWarner Losh(e.g., a buffer) will be out of scope.
56100495ed39SKyle Evans
56110495ed39SKyle Evans
56120495ed39SKyle Evans
56130495ed39SKyle Evans
56140495ed39SKyle Evans
56158e3e3a7aSWarner Losh<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p>
56168e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
56178e3e3a7aSWarner Losh<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre>
56188e3e3a7aSWarner Losh
56198e3e3a7aSWarner Losh<p>
56208e3e3a7aSWarner LoshEquivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
56218e3e3a7aSWarner Losh
56228e3e3a7aSWarner Losh
56238e3e3a7aSWarner Losh
56248e3e3a7aSWarner Losh
56258e3e3a7aSWarner Losh
56268e3e3a7aSWarner Losh<hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p>
56278e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
56288e3e3a7aSWarner Losh<pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre>
56298e3e3a7aSWarner Losh
56308e3e3a7aSWarner Losh<p>
56318e3e3a7aSWarner LoshConverts the Lua value at the given index
56328e3e3a7aSWarner Loshto the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>.
56338e3e3a7aSWarner LoshThe Lua value must be an integer,
56348e3e3a7aSWarner Loshor a number or string convertible to an integer (see <a href="#3.4.3">&sect;3.4.3</a>);
56358e3e3a7aSWarner Loshotherwise, <code>lua_tointegerx</code> returns&nbsp;0.
56368e3e3a7aSWarner Losh
56378e3e3a7aSWarner Losh
56388e3e3a7aSWarner Losh<p>
56398e3e3a7aSWarner LoshIf <code>isnum</code> is not <code>NULL</code>,
56408e3e3a7aSWarner Loshits referent is assigned a boolean value that
56418e3e3a7aSWarner Loshindicates whether the operation succeeded.
56428e3e3a7aSWarner Losh
56438e3e3a7aSWarner Losh
56448e3e3a7aSWarner Losh
56458e3e3a7aSWarner Losh
56468e3e3a7aSWarner Losh
56478e3e3a7aSWarner Losh<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p>
56488e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span>
56498e3e3a7aSWarner Losh<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre>
56508e3e3a7aSWarner Losh
56518e3e3a7aSWarner Losh<p>
56528e3e3a7aSWarner LoshConverts the Lua value at the given index to a C&nbsp;string.
56538e3e3a7aSWarner LoshIf <code>len</code> is not <code>NULL</code>,
56548e3e3a7aSWarner Loshit sets <code>*len</code> with the string length.
56558e3e3a7aSWarner LoshThe Lua value must be a string or a number;
56568e3e3a7aSWarner Loshotherwise, the function returns <code>NULL</code>.
56578e3e3a7aSWarner LoshIf the value is a number,
56588e3e3a7aSWarner Loshthen <code>lua_tolstring</code> also
56598e3e3a7aSWarner Losh<em>changes the actual value in the stack to a string</em>.
56608e3e3a7aSWarner Losh(This change confuses <a href="#lua_next"><code>lua_next</code></a>
56618e3e3a7aSWarner Loshwhen <code>lua_tolstring</code> is applied to keys during a table traversal.)
56628e3e3a7aSWarner Losh
56638e3e3a7aSWarner Losh
56648e3e3a7aSWarner Losh<p>
56658e3e3a7aSWarner Losh<code>lua_tolstring</code> returns a pointer
56660495ed39SKyle Evansto a string inside the Lua state (see <a href="#4.1.3">&sect;4.1.3</a>).
56678e3e3a7aSWarner LoshThis string always has a zero ('<code>\0</code>')
56688e3e3a7aSWarner Loshafter its last character (as in&nbsp;C),
56698e3e3a7aSWarner Loshbut can contain other zeros in its body.
56708e3e3a7aSWarner Losh
56718e3e3a7aSWarner Losh
5672*3068d706SWarner Losh<p>
5673*3068d706SWarner LoshThis function can raise memory errors only
5674*3068d706SWarner Loshwhen converting a number to a string
5675*3068d706SWarner Losh(as then it may create a new string).
5676*3068d706SWarner Losh
5677*3068d706SWarner Losh
56788e3e3a7aSWarner Losh
56798e3e3a7aSWarner Losh
56808e3e3a7aSWarner Losh
56818e3e3a7aSWarner Losh<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p>
56828e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
56838e3e3a7aSWarner Losh<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre>
56848e3e3a7aSWarner Losh
56858e3e3a7aSWarner Losh<p>
56868e3e3a7aSWarner LoshEquivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
56878e3e3a7aSWarner Losh
56888e3e3a7aSWarner Losh
56898e3e3a7aSWarner Losh
56908e3e3a7aSWarner Losh
56918e3e3a7aSWarner Losh
56928e3e3a7aSWarner Losh<hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p>
56938e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
56948e3e3a7aSWarner Losh<pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre>
56958e3e3a7aSWarner Losh
56968e3e3a7aSWarner Losh<p>
56978e3e3a7aSWarner LoshConverts the Lua value at the given index
56988e3e3a7aSWarner Loshto the C&nbsp;type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>).
56998e3e3a7aSWarner LoshThe Lua value must be a number or a string convertible to a number
57008e3e3a7aSWarner Losh(see <a href="#3.4.3">&sect;3.4.3</a>);
57018e3e3a7aSWarner Loshotherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns&nbsp;0.
57028e3e3a7aSWarner Losh
57038e3e3a7aSWarner Losh
57048e3e3a7aSWarner Losh<p>
57058e3e3a7aSWarner LoshIf <code>isnum</code> is not <code>NULL</code>,
57068e3e3a7aSWarner Loshits referent is assigned a boolean value that
57078e3e3a7aSWarner Loshindicates whether the operation succeeded.
57088e3e3a7aSWarner Losh
57098e3e3a7aSWarner Losh
57108e3e3a7aSWarner Losh
57118e3e3a7aSWarner Losh
57128e3e3a7aSWarner Losh
57138e3e3a7aSWarner Losh<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p>
57148e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
57158e3e3a7aSWarner Losh<pre>const void *lua_topointer (lua_State *L, int index);</pre>
57168e3e3a7aSWarner Losh
57178e3e3a7aSWarner Losh<p>
57188e3e3a7aSWarner LoshConverts the value at the given index to a generic
57198e3e3a7aSWarner LoshC&nbsp;pointer (<code>void*</code>).
57200495ed39SKyle EvansThe value can be a userdata, a table, a thread, a string, or a function;
57218e3e3a7aSWarner Loshotherwise, <code>lua_topointer</code> returns <code>NULL</code>.
57228e3e3a7aSWarner LoshDifferent objects will give different pointers.
57238e3e3a7aSWarner LoshThere is no way to convert the pointer back to its original value.
57248e3e3a7aSWarner Losh
57258e3e3a7aSWarner Losh
57268e3e3a7aSWarner Losh<p>
57278e3e3a7aSWarner LoshTypically this function is used only for hashing and debug information.
57288e3e3a7aSWarner Losh
57298e3e3a7aSWarner Losh
57308e3e3a7aSWarner Losh
57318e3e3a7aSWarner Losh
57328e3e3a7aSWarner Losh
57338e3e3a7aSWarner Losh<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p>
57348e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span>
57358e3e3a7aSWarner Losh<pre>const char *lua_tostring (lua_State *L, int index);</pre>
57368e3e3a7aSWarner Losh
57378e3e3a7aSWarner Losh<p>
57388e3e3a7aSWarner LoshEquivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>.
57398e3e3a7aSWarner Losh
57408e3e3a7aSWarner Losh
57418e3e3a7aSWarner Losh
57428e3e3a7aSWarner Losh
57438e3e3a7aSWarner Losh
57448e3e3a7aSWarner Losh<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p>
57458e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
57468e3e3a7aSWarner Losh<pre>lua_State *lua_tothread (lua_State *L, int index);</pre>
57478e3e3a7aSWarner Losh
57488e3e3a7aSWarner Losh<p>
57498e3e3a7aSWarner LoshConverts the value at the given index to a Lua thread
57508e3e3a7aSWarner Losh(represented as <code>lua_State*</code>).
57518e3e3a7aSWarner LoshThis value must be a thread;
57528e3e3a7aSWarner Loshotherwise, the function returns <code>NULL</code>.
57538e3e3a7aSWarner Losh
57548e3e3a7aSWarner Losh
57558e3e3a7aSWarner Losh
57568e3e3a7aSWarner Losh
57578e3e3a7aSWarner Losh
57588e3e3a7aSWarner Losh<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p>
57598e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
57608e3e3a7aSWarner Losh<pre>void *lua_touserdata (lua_State *L, int index);</pre>
57618e3e3a7aSWarner Losh
57628e3e3a7aSWarner Losh<p>
57638e3e3a7aSWarner LoshIf the value at the given index is a full userdata,
57640495ed39SKyle Evansreturns its memory-block address.
57658e3e3a7aSWarner LoshIf the value is a light userdata,
57660495ed39SKyle Evansreturns its value (a pointer).
57678e3e3a7aSWarner LoshOtherwise, returns <code>NULL</code>.
57688e3e3a7aSWarner Losh
57698e3e3a7aSWarner Losh
57708e3e3a7aSWarner Losh
57718e3e3a7aSWarner Losh
57728e3e3a7aSWarner Losh
57738e3e3a7aSWarner Losh<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p>
57748e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
57758e3e3a7aSWarner Losh<pre>int lua_type (lua_State *L, int index);</pre>
57768e3e3a7aSWarner Losh
57778e3e3a7aSWarner Losh<p>
57788e3e3a7aSWarner LoshReturns the type of the value in the given valid index,
57790495ed39SKyle Evansor <code>LUA_TNONE</code> for a non-valid but acceptable index.
57808e3e3a7aSWarner LoshThe types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants
57818e3e3a7aSWarner Loshdefined in <code>lua.h</code>:
57820495ed39SKyle Evans<a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a>,
57838e3e3a7aSWarner Losh<a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>,
57848e3e3a7aSWarner Losh<a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>,
57858e3e3a7aSWarner Losh<a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>,
57868e3e3a7aSWarner Losh<a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>,
57878e3e3a7aSWarner Losh<a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>,
57888e3e3a7aSWarner Losh<a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>,
57898e3e3a7aSWarner Losh<a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>,
57908e3e3a7aSWarner Loshand
57918e3e3a7aSWarner Losh<a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>.
57928e3e3a7aSWarner Losh
57938e3e3a7aSWarner Losh
57948e3e3a7aSWarner Losh
57958e3e3a7aSWarner Losh
57968e3e3a7aSWarner Losh
57978e3e3a7aSWarner Losh<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p>
57988e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
57998e3e3a7aSWarner Losh<pre>const char *lua_typename (lua_State *L, int tp);</pre>
58008e3e3a7aSWarner Losh
58018e3e3a7aSWarner Losh<p>
58028e3e3a7aSWarner LoshReturns the name of the type encoded by the value <code>tp</code>,
58038e3e3a7aSWarner Loshwhich must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>.
58048e3e3a7aSWarner Losh
58058e3e3a7aSWarner Losh
58068e3e3a7aSWarner Losh
58078e3e3a7aSWarner Losh
58088e3e3a7aSWarner Losh
58098e3e3a7aSWarner Losh<hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3>
58108e3e3a7aSWarner Losh<pre>typedef ... lua_Unsigned;</pre>
58118e3e3a7aSWarner Losh
58128e3e3a7aSWarner Losh<p>
58138e3e3a7aSWarner LoshThe unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>.
58148e3e3a7aSWarner Losh
58158e3e3a7aSWarner Losh
58168e3e3a7aSWarner Losh
58178e3e3a7aSWarner Losh
58188e3e3a7aSWarner Losh
58198e3e3a7aSWarner Losh<hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p>
58208e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
58218e3e3a7aSWarner Losh<pre>int lua_upvalueindex (int i);</pre>
58228e3e3a7aSWarner Losh
58238e3e3a7aSWarner Losh<p>
58248e3e3a7aSWarner LoshReturns the pseudo-index that represents the <code>i</code>-th upvalue of
58250495ed39SKyle Evansthe running function (see <a href="#4.2">&sect;4.2</a>).
58260495ed39SKyle Evans<code>i</code> must be in the range <em>[1,256]</em>.
58278e3e3a7aSWarner Losh
58288e3e3a7aSWarner Losh
58298e3e3a7aSWarner Losh
58308e3e3a7aSWarner Losh
58318e3e3a7aSWarner Losh
58328e3e3a7aSWarner Losh<hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p>
58338e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
58340495ed39SKyle Evans<pre>lua_Number lua_version (lua_State *L);</pre>
58358e3e3a7aSWarner Losh
58368e3e3a7aSWarner Losh<p>
58370495ed39SKyle EvansReturns the version number of this core.
58380495ed39SKyle Evans
58390495ed39SKyle Evans
58400495ed39SKyle Evans
58410495ed39SKyle Evans
58420495ed39SKyle Evans
58430495ed39SKyle Evans<hr><h3><a name="lua_WarnFunction"><code>lua_WarnFunction</code></a></h3>
58440495ed39SKyle Evans<pre>typedef void (*lua_WarnFunction) (void *ud, const char *msg, int tocont);</pre>
58450495ed39SKyle Evans
58460495ed39SKyle Evans<p>
58470495ed39SKyle EvansThe type of warning functions, called by Lua to emit warnings.
58480495ed39SKyle EvansThe first parameter is an opaque pointer
58490495ed39SKyle Evansset by <a href="#lua_setwarnf"><code>lua_setwarnf</code></a>.
58500495ed39SKyle EvansThe second parameter is the warning message.
58510495ed39SKyle EvansThe third parameter is a boolean that
58520495ed39SKyle Evansindicates whether the message is
58530495ed39SKyle Evansto be continued by the message in the next call.
58540495ed39SKyle Evans
58550495ed39SKyle Evans
58560495ed39SKyle Evans<p>
58570495ed39SKyle EvansSee <a href="#pdf-warn"><code>warn</code></a> for more details about warnings.
58580495ed39SKyle Evans
58590495ed39SKyle Evans
58600495ed39SKyle Evans
58610495ed39SKyle Evans
58620495ed39SKyle Evans
58630495ed39SKyle Evans<hr><h3><a name="lua_warning"><code>lua_warning</code></a></h3><p>
58640495ed39SKyle Evans<span class="apii">[-0, +0, &ndash;]</span>
58650495ed39SKyle Evans<pre>void lua_warning (lua_State *L, const char *msg, int tocont);</pre>
58660495ed39SKyle Evans
58670495ed39SKyle Evans<p>
58680495ed39SKyle EvansEmits a warning with the given message.
58690495ed39SKyle EvansA message in a call with <code>tocont</code> true should be
58700495ed39SKyle Evanscontinued in another call to this function.
58710495ed39SKyle Evans
58720495ed39SKyle Evans
58730495ed39SKyle Evans<p>
58740495ed39SKyle EvansSee <a href="#pdf-warn"><code>warn</code></a> for more details about warnings.
58758e3e3a7aSWarner Losh
58768e3e3a7aSWarner Losh
58778e3e3a7aSWarner Losh
58788e3e3a7aSWarner Losh
58798e3e3a7aSWarner Losh
58808e3e3a7aSWarner Losh<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3>
58818e3e3a7aSWarner Losh<pre>typedef int (*lua_Writer) (lua_State *L,
58828e3e3a7aSWarner Losh                           const void* p,
58838e3e3a7aSWarner Losh                           size_t sz,
58848e3e3a7aSWarner Losh                           void* ud);</pre>
58858e3e3a7aSWarner Losh
58868e3e3a7aSWarner Losh<p>
58878e3e3a7aSWarner LoshThe type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>.
58880495ed39SKyle EvansEvery time <a href="#lua_dump"><code>lua_dump</code></a> produces another piece of chunk,
58890495ed39SKyle Evansit calls the writer,
58908e3e3a7aSWarner Loshpassing along the buffer to be written (<code>p</code>),
58918e3e3a7aSWarner Loshits size (<code>sz</code>),
58920495ed39SKyle Evansand the <code>ud</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>.
58938e3e3a7aSWarner Losh
58948e3e3a7aSWarner Losh
58958e3e3a7aSWarner Losh<p>
58968e3e3a7aSWarner LoshThe writer returns an error code:
58978e3e3a7aSWarner Losh0&nbsp;means no errors;
58988e3e3a7aSWarner Loshany other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from
58998e3e3a7aSWarner Loshcalling the writer again.
59008e3e3a7aSWarner Losh
59018e3e3a7aSWarner Losh
59028e3e3a7aSWarner Losh
59038e3e3a7aSWarner Losh
59048e3e3a7aSWarner Losh
59058e3e3a7aSWarner Losh<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p>
59068e3e3a7aSWarner Losh<span class="apii">[-?, +?, &ndash;]</span>
59078e3e3a7aSWarner Losh<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre>
59088e3e3a7aSWarner Losh
59098e3e3a7aSWarner Losh<p>
59108e3e3a7aSWarner LoshExchange values between different threads of the same state.
59118e3e3a7aSWarner Losh
59128e3e3a7aSWarner Losh
59138e3e3a7aSWarner Losh<p>
59148e3e3a7aSWarner LoshThis function pops <code>n</code> values from the stack <code>from</code>,
59158e3e3a7aSWarner Loshand pushes them onto the stack <code>to</code>.
59168e3e3a7aSWarner Losh
59178e3e3a7aSWarner Losh
59188e3e3a7aSWarner Losh
59198e3e3a7aSWarner Losh
59208e3e3a7aSWarner Losh
59218e3e3a7aSWarner Losh<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p>
59220495ed39SKyle Evans<span class="apii">[-?, +?, <em>v</em>]</span>
59238e3e3a7aSWarner Losh<pre>int lua_yield (lua_State *L, int nresults);</pre>
59248e3e3a7aSWarner Losh
59258e3e3a7aSWarner Losh<p>
59268e3e3a7aSWarner LoshThis function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
59270495ed39SKyle Evansbut it has no continuation (see <a href="#4.5">&sect;4.5</a>).
59288e3e3a7aSWarner LoshTherefore, when the thread resumes,
59298e3e3a7aSWarner Loshit continues the function that called
59308e3e3a7aSWarner Loshthe function calling <code>lua_yield</code>.
59310495ed39SKyle EvansTo avoid surprises,
59320495ed39SKyle Evansthis function should be called only in a tail call.
59338e3e3a7aSWarner Losh
59348e3e3a7aSWarner Losh
59358e3e3a7aSWarner Losh
59368e3e3a7aSWarner Losh
59378e3e3a7aSWarner Losh
59388e3e3a7aSWarner Losh<hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p>
59390495ed39SKyle Evans<span class="apii">[-?, +?, <em>v</em>]</span>
59408e3e3a7aSWarner Losh<pre>int lua_yieldk (lua_State *L,
59418e3e3a7aSWarner Losh                int nresults,
59428e3e3a7aSWarner Losh                lua_KContext ctx,
59438e3e3a7aSWarner Losh                lua_KFunction k);</pre>
59448e3e3a7aSWarner Losh
59458e3e3a7aSWarner Losh<p>
59468e3e3a7aSWarner LoshYields a coroutine (thread).
59478e3e3a7aSWarner Losh
59488e3e3a7aSWarner Losh
59498e3e3a7aSWarner Losh<p>
59508e3e3a7aSWarner LoshWhen a C&nbsp;function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
59518e3e3a7aSWarner Loshthe running coroutine suspends its execution,
59528e3e3a7aSWarner Loshand the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns.
59538e3e3a7aSWarner LoshThe parameter <code>nresults</code> is the number of values from the stack
59548e3e3a7aSWarner Loshthat will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>.
59558e3e3a7aSWarner Losh
59568e3e3a7aSWarner Losh
59578e3e3a7aSWarner Losh<p>
59588e3e3a7aSWarner LoshWhen the coroutine is resumed again,
59598e3e3a7aSWarner LoshLua calls the given continuation function <code>k</code> to continue
59600495ed39SKyle Evansthe execution of the C&nbsp;function that yielded (see <a href="#4.5">&sect;4.5</a>).
59618e3e3a7aSWarner LoshThis continuation function receives the same stack
59628e3e3a7aSWarner Loshfrom the previous function,
59638e3e3a7aSWarner Loshwith the <code>n</code> results removed and
59648e3e3a7aSWarner Loshreplaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>.
59658e3e3a7aSWarner LoshMoreover,
59668e3e3a7aSWarner Loshthe continuation function receives the value <code>ctx</code>
59678e3e3a7aSWarner Loshthat was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>.
59688e3e3a7aSWarner Losh
59698e3e3a7aSWarner Losh
59708e3e3a7aSWarner Losh<p>
59718e3e3a7aSWarner LoshUsually, this function does not return;
59728e3e3a7aSWarner Loshwhen the coroutine eventually resumes,
59738e3e3a7aSWarner Loshit continues executing the continuation function.
59748e3e3a7aSWarner LoshHowever, there is one special case,
59758e3e3a7aSWarner Loshwhich is when this function is called
59760495ed39SKyle Evansfrom inside a line or a count hook (see <a href="#4.7">&sect;4.7</a>).
59778e3e3a7aSWarner LoshIn that case, <code>lua_yieldk</code> should be called with no continuation
59788e3e3a7aSWarner Losh(probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results,
59798e3e3a7aSWarner Loshand the hook should return immediately after the call.
59808e3e3a7aSWarner LoshLua will yield and,
59818e3e3a7aSWarner Loshwhen the coroutine resumes again,
59828e3e3a7aSWarner Loshit will continue the normal execution
59838e3e3a7aSWarner Loshof the (Lua) function that triggered the hook.
59848e3e3a7aSWarner Losh
59858e3e3a7aSWarner Losh
59868e3e3a7aSWarner Losh<p>
59878e3e3a7aSWarner LoshThis function can raise an error if it is called from a thread
59880495ed39SKyle Evanswith a pending C call with no continuation function
59890495ed39SKyle Evans(what is called a <em>C-call boundary</em>),
59908e3e3a7aSWarner Loshor it is called from a thread that is not running inside a resume
59910495ed39SKyle Evans(typically the main thread).
59928e3e3a7aSWarner Losh
59938e3e3a7aSWarner Losh
59948e3e3a7aSWarner Losh
59958e3e3a7aSWarner Losh
59968e3e3a7aSWarner Losh
59978e3e3a7aSWarner Losh
59988e3e3a7aSWarner Losh
59990495ed39SKyle Evans<h2>4.7 &ndash; <a name="4.7">The Debug Interface</a></h2>
60008e3e3a7aSWarner Losh
60018e3e3a7aSWarner Losh<p>
60028e3e3a7aSWarner LoshLua has no built-in debugging facilities.
60038e3e3a7aSWarner LoshInstead, it offers a special interface
60048e3e3a7aSWarner Loshby means of functions and <em>hooks</em>.
60058e3e3a7aSWarner LoshThis interface allows the construction of different
60068e3e3a7aSWarner Loshkinds of debuggers, profilers, and other tools
60078e3e3a7aSWarner Loshthat need "inside information" from the interpreter.
60088e3e3a7aSWarner Losh
60098e3e3a7aSWarner Losh
60108e3e3a7aSWarner Losh
60118e3e3a7aSWarner Losh<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3>
60128e3e3a7aSWarner Losh<pre>typedef struct lua_Debug {
60138e3e3a7aSWarner Losh  int event;
60148e3e3a7aSWarner Losh  const char *name;           /* (n) */
60158e3e3a7aSWarner Losh  const char *namewhat;       /* (n) */
60168e3e3a7aSWarner Losh  const char *what;           /* (S) */
60178e3e3a7aSWarner Losh  const char *source;         /* (S) */
60180495ed39SKyle Evans  size_t srclen;              /* (S) */
60198e3e3a7aSWarner Losh  int currentline;            /* (l) */
60208e3e3a7aSWarner Losh  int linedefined;            /* (S) */
60218e3e3a7aSWarner Losh  int lastlinedefined;        /* (S) */
60228e3e3a7aSWarner Losh  unsigned char nups;         /* (u) number of upvalues */
60238e3e3a7aSWarner Losh  unsigned char nparams;      /* (u) number of parameters */
60248e3e3a7aSWarner Losh  char isvararg;              /* (u) */
60258e3e3a7aSWarner Losh  char istailcall;            /* (t) */
60260495ed39SKyle Evans  unsigned short ftransfer;   /* (r) index of first value transferred */
60270495ed39SKyle Evans  unsigned short ntransfer;   /* (r) number of transferred values */
60288e3e3a7aSWarner Losh  char short_src[LUA_IDSIZE]; /* (S) */
60298e3e3a7aSWarner Losh  /* private part */
60308e3e3a7aSWarner Losh  <em>other fields</em>
60318e3e3a7aSWarner Losh} lua_Debug;</pre>
60328e3e3a7aSWarner Losh
60338e3e3a7aSWarner Losh<p>
60348e3e3a7aSWarner LoshA structure used to carry different pieces of
60358e3e3a7aSWarner Loshinformation about a function or an activation record.
60368e3e3a7aSWarner Losh<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part
60378e3e3a7aSWarner Loshof this structure, for later use.
60388e3e3a7aSWarner LoshTo fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information,
60398c784bb8SWarner Loshyou must call <a href="#lua_getinfo"><code>lua_getinfo</code></a> with an appropriate parameter.
60408c784bb8SWarner Losh(Specifically, to get a field,
60418c784bb8SWarner Loshyou must add the letter between parentheses in the field's comment
60428c784bb8SWarner Loshto the parameter <code>what</code> of <a href="#lua_getinfo"><code>lua_getinfo</code></a>.)
60438e3e3a7aSWarner Losh
60448e3e3a7aSWarner Losh
60458e3e3a7aSWarner Losh<p>
60468e3e3a7aSWarner LoshThe fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning:
60478e3e3a7aSWarner Losh
60488e3e3a7aSWarner Losh<ul>
60498e3e3a7aSWarner Losh
60508e3e3a7aSWarner Losh<li><b><code>source</code>: </b>
60510495ed39SKyle Evansthe source of the chunk that created the function.
60528e3e3a7aSWarner LoshIf <code>source</code> starts with a '<code>@</code>',
60538e3e3a7aSWarner Loshit means that the function was defined in a file where
60548e3e3a7aSWarner Loshthe file name follows the '<code>@</code>'.
60558e3e3a7aSWarner LoshIf <code>source</code> starts with a '<code>=</code>',
60560495ed39SKyle Evansthe remainder of its contents describes the source in a user-dependent manner.
60578e3e3a7aSWarner LoshOtherwise,
60588e3e3a7aSWarner Loshthe function was defined in a string where
60598e3e3a7aSWarner Losh<code>source</code> is that string.
60608e3e3a7aSWarner Losh</li>
60618e3e3a7aSWarner Losh
60620495ed39SKyle Evans<li><b><code>srclen</code>: </b>
60630495ed39SKyle EvansThe length of the string <code>source</code>.
60640495ed39SKyle Evans</li>
60650495ed39SKyle Evans
60668e3e3a7aSWarner Losh<li><b><code>short_src</code>: </b>
60678e3e3a7aSWarner Losha "printable" version of <code>source</code>, to be used in error messages.
60688e3e3a7aSWarner Losh</li>
60698e3e3a7aSWarner Losh
60708e3e3a7aSWarner Losh<li><b><code>linedefined</code>: </b>
60718e3e3a7aSWarner Loshthe line number where the definition of the function starts.
60728e3e3a7aSWarner Losh</li>
60738e3e3a7aSWarner Losh
60748e3e3a7aSWarner Losh<li><b><code>lastlinedefined</code>: </b>
60758e3e3a7aSWarner Loshthe line number where the definition of the function ends.
60768e3e3a7aSWarner Losh</li>
60778e3e3a7aSWarner Losh
60788e3e3a7aSWarner Losh<li><b><code>what</code>: </b>
60798e3e3a7aSWarner Loshthe string <code>"Lua"</code> if the function is a Lua function,
60808e3e3a7aSWarner Losh<code>"C"</code> if it is a C&nbsp;function,
60818e3e3a7aSWarner Losh<code>"main"</code> if it is the main part of a chunk.
60828e3e3a7aSWarner Losh</li>
60838e3e3a7aSWarner Losh
60848e3e3a7aSWarner Losh<li><b><code>currentline</code>: </b>
60858e3e3a7aSWarner Loshthe current line where the given function is executing.
60868e3e3a7aSWarner LoshWhen no line information is available,
60878e3e3a7aSWarner Losh<code>currentline</code> is set to -1.
60888e3e3a7aSWarner Losh</li>
60898e3e3a7aSWarner Losh
60908e3e3a7aSWarner Losh<li><b><code>name</code>: </b>
60918e3e3a7aSWarner Losha reasonable name for the given function.
60928e3e3a7aSWarner LoshBecause functions in Lua are first-class values,
60938e3e3a7aSWarner Loshthey do not have a fixed name:
60948e3e3a7aSWarner Loshsome functions can be the value of multiple global variables,
60958e3e3a7aSWarner Loshwhile others can be stored only in a table field.
60968e3e3a7aSWarner LoshThe <code>lua_getinfo</code> function checks how the function was
60978e3e3a7aSWarner Loshcalled to find a suitable name.
60988e3e3a7aSWarner LoshIf it cannot find a name,
60998e3e3a7aSWarner Loshthen <code>name</code> is set to <code>NULL</code>.
61008e3e3a7aSWarner Losh</li>
61018e3e3a7aSWarner Losh
61028e3e3a7aSWarner Losh<li><b><code>namewhat</code>: </b>
61038e3e3a7aSWarner Loshexplains the <code>name</code> field.
61048e3e3a7aSWarner LoshThe value of <code>namewhat</code> can be
61058e3e3a7aSWarner Losh<code>"global"</code>, <code>"local"</code>, <code>"method"</code>,
61068e3e3a7aSWarner Losh<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string),
61078e3e3a7aSWarner Loshaccording to how the function was called.
61088e3e3a7aSWarner Losh(Lua uses the empty string when no other option seems to apply.)
61098e3e3a7aSWarner Losh</li>
61108e3e3a7aSWarner Losh
61118e3e3a7aSWarner Losh<li><b><code>istailcall</code>: </b>
61128e3e3a7aSWarner Loshtrue if this function invocation was called by a tail call.
61138e3e3a7aSWarner LoshIn this case, the caller of this level is not in the stack.
61148e3e3a7aSWarner Losh</li>
61158e3e3a7aSWarner Losh
61168e3e3a7aSWarner Losh<li><b><code>nups</code>: </b>
61178e3e3a7aSWarner Loshthe number of upvalues of the function.
61188e3e3a7aSWarner Losh</li>
61198e3e3a7aSWarner Losh
61208e3e3a7aSWarner Losh<li><b><code>nparams</code>: </b>
61210495ed39SKyle Evansthe number of parameters of the function
61228e3e3a7aSWarner Losh(always 0&nbsp;for C&nbsp;functions).
61238e3e3a7aSWarner Losh</li>
61248e3e3a7aSWarner Losh
61258e3e3a7aSWarner Losh<li><b><code>isvararg</code>: </b>
6126a9490b81SWarner Loshtrue if the function is a variadic function
61278e3e3a7aSWarner Losh(always true for C&nbsp;functions).
61288e3e3a7aSWarner Losh</li>
61298e3e3a7aSWarner Losh
61300495ed39SKyle Evans<li><b><code>ftransfer</code>: </b>
61310495ed39SKyle Evansthe index in the stack of the first value being "transferred",
61320495ed39SKyle Evansthat is, parameters in a call or return values in a return.
61330495ed39SKyle Evans(The other values are in consecutive indices.)
61340495ed39SKyle EvansUsing this index, you can access and modify these values
61350495ed39SKyle Evansthrough <a href="#lua_getlocal"><code>lua_getlocal</code></a> and <a href="#lua_setlocal"><code>lua_setlocal</code></a>.
61360495ed39SKyle EvansThis field is only meaningful during a
61370495ed39SKyle Evanscall hook, denoting the first parameter,
61380495ed39SKyle Evansor a return hook, denoting the first value being returned.
61390495ed39SKyle Evans(For call hooks, this value is always 1.)
61400495ed39SKyle Evans</li>
61410495ed39SKyle Evans
61420495ed39SKyle Evans<li><b><code>ntransfer</code>: </b>
61430495ed39SKyle EvansThe number of values being transferred (see previous item).
61440495ed39SKyle Evans(For calls of Lua functions,
61450495ed39SKyle Evansthis value is always equal to <code>nparams</code>.)
61460495ed39SKyle Evans</li>
61470495ed39SKyle Evans
61488e3e3a7aSWarner Losh</ul>
61498e3e3a7aSWarner Losh
61508e3e3a7aSWarner Losh
61518e3e3a7aSWarner Losh
61528e3e3a7aSWarner Losh
61538e3e3a7aSWarner Losh<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p>
61548e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
61558e3e3a7aSWarner Losh<pre>lua_Hook lua_gethook (lua_State *L);</pre>
61568e3e3a7aSWarner Losh
61578e3e3a7aSWarner Losh<p>
61588e3e3a7aSWarner LoshReturns the current hook function.
61598e3e3a7aSWarner Losh
61608e3e3a7aSWarner Losh
61618e3e3a7aSWarner Losh
61628e3e3a7aSWarner Losh
61638e3e3a7aSWarner Losh
61648e3e3a7aSWarner Losh<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p>
61658e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
61668e3e3a7aSWarner Losh<pre>int lua_gethookcount (lua_State *L);</pre>
61678e3e3a7aSWarner Losh
61688e3e3a7aSWarner Losh<p>
61698e3e3a7aSWarner LoshReturns the current hook count.
61708e3e3a7aSWarner Losh
61718e3e3a7aSWarner Losh
61728e3e3a7aSWarner Losh
61738e3e3a7aSWarner Losh
61748e3e3a7aSWarner Losh
61758e3e3a7aSWarner Losh<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p>
61768e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
61778e3e3a7aSWarner Losh<pre>int lua_gethookmask (lua_State *L);</pre>
61788e3e3a7aSWarner Losh
61798e3e3a7aSWarner Losh<p>
61808e3e3a7aSWarner LoshReturns the current hook mask.
61818e3e3a7aSWarner Losh
61828e3e3a7aSWarner Losh
61838e3e3a7aSWarner Losh
61848e3e3a7aSWarner Losh
61858e3e3a7aSWarner Losh
61868e3e3a7aSWarner Losh<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p>
61870495ed39SKyle Evans<span class="apii">[-(0|1), +(0|1|2), <em>m</em>]</span>
61888e3e3a7aSWarner Losh<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre>
61898e3e3a7aSWarner Losh
61908e3e3a7aSWarner Losh<p>
61918e3e3a7aSWarner LoshGets information about a specific function or function invocation.
61928e3e3a7aSWarner Losh
61938e3e3a7aSWarner Losh
61948e3e3a7aSWarner Losh<p>
61958e3e3a7aSWarner LoshTo get information about a function invocation,
61968e3e3a7aSWarner Loshthe parameter <code>ar</code> must be a valid activation record that was
61978e3e3a7aSWarner Loshfilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
61988e3e3a7aSWarner Loshgiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
61998e3e3a7aSWarner Losh
62008e3e3a7aSWarner Losh
62018e3e3a7aSWarner Losh<p>
6202e112e9d2SKyle EvansTo get information about a function, you push it onto the stack
62038e3e3a7aSWarner Loshand start the <code>what</code> string with the character '<code>&gt;</code>'.
62048e3e3a7aSWarner Losh(In that case,
62058e3e3a7aSWarner Losh<code>lua_getinfo</code> pops the function from the top of the stack.)
62068e3e3a7aSWarner LoshFor instance, to know in which line a function <code>f</code> was defined,
62078e3e3a7aSWarner Loshyou can write the following code:
62088e3e3a7aSWarner Losh
62098e3e3a7aSWarner Losh<pre>
62108e3e3a7aSWarner Losh     lua_Debug ar;
62118e3e3a7aSWarner Losh     lua_getglobal(L, "f");  /* get global 'f' */
62128e3e3a7aSWarner Losh     lua_getinfo(L, "&gt;S", &amp;ar);
62138e3e3a7aSWarner Losh     printf("%d\n", ar.linedefined);
62148e3e3a7aSWarner Losh</pre>
62158e3e3a7aSWarner Losh
62168e3e3a7aSWarner Losh<p>
62178e3e3a7aSWarner LoshEach character in the string <code>what</code>
62188e3e3a7aSWarner Loshselects some fields of the structure <code>ar</code> to be filled or
62198c784bb8SWarner Losha value to be pushed on the stack.
62208c784bb8SWarner Losh(These characters are also documented in the declaration of
62218c784bb8SWarner Loshthe structure <a href="#lua_Debug"><code>lua_Debug</code></a>,
62228c784bb8SWarner Loshbetween parentheses in the comments following each field.)
62238e3e3a7aSWarner Losh
62248e3e3a7aSWarner Losh<ul>
62258e3e3a7aSWarner Losh
62268c784bb8SWarner Losh<li><b>'<code>f</code>': </b>
62278c784bb8SWarner Loshpushes onto the stack the function that is
62288c784bb8SWarner Loshrunning at the given level;
62298c784bb8SWarner Losh</li>
62308c784bb8SWarner Losh
62318c784bb8SWarner Losh<li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>;
62328c784bb8SWarner Losh</li>
62338c784bb8SWarner Losh
62348c784bb8SWarner Losh<li><b>'<code>n</code>': </b> fills in the fields <code>name</code> and <code>namewhat</code>;
62358c784bb8SWarner Losh</li>
62368c784bb8SWarner Losh
62378c784bb8SWarner Losh<li><b>'<code>r</code>': </b> fills in the fields <code>ftransfer</code> and <code>ntransfer</code>;
62388e3e3a7aSWarner Losh</li>
62398e3e3a7aSWarner Losh
62408e3e3a7aSWarner Losh<li><b>'<code>S</code>': </b>
62418e3e3a7aSWarner Loshfills in the fields <code>source</code>, <code>short_src</code>,
62428e3e3a7aSWarner Losh<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>;
62438e3e3a7aSWarner Losh</li>
62448e3e3a7aSWarner Losh
62458e3e3a7aSWarner Losh<li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>;
62468e3e3a7aSWarner Losh</li>
62478e3e3a7aSWarner Losh
62488e3e3a7aSWarner Losh<li><b>'<code>u</code>': </b> fills in the fields
62498e3e3a7aSWarner Losh<code>nups</code>, <code>nparams</code>, and <code>isvararg</code>;
62508e3e3a7aSWarner Losh</li>
62518e3e3a7aSWarner Losh
62528e3e3a7aSWarner Losh<li><b>'<code>L</code>': </b>
62538c784bb8SWarner Loshpushes onto the stack a table whose indices are
62548c784bb8SWarner Loshthe lines on the function with some associated code,
62558c784bb8SWarner Loshthat is, the lines where you can put a break point.
62568c784bb8SWarner Losh(Lines with no code include empty lines and comments.)
62578e3e3a7aSWarner LoshIf this option is given together with option '<code>f</code>',
62588e3e3a7aSWarner Loshits table is pushed after the function.
62590495ed39SKyle EvansThis is the only option that can raise a memory error.
62608e3e3a7aSWarner Losh</li>
62618e3e3a7aSWarner Losh
62628e3e3a7aSWarner Losh</ul>
62638e3e3a7aSWarner Losh
62648e3e3a7aSWarner Losh<p>
62650495ed39SKyle EvansThis function returns 0 to signal an invalid option in <code>what</code>;
62660495ed39SKyle Evanseven then the valid options are handled correctly.
62678e3e3a7aSWarner Losh
62688e3e3a7aSWarner Losh
62698e3e3a7aSWarner Losh
62708e3e3a7aSWarner Losh
62718e3e3a7aSWarner Losh
62728e3e3a7aSWarner Losh<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p>
62738e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), &ndash;]</span>
62748e3e3a7aSWarner Losh<pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre>
62758e3e3a7aSWarner Losh
62768e3e3a7aSWarner Losh<p>
62770495ed39SKyle EvansGets information about a local variable or a temporary value
62780495ed39SKyle Evansof a given activation record or a given function.
62798e3e3a7aSWarner Losh
62808e3e3a7aSWarner Losh
62818e3e3a7aSWarner Losh<p>
62828e3e3a7aSWarner LoshIn the first case,
62838e3e3a7aSWarner Loshthe parameter <code>ar</code> must be a valid activation record that was
62848e3e3a7aSWarner Loshfilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
62858e3e3a7aSWarner Loshgiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
62868e3e3a7aSWarner LoshThe index <code>n</code> selects which local variable to inspect;
62878e3e3a7aSWarner Loshsee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices
62888e3e3a7aSWarner Loshand names.
62898e3e3a7aSWarner Losh
62908e3e3a7aSWarner Losh
62918e3e3a7aSWarner Losh<p>
62928e3e3a7aSWarner Losh<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack
62938e3e3a7aSWarner Loshand returns its name.
62948e3e3a7aSWarner Losh
62958e3e3a7aSWarner Losh
62968e3e3a7aSWarner Losh<p>
62978e3e3a7aSWarner LoshIn the second case, <code>ar</code> must be <code>NULL</code> and the function
62980495ed39SKyle Evansto be inspected must be on the top of the stack.
62998e3e3a7aSWarner LoshIn this case, only parameters of Lua functions are visible
63008e3e3a7aSWarner Losh(as there is no information about what variables are active)
63018e3e3a7aSWarner Loshand no values are pushed onto the stack.
63028e3e3a7aSWarner Losh
63038e3e3a7aSWarner Losh
63048e3e3a7aSWarner Losh<p>
63058e3e3a7aSWarner LoshReturns <code>NULL</code> (and pushes nothing)
63068e3e3a7aSWarner Loshwhen the index is greater than
63078e3e3a7aSWarner Loshthe number of active local variables.
63088e3e3a7aSWarner Losh
63098e3e3a7aSWarner Losh
63108e3e3a7aSWarner Losh
63118e3e3a7aSWarner Losh
63128e3e3a7aSWarner Losh
63138e3e3a7aSWarner Losh<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p>
63148e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
63158e3e3a7aSWarner Losh<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre>
63168e3e3a7aSWarner Losh
63178e3e3a7aSWarner Losh<p>
63188e3e3a7aSWarner LoshGets information about the interpreter runtime stack.
63198e3e3a7aSWarner Losh
63208e3e3a7aSWarner Losh
63218e3e3a7aSWarner Losh<p>
63228e3e3a7aSWarner LoshThis function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with
63238e3e3a7aSWarner Loshan identification of the <em>activation record</em>
63248e3e3a7aSWarner Loshof the function executing at a given level.
63258e3e3a7aSWarner LoshLevel&nbsp;0 is the current running function,
63268e3e3a7aSWarner Loshwhereas level <em>n+1</em> is the function that has called level <em>n</em>
63270495ed39SKyle Evans(except for tail calls, which do not count in the stack).
63280495ed39SKyle EvansWhen called with a level greater than the stack depth,
63290495ed39SKyle Evans<a href="#lua_getstack"><code>lua_getstack</code></a> returns 0;
63300495ed39SKyle Evansotherwise it returns 1.
63318e3e3a7aSWarner Losh
63328e3e3a7aSWarner Losh
63338e3e3a7aSWarner Losh
63348e3e3a7aSWarner Losh
63358e3e3a7aSWarner Losh
63368e3e3a7aSWarner Losh<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p>
63378e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), &ndash;]</span>
63388e3e3a7aSWarner Losh<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre>
63398e3e3a7aSWarner Losh
63408e3e3a7aSWarner Losh<p>
63418e3e3a7aSWarner LoshGets information about the <code>n</code>-th upvalue
63428e3e3a7aSWarner Loshof the closure at index <code>funcindex</code>.
63438e3e3a7aSWarner LoshIt pushes the upvalue's value onto the stack
63448e3e3a7aSWarner Loshand returns its name.
63458e3e3a7aSWarner LoshReturns <code>NULL</code> (and pushes nothing)
63468e3e3a7aSWarner Loshwhen the index <code>n</code> is greater than the number of upvalues.
63478e3e3a7aSWarner Losh
63488e3e3a7aSWarner Losh
63498e3e3a7aSWarner Losh<p>
63500495ed39SKyle EvansSee <a href="#pdf-debug.getupvalue"><code>debug.getupvalue</code></a> for more information about upvalues.
63518e3e3a7aSWarner Losh
63528e3e3a7aSWarner Losh
63538e3e3a7aSWarner Losh
63548e3e3a7aSWarner Losh
63558e3e3a7aSWarner Losh
63568e3e3a7aSWarner Losh<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3>
63578e3e3a7aSWarner Losh<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre>
63588e3e3a7aSWarner Losh
63598e3e3a7aSWarner Losh<p>
63608e3e3a7aSWarner LoshType for debugging hook functions.
63618e3e3a7aSWarner Losh
63628e3e3a7aSWarner Losh
63638e3e3a7aSWarner Losh<p>
63648e3e3a7aSWarner LoshWhenever a hook is called, its <code>ar</code> argument has its field
63658e3e3a7aSWarner Losh<code>event</code> set to the specific event that triggered the hook.
63668e3e3a7aSWarner LoshLua identifies these events with the following constants:
63678e3e3a7aSWarner Losh<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>,
63688e3e3a7aSWarner Losh<a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>,
63698e3e3a7aSWarner Loshand <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>.
63708e3e3a7aSWarner LoshMoreover, for line events, the field <code>currentline</code> is also set.
63718e3e3a7aSWarner LoshTo get the value of any other field in <code>ar</code>,
63728e3e3a7aSWarner Loshthe hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
63738e3e3a7aSWarner Losh
63748e3e3a7aSWarner Losh
63758e3e3a7aSWarner Losh<p>
63768e3e3a7aSWarner LoshFor call events, <code>event</code> can be <code>LUA_HOOKCALL</code>,
63778e3e3a7aSWarner Loshthe normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call;
63788e3e3a7aSWarner Loshin this case, there will be no corresponding return event.
63798e3e3a7aSWarner Losh
63808e3e3a7aSWarner Losh
63818e3e3a7aSWarner Losh<p>
63828e3e3a7aSWarner LoshWhile Lua is running a hook, it disables other calls to hooks.
63838e3e3a7aSWarner LoshTherefore, if a hook calls back Lua to execute a function or a chunk,
63848e3e3a7aSWarner Loshthis execution occurs without any calls to hooks.
63858e3e3a7aSWarner Losh
63868e3e3a7aSWarner Losh
63878e3e3a7aSWarner Losh<p>
63888e3e3a7aSWarner LoshHook functions cannot have continuations,
63898e3e3a7aSWarner Loshthat is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
63908e3e3a7aSWarner 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>.
63918e3e3a7aSWarner Losh
63928e3e3a7aSWarner Losh
63938e3e3a7aSWarner Losh<p>
63948e3e3a7aSWarner LoshHook functions can yield under the following conditions:
63958e3e3a7aSWarner LoshOnly count and line events can yield;
63968e3e3a7aSWarner Loshto yield, a hook function must finish its execution
63978e3e3a7aSWarner Loshcalling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero
63988e3e3a7aSWarner Losh(that is, with no values).
63998e3e3a7aSWarner Losh
64008e3e3a7aSWarner Losh
64018e3e3a7aSWarner Losh
64028e3e3a7aSWarner Losh
64038e3e3a7aSWarner Losh
64048e3e3a7aSWarner Losh<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p>
64058e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
64068e3e3a7aSWarner Losh<pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre>
64078e3e3a7aSWarner Losh
64088e3e3a7aSWarner Losh<p>
64098e3e3a7aSWarner LoshSets the debugging hook function.
64108e3e3a7aSWarner Losh
64118e3e3a7aSWarner Losh
64128e3e3a7aSWarner Losh<p>
64138e3e3a7aSWarner LoshArgument <code>f</code> is the hook function.
64148e3e3a7aSWarner Losh<code>mask</code> specifies on which events the hook will be called:
64158e3e3a7aSWarner Loshit is formed by a bitwise OR of the constants
64168e3e3a7aSWarner Losh<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>,
64178e3e3a7aSWarner Losh<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>,
64188e3e3a7aSWarner Losh<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>,
64198e3e3a7aSWarner Loshand <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>.
64208e3e3a7aSWarner LoshThe <code>count</code> argument is only meaningful when the mask
64218e3e3a7aSWarner Loshincludes <code>LUA_MASKCOUNT</code>.
64228e3e3a7aSWarner LoshFor each event, the hook is called as explained below:
64238e3e3a7aSWarner Losh
64248e3e3a7aSWarner Losh<ul>
64258e3e3a7aSWarner Losh
64268e3e3a7aSWarner Losh<li><b>The call hook: </b> is called when the interpreter calls a function.
64270495ed39SKyle EvansThe hook is called just after Lua enters the new function.
64288e3e3a7aSWarner Losh</li>
64298e3e3a7aSWarner Losh
64308e3e3a7aSWarner Losh<li><b>The return hook: </b> is called when the interpreter returns from a function.
64318e3e3a7aSWarner LoshThe hook is called just before Lua leaves the function.
64328e3e3a7aSWarner Losh</li>
64338e3e3a7aSWarner Losh
64348e3e3a7aSWarner Losh<li><b>The line hook: </b> is called when the interpreter is about to
64358e3e3a7aSWarner Loshstart the execution of a new line of code,
64368e3e3a7aSWarner Loshor when it jumps back in the code (even to the same line).
64370495ed39SKyle EvansThis event only happens while Lua is executing a Lua function.
64388e3e3a7aSWarner Losh</li>
64398e3e3a7aSWarner Losh
64408e3e3a7aSWarner Losh<li><b>The count hook: </b> is called after the interpreter executes every
64418e3e3a7aSWarner Losh<code>count</code> instructions.
64420495ed39SKyle EvansThis event only happens while Lua is executing a Lua function.
64438e3e3a7aSWarner Losh</li>
64448e3e3a7aSWarner Losh
64458e3e3a7aSWarner Losh</ul>
64468e3e3a7aSWarner Losh
64478e3e3a7aSWarner Losh<p>
64480495ed39SKyle EvansHooks are disabled by setting <code>mask</code> to zero.
64498e3e3a7aSWarner Losh
64508e3e3a7aSWarner Losh
64518e3e3a7aSWarner Losh
64528e3e3a7aSWarner Losh
64538e3e3a7aSWarner Losh
64548e3e3a7aSWarner Losh<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p>
64558e3e3a7aSWarner Losh<span class="apii">[-(0|1), +0, &ndash;]</span>
64568e3e3a7aSWarner Losh<pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre>
64578e3e3a7aSWarner Losh
64588e3e3a7aSWarner Losh<p>
64598e3e3a7aSWarner LoshSets the value of a local variable of a given activation record.
64600495ed39SKyle EvansIt assigns the value on the top of the stack
64618e3e3a7aSWarner Loshto the variable and returns its name.
64628e3e3a7aSWarner LoshIt also pops the value from the stack.
64638e3e3a7aSWarner Losh
64648e3e3a7aSWarner Losh
64658e3e3a7aSWarner Losh<p>
64668e3e3a7aSWarner LoshReturns <code>NULL</code> (and pops nothing)
64678e3e3a7aSWarner Loshwhen the index is greater than
64688e3e3a7aSWarner Loshthe number of active local variables.
64698e3e3a7aSWarner Losh
64708e3e3a7aSWarner Losh
64718e3e3a7aSWarner Losh<p>
64720495ed39SKyle EvansParameters <code>ar</code> and <code>n</code> are as in the function <a href="#lua_getlocal"><code>lua_getlocal</code></a>.
64738e3e3a7aSWarner Losh
64748e3e3a7aSWarner Losh
64758e3e3a7aSWarner Losh
64768e3e3a7aSWarner Losh
64778e3e3a7aSWarner Losh
64788e3e3a7aSWarner Losh<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p>
64798e3e3a7aSWarner Losh<span class="apii">[-(0|1), +0, &ndash;]</span>
64808e3e3a7aSWarner Losh<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre>
64818e3e3a7aSWarner Losh
64828e3e3a7aSWarner Losh<p>
64838e3e3a7aSWarner LoshSets the value of a closure's upvalue.
64840495ed39SKyle EvansIt assigns the value on the top of the stack
64858e3e3a7aSWarner Loshto the upvalue and returns its name.
64868e3e3a7aSWarner LoshIt also pops the value from the stack.
64878e3e3a7aSWarner Losh
64888e3e3a7aSWarner Losh
64898e3e3a7aSWarner Losh<p>
64908e3e3a7aSWarner LoshReturns <code>NULL</code> (and pops nothing)
64918e3e3a7aSWarner Loshwhen the index <code>n</code> is greater than the number of upvalues.
64928e3e3a7aSWarner Losh
64938e3e3a7aSWarner Losh
64948e3e3a7aSWarner Losh<p>
64950495ed39SKyle EvansParameters <code>funcindex</code> and <code>n</code> are as in
64960495ed39SKyle Evansthe function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>.
64978e3e3a7aSWarner Losh
64988e3e3a7aSWarner Losh
64998e3e3a7aSWarner Losh
65008e3e3a7aSWarner Losh
65018e3e3a7aSWarner Losh
65028e3e3a7aSWarner Losh<hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p>
65038e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
65048e3e3a7aSWarner Losh<pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre>
65058e3e3a7aSWarner Losh
65068e3e3a7aSWarner Losh<p>
65078e3e3a7aSWarner LoshReturns a unique identifier for the upvalue numbered <code>n</code>
65088e3e3a7aSWarner Loshfrom the closure at index <code>funcindex</code>.
65098e3e3a7aSWarner Losh
65108e3e3a7aSWarner Losh
65118e3e3a7aSWarner Losh<p>
65128e3e3a7aSWarner LoshThese unique identifiers allow a program to check whether different
65138e3e3a7aSWarner Loshclosures share upvalues.
65148e3e3a7aSWarner LoshLua closures that share an upvalue
65158e3e3a7aSWarner Losh(that is, that access a same external local variable)
65168e3e3a7aSWarner Loshwill return identical ids for those upvalue indices.
65178e3e3a7aSWarner Losh
65188e3e3a7aSWarner Losh
65198e3e3a7aSWarner Losh<p>
65200495ed39SKyle EvansParameters <code>funcindex</code> and <code>n</code> are as in
65210495ed39SKyle Evansthe function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>,
65228e3e3a7aSWarner Loshbut <code>n</code> cannot be greater than the number of upvalues.
65238e3e3a7aSWarner Losh
65248e3e3a7aSWarner Losh
65258e3e3a7aSWarner Losh
65268e3e3a7aSWarner Losh
65278e3e3a7aSWarner Losh
65288e3e3a7aSWarner Losh<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p>
65298e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
65308e3e3a7aSWarner Losh<pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
65318e3e3a7aSWarner Losh                                    int funcindex2, int n2);</pre>
65328e3e3a7aSWarner Losh
65338e3e3a7aSWarner Losh<p>
65348e3e3a7aSWarner LoshMake the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code>
65358e3e3a7aSWarner Loshrefer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>.
65368e3e3a7aSWarner Losh
65378e3e3a7aSWarner Losh
65388e3e3a7aSWarner Losh
65398e3e3a7aSWarner Losh
65408e3e3a7aSWarner Losh
65418e3e3a7aSWarner Losh
65428e3e3a7aSWarner Losh
65438e3e3a7aSWarner Losh<h1>5 &ndash; <a name="5">The Auxiliary Library</a></h1>
65448e3e3a7aSWarner Losh
65450495ed39SKyle Evans
65460495ed39SKyle Evans
65478e3e3a7aSWarner Losh<p>
65488e3e3a7aSWarner Losh
65498e3e3a7aSWarner LoshThe <em>auxiliary library</em> provides several convenient functions
65508e3e3a7aSWarner Loshto interface C with Lua.
65518e3e3a7aSWarner LoshWhile the basic API provides the primitive functions for all
65528e3e3a7aSWarner Loshinteractions between C and Lua,
65538e3e3a7aSWarner Loshthe auxiliary library provides higher-level functions for some
65548e3e3a7aSWarner Loshcommon tasks.
65558e3e3a7aSWarner Losh
65568e3e3a7aSWarner Losh
65578e3e3a7aSWarner Losh<p>
65588e3e3a7aSWarner LoshAll functions and types from the auxiliary library
65598e3e3a7aSWarner Loshare defined in header file <code>lauxlib.h</code> and
65608e3e3a7aSWarner Loshhave a prefix <code>luaL_</code>.
65618e3e3a7aSWarner Losh
65628e3e3a7aSWarner Losh
65638e3e3a7aSWarner Losh<p>
65648e3e3a7aSWarner LoshAll functions in the auxiliary library are built on
65658e3e3a7aSWarner Loshtop of the basic API,
65668e3e3a7aSWarner Loshand so they provide nothing that cannot be done with that API.
65678e3e3a7aSWarner LoshNevertheless, the use of the auxiliary library ensures
65688e3e3a7aSWarner Loshmore consistency to your code.
65698e3e3a7aSWarner Losh
65708e3e3a7aSWarner Losh
65718e3e3a7aSWarner Losh<p>
65728e3e3a7aSWarner LoshSeveral functions in the auxiliary library use internally some
65738e3e3a7aSWarner Loshextra stack slots.
65748e3e3a7aSWarner LoshWhen a function in the auxiliary library uses less than five slots,
65758e3e3a7aSWarner Loshit does not check the stack size;
65768e3e3a7aSWarner Loshit simply assumes that there are enough slots.
65778e3e3a7aSWarner Losh
65788e3e3a7aSWarner Losh
65798e3e3a7aSWarner Losh<p>
65808e3e3a7aSWarner LoshSeveral functions in the auxiliary library are used to
65818e3e3a7aSWarner Loshcheck C&nbsp;function arguments.
65828e3e3a7aSWarner LoshBecause the error message is formatted for arguments
65838e3e3a7aSWarner Losh(e.g., "<code>bad argument #1</code>"),
65848e3e3a7aSWarner Loshyou should not use these functions for other stack values.
65858e3e3a7aSWarner Losh
65868e3e3a7aSWarner Losh
65878e3e3a7aSWarner Losh<p>
65888e3e3a7aSWarner LoshFunctions called <code>luaL_check*</code>
65898e3e3a7aSWarner Loshalways raise an error if the check is not satisfied.
65908e3e3a7aSWarner Losh
65918e3e3a7aSWarner Losh
65928e3e3a7aSWarner Losh
65930495ed39SKyle Evans
65940495ed39SKyle Evans
65958e3e3a7aSWarner Losh<h2>5.1 &ndash; <a name="5.1">Functions and Types</a></h2>
65968e3e3a7aSWarner Losh
65978e3e3a7aSWarner Losh<p>
65988e3e3a7aSWarner LoshHere we list all functions and types from the auxiliary library
65998e3e3a7aSWarner Loshin alphabetical order.
66008e3e3a7aSWarner Losh
66018e3e3a7aSWarner Losh
66028e3e3a7aSWarner Losh
66038e3e3a7aSWarner Losh<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p>
66048e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span>
66058e3e3a7aSWarner Losh<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre>
66068e3e3a7aSWarner Losh
66078e3e3a7aSWarner Losh<p>
66088e3e3a7aSWarner LoshAdds the byte <code>c</code> to the buffer <code>B</code>
66098e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
66108e3e3a7aSWarner Losh
66118e3e3a7aSWarner Losh
66128e3e3a7aSWarner Losh
66138e3e3a7aSWarner Losh
66148e3e3a7aSWarner Losh
66150495ed39SKyle Evans<hr><h3><a name="luaL_addgsub"><code>luaL_addgsub</code></a></h3><p>
66168c784bb8SWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span>
66170495ed39SKyle Evans<pre>const void luaL_addgsub (luaL_Buffer *B, const char *s,
66180495ed39SKyle Evans                         const char *p, const char *r);</pre>
66190495ed39SKyle Evans
66200495ed39SKyle Evans<p>
66210495ed39SKyle 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>),
66220495ed39SKyle Evansreplacing any occurrence of the string <code>p</code>
66230495ed39SKyle Evanswith the string <code>r</code>.
66240495ed39SKyle Evans
66250495ed39SKyle Evans
66260495ed39SKyle Evans
66270495ed39SKyle Evans
66280495ed39SKyle Evans
66298e3e3a7aSWarner Losh<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p>
66308e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span>
66318e3e3a7aSWarner Losh<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre>
66328e3e3a7aSWarner Losh
66338e3e3a7aSWarner Losh<p>
66348e3e3a7aSWarner LoshAdds the string pointed to by <code>s</code> with length <code>l</code> to
66358e3e3a7aSWarner Loshthe buffer <code>B</code>
66368e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
66378e3e3a7aSWarner LoshThe string can contain embedded zeros.
66388e3e3a7aSWarner Losh
66398e3e3a7aSWarner Losh
66408e3e3a7aSWarner Losh
66418e3e3a7aSWarner Losh
66428e3e3a7aSWarner Losh
66438e3e3a7aSWarner Losh<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p>
66448e3e3a7aSWarner Losh<span class="apii">[-?, +?, &ndash;]</span>
66458e3e3a7aSWarner Losh<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre>
66468e3e3a7aSWarner Losh
66478e3e3a7aSWarner Losh<p>
66480495ed39SKyle EvansAdds to the buffer <code>B</code>
66498e3e3a7aSWarner Losha string of length <code>n</code> previously copied to the
66508e3e3a7aSWarner Loshbuffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>).
66518e3e3a7aSWarner Losh
66528e3e3a7aSWarner Losh
66538e3e3a7aSWarner Losh
66548e3e3a7aSWarner Losh
66558e3e3a7aSWarner Losh
66568e3e3a7aSWarner Losh<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p>
66578e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span>
66588e3e3a7aSWarner Losh<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre>
66598e3e3a7aSWarner Losh
66608e3e3a7aSWarner Losh<p>
66618e3e3a7aSWarner LoshAdds the zero-terminated string pointed to by <code>s</code>
66628e3e3a7aSWarner Loshto the buffer <code>B</code>
66638e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
66648e3e3a7aSWarner Losh
66658e3e3a7aSWarner Losh
66668e3e3a7aSWarner Losh
66678e3e3a7aSWarner Losh
66688e3e3a7aSWarner Losh
66698e3e3a7aSWarner Losh<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p>
66708c784bb8SWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span>
66718e3e3a7aSWarner Losh<pre>void luaL_addvalue (luaL_Buffer *B);</pre>
66728e3e3a7aSWarner Losh
66738e3e3a7aSWarner Losh<p>
66740495ed39SKyle EvansAdds the value on the top of the stack
66758e3e3a7aSWarner Loshto the buffer <code>B</code>
66768e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
66778e3e3a7aSWarner LoshPops the value.
66788e3e3a7aSWarner Losh
66798e3e3a7aSWarner Losh
66808e3e3a7aSWarner Losh<p>
66818e3e3a7aSWarner LoshThis is the only function on string buffers that can (and must)
66828e3e3a7aSWarner Loshbe called with an extra element on the stack,
66838e3e3a7aSWarner Loshwhich is the value to be added to the buffer.
66848e3e3a7aSWarner Losh
66858e3e3a7aSWarner Losh
66868e3e3a7aSWarner Losh
66878e3e3a7aSWarner Losh
66888e3e3a7aSWarner Losh
66898e3e3a7aSWarner Losh<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p>
66908e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
66918e3e3a7aSWarner Losh<pre>void luaL_argcheck (lua_State *L,
66928e3e3a7aSWarner Losh                    int cond,
66938e3e3a7aSWarner Losh                    int arg,
66948e3e3a7aSWarner Losh                    const char *extramsg);</pre>
66958e3e3a7aSWarner Losh
66968e3e3a7aSWarner Losh<p>
66978e3e3a7aSWarner LoshChecks whether <code>cond</code> is true.
66988e3e3a7aSWarner LoshIf it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>).
66998e3e3a7aSWarner Losh
67008e3e3a7aSWarner Losh
67018e3e3a7aSWarner Losh
67028e3e3a7aSWarner Losh
67038e3e3a7aSWarner Losh
67048e3e3a7aSWarner Losh<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p>
67058e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
67068e3e3a7aSWarner Losh<pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre>
67078e3e3a7aSWarner Losh
67088e3e3a7aSWarner Losh<p>
67098e3e3a7aSWarner LoshRaises an error reporting a problem with argument <code>arg</code>
67108e3e3a7aSWarner Loshof the C&nbsp;function that called it,
67118e3e3a7aSWarner Loshusing a standard message
67128e3e3a7aSWarner Loshthat includes <code>extramsg</code> as a comment:
67138e3e3a7aSWarner Losh
67148e3e3a7aSWarner Losh<pre>
67158e3e3a7aSWarner Losh     bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>)
67168e3e3a7aSWarner Losh</pre><p>
67178e3e3a7aSWarner LoshThis function never returns.
67188e3e3a7aSWarner Losh
67198e3e3a7aSWarner Losh
67208e3e3a7aSWarner Losh
67218e3e3a7aSWarner Losh
67228e3e3a7aSWarner Losh
67230495ed39SKyle Evans<hr><h3><a name="luaL_argexpected"><code>luaL_argexpected</code></a></h3><p>
67240495ed39SKyle Evans<span class="apii">[-0, +0, <em>v</em>]</span>
67250495ed39SKyle Evans<pre>void luaL_argexpected (lua_State *L,
67260495ed39SKyle Evans                       int cond,
67270495ed39SKyle Evans                       int arg,
67280495ed39SKyle Evans                       const char *tname);</pre>
67290495ed39SKyle Evans
67300495ed39SKyle Evans<p>
67310495ed39SKyle EvansChecks whether <code>cond</code> is true.
67320495ed39SKyle EvansIf it is not, raises an error about the type of the argument <code>arg</code>
67330495ed39SKyle Evanswith a standard message (see <a href="#luaL_typeerror"><code>luaL_typeerror</code></a>).
67340495ed39SKyle Evans
67350495ed39SKyle Evans
67360495ed39SKyle Evans
67370495ed39SKyle Evans
67380495ed39SKyle Evans
67398e3e3a7aSWarner Losh<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3>
67408e3e3a7aSWarner Losh<pre>typedef struct luaL_Buffer luaL_Buffer;</pre>
67418e3e3a7aSWarner Losh
67428e3e3a7aSWarner Losh<p>
67438e3e3a7aSWarner LoshType for a <em>string buffer</em>.
67448e3e3a7aSWarner Losh
67458e3e3a7aSWarner Losh
67468e3e3a7aSWarner Losh<p>
67478e3e3a7aSWarner LoshA string buffer allows C&nbsp;code to build Lua strings piecemeal.
67488e3e3a7aSWarner LoshIts pattern of use is as follows:
67498e3e3a7aSWarner Losh
67508e3e3a7aSWarner Losh<ul>
67518e3e3a7aSWarner Losh
67528e3e3a7aSWarner Losh<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
67538e3e3a7aSWarner Losh
67548e3e3a7aSWarner Losh<li>Then initialize it with a call <code>luaL_buffinit(L, &amp;b)</code>.</li>
67558e3e3a7aSWarner Losh
67568e3e3a7aSWarner Losh<li>
67578e3e3a7aSWarner LoshThen add string pieces to the buffer calling any of
67588e3e3a7aSWarner Loshthe <code>luaL_add*</code> functions.
67598e3e3a7aSWarner Losh</li>
67608e3e3a7aSWarner Losh
67618e3e3a7aSWarner Losh<li>
67628e3e3a7aSWarner LoshFinish by calling <code>luaL_pushresult(&amp;b)</code>.
67638e3e3a7aSWarner LoshThis call leaves the final string on the top of the stack.
67648e3e3a7aSWarner Losh</li>
67658e3e3a7aSWarner Losh
67668e3e3a7aSWarner Losh</ul>
67678e3e3a7aSWarner Losh
67688e3e3a7aSWarner Losh<p>
67690495ed39SKyle EvansIf you know beforehand the maximum size of the resulting string,
67708e3e3a7aSWarner Loshyou can use the buffer like this:
67718e3e3a7aSWarner Losh
67728e3e3a7aSWarner Losh<ul>
67738e3e3a7aSWarner Losh
67748e3e3a7aSWarner Losh<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
67758e3e3a7aSWarner Losh
67768e3e3a7aSWarner Losh<li>Then initialize it and preallocate a space of
67778e3e3a7aSWarner Loshsize <code>sz</code> with a call <code>luaL_buffinitsize(L, &amp;b, sz)</code>.</li>
67788e3e3a7aSWarner Losh
67790495ed39SKyle Evans<li>Then produce the string into that space.</li>
67808e3e3a7aSWarner Losh
67818e3e3a7aSWarner Losh<li>
67828e3e3a7aSWarner LoshFinish by calling <code>luaL_pushresultsize(&amp;b, sz)</code>,
67838e3e3a7aSWarner Loshwhere <code>sz</code> is the total size of the resulting string
67840495ed39SKyle Evanscopied into that space (which may be less than or
67850495ed39SKyle Evansequal to the preallocated size).
67868e3e3a7aSWarner Losh</li>
67878e3e3a7aSWarner Losh
67888e3e3a7aSWarner Losh</ul>
67898e3e3a7aSWarner Losh
67908e3e3a7aSWarner Losh<p>
67918e3e3a7aSWarner LoshDuring its normal operation,
67928e3e3a7aSWarner Losha string buffer uses a variable number of stack slots.
67938e3e3a7aSWarner LoshSo, while using a buffer, you cannot assume that you know where
67948e3e3a7aSWarner Loshthe top of the stack is.
67958e3e3a7aSWarner LoshYou can use the stack between successive calls to buffer operations
67968e3e3a7aSWarner Loshas long as that use is balanced;
67978e3e3a7aSWarner Loshthat is,
67988e3e3a7aSWarner Loshwhen you call a buffer operation,
67998e3e3a7aSWarner Loshthe stack is at the same level
68008e3e3a7aSWarner Loshit was immediately after the previous buffer operation.
68018e3e3a7aSWarner Losh(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.)
68020495ed39SKyle EvansAfter calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>,
68030495ed39SKyle Evansthe stack is back to its level when the buffer was initialized,
68048e3e3a7aSWarner Loshplus the final string on its top.
68058e3e3a7aSWarner Losh
68068e3e3a7aSWarner Losh
68078e3e3a7aSWarner Losh
68088e3e3a7aSWarner Losh
68098e3e3a7aSWarner Losh
68100495ed39SKyle Evans<hr><h3><a name="luaL_buffaddr"><code>luaL_buffaddr</code></a></h3><p>
68110495ed39SKyle Evans<span class="apii">[-0, +0, &ndash;]</span>
68120495ed39SKyle Evans<pre>char *luaL_buffaddr (luaL_Buffer *B);</pre>
68130495ed39SKyle Evans
68140495ed39SKyle Evans<p>
68150495ed39SKyle EvansReturns the address of the current content of buffer <code>B</code>
68160495ed39SKyle Evans(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
68170495ed39SKyle EvansNote that any addition to the buffer may invalidate this address.
68180495ed39SKyle Evans
68190495ed39SKyle Evans
68200495ed39SKyle Evans
68210495ed39SKyle Evans
68220495ed39SKyle Evans
68238e3e3a7aSWarner Losh<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p>
68248c784bb8SWarner Losh<span class="apii">[-0, +?, &ndash;]</span>
68258e3e3a7aSWarner Losh<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre>
68268e3e3a7aSWarner Losh
68278e3e3a7aSWarner Losh<p>
68280495ed39SKyle EvansInitializes a buffer <code>B</code>
68290495ed39SKyle Evans(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
68308e3e3a7aSWarner LoshThis function does not allocate any space;
68310495ed39SKyle Evansthe buffer must be declared as a variable.
68320495ed39SKyle Evans
68330495ed39SKyle Evans
68340495ed39SKyle Evans
68350495ed39SKyle Evans
68360495ed39SKyle Evans
68370495ed39SKyle Evans<hr><h3><a name="luaL_bufflen"><code>luaL_bufflen</code></a></h3><p>
68380495ed39SKyle Evans<span class="apii">[-0, +0, &ndash;]</span>
68390495ed39SKyle Evans<pre>size_t luaL_bufflen (luaL_Buffer *B);</pre>
68400495ed39SKyle Evans
68410495ed39SKyle Evans<p>
68420495ed39SKyle EvansReturns the length of the current content of buffer <code>B</code>
68438e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
68448e3e3a7aSWarner Losh
68458e3e3a7aSWarner Losh
68468e3e3a7aSWarner Losh
68478e3e3a7aSWarner Losh
68488e3e3a7aSWarner Losh
68498e3e3a7aSWarner Losh<hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p>
68508e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span>
68518e3e3a7aSWarner Losh<pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre>
68528e3e3a7aSWarner Losh
68538e3e3a7aSWarner Losh<p>
68548e3e3a7aSWarner LoshEquivalent to the sequence
68558e3e3a7aSWarner Losh<a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>.
68568e3e3a7aSWarner Losh
68578e3e3a7aSWarner Losh
68588e3e3a7aSWarner Losh
68598e3e3a7aSWarner Losh
68608e3e3a7aSWarner Losh
68610495ed39SKyle Evans<hr><h3><a name="luaL_buffsub"><code>luaL_buffsub</code></a></h3><p>
68628c784bb8SWarner Losh<span class="apii">[-?, +?, &ndash;]</span>
68630495ed39SKyle Evans<pre>void luaL_buffsub (luaL_Buffer *B, int n);</pre>
68640495ed39SKyle Evans
68650495ed39SKyle Evans<p>
6866a9490b81SWarner LoshRemoves <code>n</code> bytes from the buffer <code>B</code>
68670495ed39SKyle Evans(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
68680495ed39SKyle EvansThe buffer must have at least that many bytes.
68690495ed39SKyle Evans
68700495ed39SKyle Evans
68710495ed39SKyle Evans
68720495ed39SKyle Evans
68730495ed39SKyle Evans
68748e3e3a7aSWarner Losh<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p>
68758e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), <em>e</em>]</span>
68768e3e3a7aSWarner Losh<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre>
68778e3e3a7aSWarner Losh
68788e3e3a7aSWarner Losh<p>
68798e3e3a7aSWarner LoshCalls a metamethod.
68808e3e3a7aSWarner Losh
68818e3e3a7aSWarner Losh
68828e3e3a7aSWarner Losh<p>
68838e3e3a7aSWarner LoshIf the object at index <code>obj</code> has a metatable and this
68848e3e3a7aSWarner Loshmetatable has a field <code>e</code>,
68858e3e3a7aSWarner Loshthis function calls this field passing the object as its only argument.
68868e3e3a7aSWarner LoshIn this case this function returns true and pushes onto the
68878e3e3a7aSWarner Loshstack the value returned by the call.
68888e3e3a7aSWarner LoshIf there is no metatable or no metamethod,
68890495ed39SKyle Evansthis function returns false without pushing any value on the stack.
68908e3e3a7aSWarner Losh
68918e3e3a7aSWarner Losh
68928e3e3a7aSWarner Losh
68938e3e3a7aSWarner Losh
68948e3e3a7aSWarner Losh
68958e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p>
68968e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
68978e3e3a7aSWarner Losh<pre>void luaL_checkany (lua_State *L, int arg);</pre>
68988e3e3a7aSWarner Losh
68998e3e3a7aSWarner Losh<p>
69008e3e3a7aSWarner LoshChecks whether the function has an argument
69018e3e3a7aSWarner Loshof any type (including <b>nil</b>) at position <code>arg</code>.
69028e3e3a7aSWarner Losh
69038e3e3a7aSWarner Losh
69048e3e3a7aSWarner Losh
69058e3e3a7aSWarner Losh
69068e3e3a7aSWarner Losh
69078e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p>
69088e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
69098e3e3a7aSWarner Losh<pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre>
69108e3e3a7aSWarner Losh
69118e3e3a7aSWarner Losh<p>
69128e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is an integer
69138e3e3a7aSWarner Losh(or can be converted to an integer)
69140495ed39SKyle Evansand returns this integer.
69158e3e3a7aSWarner Losh
69168e3e3a7aSWarner Losh
69178e3e3a7aSWarner Losh
69188e3e3a7aSWarner Losh
69198e3e3a7aSWarner Losh
69208e3e3a7aSWarner Losh<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p>
69218e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
69228e3e3a7aSWarner Losh<pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre>
69238e3e3a7aSWarner Losh
69248e3e3a7aSWarner Losh<p>
69258e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string
69268e3e3a7aSWarner Loshand returns this string;
69270495ed39SKyle Evansif <code>l</code> is not <code>NULL</code> fills its referent
69288e3e3a7aSWarner Loshwith the string's length.
69298e3e3a7aSWarner Losh
69308e3e3a7aSWarner Losh
69318e3e3a7aSWarner Losh<p>
69328e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
69338e3e3a7aSWarner Loshso all conversions and caveats of that function apply here.
69348e3e3a7aSWarner Losh
69358e3e3a7aSWarner Losh
69368e3e3a7aSWarner Losh
69378e3e3a7aSWarner Losh
69388e3e3a7aSWarner Losh
69398e3e3a7aSWarner Losh<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p>
69408e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
69418e3e3a7aSWarner Losh<pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre>
69428e3e3a7aSWarner Losh
69438e3e3a7aSWarner Losh<p>
69448e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a number
69450495ed39SKyle Evansand returns this number converted to a <code>lua_Number</code>.
69468e3e3a7aSWarner Losh
69478e3e3a7aSWarner Losh
69488e3e3a7aSWarner Losh
69498e3e3a7aSWarner Losh
69508e3e3a7aSWarner Losh
69518e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p>
69528e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
69538e3e3a7aSWarner Losh<pre>int luaL_checkoption (lua_State *L,
69548e3e3a7aSWarner Losh                      int arg,
69558e3e3a7aSWarner Losh                      const char *def,
69568e3e3a7aSWarner Losh                      const char *const lst[]);</pre>
69578e3e3a7aSWarner Losh
69588e3e3a7aSWarner Losh<p>
69598e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string and
69608e3e3a7aSWarner Loshsearches for this string in the array <code>lst</code>
69618e3e3a7aSWarner Losh(which must be NULL-terminated).
69628e3e3a7aSWarner LoshReturns the index in the array where the string was found.
69638e3e3a7aSWarner LoshRaises an error if the argument is not a string or
69648e3e3a7aSWarner Loshif the string cannot be found.
69658e3e3a7aSWarner Losh
69668e3e3a7aSWarner Losh
69678e3e3a7aSWarner Losh<p>
69688e3e3a7aSWarner LoshIf <code>def</code> is not <code>NULL</code>,
69698e3e3a7aSWarner Loshthe function uses <code>def</code> as a default value when
69708e3e3a7aSWarner Loshthere is no argument <code>arg</code> or when this argument is <b>nil</b>.
69718e3e3a7aSWarner Losh
69728e3e3a7aSWarner Losh
69738e3e3a7aSWarner Losh<p>
69748e3e3a7aSWarner LoshThis is a useful function for mapping strings to C&nbsp;enums.
69758e3e3a7aSWarner Losh(The usual convention in Lua libraries is
69768e3e3a7aSWarner Loshto use strings instead of numbers to select options.)
69778e3e3a7aSWarner Losh
69788e3e3a7aSWarner Losh
69798e3e3a7aSWarner Losh
69808e3e3a7aSWarner Losh
69818e3e3a7aSWarner Losh
69828e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p>
69838e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
69848e3e3a7aSWarner Losh<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre>
69858e3e3a7aSWarner Losh
69868e3e3a7aSWarner Losh<p>
69878e3e3a7aSWarner LoshGrows the stack size to <code>top + sz</code> elements,
69888e3e3a7aSWarner Loshraising an error if the stack cannot grow to that size.
69898e3e3a7aSWarner Losh<code>msg</code> is an additional text to go into the error message
69908e3e3a7aSWarner Losh(or <code>NULL</code> for no additional text).
69918e3e3a7aSWarner Losh
69928e3e3a7aSWarner Losh
69938e3e3a7aSWarner Losh
69948e3e3a7aSWarner Losh
69958e3e3a7aSWarner Losh
69968e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p>
69978e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
69988e3e3a7aSWarner Losh<pre>const char *luaL_checkstring (lua_State *L, int arg);</pre>
69998e3e3a7aSWarner Losh
70008e3e3a7aSWarner Losh<p>
70018e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string
70028e3e3a7aSWarner Loshand returns this string.
70038e3e3a7aSWarner Losh
70048e3e3a7aSWarner Losh
70058e3e3a7aSWarner Losh<p>
70068e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
70078e3e3a7aSWarner Loshso all conversions and caveats of that function apply here.
70088e3e3a7aSWarner Losh
70098e3e3a7aSWarner Losh
70108e3e3a7aSWarner Losh
70118e3e3a7aSWarner Losh
70128e3e3a7aSWarner Losh
70138e3e3a7aSWarner Losh<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p>
70148e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
70158e3e3a7aSWarner Losh<pre>void luaL_checktype (lua_State *L, int arg, int t);</pre>
70168e3e3a7aSWarner Losh
70178e3e3a7aSWarner Losh<p>
70188e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> has type <code>t</code>.
70198e3e3a7aSWarner LoshSee <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>.
70208e3e3a7aSWarner Losh
70218e3e3a7aSWarner Losh
70228e3e3a7aSWarner Losh
70238e3e3a7aSWarner Losh
70248e3e3a7aSWarner Losh
70258e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p>
70268e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
70278e3e3a7aSWarner Losh<pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre>
70288e3e3a7aSWarner Losh
70298e3e3a7aSWarner Losh<p>
70308e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a userdata
70318e3e3a7aSWarner Loshof the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and
70320495ed39SKyle Evansreturns the userdata's memory-block address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>).
70338e3e3a7aSWarner Losh
70348e3e3a7aSWarner Losh
70358e3e3a7aSWarner Losh
70368e3e3a7aSWarner Losh
70378e3e3a7aSWarner Losh
70388e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p>
70398e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
70408e3e3a7aSWarner Losh<pre>void luaL_checkversion (lua_State *L);</pre>
70418e3e3a7aSWarner Losh
70428e3e3a7aSWarner Losh<p>
70430495ed39SKyle EvansChecks whether the code making the call and the Lua library being called
70440495ed39SKyle Evansare using the same version of Lua and the same numeric types.
70458e3e3a7aSWarner Losh
70468e3e3a7aSWarner Losh
70478e3e3a7aSWarner Losh
70488e3e3a7aSWarner Losh
70498e3e3a7aSWarner Losh
70508e3e3a7aSWarner Losh<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p>
70510495ed39SKyle Evans<span class="apii">[-0, +?, <em>m</em>]</span>
70528e3e3a7aSWarner Losh<pre>int luaL_dofile (lua_State *L, const char *filename);</pre>
70538e3e3a7aSWarner Losh
70548e3e3a7aSWarner Losh<p>
70558e3e3a7aSWarner LoshLoads and runs the given file.
70568e3e3a7aSWarner LoshIt is defined as the following macro:
70578e3e3a7aSWarner Losh
70588e3e3a7aSWarner Losh<pre>
70598e3e3a7aSWarner Losh     (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
70608e3e3a7aSWarner Losh</pre><p>
7061a9490b81SWarner LoshIt returns&nbsp;0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) if there are no errors,
7062a9490b81SWarner Loshor 1 in case of errors.
70638e3e3a7aSWarner Losh
70648e3e3a7aSWarner Losh
70658e3e3a7aSWarner Losh
70668e3e3a7aSWarner Losh
70678e3e3a7aSWarner Losh
70688e3e3a7aSWarner Losh<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p>
70698e3e3a7aSWarner Losh<span class="apii">[-0, +?, &ndash;]</span>
70708e3e3a7aSWarner Losh<pre>int luaL_dostring (lua_State *L, const char *str);</pre>
70718e3e3a7aSWarner Losh
70728e3e3a7aSWarner Losh<p>
70738e3e3a7aSWarner LoshLoads and runs the given string.
70748e3e3a7aSWarner LoshIt is defined as the following macro:
70758e3e3a7aSWarner Losh
70768e3e3a7aSWarner Losh<pre>
70778e3e3a7aSWarner Losh     (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
70788e3e3a7aSWarner Losh</pre><p>
7079a9490b81SWarner LoshIt returns&nbsp;0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) if there are no errors,
7080a9490b81SWarner Loshor 1 in case of errors.
70818e3e3a7aSWarner Losh
70828e3e3a7aSWarner Losh
70838e3e3a7aSWarner Losh
70848e3e3a7aSWarner Losh
70858e3e3a7aSWarner Losh
70868e3e3a7aSWarner Losh<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p>
70878e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
70888e3e3a7aSWarner Losh<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre>
70898e3e3a7aSWarner Losh
70908e3e3a7aSWarner Losh<p>
70918e3e3a7aSWarner LoshRaises an error.
70928e3e3a7aSWarner LoshThe error message format is given by <code>fmt</code>
70938e3e3a7aSWarner Loshplus any extra arguments,
70948e3e3a7aSWarner Loshfollowing the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>.
70958e3e3a7aSWarner LoshIt also adds at the beginning of the message the file name and
70968e3e3a7aSWarner Loshthe line number where the error occurred,
70978e3e3a7aSWarner Loshif this information is available.
70988e3e3a7aSWarner Losh
70998e3e3a7aSWarner Losh
71008e3e3a7aSWarner Losh<p>
71018e3e3a7aSWarner LoshThis function never returns,
71028e3e3a7aSWarner Loshbut it is an idiom to use it in C&nbsp;functions
71038e3e3a7aSWarner Loshas <code>return luaL_error(<em>args</em>)</code>.
71048e3e3a7aSWarner Losh
71058e3e3a7aSWarner Losh
71068e3e3a7aSWarner Losh
71078e3e3a7aSWarner Losh
71088e3e3a7aSWarner Losh
71098e3e3a7aSWarner Losh<hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p>
71108e3e3a7aSWarner Losh<span class="apii">[-0, +3, <em>m</em>]</span>
71118e3e3a7aSWarner Losh<pre>int luaL_execresult (lua_State *L, int stat);</pre>
71128e3e3a7aSWarner Losh
71138e3e3a7aSWarner Losh<p>
71148e3e3a7aSWarner LoshThis function produces the return values for
71158e3e3a7aSWarner Loshprocess-related functions in the standard library
71168e3e3a7aSWarner Losh(<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>).
71178e3e3a7aSWarner Losh
71188e3e3a7aSWarner Losh
71198e3e3a7aSWarner Losh
71208e3e3a7aSWarner Losh
71218e3e3a7aSWarner Losh
71228e3e3a7aSWarner Losh<hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p>
71238e3e3a7aSWarner Losh<span class="apii">[-0, +(1|3), <em>m</em>]</span>
71248e3e3a7aSWarner Losh<pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre>
71258e3e3a7aSWarner Losh
71268e3e3a7aSWarner Losh<p>
71278e3e3a7aSWarner LoshThis function produces the return values for
71288e3e3a7aSWarner Loshfile-related functions in the standard library
71298e3e3a7aSWarner 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.).
71308e3e3a7aSWarner Losh
71318e3e3a7aSWarner Losh
71328e3e3a7aSWarner Losh
71338e3e3a7aSWarner Losh
71348e3e3a7aSWarner Losh
71358e3e3a7aSWarner Losh<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p>
71368e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), <em>m</em>]</span>
71378e3e3a7aSWarner Losh<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre>
71388e3e3a7aSWarner Losh
71398e3e3a7aSWarner Losh<p>
71408e3e3a7aSWarner LoshPushes onto the stack the field <code>e</code> from the metatable
7141e112e9d2SKyle Evansof the object at index <code>obj</code> and returns the type of the pushed value.
71428e3e3a7aSWarner LoshIf the object does not have a metatable,
71438e3e3a7aSWarner Loshor if the metatable does not have this field,
71448e3e3a7aSWarner Loshpushes nothing and returns <code>LUA_TNIL</code>.
71458e3e3a7aSWarner Losh
71468e3e3a7aSWarner Losh
71478e3e3a7aSWarner Losh
71488e3e3a7aSWarner Losh
71498e3e3a7aSWarner Losh
71508e3e3a7aSWarner Losh<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p>
71518e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
71528e3e3a7aSWarner Losh<pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre>
71538e3e3a7aSWarner Losh
71548e3e3a7aSWarner Losh<p>
71550495ed39SKyle EvansPushes onto the stack the metatable associated with the name <code>tname</code>
71560495ed39SKyle Evansin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>),
71570495ed39SKyle Evansor <b>nil</b> if there is no metatable associated with that name.
71588e3e3a7aSWarner LoshReturns the type of the pushed value.
71598e3e3a7aSWarner Losh
71608e3e3a7aSWarner Losh
71618e3e3a7aSWarner Losh
71628e3e3a7aSWarner Losh
71638e3e3a7aSWarner Losh
71648e3e3a7aSWarner Losh<hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p>
71658e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span>
71668e3e3a7aSWarner Losh<pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre>
71678e3e3a7aSWarner Losh
71688e3e3a7aSWarner Losh<p>
71698e3e3a7aSWarner LoshEnsures that the value <code>t[fname]</code>,
71708e3e3a7aSWarner Loshwhere <code>t</code> is the value at index <code>idx</code>,
71718e3e3a7aSWarner Loshis a table,
71728e3e3a7aSWarner Loshand pushes that table onto the stack.
71738e3e3a7aSWarner LoshReturns true if it finds a previous table there
71748e3e3a7aSWarner Loshand false if it creates a new table.
71758e3e3a7aSWarner Losh
71768e3e3a7aSWarner Losh
71778e3e3a7aSWarner Losh
71788e3e3a7aSWarner Losh
71798e3e3a7aSWarner Losh
71808e3e3a7aSWarner Losh<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p>
71818e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
71828e3e3a7aSWarner Losh<pre>const char *luaL_gsub (lua_State *L,
71838e3e3a7aSWarner Losh                       const char *s,
71848e3e3a7aSWarner Losh                       const char *p,
71858e3e3a7aSWarner Losh                       const char *r);</pre>
71868e3e3a7aSWarner Losh
71878e3e3a7aSWarner Losh<p>
71880495ed39SKyle EvansCreates a copy of string <code>s</code>,
71890495ed39SKyle Evansreplacing any occurrence of the string <code>p</code>
71908e3e3a7aSWarner Loshwith the string <code>r</code>.
71918e3e3a7aSWarner LoshPushes the resulting string on the stack and returns it.
71928e3e3a7aSWarner Losh
71938e3e3a7aSWarner Losh
71948e3e3a7aSWarner Losh
71958e3e3a7aSWarner Losh
71968e3e3a7aSWarner Losh
71978e3e3a7aSWarner Losh<hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p>
71988e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span>
71998e3e3a7aSWarner Losh<pre>lua_Integer luaL_len (lua_State *L, int index);</pre>
72008e3e3a7aSWarner Losh
72018e3e3a7aSWarner Losh<p>
72028e3e3a7aSWarner LoshReturns the "length" of the value at the given index
72038e3e3a7aSWarner Loshas a number;
72048e3e3a7aSWarner Loshit is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">&sect;3.4.7</a>).
72058e3e3a7aSWarner LoshRaises an error if the result of the operation is not an integer.
72060495ed39SKyle Evans(This case can only happen through metamethods.)
72078e3e3a7aSWarner Losh
72088e3e3a7aSWarner Losh
72098e3e3a7aSWarner Losh
72108e3e3a7aSWarner Losh
72118e3e3a7aSWarner Losh
72128e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p>
72138e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
72148e3e3a7aSWarner Losh<pre>int luaL_loadbuffer (lua_State *L,
72158e3e3a7aSWarner Losh                     const char *buff,
72168e3e3a7aSWarner Losh                     size_t sz,
72178e3e3a7aSWarner Losh                     const char *name);</pre>
72188e3e3a7aSWarner Losh
72198e3e3a7aSWarner Losh<p>
72208e3e3a7aSWarner LoshEquivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>.
72218e3e3a7aSWarner Losh
72228e3e3a7aSWarner Losh
72238e3e3a7aSWarner Losh
72248e3e3a7aSWarner Losh
72258e3e3a7aSWarner Losh
72268e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p>
72278e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
72288e3e3a7aSWarner Losh<pre>int luaL_loadbufferx (lua_State *L,
72298e3e3a7aSWarner Losh                      const char *buff,
72308e3e3a7aSWarner Losh                      size_t sz,
72318e3e3a7aSWarner Losh                      const char *name,
72328e3e3a7aSWarner Losh                      const char *mode);</pre>
72338e3e3a7aSWarner Losh
72348e3e3a7aSWarner Losh<p>
72358e3e3a7aSWarner LoshLoads a buffer as a Lua chunk.
72368e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the
72378e3e3a7aSWarner Loshbuffer pointed to by <code>buff</code> with size <code>sz</code>.
72388e3e3a7aSWarner Losh
72398e3e3a7aSWarner Losh
72408e3e3a7aSWarner Losh<p>
72418e3e3a7aSWarner LoshThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
72428e3e3a7aSWarner Losh<code>name</code> is the chunk name,
72438e3e3a7aSWarner Loshused for debug information and error messages.
72440495ed39SKyle EvansThe string <code>mode</code> works as in the function <a href="#lua_load"><code>lua_load</code></a>.
72458e3e3a7aSWarner Losh
72468e3e3a7aSWarner Losh
72478e3e3a7aSWarner Losh
72488e3e3a7aSWarner Losh
72498e3e3a7aSWarner Losh
72508e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p>
72518e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
72528e3e3a7aSWarner Losh<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre>
72538e3e3a7aSWarner Losh
72548e3e3a7aSWarner Losh<p>
72558e3e3a7aSWarner LoshEquivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>.
72568e3e3a7aSWarner Losh
72578e3e3a7aSWarner Losh
72588e3e3a7aSWarner Losh
72598e3e3a7aSWarner Losh
72608e3e3a7aSWarner Losh
72618e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p>
72628e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
72638e3e3a7aSWarner Losh<pre>int luaL_loadfilex (lua_State *L, const char *filename,
72648e3e3a7aSWarner Losh                                            const char *mode);</pre>
72658e3e3a7aSWarner Losh
72668e3e3a7aSWarner Losh<p>
72678e3e3a7aSWarner LoshLoads a file as a Lua chunk.
72688e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file
72698e3e3a7aSWarner Loshnamed <code>filename</code>.
72708e3e3a7aSWarner LoshIf <code>filename</code> is <code>NULL</code>,
72718e3e3a7aSWarner Loshthen it loads from the standard input.
72728e3e3a7aSWarner LoshThe first line in the file is ignored if it starts with a <code>#</code>.
72738e3e3a7aSWarner Losh
72748e3e3a7aSWarner Losh
72758e3e3a7aSWarner Losh<p>
72760495ed39SKyle EvansThe string <code>mode</code> works as in the function <a href="#lua_load"><code>lua_load</code></a>.
72778e3e3a7aSWarner Losh
72788e3e3a7aSWarner Losh
72798e3e3a7aSWarner Losh<p>
72800495ed39SKyle EvansThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>
72810495ed39SKyle Evansor <a href="#pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> for file-related errors.
72828e3e3a7aSWarner Losh
72838e3e3a7aSWarner Losh
72848e3e3a7aSWarner Losh<p>
72858e3e3a7aSWarner LoshAs <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
72868e3e3a7aSWarner Loshit does not run it.
72878e3e3a7aSWarner Losh
72888e3e3a7aSWarner Losh
72898e3e3a7aSWarner Losh
72908e3e3a7aSWarner Losh
72918e3e3a7aSWarner Losh
72928e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p>
72938e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
72948e3e3a7aSWarner Losh<pre>int luaL_loadstring (lua_State *L, const char *s);</pre>
72958e3e3a7aSWarner Losh
72968e3e3a7aSWarner Losh<p>
72978e3e3a7aSWarner LoshLoads a string as a Lua chunk.
72988e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in
72998e3e3a7aSWarner Loshthe zero-terminated string <code>s</code>.
73008e3e3a7aSWarner Losh
73018e3e3a7aSWarner Losh
73028e3e3a7aSWarner Losh<p>
73038e3e3a7aSWarner LoshThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
73048e3e3a7aSWarner Losh
73058e3e3a7aSWarner Losh
73068e3e3a7aSWarner Losh<p>
73078e3e3a7aSWarner LoshAlso as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
73088e3e3a7aSWarner Loshit does not run it.
73098e3e3a7aSWarner Losh
73108e3e3a7aSWarner Losh
73118e3e3a7aSWarner Losh
73128e3e3a7aSWarner Losh
73138e3e3a7aSWarner Losh
73148e3e3a7aSWarner Losh<hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p>
73158e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
73168e3e3a7aSWarner Losh<pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre>
73178e3e3a7aSWarner Losh
73188e3e3a7aSWarner Losh<p>
73198e3e3a7aSWarner LoshCreates a new table and registers there
73200495ed39SKyle Evansthe functions in the list <code>l</code>.
73218e3e3a7aSWarner Losh
73228e3e3a7aSWarner Losh
73238e3e3a7aSWarner Losh<p>
73248e3e3a7aSWarner LoshIt is implemented as the following macro:
73258e3e3a7aSWarner Losh
73268e3e3a7aSWarner Losh<pre>
73278e3e3a7aSWarner Losh     (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
73288e3e3a7aSWarner Losh</pre><p>
73298e3e3a7aSWarner LoshThe array <code>l</code> must be the actual array,
73308e3e3a7aSWarner Loshnot a pointer to it.
73318e3e3a7aSWarner Losh
73328e3e3a7aSWarner Losh
73338e3e3a7aSWarner Losh
73348e3e3a7aSWarner Losh
73358e3e3a7aSWarner Losh
73368e3e3a7aSWarner Losh<hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p>
73378e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
73388e3e3a7aSWarner Losh<pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre>
73398e3e3a7aSWarner Losh
73408e3e3a7aSWarner Losh<p>
73418e3e3a7aSWarner LoshCreates a new table with a size optimized
73428e3e3a7aSWarner Loshto store all entries in the array <code>l</code>
73438e3e3a7aSWarner Losh(but does not actually store them).
73448e3e3a7aSWarner LoshIt is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>
73458e3e3a7aSWarner Losh(see <a href="#luaL_newlib"><code>luaL_newlib</code></a>).
73468e3e3a7aSWarner Losh
73478e3e3a7aSWarner Losh
73488e3e3a7aSWarner Losh<p>
73498e3e3a7aSWarner LoshIt is implemented as a macro.
73508e3e3a7aSWarner LoshThe array <code>l</code> must be the actual array,
73518e3e3a7aSWarner Loshnot a pointer to it.
73528e3e3a7aSWarner Losh
73538e3e3a7aSWarner Losh
73548e3e3a7aSWarner Losh
73558e3e3a7aSWarner Losh
73568e3e3a7aSWarner Losh
73578e3e3a7aSWarner Losh<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p>
73588e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
73598e3e3a7aSWarner Losh<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre>
73608e3e3a7aSWarner Losh
73618e3e3a7aSWarner Losh<p>
73628e3e3a7aSWarner LoshIf the registry already has the key <code>tname</code>,
73638e3e3a7aSWarner Loshreturns 0.
73648e3e3a7aSWarner LoshOtherwise,
73658e3e3a7aSWarner Loshcreates a new table to be used as a metatable for userdata,
73668e3e3a7aSWarner Loshadds to this new table the pair <code>__name = tname</code>,
73678e3e3a7aSWarner Loshadds to the registry the pair <code>[tname] = new table</code>,
73688e3e3a7aSWarner Loshand returns 1.
73698e3e3a7aSWarner Losh
73708e3e3a7aSWarner Losh
73718e3e3a7aSWarner Losh<p>
73720495ed39SKyle EvansIn both cases,
73730495ed39SKyle Evansthe function pushes onto the stack the final value associated
73748e3e3a7aSWarner Loshwith <code>tname</code> in the registry.
73758e3e3a7aSWarner Losh
73768e3e3a7aSWarner Losh
73778e3e3a7aSWarner Losh
73788e3e3a7aSWarner Losh
73798e3e3a7aSWarner Losh
73808e3e3a7aSWarner Losh<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p>
73818e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
73828e3e3a7aSWarner Losh<pre>lua_State *luaL_newstate (void);</pre>
73838e3e3a7aSWarner Losh
73848e3e3a7aSWarner Losh<p>
73858e3e3a7aSWarner LoshCreates a new Lua state.
73868e3e3a7aSWarner LoshIt calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an
7387a9490b81SWarner Loshallocator based on the ISO&nbsp;C allocation functions
73880495ed39SKyle Evansand then sets a warning function and a panic function (see <a href="#4.4">&sect;4.4</a>)
73890495ed39SKyle Evansthat print messages to the standard error output.
73908e3e3a7aSWarner Losh
73918e3e3a7aSWarner Losh
73928e3e3a7aSWarner Losh<p>
73938e3e3a7aSWarner LoshReturns the new state,
73948e3e3a7aSWarner Loshor <code>NULL</code> if there is a memory allocation error.
73958e3e3a7aSWarner Losh
73968e3e3a7aSWarner Losh
73978e3e3a7aSWarner Losh
73988e3e3a7aSWarner Losh
73998e3e3a7aSWarner Losh
74008e3e3a7aSWarner Losh<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p>
74018e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span>
74028e3e3a7aSWarner Losh<pre>void luaL_openlibs (lua_State *L);</pre>
74038e3e3a7aSWarner Losh
74048e3e3a7aSWarner Losh<p>
74058e3e3a7aSWarner LoshOpens all standard Lua libraries into the given state.
74068e3e3a7aSWarner Losh
74078e3e3a7aSWarner Losh
74088e3e3a7aSWarner Losh
74098e3e3a7aSWarner Losh
74108e3e3a7aSWarner Losh
74118e3e3a7aSWarner Losh<hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p>
74120495ed39SKyle Evans<span class="apii">[-0, +0, &ndash;]</span>
74138e3e3a7aSWarner Losh<pre>T luaL_opt (L, func, arg, dflt);</pre>
74148e3e3a7aSWarner Losh
74158e3e3a7aSWarner Losh<p>
74168e3e3a7aSWarner LoshThis macro is defined as follows:
74178e3e3a7aSWarner Losh
74188e3e3a7aSWarner Losh<pre>
74198e3e3a7aSWarner Losh     (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))
74208e3e3a7aSWarner Losh</pre><p>
74218e3e3a7aSWarner LoshIn words, if the argument <code>arg</code> is nil or absent,
74228e3e3a7aSWarner Loshthe macro results in the default <code>dflt</code>.
74238e3e3a7aSWarner LoshOtherwise, it results in the result of calling <code>func</code>
74248e3e3a7aSWarner Loshwith the state <code>L</code> and the argument index <code>arg</code> as
7425e112e9d2SKyle Evansarguments.
74268e3e3a7aSWarner LoshNote that it evaluates the expression <code>dflt</code> only if needed.
74278e3e3a7aSWarner Losh
74288e3e3a7aSWarner Losh
74298e3e3a7aSWarner Losh
74308e3e3a7aSWarner Losh
74318e3e3a7aSWarner Losh
74328e3e3a7aSWarner Losh<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p>
74338e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
74348e3e3a7aSWarner Losh<pre>lua_Integer luaL_optinteger (lua_State *L,
74358e3e3a7aSWarner Losh                             int arg,
74368e3e3a7aSWarner Losh                             lua_Integer d);</pre>
74378e3e3a7aSWarner Losh
74388e3e3a7aSWarner Losh<p>
74398e3e3a7aSWarner LoshIf the function argument <code>arg</code> is an integer
74400495ed39SKyle Evans(or it is convertible to an integer),
74418e3e3a7aSWarner Loshreturns this integer.
74428e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>,
74438e3e3a7aSWarner Loshreturns <code>d</code>.
74448e3e3a7aSWarner LoshOtherwise, raises an error.
74458e3e3a7aSWarner Losh
74468e3e3a7aSWarner Losh
74478e3e3a7aSWarner Losh
74488e3e3a7aSWarner Losh
74498e3e3a7aSWarner Losh
74508e3e3a7aSWarner Losh<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p>
74518e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
74528e3e3a7aSWarner Losh<pre>const char *luaL_optlstring (lua_State *L,
74538e3e3a7aSWarner Losh                             int arg,
74548e3e3a7aSWarner Losh                             const char *d,
74558e3e3a7aSWarner Losh                             size_t *l);</pre>
74568e3e3a7aSWarner Losh
74578e3e3a7aSWarner Losh<p>
74588e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a string,
74598e3e3a7aSWarner Loshreturns this string.
74608e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>,
74618e3e3a7aSWarner Loshreturns <code>d</code>.
74628e3e3a7aSWarner LoshOtherwise, raises an error.
74638e3e3a7aSWarner Losh
74648e3e3a7aSWarner Losh
74658e3e3a7aSWarner Losh<p>
74668e3e3a7aSWarner LoshIf <code>l</code> is not <code>NULL</code>,
74670495ed39SKyle Evansfills its referent with the result's length.
74688e3e3a7aSWarner LoshIf the result is <code>NULL</code>
74698e3e3a7aSWarner Losh(only possible when returning <code>d</code> and <code>d == NULL</code>),
74708e3e3a7aSWarner Loshits length is considered zero.
74718e3e3a7aSWarner Losh
74728e3e3a7aSWarner Losh
74738e3e3a7aSWarner Losh<p>
74748e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
74758e3e3a7aSWarner Loshso all conversions and caveats of that function apply here.
74768e3e3a7aSWarner Losh
74778e3e3a7aSWarner Losh
74788e3e3a7aSWarner Losh
74798e3e3a7aSWarner Losh
74808e3e3a7aSWarner Losh
74818e3e3a7aSWarner Losh<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p>
74828e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
74838e3e3a7aSWarner Losh<pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre>
74848e3e3a7aSWarner Losh
74858e3e3a7aSWarner Losh<p>
74868e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a number,
74870495ed39SKyle Evansreturns this number as a <code>lua_Number</code>.
74888e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>,
74898e3e3a7aSWarner Loshreturns <code>d</code>.
74908e3e3a7aSWarner LoshOtherwise, raises an error.
74918e3e3a7aSWarner Losh
74928e3e3a7aSWarner Losh
74938e3e3a7aSWarner Losh
74948e3e3a7aSWarner Losh
74958e3e3a7aSWarner Losh
74968e3e3a7aSWarner Losh<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p>
74978e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
74988e3e3a7aSWarner Losh<pre>const char *luaL_optstring (lua_State *L,
74998e3e3a7aSWarner Losh                            int arg,
75008e3e3a7aSWarner Losh                            const char *d);</pre>
75018e3e3a7aSWarner Losh
75028e3e3a7aSWarner Losh<p>
75038e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a string,
75048e3e3a7aSWarner Loshreturns this string.
75058e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>,
75068e3e3a7aSWarner Loshreturns <code>d</code>.
75078e3e3a7aSWarner LoshOtherwise, raises an error.
75088e3e3a7aSWarner Losh
75098e3e3a7aSWarner Losh
75108e3e3a7aSWarner Losh
75118e3e3a7aSWarner Losh
75128e3e3a7aSWarner Losh
75138e3e3a7aSWarner Losh<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p>
75148e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span>
75158e3e3a7aSWarner Losh<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre>
75168e3e3a7aSWarner Losh
75178e3e3a7aSWarner Losh<p>
75188e3e3a7aSWarner LoshEquivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>
75198e3e3a7aSWarner Loshwith the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>.
75208e3e3a7aSWarner Losh
75218e3e3a7aSWarner Losh
75228e3e3a7aSWarner Losh
75238e3e3a7aSWarner Losh
75248e3e3a7aSWarner Losh
75258e3e3a7aSWarner Losh<hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p>
75268e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span>
75278e3e3a7aSWarner Losh<pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre>
75288e3e3a7aSWarner Losh
75298e3e3a7aSWarner Losh<p>
75308e3e3a7aSWarner LoshReturns an address to a space of size <code>sz</code>
75318e3e3a7aSWarner Loshwhere you can copy a string to be added to buffer <code>B</code>
75328e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
75338e3e3a7aSWarner LoshAfter copying the string into this space you must call
75348e3e3a7aSWarner Losh<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add
75358e3e3a7aSWarner Loshit to the buffer.
75368e3e3a7aSWarner Losh
75378e3e3a7aSWarner Losh
75388e3e3a7aSWarner Losh
75398e3e3a7aSWarner Losh
75408e3e3a7aSWarner Losh
75410495ed39SKyle Evans<hr><h3><a name="luaL_pushfail"><code>luaL_pushfail</code></a></h3><p>
75420495ed39SKyle Evans<span class="apii">[-0, +1, &ndash;]</span>
75430495ed39SKyle Evans<pre>void luaL_pushfail (lua_State *L);</pre>
75440495ed39SKyle Evans
75450495ed39SKyle Evans<p>
75460495ed39SKyle EvansPushes the <b>fail</b> value onto the stack (see <a href="#6">&sect;6</a>).
75470495ed39SKyle Evans
75480495ed39SKyle Evans
75490495ed39SKyle Evans
75500495ed39SKyle Evans
75510495ed39SKyle Evans
75528e3e3a7aSWarner Losh<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p>
75538e3e3a7aSWarner Losh<span class="apii">[-?, +1, <em>m</em>]</span>
75548e3e3a7aSWarner Losh<pre>void luaL_pushresult (luaL_Buffer *B);</pre>
75558e3e3a7aSWarner Losh
75568e3e3a7aSWarner Losh<p>
75578e3e3a7aSWarner LoshFinishes the use of buffer <code>B</code> leaving the final string on
75588e3e3a7aSWarner Loshthe top of the stack.
75598e3e3a7aSWarner Losh
75608e3e3a7aSWarner Losh
75618e3e3a7aSWarner Losh
75628e3e3a7aSWarner Losh
75638e3e3a7aSWarner Losh
75648e3e3a7aSWarner Losh<hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p>
75658e3e3a7aSWarner Losh<span class="apii">[-?, +1, <em>m</em>]</span>
75668e3e3a7aSWarner Losh<pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre>
75678e3e3a7aSWarner Losh
75688e3e3a7aSWarner Losh<p>
75698e3e3a7aSWarner LoshEquivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>.
75708e3e3a7aSWarner Losh
75718e3e3a7aSWarner Losh
75728e3e3a7aSWarner Losh
75738e3e3a7aSWarner Losh
75748e3e3a7aSWarner Losh
75758e3e3a7aSWarner Losh<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p>
75768e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span>
75778e3e3a7aSWarner Losh<pre>int luaL_ref (lua_State *L, int t);</pre>
75788e3e3a7aSWarner Losh
75798e3e3a7aSWarner Losh<p>
75808e3e3a7aSWarner LoshCreates and returns a <em>reference</em>,
75818e3e3a7aSWarner Loshin the table at index <code>t</code>,
75820495ed39SKyle Evansfor the object on the top of the stack (and pops the object).
75838e3e3a7aSWarner Losh
75848e3e3a7aSWarner Losh
75858e3e3a7aSWarner Losh<p>
75868e3e3a7aSWarner LoshA reference is a unique integer key.
75870495ed39SKyle EvansAs long as you do not manually add integer keys into the table <code>t</code>,
75888e3e3a7aSWarner Losh<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns.
75890495ed39SKyle EvansYou can retrieve an object referred by the reference <code>r</code>
75908e3e3a7aSWarner Loshby calling <code>lua_rawgeti(L, t, r)</code>.
75910495ed39SKyle EvansThe function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference.
75928e3e3a7aSWarner Losh
75938e3e3a7aSWarner Losh
75948e3e3a7aSWarner Losh<p>
75950495ed39SKyle EvansIf the object on the top of the stack is <b>nil</b>,
75968e3e3a7aSWarner Losh<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>.
75978e3e3a7aSWarner LoshThe constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different
75988e3e3a7aSWarner Loshfrom any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>.
75998e3e3a7aSWarner Losh
76008e3e3a7aSWarner Losh
76018e3e3a7aSWarner Losh
76028e3e3a7aSWarner Losh
76038e3e3a7aSWarner Losh
76048e3e3a7aSWarner Losh<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3>
76058e3e3a7aSWarner Losh<pre>typedef struct luaL_Reg {
76068e3e3a7aSWarner Losh  const char *name;
76078e3e3a7aSWarner Losh  lua_CFunction func;
76088e3e3a7aSWarner Losh} luaL_Reg;</pre>
76098e3e3a7aSWarner Losh
76108e3e3a7aSWarner Losh<p>
76118e3e3a7aSWarner LoshType for arrays of functions to be registered by
76128e3e3a7aSWarner Losh<a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>.
76138e3e3a7aSWarner Losh<code>name</code> is the function name and <code>func</code> is a pointer to
76148e3e3a7aSWarner Loshthe function.
76158e3e3a7aSWarner LoshAny array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry
76168e3e3a7aSWarner Loshin which both <code>name</code> and <code>func</code> are <code>NULL</code>.
76178e3e3a7aSWarner Losh
76188e3e3a7aSWarner Losh
76198e3e3a7aSWarner Losh
76208e3e3a7aSWarner Losh
76218e3e3a7aSWarner Losh
76228e3e3a7aSWarner Losh<hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p>
76238e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span>
76248e3e3a7aSWarner Losh<pre>void luaL_requiref (lua_State *L, const char *modname,
76258e3e3a7aSWarner Losh                    lua_CFunction openf, int glb);</pre>
76268e3e3a7aSWarner Losh
76278e3e3a7aSWarner Losh<p>
76280495ed39SKyle EvansIf <code>package.loaded[modname]</code> is not true,
76290495ed39SKyle Evanscalls the function <code>openf</code> with the string <code>modname</code> as an argument
76300495ed39SKyle Evansand sets the call result to <code>package.loaded[modname]</code>,
76318e3e3a7aSWarner Loshas if that function has been called through <a href="#pdf-require"><code>require</code></a>.
76328e3e3a7aSWarner Losh
76338e3e3a7aSWarner Losh
76348e3e3a7aSWarner Losh<p>
76358e3e3a7aSWarner LoshIf <code>glb</code> is true,
76360495ed39SKyle Evansalso stores the module into the global <code>modname</code>.
76378e3e3a7aSWarner Losh
76388e3e3a7aSWarner Losh
76398e3e3a7aSWarner Losh<p>
76408e3e3a7aSWarner LoshLeaves a copy of the module on the stack.
76418e3e3a7aSWarner Losh
76428e3e3a7aSWarner Losh
76438e3e3a7aSWarner Losh
76448e3e3a7aSWarner Losh
76458e3e3a7aSWarner Losh
76468e3e3a7aSWarner Losh<hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p>
76478e3e3a7aSWarner Losh<span class="apii">[-nup, +0, <em>m</em>]</span>
76488e3e3a7aSWarner Losh<pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre>
76498e3e3a7aSWarner Losh
76508e3e3a7aSWarner Losh<p>
76518e3e3a7aSWarner LoshRegisters all functions in the array <code>l</code>
76528e3e3a7aSWarner Losh(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack
76538e3e3a7aSWarner Losh(below optional upvalues, see next).
76548e3e3a7aSWarner Losh
76558e3e3a7aSWarner Losh
76568e3e3a7aSWarner Losh<p>
76578e3e3a7aSWarner LoshWhen <code>nup</code> is not zero,
76580495ed39SKyle Evansall functions are created with <code>nup</code> upvalues,
76590495ed39SKyle Evansinitialized with copies of the <code>nup</code> values
76600495ed39SKyle Evanspreviously pushed on the stack
76618e3e3a7aSWarner Loshon top of the library table.
76628e3e3a7aSWarner LoshThese values are popped from the stack after the registration.
76638e3e3a7aSWarner Losh
76648e3e3a7aSWarner Losh
76658c784bb8SWarner Losh<p>
76668c784bb8SWarner LoshA function with a <code>NULL</code> value represents a placeholder,
76678c784bb8SWarner Loshwhich is filled with <b>false</b>.
76688c784bb8SWarner Losh
76698c784bb8SWarner Losh
76708e3e3a7aSWarner Losh
76718e3e3a7aSWarner Losh
76728e3e3a7aSWarner Losh
76738e3e3a7aSWarner Losh<hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p>
76748e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
76758e3e3a7aSWarner Losh<pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre>
76768e3e3a7aSWarner Losh
76778e3e3a7aSWarner Losh<p>
76780495ed39SKyle EvansSets the metatable of the object on the top of the stack
76798e3e3a7aSWarner Loshas the metatable associated with name <code>tname</code>
76808e3e3a7aSWarner Loshin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
76818e3e3a7aSWarner Losh
76828e3e3a7aSWarner Losh
76838e3e3a7aSWarner Losh
76848e3e3a7aSWarner Losh
76858e3e3a7aSWarner Losh
76868e3e3a7aSWarner Losh<hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3>
76878e3e3a7aSWarner Losh<pre>typedef struct luaL_Stream {
76888e3e3a7aSWarner Losh  FILE *f;
76898e3e3a7aSWarner Losh  lua_CFunction closef;
76908e3e3a7aSWarner Losh} luaL_Stream;</pre>
76918e3e3a7aSWarner Losh
76928e3e3a7aSWarner Losh<p>
76930495ed39SKyle EvansThe standard representation for file handles
76940495ed39SKyle Evansused by the standard I/O library.
76958e3e3a7aSWarner Losh
76968e3e3a7aSWarner Losh
76978e3e3a7aSWarner Losh<p>
76988e3e3a7aSWarner LoshA file handle is implemented as a full userdata,
76998e3e3a7aSWarner Loshwith a metatable called <code>LUA_FILEHANDLE</code>
77008e3e3a7aSWarner Losh(where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name).
77018e3e3a7aSWarner LoshThe metatable is created by the I/O library
77028e3e3a7aSWarner Losh(see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
77038e3e3a7aSWarner Losh
77048e3e3a7aSWarner Losh
77058e3e3a7aSWarner Losh<p>
77068e3e3a7aSWarner LoshThis userdata must start with the structure <code>luaL_Stream</code>;
77078e3e3a7aSWarner Loshit can contain other data after this initial structure.
77080495ed39SKyle EvansThe field <code>f</code> points to the corresponding C stream
77098e3e3a7aSWarner Losh(or it can be <code>NULL</code> to indicate an incompletely created handle).
77100495ed39SKyle EvansThe field <code>closef</code> points to a Lua function
77118e3e3a7aSWarner Loshthat will be called to close the stream
77128e3e3a7aSWarner Loshwhen the handle is closed or collected;
77138e3e3a7aSWarner Loshthis function receives the file handle as its sole argument and
77140495ed39SKyle Evansmust return either a true value, in case of success,
77150495ed39SKyle Evansor a false value plus an error message, in case of error.
77168e3e3a7aSWarner LoshOnce Lua calls this field,
77178e3e3a7aSWarner Loshit changes the field value to <code>NULL</code>
77188e3e3a7aSWarner Loshto signal that the handle is closed.
77198e3e3a7aSWarner Losh
77208e3e3a7aSWarner Losh
77218e3e3a7aSWarner Losh
77228e3e3a7aSWarner Losh
77238e3e3a7aSWarner Losh
77248e3e3a7aSWarner Losh<hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p>
77258e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span>
77268e3e3a7aSWarner Losh<pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre>
77278e3e3a7aSWarner Losh
77288e3e3a7aSWarner Losh<p>
77298e3e3a7aSWarner LoshThis function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>,
77308e3e3a7aSWarner Loshexcept that, when the test fails,
77318e3e3a7aSWarner Loshit returns <code>NULL</code> instead of raising an error.
77328e3e3a7aSWarner Losh
77338e3e3a7aSWarner Losh
77348e3e3a7aSWarner Losh
77358e3e3a7aSWarner Losh
77368e3e3a7aSWarner Losh
77378e3e3a7aSWarner Losh<hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p>
77388e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span>
77398e3e3a7aSWarner Losh<pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre>
77408e3e3a7aSWarner Losh
77418e3e3a7aSWarner Losh<p>
77428e3e3a7aSWarner LoshConverts any Lua value at the given index to a C&nbsp;string
77438e3e3a7aSWarner Loshin a reasonable format.
77448e3e3a7aSWarner LoshThe resulting string is pushed onto the stack and also
77450495ed39SKyle Evansreturned by the function (see <a href="#4.1.3">&sect;4.1.3</a>).
77468e3e3a7aSWarner LoshIf <code>len</code> is not <code>NULL</code>,
77478e3e3a7aSWarner Loshthe function also sets <code>*len</code> with the string length.
77488e3e3a7aSWarner Losh
77498e3e3a7aSWarner Losh
77508e3e3a7aSWarner Losh<p>
77518e3e3a7aSWarner LoshIf the value has a metatable with a <code>__tostring</code> field,
77528e3e3a7aSWarner Loshthen <code>luaL_tolstring</code> calls the corresponding metamethod
77538e3e3a7aSWarner Loshwith the value as argument,
77548e3e3a7aSWarner Loshand uses the result of the call as its result.
77558e3e3a7aSWarner Losh
77568e3e3a7aSWarner Losh
77578e3e3a7aSWarner Losh
77588e3e3a7aSWarner Losh
77598e3e3a7aSWarner Losh
77608e3e3a7aSWarner Losh<hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p>
77618e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
77628e3e3a7aSWarner Losh<pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg,
77638e3e3a7aSWarner Losh                     int level);</pre>
77648e3e3a7aSWarner Losh
77658e3e3a7aSWarner Losh<p>
77668e3e3a7aSWarner LoshCreates and pushes a traceback of the stack <code>L1</code>.
77670495ed39SKyle EvansIf <code>msg</code> is not <code>NULL</code>, it is appended
77688e3e3a7aSWarner Loshat the beginning of the traceback.
77698e3e3a7aSWarner LoshThe <code>level</code> parameter tells at which level
77708e3e3a7aSWarner Loshto start the traceback.
77718e3e3a7aSWarner Losh
77728e3e3a7aSWarner Losh
77738e3e3a7aSWarner Losh
77748e3e3a7aSWarner Losh
77758e3e3a7aSWarner Losh
77760495ed39SKyle Evans<hr><h3><a name="luaL_typeerror"><code>luaL_typeerror</code></a></h3><p>
77770495ed39SKyle Evans<span class="apii">[-0, +0, <em>v</em>]</span>
7778a9490b81SWarner Losh<pre>int luaL_typeerror (lua_State *L, int arg, const char *tname);</pre>
77790495ed39SKyle Evans
77800495ed39SKyle Evans<p>
77810495ed39SKyle EvansRaises a type error for the argument <code>arg</code>
77820495ed39SKyle Evansof the C&nbsp;function that called it,
77830495ed39SKyle Evansusing a standard message;
77840495ed39SKyle Evans<code>tname</code> is a "name" for the expected type.
77850495ed39SKyle EvansThis function never returns.
77860495ed39SKyle Evans
77870495ed39SKyle Evans
77880495ed39SKyle Evans
77890495ed39SKyle Evans
77900495ed39SKyle Evans
77918e3e3a7aSWarner Losh<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p>
77928e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
77938e3e3a7aSWarner Losh<pre>const char *luaL_typename (lua_State *L, int index);</pre>
77948e3e3a7aSWarner Losh
77958e3e3a7aSWarner Losh<p>
77968e3e3a7aSWarner LoshReturns the name of the type of the value at the given index.
77978e3e3a7aSWarner Losh
77988e3e3a7aSWarner Losh
77998e3e3a7aSWarner Losh
78008e3e3a7aSWarner Losh
78018e3e3a7aSWarner Losh
78028e3e3a7aSWarner Losh<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p>
78038e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
78048e3e3a7aSWarner Losh<pre>void luaL_unref (lua_State *L, int t, int ref);</pre>
78058e3e3a7aSWarner Losh
78068e3e3a7aSWarner Losh<p>
78070495ed39SKyle EvansReleases the reference <code>ref</code> from the table at index <code>t</code>
78088e3e3a7aSWarner Losh(see <a href="#luaL_ref"><code>luaL_ref</code></a>).
78098e3e3a7aSWarner LoshThe entry is removed from the table,
78108e3e3a7aSWarner Loshso that the referred object can be collected.
78118e3e3a7aSWarner LoshThe reference <code>ref</code> is also freed to be used again.
78128e3e3a7aSWarner Losh
78138e3e3a7aSWarner Losh
78148e3e3a7aSWarner Losh<p>
78158e3e3a7aSWarner 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>,
78168e3e3a7aSWarner Losh<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing.
78178e3e3a7aSWarner Losh
78188e3e3a7aSWarner Losh
78198e3e3a7aSWarner Losh
78208e3e3a7aSWarner Losh
78218e3e3a7aSWarner Losh
78228e3e3a7aSWarner Losh<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p>
78238e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
78248e3e3a7aSWarner Losh<pre>void luaL_where (lua_State *L, int lvl);</pre>
78258e3e3a7aSWarner Losh
78268e3e3a7aSWarner Losh<p>
78278e3e3a7aSWarner LoshPushes onto the stack a string identifying the current position
78288e3e3a7aSWarner Loshof the control at level <code>lvl</code> in the call stack.
78298e3e3a7aSWarner LoshTypically this string has the following format:
78308e3e3a7aSWarner Losh
78318e3e3a7aSWarner Losh<pre>
78328e3e3a7aSWarner Losh     <em>chunkname</em>:<em>currentline</em>:
78338e3e3a7aSWarner Losh</pre><p>
78348e3e3a7aSWarner LoshLevel&nbsp;0 is the running function,
78358e3e3a7aSWarner Loshlevel&nbsp;1 is the function that called the running function,
78368e3e3a7aSWarner Loshetc.
78378e3e3a7aSWarner Losh
78388e3e3a7aSWarner Losh
78398e3e3a7aSWarner Losh<p>
78408e3e3a7aSWarner LoshThis function is used to build a prefix for error messages.
78418e3e3a7aSWarner Losh
78428e3e3a7aSWarner Losh
78438e3e3a7aSWarner Losh
78448e3e3a7aSWarner Losh
78458e3e3a7aSWarner Losh
78468e3e3a7aSWarner Losh
78478e3e3a7aSWarner Losh
78480495ed39SKyle Evans<h1>6 &ndash; <a name="6">The Standard Libraries</a></h1>
78490495ed39SKyle Evans
78500495ed39SKyle Evans
78518e3e3a7aSWarner Losh
78528e3e3a7aSWarner Losh<p>
78538e3e3a7aSWarner LoshThe standard Lua libraries provide useful functions
78540495ed39SKyle Evansthat are implemented in&nbsp;C through the C&nbsp;API.
78558e3e3a7aSWarner LoshSome of these functions provide essential services to the language
78568e3e3a7aSWarner Losh(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>);
78570495ed39SKyle Evansothers provide access to outside services (e.g., I/O);
78588e3e3a7aSWarner Loshand others could be implemented in Lua itself,
78590495ed39SKyle Evansbut that for different reasons
78608e3e3a7aSWarner Loshdeserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>).
78618e3e3a7aSWarner Losh
78628e3e3a7aSWarner Losh
78638e3e3a7aSWarner Losh<p>
78648e3e3a7aSWarner LoshAll libraries are implemented through the official C&nbsp;API
78658e3e3a7aSWarner Loshand are provided as separate C&nbsp;modules.
78660495ed39SKyle EvansUnless otherwise noted,
78670495ed39SKyle Evansthese library functions do not adjust its number of arguments
78680495ed39SKyle Evansto its expected parameters.
78690495ed39SKyle EvansFor instance, a function documented as <code>foo(arg)</code>
78700495ed39SKyle Evansshould not be called without an argument.
78710495ed39SKyle Evans
78720495ed39SKyle Evans
78730495ed39SKyle Evans<p>
78740495ed39SKyle EvansThe notation <b>fail</b> means a false value representing
78750495ed39SKyle Evanssome kind of failure.
78760495ed39SKyle Evans(Currently, <b>fail</b> is equal to <b>nil</b>,
78770495ed39SKyle Evansbut that may change in future versions.
78780495ed39SKyle EvansThe recommendation is to always test the success of these functions
78790495ed39SKyle Evanswith <code>(not status)</code>, instead of <code>(status == nil)</code>.)
78800495ed39SKyle Evans
78810495ed39SKyle Evans
78820495ed39SKyle Evans<p>
78838e3e3a7aSWarner LoshCurrently, Lua has the following standard libraries:
78848e3e3a7aSWarner Losh
78858e3e3a7aSWarner Losh<ul>
78868e3e3a7aSWarner Losh
78878e3e3a7aSWarner Losh<li>basic library (<a href="#6.1">&sect;6.1</a>);</li>
78888e3e3a7aSWarner Losh
78898e3e3a7aSWarner Losh<li>coroutine library (<a href="#6.2">&sect;6.2</a>);</li>
78908e3e3a7aSWarner Losh
78918e3e3a7aSWarner Losh<li>package library (<a href="#6.3">&sect;6.3</a>);</li>
78928e3e3a7aSWarner Losh
78938e3e3a7aSWarner Losh<li>string manipulation (<a href="#6.4">&sect;6.4</a>);</li>
78948e3e3a7aSWarner Losh
78958e3e3a7aSWarner Losh<li>basic UTF-8 support (<a href="#6.5">&sect;6.5</a>);</li>
78968e3e3a7aSWarner Losh
78978e3e3a7aSWarner Losh<li>table manipulation (<a href="#6.6">&sect;6.6</a>);</li>
78988e3e3a7aSWarner Losh
78998e3e3a7aSWarner Losh<li>mathematical functions (<a href="#6.7">&sect;6.7</a>) (sin, log, etc.);</li>
79008e3e3a7aSWarner Losh
79018e3e3a7aSWarner Losh<li>input and output (<a href="#6.8">&sect;6.8</a>);</li>
79028e3e3a7aSWarner Losh
79038e3e3a7aSWarner Losh<li>operating system facilities (<a href="#6.9">&sect;6.9</a>);</li>
79048e3e3a7aSWarner Losh
79058e3e3a7aSWarner Losh<li>debug facilities (<a href="#6.10">&sect;6.10</a>).</li>
79068e3e3a7aSWarner Losh
79078e3e3a7aSWarner Losh</ul><p>
79088e3e3a7aSWarner LoshExcept for the basic and the package libraries,
79098e3e3a7aSWarner Losheach library provides all its functions as fields of a global table
79108e3e3a7aSWarner Loshor as methods of its objects.
79118e3e3a7aSWarner Losh
79128e3e3a7aSWarner Losh
79138e3e3a7aSWarner Losh<p>
79148e3e3a7aSWarner LoshTo have access to these libraries,
79158e3e3a7aSWarner Loshthe C&nbsp;host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function,
79168e3e3a7aSWarner Loshwhich opens all standard libraries.
79178e3e3a7aSWarner LoshAlternatively,
79188e3e3a7aSWarner Loshthe host program can open them individually by using
79198e3e3a7aSWarner Losh<a href="#luaL_requiref"><code>luaL_requiref</code></a> to call
79208e3e3a7aSWarner Losh<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library),
79218e3e3a7aSWarner Losh<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library),
79228e3e3a7aSWarner Losh<a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library),
79238e3e3a7aSWarner Losh<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library),
79240495ed39SKyle Evans<a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF-8 library),
79258e3e3a7aSWarner Losh<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library),
79268e3e3a7aSWarner Losh<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library),
79278e3e3a7aSWarner Losh<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library),
79288e3e3a7aSWarner Losh<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library),
79298e3e3a7aSWarner Loshand <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library).
79308e3e3a7aSWarner LoshThese functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>.
79318e3e3a7aSWarner Losh
79328e3e3a7aSWarner Losh
79338e3e3a7aSWarner Losh
79340495ed39SKyle Evans
79350495ed39SKyle Evans
79368e3e3a7aSWarner Losh<h2>6.1 &ndash; <a name="6.1">Basic Functions</a></h2>
79378e3e3a7aSWarner Losh
79388e3e3a7aSWarner Losh<p>
79398e3e3a7aSWarner LoshThe basic library provides core functions to Lua.
79408e3e3a7aSWarner LoshIf you do not include this library in your application,
79418e3e3a7aSWarner Loshyou should check carefully whether you need to provide
79428e3e3a7aSWarner Loshimplementations for some of its facilities.
79438e3e3a7aSWarner Losh
79448e3e3a7aSWarner Losh
79458e3e3a7aSWarner Losh<p>
79468e3e3a7aSWarner Losh<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3>
79478e3e3a7aSWarner Losh
79488e3e3a7aSWarner Losh
79498e3e3a7aSWarner Losh<p>
79500495ed39SKyle EvansRaises an error if
79518e3e3a7aSWarner Loshthe value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>);
79528e3e3a7aSWarner Loshotherwise, returns all its arguments.
79538e3e3a7aSWarner LoshIn case of error,
79548e3e3a7aSWarner Losh<code>message</code> is the error object;
79558e3e3a7aSWarner Loshwhen absent, it defaults to "<code>assertion failed!</code>"
79568e3e3a7aSWarner Losh
79578e3e3a7aSWarner Losh
79588e3e3a7aSWarner Losh
79598e3e3a7aSWarner Losh
79608e3e3a7aSWarner Losh<p>
79618e3e3a7aSWarner Losh<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3>
79628e3e3a7aSWarner Losh
79638e3e3a7aSWarner Losh
79648e3e3a7aSWarner Losh<p>
79658e3e3a7aSWarner LoshThis function is a generic interface to the garbage collector.
79668e3e3a7aSWarner LoshIt performs different functions according to its first argument, <code>opt</code>:
79678e3e3a7aSWarner Losh
79688e3e3a7aSWarner Losh<ul>
79698e3e3a7aSWarner Losh
79708e3e3a7aSWarner Losh<li><b>"<code>collect</code>": </b>
79710495ed39SKyle EvansPerforms a full garbage-collection cycle.
79728e3e3a7aSWarner LoshThis is the default option.
79738e3e3a7aSWarner Losh</li>
79748e3e3a7aSWarner Losh
79758e3e3a7aSWarner Losh<li><b>"<code>stop</code>": </b>
79760495ed39SKyle EvansStops automatic execution of the garbage collector.
79778e3e3a7aSWarner LoshThe collector will run only when explicitly invoked,
79788e3e3a7aSWarner Loshuntil a call to restart it.
79798e3e3a7aSWarner Losh</li>
79808e3e3a7aSWarner Losh
79818e3e3a7aSWarner Losh<li><b>"<code>restart</code>": </b>
79820495ed39SKyle EvansRestarts automatic execution of the garbage collector.
79838e3e3a7aSWarner Losh</li>
79848e3e3a7aSWarner Losh
79858e3e3a7aSWarner Losh<li><b>"<code>count</code>": </b>
79860495ed39SKyle EvansReturns the total memory in use by Lua in Kbytes.
79878e3e3a7aSWarner LoshThe value has a fractional part,
79888e3e3a7aSWarner Loshso that it multiplied by 1024
79890495ed39SKyle Evansgives the exact number of bytes in use by Lua.
79908e3e3a7aSWarner Losh</li>
79918e3e3a7aSWarner Losh
79928e3e3a7aSWarner Losh<li><b>"<code>step</code>": </b>
79930495ed39SKyle EvansPerforms a garbage-collection step.
79948e3e3a7aSWarner LoshThe step "size" is controlled by <code>arg</code>.
79958e3e3a7aSWarner LoshWith a zero value,
79968e3e3a7aSWarner Loshthe collector will perform one basic (indivisible) step.
79978e3e3a7aSWarner LoshFor non-zero values,
79988e3e3a7aSWarner Loshthe collector will perform as if that amount of memory
79990495ed39SKyle Evans(in Kbytes) had been allocated by Lua.
80008e3e3a7aSWarner LoshReturns <b>true</b> if the step finished a collection cycle.
80018e3e3a7aSWarner Losh</li>
80028e3e3a7aSWarner Losh
80038e3e3a7aSWarner Losh<li><b>"<code>isrunning</code>": </b>
80040495ed39SKyle EvansReturns a boolean that tells whether the collector is running
80058e3e3a7aSWarner Losh(i.e., not stopped).
80068e3e3a7aSWarner Losh</li>
80078e3e3a7aSWarner Losh
80080495ed39SKyle Evans<li><b>"<code>incremental</code>": </b>
80090495ed39SKyle EvansChange the collector mode to incremental.
80100495ed39SKyle EvansThis option can be followed by three numbers:
80110495ed39SKyle Evansthe garbage-collector pause,
80120495ed39SKyle Evansthe step multiplier,
80130495ed39SKyle Evansand the step size (see <a href="#2.5.1">&sect;2.5.1</a>).
80140495ed39SKyle EvansA zero means to not change that value.
80150495ed39SKyle Evans</li>
80160495ed39SKyle Evans
80170495ed39SKyle Evans<li><b>"<code>generational</code>": </b>
80180495ed39SKyle EvansChange the collector mode to generational.
80190495ed39SKyle EvansThis option can be followed by two numbers:
80200495ed39SKyle Evansthe garbage-collector minor multiplier
80210495ed39SKyle Evansand the major multiplier (see <a href="#2.5.2">&sect;2.5.2</a>).
80220495ed39SKyle EvansA zero means to not change that value.
80230495ed39SKyle Evans</li>
80240495ed39SKyle Evans
80250495ed39SKyle Evans</ul><p>
80260495ed39SKyle EvansSee <a href="#2.5">&sect;2.5</a> for more details about garbage collection
80270495ed39SKyle Evansand some of these options.
80280495ed39SKyle Evans
80298e3e3a7aSWarner Losh
80308c784bb8SWarner Losh<p>
80318c784bb8SWarner LoshThis function should not be called by a finalizer.
80328c784bb8SWarner Losh
80338c784bb8SWarner Losh
80348e3e3a7aSWarner Losh
80358e3e3a7aSWarner Losh
80368e3e3a7aSWarner Losh<p>
80378e3e3a7aSWarner Losh<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3>
80380495ed39SKyle EvansOpens the named file and executes its content as a Lua chunk.
80398e3e3a7aSWarner LoshWhen called without arguments,
80400495ed39SKyle Evans<code>dofile</code> executes the content of the standard input (<code>stdin</code>).
80418e3e3a7aSWarner LoshReturns all values returned by the chunk.
80428e3e3a7aSWarner LoshIn case of errors, <code>dofile</code> propagates the error
80430495ed39SKyle Evansto its caller.
80440495ed39SKyle Evans(That is, <code>dofile</code> does not run in protected mode.)
80458e3e3a7aSWarner Losh
80468e3e3a7aSWarner Losh
80478e3e3a7aSWarner Losh
80488e3e3a7aSWarner Losh
80498e3e3a7aSWarner Losh<p>
80508e3e3a7aSWarner Losh<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3>
80518c784bb8SWarner LoshRaises an error (see <a href="#2.3">&sect;2.3</a>) with <code>message</code> as the error object.
80520495ed39SKyle EvansThis function never returns.
80538e3e3a7aSWarner Losh
80548e3e3a7aSWarner Losh
80558e3e3a7aSWarner Losh<p>
80568e3e3a7aSWarner LoshUsually, <code>error</code> adds some information about the error position
80578e3e3a7aSWarner Loshat the beginning of the message, if the message is a string.
80588e3e3a7aSWarner LoshThe <code>level</code> argument specifies how to get the error position.
80598e3e3a7aSWarner LoshWith level&nbsp;1 (the default), the error position is where the
80608e3e3a7aSWarner Losh<code>error</code> function was called.
80618e3e3a7aSWarner LoshLevel&nbsp;2 points the error to where the function
80628e3e3a7aSWarner Loshthat called <code>error</code> was called; and so on.
80638e3e3a7aSWarner LoshPassing a level&nbsp;0 avoids the addition of error position information
80648e3e3a7aSWarner Loshto the message.
80658e3e3a7aSWarner Losh
80668e3e3a7aSWarner Losh
80678e3e3a7aSWarner Losh
80688e3e3a7aSWarner Losh
80698e3e3a7aSWarner Losh<p>
80708e3e3a7aSWarner Losh<hr><h3><a name="pdf-_G"><code>_G</code></a></h3>
80718e3e3a7aSWarner LoshA global variable (not a function) that
80728e3e3a7aSWarner Loshholds the global environment (see <a href="#2.2">&sect;2.2</a>).
80738e3e3a7aSWarner LoshLua itself does not use this variable;
80748e3e3a7aSWarner Loshchanging its value does not affect any environment,
80758e3e3a7aSWarner Loshnor vice versa.
80768e3e3a7aSWarner Losh
80778e3e3a7aSWarner Losh
80788e3e3a7aSWarner Losh
80798e3e3a7aSWarner Losh
80808e3e3a7aSWarner Losh<p>
80818e3e3a7aSWarner Losh<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3>
80828e3e3a7aSWarner Losh
80838e3e3a7aSWarner Losh
80848e3e3a7aSWarner Losh<p>
80858e3e3a7aSWarner LoshIf <code>object</code> does not have a metatable, returns <b>nil</b>.
80868e3e3a7aSWarner LoshOtherwise,
80878e3e3a7aSWarner Loshif the object's metatable has a <code>__metatable</code> field,
80888e3e3a7aSWarner Loshreturns the associated value.
80898e3e3a7aSWarner LoshOtherwise, returns the metatable of the given object.
80908e3e3a7aSWarner Losh
80918e3e3a7aSWarner Losh
80928e3e3a7aSWarner Losh
80938e3e3a7aSWarner Losh
80948e3e3a7aSWarner Losh<p>
80958e3e3a7aSWarner Losh<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3>
80968e3e3a7aSWarner Losh
80978e3e3a7aSWarner Losh
80988e3e3a7aSWarner Losh<p>
80998e3e3a7aSWarner LoshReturns three values (an iterator function, the table <code>t</code>, and 0)
81008e3e3a7aSWarner Loshso that the construction
81018e3e3a7aSWarner Losh
81028e3e3a7aSWarner Losh<pre>
81038e3e3a7aSWarner Losh     for i,v in ipairs(t) do <em>body</em> end
81048e3e3a7aSWarner Losh</pre><p>
81058e3e3a7aSWarner Loshwill iterate over the key&ndash;value pairs
81068e3e3a7aSWarner Losh(<code>1,t[1]</code>), (<code>2,t[2]</code>), ...,
81070495ed39SKyle Evansup to the first absent index.
81088e3e3a7aSWarner Losh
81098e3e3a7aSWarner Losh
81108e3e3a7aSWarner Losh
81118e3e3a7aSWarner Losh
81128e3e3a7aSWarner Losh<p>
81138e3e3a7aSWarner Losh<hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3>
81148e3e3a7aSWarner Losh
81158e3e3a7aSWarner Losh
81168e3e3a7aSWarner Losh<p>
81178e3e3a7aSWarner LoshLoads a chunk.
81188e3e3a7aSWarner Losh
81198e3e3a7aSWarner Losh
81208e3e3a7aSWarner Losh<p>
81218e3e3a7aSWarner LoshIf <code>chunk</code> is a string, the chunk is this string.
81228e3e3a7aSWarner LoshIf <code>chunk</code> is a function,
81238e3e3a7aSWarner Losh<code>load</code> calls it repeatedly to get the chunk pieces.
81248e3e3a7aSWarner LoshEach call to <code>chunk</code> must return a string that concatenates
81258e3e3a7aSWarner Loshwith previous results.
81268e3e3a7aSWarner LoshA return of an empty string, <b>nil</b>, or no value signals the end of the chunk.
81278e3e3a7aSWarner Losh
81288e3e3a7aSWarner Losh
81298e3e3a7aSWarner Losh<p>
81308e3e3a7aSWarner LoshIf there are no syntactic errors,
81310495ed39SKyle Evans<code>load</code> returns the compiled chunk as a function;
81320495ed39SKyle Evansotherwise, it returns <b>fail</b> plus the error message.
81338e3e3a7aSWarner Losh
81348e3e3a7aSWarner Losh
81358e3e3a7aSWarner Losh<p>
81360495ed39SKyle EvansWhen you load a main chunk,
81378e3e3a7aSWarner Loshthe resulting function will always have exactly one upvalue,
81388e3e3a7aSWarner Loshthe <code>_ENV</code> variable (see <a href="#2.2">&sect;2.2</a>).
81398e3e3a7aSWarner LoshHowever,
81408e3e3a7aSWarner Loshwhen you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>),
81410495ed39SKyle Evansthe resulting function can have an arbitrary number of upvalues,
81420495ed39SKyle Evansand there is no guarantee that its first upvalue will be
81430495ed39SKyle Evansthe <code>_ENV</code> variable.
81440495ed39SKyle Evans(A non-main function may not even have an <code>_ENV</code> upvalue.)
81450495ed39SKyle Evans
81460495ed39SKyle Evans
81470495ed39SKyle Evans<p>
81480495ed39SKyle EvansRegardless, if the resulting function has any upvalues,
81490495ed39SKyle Evansits first upvalue is set to the value of <code>env</code>,
81500495ed39SKyle Evansif that parameter is given,
81510495ed39SKyle Evansor to the value of the global environment.
81520495ed39SKyle EvansOther upvalues are initialized with <b>nil</b>.
81538e3e3a7aSWarner LoshAll upvalues are fresh, that is,
81548e3e3a7aSWarner Loshthey are not shared with any other function.
81558e3e3a7aSWarner Losh
81568e3e3a7aSWarner Losh
81578e3e3a7aSWarner Losh<p>
81588e3e3a7aSWarner Losh<code>chunkname</code> is used as the name of the chunk for error messages
81590495ed39SKyle Evansand debug information (see <a href="#4.7">&sect;4.7</a>).
81608e3e3a7aSWarner LoshWhen absent,
81618e3e3a7aSWarner Loshit defaults to <code>chunk</code>, if <code>chunk</code> is a string,
81628e3e3a7aSWarner Loshor to "<code>=(load)</code>" otherwise.
81638e3e3a7aSWarner Losh
81648e3e3a7aSWarner Losh
81658e3e3a7aSWarner Losh<p>
81668e3e3a7aSWarner LoshThe string <code>mode</code> controls whether the chunk can be text or binary
81678e3e3a7aSWarner Losh(that is, a precompiled chunk).
81688e3e3a7aSWarner LoshIt may be the string "<code>b</code>" (only binary chunks),
81698e3e3a7aSWarner Losh"<code>t</code>" (only text chunks),
81708e3e3a7aSWarner Loshor "<code>bt</code>" (both binary and text).
81718e3e3a7aSWarner LoshThe default is "<code>bt</code>".
81728e3e3a7aSWarner Losh
81738e3e3a7aSWarner Losh
81748e3e3a7aSWarner Losh<p>
81750495ed39SKyle EvansIt is safe to load malformed binary chunks;
81760495ed39SKyle Evans<code>load</code> signals an appropriate error.
81770495ed39SKyle EvansHowever,
81780495ed39SKyle EvansLua does not check the consistency of the code inside binary chunks;
81790495ed39SKyle Evansrunning maliciously crafted bytecode can crash the interpreter.
81808e3e3a7aSWarner Losh
81818e3e3a7aSWarner Losh
81828e3e3a7aSWarner Losh
81838e3e3a7aSWarner Losh
81848e3e3a7aSWarner Losh<p>
81858e3e3a7aSWarner Losh<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3>
81868e3e3a7aSWarner Losh
81878e3e3a7aSWarner Losh
81888e3e3a7aSWarner Losh<p>
81898e3e3a7aSWarner LoshSimilar to <a href="#pdf-load"><code>load</code></a>,
81908e3e3a7aSWarner Loshbut gets the chunk from file <code>filename</code>
81918e3e3a7aSWarner Loshor from the standard input,
81928e3e3a7aSWarner Loshif no file name is given.
81938e3e3a7aSWarner Losh
81948e3e3a7aSWarner Losh
81958e3e3a7aSWarner Losh
81968e3e3a7aSWarner Losh
81978e3e3a7aSWarner Losh<p>
81988e3e3a7aSWarner Losh<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3>
81998e3e3a7aSWarner Losh
82008e3e3a7aSWarner Losh
82018e3e3a7aSWarner Losh<p>
82028e3e3a7aSWarner LoshAllows a program to traverse all fields of a table.
82038e3e3a7aSWarner LoshIts first argument is a table and its second argument
82048e3e3a7aSWarner Loshis an index in this table.
82050495ed39SKyle EvansA call to <code>next</code> returns the next index of the table
82068e3e3a7aSWarner Loshand its associated value.
82078e3e3a7aSWarner LoshWhen called with <b>nil</b> as its second argument,
82088e3e3a7aSWarner Losh<code>next</code> returns an initial index
82098e3e3a7aSWarner Loshand its associated value.
82108e3e3a7aSWarner LoshWhen called with the last index,
82118e3e3a7aSWarner Loshor with <b>nil</b> in an empty table,
82128e3e3a7aSWarner Losh<code>next</code> returns <b>nil</b>.
82138e3e3a7aSWarner LoshIf the second argument is absent, then it is interpreted as <b>nil</b>.
82148e3e3a7aSWarner LoshIn particular,
82158e3e3a7aSWarner Loshyou can use <code>next(t)</code> to check whether a table is empty.
82168e3e3a7aSWarner Losh
82178e3e3a7aSWarner Losh
82188e3e3a7aSWarner Losh<p>
82198e3e3a7aSWarner LoshThe order in which the indices are enumerated is not specified,
82208e3e3a7aSWarner Losh<em>even for numeric indices</em>.
82218e3e3a7aSWarner Losh(To traverse a table in numerical order,
82228e3e3a7aSWarner Loshuse a numerical <b>for</b>.)
82238e3e3a7aSWarner Losh
82248e3e3a7aSWarner Losh
82258e3e3a7aSWarner Losh<p>
82268c784bb8SWarner LoshYou should not assign any value to a non-existent field in a table
82278c784bb8SWarner Loshduring its traversal.
82288e3e3a7aSWarner LoshYou may however modify existing fields.
82290495ed39SKyle EvansIn particular, you may set existing fields to nil.
82308e3e3a7aSWarner Losh
82318e3e3a7aSWarner Losh
82328e3e3a7aSWarner Losh
82338e3e3a7aSWarner Losh
82348e3e3a7aSWarner Losh<p>
82358e3e3a7aSWarner Losh<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3>
82368e3e3a7aSWarner Losh
82378e3e3a7aSWarner Losh
82388e3e3a7aSWarner Losh<p>
82398e3e3a7aSWarner LoshIf <code>t</code> has a metamethod <code>__pairs</code>,
82408e3e3a7aSWarner Loshcalls it with <code>t</code> as argument and returns the first three
82418e3e3a7aSWarner Loshresults from the call.
82428e3e3a7aSWarner Losh
82438e3e3a7aSWarner Losh
82448e3e3a7aSWarner Losh<p>
82458e3e3a7aSWarner LoshOtherwise,
82468e3e3a7aSWarner Loshreturns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>,
82478e3e3a7aSWarner Loshso that the construction
82488e3e3a7aSWarner Losh
82498e3e3a7aSWarner Losh<pre>
82508e3e3a7aSWarner Losh     for k,v in pairs(t) do <em>body</em> end
82518e3e3a7aSWarner Losh</pre><p>
82528e3e3a7aSWarner Loshwill iterate over all key&ndash;value pairs of table <code>t</code>.
82538e3e3a7aSWarner Losh
82548e3e3a7aSWarner Losh
82558e3e3a7aSWarner Losh<p>
82568e3e3a7aSWarner LoshSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
82578e3e3a7aSWarner Loshthe table during its traversal.
82588e3e3a7aSWarner Losh
82598e3e3a7aSWarner Losh
82608e3e3a7aSWarner Losh
82618e3e3a7aSWarner Losh
82628e3e3a7aSWarner Losh<p>
82638e3e3a7aSWarner Losh<hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, &middot;&middot;&middot;])</code></a></h3>
82648e3e3a7aSWarner Losh
82658e3e3a7aSWarner Losh
82668e3e3a7aSWarner Losh<p>
82670495ed39SKyle EvansCalls the function <code>f</code> with
82688e3e3a7aSWarner Loshthe given arguments in <em>protected mode</em>.
82698e3e3a7aSWarner LoshThis means that any error inside&nbsp;<code>f</code> is not propagated;
82708e3e3a7aSWarner Loshinstead, <code>pcall</code> catches the error
82718e3e3a7aSWarner Loshand returns a status code.
82728e3e3a7aSWarner LoshIts first result is the status code (a boolean),
82738c784bb8SWarner Loshwhich is <b>true</b> if the call succeeds without errors.
82748e3e3a7aSWarner LoshIn such case, <code>pcall</code> also returns all results from the call,
82758e3e3a7aSWarner Loshafter this first result.
82760495ed39SKyle EvansIn case of any error, <code>pcall</code> returns <b>false</b> plus the error object.
82770495ed39SKyle EvansNote that errors caught by <code>pcall</code> do not call a message handler.
82788e3e3a7aSWarner Losh
82798e3e3a7aSWarner Losh
82808e3e3a7aSWarner Losh
82818e3e3a7aSWarner Losh
82828e3e3a7aSWarner Losh<p>
82838e3e3a7aSWarner Losh<hr><h3><a name="pdf-print"><code>print (&middot;&middot;&middot;)</code></a></h3>
82848e3e3a7aSWarner LoshReceives any number of arguments
82858e3e3a7aSWarner Loshand prints their values to <code>stdout</code>,
82860495ed39SKyle Evansconverting each argument to a string
82870495ed39SKyle Evansfollowing the same rules of <a href="#pdf-tostring"><code>tostring</code></a>.
82880495ed39SKyle Evans
82890495ed39SKyle Evans
82900495ed39SKyle Evans<p>
82910495ed39SKyle EvansThe function <code>print</code> is not intended for formatted output,
82928e3e3a7aSWarner Loshbut only as a quick way to show a value,
82938e3e3a7aSWarner Loshfor instance for debugging.
82948e3e3a7aSWarner LoshFor complete control over the output,
82958e3e3a7aSWarner Loshuse <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>.
82968e3e3a7aSWarner Losh
82978e3e3a7aSWarner Losh
82988e3e3a7aSWarner Losh
82998e3e3a7aSWarner Losh
83008e3e3a7aSWarner Losh<p>
83018e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3>
83028e3e3a7aSWarner LoshChecks whether <code>v1</code> is equal to <code>v2</code>,
83038e3e3a7aSWarner Loshwithout invoking the <code>__eq</code> metamethod.
83048e3e3a7aSWarner LoshReturns a boolean.
83058e3e3a7aSWarner Losh
83068e3e3a7aSWarner Losh
83078e3e3a7aSWarner Losh
83088e3e3a7aSWarner Losh
83098e3e3a7aSWarner Losh<p>
83108e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3>
83118e3e3a7aSWarner LoshGets the real value of <code>table[index]</code>,
83120495ed39SKyle Evanswithout using the <code>__index</code> metavalue.
83138e3e3a7aSWarner Losh<code>table</code> must be a table;
83148e3e3a7aSWarner Losh<code>index</code> may be any value.
83158e3e3a7aSWarner Losh
83168e3e3a7aSWarner Losh
83178e3e3a7aSWarner Losh
83188e3e3a7aSWarner Losh
83198e3e3a7aSWarner Losh<p>
83208e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3>
83218e3e3a7aSWarner LoshReturns the length of the object <code>v</code>,
83228e3e3a7aSWarner Loshwhich must be a table or a string,
83238e3e3a7aSWarner Loshwithout invoking the <code>__len</code> metamethod.
83248e3e3a7aSWarner LoshReturns an integer.
83258e3e3a7aSWarner Losh
83268e3e3a7aSWarner Losh
83278e3e3a7aSWarner Losh
83288e3e3a7aSWarner Losh
83298e3e3a7aSWarner Losh<p>
83308e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3>
83318e3e3a7aSWarner LoshSets the real value of <code>table[index]</code> to <code>value</code>,
83320495ed39SKyle Evanswithout using the <code>__newindex</code> metavalue.
83338e3e3a7aSWarner Losh<code>table</code> must be a table,
83348e3e3a7aSWarner Losh<code>index</code> any value different from <b>nil</b> and NaN,
83358e3e3a7aSWarner Loshand <code>value</code> any Lua value.
83368e3e3a7aSWarner Losh
83378e3e3a7aSWarner Losh
83388e3e3a7aSWarner Losh<p>
83398e3e3a7aSWarner LoshThis function returns <code>table</code>.
83408e3e3a7aSWarner Losh
83418e3e3a7aSWarner Losh
83428e3e3a7aSWarner Losh
83438e3e3a7aSWarner Losh
83448e3e3a7aSWarner Losh<p>
83458e3e3a7aSWarner Losh<hr><h3><a name="pdf-select"><code>select (index, &middot;&middot;&middot;)</code></a></h3>
83468e3e3a7aSWarner Losh
83478e3e3a7aSWarner Losh
83488e3e3a7aSWarner Losh<p>
83498e3e3a7aSWarner LoshIf <code>index</code> is a number,
83508e3e3a7aSWarner Loshreturns all arguments after argument number <code>index</code>;
83518e3e3a7aSWarner Losha negative number indexes from the end (-1 is the last argument).
83528e3e3a7aSWarner LoshOtherwise, <code>index</code> must be the string <code>"#"</code>,
83538e3e3a7aSWarner Loshand <code>select</code> returns the total number of extra arguments it received.
83548e3e3a7aSWarner Losh
83558e3e3a7aSWarner Losh
83568e3e3a7aSWarner Losh
83578e3e3a7aSWarner Losh
83588e3e3a7aSWarner Losh<p>
83598e3e3a7aSWarner Losh<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3>
83608e3e3a7aSWarner Losh
83618e3e3a7aSWarner Losh
83628e3e3a7aSWarner Losh<p>
83638e3e3a7aSWarner LoshSets the metatable for the given table.
83648e3e3a7aSWarner LoshIf <code>metatable</code> is <b>nil</b>,
83658e3e3a7aSWarner Loshremoves the metatable of the given table.
83668e3e3a7aSWarner LoshIf the original metatable has a <code>__metatable</code> field,
83678e3e3a7aSWarner Loshraises an error.
83688e3e3a7aSWarner Losh
83698e3e3a7aSWarner Losh
83708e3e3a7aSWarner Losh<p>
83718e3e3a7aSWarner LoshThis function returns <code>table</code>.
83728e3e3a7aSWarner Losh
83738e3e3a7aSWarner Losh
83740495ed39SKyle Evans<p>
83750495ed39SKyle EvansTo change the metatable of other types from Lua code,
83760495ed39SKyle Evansyou must use the debug library (<a href="#6.10">&sect;6.10</a>).
83770495ed39SKyle Evans
83780495ed39SKyle Evans
83798e3e3a7aSWarner Losh
83808e3e3a7aSWarner Losh
83818e3e3a7aSWarner Losh<p>
83828e3e3a7aSWarner Losh<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3>
83838e3e3a7aSWarner Losh
83848e3e3a7aSWarner Losh
83858e3e3a7aSWarner Losh<p>
83868e3e3a7aSWarner LoshWhen called with no <code>base</code>,
83878e3e3a7aSWarner Losh<code>tonumber</code> tries to convert its argument to a number.
83888e3e3a7aSWarner LoshIf the argument is already a number or
83898e3e3a7aSWarner Losha string convertible to a number,
83908e3e3a7aSWarner Loshthen <code>tonumber</code> returns this number;
83910495ed39SKyle Evansotherwise, it returns <b>fail</b>.
83928e3e3a7aSWarner Losh
83938e3e3a7aSWarner Losh
83948e3e3a7aSWarner Losh<p>
83958e3e3a7aSWarner LoshThe conversion of strings can result in integers or floats,
83968e3e3a7aSWarner Loshaccording to the lexical conventions of Lua (see <a href="#3.1">&sect;3.1</a>).
83970495ed39SKyle EvansThe string may have leading and trailing spaces and a sign.
83988e3e3a7aSWarner Losh
83998e3e3a7aSWarner Losh
84008e3e3a7aSWarner Losh<p>
84018e3e3a7aSWarner LoshWhen called with <code>base</code>,
84028e3e3a7aSWarner Loshthen <code>e</code> must be a string to be interpreted as
84038e3e3a7aSWarner Loshan integer numeral in that base.
84048e3e3a7aSWarner LoshThe base may be any integer between 2 and 36, inclusive.
84058e3e3a7aSWarner LoshIn bases above&nbsp;10, the letter '<code>A</code>' (in either upper or lower case)
84068e3e3a7aSWarner Loshrepresents&nbsp;10, '<code>B</code>' represents&nbsp;11, and so forth,
84078e3e3a7aSWarner Loshwith '<code>Z</code>' representing 35.
84088e3e3a7aSWarner LoshIf the string <code>e</code> is not a valid numeral in the given base,
84090495ed39SKyle Evansthe function returns <b>fail</b>.
84108e3e3a7aSWarner Losh
84118e3e3a7aSWarner Losh
84128e3e3a7aSWarner Losh
84138e3e3a7aSWarner Losh
84148e3e3a7aSWarner Losh<p>
84158e3e3a7aSWarner Losh<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3>
84160495ed39SKyle Evans
84170495ed39SKyle Evans
84180495ed39SKyle Evans<p>
84198e3e3a7aSWarner LoshReceives a value of any type and
84208e3e3a7aSWarner Loshconverts it to a string in a human-readable format.
84218e3e3a7aSWarner Losh
84228e3e3a7aSWarner Losh
84238e3e3a7aSWarner Losh<p>
84248e3e3a7aSWarner LoshIf the metatable of <code>v</code> has a <code>__tostring</code> field,
84258e3e3a7aSWarner Loshthen <code>tostring</code> calls the corresponding value
84268e3e3a7aSWarner Loshwith <code>v</code> as argument,
84278e3e3a7aSWarner Loshand uses the result of the call as its result.
84280495ed39SKyle EvansOtherwise, if the metatable of <code>v</code> has a <code>__name</code> field
84290495ed39SKyle Evanswith a string value,
84300495ed39SKyle Evans<code>tostring</code> may use that string in its final result.
84310495ed39SKyle Evans
84320495ed39SKyle Evans
84330495ed39SKyle Evans<p>
84340495ed39SKyle EvansFor complete control of how numbers are converted,
84350495ed39SKyle Evansuse <a href="#pdf-string.format"><code>string.format</code></a>.
84368e3e3a7aSWarner Losh
84378e3e3a7aSWarner Losh
84388e3e3a7aSWarner Losh
84398e3e3a7aSWarner Losh
84408e3e3a7aSWarner Losh<p>
84418e3e3a7aSWarner Losh<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3>
84420495ed39SKyle Evans
84430495ed39SKyle Evans
84440495ed39SKyle Evans<p>
84458e3e3a7aSWarner LoshReturns the type of its only argument, coded as a string.
84468e3e3a7aSWarner LoshThe possible results of this function are
84478e3e3a7aSWarner Losh"<code>nil</code>" (a string, not the value <b>nil</b>),
84488e3e3a7aSWarner Losh"<code>number</code>",
84498e3e3a7aSWarner Losh"<code>string</code>",
84508e3e3a7aSWarner Losh"<code>boolean</code>",
84518e3e3a7aSWarner Losh"<code>table</code>",
84528e3e3a7aSWarner Losh"<code>function</code>",
84538e3e3a7aSWarner Losh"<code>thread</code>",
84548e3e3a7aSWarner Loshand "<code>userdata</code>".
84558e3e3a7aSWarner Losh
84568e3e3a7aSWarner Losh
84578e3e3a7aSWarner Losh
84588e3e3a7aSWarner Losh
84598e3e3a7aSWarner Losh<p>
84608e3e3a7aSWarner Losh<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3>
84618e3e3a7aSWarner Losh
84628e3e3a7aSWarner Losh
84638e3e3a7aSWarner Losh<p>
84648e3e3a7aSWarner LoshA global variable (not a function) that
84658e3e3a7aSWarner Loshholds a string containing the running Lua version.
84660495ed39SKyle EvansThe current value of this variable is "<code>Lua 5.4</code>".
84670495ed39SKyle Evans
84680495ed39SKyle Evans
84690495ed39SKyle Evans
84700495ed39SKyle Evans
84710495ed39SKyle Evans<p>
84720495ed39SKyle Evans<hr><h3><a name="pdf-warn"><code>warn (msg1, &middot;&middot;&middot;)</code></a></h3>
84730495ed39SKyle Evans
84740495ed39SKyle Evans
84750495ed39SKyle Evans<p>
84760495ed39SKyle EvansEmits a warning with a message composed by the concatenation
84770495ed39SKyle Evansof all its arguments (which should be strings).
84780495ed39SKyle Evans
84790495ed39SKyle Evans
84800495ed39SKyle Evans<p>
84810495ed39SKyle EvansBy convention,
84820495ed39SKyle Evansa one-piece message starting with '<code>@</code>'
84830495ed39SKyle Evansis intended to be a <em>control message</em>,
84840495ed39SKyle Evanswhich is a message to the warning system itself.
84850495ed39SKyle EvansIn particular, the standard warning function in Lua
84860495ed39SKyle Evansrecognizes the control messages "<code>@off</code>",
84870495ed39SKyle Evansto stop the emission of warnings,
84880495ed39SKyle Evansand "<code>@on</code>", to (re)start the emission;
84890495ed39SKyle Evansit ignores unknown control messages.
84908e3e3a7aSWarner Losh
84918e3e3a7aSWarner Losh
84928e3e3a7aSWarner Losh
84938e3e3a7aSWarner Losh
84948e3e3a7aSWarner Losh<p>
84958e3e3a7aSWarner Losh<hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, &middot;&middot;&middot;])</code></a></h3>
84968e3e3a7aSWarner Losh
84978e3e3a7aSWarner Losh
84988e3e3a7aSWarner Losh<p>
84998e3e3a7aSWarner LoshThis function is similar to <a href="#pdf-pcall"><code>pcall</code></a>,
85008e3e3a7aSWarner Loshexcept that it sets a new message handler <code>msgh</code>.
85018e3e3a7aSWarner Losh
85028e3e3a7aSWarner Losh
85038e3e3a7aSWarner Losh
85048e3e3a7aSWarner Losh
85058e3e3a7aSWarner Losh
85068e3e3a7aSWarner Losh
85078e3e3a7aSWarner Losh
85088e3e3a7aSWarner Losh<h2>6.2 &ndash; <a name="6.2">Coroutine Manipulation</a></h2>
85098e3e3a7aSWarner Losh
85108e3e3a7aSWarner Losh<p>
85118e3e3a7aSWarner LoshThis library comprises the operations to manipulate coroutines,
85128e3e3a7aSWarner Loshwhich come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>.
85138e3e3a7aSWarner LoshSee <a href="#2.6">&sect;2.6</a> for a general description of coroutines.
85148e3e3a7aSWarner Losh
85158e3e3a7aSWarner Losh
85168e3e3a7aSWarner Losh<p>
85170495ed39SKyle Evans<hr><h3><a name="pdf-coroutine.close"><code>coroutine.close (co)</code></a></h3>
85180495ed39SKyle Evans
85190495ed39SKyle Evans
85200495ed39SKyle Evans<p>
85210495ed39SKyle EvansCloses coroutine <code>co</code>,
85220495ed39SKyle Evansthat is,
85230495ed39SKyle Evanscloses all its pending to-be-closed variables
85240495ed39SKyle Evansand puts the coroutine in a dead state.
85250495ed39SKyle EvansThe given coroutine must be dead or suspended.
85268c784bb8SWarner LoshIn case of error
85278c784bb8SWarner Losh(either the original error that stopped the coroutine or
85288c784bb8SWarner Losherrors in closing methods),
85290495ed39SKyle Evansreturns <b>false</b> plus the error object;
85300495ed39SKyle Evansotherwise returns <b>true</b>.
85310495ed39SKyle Evans
85320495ed39SKyle Evans
85330495ed39SKyle Evans
85340495ed39SKyle Evans
85350495ed39SKyle Evans<p>
85368e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3>
85378e3e3a7aSWarner Losh
85388e3e3a7aSWarner Losh
85398e3e3a7aSWarner Losh<p>
85408e3e3a7aSWarner LoshCreates a new coroutine, with body <code>f</code>.
85418e3e3a7aSWarner Losh<code>f</code> must be a function.
85428e3e3a7aSWarner LoshReturns this new coroutine,
85438e3e3a7aSWarner Loshan object with type <code>"thread"</code>.
85448e3e3a7aSWarner Losh
85458e3e3a7aSWarner Losh
85468e3e3a7aSWarner Losh
85478e3e3a7aSWarner Losh
85488e3e3a7aSWarner Losh<p>
85490495ed39SKyle Evans<hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ([co])</code></a></h3>
85508e3e3a7aSWarner Losh
85518e3e3a7aSWarner Losh
85528e3e3a7aSWarner Losh<p>
85538c784bb8SWarner LoshReturns <b>true</b> when the coroutine <code>co</code> can yield.
85540495ed39SKyle EvansThe default for <code>co</code> is the running coroutine.
85558e3e3a7aSWarner Losh
85568e3e3a7aSWarner Losh
85578e3e3a7aSWarner Losh<p>
85580495ed39SKyle EvansA coroutine is yieldable if it is not the main thread and
85598e3e3a7aSWarner Loshit is not inside a non-yieldable C&nbsp;function.
85608e3e3a7aSWarner Losh
85618e3e3a7aSWarner Losh
85628e3e3a7aSWarner Losh
85638e3e3a7aSWarner Losh
85648e3e3a7aSWarner Losh<p>
85658e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, &middot;&middot;&middot;])</code></a></h3>
85668e3e3a7aSWarner Losh
85678e3e3a7aSWarner Losh
85688e3e3a7aSWarner Losh<p>
85698e3e3a7aSWarner LoshStarts or continues the execution of coroutine <code>co</code>.
85708e3e3a7aSWarner LoshThe first time you resume a coroutine,
85718e3e3a7aSWarner Loshit starts running its body.
85728e3e3a7aSWarner LoshThe values <code>val1</code>, ... are passed
85738e3e3a7aSWarner Loshas the arguments to the body function.
85748e3e3a7aSWarner LoshIf the coroutine has yielded,
85758e3e3a7aSWarner Losh<code>resume</code> restarts it;
85768e3e3a7aSWarner Loshthe values <code>val1</code>, ... are passed
85778e3e3a7aSWarner Loshas the results from the yield.
85788e3e3a7aSWarner Losh
85798e3e3a7aSWarner Losh
85808e3e3a7aSWarner Losh<p>
85818e3e3a7aSWarner LoshIf the coroutine runs without any errors,
85828e3e3a7aSWarner Losh<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code>
85838e3e3a7aSWarner Losh(when the coroutine yields) or any values returned by the body function
85848e3e3a7aSWarner Losh(when the coroutine terminates).
85858e3e3a7aSWarner LoshIf there is any error,
85868e3e3a7aSWarner Losh<code>resume</code> returns <b>false</b> plus the error message.
85878e3e3a7aSWarner Losh
85888e3e3a7aSWarner Losh
85898e3e3a7aSWarner Losh
85908e3e3a7aSWarner Losh
85918e3e3a7aSWarner Losh<p>
85928e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3>
85938e3e3a7aSWarner Losh
85948e3e3a7aSWarner Losh
85958e3e3a7aSWarner Losh<p>
85968e3e3a7aSWarner LoshReturns the running coroutine plus a boolean,
85978c784bb8SWarner Losh<b>true</b> when the running coroutine is the main one.
85988e3e3a7aSWarner Losh
85998e3e3a7aSWarner Losh
86008e3e3a7aSWarner Losh
86018e3e3a7aSWarner Losh
86028e3e3a7aSWarner Losh<p>
86038e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3>
86048e3e3a7aSWarner Losh
86058e3e3a7aSWarner Losh
86068e3e3a7aSWarner Losh<p>
86070495ed39SKyle EvansReturns the status of the coroutine <code>co</code>, as a string:
86088e3e3a7aSWarner Losh<code>"running"</code>,
86090495ed39SKyle Evansif the coroutine is running
86100495ed39SKyle Evans(that is, it is the one that called <code>status</code>);
86118e3e3a7aSWarner Losh<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>,
86128e3e3a7aSWarner Loshor if it has not started running yet;
86138e3e3a7aSWarner Losh<code>"normal"</code> if the coroutine is active but not running
86148e3e3a7aSWarner Losh(that is, it has resumed another coroutine);
86158e3e3a7aSWarner Loshand <code>"dead"</code> if the coroutine has finished its body function,
86168e3e3a7aSWarner Loshor if it has stopped with an error.
86178e3e3a7aSWarner Losh
86188e3e3a7aSWarner Losh
86198e3e3a7aSWarner Losh
86208e3e3a7aSWarner Losh
86218e3e3a7aSWarner Losh<p>
86228e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3>
86238e3e3a7aSWarner Losh
86248e3e3a7aSWarner Losh
86258e3e3a7aSWarner Losh<p>
86260495ed39SKyle EvansCreates a new coroutine, with body <code>f</code>;
86278e3e3a7aSWarner Losh<code>f</code> must be a function.
86288e3e3a7aSWarner LoshReturns a function that resumes the coroutine each time it is called.
86290495ed39SKyle EvansAny arguments passed to this function behave as the
86308e3e3a7aSWarner Loshextra arguments to <code>resume</code>.
86310495ed39SKyle EvansThe function returns the same values returned by <code>resume</code>,
86328e3e3a7aSWarner Loshexcept the first boolean.
86330495ed39SKyle EvansIn case of error,
86340495ed39SKyle Evansthe function closes the coroutine and propagates the error.
86358e3e3a7aSWarner Losh
86368e3e3a7aSWarner Losh
86378e3e3a7aSWarner Losh
86388e3e3a7aSWarner Losh
86398e3e3a7aSWarner Losh<p>
86408e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (&middot;&middot;&middot;)</code></a></h3>
86418e3e3a7aSWarner Losh
86428e3e3a7aSWarner Losh
86438e3e3a7aSWarner Losh<p>
86448e3e3a7aSWarner LoshSuspends the execution of the calling coroutine.
86458e3e3a7aSWarner LoshAny arguments to <code>yield</code> are passed as extra results to <code>resume</code>.
86468e3e3a7aSWarner Losh
86478e3e3a7aSWarner Losh
86488e3e3a7aSWarner Losh
86498e3e3a7aSWarner Losh
86508e3e3a7aSWarner Losh
86518e3e3a7aSWarner Losh
86528e3e3a7aSWarner Losh
86538e3e3a7aSWarner Losh<h2>6.3 &ndash; <a name="6.3">Modules</a></h2>
86548e3e3a7aSWarner Losh
86558e3e3a7aSWarner Losh<p>
86568e3e3a7aSWarner LoshThe package library provides basic
86578e3e3a7aSWarner Loshfacilities for loading modules in Lua.
86588e3e3a7aSWarner LoshIt exports one function directly in the global environment:
86598e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a>.
86600495ed39SKyle EvansEverything else is exported in the table <a name="pdf-package"><code>package</code></a>.
86618e3e3a7aSWarner Losh
86628e3e3a7aSWarner Losh
86638e3e3a7aSWarner Losh<p>
86648e3e3a7aSWarner Losh<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3>
86658e3e3a7aSWarner Losh
86668e3e3a7aSWarner Losh
86678e3e3a7aSWarner Losh<p>
86688e3e3a7aSWarner LoshLoads the given module.
86698e3e3a7aSWarner LoshThe function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table
86708e3e3a7aSWarner Loshto determine whether <code>modname</code> is already loaded.
86718e3e3a7aSWarner LoshIf it is, then <code>require</code> returns the value stored
86728e3e3a7aSWarner Loshat <code>package.loaded[modname]</code>.
86730495ed39SKyle Evans(The absence of a second result in this case
86740495ed39SKyle Evanssignals that this call did not have to load the module.)
86758e3e3a7aSWarner LoshOtherwise, it tries to find a <em>loader</em> for the module.
86768e3e3a7aSWarner Losh
86778e3e3a7aSWarner Losh
86788e3e3a7aSWarner Losh<p>
86798e3e3a7aSWarner LoshTo find a loader,
86800495ed39SKyle Evans<code>require</code> is guided by the table <a href="#pdf-package.searchers"><code>package.searchers</code></a>.
86810495ed39SKyle EvansEach item in this table is a search function,
86820495ed39SKyle Evansthat searches for the module in a particular way.
86830495ed39SKyle EvansBy changing this table,
86848e3e3a7aSWarner Loshwe can change how <code>require</code> looks for a module.
86858e3e3a7aSWarner LoshThe following explanation is based on the default configuration
86868e3e3a7aSWarner Loshfor <a href="#pdf-package.searchers"><code>package.searchers</code></a>.
86878e3e3a7aSWarner Losh
86888e3e3a7aSWarner Losh
86898e3e3a7aSWarner Losh<p>
86908e3e3a7aSWarner LoshFirst <code>require</code> queries <code>package.preload[modname]</code>.
86918e3e3a7aSWarner LoshIf it has a value,
86928e3e3a7aSWarner Loshthis value (which must be a function) is the loader.
86938e3e3a7aSWarner LoshOtherwise <code>require</code> searches for a Lua loader using the
86948e3e3a7aSWarner Loshpath stored in <a href="#pdf-package.path"><code>package.path</code></a>.
86958e3e3a7aSWarner LoshIf that also fails, it searches for a C&nbsp;loader using the
86968e3e3a7aSWarner Loshpath stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
86978e3e3a7aSWarner LoshIf that also fails,
86988e3e3a7aSWarner Loshit tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>).
86998e3e3a7aSWarner Losh
87008e3e3a7aSWarner Losh
87018e3e3a7aSWarner Losh<p>
87028e3e3a7aSWarner LoshOnce a loader is found,
87038e3e3a7aSWarner Losh<code>require</code> calls the loader with two arguments:
87040495ed39SKyle Evans<code>modname</code> and an extra value,
87050495ed39SKyle Evansa <em>loader data</em>,
87060495ed39SKyle Evansalso returned by the searcher.
87070495ed39SKyle EvansThe loader data can be any value useful to the module;
87080495ed39SKyle Evansfor the default searchers,
87090495ed39SKyle Evansit indicates where the loader was found.
87100495ed39SKyle Evans(For instance, if the loader came from a file,
87110495ed39SKyle Evansthis extra value is the file path.)
87128e3e3a7aSWarner LoshIf the loader returns any non-nil value,
87138e3e3a7aSWarner Losh<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>.
87148e3e3a7aSWarner LoshIf the loader does not return a non-nil value and
87158e3e3a7aSWarner Loshhas not assigned any value to <code>package.loaded[modname]</code>,
87168e3e3a7aSWarner Loshthen <code>require</code> assigns <b>true</b> to this entry.
87178e3e3a7aSWarner LoshIn any case, <code>require</code> returns the
87188e3e3a7aSWarner Loshfinal value of <code>package.loaded[modname]</code>.
87190495ed39SKyle EvansBesides that value, <code>require</code> also returns as a second result
87200495ed39SKyle Evansthe loader data returned by the searcher,
87210495ed39SKyle Evanswhich indicates how <code>require</code> found the module.
87228e3e3a7aSWarner Losh
87238e3e3a7aSWarner Losh
87248e3e3a7aSWarner Losh<p>
87258e3e3a7aSWarner LoshIf there is any error loading or running the module,
87268e3e3a7aSWarner Loshor if it cannot find any loader for the module,
87278e3e3a7aSWarner Loshthen <code>require</code> raises an error.
87288e3e3a7aSWarner Losh
87298e3e3a7aSWarner Losh
87308e3e3a7aSWarner Losh
87318e3e3a7aSWarner Losh
87328e3e3a7aSWarner Losh<p>
87338e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3>
87348e3e3a7aSWarner Losh
87358e3e3a7aSWarner Losh
87368e3e3a7aSWarner Losh<p>
87378e3e3a7aSWarner LoshA string describing some compile-time configurations for packages.
87388e3e3a7aSWarner LoshThis string is a sequence of lines:
87398e3e3a7aSWarner Losh
87408e3e3a7aSWarner Losh<ul>
87418e3e3a7aSWarner Losh
87428e3e3a7aSWarner Losh<li>The first line is the directory separator string.
87438e3e3a7aSWarner LoshDefault is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li>
87448e3e3a7aSWarner Losh
87458e3e3a7aSWarner Losh<li>The second line is the character that separates templates in a path.
87468e3e3a7aSWarner LoshDefault is '<code>;</code>'.</li>
87478e3e3a7aSWarner Losh
87488e3e3a7aSWarner Losh<li>The third line is the string that marks the
87498e3e3a7aSWarner Loshsubstitution points in a template.
87508e3e3a7aSWarner LoshDefault is '<code>?</code>'.</li>
87518e3e3a7aSWarner Losh
87528e3e3a7aSWarner Losh<li>The fourth line is a string that, in a path in Windows,
87538e3e3a7aSWarner Loshis replaced by the executable's directory.
87548e3e3a7aSWarner LoshDefault is '<code>!</code>'.</li>
87558e3e3a7aSWarner Losh
87568e3e3a7aSWarner Losh<li>The fifth line is a mark to ignore all text after it
87578e3e3a7aSWarner Loshwhen building the <code>luaopen_</code> function name.
87588e3e3a7aSWarner LoshDefault is '<code>-</code>'.</li>
87598e3e3a7aSWarner Losh
87608e3e3a7aSWarner Losh</ul>
87618e3e3a7aSWarner Losh
87628e3e3a7aSWarner Losh
87638e3e3a7aSWarner Losh
87648e3e3a7aSWarner Losh<p>
87658e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3>
87668e3e3a7aSWarner Losh
87678e3e3a7aSWarner Losh
87688e3e3a7aSWarner Losh<p>
87690495ed39SKyle EvansA string with the path used by <a href="#pdf-require"><code>require</code></a>
87700495ed39SKyle Evansto search for a C&nbsp;loader.
87718e3e3a7aSWarner Losh
87728e3e3a7aSWarner Losh
87738e3e3a7aSWarner Losh<p>
87748e3e3a7aSWarner LoshLua initializes the C&nbsp;path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
87758e3e3a7aSWarner Loshit initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
87760495ed39SKyle Evansusing the environment variable <a name="pdf-LUA_CPATH_5_4"><code>LUA_CPATH_5_4</code></a>,
87778e3e3a7aSWarner Loshor the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>,
87788e3e3a7aSWarner Loshor a default path defined in <code>luaconf.h</code>.
87798e3e3a7aSWarner Losh
87808e3e3a7aSWarner Losh
87818e3e3a7aSWarner Losh
87828e3e3a7aSWarner Losh
87838e3e3a7aSWarner Losh<p>
87848e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3>
87858e3e3a7aSWarner Losh
87868e3e3a7aSWarner Losh
87878e3e3a7aSWarner Losh<p>
87888e3e3a7aSWarner LoshA table used by <a href="#pdf-require"><code>require</code></a> to control which
87898e3e3a7aSWarner Loshmodules are already loaded.
87908e3e3a7aSWarner LoshWhen you require a module <code>modname</code> and
87918e3e3a7aSWarner Losh<code>package.loaded[modname]</code> is not false,
87928e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a> simply returns the value stored there.
87938e3e3a7aSWarner Losh
87948e3e3a7aSWarner Losh
87958e3e3a7aSWarner Losh<p>
87968e3e3a7aSWarner LoshThis variable is only a reference to the real table;
87978e3e3a7aSWarner Loshassignments to this variable do not change the
87988e3e3a7aSWarner Loshtable used by <a href="#pdf-require"><code>require</code></a>.
8799a9490b81SWarner LoshThe real table is stored in the C registry (see <a href="#4.3">&sect;4.3</a>),
8800a9490b81SWarner Loshindexed by the key <a name="pdf-LUA_LOADED_TABLE"><code>LUA_LOADED_TABLE</code></a>, a string.
88018e3e3a7aSWarner Losh
88028e3e3a7aSWarner Losh
88038e3e3a7aSWarner Losh
88048e3e3a7aSWarner Losh
88058e3e3a7aSWarner Losh<p>
88068e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
88078e3e3a7aSWarner Losh
88088e3e3a7aSWarner Losh
88098e3e3a7aSWarner Losh<p>
88108e3e3a7aSWarner LoshDynamically links the host program with the C&nbsp;library <code>libname</code>.
88118e3e3a7aSWarner Losh
88128e3e3a7aSWarner Losh
88138e3e3a7aSWarner Losh<p>
88148e3e3a7aSWarner LoshIf <code>funcname</code> is "<code>*</code>",
88158e3e3a7aSWarner Loshthen it only links with the library,
88168e3e3a7aSWarner Loshmaking the symbols exported by the library
88178e3e3a7aSWarner Loshavailable to other dynamically linked libraries.
88188e3e3a7aSWarner LoshOtherwise,
88198e3e3a7aSWarner Loshit looks for a function <code>funcname</code> inside the library
88208e3e3a7aSWarner Loshand returns this function as a C&nbsp;function.
88218e3e3a7aSWarner LoshSo, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype
88228e3e3a7aSWarner Losh(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
88238e3e3a7aSWarner Losh
88248e3e3a7aSWarner Losh
88258e3e3a7aSWarner Losh<p>
88268e3e3a7aSWarner LoshThis is a low-level function.
88278e3e3a7aSWarner LoshIt completely bypasses the package and module system.
88288e3e3a7aSWarner LoshUnlike <a href="#pdf-require"><code>require</code></a>,
88298e3e3a7aSWarner Loshit does not perform any path searching and
88308e3e3a7aSWarner Loshdoes not automatically adds extensions.
88318e3e3a7aSWarner Losh<code>libname</code> must be the complete file name of the C&nbsp;library,
88328e3e3a7aSWarner Loshincluding if necessary a path and an extension.
88338e3e3a7aSWarner Losh<code>funcname</code> must be the exact name exported by the C&nbsp;library
88348e3e3a7aSWarner Losh(which may depend on the C&nbsp;compiler and linker used).
88358e3e3a7aSWarner Losh
88368e3e3a7aSWarner Losh
88378e3e3a7aSWarner Losh<p>
8838a9490b81SWarner LoshThis functionality is not supported by ISO&nbsp;C.
88398e3e3a7aSWarner LoshAs such, it is only available on some platforms
88408e3e3a7aSWarner Losh(Windows, Linux, Mac OS X, Solaris, BSD,
88418e3e3a7aSWarner Loshplus other Unix systems that support the <code>dlfcn</code> standard).
88428e3e3a7aSWarner Losh
88438e3e3a7aSWarner Losh
88440495ed39SKyle Evans<p>
88450495ed39SKyle EvansThis function is inherently insecure,
88460495ed39SKyle Evansas it allows Lua to call any function in any readable dynamic
88470495ed39SKyle Evanslibrary in the system.
88480495ed39SKyle Evans(Lua calls any function assuming the function
88490495ed39SKyle Evanshas a proper prototype and respects a proper protocol
88500495ed39SKyle Evans(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
88510495ed39SKyle EvansTherefore,
88520495ed39SKyle Evanscalling an arbitrary function in an arbitrary dynamic library
88530495ed39SKyle Evansmore often than not results in an access violation.)
88540495ed39SKyle Evans
88550495ed39SKyle Evans
88568e3e3a7aSWarner Losh
88578e3e3a7aSWarner Losh
88588e3e3a7aSWarner Losh<p>
88598e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3>
88608e3e3a7aSWarner Losh
88618e3e3a7aSWarner Losh
88628e3e3a7aSWarner Losh<p>
88630495ed39SKyle EvansA string with the path used by <a href="#pdf-require"><code>require</code></a>
88640495ed39SKyle Evansto search for a Lua loader.
88658e3e3a7aSWarner Losh
88668e3e3a7aSWarner Losh
88678e3e3a7aSWarner Losh<p>
88688e3e3a7aSWarner LoshAt start-up, Lua initializes this variable with
88690495ed39SKyle Evansthe value of the environment variable <a name="pdf-LUA_PATH_5_4"><code>LUA_PATH_5_4</code></a> or
88708e3e3a7aSWarner Loshthe environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or
88718e3e3a7aSWarner Loshwith a default path defined in <code>luaconf.h</code>,
88728e3e3a7aSWarner Loshif those environment variables are not defined.
88730495ed39SKyle EvansA "<code>;;</code>" in the value of the environment variable
88748e3e3a7aSWarner Loshis replaced by the default path.
88758e3e3a7aSWarner Losh
88768e3e3a7aSWarner Losh
88778e3e3a7aSWarner Losh
88788e3e3a7aSWarner Losh
88798e3e3a7aSWarner Losh<p>
88808e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3>
88818e3e3a7aSWarner Losh
88828e3e3a7aSWarner Losh
88838e3e3a7aSWarner Losh<p>
88848e3e3a7aSWarner LoshA table to store loaders for specific modules
88858e3e3a7aSWarner Losh(see <a href="#pdf-require"><code>require</code></a>).
88868e3e3a7aSWarner Losh
88878e3e3a7aSWarner Losh
88888e3e3a7aSWarner Losh<p>
88898e3e3a7aSWarner LoshThis variable is only a reference to the real table;
88908e3e3a7aSWarner Loshassignments to this variable do not change the
88918e3e3a7aSWarner Loshtable used by <a href="#pdf-require"><code>require</code></a>.
8892a9490b81SWarner LoshThe real table is stored in the C registry (see <a href="#4.3">&sect;4.3</a>),
8893a9490b81SWarner Loshindexed by the key <a name="pdf-LUA_PRELOAD_TABLE"><code>LUA_PRELOAD_TABLE</code></a>, a string.
88948e3e3a7aSWarner Losh
88958e3e3a7aSWarner Losh
88968e3e3a7aSWarner Losh
88978e3e3a7aSWarner Losh
88988e3e3a7aSWarner Losh<p>
88998e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3>
89008e3e3a7aSWarner Losh
89018e3e3a7aSWarner Losh
89028e3e3a7aSWarner Losh<p>
89030495ed39SKyle EvansA table used by <a href="#pdf-require"><code>require</code></a> to control how to find modules.
89048e3e3a7aSWarner Losh
89058e3e3a7aSWarner Losh
89068e3e3a7aSWarner Losh<p>
89078e3e3a7aSWarner LoshEach entry in this table is a <em>searcher function</em>.
89088e3e3a7aSWarner LoshWhen looking for a module,
89098e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order,
89108e3e3a7aSWarner Loshwith the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its
89110495ed39SKyle Evanssole argument.
89120495ed39SKyle EvansIf the searcher finds the module,
89130495ed39SKyle Evansit returns another function, the module <em>loader</em>,
89140495ed39SKyle Evansplus an extra value, a <em>loader data</em>,
89150495ed39SKyle Evansthat will be passed to that loader and
89160495ed39SKyle Evansreturned as a second result by <a href="#pdf-require"><code>require</code></a>.
89170495ed39SKyle EvansIf it cannot find the module,
89180495ed39SKyle Evansit returns a string explaining why
89198e3e3a7aSWarner Losh(or <b>nil</b> if it has nothing to say).
89208e3e3a7aSWarner Losh
89218e3e3a7aSWarner Losh
89228e3e3a7aSWarner Losh<p>
89238e3e3a7aSWarner LoshLua initializes this table with four searcher functions.
89248e3e3a7aSWarner Losh
89258e3e3a7aSWarner Losh
89268e3e3a7aSWarner Losh<p>
89278e3e3a7aSWarner LoshThe first searcher simply looks for a loader in the
89288e3e3a7aSWarner Losh<a href="#pdf-package.preload"><code>package.preload</code></a> table.
89298e3e3a7aSWarner Losh
89308e3e3a7aSWarner Losh
89318e3e3a7aSWarner Losh<p>
89328e3e3a7aSWarner LoshThe second searcher looks for a loader as a Lua library,
89338e3e3a7aSWarner Loshusing the path stored at <a href="#pdf-package.path"><code>package.path</code></a>.
89348e3e3a7aSWarner LoshThe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
89358e3e3a7aSWarner Losh
89368e3e3a7aSWarner Losh
89378e3e3a7aSWarner Losh<p>
89388e3e3a7aSWarner LoshThe third searcher looks for a loader as a C&nbsp;library,
89398e3e3a7aSWarner Loshusing the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
89408e3e3a7aSWarner LoshAgain,
89418e3e3a7aSWarner Loshthe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
89428e3e3a7aSWarner LoshFor instance,
89438e3e3a7aSWarner Loshif the C&nbsp;path is the string
89448e3e3a7aSWarner Losh
89458e3e3a7aSWarner Losh<pre>
89468e3e3a7aSWarner Losh     "./?.so;./?.dll;/usr/local/?/init.so"
89478e3e3a7aSWarner Losh</pre><p>
89488e3e3a7aSWarner Loshthe searcher for module <code>foo</code>
89498e3e3a7aSWarner Loshwill try to open the files <code>./foo.so</code>, <code>./foo.dll</code>,
89508e3e3a7aSWarner Loshand <code>/usr/local/foo/init.so</code>, in that order.
89518e3e3a7aSWarner LoshOnce it finds a C&nbsp;library,
89528e3e3a7aSWarner Loshthis searcher first uses a dynamic link facility to link the
89538e3e3a7aSWarner Loshapplication with the library.
89548e3e3a7aSWarner LoshThen it tries to find a C&nbsp;function inside the library to
89558e3e3a7aSWarner Loshbe used as the loader.
89568e3e3a7aSWarner LoshThe name of this C&nbsp;function is the string "<code>luaopen_</code>"
89578e3e3a7aSWarner Loshconcatenated with a copy of the module name where each dot
89588e3e3a7aSWarner Loshis replaced by an underscore.
89598e3e3a7aSWarner LoshMoreover, if the module name has a hyphen,
89608e3e3a7aSWarner Loshits suffix after (and including) the first hyphen is removed.
89618e3e3a7aSWarner LoshFor instance, if the module name is <code>a.b.c-v2.1</code>,
89628e3e3a7aSWarner Loshthe function name will be <code>luaopen_a_b_c</code>.
89638e3e3a7aSWarner Losh
89648e3e3a7aSWarner Losh
89658e3e3a7aSWarner Losh<p>
89668e3e3a7aSWarner LoshThe fourth searcher tries an <em>all-in-one loader</em>.
89678e3e3a7aSWarner LoshIt searches the C&nbsp;path for a library for
89688e3e3a7aSWarner Loshthe root name of the given module.
89698e3e3a7aSWarner LoshFor instance, when requiring <code>a.b.c</code>,
89708e3e3a7aSWarner Loshit will search for a C&nbsp;library for <code>a</code>.
89718e3e3a7aSWarner LoshIf found, it looks into it for an open function for
89728e3e3a7aSWarner Loshthe submodule;
89738e3e3a7aSWarner Loshin our example, that would be <code>luaopen_a_b_c</code>.
89748e3e3a7aSWarner LoshWith this facility, a package can pack several C&nbsp;submodules
89758e3e3a7aSWarner Loshinto one single library,
89768e3e3a7aSWarner Loshwith each submodule keeping its original open function.
89778e3e3a7aSWarner Losh
89788e3e3a7aSWarner Losh
89798e3e3a7aSWarner Losh<p>
89808e3e3a7aSWarner LoshAll searchers except the first one (preload) return as the extra value
89810495ed39SKyle Evansthe file path where the module was found,
89828e3e3a7aSWarner Loshas returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
89830495ed39SKyle EvansThe first searcher always returns the string "<code>:preload:</code>".
89840495ed39SKyle Evans
89850495ed39SKyle Evans
89860495ed39SKyle Evans<p>
89870495ed39SKyle EvansSearchers should raise no errors and have no side effects in Lua.
89880495ed39SKyle Evans(They may have side effects in C,
89890495ed39SKyle Evansfor instance by linking the application with a library.)
89908e3e3a7aSWarner Losh
89918e3e3a7aSWarner Losh
89928e3e3a7aSWarner Losh
89938e3e3a7aSWarner Losh
89948e3e3a7aSWarner Losh<p>
89958e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3>
89968e3e3a7aSWarner Losh
89978e3e3a7aSWarner Losh
89988e3e3a7aSWarner Losh<p>
89998e3e3a7aSWarner LoshSearches for the given <code>name</code> in the given <code>path</code>.
90008e3e3a7aSWarner Losh
90018e3e3a7aSWarner Losh
90028e3e3a7aSWarner Losh<p>
90038e3e3a7aSWarner LoshA path is a string containing a sequence of
90048e3e3a7aSWarner Losh<em>templates</em> separated by semicolons.
90058e3e3a7aSWarner LoshFor each template,
90068e3e3a7aSWarner Loshthe function replaces each interrogation mark (if any)
90078e3e3a7aSWarner Loshin the template with a copy of <code>name</code>
90088e3e3a7aSWarner Loshwherein all occurrences of <code>sep</code>
90098e3e3a7aSWarner Losh(a dot, by default)
90108e3e3a7aSWarner Loshwere replaced by <code>rep</code>
90118e3e3a7aSWarner Losh(the system's directory separator, by default),
90128e3e3a7aSWarner Loshand then tries to open the resulting file name.
90138e3e3a7aSWarner Losh
90148e3e3a7aSWarner Losh
90158e3e3a7aSWarner Losh<p>
90168e3e3a7aSWarner LoshFor instance, if the path is the string
90178e3e3a7aSWarner Losh
90188e3e3a7aSWarner Losh<pre>
90198e3e3a7aSWarner Losh     "./?.lua;./?.lc;/usr/local/?/init.lua"
90208e3e3a7aSWarner Losh</pre><p>
90218e3e3a7aSWarner Loshthe search for the name <code>foo.a</code>
90228e3e3a7aSWarner Loshwill try to open the files
90238e3e3a7aSWarner Losh<code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and
90248e3e3a7aSWarner Losh<code>/usr/local/foo/a/init.lua</code>, in that order.
90258e3e3a7aSWarner Losh
90268e3e3a7aSWarner Losh
90278e3e3a7aSWarner Losh<p>
90288e3e3a7aSWarner LoshReturns the resulting name of the first file that it can
90298e3e3a7aSWarner Loshopen in read mode (after closing the file),
90300495ed39SKyle Evansor <b>fail</b> plus an error message if none succeeds.
90318e3e3a7aSWarner Losh(This error message lists all file names it tried to open.)
90328e3e3a7aSWarner Losh
90338e3e3a7aSWarner Losh
90348e3e3a7aSWarner Losh
90358e3e3a7aSWarner Losh
90368e3e3a7aSWarner Losh
90378e3e3a7aSWarner Losh
90388e3e3a7aSWarner Losh
90398e3e3a7aSWarner Losh<h2>6.4 &ndash; <a name="6.4">String Manipulation</a></h2>
90408e3e3a7aSWarner Losh
90410495ed39SKyle Evans
90420495ed39SKyle Evans
90438e3e3a7aSWarner Losh<p>
90448e3e3a7aSWarner LoshThis library provides generic functions for string manipulation,
90458e3e3a7aSWarner Loshsuch as finding and extracting substrings, and pattern matching.
90468e3e3a7aSWarner LoshWhen indexing a string in Lua, the first character is at position&nbsp;1
90478e3e3a7aSWarner Losh(not at&nbsp;0, as in C).
90488e3e3a7aSWarner LoshIndices are allowed to be negative and are interpreted as indexing backwards,
90498e3e3a7aSWarner Loshfrom the end of the string.
90508e3e3a7aSWarner LoshThus, the last character is at position -1, and so on.
90518e3e3a7aSWarner Losh
90528e3e3a7aSWarner Losh
90538e3e3a7aSWarner Losh<p>
90548e3e3a7aSWarner LoshThe string library provides all its functions inside the table
90558e3e3a7aSWarner Losh<a name="pdf-string"><code>string</code></a>.
90568e3e3a7aSWarner LoshIt also sets a metatable for strings
90578e3e3a7aSWarner Loshwhere the <code>__index</code> field points to the <code>string</code> table.
90588e3e3a7aSWarner LoshTherefore, you can use the string functions in object-oriented style.
90598e3e3a7aSWarner LoshFor instance, <code>string.byte(s,i)</code>
90608e3e3a7aSWarner Loshcan be written as <code>s:byte(i)</code>.
90618e3e3a7aSWarner Losh
90628e3e3a7aSWarner Losh
90638e3e3a7aSWarner Losh<p>
90648e3e3a7aSWarner LoshThe string library assumes one-byte character encodings.
90658e3e3a7aSWarner Losh
90668e3e3a7aSWarner Losh
90678e3e3a7aSWarner Losh<p>
90688e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>
90698e3e3a7aSWarner LoshReturns the internal numeric codes of the characters <code>s[i]</code>,
90708e3e3a7aSWarner Losh<code>s[i+1]</code>, ..., <code>s[j]</code>.
90718e3e3a7aSWarner LoshThe default value for <code>i</code> is&nbsp;1;
90728e3e3a7aSWarner Loshthe default value for <code>j</code> is&nbsp;<code>i</code>.
90738e3e3a7aSWarner LoshThese indices are corrected
90748e3e3a7aSWarner Loshfollowing the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>.
90758e3e3a7aSWarner Losh
90768e3e3a7aSWarner Losh
90778e3e3a7aSWarner Losh<p>
90788e3e3a7aSWarner LoshNumeric codes are not necessarily portable across platforms.
90798e3e3a7aSWarner Losh
90808e3e3a7aSWarner Losh
90818e3e3a7aSWarner Losh
90828e3e3a7aSWarner Losh
90838e3e3a7aSWarner Losh<p>
90848e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.char"><code>string.char (&middot;&middot;&middot;)</code></a></h3>
90858e3e3a7aSWarner LoshReceives zero or more integers.
90868e3e3a7aSWarner LoshReturns a string with length equal to the number of arguments,
90878e3e3a7aSWarner Loshin which each character has the internal numeric code equal
90888e3e3a7aSWarner Loshto its corresponding argument.
90898e3e3a7aSWarner Losh
90908e3e3a7aSWarner Losh
90918e3e3a7aSWarner Losh<p>
90928e3e3a7aSWarner LoshNumeric codes are not necessarily portable across platforms.
90938e3e3a7aSWarner Losh
90948e3e3a7aSWarner Losh
90958e3e3a7aSWarner Losh
90968e3e3a7aSWarner Losh
90978e3e3a7aSWarner Losh<p>
90988e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3>
90998e3e3a7aSWarner Losh
91008e3e3a7aSWarner Losh
91018e3e3a7aSWarner Losh<p>
91028e3e3a7aSWarner LoshReturns a string containing a binary representation
91038e3e3a7aSWarner Losh(a <em>binary chunk</em>)
91048e3e3a7aSWarner Loshof the given function,
91058e3e3a7aSWarner Loshso that a later <a href="#pdf-load"><code>load</code></a> on this string returns
91068e3e3a7aSWarner Losha copy of the function (but with new upvalues).
91078e3e3a7aSWarner LoshIf <code>strip</code> is a true value,
91088e3e3a7aSWarner Loshthe binary representation may not include all debug information
91098e3e3a7aSWarner Loshabout the function,
91108e3e3a7aSWarner Loshto save space.
91118e3e3a7aSWarner Losh
91128e3e3a7aSWarner Losh
91138e3e3a7aSWarner Losh<p>
91148e3e3a7aSWarner LoshFunctions with upvalues have only their number of upvalues saved.
91158e3e3a7aSWarner LoshWhen (re)loaded,
91160495ed39SKyle Evansthose upvalues receive fresh instances.
91170495ed39SKyle Evans(See the <a href="#pdf-load"><code>load</code></a> function for details about
91180495ed39SKyle Evanshow these upvalues are initialized.
91190495ed39SKyle EvansYou can use the debug library to serialize
91208e3e3a7aSWarner Loshand reload the upvalues of a function
91218e3e3a7aSWarner Loshin a way adequate to your needs.)
91228e3e3a7aSWarner Losh
91238e3e3a7aSWarner Losh
91248e3e3a7aSWarner Losh
91258e3e3a7aSWarner Losh
91268e3e3a7aSWarner Losh<p>
91278e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
91288e3e3a7aSWarner Losh
91298e3e3a7aSWarner Losh
91308e3e3a7aSWarner Losh<p>
91318e3e3a7aSWarner LoshLooks for the first match of
91328e3e3a7aSWarner Losh<code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) in the string <code>s</code>.
91338e3e3a7aSWarner LoshIf it finds a match, then <code>find</code> returns the indices of&nbsp;<code>s</code>
91348e3e3a7aSWarner Loshwhere this occurrence starts and ends;
91350495ed39SKyle Evansotherwise, it returns <b>fail</b>.
91368e3e3a7aSWarner LoshA third, optional numeric argument <code>init</code> specifies
91378e3e3a7aSWarner Loshwhere to start the search;
91388e3e3a7aSWarner Loshits default value is&nbsp;1 and can be negative.
91398c784bb8SWarner LoshA <b>true</b> as a fourth, optional argument <code>plain</code>
91408e3e3a7aSWarner Loshturns off the pattern matching facilities,
91418e3e3a7aSWarner Loshso the function does a plain "find substring" operation,
91428e3e3a7aSWarner Loshwith no characters in <code>pattern</code> being considered magic.
91438e3e3a7aSWarner Losh
91448e3e3a7aSWarner Losh
91458e3e3a7aSWarner Losh<p>
91468e3e3a7aSWarner LoshIf the pattern has captures,
91478e3e3a7aSWarner Loshthen in a successful match
91488e3e3a7aSWarner Loshthe captured values are also returned,
91498e3e3a7aSWarner Loshafter the two indices.
91508e3e3a7aSWarner Losh
91518e3e3a7aSWarner Losh
91528e3e3a7aSWarner Losh
91538e3e3a7aSWarner Losh
91548e3e3a7aSWarner Losh<p>
91558e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, &middot;&middot;&middot;)</code></a></h3>
91568e3e3a7aSWarner Losh
91578e3e3a7aSWarner Losh
91588e3e3a7aSWarner Losh<p>
91598e3e3a7aSWarner LoshReturns a formatted version of its variable number of arguments
91600495ed39SKyle Evansfollowing the description given in its first argument,
91610495ed39SKyle Evanswhich must be a string.
91628e3e3a7aSWarner LoshThe format string follows the same rules as the ISO&nbsp;C function <code>sprintf</code>.
91630495ed39SKyle EvansThe only differences are that the conversion specifiers and modifiers
91648c784bb8SWarner Losh<code>F</code>, <code>n</code>, <code>*</code>, <code>h</code>, <code>L</code>, and <code>l</code> are not supported
91650495ed39SKyle Evansand that there is an extra specifier, <code>q</code>.
91668c784bb8SWarner LoshBoth width and precision, when present,
91678c784bb8SWarner Loshare limited to two digits.
91688e3e3a7aSWarner Losh
91698e3e3a7aSWarner Losh
91708e3e3a7aSWarner Losh<p>
91710495ed39SKyle EvansThe specifier <code>q</code> formats booleans, nil, numbers, and strings
91720495ed39SKyle Evansin a way that the result is a valid constant in Lua source code.
91730495ed39SKyle EvansBooleans and nil are written in the obvious way
91740495ed39SKyle Evans(<code>true</code>, <code>false</code>, <code>nil</code>).
91750495ed39SKyle EvansFloats are written in hexadecimal,
91760495ed39SKyle Evansto preserve full precision.
91770495ed39SKyle EvansA string is written between double quotes,
91788e3e3a7aSWarner Loshusing escape sequences when necessary to ensure that
91798e3e3a7aSWarner Loshit can safely be read back by the Lua interpreter.
91808e3e3a7aSWarner LoshFor instance, the call
91818e3e3a7aSWarner Losh
91828e3e3a7aSWarner Losh<pre>
91838e3e3a7aSWarner Losh     string.format('%q', 'a string with "quotes" and \n new line')
91848e3e3a7aSWarner Losh</pre><p>
91858e3e3a7aSWarner Loshmay produce the string:
91868e3e3a7aSWarner Losh
91878e3e3a7aSWarner Losh<pre>
91888e3e3a7aSWarner Losh     "a string with \"quotes\" and \
91898e3e3a7aSWarner Losh      new line"
91900495ed39SKyle Evans</pre><p>
91918c784bb8SWarner LoshThis specifier does not support modifiers (flags, width, precision).
91920495ed39SKyle Evans
91938e3e3a7aSWarner Losh
91948e3e3a7aSWarner Losh<p>
91950495ed39SKyle EvansThe conversion specifiers
91968e3e3a7aSWarner Losh<code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>,
91978e3e3a7aSWarner Losh<code>G</code>, and <code>g</code> all expect a number as argument.
91980495ed39SKyle EvansThe specifiers <code>c</code>, <code>d</code>,
91998e3e3a7aSWarner Losh<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code>
92008e3e3a7aSWarner Loshexpect an integer.
92018e3e3a7aSWarner LoshWhen Lua is compiled with a C89 compiler,
92020495ed39SKyle Evansthe specifiers <code>A</code> and <code>a</code> (hexadecimal floats)
92030495ed39SKyle Evansdo not support modifiers.
92048e3e3a7aSWarner Losh
92058e3e3a7aSWarner Losh
92068e3e3a7aSWarner Losh<p>
92070495ed39SKyle EvansThe specifier <code>s</code> expects a string;
92088e3e3a7aSWarner Loshif its argument is not a string,
92098e3e3a7aSWarner Loshit is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>.
92100495ed39SKyle EvansIf the specifier has any modifier,
92110495ed39SKyle Evansthe corresponding string argument should not contain embedded zeros.
92120495ed39SKyle Evans
92130495ed39SKyle Evans
92140495ed39SKyle Evans<p>
92150495ed39SKyle EvansThe specifier <code>p</code> formats the pointer
92160495ed39SKyle Evansreturned by <a href="#lua_topointer"><code>lua_topointer</code></a>.
92170495ed39SKyle EvansThat gives a unique string identifier for tables, userdata,
92180495ed39SKyle Evansthreads, strings, and functions.
92190495ed39SKyle EvansFor other values (numbers, nil, booleans),
92200495ed39SKyle Evansthis specifier results in a string representing
92210495ed39SKyle Evansthe pointer <code>NULL</code>.
92228e3e3a7aSWarner Losh
92238e3e3a7aSWarner Losh
92248e3e3a7aSWarner Losh
92258e3e3a7aSWarner Losh
92268e3e3a7aSWarner Losh<p>
92270495ed39SKyle Evans<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern [, init])</code></a></h3>
92288e3e3a7aSWarner LoshReturns an iterator function that,
92298e3e3a7aSWarner Losheach time it is called,
92308e3e3a7aSWarner Loshreturns the next captures from <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>)
92318e3e3a7aSWarner Loshover the string <code>s</code>.
92328e3e3a7aSWarner LoshIf <code>pattern</code> specifies no captures,
92338e3e3a7aSWarner Loshthen the whole match is produced in each call.
92340495ed39SKyle EvansA third, optional numeric argument <code>init</code> specifies
92350495ed39SKyle Evanswhere to start the search;
92360495ed39SKyle Evansits default value is&nbsp;1 and can be negative.
92378e3e3a7aSWarner Losh
92388e3e3a7aSWarner Losh
92398e3e3a7aSWarner Losh<p>
92408e3e3a7aSWarner LoshAs an example, the following loop
92418e3e3a7aSWarner Loshwill iterate over all the words from string <code>s</code>,
92428e3e3a7aSWarner Loshprinting one per line:
92438e3e3a7aSWarner Losh
92448e3e3a7aSWarner Losh<pre>
92458e3e3a7aSWarner Losh     s = "hello world from Lua"
92468e3e3a7aSWarner Losh     for w in string.gmatch(s, "%a+") do
92478e3e3a7aSWarner Losh       print(w)
92488e3e3a7aSWarner Losh     end
92498e3e3a7aSWarner Losh</pre><p>
92508e3e3a7aSWarner LoshThe next example collects all pairs <code>key=value</code> from the
92518e3e3a7aSWarner Loshgiven string into a table:
92528e3e3a7aSWarner Losh
92538e3e3a7aSWarner Losh<pre>
92548e3e3a7aSWarner Losh     t = {}
92558e3e3a7aSWarner Losh     s = "from=world, to=Lua"
92568e3e3a7aSWarner Losh     for k, v in string.gmatch(s, "(%w+)=(%w+)") do
92578e3e3a7aSWarner Losh       t[k] = v
92588e3e3a7aSWarner Losh     end
92598e3e3a7aSWarner Losh</pre>
92608e3e3a7aSWarner Losh
92618e3e3a7aSWarner Losh<p>
92628e3e3a7aSWarner LoshFor this function, a caret '<code>^</code>' at the start of a pattern does not
92638e3e3a7aSWarner Loshwork as an anchor, as this would prevent the iteration.
92648e3e3a7aSWarner Losh
92658e3e3a7aSWarner Losh
92668e3e3a7aSWarner Losh
92678e3e3a7aSWarner Losh
92688e3e3a7aSWarner Losh<p>
92698e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3>
92708e3e3a7aSWarner LoshReturns a copy of <code>s</code>
92718e3e3a7aSWarner Loshin which all (or the first <code>n</code>, if given)
92728e3e3a7aSWarner Loshoccurrences of the <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) have been
92738e3e3a7aSWarner Loshreplaced by a replacement string specified by <code>repl</code>,
92748e3e3a7aSWarner Loshwhich can be a string, a table, or a function.
92758e3e3a7aSWarner Losh<code>gsub</code> also returns, as its second value,
92768e3e3a7aSWarner Loshthe total number of matches that occurred.
92778e3e3a7aSWarner LoshThe name <code>gsub</code> comes from <em>Global SUBstitution</em>.
92788e3e3a7aSWarner Losh
92798e3e3a7aSWarner Losh
92808e3e3a7aSWarner Losh<p>
92818e3e3a7aSWarner LoshIf <code>repl</code> is a string, then its value is used for replacement.
92828e3e3a7aSWarner LoshThe character&nbsp;<code>%</code> works as an escape character:
92838e3e3a7aSWarner Loshany sequence in <code>repl</code> of the form <code>%<em>d</em></code>,
92848e3e3a7aSWarner Loshwith <em>d</em> between 1 and 9,
92850495ed39SKyle Evansstands for the value of the <em>d</em>-th captured substring;
92860495ed39SKyle Evansthe sequence <code>%0</code> stands for the whole match;
92870495ed39SKyle Evansthe sequence <code>%%</code> stands for a single&nbsp;<code>%</code>.
92888e3e3a7aSWarner Losh
92898e3e3a7aSWarner Losh
92908e3e3a7aSWarner Losh<p>
92918e3e3a7aSWarner LoshIf <code>repl</code> is a table, then the table is queried for every match,
92928e3e3a7aSWarner Loshusing the first capture as the key.
92938e3e3a7aSWarner Losh
92948e3e3a7aSWarner Losh
92958e3e3a7aSWarner Losh<p>
92968e3e3a7aSWarner LoshIf <code>repl</code> is a function, then this function is called every time a
92978e3e3a7aSWarner Loshmatch occurs, with all captured substrings passed as arguments,
92988e3e3a7aSWarner Loshin order.
92998e3e3a7aSWarner Losh
93008e3e3a7aSWarner Losh
93018e3e3a7aSWarner Losh<p>
93028e3e3a7aSWarner LoshIn any case,
93038e3e3a7aSWarner Loshif the pattern specifies no captures,
93048e3e3a7aSWarner Loshthen it behaves as if the whole pattern was inside a capture.
93058e3e3a7aSWarner Losh
93068e3e3a7aSWarner Losh
93078e3e3a7aSWarner Losh<p>
93088e3e3a7aSWarner LoshIf the value returned by the table query or by the function call
93098e3e3a7aSWarner Loshis a string or a number,
93108e3e3a7aSWarner Loshthen it is used as the replacement string;
93118e3e3a7aSWarner Loshotherwise, if it is <b>false</b> or <b>nil</b>,
93128e3e3a7aSWarner Loshthen there is no replacement
93138e3e3a7aSWarner Losh(that is, the original match is kept in the string).
93148e3e3a7aSWarner Losh
93158e3e3a7aSWarner Losh
93168e3e3a7aSWarner Losh<p>
93178e3e3a7aSWarner LoshHere are some examples:
93188e3e3a7aSWarner Losh
93198e3e3a7aSWarner Losh<pre>
93208e3e3a7aSWarner Losh     x = string.gsub("hello world", "(%w+)", "%1 %1")
93218e3e3a7aSWarner Losh     --&gt; x="hello hello world world"
93228e3e3a7aSWarner Losh
93238e3e3a7aSWarner Losh     x = string.gsub("hello world", "%w+", "%0 %0", 1)
93248e3e3a7aSWarner Losh     --&gt; x="hello hello world"
93258e3e3a7aSWarner Losh
93268e3e3a7aSWarner Losh     x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
93278e3e3a7aSWarner Losh     --&gt; x="world hello Lua from"
93288e3e3a7aSWarner Losh
93298e3e3a7aSWarner Losh     x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
93308e3e3a7aSWarner Losh     --&gt; x="home = /home/roberto, user = roberto"
93318e3e3a7aSWarner Losh
93328e3e3a7aSWarner Losh     x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
93338e3e3a7aSWarner Losh           return load(s)()
93348e3e3a7aSWarner Losh         end)
93358e3e3a7aSWarner Losh     --&gt; x="4+5 = 9"
93368e3e3a7aSWarner Losh
93370495ed39SKyle Evans     local t = {name="lua", version="5.4"}
93388e3e3a7aSWarner Losh     x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
93390495ed39SKyle Evans     --&gt; x="lua-5.4.tar.gz"
93408e3e3a7aSWarner Losh</pre>
93418e3e3a7aSWarner Losh
93428e3e3a7aSWarner Losh
93438e3e3a7aSWarner Losh
93448e3e3a7aSWarner Losh<p>
93458e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3>
93460495ed39SKyle Evans
93470495ed39SKyle Evans
93480495ed39SKyle Evans<p>
93498e3e3a7aSWarner LoshReceives a string and returns its length.
93508e3e3a7aSWarner LoshThe empty string <code>""</code> has length 0.
93518e3e3a7aSWarner LoshEmbedded zeros are counted,
93528e3e3a7aSWarner Loshso <code>"a\000bc\000"</code> has length 5.
93538e3e3a7aSWarner Losh
93548e3e3a7aSWarner Losh
93558e3e3a7aSWarner Losh
93568e3e3a7aSWarner Losh
93578e3e3a7aSWarner Losh<p>
93588e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3>
93590495ed39SKyle Evans
93600495ed39SKyle Evans
93610495ed39SKyle Evans<p>
93628e3e3a7aSWarner LoshReceives a string and returns a copy of this string with all
93638e3e3a7aSWarner Loshuppercase letters changed to lowercase.
93648e3e3a7aSWarner LoshAll other characters are left unchanged.
93658e3e3a7aSWarner LoshThe definition of what an uppercase letter is depends on the current locale.
93668e3e3a7aSWarner Losh
93678e3e3a7aSWarner Losh
93688e3e3a7aSWarner Losh
93698e3e3a7aSWarner Losh
93708e3e3a7aSWarner Losh<p>
93718e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3>
93720495ed39SKyle Evans
93730495ed39SKyle Evans
93740495ed39SKyle Evans<p>
93758e3e3a7aSWarner LoshLooks for the first <em>match</em> of
93760495ed39SKyle Evansthe <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) in the string <code>s</code>.
93778e3e3a7aSWarner LoshIf it finds one, then <code>match</code> returns
93788e3e3a7aSWarner Loshthe captures from the pattern;
93790495ed39SKyle Evansotherwise it returns <b>fail</b>.
93808e3e3a7aSWarner LoshIf <code>pattern</code> specifies no captures,
93818e3e3a7aSWarner Loshthen the whole match is returned.
93828e3e3a7aSWarner LoshA third, optional numeric argument <code>init</code> specifies
93838e3e3a7aSWarner Loshwhere to start the search;
93848e3e3a7aSWarner Loshits default value is&nbsp;1 and can be negative.
93858e3e3a7aSWarner Losh
93868e3e3a7aSWarner Losh
93878e3e3a7aSWarner Losh
93888e3e3a7aSWarner Losh
93898e3e3a7aSWarner Losh<p>
93908e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, &middot;&middot;&middot;)</code></a></h3>
93918e3e3a7aSWarner Losh
93928e3e3a7aSWarner Losh
93938e3e3a7aSWarner Losh<p>
93948e3e3a7aSWarner LoshReturns a binary string containing the values <code>v1</code>, <code>v2</code>, etc.
93950495ed39SKyle Evansserialized in binary form (packed)
93968e3e3a7aSWarner Loshaccording to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;6.4.2</a>).
93978e3e3a7aSWarner Losh
93988e3e3a7aSWarner Losh
93998e3e3a7aSWarner Losh
94008e3e3a7aSWarner Losh
94018e3e3a7aSWarner Losh<p>
94028e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3>
94038e3e3a7aSWarner Losh
94048e3e3a7aSWarner Losh
94058e3e3a7aSWarner Losh<p>
9406a9490b81SWarner LoshReturns the length of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a>
94078e3e3a7aSWarner Loshwith the given format.
94088e3e3a7aSWarner LoshThe format string cannot have the variable-length options
94098e3e3a7aSWarner Losh'<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">&sect;6.4.2</a>).
94108e3e3a7aSWarner Losh
94118e3e3a7aSWarner Losh
94128e3e3a7aSWarner Losh
94138e3e3a7aSWarner Losh
94148e3e3a7aSWarner Losh<p>
94158e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3>
94160495ed39SKyle Evans
94170495ed39SKyle Evans
94180495ed39SKyle Evans<p>
94198e3e3a7aSWarner LoshReturns a string that is the concatenation of <code>n</code> copies of
94208e3e3a7aSWarner Loshthe string <code>s</code> separated by the string <code>sep</code>.
94218e3e3a7aSWarner LoshThe default value for <code>sep</code> is the empty string
94228e3e3a7aSWarner Losh(that is, no separator).
94238e3e3a7aSWarner LoshReturns the empty string if <code>n</code> is not positive.
94248e3e3a7aSWarner Losh
94258e3e3a7aSWarner Losh
94268e3e3a7aSWarner Losh<p>
94278e3e3a7aSWarner Losh(Note that it is very easy to exhaust the memory of your machine
94288e3e3a7aSWarner Loshwith a single call to this function.)
94298e3e3a7aSWarner Losh
94308e3e3a7aSWarner Losh
94318e3e3a7aSWarner Losh
94328e3e3a7aSWarner Losh
94338e3e3a7aSWarner Losh<p>
94348e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3>
94350495ed39SKyle Evans
94360495ed39SKyle Evans
94370495ed39SKyle Evans<p>
94388e3e3a7aSWarner LoshReturns a string that is the string <code>s</code> reversed.
94398e3e3a7aSWarner Losh
94408e3e3a7aSWarner Losh
94418e3e3a7aSWarner Losh
94428e3e3a7aSWarner Losh
94438e3e3a7aSWarner Losh<p>
94448e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3>
94450495ed39SKyle Evans
94460495ed39SKyle Evans
94470495ed39SKyle Evans<p>
94488e3e3a7aSWarner LoshReturns the substring of <code>s</code> that
94498e3e3a7aSWarner Loshstarts at <code>i</code>  and continues until <code>j</code>;
94508e3e3a7aSWarner Losh<code>i</code> and <code>j</code> can be negative.
94518e3e3a7aSWarner LoshIf <code>j</code> is absent, then it is assumed to be equal to -1
94528e3e3a7aSWarner Losh(which is the same as the string length).
94538e3e3a7aSWarner LoshIn particular,
94548e3e3a7aSWarner Loshthe call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
94558e3e3a7aSWarner Loshwith length <code>j</code>,
94568e3e3a7aSWarner Loshand <code>string.sub(s, -i)</code> (for a positive <code>i</code>)
94578e3e3a7aSWarner Loshreturns a suffix of <code>s</code>
94588e3e3a7aSWarner Loshwith length <code>i</code>.
94598e3e3a7aSWarner Losh
94608e3e3a7aSWarner Losh
94618e3e3a7aSWarner Losh<p>
94628e3e3a7aSWarner LoshIf, after the translation of negative indices,
94638e3e3a7aSWarner Losh<code>i</code> is less than 1,
94648e3e3a7aSWarner Loshit is corrected to 1.
94658e3e3a7aSWarner LoshIf <code>j</code> is greater than the string length,
94668e3e3a7aSWarner Loshit is corrected to that length.
94678e3e3a7aSWarner LoshIf, after these corrections,
94688e3e3a7aSWarner Losh<code>i</code> is greater than <code>j</code>,
94698e3e3a7aSWarner Loshthe function returns the empty string.
94708e3e3a7aSWarner Losh
94718e3e3a7aSWarner Losh
94728e3e3a7aSWarner Losh
94738e3e3a7aSWarner Losh
94748e3e3a7aSWarner Losh<p>
94758e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3>
94768e3e3a7aSWarner Losh
94778e3e3a7aSWarner Losh
94788e3e3a7aSWarner Losh<p>
94798e3e3a7aSWarner LoshReturns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>)
94808e3e3a7aSWarner Loshaccording to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;6.4.2</a>).
94818e3e3a7aSWarner LoshAn optional <code>pos</code> marks where
94828e3e3a7aSWarner Loshto start reading in <code>s</code> (default is 1).
94838e3e3a7aSWarner LoshAfter the read values,
94848e3e3a7aSWarner Loshthis function also returns the index of the first unread byte in <code>s</code>.
94858e3e3a7aSWarner Losh
94868e3e3a7aSWarner Losh
94878e3e3a7aSWarner Losh
94888e3e3a7aSWarner Losh
94898e3e3a7aSWarner Losh<p>
94908e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3>
94910495ed39SKyle Evans
94920495ed39SKyle Evans
94930495ed39SKyle Evans<p>
94948e3e3a7aSWarner LoshReceives a string and returns a copy of this string with all
94958e3e3a7aSWarner Loshlowercase letters changed to uppercase.
94968e3e3a7aSWarner LoshAll other characters are left unchanged.
94978e3e3a7aSWarner LoshThe definition of what a lowercase letter is depends on the current locale.
94988e3e3a7aSWarner Losh
94998e3e3a7aSWarner Losh
95008e3e3a7aSWarner Losh
95018e3e3a7aSWarner Losh
95028e3e3a7aSWarner Losh
95030495ed39SKyle Evans
95040495ed39SKyle Evans
95058e3e3a7aSWarner Losh<h3>6.4.1 &ndash; <a name="6.4.1">Patterns</a></h3>
95068e3e3a7aSWarner Losh
95070495ed39SKyle Evans
95080495ed39SKyle Evans
95098e3e3a7aSWarner Losh<p>
95108e3e3a7aSWarner LoshPatterns in Lua are described by regular strings,
95118e3e3a7aSWarner Loshwhich are interpreted as patterns by the pattern-matching functions
95128e3e3a7aSWarner Losh<a href="#pdf-string.find"><code>string.find</code></a>,
95138e3e3a7aSWarner Losh<a href="#pdf-string.gmatch"><code>string.gmatch</code></a>,
95148e3e3a7aSWarner Losh<a href="#pdf-string.gsub"><code>string.gsub</code></a>,
95158e3e3a7aSWarner Loshand <a href="#pdf-string.match"><code>string.match</code></a>.
95168e3e3a7aSWarner LoshThis section describes the syntax and the meaning
95178e3e3a7aSWarner Losh(that is, what they match) of these strings.
95188e3e3a7aSWarner Losh
95198e3e3a7aSWarner Losh
95208e3e3a7aSWarner Losh
95210495ed39SKyle Evans
95220495ed39SKyle Evans
95238e3e3a7aSWarner Losh<h4>Character Class:</h4><p>
95248e3e3a7aSWarner LoshA <em>character class</em> is used to represent a set of characters.
95258e3e3a7aSWarner LoshThe following combinations are allowed in describing a character class:
95268e3e3a7aSWarner Losh
95278e3e3a7aSWarner Losh<ul>
95288e3e3a7aSWarner Losh
95298e3e3a7aSWarner Losh<li><b><em>x</em>: </b>
95308e3e3a7aSWarner Losh(where <em>x</em> is not one of the <em>magic characters</em>
95318e3e3a7aSWarner Losh<code>^$()%.[]*+-?</code>)
95328e3e3a7aSWarner Loshrepresents the character <em>x</em> itself.
95338e3e3a7aSWarner Losh</li>
95348e3e3a7aSWarner Losh
95358e3e3a7aSWarner Losh<li><b><code>.</code>: </b> (a dot) represents all characters.</li>
95368e3e3a7aSWarner Losh
95378e3e3a7aSWarner Losh<li><b><code>%a</code>: </b> represents all letters.</li>
95388e3e3a7aSWarner Losh
95398e3e3a7aSWarner Losh<li><b><code>%c</code>: </b> represents all control characters.</li>
95408e3e3a7aSWarner Losh
95418e3e3a7aSWarner Losh<li><b><code>%d</code>: </b> represents all digits.</li>
95428e3e3a7aSWarner Losh
95438e3e3a7aSWarner Losh<li><b><code>%g</code>: </b> represents all printable characters except space.</li>
95448e3e3a7aSWarner Losh
95458e3e3a7aSWarner Losh<li><b><code>%l</code>: </b> represents all lowercase letters.</li>
95468e3e3a7aSWarner Losh
95478e3e3a7aSWarner Losh<li><b><code>%p</code>: </b> represents all punctuation characters.</li>
95488e3e3a7aSWarner Losh
95498e3e3a7aSWarner Losh<li><b><code>%s</code>: </b> represents all space characters.</li>
95508e3e3a7aSWarner Losh
95518e3e3a7aSWarner Losh<li><b><code>%u</code>: </b> represents all uppercase letters.</li>
95528e3e3a7aSWarner Losh
95538e3e3a7aSWarner Losh<li><b><code>%w</code>: </b> represents all alphanumeric characters.</li>
95548e3e3a7aSWarner Losh
95558e3e3a7aSWarner Losh<li><b><code>%x</code>: </b> represents all hexadecimal digits.</li>
95568e3e3a7aSWarner Losh
95578e3e3a7aSWarner Losh<li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character)
95588e3e3a7aSWarner Loshrepresents the character <em>x</em>.
95598e3e3a7aSWarner LoshThis is the standard way to escape the magic characters.
95608e3e3a7aSWarner LoshAny non-alphanumeric character
95618e3e3a7aSWarner Losh(including all punctuation characters, even the non-magical)
95620495ed39SKyle Evanscan be preceded by a '<code>%</code>' to represent itself in a pattern.
95638e3e3a7aSWarner Losh</li>
95648e3e3a7aSWarner Losh
95658e3e3a7aSWarner Losh<li><b><code>[<em>set</em>]</code>: </b>
95668e3e3a7aSWarner Loshrepresents the class which is the union of all
95678e3e3a7aSWarner Loshcharacters in <em>set</em>.
95688e3e3a7aSWarner LoshA range of characters can be specified by
95698e3e3a7aSWarner Loshseparating the end characters of the range,
95708e3e3a7aSWarner Loshin ascending order, with a '<code>-</code>'.
95718e3e3a7aSWarner LoshAll classes <code>%</code><em>x</em> described above can also be used as
95728e3e3a7aSWarner Loshcomponents in <em>set</em>.
95738e3e3a7aSWarner LoshAll other characters in <em>set</em> represent themselves.
95748e3e3a7aSWarner LoshFor example, <code>[%w_]</code> (or <code>[_%w]</code>)
95758e3e3a7aSWarner Loshrepresents all alphanumeric characters plus the underscore,
95768e3e3a7aSWarner Losh<code>[0-7]</code> represents the octal digits,
95778e3e3a7aSWarner Loshand <code>[0-7%l%-]</code> represents the octal digits plus
95788e3e3a7aSWarner Loshthe lowercase letters plus the '<code>-</code>' character.
95798e3e3a7aSWarner Losh
95808e3e3a7aSWarner Losh
95818e3e3a7aSWarner Losh<p>
95828e3e3a7aSWarner LoshYou can put a closing square bracket in a set
95838e3e3a7aSWarner Loshby positioning it as the first character in the set.
9584e112e9d2SKyle EvansYou can put a hyphen in a set
95858e3e3a7aSWarner Loshby positioning it as the first or the last character in the set.
95868e3e3a7aSWarner Losh(You can also use an escape for both cases.)
95878e3e3a7aSWarner Losh
95888e3e3a7aSWarner Losh
95898e3e3a7aSWarner Losh<p>
95908e3e3a7aSWarner LoshThe interaction between ranges and classes is not defined.
95918e3e3a7aSWarner LoshTherefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code>
95928e3e3a7aSWarner Loshhave no meaning.
95938e3e3a7aSWarner Losh</li>
95948e3e3a7aSWarner Losh
95958e3e3a7aSWarner Losh<li><b><code>[^<em>set</em>]</code>: </b>
95968e3e3a7aSWarner Loshrepresents the complement of <em>set</em>,
95978e3e3a7aSWarner Loshwhere <em>set</em> is interpreted as above.
95988e3e3a7aSWarner Losh</li>
95998e3e3a7aSWarner Losh
96008e3e3a7aSWarner Losh</ul><p>
96018e3e3a7aSWarner LoshFor all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.),
96028e3e3a7aSWarner Loshthe corresponding uppercase letter represents the complement of the class.
96038e3e3a7aSWarner LoshFor instance, <code>%S</code> represents all non-space characters.
96048e3e3a7aSWarner Losh
96058e3e3a7aSWarner Losh
96068e3e3a7aSWarner Losh<p>
96078e3e3a7aSWarner LoshThe definitions of letter, space, and other character groups
96088e3e3a7aSWarner Loshdepend on the current locale.
96098e3e3a7aSWarner LoshIn particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>.
96108e3e3a7aSWarner Losh
96118e3e3a7aSWarner Losh
96128e3e3a7aSWarner Losh
96138e3e3a7aSWarner Losh
96148e3e3a7aSWarner Losh
96158e3e3a7aSWarner Losh<h4>Pattern Item:</h4><p>
96168e3e3a7aSWarner LoshA <em>pattern item</em> can be
96178e3e3a7aSWarner Losh
96188e3e3a7aSWarner Losh<ul>
96198e3e3a7aSWarner Losh
96208e3e3a7aSWarner Losh<li>
96218e3e3a7aSWarner Losha single character class,
96228e3e3a7aSWarner Loshwhich matches any single character in the class;
96238e3e3a7aSWarner Losh</li>
96248e3e3a7aSWarner Losh
96258e3e3a7aSWarner Losh<li>
96268e3e3a7aSWarner Losha single character class followed by '<code>*</code>',
96270495ed39SKyle Evanswhich matches sequences of zero or more characters in the class.
96288e3e3a7aSWarner LoshThese repetition items will always match the longest possible sequence;
96298e3e3a7aSWarner Losh</li>
96308e3e3a7aSWarner Losh
96318e3e3a7aSWarner Losh<li>
96328e3e3a7aSWarner Losha single character class followed by '<code>+</code>',
96330495ed39SKyle Evanswhich matches sequences of one or more characters in the class.
96348e3e3a7aSWarner LoshThese repetition items will always match the longest possible sequence;
96358e3e3a7aSWarner Losh</li>
96368e3e3a7aSWarner Losh
96378e3e3a7aSWarner Losh<li>
96388e3e3a7aSWarner Losha single character class followed by '<code>-</code>',
96390495ed39SKyle Evanswhich also matches sequences of zero or more characters in the class.
96408e3e3a7aSWarner LoshUnlike '<code>*</code>',
96418e3e3a7aSWarner Loshthese repetition items will always match the shortest possible sequence;
96428e3e3a7aSWarner Losh</li>
96438e3e3a7aSWarner Losh
96448e3e3a7aSWarner Losh<li>
96458e3e3a7aSWarner Losha single character class followed by '<code>?</code>',
96468e3e3a7aSWarner Loshwhich matches zero or one occurrence of a character in the class.
96478e3e3a7aSWarner LoshIt always matches one occurrence if possible;
96488e3e3a7aSWarner Losh</li>
96498e3e3a7aSWarner Losh
96508e3e3a7aSWarner Losh<li>
96518e3e3a7aSWarner Losh<code>%<em>n</em></code>, for <em>n</em> between 1 and 9;
96528e3e3a7aSWarner Loshsuch item matches a substring equal to the <em>n</em>-th captured string
96538e3e3a7aSWarner Losh(see below);
96548e3e3a7aSWarner Losh</li>
96558e3e3a7aSWarner Losh
96568e3e3a7aSWarner Losh<li>
96578e3e3a7aSWarner Losh<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters;
96588e3e3a7aSWarner Loshsuch item matches strings that start with&nbsp;<em>x</em>, end with&nbsp;<em>y</em>,
96598e3e3a7aSWarner Loshand where the <em>x</em> and <em>y</em> are <em>balanced</em>.
96608e3e3a7aSWarner LoshThis means that, if one reads the string from left to right,
96618e3e3a7aSWarner Loshcounting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>,
96628e3e3a7aSWarner Loshthe ending <em>y</em> is the first <em>y</em> where the count reaches 0.
96638e3e3a7aSWarner LoshFor instance, the item <code>%b()</code> matches expressions with
96648e3e3a7aSWarner Loshbalanced parentheses.
96658e3e3a7aSWarner Losh</li>
96668e3e3a7aSWarner Losh
96678e3e3a7aSWarner Losh<li>
96688e3e3a7aSWarner Losh<code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>;
96698e3e3a7aSWarner Loshsuch item matches an empty string at any position such that
96708e3e3a7aSWarner Loshthe next character belongs to <em>set</em>
96718e3e3a7aSWarner Loshand the previous character does not belong to <em>set</em>.
96728e3e3a7aSWarner LoshThe set <em>set</em> is interpreted as previously described.
96738e3e3a7aSWarner LoshThe beginning and the end of the subject are handled as if
96748e3e3a7aSWarner Loshthey were the character '<code>\0</code>'.
96758e3e3a7aSWarner Losh</li>
96768e3e3a7aSWarner Losh
96778e3e3a7aSWarner Losh</ul>
96788e3e3a7aSWarner Losh
96798e3e3a7aSWarner Losh
96808e3e3a7aSWarner Losh
96818e3e3a7aSWarner Losh
96828e3e3a7aSWarner Losh<h4>Pattern:</h4><p>
96838e3e3a7aSWarner LoshA <em>pattern</em> is a sequence of pattern items.
96848e3e3a7aSWarner LoshA caret '<code>^</code>' at the beginning of a pattern anchors the match at the
96858e3e3a7aSWarner Loshbeginning of the subject string.
96868e3e3a7aSWarner LoshA '<code>$</code>' at the end of a pattern anchors the match at the
96878e3e3a7aSWarner Loshend of the subject string.
96888e3e3a7aSWarner LoshAt other positions,
96898e3e3a7aSWarner Losh'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves.
96908e3e3a7aSWarner Losh
96918e3e3a7aSWarner Losh
96928e3e3a7aSWarner Losh
96938e3e3a7aSWarner Losh
96948e3e3a7aSWarner Losh
96958e3e3a7aSWarner Losh<h4>Captures:</h4><p>
96968e3e3a7aSWarner LoshA pattern can contain sub-patterns enclosed in parentheses;
96978e3e3a7aSWarner Loshthey describe <em>captures</em>.
96988e3e3a7aSWarner LoshWhen a match succeeds, the substrings of the subject string
96998e3e3a7aSWarner Loshthat match captures are stored (<em>captured</em>) for future use.
97008e3e3a7aSWarner LoshCaptures are numbered according to their left parentheses.
97018e3e3a7aSWarner LoshFor instance, in the pattern <code>"(a*(.)%w(%s*))"</code>,
97028e3e3a7aSWarner Loshthe part of the string matching <code>"a*(.)%w(%s*)"</code> is
97030495ed39SKyle Evansstored as the first capture, and therefore has number&nbsp;1;
97048e3e3a7aSWarner Loshthe character matching "<code>.</code>" is captured with number&nbsp;2,
97058e3e3a7aSWarner Loshand the part matching "<code>%s*</code>" has number&nbsp;3.
97068e3e3a7aSWarner Losh
97078e3e3a7aSWarner Losh
97088e3e3a7aSWarner Losh<p>
97090495ed39SKyle EvansAs a special case, the capture <code>()</code> captures
97108e3e3a7aSWarner Loshthe current string position (a number).
97118e3e3a7aSWarner LoshFor instance, if we apply the pattern <code>"()aa()"</code> on the
97128e3e3a7aSWarner Loshstring <code>"flaaap"</code>, there will be two captures: 3&nbsp;and&nbsp;5.
97138e3e3a7aSWarner Losh
97148e3e3a7aSWarner Losh
97158e3e3a7aSWarner Losh
97168e3e3a7aSWarner Losh
97178e3e3a7aSWarner Losh
97180495ed39SKyle Evans<h4>Multiple matches:</h4><p>
97190495ed39SKyle 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>
97200495ed39SKyle Evansmatch multiple occurrences of the given pattern in the subject.
97210495ed39SKyle EvansFor these functions,
97220495ed39SKyle Evansa new match is considered valid only
97230495ed39SKyle Evansif it ends at least one byte after the end of the previous match.
97240495ed39SKyle EvansIn other words, the pattern machine never accepts the
97250495ed39SKyle Evansempty string as a match immediately after another match.
97260495ed39SKyle EvansAs an example,
97270495ed39SKyle Evansconsider the results of the following code:
97280495ed39SKyle Evans
97290495ed39SKyle Evans<pre>
97300495ed39SKyle Evans     &gt; string.gsub("abc", "()a*()", print);
97310495ed39SKyle Evans     --&gt; 1   2
97320495ed39SKyle Evans     --&gt; 3   3
97330495ed39SKyle Evans     --&gt; 4   4
97340495ed39SKyle Evans</pre><p>
97350495ed39SKyle EvansThe second and third results come from Lua matching an empty
97360495ed39SKyle Evansstring after '<code>b</code>' and another one after '<code>c</code>'.
97370495ed39SKyle EvansLua does not match an empty string after '<code>a</code>',
97380495ed39SKyle Evansbecause it would end at the same position of the previous match.
97390495ed39SKyle Evans
97400495ed39SKyle Evans
97410495ed39SKyle Evans
97420495ed39SKyle Evans
97430495ed39SKyle Evans
97448e3e3a7aSWarner Losh
97458e3e3a7aSWarner Losh
97468e3e3a7aSWarner Losh<h3>6.4.2 &ndash; <a name="6.4.2">Format Strings for Pack and Unpack</a></h3>
97478e3e3a7aSWarner Losh
97488e3e3a7aSWarner Losh<p>
97498e3e3a7aSWarner LoshThe first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>,
97508e3e3a7aSWarner Losh<a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a>
97518e3e3a7aSWarner Loshis a format string,
97528e3e3a7aSWarner Loshwhich describes the layout of the structure being created or read.
97538e3e3a7aSWarner Losh
97548e3e3a7aSWarner Losh
97558e3e3a7aSWarner Losh<p>
97568e3e3a7aSWarner LoshA format string is a sequence of conversion options.
97578e3e3a7aSWarner LoshThe conversion options are as follows:
97588e3e3a7aSWarner Losh
97598e3e3a7aSWarner Losh<ul>
97608e3e3a7aSWarner Losh<li><b><code>&lt;</code>: </b>sets little endian</li>
97618e3e3a7aSWarner Losh<li><b><code>&gt;</code>: </b>sets big endian</li>
97628e3e3a7aSWarner Losh<li><b><code>=</code>: </b>sets native endian</li>
97638e3e3a7aSWarner Losh<li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code>
97648e3e3a7aSWarner Losh(default is native alignment)</li>
97658e3e3a7aSWarner Losh<li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li>
97668e3e3a7aSWarner Losh<li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li>
97678e3e3a7aSWarner Losh<li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li>
97688e3e3a7aSWarner Losh<li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li>
97698e3e3a7aSWarner Losh<li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li>
97708e3e3a7aSWarner Losh<li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li>
97718e3e3a7aSWarner Losh<li><b><code>j</code>: </b>a <code>lua_Integer</code></li>
97728e3e3a7aSWarner Losh<li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li>
97738e3e3a7aSWarner Losh<li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li>
97748e3e3a7aSWarner Losh<li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes
97758e3e3a7aSWarner Losh(default is native size)</li>
97768e3e3a7aSWarner Losh<li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes
97778e3e3a7aSWarner Losh(default is native size)</li>
97788e3e3a7aSWarner Losh<li><b><code>f</code>: </b>a <code>float</code> (native size)</li>
97798e3e3a7aSWarner Losh<li><b><code>d</code>: </b>a <code>double</code> (native size)</li>
97808e3e3a7aSWarner Losh<li><b><code>n</code>: </b>a <code>lua_Number</code></li>
97818e3e3a7aSWarner Losh<li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li>
97828e3e3a7aSWarner Losh<li><b><code>z</code>: </b>a zero-terminated string</li>
97838e3e3a7aSWarner Losh<li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length
97848e3e3a7aSWarner Loshcoded as an unsigned integer with <code>n</code> bytes
97858e3e3a7aSWarner Losh(default is a <code>size_t</code>)</li>
97868e3e3a7aSWarner Losh<li><b><code>x</code>: </b>one byte of padding</li>
97878e3e3a7aSWarner Losh<li><b><code>X<em>op</em></code>: </b>an empty item that aligns
97888e3e3a7aSWarner Loshaccording to option <code>op</code>
97898e3e3a7aSWarner Losh(which is otherwise ignored)</li>
97900495ed39SKyle Evans<li><b>'<code> </code>': </b>(space) ignored</li>
97918e3e3a7aSWarner Losh</ul><p>
97928e3e3a7aSWarner Losh(A "<code>[<em>n</em>]</code>" means an optional integral numeral.)
97938e3e3a7aSWarner LoshExcept for padding, spaces, and configurations
97948e3e3a7aSWarner Losh(options "<code>xX &lt;=&gt;!</code>"),
97950495ed39SKyle Evanseach option corresponds to an argument in <a href="#pdf-string.pack"><code>string.pack</code></a>
97960495ed39SKyle Evansor a result in <a href="#pdf-string.unpack"><code>string.unpack</code></a>.
97978e3e3a7aSWarner Losh
97988e3e3a7aSWarner Losh
97998e3e3a7aSWarner Losh<p>
98008e3e3a7aSWarner 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>",
98018e3e3a7aSWarner Losh<code>n</code> can be any integer between 1 and 16.
98028e3e3a7aSWarner LoshAll integral options check overflows;
98038e3e3a7aSWarner Losh<a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size;
98048e3e3a7aSWarner Losh<a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer.
98050495ed39SKyle EvansFor the unsigned options,
98060495ed39SKyle EvansLua integers are treated as unsigned values too.
98078e3e3a7aSWarner Losh
98088e3e3a7aSWarner Losh
98098e3e3a7aSWarner Losh<p>
98108e3e3a7aSWarner LoshAny format string starts as if prefixed by "<code>!1=</code>",
98118e3e3a7aSWarner Loshthat is,
98128e3e3a7aSWarner Loshwith maximum alignment of 1 (no alignment)
98138e3e3a7aSWarner Loshand native endianness.
98148e3e3a7aSWarner Losh
98158e3e3a7aSWarner Losh
98168e3e3a7aSWarner Losh<p>
98170495ed39SKyle EvansNative endianness assumes that the whole system is
98180495ed39SKyle Evanseither big or little endian.
98190495ed39SKyle EvansThe packing functions will not emulate correctly the behavior
98200495ed39SKyle Evansof mixed-endian formats.
98210495ed39SKyle Evans
98220495ed39SKyle Evans
98230495ed39SKyle Evans<p>
98248e3e3a7aSWarner LoshAlignment works as follows:
98258e3e3a7aSWarner LoshFor each option,
98268e3e3a7aSWarner Loshthe format gets extra padding until the data starts
98278e3e3a7aSWarner Loshat an offset that is a multiple of the minimum between the
98288e3e3a7aSWarner Loshoption size and the maximum alignment;
98298e3e3a7aSWarner Loshthis minimum must be a power of 2.
98308e3e3a7aSWarner LoshOptions "<code>c</code>" and "<code>z</code>" are not aligned;
98318e3e3a7aSWarner Loshoption "<code>s</code>" follows the alignment of its starting integer.
98328e3e3a7aSWarner Losh
98338e3e3a7aSWarner Losh
98348e3e3a7aSWarner Losh<p>
98358e3e3a7aSWarner LoshAll padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a>
98360495ed39SKyle Evansand ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>.
98378e3e3a7aSWarner Losh
98388e3e3a7aSWarner Losh
98398e3e3a7aSWarner Losh
98408e3e3a7aSWarner Losh
98418e3e3a7aSWarner Losh
98428e3e3a7aSWarner Losh
98438e3e3a7aSWarner Losh
98448e3e3a7aSWarner Losh<h2>6.5 &ndash; <a name="6.5">UTF-8 Support</a></h2>
98458e3e3a7aSWarner Losh
98468e3e3a7aSWarner Losh<p>
98478e3e3a7aSWarner LoshThis library provides basic support for UTF-8 encoding.
98488e3e3a7aSWarner LoshIt provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>.
98498e3e3a7aSWarner LoshThis library does not provide any support for Unicode other
98508e3e3a7aSWarner Loshthan the handling of the encoding.
98518e3e3a7aSWarner LoshAny operation that needs the meaning of a character,
98528e3e3a7aSWarner Loshsuch as character classification, is outside its scope.
98538e3e3a7aSWarner Losh
98548e3e3a7aSWarner Losh
98558e3e3a7aSWarner Losh<p>
98568e3e3a7aSWarner LoshUnless stated otherwise,
98578e3e3a7aSWarner Loshall functions that expect a byte position as a parameter
98588e3e3a7aSWarner Loshassume that the given position is either the start of a byte sequence
98598e3e3a7aSWarner Loshor one plus the length of the subject string.
98608e3e3a7aSWarner LoshAs in the string library,
98618e3e3a7aSWarner Loshnegative indices count from the end of the string.
98628e3e3a7aSWarner Losh
98638e3e3a7aSWarner Losh
98648e3e3a7aSWarner Losh<p>
98650495ed39SKyle EvansFunctions that create byte sequences
98660495ed39SKyle Evansaccept all values up to <code>0x7FFFFFFF</code>,
98670495ed39SKyle Evansas defined in the original UTF-8 specification;
98680495ed39SKyle Evansthat implies byte sequences of up to six bytes.
98690495ed39SKyle Evans
98700495ed39SKyle Evans
98710495ed39SKyle Evans<p>
98720495ed39SKyle EvansFunctions that interpret byte sequences only accept
98730495ed39SKyle Evansvalid sequences (well formed and not overlong).
98740495ed39SKyle EvansBy default, they only accept byte sequences
98750495ed39SKyle Evansthat result in valid Unicode code points,
98760495ed39SKyle Evansrejecting values greater than <code>10FFFF</code> and surrogates.
98770495ed39SKyle EvansA boolean argument <code>lax</code>, when available,
98780495ed39SKyle Evanslifts these checks,
98790495ed39SKyle Evansso that all values up to <code>0x7FFFFFFF</code> are accepted.
98800495ed39SKyle Evans(Not well formed and overlong sequences are still rejected.)
98810495ed39SKyle Evans
98820495ed39SKyle Evans
98830495ed39SKyle Evans<p>
98848e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.char"><code>utf8.char (&middot;&middot;&middot;)</code></a></h3>
98850495ed39SKyle Evans
98860495ed39SKyle Evans
98870495ed39SKyle Evans<p>
98888e3e3a7aSWarner LoshReceives zero or more integers,
98898e3e3a7aSWarner Loshconverts each one to its corresponding UTF-8 byte sequence
98908e3e3a7aSWarner Loshand returns a string with the concatenation of all these sequences.
98918e3e3a7aSWarner Losh
98928e3e3a7aSWarner Losh
98938e3e3a7aSWarner Losh
98948e3e3a7aSWarner Losh
98958e3e3a7aSWarner Losh<p>
98968e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3>
98970495ed39SKyle Evans
98980495ed39SKyle Evans
98990495ed39SKyle Evans<p>
99000495ed39SKyle EvansThe pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xFD][\x80-\xBF]*</code>"
99018e3e3a7aSWarner Losh(see <a href="#6.4.1">&sect;6.4.1</a>),
99028e3e3a7aSWarner Loshwhich matches exactly one UTF-8 byte sequence,
99038e3e3a7aSWarner Loshassuming that the subject is a valid UTF-8 string.
99048e3e3a7aSWarner Losh
99058e3e3a7aSWarner Losh
99068e3e3a7aSWarner Losh
99078e3e3a7aSWarner Losh
99088e3e3a7aSWarner Losh<p>
99090495ed39SKyle Evans<hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s [, lax])</code></a></h3>
99108e3e3a7aSWarner Losh
99118e3e3a7aSWarner Losh
99128e3e3a7aSWarner Losh<p>
99138e3e3a7aSWarner LoshReturns values so that the construction
99148e3e3a7aSWarner Losh
99158e3e3a7aSWarner Losh<pre>
99168e3e3a7aSWarner Losh     for p, c in utf8.codes(s) do <em>body</em> end
99178e3e3a7aSWarner Losh</pre><p>
99180495ed39SKyle Evanswill iterate over all UTF-8 characters in string <code>s</code>,
99198e3e3a7aSWarner Loshwith <code>p</code> being the position (in bytes) and <code>c</code> the code point
99208e3e3a7aSWarner Loshof each character.
99218e3e3a7aSWarner LoshIt raises an error if it meets any invalid byte sequence.
99228e3e3a7aSWarner Losh
99238e3e3a7aSWarner Losh
99248e3e3a7aSWarner Losh
99258e3e3a7aSWarner Losh
99268e3e3a7aSWarner Losh<p>
99270495ed39SKyle Evans<hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j [, lax]]])</code></a></h3>
99280495ed39SKyle Evans
99290495ed39SKyle Evans
99300495ed39SKyle Evans<p>
99318e3e3a7aSWarner LoshReturns the code points (as integers) from all characters in <code>s</code>
99328e3e3a7aSWarner Loshthat start between byte position <code>i</code> and <code>j</code> (both included).
99338e3e3a7aSWarner LoshThe default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>.
99348e3e3a7aSWarner LoshIt raises an error if it meets any invalid byte sequence.
99358e3e3a7aSWarner Losh
99368e3e3a7aSWarner Losh
99378e3e3a7aSWarner Losh
99388e3e3a7aSWarner Losh
99398e3e3a7aSWarner Losh<p>
99400495ed39SKyle Evans<hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j [, lax]]])</code></a></h3>
99410495ed39SKyle Evans
99420495ed39SKyle Evans
99430495ed39SKyle Evans<p>
99448e3e3a7aSWarner LoshReturns the number of UTF-8 characters in string <code>s</code>
99458e3e3a7aSWarner Loshthat start between positions <code>i</code> and <code>j</code> (both inclusive).
99468e3e3a7aSWarner LoshThe default for <code>i</code> is 1 and for <code>j</code> is -1.
99478e3e3a7aSWarner LoshIf it finds any invalid byte sequence,
99480495ed39SKyle Evansreturns <b>fail</b> plus the position of the first invalid byte.
99498e3e3a7aSWarner Losh
99508e3e3a7aSWarner Losh
99518e3e3a7aSWarner Losh
99528e3e3a7aSWarner Losh
99538e3e3a7aSWarner Losh<p>
99548e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3>
99550495ed39SKyle Evans
99560495ed39SKyle Evans
99570495ed39SKyle Evans<p>
99588e3e3a7aSWarner LoshReturns the position (in bytes) where the encoding of the
99598e3e3a7aSWarner Losh<code>n</code>-th character of <code>s</code>
99608e3e3a7aSWarner Losh(counting from position <code>i</code>) starts.
99618e3e3a7aSWarner LoshA negative <code>n</code> gets characters before position <code>i</code>.
99628e3e3a7aSWarner LoshThe default for <code>i</code> is 1 when <code>n</code> is non-negative
99638e3e3a7aSWarner Loshand <code>#s + 1</code> otherwise,
99648e3e3a7aSWarner Loshso that <code>utf8.offset(s, -n)</code> gets the offset of the
99658e3e3a7aSWarner Losh<code>n</code>-th character from the end of the string.
99668e3e3a7aSWarner LoshIf the specified character is neither in the subject
99678e3e3a7aSWarner Loshnor right after its end,
99680495ed39SKyle Evansthe function returns <b>fail</b>.
99698e3e3a7aSWarner Losh
99708e3e3a7aSWarner Losh
99718e3e3a7aSWarner Losh<p>
99728e3e3a7aSWarner LoshAs a special case,
99738e3e3a7aSWarner Loshwhen <code>n</code> is 0 the function returns the start of the encoding
99748e3e3a7aSWarner Loshof the character that contains the <code>i</code>-th byte of <code>s</code>.
99758e3e3a7aSWarner Losh
99768e3e3a7aSWarner Losh
99778e3e3a7aSWarner Losh<p>
99788e3e3a7aSWarner LoshThis function assumes that <code>s</code> is a valid UTF-8 string.
99798e3e3a7aSWarner Losh
99808e3e3a7aSWarner Losh
99818e3e3a7aSWarner Losh
99828e3e3a7aSWarner Losh
99838e3e3a7aSWarner Losh
99848e3e3a7aSWarner Losh
99858e3e3a7aSWarner Losh
99868e3e3a7aSWarner Losh<h2>6.6 &ndash; <a name="6.6">Table Manipulation</a></h2>
99878e3e3a7aSWarner Losh
99888e3e3a7aSWarner Losh<p>
99898e3e3a7aSWarner LoshThis library provides generic functions for table manipulation.
99908e3e3a7aSWarner LoshIt provides all its functions inside the table <a name="pdf-table"><code>table</code></a>.
99918e3e3a7aSWarner Losh
99928e3e3a7aSWarner Losh
99938e3e3a7aSWarner Losh<p>
99948e3e3a7aSWarner LoshRemember that, whenever an operation needs the length of a table,
99958e3e3a7aSWarner Loshall caveats about the length operator apply (see <a href="#3.4.7">&sect;3.4.7</a>).
99968e3e3a7aSWarner LoshAll functions ignore non-numeric keys
99978e3e3a7aSWarner Loshin the tables given as arguments.
99988e3e3a7aSWarner Losh
99998e3e3a7aSWarner Losh
100008e3e3a7aSWarner Losh<p>
100018e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3>
100028e3e3a7aSWarner Losh
100038e3e3a7aSWarner Losh
100048e3e3a7aSWarner Losh<p>
100058e3e3a7aSWarner LoshGiven a list where all elements are strings or numbers,
100068e3e3a7aSWarner Loshreturns the string <code>list[i]..sep..list[i+1] &middot;&middot;&middot; sep..list[j]</code>.
100078e3e3a7aSWarner LoshThe default value for <code>sep</code> is the empty string,
100088e3e3a7aSWarner Loshthe default for <code>i</code> is 1,
100098e3e3a7aSWarner Loshand the default for <code>j</code> is <code>#list</code>.
100108e3e3a7aSWarner LoshIf <code>i</code> is greater than <code>j</code>, returns the empty string.
100118e3e3a7aSWarner Losh
100128e3e3a7aSWarner Losh
100138e3e3a7aSWarner Losh
100148e3e3a7aSWarner Losh
100158e3e3a7aSWarner Losh<p>
100168e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3>
100178e3e3a7aSWarner Losh
100188e3e3a7aSWarner Losh
100198e3e3a7aSWarner Losh<p>
100208e3e3a7aSWarner LoshInserts element <code>value</code> at position <code>pos</code> in <code>list</code>,
100218e3e3a7aSWarner Loshshifting up the elements
100228e3e3a7aSWarner Losh<code>list[pos], list[pos+1], &middot;&middot;&middot;, list[#list]</code>.
100238e3e3a7aSWarner LoshThe default value for <code>pos</code> is <code>#list+1</code>,
100248e3e3a7aSWarner Loshso that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end
100250495ed39SKyle Evansof the list <code>t</code>.
100268e3e3a7aSWarner Losh
100278e3e3a7aSWarner Losh
100288e3e3a7aSWarner Losh
100298e3e3a7aSWarner Losh
100308e3e3a7aSWarner Losh<p>
100318e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3>
100328e3e3a7aSWarner Losh
100338e3e3a7aSWarner Losh
100348e3e3a7aSWarner Losh<p>
100350495ed39SKyle EvansMoves elements from the table <code>a1</code> to the table <code>a2</code>,
100368e3e3a7aSWarner Loshperforming the equivalent to the following
100378e3e3a7aSWarner Loshmultiple assignment:
100388e3e3a7aSWarner Losh<code>a2[t],&middot;&middot;&middot; = a1[f],&middot;&middot;&middot;,a1[e]</code>.
100398e3e3a7aSWarner LoshThe default for <code>a2</code> is <code>a1</code>.
100408e3e3a7aSWarner LoshThe destination range can overlap with the source range.
100418e3e3a7aSWarner LoshThe number of elements to be moved must fit in a Lua integer.
100428e3e3a7aSWarner Losh
100438e3e3a7aSWarner Losh
100448e3e3a7aSWarner Losh<p>
100458e3e3a7aSWarner LoshReturns the destination table <code>a2</code>.
100468e3e3a7aSWarner Losh
100478e3e3a7aSWarner Losh
100488e3e3a7aSWarner Losh
100498e3e3a7aSWarner Losh
100508e3e3a7aSWarner Losh<p>
100518e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.pack"><code>table.pack (&middot;&middot;&middot;)</code></a></h3>
100528e3e3a7aSWarner Losh
100538e3e3a7aSWarner Losh
100548e3e3a7aSWarner Losh<p>
10055e112e9d2SKyle EvansReturns a new table with all arguments stored into keys 1, 2, etc.
10056e112e9d2SKyle Evansand with a field "<code>n</code>" with the total number of arguments.
100570495ed39SKyle EvansNote that the resulting table may not be a sequence,
100580495ed39SKyle Evansif some arguments are <b>nil</b>.
100598e3e3a7aSWarner Losh
100608e3e3a7aSWarner Losh
100618e3e3a7aSWarner Losh
100628e3e3a7aSWarner Losh
100638e3e3a7aSWarner Losh<p>
100648e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3>
100658e3e3a7aSWarner Losh
100668e3e3a7aSWarner Losh
100678e3e3a7aSWarner Losh<p>
100688e3e3a7aSWarner LoshRemoves from <code>list</code> the element at position <code>pos</code>,
100698e3e3a7aSWarner Loshreturning the value of the removed element.
100708e3e3a7aSWarner LoshWhen <code>pos</code> is an integer between 1 and <code>#list</code>,
100718e3e3a7aSWarner Loshit shifts down the elements
100728e3e3a7aSWarner Losh<code>list[pos+1], list[pos+2], &middot;&middot;&middot;, list[#list]</code>
100738e3e3a7aSWarner Loshand erases element <code>list[#list]</code>;
100748e3e3a7aSWarner LoshThe index <code>pos</code> can also be 0 when <code>#list</code> is 0,
100750495ed39SKyle Evansor <code>#list + 1</code>.
100768e3e3a7aSWarner Losh
100778e3e3a7aSWarner Losh
100788e3e3a7aSWarner Losh<p>
100798e3e3a7aSWarner LoshThe default value for <code>pos</code> is <code>#list</code>,
100808e3e3a7aSWarner Loshso that a call <code>table.remove(l)</code> removes the last element
100810495ed39SKyle Evansof the list <code>l</code>.
100828e3e3a7aSWarner Losh
100838e3e3a7aSWarner Losh
100848e3e3a7aSWarner Losh
100858e3e3a7aSWarner Losh
100868e3e3a7aSWarner Losh<p>
100878e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3>
100888e3e3a7aSWarner Losh
100898e3e3a7aSWarner Losh
100908e3e3a7aSWarner Losh<p>
100910495ed39SKyle EvansSorts the list elements in a given order, <em>in-place</em>,
100928e3e3a7aSWarner Loshfrom <code>list[1]</code> to <code>list[#list]</code>.
100938e3e3a7aSWarner LoshIf <code>comp</code> is given,
100948e3e3a7aSWarner Loshthen it must be a function that receives two list elements
100958e3e3a7aSWarner Loshand returns true when the first element must come
100968c784bb8SWarner Loshbefore the second in the final order,
100978c784bb8SWarner Loshso that, after the sort,
100988c784bb8SWarner Losh<code>i &lt;= j</code> implies <code>not comp(list[j],list[i])</code>.
100998e3e3a7aSWarner LoshIf <code>comp</code> is not given,
101008e3e3a7aSWarner Loshthen the standard Lua operator <code>&lt;</code> is used instead.
101018e3e3a7aSWarner Losh
101028e3e3a7aSWarner Losh
101038e3e3a7aSWarner Losh<p>
101048c784bb8SWarner LoshThe <code>comp</code> function must define a consistent order;
101058c784bb8SWarner Loshmore formally, the function must define a strict weak order.
101068c784bb8SWarner Losh(A weak order is similar to a total order,
101078c784bb8SWarner Loshbut it can equate different elements for comparison purposes.)
101088e3e3a7aSWarner Losh
101098e3e3a7aSWarner Losh
101108e3e3a7aSWarner Losh<p>
101118e3e3a7aSWarner LoshThe sort algorithm is not stable:
101128c784bb8SWarner LoshDifferent elements considered equal by the given order
101138e3e3a7aSWarner Loshmay have their relative positions changed by the sort.
101148e3e3a7aSWarner Losh
101158e3e3a7aSWarner Losh
101168e3e3a7aSWarner Losh
101178e3e3a7aSWarner Losh
101188e3e3a7aSWarner Losh<p>
101198e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3>
101208e3e3a7aSWarner Losh
101218e3e3a7aSWarner Losh
101228e3e3a7aSWarner Losh<p>
101238e3e3a7aSWarner LoshReturns the elements from the given list.
101248e3e3a7aSWarner LoshThis function is equivalent to
101258e3e3a7aSWarner Losh
101268e3e3a7aSWarner Losh<pre>
101278e3e3a7aSWarner Losh     return list[i], list[i+1], &middot;&middot;&middot;, list[j]
101288e3e3a7aSWarner Losh</pre><p>
101298e3e3a7aSWarner LoshBy default, <code>i</code> is&nbsp;1 and <code>j</code> is <code>#list</code>.
101308e3e3a7aSWarner Losh
101318e3e3a7aSWarner Losh
101328e3e3a7aSWarner Losh
101338e3e3a7aSWarner Losh
101348e3e3a7aSWarner Losh
101358e3e3a7aSWarner Losh
101368e3e3a7aSWarner Losh
101378e3e3a7aSWarner Losh<h2>6.7 &ndash; <a name="6.7">Mathematical Functions</a></h2>
101388e3e3a7aSWarner Losh
101398e3e3a7aSWarner Losh<p>
101408e3e3a7aSWarner LoshThis library provides basic mathematical functions.
101418e3e3a7aSWarner LoshIt provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>.
101428e3e3a7aSWarner LoshFunctions with the annotation "<code>integer/float</code>" give
101438e3e3a7aSWarner Loshinteger results for integer arguments
101440495ed39SKyle Evansand float results for non-integer arguments.
101450495ed39SKyle EvansThe rounding functions
101460495ed39SKyle 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>
101478e3e3a7aSWarner Loshreturn an integer when the result fits in the range of an integer,
101488e3e3a7aSWarner Loshor a float otherwise.
101498e3e3a7aSWarner Losh
101508e3e3a7aSWarner Losh
101518e3e3a7aSWarner Losh<p>
101528e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3>
101538e3e3a7aSWarner Losh
101548e3e3a7aSWarner Losh
101558e3e3a7aSWarner Losh<p>
101560495ed39SKyle EvansReturns the maximum value between <code>x</code> and <code>-x</code>. (integer/float)
101578e3e3a7aSWarner Losh
101588e3e3a7aSWarner Losh
101598e3e3a7aSWarner Losh
101608e3e3a7aSWarner Losh
101618e3e3a7aSWarner Losh<p>
101628e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3>
101638e3e3a7aSWarner Losh
101648e3e3a7aSWarner Losh
101658e3e3a7aSWarner Losh<p>
101668e3e3a7aSWarner LoshReturns the arc cosine of <code>x</code> (in radians).
101678e3e3a7aSWarner Losh
101688e3e3a7aSWarner Losh
101698e3e3a7aSWarner Losh
101708e3e3a7aSWarner Losh
101718e3e3a7aSWarner Losh<p>
101728e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3>
101738e3e3a7aSWarner Losh
101748e3e3a7aSWarner Losh
101758e3e3a7aSWarner Losh<p>
101768e3e3a7aSWarner LoshReturns the arc sine of <code>x</code> (in radians).
101778e3e3a7aSWarner Losh
101788e3e3a7aSWarner Losh
101798e3e3a7aSWarner Losh
101808e3e3a7aSWarner Losh
101818e3e3a7aSWarner Losh<p>
101828e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3>
101838e3e3a7aSWarner Losh
101848e3e3a7aSWarner Losh
101858e3e3a7aSWarner Losh<p>
101868e3e3a7aSWarner Losh
101878e3e3a7aSWarner LoshReturns the arc tangent of <code>y/x</code> (in radians),
10188a9490b81SWarner Loshusing the signs of both arguments to find the
101898e3e3a7aSWarner Loshquadrant of the result.
101900495ed39SKyle EvansIt also handles correctly the case of <code>x</code> being zero.
101918e3e3a7aSWarner Losh
101928e3e3a7aSWarner Losh
101938e3e3a7aSWarner Losh<p>
101948e3e3a7aSWarner LoshThe default value for <code>x</code> is 1,
101958e3e3a7aSWarner Loshso that the call <code>math.atan(y)</code>
101968e3e3a7aSWarner Loshreturns the arc tangent of <code>y</code>.
101978e3e3a7aSWarner Losh
101988e3e3a7aSWarner Losh
101998e3e3a7aSWarner Losh
102008e3e3a7aSWarner Losh
102018e3e3a7aSWarner Losh<p>
102028e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3>
102038e3e3a7aSWarner Losh
102048e3e3a7aSWarner Losh
102058e3e3a7aSWarner Losh<p>
102060495ed39SKyle EvansReturns the smallest integral value greater than or equal to <code>x</code>.
102078e3e3a7aSWarner Losh
102088e3e3a7aSWarner Losh
102098e3e3a7aSWarner Losh
102108e3e3a7aSWarner Losh
102118e3e3a7aSWarner Losh<p>
102128e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3>
102138e3e3a7aSWarner Losh
102148e3e3a7aSWarner Losh
102158e3e3a7aSWarner Losh<p>
102168e3e3a7aSWarner LoshReturns the cosine of <code>x</code> (assumed to be in radians).
102178e3e3a7aSWarner Losh
102188e3e3a7aSWarner Losh
102198e3e3a7aSWarner Losh
102208e3e3a7aSWarner Losh
102218e3e3a7aSWarner Losh<p>
102228e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3>
102238e3e3a7aSWarner Losh
102248e3e3a7aSWarner Losh
102258e3e3a7aSWarner Losh<p>
102268e3e3a7aSWarner LoshConverts the angle <code>x</code> from radians to degrees.
102278e3e3a7aSWarner Losh
102288e3e3a7aSWarner Losh
102298e3e3a7aSWarner Losh
102308e3e3a7aSWarner Losh
102318e3e3a7aSWarner Losh<p>
102328e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3>
102338e3e3a7aSWarner Losh
102348e3e3a7aSWarner Losh
102358e3e3a7aSWarner Losh<p>
102368e3e3a7aSWarner LoshReturns the value <em>e<sup>x</sup></em>
102378e3e3a7aSWarner Losh(where <code>e</code> is the base of natural logarithms).
102388e3e3a7aSWarner Losh
102398e3e3a7aSWarner Losh
102408e3e3a7aSWarner Losh
102418e3e3a7aSWarner Losh
102428e3e3a7aSWarner Losh<p>
102438e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3>
102448e3e3a7aSWarner Losh
102458e3e3a7aSWarner Losh
102468e3e3a7aSWarner Losh<p>
102470495ed39SKyle EvansReturns the largest integral value less than or equal to <code>x</code>.
102488e3e3a7aSWarner Losh
102498e3e3a7aSWarner Losh
102508e3e3a7aSWarner Losh
102518e3e3a7aSWarner Losh
102528e3e3a7aSWarner Losh<p>
102538e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3>
102548e3e3a7aSWarner Losh
102558e3e3a7aSWarner Losh
102568e3e3a7aSWarner Losh<p>
102578e3e3a7aSWarner LoshReturns the remainder of the division of <code>x</code> by <code>y</code>
102588e3e3a7aSWarner Loshthat rounds the quotient towards zero. (integer/float)
102598e3e3a7aSWarner Losh
102608e3e3a7aSWarner Losh
102618e3e3a7aSWarner Losh
102628e3e3a7aSWarner Losh
102638e3e3a7aSWarner Losh<p>
102648e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3>
102658e3e3a7aSWarner Losh
102668e3e3a7aSWarner Losh
102678e3e3a7aSWarner Losh<p>
102688e3e3a7aSWarner LoshThe float value <code>HUGE_VAL</code>,
102690495ed39SKyle Evansa value greater than any other numeric value.
102708e3e3a7aSWarner Losh
102718e3e3a7aSWarner Losh
102728e3e3a7aSWarner Losh
102738e3e3a7aSWarner Losh
102748e3e3a7aSWarner Losh<p>
102758e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3>
102768e3e3a7aSWarner Losh
102778e3e3a7aSWarner Losh
102788e3e3a7aSWarner Losh<p>
102798e3e3a7aSWarner LoshReturns the logarithm of <code>x</code> in the given base.
102808e3e3a7aSWarner LoshThe default for <code>base</code> is <em>e</em>
102818e3e3a7aSWarner Losh(so that the function returns the natural logarithm of <code>x</code>).
102828e3e3a7aSWarner Losh
102838e3e3a7aSWarner Losh
102848e3e3a7aSWarner Losh
102858e3e3a7aSWarner Losh
102868e3e3a7aSWarner Losh<p>
102878e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.max"><code>math.max (x, &middot;&middot;&middot;)</code></a></h3>
102888e3e3a7aSWarner Losh
102898e3e3a7aSWarner Losh
102908e3e3a7aSWarner Losh<p>
102918e3e3a7aSWarner LoshReturns the argument with the maximum value,
102920495ed39SKyle Evansaccording to the Lua operator <code>&lt;</code>.
102938e3e3a7aSWarner Losh
102948e3e3a7aSWarner Losh
102958e3e3a7aSWarner Losh
102968e3e3a7aSWarner Losh
102978e3e3a7aSWarner Losh<p>
102988e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3>
102998e3e3a7aSWarner LoshAn integer with the maximum value for an integer.
103008e3e3a7aSWarner Losh
103018e3e3a7aSWarner Losh
103028e3e3a7aSWarner Losh
103038e3e3a7aSWarner Losh
103048e3e3a7aSWarner Losh<p>
103058e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.min"><code>math.min (x, &middot;&middot;&middot;)</code></a></h3>
103068e3e3a7aSWarner Losh
103078e3e3a7aSWarner Losh
103088e3e3a7aSWarner Losh<p>
103098e3e3a7aSWarner LoshReturns the argument with the minimum value,
103100495ed39SKyle Evansaccording to the Lua operator <code>&lt;</code>.
103118e3e3a7aSWarner Losh
103128e3e3a7aSWarner Losh
103138e3e3a7aSWarner Losh
103148e3e3a7aSWarner Losh
103158e3e3a7aSWarner Losh<p>
103168e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3>
103178e3e3a7aSWarner LoshAn integer with the minimum value for an integer.
103188e3e3a7aSWarner Losh
103198e3e3a7aSWarner Losh
103208e3e3a7aSWarner Losh
103218e3e3a7aSWarner Losh
103228e3e3a7aSWarner Losh<p>
103238e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3>
103248e3e3a7aSWarner Losh
103258e3e3a7aSWarner Losh
103268e3e3a7aSWarner Losh<p>
103278e3e3a7aSWarner LoshReturns the integral part of <code>x</code> and the fractional part of <code>x</code>.
103288e3e3a7aSWarner LoshIts second result is always a float.
103298e3e3a7aSWarner Losh
103308e3e3a7aSWarner Losh
103318e3e3a7aSWarner Losh
103328e3e3a7aSWarner Losh
103338e3e3a7aSWarner Losh<p>
103348e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3>
103358e3e3a7aSWarner Losh
103368e3e3a7aSWarner Losh
103378e3e3a7aSWarner Losh<p>
103388e3e3a7aSWarner LoshThe value of <em>&pi;</em>.
103398e3e3a7aSWarner Losh
103408e3e3a7aSWarner Losh
103418e3e3a7aSWarner Losh
103428e3e3a7aSWarner Losh
103438e3e3a7aSWarner Losh<p>
103448e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3>
103458e3e3a7aSWarner Losh
103468e3e3a7aSWarner Losh
103478e3e3a7aSWarner Losh<p>
103488e3e3a7aSWarner LoshConverts the angle <code>x</code> from degrees to radians.
103498e3e3a7aSWarner Losh
103508e3e3a7aSWarner Losh
103518e3e3a7aSWarner Losh
103528e3e3a7aSWarner Losh
103538e3e3a7aSWarner Losh<p>
103548e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3>
103558e3e3a7aSWarner Losh
103568e3e3a7aSWarner Losh
103578e3e3a7aSWarner Losh<p>
103588e3e3a7aSWarner LoshWhen called without arguments,
103598e3e3a7aSWarner Loshreturns a pseudo-random float with uniform distribution
103608e3e3a7aSWarner Loshin the range  <em>[0,1)</em>.
103618e3e3a7aSWarner LoshWhen called with two integers <code>m</code> and <code>n</code>,
103628e3e3a7aSWarner Losh<code>math.random</code> returns a pseudo-random integer
103638e3e3a7aSWarner Loshwith uniform distribution in the range <em>[m, n]</em>.
103640495ed39SKyle EvansThe call <code>math.random(n)</code>, for a positive <code>n</code>,
103650495ed39SKyle Evansis equivalent to <code>math.random(1,n)</code>.
103660495ed39SKyle EvansThe call <code>math.random(0)</code> produces an integer with
103670495ed39SKyle Evansall bits (pseudo)random.
103688e3e3a7aSWarner Losh
103698e3e3a7aSWarner Losh
103708e3e3a7aSWarner Losh<p>
103710495ed39SKyle EvansThis function uses the <code>xoshiro256**</code> algorithm to produce
103720495ed39SKyle Evanspseudo-random 64-bit integers,
103730495ed39SKyle Evanswhich are the results of calls with argument&nbsp;0.
103740495ed39SKyle EvansOther results (ranges and floats)
103750495ed39SKyle Evansare unbiased extracted from these integers.
103760495ed39SKyle Evans
103770495ed39SKyle Evans
103780495ed39SKyle Evans<p>
103790495ed39SKyle EvansLua initializes its pseudo-random generator with the equivalent of
103800495ed39SKyle Evansa call to <a href="#pdf-math.randomseed"><code>math.randomseed</code></a> with no arguments,
103810495ed39SKyle Evansso that <code>math.random</code> should generate
103820495ed39SKyle Evansdifferent sequences of results each time the program runs.
103838e3e3a7aSWarner Losh
103848e3e3a7aSWarner Losh
103858e3e3a7aSWarner Losh
103868e3e3a7aSWarner Losh
103878e3e3a7aSWarner Losh<p>
103880495ed39SKyle Evans<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed ([x [, y]])</code></a></h3>
103898e3e3a7aSWarner Losh
103908e3e3a7aSWarner Losh
103918e3e3a7aSWarner Losh<p>
103920495ed39SKyle EvansWhen called with at least one argument,
103930495ed39SKyle Evansthe integer parameters <code>x</code> and <code>y</code> are
103940495ed39SKyle Evansjoined into a 128-bit <em>seed</em> that
103950495ed39SKyle Evansis used to reinitialize the pseudo-random generator;
103968e3e3a7aSWarner Loshequal seeds produce equal sequences of numbers.
103970495ed39SKyle EvansThe default for <code>y</code> is zero.
103980495ed39SKyle Evans
103990495ed39SKyle Evans
104000495ed39SKyle Evans<p>
104010495ed39SKyle EvansWhen called with no arguments,
104020495ed39SKyle EvansLua generates a seed with
104030495ed39SKyle Evansa weak attempt for randomness.
104040495ed39SKyle Evans
104050495ed39SKyle Evans
104060495ed39SKyle Evans<p>
104070495ed39SKyle EvansThis function returns the two seed components
104080495ed39SKyle Evansthat were effectively used,
104090495ed39SKyle Evansso that setting them again repeats the sequence.
104100495ed39SKyle Evans
104110495ed39SKyle Evans
104120495ed39SKyle Evans<p>
104130495ed39SKyle EvansTo ensure a required level of randomness to the initial state
104140495ed39SKyle Evans(or contrarily, to have a deterministic sequence,
104150495ed39SKyle Evansfor instance when debugging a program),
104160495ed39SKyle Evansyou should call <a href="#pdf-math.randomseed"><code>math.randomseed</code></a> with explicit arguments.
104178e3e3a7aSWarner Losh
104188e3e3a7aSWarner Losh
104198e3e3a7aSWarner Losh
104208e3e3a7aSWarner Losh
104218e3e3a7aSWarner Losh<p>
104228e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3>
104238e3e3a7aSWarner Losh
104248e3e3a7aSWarner Losh
104258e3e3a7aSWarner Losh<p>
104268e3e3a7aSWarner LoshReturns the sine of <code>x</code> (assumed to be in radians).
104278e3e3a7aSWarner Losh
104288e3e3a7aSWarner Losh
104298e3e3a7aSWarner Losh
104308e3e3a7aSWarner Losh
104318e3e3a7aSWarner Losh<p>
104328e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3>
104338e3e3a7aSWarner Losh
104348e3e3a7aSWarner Losh
104358e3e3a7aSWarner Losh<p>
104368e3e3a7aSWarner LoshReturns the square root of <code>x</code>.
104378e3e3a7aSWarner Losh(You can also use the expression <code>x^0.5</code> to compute this value.)
104388e3e3a7aSWarner Losh
104398e3e3a7aSWarner Losh
104408e3e3a7aSWarner Losh
104418e3e3a7aSWarner Losh
104428e3e3a7aSWarner Losh<p>
104438e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3>
104448e3e3a7aSWarner Losh
104458e3e3a7aSWarner Losh
104468e3e3a7aSWarner Losh<p>
104478e3e3a7aSWarner LoshReturns the tangent of <code>x</code> (assumed to be in radians).
104488e3e3a7aSWarner Losh
104498e3e3a7aSWarner Losh
104508e3e3a7aSWarner Losh
104518e3e3a7aSWarner Losh
104528e3e3a7aSWarner Losh<p>
104538e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3>
104548e3e3a7aSWarner Losh
104558e3e3a7aSWarner Losh
104568e3e3a7aSWarner Losh<p>
104578e3e3a7aSWarner LoshIf the value <code>x</code> is convertible to an integer,
104588e3e3a7aSWarner Loshreturns that integer.
104590495ed39SKyle EvansOtherwise, returns <b>fail</b>.
104608e3e3a7aSWarner Losh
104618e3e3a7aSWarner Losh
104628e3e3a7aSWarner Losh
104638e3e3a7aSWarner Losh
104648e3e3a7aSWarner Losh<p>
104658e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3>
104668e3e3a7aSWarner Losh
104678e3e3a7aSWarner Losh
104688e3e3a7aSWarner Losh<p>
104698e3e3a7aSWarner LoshReturns "<code>integer</code>" if <code>x</code> is an integer,
104708e3e3a7aSWarner Losh"<code>float</code>" if it is a float,
104710495ed39SKyle Evansor <b>fail</b> if <code>x</code> is not a number.
104728e3e3a7aSWarner Losh
104738e3e3a7aSWarner Losh
104748e3e3a7aSWarner Losh
104758e3e3a7aSWarner Losh
104768e3e3a7aSWarner Losh<p>
104778e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3>
104788e3e3a7aSWarner Losh
104798e3e3a7aSWarner Losh
104808e3e3a7aSWarner Losh<p>
104818e3e3a7aSWarner LoshReturns a boolean,
104828c784bb8SWarner Losh<b>true</b> if and only if integer <code>m</code> is below integer <code>n</code> when
104838e3e3a7aSWarner Loshthey are compared as unsigned integers.
104848e3e3a7aSWarner Losh
104858e3e3a7aSWarner Losh
104868e3e3a7aSWarner Losh
104878e3e3a7aSWarner Losh
104888e3e3a7aSWarner Losh
104898e3e3a7aSWarner Losh
104908e3e3a7aSWarner Losh
104918e3e3a7aSWarner Losh<h2>6.8 &ndash; <a name="6.8">Input and Output Facilities</a></h2>
104928e3e3a7aSWarner Losh
104938e3e3a7aSWarner Losh<p>
104948e3e3a7aSWarner LoshThe I/O library provides two different styles for file manipulation.
104958e3e3a7aSWarner LoshThe first one uses implicit file handles;
104968e3e3a7aSWarner Loshthat is, there are operations to set a default input file and a
104978e3e3a7aSWarner Loshdefault output file,
104980495ed39SKyle Evansand all input/output operations are done over these default files.
104998e3e3a7aSWarner LoshThe second style uses explicit file handles.
105008e3e3a7aSWarner Losh
105018e3e3a7aSWarner Losh
105028e3e3a7aSWarner Losh<p>
105038e3e3a7aSWarner LoshWhen using implicit file handles,
105048e3e3a7aSWarner Loshall operations are supplied by table <a name="pdf-io"><code>io</code></a>.
105058e3e3a7aSWarner LoshWhen using explicit file handles,
105068e3e3a7aSWarner Loshthe operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle
105078e3e3a7aSWarner Loshand then all operations are supplied as methods of the file handle.
105088e3e3a7aSWarner Losh
105098e3e3a7aSWarner Losh
105108e3e3a7aSWarner Losh<p>
105110495ed39SKyle EvansThe metatable for file handles provides metamethods
105120495ed39SKyle Evansfor <code>__gc</code> and <code>__close</code> that try
105130495ed39SKyle Evansto close the file when called.
105140495ed39SKyle Evans
105150495ed39SKyle Evans
105160495ed39SKyle Evans<p>
105178e3e3a7aSWarner LoshThe table <code>io</code> also provides
105188e3e3a7aSWarner Loshthree predefined file handles with their usual meanings from C:
105198e3e3a7aSWarner 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>.
105208e3e3a7aSWarner LoshThe I/O library never closes these files.
105218e3e3a7aSWarner Losh
105228e3e3a7aSWarner Losh
105238e3e3a7aSWarner Losh<p>
105248e3e3a7aSWarner LoshUnless otherwise stated,
105250495ed39SKyle Evansall I/O functions return <b>fail</b> on failure,
105260495ed39SKyle Evansplus an error message as a second result and
105270495ed39SKyle Evansa system-dependent error code as a third result,
105280495ed39SKyle Evansand some non-false value on success.
105290495ed39SKyle EvansOn non-POSIX systems,
105308e3e3a7aSWarner Loshthe computation of the error message and error code
105318e3e3a7aSWarner Loshin case of errors
105328e3e3a7aSWarner Loshmay be not thread safe,
105338e3e3a7aSWarner Loshbecause they rely on the global C variable <code>errno</code>.
105348e3e3a7aSWarner Losh
105358e3e3a7aSWarner Losh
105368e3e3a7aSWarner Losh<p>
105378e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3>
105388e3e3a7aSWarner Losh
105398e3e3a7aSWarner Losh
105408e3e3a7aSWarner Losh<p>
105418e3e3a7aSWarner LoshEquivalent to <code>file:close()</code>.
105428e3e3a7aSWarner LoshWithout a <code>file</code>, closes the default output file.
105438e3e3a7aSWarner Losh
105448e3e3a7aSWarner Losh
105458e3e3a7aSWarner Losh
105468e3e3a7aSWarner Losh
105478e3e3a7aSWarner Losh<p>
105488e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3>
105498e3e3a7aSWarner Losh
105508e3e3a7aSWarner Losh
105518e3e3a7aSWarner Losh<p>
105528e3e3a7aSWarner LoshEquivalent to <code>io.output():flush()</code>.
105538e3e3a7aSWarner Losh
105548e3e3a7aSWarner Losh
105558e3e3a7aSWarner Losh
105568e3e3a7aSWarner Losh
105578e3e3a7aSWarner Losh<p>
105588e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3>
105598e3e3a7aSWarner Losh
105608e3e3a7aSWarner Losh
105618e3e3a7aSWarner Losh<p>
105628e3e3a7aSWarner LoshWhen called with a file name, it opens the named file (in text mode),
105638e3e3a7aSWarner Loshand sets its handle as the default input file.
105648e3e3a7aSWarner LoshWhen called with a file handle,
105658e3e3a7aSWarner Loshit simply sets this file handle as the default input file.
10566e112e9d2SKyle EvansWhen called without arguments,
105678e3e3a7aSWarner Loshit returns the current default input file.
105688e3e3a7aSWarner Losh
105698e3e3a7aSWarner Losh
105708e3e3a7aSWarner Losh<p>
105718e3e3a7aSWarner LoshIn case of errors this function raises the error,
105728e3e3a7aSWarner Loshinstead of returning an error code.
105738e3e3a7aSWarner Losh
105748e3e3a7aSWarner Losh
105758e3e3a7aSWarner Losh
105768e3e3a7aSWarner Losh
105778e3e3a7aSWarner Losh<p>
105788e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, &middot;&middot;&middot;])</code></a></h3>
105798e3e3a7aSWarner Losh
105808e3e3a7aSWarner Losh
105818e3e3a7aSWarner Losh<p>
105828e3e3a7aSWarner LoshOpens the given file name in read mode
105838e3e3a7aSWarner Loshand returns an iterator function that
105848e3e3a7aSWarner Loshworks like <code>file:lines(&middot;&middot;&middot;)</code> over the opened file.
105850495ed39SKyle EvansWhen the iterator function fails to read any value,
105860495ed39SKyle Evansit automatically closes the file.
105870495ed39SKyle EvansBesides the iterator function,
105880495ed39SKyle Evans<code>io.lines</code> returns three other values:
105890495ed39SKyle Evanstwo <b>nil</b> values as placeholders,
105900495ed39SKyle Evansplus the created file handle.
105910495ed39SKyle EvansTherefore, when used in a generic <b>for</b> loop,
105920495ed39SKyle Evansthe file is closed also if the loop is interrupted by an
105930495ed39SKyle Evanserror or a <b>break</b>.
105948e3e3a7aSWarner Losh
105958e3e3a7aSWarner Losh
105968e3e3a7aSWarner Losh<p>
105978e3e3a7aSWarner LoshThe call <code>io.lines()</code> (with no file name) is equivalent
105980495ed39SKyle Evansto <code>io.input():lines("l")</code>;
105998e3e3a7aSWarner Loshthat is, it iterates over the lines of the default input file.
10600e112e9d2SKyle EvansIn this case, the iterator does not close the file when the loop ends.
106018e3e3a7aSWarner Losh
106028e3e3a7aSWarner Losh
106038e3e3a7aSWarner Losh<p>
106040495ed39SKyle EvansIn case of errors opening the file,
106050495ed39SKyle Evansthis function raises the error,
106068e3e3a7aSWarner Loshinstead of returning an error code.
106078e3e3a7aSWarner Losh
106088e3e3a7aSWarner Losh
106098e3e3a7aSWarner Losh
106108e3e3a7aSWarner Losh
106118e3e3a7aSWarner Losh<p>
106128e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3>
106138e3e3a7aSWarner Losh
106148e3e3a7aSWarner Losh
106158e3e3a7aSWarner Losh<p>
106168e3e3a7aSWarner LoshThis function opens a file,
106178e3e3a7aSWarner Loshin the mode specified in the string <code>mode</code>.
106188e3e3a7aSWarner LoshIn case of success,
106198e3e3a7aSWarner Loshit returns a new file handle.
106208e3e3a7aSWarner Losh
106218e3e3a7aSWarner Losh
106228e3e3a7aSWarner Losh<p>
106238e3e3a7aSWarner LoshThe <code>mode</code> string can be any of the following:
106248e3e3a7aSWarner Losh
106258e3e3a7aSWarner Losh<ul>
106268e3e3a7aSWarner Losh<li><b>"<code>r</code>": </b> read mode (the default);</li>
106278e3e3a7aSWarner Losh<li><b>"<code>w</code>": </b> write mode;</li>
106288e3e3a7aSWarner Losh<li><b>"<code>a</code>": </b> append mode;</li>
106298e3e3a7aSWarner Losh<li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li>
106308e3e3a7aSWarner Losh<li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li>
106318e3e3a7aSWarner Losh<li><b>"<code>a+</code>": </b> append update mode, previous data is preserved,
106328e3e3a7aSWarner Losh  writing is only allowed at the end of file.</li>
106338e3e3a7aSWarner Losh</ul><p>
106348e3e3a7aSWarner LoshThe <code>mode</code> string can also have a '<code>b</code>' at the end,
106358e3e3a7aSWarner Loshwhich is needed in some systems to open the file in binary mode.
106368e3e3a7aSWarner Losh
106378e3e3a7aSWarner Losh
106388e3e3a7aSWarner Losh
106398e3e3a7aSWarner Losh
106408e3e3a7aSWarner Losh<p>
106418e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3>
106428e3e3a7aSWarner Losh
106438e3e3a7aSWarner Losh
106448e3e3a7aSWarner Losh<p>
106458e3e3a7aSWarner LoshSimilar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file.
106468e3e3a7aSWarner Losh
106478e3e3a7aSWarner Losh
106488e3e3a7aSWarner Losh
106498e3e3a7aSWarner Losh
106508e3e3a7aSWarner Losh<p>
106518e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3>
106528e3e3a7aSWarner Losh
106538e3e3a7aSWarner Losh
106548e3e3a7aSWarner Losh<p>
106558e3e3a7aSWarner LoshThis function is system dependent and is not available
106568e3e3a7aSWarner Loshon all platforms.
106578e3e3a7aSWarner Losh
106588e3e3a7aSWarner Losh
106598e3e3a7aSWarner Losh<p>
106600495ed39SKyle EvansStarts the program <code>prog</code> in a separated process and returns
106618e3e3a7aSWarner Losha file handle that you can use to read data from this program
106628e3e3a7aSWarner Losh(if <code>mode</code> is <code>"r"</code>, the default)
106638e3e3a7aSWarner Loshor to write data to this program
106648e3e3a7aSWarner Losh(if <code>mode</code> is <code>"w"</code>).
106658e3e3a7aSWarner Losh
106668e3e3a7aSWarner Losh
106678e3e3a7aSWarner Losh
106688e3e3a7aSWarner Losh
106698e3e3a7aSWarner Losh<p>
106708e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.read"><code>io.read (&middot;&middot;&middot;)</code></a></h3>
106718e3e3a7aSWarner Losh
106728e3e3a7aSWarner Losh
106738e3e3a7aSWarner Losh<p>
106748e3e3a7aSWarner LoshEquivalent to <code>io.input():read(&middot;&middot;&middot;)</code>.
106758e3e3a7aSWarner Losh
106768e3e3a7aSWarner Losh
106778e3e3a7aSWarner Losh
106788e3e3a7aSWarner Losh
106798e3e3a7aSWarner Losh<p>
106808e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3>
106818e3e3a7aSWarner Losh
106828e3e3a7aSWarner Losh
106838e3e3a7aSWarner Losh<p>
106848e3e3a7aSWarner LoshIn case of success,
106858e3e3a7aSWarner Loshreturns a handle for a temporary file.
106868e3e3a7aSWarner LoshThis file is opened in update mode
106878e3e3a7aSWarner Loshand it is automatically removed when the program ends.
106888e3e3a7aSWarner Losh
106898e3e3a7aSWarner Losh
106908e3e3a7aSWarner Losh
106918e3e3a7aSWarner Losh
106928e3e3a7aSWarner Losh<p>
106938e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3>
106948e3e3a7aSWarner Losh
106958e3e3a7aSWarner Losh
106968e3e3a7aSWarner Losh<p>
106978e3e3a7aSWarner LoshChecks whether <code>obj</code> is a valid file handle.
106988e3e3a7aSWarner LoshReturns the string <code>"file"</code> if <code>obj</code> is an open file handle,
106998e3e3a7aSWarner Losh<code>"closed file"</code> if <code>obj</code> is a closed file handle,
107000495ed39SKyle Evansor <b>fail</b> if <code>obj</code> is not a file handle.
107018e3e3a7aSWarner Losh
107028e3e3a7aSWarner Losh
107038e3e3a7aSWarner Losh
107048e3e3a7aSWarner Losh
107058e3e3a7aSWarner Losh<p>
107068e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.write"><code>io.write (&middot;&middot;&middot;)</code></a></h3>
107078e3e3a7aSWarner Losh
107088e3e3a7aSWarner Losh
107098e3e3a7aSWarner Losh<p>
107108e3e3a7aSWarner LoshEquivalent to <code>io.output():write(&middot;&middot;&middot;)</code>.
107118e3e3a7aSWarner Losh
107128e3e3a7aSWarner Losh
107138e3e3a7aSWarner Losh
107148e3e3a7aSWarner Losh
107158e3e3a7aSWarner Losh<p>
107168e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3>
107178e3e3a7aSWarner Losh
107188e3e3a7aSWarner Losh
107198e3e3a7aSWarner Losh<p>
107208e3e3a7aSWarner LoshCloses <code>file</code>.
107218e3e3a7aSWarner LoshNote that files are automatically closed when
107228e3e3a7aSWarner Loshtheir handles are garbage collected,
107238e3e3a7aSWarner Loshbut that takes an unpredictable amount of time to happen.
107248e3e3a7aSWarner Losh
107258e3e3a7aSWarner Losh
107268e3e3a7aSWarner Losh<p>
107278e3e3a7aSWarner LoshWhen closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>,
107288e3e3a7aSWarner Losh<a href="#pdf-file:close"><code>file:close</code></a> returns the same values
107298e3e3a7aSWarner Loshreturned by <a href="#pdf-os.execute"><code>os.execute</code></a>.
107308e3e3a7aSWarner Losh
107318e3e3a7aSWarner Losh
107328e3e3a7aSWarner Losh
107338e3e3a7aSWarner Losh
107348e3e3a7aSWarner Losh<p>
107358e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3>
107368e3e3a7aSWarner Losh
107378e3e3a7aSWarner Losh
107388e3e3a7aSWarner Losh<p>
107398e3e3a7aSWarner LoshSaves any written data to <code>file</code>.
107408e3e3a7aSWarner Losh
107418e3e3a7aSWarner Losh
107428e3e3a7aSWarner Losh
107438e3e3a7aSWarner Losh
107448e3e3a7aSWarner Losh<p>
107458e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:lines"><code>file:lines (&middot;&middot;&middot;)</code></a></h3>
107468e3e3a7aSWarner Losh
107478e3e3a7aSWarner Losh
107488e3e3a7aSWarner Losh<p>
107498e3e3a7aSWarner LoshReturns an iterator function that,
107508e3e3a7aSWarner Losheach time it is called,
107518e3e3a7aSWarner Loshreads the file according to the given formats.
107528e3e3a7aSWarner LoshWhen no format is given,
107538e3e3a7aSWarner Loshuses "<code>l</code>" as a default.
107548e3e3a7aSWarner LoshAs an example, the construction
107558e3e3a7aSWarner Losh
107568e3e3a7aSWarner Losh<pre>
107578e3e3a7aSWarner Losh     for c in file:lines(1) do <em>body</em> end
107588e3e3a7aSWarner Losh</pre><p>
107598e3e3a7aSWarner Loshwill iterate over all characters of the file,
107608e3e3a7aSWarner Loshstarting at the current position.
107618e3e3a7aSWarner LoshUnlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
107628e3e3a7aSWarner Loshwhen the loop ends.
107638e3e3a7aSWarner Losh
107648e3e3a7aSWarner Losh
107658e3e3a7aSWarner Losh
107668e3e3a7aSWarner Losh
107678e3e3a7aSWarner Losh<p>
107688e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:read"><code>file:read (&middot;&middot;&middot;)</code></a></h3>
107698e3e3a7aSWarner Losh
107708e3e3a7aSWarner Losh
107718e3e3a7aSWarner Losh<p>
107728e3e3a7aSWarner LoshReads the file <code>file</code>,
107738e3e3a7aSWarner Loshaccording to the given formats, which specify what to read.
107748e3e3a7aSWarner LoshFor each format,
107758e3e3a7aSWarner Loshthe function returns a string or a number with the characters read,
107760495ed39SKyle Evansor <b>fail</b> if it cannot read data with the specified format.
107778e3e3a7aSWarner Losh(In this latter case,
107788e3e3a7aSWarner Loshthe function does not read subsequent formats.)
107790495ed39SKyle EvansWhen called without arguments,
107808e3e3a7aSWarner Loshit uses a default format that reads the next line
107818e3e3a7aSWarner Losh(see below).
107828e3e3a7aSWarner Losh
107838e3e3a7aSWarner Losh
107848e3e3a7aSWarner Losh<p>
107858e3e3a7aSWarner LoshThe available formats are
107868e3e3a7aSWarner Losh
107878e3e3a7aSWarner Losh<ul>
107888e3e3a7aSWarner Losh
107898e3e3a7aSWarner Losh<li><b>"<code>n</code>": </b>
107908e3e3a7aSWarner Loshreads a numeral and returns it as a float or an integer,
107918e3e3a7aSWarner Loshfollowing the lexical conventions of Lua.
107920495ed39SKyle Evans(The numeral may have leading whitespaces and a sign.)
107938e3e3a7aSWarner LoshThis format always reads the longest input sequence that
107948e3e3a7aSWarner Loshis a valid prefix for a numeral;
107958e3e3a7aSWarner Loshif that prefix does not form a valid numeral
107960495ed39SKyle Evans(e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>")
107970495ed39SKyle Evansor it is too long (more than 200 characters),
107980495ed39SKyle Evansit is discarded and the format returns <b>fail</b>.
107998e3e3a7aSWarner Losh</li>
108008e3e3a7aSWarner Losh
108018e3e3a7aSWarner Losh<li><b>"<code>a</code>": </b>
108028e3e3a7aSWarner Loshreads the whole file, starting at the current position.
108030495ed39SKyle EvansOn end of file, it returns the empty string;
108040495ed39SKyle Evansthis format never fails.
108058e3e3a7aSWarner Losh</li>
108068e3e3a7aSWarner Losh
108078e3e3a7aSWarner Losh<li><b>"<code>l</code>": </b>
108088e3e3a7aSWarner Loshreads the next line skipping the end of line,
108090495ed39SKyle Evansreturning <b>fail</b> on end of file.
108108e3e3a7aSWarner LoshThis is the default format.
108118e3e3a7aSWarner Losh</li>
108128e3e3a7aSWarner Losh
108138e3e3a7aSWarner Losh<li><b>"<code>L</code>": </b>
108148e3e3a7aSWarner Loshreads the next line keeping the end-of-line character (if present),
108150495ed39SKyle Evansreturning <b>fail</b> on end of file.
108168e3e3a7aSWarner Losh</li>
108178e3e3a7aSWarner Losh
108188e3e3a7aSWarner Losh<li><b><em>number</em>: </b>
108198e3e3a7aSWarner Loshreads a string with up to this number of bytes,
108200495ed39SKyle Evansreturning <b>fail</b> on end of file.
108218e3e3a7aSWarner LoshIf <code>number</code> is zero,
108228e3e3a7aSWarner Loshit reads nothing and returns an empty string,
108230495ed39SKyle Evansor <b>fail</b> on end of file.
108248e3e3a7aSWarner Losh</li>
108258e3e3a7aSWarner Losh
108268e3e3a7aSWarner Losh</ul><p>
108278e3e3a7aSWarner LoshThe formats "<code>l</code>" and "<code>L</code>" should be used only for text files.
108288e3e3a7aSWarner Losh
108298e3e3a7aSWarner Losh
108308e3e3a7aSWarner Losh
108318e3e3a7aSWarner Losh
108328e3e3a7aSWarner Losh<p>
108338e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3>
108348e3e3a7aSWarner Losh
108358e3e3a7aSWarner Losh
108368e3e3a7aSWarner Losh<p>
108378e3e3a7aSWarner LoshSets and gets the file position,
108388e3e3a7aSWarner Loshmeasured from the beginning of the file,
108398e3e3a7aSWarner Loshto the position given by <code>offset</code> plus a base
108408e3e3a7aSWarner Loshspecified by the string <code>whence</code>, as follows:
108418e3e3a7aSWarner Losh
108428e3e3a7aSWarner Losh<ul>
108438e3e3a7aSWarner Losh<li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li>
108448e3e3a7aSWarner Losh<li><b>"<code>cur</code>": </b> base is current position;</li>
108458e3e3a7aSWarner Losh<li><b>"<code>end</code>": </b> base is end of file;</li>
108468e3e3a7aSWarner Losh</ul><p>
108478e3e3a7aSWarner LoshIn case of success, <code>seek</code> returns the final file position,
108488e3e3a7aSWarner Loshmeasured in bytes from the beginning of the file.
108490495ed39SKyle EvansIf <code>seek</code> fails, it returns <b>fail</b>,
108508e3e3a7aSWarner Loshplus a string describing the error.
108518e3e3a7aSWarner Losh
108528e3e3a7aSWarner Losh
108538e3e3a7aSWarner Losh<p>
108548e3e3a7aSWarner LoshThe default value for <code>whence</code> is <code>"cur"</code>,
108558e3e3a7aSWarner Loshand for <code>offset</code> is 0.
108568e3e3a7aSWarner LoshTherefore, the call <code>file:seek()</code> returns the current
108578e3e3a7aSWarner Loshfile position, without changing it;
108588e3e3a7aSWarner Loshthe call <code>file:seek("set")</code> sets the position to the
108598e3e3a7aSWarner Loshbeginning of the file (and returns 0);
108608e3e3a7aSWarner Loshand the call <code>file:seek("end")</code> sets the position to the
108618e3e3a7aSWarner Loshend of the file, and returns its size.
108628e3e3a7aSWarner Losh
108638e3e3a7aSWarner Losh
108648e3e3a7aSWarner Losh
108658e3e3a7aSWarner Losh
108668e3e3a7aSWarner Losh<p>
108678e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3>
108688e3e3a7aSWarner Losh
108698e3e3a7aSWarner Losh
108708e3e3a7aSWarner Losh<p>
108710495ed39SKyle EvansSets the buffering mode for a file.
108728e3e3a7aSWarner LoshThere are three available modes:
108738e3e3a7aSWarner Losh
108748e3e3a7aSWarner Losh<ul>
108750495ed39SKyle Evans<li><b>"<code>no</code>": </b> no buffering.</li>
108760495ed39SKyle Evans<li><b>"<code>full</code>": </b> full buffering.</li>
108770495ed39SKyle Evans<li><b>"<code>line</code>": </b> line buffering.</li>
108780495ed39SKyle Evans</ul>
108798e3e3a7aSWarner Losh
108800495ed39SKyle Evans<p>
108810495ed39SKyle EvansFor the last two cases,
108820495ed39SKyle Evans<code>size</code> is a hint for the size of the buffer, in bytes.
108838e3e3a7aSWarner LoshThe default is an appropriate size.
108848e3e3a7aSWarner Losh
108858e3e3a7aSWarner Losh
108860495ed39SKyle Evans<p>
108870495ed39SKyle EvansThe specific behavior of each mode is non portable;
108880495ed39SKyle Evanscheck the underlying ISO&nbsp;C function <code>setvbuf</code> in your platform for
108890495ed39SKyle Evansmore details.
108900495ed39SKyle Evans
108910495ed39SKyle Evans
108928e3e3a7aSWarner Losh
108938e3e3a7aSWarner Losh
108948e3e3a7aSWarner Losh<p>
108958e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:write"><code>file:write (&middot;&middot;&middot;)</code></a></h3>
108968e3e3a7aSWarner Losh
108978e3e3a7aSWarner Losh
108988e3e3a7aSWarner Losh<p>
108998e3e3a7aSWarner LoshWrites the value of each of its arguments to <code>file</code>.
109008e3e3a7aSWarner LoshThe arguments must be strings or numbers.
109018e3e3a7aSWarner Losh
109028e3e3a7aSWarner Losh
109038e3e3a7aSWarner Losh<p>
109048e3e3a7aSWarner LoshIn case of success, this function returns <code>file</code>.
109058e3e3a7aSWarner Losh
109068e3e3a7aSWarner Losh
109078e3e3a7aSWarner Losh
109088e3e3a7aSWarner Losh
109098e3e3a7aSWarner Losh
109108e3e3a7aSWarner Losh
109118e3e3a7aSWarner Losh
109128e3e3a7aSWarner Losh<h2>6.9 &ndash; <a name="6.9">Operating System Facilities</a></h2>
109138e3e3a7aSWarner Losh
109148e3e3a7aSWarner Losh<p>
109158e3e3a7aSWarner LoshThis library is implemented through table <a name="pdf-os"><code>os</code></a>.
109168e3e3a7aSWarner Losh
109178e3e3a7aSWarner Losh
109188e3e3a7aSWarner Losh<p>
109198e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3>
109208e3e3a7aSWarner Losh
109218e3e3a7aSWarner Losh
109228e3e3a7aSWarner Losh<p>
109238e3e3a7aSWarner LoshReturns an approximation of the amount in seconds of CPU time
109240495ed39SKyle Evansused by the program,
109250495ed39SKyle Evansas returned by the underlying ISO&nbsp;C function <code>clock</code>.
109268e3e3a7aSWarner Losh
109278e3e3a7aSWarner Losh
109288e3e3a7aSWarner Losh
109298e3e3a7aSWarner Losh
109308e3e3a7aSWarner Losh<p>
109318e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3>
109328e3e3a7aSWarner Losh
109338e3e3a7aSWarner Losh
109348e3e3a7aSWarner Losh<p>
109358e3e3a7aSWarner LoshReturns a string or a table containing date and time,
109368e3e3a7aSWarner Loshformatted according to the given string <code>format</code>.
109378e3e3a7aSWarner Losh
109388e3e3a7aSWarner Losh
109398e3e3a7aSWarner Losh<p>
109408e3e3a7aSWarner LoshIf the <code>time</code> argument is present,
109418e3e3a7aSWarner Loshthis is the time to be formatted
109428e3e3a7aSWarner Losh(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
109438e3e3a7aSWarner LoshOtherwise, <code>date</code> formats the current time.
109448e3e3a7aSWarner Losh
109458e3e3a7aSWarner Losh
109468e3e3a7aSWarner Losh<p>
109478e3e3a7aSWarner LoshIf <code>format</code> starts with '<code>!</code>',
109488e3e3a7aSWarner Loshthen the date is formatted in Coordinated Universal Time.
109498e3e3a7aSWarner LoshAfter this optional character,
109508e3e3a7aSWarner Loshif <code>format</code> is the string "<code>*t</code>",
109518e3e3a7aSWarner Loshthen <code>date</code> returns a table with the following fields:
109528e3e3a7aSWarner Losh<code>year</code>, <code>month</code> (1&ndash;12), <code>day</code> (1&ndash;31),
109530495ed39SKyle Evans<code>hour</code> (0&ndash;23), <code>min</code> (0&ndash;59),
109540495ed39SKyle Evans<code>sec</code> (0&ndash;61, due to leap seconds),
109558e3e3a7aSWarner Losh<code>wday</code> (weekday, 1&ndash;7, Sunday is&nbsp;1),
109568e3e3a7aSWarner Losh<code>yday</code> (day of the year, 1&ndash;366),
109578e3e3a7aSWarner Loshand <code>isdst</code> (daylight saving flag, a boolean).
109588e3e3a7aSWarner LoshThis last field may be absent
109598e3e3a7aSWarner Loshif the information is not available.
109608e3e3a7aSWarner Losh
109618e3e3a7aSWarner Losh
109628e3e3a7aSWarner Losh<p>
109638e3e3a7aSWarner LoshIf <code>format</code> is not "<code>*t</code>",
109648e3e3a7aSWarner Loshthen <code>date</code> returns the date as a string,
109658e3e3a7aSWarner Loshformatted according to the same rules as the ISO&nbsp;C function <code>strftime</code>.
109668e3e3a7aSWarner Losh
109678e3e3a7aSWarner Losh
109688e3e3a7aSWarner Losh<p>
109690495ed39SKyle EvansIf <code>format</code> is absent, it defaults to "<code>%c</code>",
109700495ed39SKyle Evanswhich gives a human-readable date and time representation
109710495ed39SKyle Evansusing the current locale.
109728e3e3a7aSWarner Losh
109738e3e3a7aSWarner Losh
109748e3e3a7aSWarner Losh<p>
109750495ed39SKyle EvansOn non-POSIX systems,
109768e3e3a7aSWarner Loshthis function may be not thread safe
109778e3e3a7aSWarner Loshbecause of its reliance on C&nbsp;function <code>gmtime</code> and C&nbsp;function <code>localtime</code>.
109788e3e3a7aSWarner Losh
109798e3e3a7aSWarner Losh
109808e3e3a7aSWarner Losh
109818e3e3a7aSWarner Losh
109828e3e3a7aSWarner Losh<p>
109838e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>
109848e3e3a7aSWarner Losh
109858e3e3a7aSWarner Losh
109868e3e3a7aSWarner Losh<p>
109878e3e3a7aSWarner LoshReturns the difference, in seconds,
109888e3e3a7aSWarner Loshfrom time <code>t1</code> to time <code>t2</code>
109898e3e3a7aSWarner Losh(where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>).
109908e3e3a7aSWarner LoshIn POSIX, Windows, and some other systems,
109918e3e3a7aSWarner Loshthis value is exactly <code>t2</code><em>-</em><code>t1</code>.
109928e3e3a7aSWarner Losh
109938e3e3a7aSWarner Losh
109948e3e3a7aSWarner Losh
109958e3e3a7aSWarner Losh
109968e3e3a7aSWarner Losh<p>
109978e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3>
109988e3e3a7aSWarner Losh
109998e3e3a7aSWarner Losh
110008e3e3a7aSWarner Losh<p>
110018e3e3a7aSWarner LoshThis function is equivalent to the ISO&nbsp;C function <code>system</code>.
110028e3e3a7aSWarner LoshIt passes <code>command</code> to be executed by an operating system shell.
110038e3e3a7aSWarner LoshIts first result is <b>true</b>
110048e3e3a7aSWarner Loshif the command terminated successfully,
110050495ed39SKyle Evansor <b>fail</b> otherwise.
110068e3e3a7aSWarner LoshAfter this first result
110078e3e3a7aSWarner Loshthe function returns a string plus a number,
110088e3e3a7aSWarner Loshas follows:
110098e3e3a7aSWarner Losh
110108e3e3a7aSWarner Losh<ul>
110118e3e3a7aSWarner Losh
110128e3e3a7aSWarner Losh<li><b>"<code>exit</code>": </b>
110138e3e3a7aSWarner Loshthe command terminated normally;
110148e3e3a7aSWarner Loshthe following number is the exit status of the command.
110158e3e3a7aSWarner Losh</li>
110168e3e3a7aSWarner Losh
110178e3e3a7aSWarner Losh<li><b>"<code>signal</code>": </b>
110188e3e3a7aSWarner Loshthe command was terminated by a signal;
110198e3e3a7aSWarner Loshthe following number is the signal that terminated the command.
110208e3e3a7aSWarner Losh</li>
110218e3e3a7aSWarner Losh
110228e3e3a7aSWarner Losh</ul>
110238e3e3a7aSWarner Losh
110248e3e3a7aSWarner Losh<p>
110258e3e3a7aSWarner LoshWhen called without a <code>command</code>,
110268e3e3a7aSWarner Losh<code>os.execute</code> returns a boolean that is true if a shell is available.
110278e3e3a7aSWarner Losh
110288e3e3a7aSWarner Losh
110298e3e3a7aSWarner Losh
110308e3e3a7aSWarner Losh
110318e3e3a7aSWarner Losh<p>
110328e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3>
110338e3e3a7aSWarner Losh
110348e3e3a7aSWarner Losh
110358e3e3a7aSWarner Losh<p>
110368e3e3a7aSWarner LoshCalls the ISO&nbsp;C function <code>exit</code> to terminate the host program.
110378e3e3a7aSWarner LoshIf <code>code</code> is <b>true</b>,
110388e3e3a7aSWarner Loshthe returned status is <code>EXIT_SUCCESS</code>;
110398e3e3a7aSWarner Loshif <code>code</code> is <b>false</b>,
110408e3e3a7aSWarner Loshthe returned status is <code>EXIT_FAILURE</code>;
110418e3e3a7aSWarner Loshif <code>code</code> is a number,
110428e3e3a7aSWarner Loshthe returned status is this number.
110438e3e3a7aSWarner LoshThe default value for <code>code</code> is <b>true</b>.
110448e3e3a7aSWarner Losh
110458e3e3a7aSWarner Losh
110468e3e3a7aSWarner Losh<p>
110478e3e3a7aSWarner LoshIf the optional second argument <code>close</code> is true,
11048a9490b81SWarner Loshthe function closes the Lua state before exiting (see <a href="#lua_close"><code>lua_close</code></a>).
110498e3e3a7aSWarner Losh
110508e3e3a7aSWarner Losh
110518e3e3a7aSWarner Losh
110528e3e3a7aSWarner Losh
110538e3e3a7aSWarner Losh<p>
110548e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3>
110558e3e3a7aSWarner Losh
110568e3e3a7aSWarner Losh
110578e3e3a7aSWarner Losh<p>
110580495ed39SKyle EvansReturns the value of the process environment variable <code>varname</code>
110590495ed39SKyle Evansor <b>fail</b> if the variable is not defined.
110608e3e3a7aSWarner Losh
110618e3e3a7aSWarner Losh
110628e3e3a7aSWarner Losh
110638e3e3a7aSWarner Losh
110648e3e3a7aSWarner Losh<p>
110658e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3>
110668e3e3a7aSWarner Losh
110678e3e3a7aSWarner Losh
110688e3e3a7aSWarner Losh<p>
110698e3e3a7aSWarner LoshDeletes the file (or empty directory, on POSIX systems)
110708e3e3a7aSWarner Loshwith the given name.
110710495ed39SKyle EvansIf this function fails, it returns <b>fail</b>
110728e3e3a7aSWarner Loshplus a string describing the error and the error code.
110738e3e3a7aSWarner LoshOtherwise, it returns true.
110748e3e3a7aSWarner Losh
110758e3e3a7aSWarner Losh
110768e3e3a7aSWarner Losh
110778e3e3a7aSWarner Losh
110788e3e3a7aSWarner Losh<p>
110798e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3>
110808e3e3a7aSWarner Losh
110818e3e3a7aSWarner Losh
110828e3e3a7aSWarner Losh<p>
110838e3e3a7aSWarner LoshRenames the file or directory named <code>oldname</code> to <code>newname</code>.
110840495ed39SKyle EvansIf this function fails, it returns <b>fail</b>,
110858e3e3a7aSWarner Loshplus a string describing the error and the error code.
110868e3e3a7aSWarner LoshOtherwise, it returns true.
110878e3e3a7aSWarner Losh
110888e3e3a7aSWarner Losh
110898e3e3a7aSWarner Losh
110908e3e3a7aSWarner Losh
110918e3e3a7aSWarner Losh<p>
110928e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3>
110938e3e3a7aSWarner Losh
110948e3e3a7aSWarner Losh
110958e3e3a7aSWarner Losh<p>
110968e3e3a7aSWarner LoshSets the current locale of the program.
110978e3e3a7aSWarner Losh<code>locale</code> is a system-dependent string specifying a locale;
110988e3e3a7aSWarner Losh<code>category</code> is an optional string describing which category to change:
110998e3e3a7aSWarner Losh<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>,
111008e3e3a7aSWarner Losh<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>;
111018e3e3a7aSWarner Loshthe default category is <code>"all"</code>.
111028e3e3a7aSWarner LoshThe function returns the name of the new locale,
111030495ed39SKyle Evansor <b>fail</b> if the request cannot be honored.
111048e3e3a7aSWarner Losh
111058e3e3a7aSWarner Losh
111068e3e3a7aSWarner Losh<p>
111078e3e3a7aSWarner LoshIf <code>locale</code> is the empty string,
111088e3e3a7aSWarner Loshthe current locale is set to an implementation-defined native locale.
111098e3e3a7aSWarner LoshIf <code>locale</code> is the string "<code>C</code>",
111108e3e3a7aSWarner Loshthe current locale is set to the standard C locale.
111118e3e3a7aSWarner Losh
111128e3e3a7aSWarner Losh
111138e3e3a7aSWarner Losh<p>
111148e3e3a7aSWarner LoshWhen called with <b>nil</b> as the first argument,
111158e3e3a7aSWarner Loshthis function only returns the name of the current locale
111168e3e3a7aSWarner Loshfor the given category.
111178e3e3a7aSWarner Losh
111188e3e3a7aSWarner Losh
111198e3e3a7aSWarner Losh<p>
111208e3e3a7aSWarner LoshThis function may be not thread safe
111218e3e3a7aSWarner Loshbecause of its reliance on C&nbsp;function <code>setlocale</code>.
111228e3e3a7aSWarner Losh
111238e3e3a7aSWarner Losh
111248e3e3a7aSWarner Losh
111258e3e3a7aSWarner Losh
111268e3e3a7aSWarner Losh<p>
111278e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3>
111288e3e3a7aSWarner Losh
111298e3e3a7aSWarner Losh
111308e3e3a7aSWarner Losh<p>
111318e3e3a7aSWarner LoshReturns the current time when called without arguments,
111328e3e3a7aSWarner Loshor a time representing the local date and time specified by the given table.
111338e3e3a7aSWarner LoshThis table must have fields <code>year</code>, <code>month</code>, and <code>day</code>,
111348e3e3a7aSWarner Loshand may have fields
111358e3e3a7aSWarner Losh<code>hour</code> (default is 12),
111368e3e3a7aSWarner Losh<code>min</code> (default is 0),
111378e3e3a7aSWarner Losh<code>sec</code> (default is 0),
111388e3e3a7aSWarner Loshand <code>isdst</code> (default is <b>nil</b>).
111398e3e3a7aSWarner LoshOther fields are ignored.
111408e3e3a7aSWarner LoshFor a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function.
111418e3e3a7aSWarner Losh
111428e3e3a7aSWarner Losh
111438e3e3a7aSWarner Losh<p>
111440495ed39SKyle EvansWhen the function is called,
111450495ed39SKyle Evansthe values in these fields do not need to be inside their valid ranges.
111468e3e3a7aSWarner LoshFor instance, if <code>sec</code> is -10,
111470495ed39SKyle Evansit means 10 seconds before the time specified by the other fields;
111488e3e3a7aSWarner Loshif <code>hour</code> is 1000,
111490495ed39SKyle Evansit means 1000 hours after the time specified by the other fields.
111508e3e3a7aSWarner Losh
111518e3e3a7aSWarner Losh
111528e3e3a7aSWarner Losh<p>
111538e3e3a7aSWarner LoshThe returned value is a number, whose meaning depends on your system.
111548e3e3a7aSWarner LoshIn POSIX, Windows, and some other systems,
111558e3e3a7aSWarner Loshthis number counts the number
111568e3e3a7aSWarner Loshof seconds since some given start time (the "epoch").
111578e3e3a7aSWarner LoshIn other systems, the meaning is not specified,
111588e3e3a7aSWarner Loshand the number returned by <code>time</code> can be used only as an argument to
111598e3e3a7aSWarner Losh<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>.
111608e3e3a7aSWarner Losh
111618e3e3a7aSWarner Losh
111620495ed39SKyle Evans<p>
111630495ed39SKyle EvansWhen called with a table,
111640495ed39SKyle Evans<code>os.time</code> also normalizes all the fields
111650495ed39SKyle Evansdocumented in the <a href="#pdf-os.date"><code>os.date</code></a> function,
111660495ed39SKyle Evansso that they represent the same time as before the call
111670495ed39SKyle Evansbut with values inside their valid ranges.
111680495ed39SKyle Evans
111690495ed39SKyle Evans
111708e3e3a7aSWarner Losh
111718e3e3a7aSWarner Losh
111728e3e3a7aSWarner Losh<p>
111738e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3>
111748e3e3a7aSWarner Losh
111758e3e3a7aSWarner Losh
111768e3e3a7aSWarner Losh<p>
111778e3e3a7aSWarner LoshReturns a string with a file name that can
111788e3e3a7aSWarner Loshbe used for a temporary file.
111798e3e3a7aSWarner LoshThe file must be explicitly opened before its use
111808e3e3a7aSWarner Loshand explicitly removed when no longer needed.
111818e3e3a7aSWarner Losh
111828e3e3a7aSWarner Losh
111838e3e3a7aSWarner Losh<p>
11184e112e9d2SKyle EvansIn POSIX systems,
111858e3e3a7aSWarner Loshthis function also creates a file with that name,
111868e3e3a7aSWarner Loshto avoid security risks.
111878e3e3a7aSWarner Losh(Someone else might create the file with wrong permissions
111888e3e3a7aSWarner Loshin the time between getting the name and creating the file.)
111898e3e3a7aSWarner LoshYou still have to open the file to use it
111908e3e3a7aSWarner Loshand to remove it (even if you do not use it).
111918e3e3a7aSWarner Losh
111928e3e3a7aSWarner Losh
111938e3e3a7aSWarner Losh<p>
111948e3e3a7aSWarner LoshWhen possible,
111958e3e3a7aSWarner Loshyou may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>,
111968e3e3a7aSWarner Loshwhich automatically removes the file when the program ends.
111978e3e3a7aSWarner Losh
111988e3e3a7aSWarner Losh
111998e3e3a7aSWarner Losh
112008e3e3a7aSWarner Losh
112018e3e3a7aSWarner Losh
112028e3e3a7aSWarner Losh
112038e3e3a7aSWarner Losh
112048e3e3a7aSWarner Losh<h2>6.10 &ndash; <a name="6.10">The Debug Library</a></h2>
112058e3e3a7aSWarner Losh
112068e3e3a7aSWarner Losh<p>
112078e3e3a7aSWarner LoshThis library provides
112080495ed39SKyle Evansthe functionality of the debug interface (<a href="#4.7">&sect;4.7</a>) to Lua programs.
112098e3e3a7aSWarner LoshYou should exert care when using this library.
112108e3e3a7aSWarner LoshSeveral of its functions
112118e3e3a7aSWarner Loshviolate basic assumptions about Lua code
112128e3e3a7aSWarner Losh(e.g., that variables local to a function
112138e3e3a7aSWarner Loshcannot be accessed from outside;
112148e3e3a7aSWarner Loshthat userdata metatables cannot be changed by Lua code;
112158e3e3a7aSWarner Loshthat Lua programs do not crash)
112168e3e3a7aSWarner Loshand therefore can compromise otherwise secure code.
112178e3e3a7aSWarner LoshMoreover, some functions in this library may be slow.
112188e3e3a7aSWarner Losh
112198e3e3a7aSWarner Losh
112208e3e3a7aSWarner Losh<p>
112218e3e3a7aSWarner LoshAll functions in this library are provided
112228e3e3a7aSWarner Loshinside the <a name="pdf-debug"><code>debug</code></a> table.
112238e3e3a7aSWarner LoshAll functions that operate over a thread
112248e3e3a7aSWarner Loshhave an optional first argument which is the
112258e3e3a7aSWarner Loshthread to operate over.
112268e3e3a7aSWarner LoshThe default is always the current thread.
112278e3e3a7aSWarner Losh
112288e3e3a7aSWarner Losh
112298e3e3a7aSWarner Losh<p>
112308e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3>
112318e3e3a7aSWarner Losh
112328e3e3a7aSWarner Losh
112338e3e3a7aSWarner Losh<p>
112348e3e3a7aSWarner LoshEnters an interactive mode with the user,
112358e3e3a7aSWarner Loshrunning each string that the user enters.
112368e3e3a7aSWarner LoshUsing simple commands and other debug facilities,
112378e3e3a7aSWarner Loshthe user can inspect global and local variables,
112388e3e3a7aSWarner Loshchange their values, evaluate expressions, and so on.
112398e3e3a7aSWarner LoshA line containing only the word <code>cont</code> finishes this function,
112408e3e3a7aSWarner Loshso that the caller continues its execution.
112418e3e3a7aSWarner Losh
112428e3e3a7aSWarner Losh
112438e3e3a7aSWarner Losh<p>
112448e3e3a7aSWarner LoshNote that commands for <code>debug.debug</code> are not lexically nested
112458e3e3a7aSWarner Loshwithin any function and so have no direct access to local variables.
112468e3e3a7aSWarner Losh
112478e3e3a7aSWarner Losh
112488e3e3a7aSWarner Losh
112498e3e3a7aSWarner Losh
112508e3e3a7aSWarner Losh<p>
112518e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3>
112528e3e3a7aSWarner Losh
112538e3e3a7aSWarner Losh
112548e3e3a7aSWarner Losh<p>
112558e3e3a7aSWarner LoshReturns the current hook settings of the thread, as three values:
112568e3e3a7aSWarner Loshthe current hook function, the current hook mask,
112570495ed39SKyle Evansand the current hook count,
112580495ed39SKyle Evansas set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function.
112590495ed39SKyle Evans
112600495ed39SKyle Evans
112610495ed39SKyle Evans<p>
112620495ed39SKyle EvansReturns <b>fail</b> if there is no active hook.
112638e3e3a7aSWarner Losh
112648e3e3a7aSWarner Losh
112658e3e3a7aSWarner Losh
112668e3e3a7aSWarner Losh
112678e3e3a7aSWarner Losh<p>
112688e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3>
112698e3e3a7aSWarner Losh
112708e3e3a7aSWarner Losh
112718e3e3a7aSWarner Losh<p>
112728e3e3a7aSWarner LoshReturns a table with information about a function.
112738e3e3a7aSWarner LoshYou can give the function directly
112748e3e3a7aSWarner Loshor you can give a number as the value of <code>f</code>,
112758e3e3a7aSWarner Loshwhich means the function running at level <code>f</code> of the call stack
112768e3e3a7aSWarner Loshof the given thread:
112778e3e3a7aSWarner Loshlevel&nbsp;0 is the current function (<code>getinfo</code> itself);
112788e3e3a7aSWarner Loshlevel&nbsp;1 is the function that called <code>getinfo</code>
112790495ed39SKyle Evans(except for tail calls, which do not count in the stack);
112808e3e3a7aSWarner Loshand so on.
112810495ed39SKyle EvansIf <code>f</code> is a number greater than the number of active functions,
112820495ed39SKyle Evansthen <code>getinfo</code> returns <b>fail</b>.
112838e3e3a7aSWarner Losh
112848e3e3a7aSWarner Losh
112858e3e3a7aSWarner Losh<p>
112868e3e3a7aSWarner LoshThe returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>,
112878e3e3a7aSWarner Loshwith the string <code>what</code> describing which fields to fill in.
112888e3e3a7aSWarner LoshThe default for <code>what</code> is to get all information available,
112898e3e3a7aSWarner Loshexcept the table of valid lines.
11290*3068d706SWarner LoshThe option '<code>f</code>'
112918e3e3a7aSWarner Loshadds a field named <code>func</code> with the function itself.
11292*3068d706SWarner LoshThe option '<code>L</code>' adds a field named <code>activelines</code>
11293*3068d706SWarner Loshwith the table of valid lines,
11294*3068d706SWarner Loshprovided the function is a Lua function.
11295*3068d706SWarner LoshIf the function has no debug information,
11296*3068d706SWarner Loshthe table is empty.
112978e3e3a7aSWarner Losh
112988e3e3a7aSWarner Losh
112998e3e3a7aSWarner Losh<p>
113008e3e3a7aSWarner LoshFor instance, the expression <code>debug.getinfo(1,"n").name</code> returns
113018e3e3a7aSWarner Losha name for the current function,
113028e3e3a7aSWarner Loshif a reasonable name can be found,
113038e3e3a7aSWarner Loshand the expression <code>debug.getinfo(print)</code>
113048e3e3a7aSWarner Loshreturns a table with all available information
113058e3e3a7aSWarner Loshabout the <a href="#pdf-print"><code>print</code></a> function.
113068e3e3a7aSWarner Losh
113078e3e3a7aSWarner Losh
113088e3e3a7aSWarner Losh
113098e3e3a7aSWarner Losh
113108e3e3a7aSWarner Losh<p>
113118e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3>
113128e3e3a7aSWarner Losh
113138e3e3a7aSWarner Losh
113148e3e3a7aSWarner Losh<p>
113158e3e3a7aSWarner LoshThis function returns the name and the value of the local variable
113168e3e3a7aSWarner Loshwith index <code>local</code> of the function at level <code>f</code> of the stack.
113178e3e3a7aSWarner LoshThis function accesses not only explicit local variables,
113180495ed39SKyle Evansbut also parameters and temporary values.
113198e3e3a7aSWarner Losh
113208e3e3a7aSWarner Losh
113218e3e3a7aSWarner Losh<p>
113228e3e3a7aSWarner LoshThe first parameter or local variable has index&nbsp;1, and so on,
113238e3e3a7aSWarner Loshfollowing the order that they are declared in the code,
113248e3e3a7aSWarner Loshcounting only the variables that are active
113258e3e3a7aSWarner Loshin the current scope of the function.
113260495ed39SKyle EvansCompile-time constants may not appear in this listing,
113270495ed39SKyle Evansif they were optimized away by the compiler.
11328e112e9d2SKyle EvansNegative indices refer to vararg arguments;
11329e112e9d2SKyle Evans-1 is the first vararg argument.
113300495ed39SKyle EvansThe function returns <b>fail</b>
113310495ed39SKyle Evansif there is no variable with the given index,
113328e3e3a7aSWarner Loshand raises an error when called with a level out of range.
113338e3e3a7aSWarner Losh(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.)
113348e3e3a7aSWarner Losh
113358e3e3a7aSWarner Losh
113368e3e3a7aSWarner Losh<p>
113378e3e3a7aSWarner LoshVariable names starting with '<code>(</code>' (open parenthesis)
113388e3e3a7aSWarner Loshrepresent variables with no known names
113398e3e3a7aSWarner Losh(internal variables such as loop control variables,
113408e3e3a7aSWarner Loshand variables from chunks saved without debug information).
113418e3e3a7aSWarner Losh
113428e3e3a7aSWarner Losh
113438e3e3a7aSWarner Losh<p>
113448e3e3a7aSWarner LoshThe parameter <code>f</code> may also be a function.
113458e3e3a7aSWarner LoshIn that case, <code>getlocal</code> returns only the name of function parameters.
113468e3e3a7aSWarner Losh
113478e3e3a7aSWarner Losh
113488e3e3a7aSWarner Losh
113498e3e3a7aSWarner Losh
113508e3e3a7aSWarner Losh<p>
113518e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3>
113528e3e3a7aSWarner Losh
113538e3e3a7aSWarner Losh
113548e3e3a7aSWarner Losh<p>
113558e3e3a7aSWarner LoshReturns the metatable of the given <code>value</code>
113568e3e3a7aSWarner Loshor <b>nil</b> if it does not have a metatable.
113578e3e3a7aSWarner Losh
113588e3e3a7aSWarner Losh
113598e3e3a7aSWarner Losh
113608e3e3a7aSWarner Losh
113618e3e3a7aSWarner Losh<p>
113628e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3>
113638e3e3a7aSWarner Losh
113648e3e3a7aSWarner Losh
113658e3e3a7aSWarner Losh<p>
113660495ed39SKyle EvansReturns the registry table (see <a href="#4.3">&sect;4.3</a>).
113678e3e3a7aSWarner Losh
113688e3e3a7aSWarner Losh
113698e3e3a7aSWarner Losh
113708e3e3a7aSWarner Losh
113718e3e3a7aSWarner Losh<p>
113728e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3>
113738e3e3a7aSWarner Losh
113748e3e3a7aSWarner Losh
113758e3e3a7aSWarner Losh<p>
113768e3e3a7aSWarner LoshThis function returns the name and the value of the upvalue
113778e3e3a7aSWarner Loshwith index <code>up</code> of the function <code>f</code>.
113780495ed39SKyle EvansThe function returns <b>fail</b>
113790495ed39SKyle Evansif there is no upvalue with the given index.
113808e3e3a7aSWarner Losh
113818e3e3a7aSWarner Losh
113828e3e3a7aSWarner Losh<p>
113830495ed39SKyle Evans(For Lua functions,
113840495ed39SKyle Evansupvalues are the external local variables that the function uses,
113850495ed39SKyle Evansand that are consequently included in its closure.)
113860495ed39SKyle Evans
113870495ed39SKyle Evans
113880495ed39SKyle Evans<p>
113890495ed39SKyle EvansFor C&nbsp;functions, this function uses the empty string <code>""</code>
113900495ed39SKyle Evansas a name for all upvalues.
113910495ed39SKyle Evans
113920495ed39SKyle Evans
113930495ed39SKyle Evans<p>
113940495ed39SKyle EvansVariable name '<code>?</code>' (interrogation mark)
113950495ed39SKyle Evansrepresents variables with no known names
113968e3e3a7aSWarner Losh(variables from chunks saved without debug information).
113978e3e3a7aSWarner Losh
113988e3e3a7aSWarner Losh
113998e3e3a7aSWarner Losh
114008e3e3a7aSWarner Losh
114018e3e3a7aSWarner Losh<p>
114020495ed39SKyle Evans<hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u, n)</code></a></h3>
114038e3e3a7aSWarner Losh
114048e3e3a7aSWarner Losh
114058e3e3a7aSWarner Losh<p>
114060495ed39SKyle EvansReturns the <code>n</code>-th user value associated
114070495ed39SKyle Evansto the userdata <code>u</code> plus a boolean,
114080495ed39SKyle Evans<b>false</b> if the userdata does not have that value.
114098e3e3a7aSWarner Losh
114108e3e3a7aSWarner Losh
114118e3e3a7aSWarner Losh
114128e3e3a7aSWarner Losh
114138e3e3a7aSWarner Losh<p>
114148e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3>
114158e3e3a7aSWarner Losh
114168e3e3a7aSWarner Losh
114178e3e3a7aSWarner Losh<p>
114180495ed39SKyle EvansSets the given function as the debug hook.
114198e3e3a7aSWarner LoshThe string <code>mask</code> and the number <code>count</code> describe
114208e3e3a7aSWarner Loshwhen the hook will be called.
114218e3e3a7aSWarner LoshThe string mask may have any combination of the following characters,
114228e3e3a7aSWarner Loshwith the given meaning:
114238e3e3a7aSWarner Losh
114248e3e3a7aSWarner Losh<ul>
114258e3e3a7aSWarner Losh<li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li>
114268e3e3a7aSWarner Losh<li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li>
114278e3e3a7aSWarner Losh<li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li>
114288e3e3a7aSWarner Losh</ul><p>
114298e3e3a7aSWarner LoshMoreover,
114308e3e3a7aSWarner Loshwith a <code>count</code> different from zero,
114318e3e3a7aSWarner Loshthe hook is called also after every <code>count</code> instructions.
114328e3e3a7aSWarner Losh
114338e3e3a7aSWarner Losh
114348e3e3a7aSWarner Losh<p>
114358e3e3a7aSWarner LoshWhen called without arguments,
114368e3e3a7aSWarner Losh<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook.
114378e3e3a7aSWarner Losh
114388e3e3a7aSWarner Losh
114398e3e3a7aSWarner Losh<p>
114400495ed39SKyle EvansWhen the hook is called, its first parameter is a string
114418e3e3a7aSWarner Loshdescribing the event that has triggered its call:
114420495ed39SKyle Evans<code>"call"</code>, <code>"tail call"</code>, <code>"return"</code>,
114438e3e3a7aSWarner Losh<code>"line"</code>, and <code>"count"</code>.
114448e3e3a7aSWarner LoshFor line events,
114458e3e3a7aSWarner Loshthe hook also gets the new line number as its second parameter.
114468e3e3a7aSWarner LoshInside a hook,
114478e3e3a7aSWarner Loshyou can call <code>getinfo</code> with level&nbsp;2 to get more information about
114480495ed39SKyle Evansthe running function.
114490495ed39SKyle Evans(Level&nbsp;0 is the <code>getinfo</code> function,
114500495ed39SKyle Evansand level&nbsp;1 is the hook function.)
114518e3e3a7aSWarner Losh
114528e3e3a7aSWarner Losh
114538e3e3a7aSWarner Losh
114548e3e3a7aSWarner Losh
114558e3e3a7aSWarner Losh<p>
114568e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3>
114578e3e3a7aSWarner Losh
114588e3e3a7aSWarner Losh
114598e3e3a7aSWarner Losh<p>
114608e3e3a7aSWarner LoshThis function assigns the value <code>value</code> to the local variable
114618e3e3a7aSWarner Loshwith index <code>local</code> of the function at level <code>level</code> of the stack.
114620495ed39SKyle EvansThe function returns <b>fail</b> if there is no local
114638e3e3a7aSWarner Loshvariable with the given index,
114648e3e3a7aSWarner Loshand raises an error when called with a <code>level</code> out of range.
114658e3e3a7aSWarner Losh(You can call <code>getinfo</code> to check whether the level is valid.)
114668e3e3a7aSWarner LoshOtherwise, it returns the name of the local variable.
114678e3e3a7aSWarner Losh
114688e3e3a7aSWarner Losh
114698e3e3a7aSWarner Losh<p>
114708e3e3a7aSWarner LoshSee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about
114718e3e3a7aSWarner Loshvariable indices and names.
114728e3e3a7aSWarner Losh
114738e3e3a7aSWarner Losh
114748e3e3a7aSWarner Losh
114758e3e3a7aSWarner Losh
114768e3e3a7aSWarner Losh<p>
114778e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3>
114788e3e3a7aSWarner Losh
114798e3e3a7aSWarner Losh
114808e3e3a7aSWarner Losh<p>
114818e3e3a7aSWarner LoshSets the metatable for the given <code>value</code> to the given <code>table</code>
114828e3e3a7aSWarner Losh(which can be <b>nil</b>).
114838e3e3a7aSWarner LoshReturns <code>value</code>.
114848e3e3a7aSWarner Losh
114858e3e3a7aSWarner Losh
114868e3e3a7aSWarner Losh
114878e3e3a7aSWarner Losh
114888e3e3a7aSWarner Losh<p>
114898e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3>
114908e3e3a7aSWarner Losh
114918e3e3a7aSWarner Losh
114928e3e3a7aSWarner Losh<p>
114938e3e3a7aSWarner LoshThis function assigns the value <code>value</code> to the upvalue
114948e3e3a7aSWarner Loshwith index <code>up</code> of the function <code>f</code>.
114950495ed39SKyle EvansThe function returns <b>fail</b> if there is no upvalue
114968e3e3a7aSWarner Loshwith the given index.
114978e3e3a7aSWarner LoshOtherwise, it returns the name of the upvalue.
114988e3e3a7aSWarner Losh
114998e3e3a7aSWarner Losh
115000495ed39SKyle Evans<p>
115010495ed39SKyle EvansSee <a href="#pdf-debug.getupvalue"><code>debug.getupvalue</code></a> for more information about upvalues.
115020495ed39SKyle Evans
115030495ed39SKyle Evans
115048e3e3a7aSWarner Losh
115058e3e3a7aSWarner Losh
115068e3e3a7aSWarner Losh<p>
115070495ed39SKyle Evans<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value, n)</code></a></h3>
115088e3e3a7aSWarner Losh
115098e3e3a7aSWarner Losh
115108e3e3a7aSWarner Losh<p>
115118e3e3a7aSWarner LoshSets the given <code>value</code> as
115120495ed39SKyle Evansthe <code>n</code>-th user value associated to the given <code>udata</code>.
115138e3e3a7aSWarner Losh<code>udata</code> must be a full userdata.
115148e3e3a7aSWarner Losh
115158e3e3a7aSWarner Losh
115168e3e3a7aSWarner Losh<p>
115170495ed39SKyle EvansReturns <code>udata</code>,
115180495ed39SKyle Evansor <b>fail</b> if the userdata does not have that value.
115198e3e3a7aSWarner Losh
115208e3e3a7aSWarner Losh
115218e3e3a7aSWarner Losh
115228e3e3a7aSWarner Losh
115238e3e3a7aSWarner Losh<p>
115248e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3>
115258e3e3a7aSWarner Losh
115268e3e3a7aSWarner Losh
115278e3e3a7aSWarner Losh<p>
115288e3e3a7aSWarner LoshIf <code>message</code> is present but is neither a string nor <b>nil</b>,
115298e3e3a7aSWarner Loshthis function returns <code>message</code> without further processing.
115308e3e3a7aSWarner LoshOtherwise,
115318e3e3a7aSWarner Loshit returns a string with a traceback of the call stack.
115328e3e3a7aSWarner LoshThe optional <code>message</code> string is appended
115338e3e3a7aSWarner Loshat the beginning of the traceback.
115348e3e3a7aSWarner LoshAn optional <code>level</code> number tells at which level
115358e3e3a7aSWarner Loshto start the traceback
115368e3e3a7aSWarner Losh(default is 1, the function calling <code>traceback</code>).
115378e3e3a7aSWarner Losh
115388e3e3a7aSWarner Losh
115398e3e3a7aSWarner Losh
115408e3e3a7aSWarner Losh
115418e3e3a7aSWarner Losh<p>
115428e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3>
115438e3e3a7aSWarner Losh
115448e3e3a7aSWarner Losh
115458e3e3a7aSWarner Losh<p>
115468e3e3a7aSWarner LoshReturns a unique identifier (as a light userdata)
115478e3e3a7aSWarner Loshfor the upvalue numbered <code>n</code>
115488e3e3a7aSWarner Loshfrom the given function.
115498e3e3a7aSWarner Losh
115508e3e3a7aSWarner Losh
115518e3e3a7aSWarner Losh<p>
115528e3e3a7aSWarner LoshThese unique identifiers allow a program to check whether different
115538e3e3a7aSWarner Loshclosures share upvalues.
115548e3e3a7aSWarner LoshLua closures that share an upvalue
115558e3e3a7aSWarner Losh(that is, that access a same external local variable)
115568e3e3a7aSWarner Loshwill return identical ids for those upvalue indices.
115578e3e3a7aSWarner Losh
115588e3e3a7aSWarner Losh
115598e3e3a7aSWarner Losh
115608e3e3a7aSWarner Losh
115618e3e3a7aSWarner Losh<p>
115628e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3>
115638e3e3a7aSWarner Losh
115648e3e3a7aSWarner Losh
115658e3e3a7aSWarner Losh<p>
115668e3e3a7aSWarner LoshMake the <code>n1</code>-th upvalue of the Lua closure <code>f1</code>
115678e3e3a7aSWarner Loshrefer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>.
115688e3e3a7aSWarner Losh
115698e3e3a7aSWarner Losh
115708e3e3a7aSWarner Losh
115718e3e3a7aSWarner Losh
115728e3e3a7aSWarner Losh
115738e3e3a7aSWarner Losh
115748e3e3a7aSWarner Losh
115758e3e3a7aSWarner Losh<h1>7 &ndash; <a name="7">Lua Standalone</a></h1>
115768e3e3a7aSWarner Losh
115778e3e3a7aSWarner Losh<p>
115788e3e3a7aSWarner LoshAlthough Lua has been designed as an extension language,
115798e3e3a7aSWarner Loshto be embedded in a host C&nbsp;program,
115808e3e3a7aSWarner Loshit is also frequently used as a standalone language.
115818e3e3a7aSWarner LoshAn interpreter for Lua as a standalone language,
115828e3e3a7aSWarner Loshcalled simply <code>lua</code>,
115838e3e3a7aSWarner Loshis provided with the standard distribution.
115848e3e3a7aSWarner LoshThe standalone interpreter includes
115850495ed39SKyle Evansall standard libraries.
115868e3e3a7aSWarner LoshIts usage is:
115878e3e3a7aSWarner Losh
115888e3e3a7aSWarner Losh<pre>
115898e3e3a7aSWarner Losh     lua [options] [script [args]]
115908e3e3a7aSWarner Losh</pre><p>
115918e3e3a7aSWarner LoshThe options are:
115928e3e3a7aSWarner Losh
115938e3e3a7aSWarner Losh<ul>
115940495ed39SKyle Evans<li><b><code>-e <em>stat</em></code>: </b> execute string <em>stat</em>;</li>
115950495ed39SKyle Evans<li><b><code>-i</code>: </b> enter interactive mode after running <em>script</em>;</li>
115960495ed39SKyle Evans<li><b><code>-l <em>mod</em></code>: </b> "require" <em>mod</em> and assign the
115970495ed39SKyle Evans  result to global <em>mod</em>;</li>
11598a9490b81SWarner Losh<li><b><code>-l <em>g=mod</em></code>: </b> "require" <em>mod</em> and assign the
11599a9490b81SWarner Losh  result to global <em>g</em>;</li>
116000495ed39SKyle Evans<li><b><code>-v</code>: </b> print version information;</li>
116010495ed39SKyle Evans<li><b><code>-E</code>: </b> ignore environment variables;</li>
116020495ed39SKyle Evans<li><b><code>-W</code>: </b> turn warnings on;</li>
116030495ed39SKyle Evans<li><b><code>--</code>: </b> stop handling options;</li>
116040495ed39SKyle Evans<li><b><code>-</code>: </b> execute <code>stdin</code> as a file and stop handling options.</li>
116058e3e3a7aSWarner Losh</ul><p>
11606a9490b81SWarner Losh(The form <code>-l <em>g=mod</em></code> was introduced in release&nbsp;5.4.4.)
11607a9490b81SWarner Losh
11608a9490b81SWarner Losh
11609a9490b81SWarner Losh<p>
116108e3e3a7aSWarner LoshAfter handling its options, <code>lua</code> runs the given <em>script</em>.
116118e3e3a7aSWarner LoshWhen called without arguments,
116128e3e3a7aSWarner Losh<code>lua</code> behaves as <code>lua -v -i</code>
116138e3e3a7aSWarner Loshwhen the standard input (<code>stdin</code>) is a terminal,
116148e3e3a7aSWarner Loshand as <code>lua -</code> otherwise.
116158e3e3a7aSWarner Losh
116168e3e3a7aSWarner Losh
116178e3e3a7aSWarner Losh<p>
116180495ed39SKyle EvansWhen called without the option <code>-E</code>,
116190495ed39SKyle Evansthe interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_4"><code>LUA_INIT_5_4</code></a>
116208e3e3a7aSWarner Losh(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined)
116218e3e3a7aSWarner Loshbefore running any argument.
116228e3e3a7aSWarner LoshIf the variable content has the format <code>@<em>filename</em></code>,
116238e3e3a7aSWarner Loshthen <code>lua</code> executes the file.
116248e3e3a7aSWarner LoshOtherwise, <code>lua</code> executes the string itself.
116258e3e3a7aSWarner Losh
116268e3e3a7aSWarner Losh
116278e3e3a7aSWarner Losh<p>
116280495ed39SKyle EvansWhen called with the option <code>-E</code>,
116290495ed39SKyle EvansLua does not consult any environment variables.
116300495ed39SKyle EvansIn particular,
116310495ed39SKyle Evansthe values of <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a>
116320495ed39SKyle Evansare set with the default paths defined in <code>luaconf.h</code>.
11633*3068d706SWarner LoshTo signal to the libraries that this option is on,
11634*3068d706SWarner Loshthe stand-alone interpreter sets the field
11635*3068d706SWarner Losh<code>"LUA_NOENV"</code> in the registry to a true value.
11636*3068d706SWarner LoshOther libraries may consult this field for the same purpose.
116378e3e3a7aSWarner Losh
116388e3e3a7aSWarner Losh
116398e3e3a7aSWarner Losh<p>
116400495ed39SKyle EvansThe options <code>-e</code>, <code>-l</code>, and <code>-W</code> are handled in
116410495ed39SKyle Evansthe order they appear.
116428e3e3a7aSWarner LoshFor instance, an invocation like
116438e3e3a7aSWarner Losh
116448e3e3a7aSWarner Losh<pre>
116450495ed39SKyle Evans     $ lua -e 'a=1' -llib1 script.lua
116468e3e3a7aSWarner Losh</pre><p>
116470495ed39SKyle Evanswill first set <code>a</code> to 1, then require the library <code>lib1</code>,
116488e3e3a7aSWarner Loshand finally run the file <code>script.lua</code> with no arguments.
116498e3e3a7aSWarner Losh(Here <code>$</code> is the shell prompt. Your prompt may be different.)
116508e3e3a7aSWarner Losh
116518e3e3a7aSWarner Losh
116528e3e3a7aSWarner Losh<p>
116538e3e3a7aSWarner LoshBefore running any code,
116548e3e3a7aSWarner Losh<code>lua</code> collects all command-line arguments
116558e3e3a7aSWarner Loshin a global table called <code>arg</code>.
116568e3e3a7aSWarner LoshThe script name goes to index 0,
116578e3e3a7aSWarner Loshthe first argument after the script name goes to index 1,
116588e3e3a7aSWarner Loshand so on.
116598e3e3a7aSWarner LoshAny arguments before the script name
116608e3e3a7aSWarner Losh(that is, the interpreter name plus its options)
116618e3e3a7aSWarner Loshgo to negative indices.
116628e3e3a7aSWarner LoshFor instance, in the call
116638e3e3a7aSWarner Losh
116648e3e3a7aSWarner Losh<pre>
116658e3e3a7aSWarner Losh     $ lua -la b.lua t1 t2
116668e3e3a7aSWarner Losh</pre><p>
116678e3e3a7aSWarner Loshthe table is like this:
116688e3e3a7aSWarner Losh
116698e3e3a7aSWarner Losh<pre>
116708e3e3a7aSWarner Losh     arg = { [-2] = "lua", [-1] = "-la",
116718e3e3a7aSWarner Losh             [0] = "b.lua",
116728e3e3a7aSWarner Losh             [1] = "t1", [2] = "t2" }
116738e3e3a7aSWarner Losh</pre><p>
116748e3e3a7aSWarner LoshIf there is no script in the call,
116758e3e3a7aSWarner Loshthe interpreter name goes to index 0,
116768e3e3a7aSWarner Loshfollowed by the other arguments.
116778e3e3a7aSWarner LoshFor instance, the call
116788e3e3a7aSWarner Losh
116798e3e3a7aSWarner Losh<pre>
116808e3e3a7aSWarner Losh     $ lua -e "print(arg[1])"
116818e3e3a7aSWarner Losh</pre><p>
116828e3e3a7aSWarner Loshwill print "<code>-e</code>".
116838e3e3a7aSWarner LoshIf there is a script,
11684e112e9d2SKyle Evansthe script is called with arguments
116858e3e3a7aSWarner Losh<code>arg[1]</code>, &middot;&middot;&middot;, <code>arg[#arg]</code>.
116860495ed39SKyle EvansLike all chunks in Lua,
11687a9490b81SWarner Loshthe script is compiled as a variadic function.
116888e3e3a7aSWarner Losh
116898e3e3a7aSWarner Losh
116908e3e3a7aSWarner Losh<p>
116918e3e3a7aSWarner LoshIn interactive mode,
116928e3e3a7aSWarner LoshLua repeatedly prompts and waits for a line.
116938e3e3a7aSWarner LoshAfter reading a line,
116948e3e3a7aSWarner LoshLua first try to interpret the line as an expression.
116958e3e3a7aSWarner LoshIf it succeeds, it prints its value.
116968e3e3a7aSWarner LoshOtherwise, it interprets the line as a statement.
116978e3e3a7aSWarner LoshIf you write an incomplete statement,
116988e3e3a7aSWarner Loshthe interpreter waits for its completion
116998e3e3a7aSWarner Loshby issuing a different prompt.
117008e3e3a7aSWarner Losh
117018e3e3a7aSWarner Losh
117028e3e3a7aSWarner Losh<p>
117038e3e3a7aSWarner LoshIf the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string,
117048e3e3a7aSWarner Loshthen its value is used as the prompt.
117058e3e3a7aSWarner LoshSimilarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string,
117068e3e3a7aSWarner Loshits value is used as the secondary prompt
117078e3e3a7aSWarner Losh(issued during incomplete statements).
117088e3e3a7aSWarner Losh
117098e3e3a7aSWarner Losh
117108e3e3a7aSWarner Losh<p>
117118e3e3a7aSWarner LoshIn case of unprotected errors in the script,
117128e3e3a7aSWarner Loshthe interpreter reports the error to the standard error stream.
117138e3e3a7aSWarner LoshIf the error object is not a string but
117148e3e3a7aSWarner Loshhas a metamethod <code>__tostring</code>,
117158e3e3a7aSWarner Loshthe interpreter calls this metamethod to produce the final message.
117168e3e3a7aSWarner LoshOtherwise, the interpreter converts the error object to a string
117178e3e3a7aSWarner Loshand adds a stack traceback to it.
117180495ed39SKyle EvansWhen warnings are on,
117190495ed39SKyle Evansthey are simply printed in the standard error output.
117208e3e3a7aSWarner Losh
117218e3e3a7aSWarner Losh
117228e3e3a7aSWarner Losh<p>
117238e3e3a7aSWarner LoshWhen finishing normally,
117248e3e3a7aSWarner Loshthe interpreter closes its main Lua state
117258e3e3a7aSWarner Losh(see <a href="#lua_close"><code>lua_close</code></a>).
117268e3e3a7aSWarner LoshThe script can avoid this step by
117278e3e3a7aSWarner Loshcalling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate.
117288e3e3a7aSWarner Losh
117298e3e3a7aSWarner Losh
117308e3e3a7aSWarner Losh<p>
117318e3e3a7aSWarner LoshTo allow the use of Lua as a
117328e3e3a7aSWarner Loshscript interpreter in Unix systems,
117330495ed39SKyle EvansLua skips the first line of a file chunk if it starts with <code>#</code>.
117348e3e3a7aSWarner LoshTherefore, Lua scripts can be made into executable programs
117358e3e3a7aSWarner Loshby using <code>chmod +x</code> and the&nbsp;<code>#!</code> form,
117368e3e3a7aSWarner Loshas in
117378e3e3a7aSWarner Losh
117388e3e3a7aSWarner Losh<pre>
117398e3e3a7aSWarner Losh     #!/usr/local/bin/lua
117408e3e3a7aSWarner Losh</pre><p>
117410495ed39SKyle EvansOf course,
117428e3e3a7aSWarner Loshthe location of the Lua interpreter may be different in your machine.
117438e3e3a7aSWarner LoshIf <code>lua</code> is in your <code>PATH</code>,
117448e3e3a7aSWarner Loshthen
117458e3e3a7aSWarner Losh
117468e3e3a7aSWarner Losh<pre>
117478e3e3a7aSWarner Losh     #!/usr/bin/env lua
117488e3e3a7aSWarner Losh</pre><p>
117490495ed39SKyle Evansis a more portable solution.
117508e3e3a7aSWarner Losh
117518e3e3a7aSWarner Losh
117528e3e3a7aSWarner Losh
117538e3e3a7aSWarner Losh<h1>8 &ndash; <a name="8">Incompatibilities with the Previous Version</a></h1>
117548e3e3a7aSWarner Losh
117550495ed39SKyle Evans
117560495ed39SKyle Evans
117578e3e3a7aSWarner Losh<p>
117588e3e3a7aSWarner LoshHere we list the incompatibilities that you may find when moving a program
117590495ed39SKyle Evansfrom Lua&nbsp;5.3 to Lua&nbsp;5.4.
117600495ed39SKyle Evans
117610495ed39SKyle Evans
117620495ed39SKyle Evans<p>
117638e3e3a7aSWarner LoshYou can avoid some incompatibilities by compiling Lua with
117648e3e3a7aSWarner Loshappropriate options (see file <code>luaconf.h</code>).
117658e3e3a7aSWarner LoshHowever,
117668e3e3a7aSWarner Loshall these compatibility options will be removed in the future.
117670495ed39SKyle EvansMore often than not,
117680495ed39SKyle Evanscompatibility issues arise when these compatibility options
117690495ed39SKyle Evansare removed.
117700495ed39SKyle EvansSo, whenever you have the chance,
117710495ed39SKyle Evansyou should try to test your code with a version of Lua compiled
117720495ed39SKyle Evanswith all compatibility options turned off.
117730495ed39SKyle EvansThat will ease transitions to newer versions of Lua.
117748e3e3a7aSWarner Losh
117758e3e3a7aSWarner Losh
117768e3e3a7aSWarner Losh<p>
117778e3e3a7aSWarner LoshLua versions can always change the C API in ways that
117788e3e3a7aSWarner Loshdo not imply source-code changes in a program,
117798e3e3a7aSWarner Loshsuch as the numeric values for constants
117808e3e3a7aSWarner Loshor the implementation of functions as macros.
117818e3e3a7aSWarner LoshTherefore,
117820495ed39SKyle Evansyou should never assume that binaries are compatible between
117838e3e3a7aSWarner Loshdifferent Lua versions.
117848e3e3a7aSWarner LoshAlways recompile clients of the Lua API when
117858e3e3a7aSWarner Loshusing a new version.
117868e3e3a7aSWarner Losh
117878e3e3a7aSWarner Losh
117888e3e3a7aSWarner Losh<p>
117898e3e3a7aSWarner LoshSimilarly, Lua versions can always change the internal representation
117908e3e3a7aSWarner Loshof precompiled chunks;
117918e3e3a7aSWarner Loshprecompiled chunks are not compatible between different Lua versions.
117928e3e3a7aSWarner Losh
117938e3e3a7aSWarner Losh
117948e3e3a7aSWarner Losh<p>
117958e3e3a7aSWarner LoshThe standard paths in the official distribution may
117968e3e3a7aSWarner Loshchange between versions.
117978e3e3a7aSWarner Losh
117988e3e3a7aSWarner Losh
117998e3e3a7aSWarner Losh
118000495ed39SKyle Evans
118010495ed39SKyle Evans
118020495ed39SKyle Evans<h2>8.1 &ndash; <a name="8.1">Incompatibilities in the Language</a></h2>
118038e3e3a7aSWarner Losh<ul>
118048e3e3a7aSWarner Losh
118058e3e3a7aSWarner Losh<li>
118060495ed39SKyle EvansThe coercion of strings to numbers in
118070495ed39SKyle Evansarithmetic and bitwise operations
118080495ed39SKyle Evanshas been removed from the core language.
118090495ed39SKyle EvansThe string library does a similar job
118100495ed39SKyle Evansfor arithmetic (but not for bitwise) operations
118110495ed39SKyle Evansusing the string metamethods.
118120495ed39SKyle EvansHowever, unlike in previous versions,
118130495ed39SKyle Evansthe new implementation preserves the implicit type of the numeral
118140495ed39SKyle Evansin the string.
118150495ed39SKyle EvansFor instance, the result of <code>"1" + "2"</code> now is an integer,
118160495ed39SKyle Evansnot a float.
118178e3e3a7aSWarner Losh</li>
118188e3e3a7aSWarner Losh
118198e3e3a7aSWarner Losh<li>
118200495ed39SKyle EvansLiteral decimal integer constants that overflow are read as floats,
118210495ed39SKyle Evansinstead of wrapping around.
118220495ed39SKyle EvansYou can use hexadecimal notation for such constants if you
118230495ed39SKyle Evanswant the old behavior
118240495ed39SKyle Evans(reading them as integers with wrap around).
118258e3e3a7aSWarner Losh</li>
118268e3e3a7aSWarner Losh
118278e3e3a7aSWarner Losh<li>
118280495ed39SKyle EvansThe use of the <code>__lt</code> metamethod to emulate <code>__le</code>
118290495ed39SKyle Evanshas been removed.
118300495ed39SKyle EvansWhen needed, this metamethod must be explicitly defined.
118310495ed39SKyle Evans</li>
118320495ed39SKyle Evans
118330495ed39SKyle Evans<li>
118340495ed39SKyle EvansThe semantics of the numerical <b>for</b> loop
118350495ed39SKyle Evansover integers changed in some details.
118360495ed39SKyle EvansIn particular, the control variable never wraps around.
118370495ed39SKyle Evans</li>
118380495ed39SKyle Evans
118390495ed39SKyle Evans<li>
118400495ed39SKyle EvansA label for a <b>goto</b> cannot be declared where a label with the same
118410495ed39SKyle Evansname is visible, even if this other label is declared in an enclosing
118420495ed39SKyle Evansblock.
118430495ed39SKyle Evans</li>
118440495ed39SKyle Evans
118450495ed39SKyle Evans<li>
118460495ed39SKyle EvansWhen finalizing an object,
118470495ed39SKyle EvansLua does not ignore <code>__gc</code> metamethods that are not functions.
118480495ed39SKyle EvansAny value will be called, if present.
118490495ed39SKyle Evans(Non-callable values will generate a warning,
118500495ed39SKyle Evanslike any other error when calling a finalizer.)
118518e3e3a7aSWarner Losh</li>
118528e3e3a7aSWarner Losh
118538e3e3a7aSWarner Losh</ul>
118548e3e3a7aSWarner Losh
118558e3e3a7aSWarner Losh
118568e3e3a7aSWarner Losh
118578e3e3a7aSWarner Losh
118580495ed39SKyle Evans<h2>8.2 &ndash; <a name="8.2">Incompatibilities in the Libraries</a></h2>
118598e3e3a7aSWarner Losh<ul>
118608e3e3a7aSWarner Losh
118618e3e3a7aSWarner Losh<li>
118620495ed39SKyle EvansThe function <a href="#pdf-print"><code>print</code></a> does not call <a href="#pdf-tostring"><code>tostring</code></a>
118630495ed39SKyle Evansto format its arguments;
118640495ed39SKyle Evansinstead, it has this functionality hardwired.
118650495ed39SKyle EvansYou should use <code>__tostring</code> to modify how values are printed.
118668e3e3a7aSWarner Losh</li>
118678e3e3a7aSWarner Losh
118688e3e3a7aSWarner Losh<li>
118690495ed39SKyle EvansThe pseudo-random number generator used by the function <a href="#pdf-math.random"><code>math.random</code></a>
118700495ed39SKyle Evansnow starts with a somewhat random seed.
118710495ed39SKyle EvansMoreover, it uses a different algorithm.
118728e3e3a7aSWarner Losh</li>
118738e3e3a7aSWarner Losh
118748e3e3a7aSWarner Losh<li>
118750495ed39SKyle EvansBy default, the decoding functions in the <a href="#pdf-utf8"><code>utf8</code></a> library
118760495ed39SKyle Evansdo not accept surrogates as valid code points.
118770495ed39SKyle EvansAn extra parameter in these functions makes them more permissive.
118788e3e3a7aSWarner Losh</li>
118798e3e3a7aSWarner Losh
118808e3e3a7aSWarner Losh<li>
118810495ed39SKyle EvansThe options "<code>setpause</code>" and "<code>setstepmul</code>"
118820495ed39SKyle Evansof the function <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> are deprecated.
118830495ed39SKyle EvansYou should use the new option "<code>incremental</code>" to set them.
118848e3e3a7aSWarner Losh</li>
118858e3e3a7aSWarner Losh
118868e3e3a7aSWarner Losh<li>
118870495ed39SKyle EvansThe function <a href="#pdf-io.lines"><code>io.lines</code></a> now returns four values,
118880495ed39SKyle Evansinstead of just one.
118890495ed39SKyle EvansThat can be a problem when it is used as the sole
118900495ed39SKyle Evansargument to another function that has optional parameters,
118910495ed39SKyle Evanssuch as in <code>load(io.lines(filename, "L"))</code>.
118920495ed39SKyle EvansTo fix that issue,
118930495ed39SKyle Evansyou can wrap the call into parentheses,
118940495ed39SKyle Evansto adjust its number of results to one.
118958e3e3a7aSWarner Losh</li>
118968e3e3a7aSWarner Losh
118978e3e3a7aSWarner Losh</ul>
118988e3e3a7aSWarner Losh
118998e3e3a7aSWarner Losh
119008e3e3a7aSWarner Losh
119018e3e3a7aSWarner Losh
119020495ed39SKyle Evans<h2>8.3 &ndash; <a name="8.3">Incompatibilities in the API</a></h2>
119038e3e3a7aSWarner Losh
119048e3e3a7aSWarner Losh
119058e3e3a7aSWarner Losh<ul>
119068e3e3a7aSWarner Losh
119078e3e3a7aSWarner Losh<li>
119080495ed39SKyle EvansFull userdata now has an arbitrary number of associated user values.
119090495ed39SKyle EvansTherefore, the functions <code>lua_newuserdata</code>,
119100495ed39SKyle Evans<code>lua_setuservalue</code>, and <code>lua_getuservalue</code> were
119110495ed39SKyle Evansreplaced by <a href="#lua_newuserdatauv"><code>lua_newuserdatauv</code></a>,
119120495ed39SKyle Evans<a href="#lua_setiuservalue"><code>lua_setiuservalue</code></a>, and <a href="#lua_getiuservalue"><code>lua_getiuservalue</code></a>,
119130495ed39SKyle Evanswhich have an extra argument.
119140495ed39SKyle Evans
119150495ed39SKyle Evans
119160495ed39SKyle Evans<p>
119170495ed39SKyle EvansFor compatibility, the old names still work as macros assuming
119180495ed39SKyle Evansone single user value.
119190495ed39SKyle EvansNote, however, that userdata with zero user values
119200495ed39SKyle Evansare more efficient memory-wise.
119218e3e3a7aSWarner Losh</li>
119228e3e3a7aSWarner Losh
119238e3e3a7aSWarner Losh<li>
119240495ed39SKyle EvansThe function <a href="#lua_resume"><code>lua_resume</code></a> has an extra parameter.
119250495ed39SKyle EvansThis out parameter returns the number of values on
119260495ed39SKyle Evansthe top of the stack that were yielded or returned by the coroutine.
119270495ed39SKyle Evans(In previous versions,
119280495ed39SKyle Evansthose values were the entire stack.)
119298e3e3a7aSWarner Losh</li>
119308e3e3a7aSWarner Losh
119318e3e3a7aSWarner Losh<li>
119320495ed39SKyle EvansThe function <a href="#lua_version"><code>lua_version</code></a> returns the version number,
119330495ed39SKyle Evansinstead of an address of the version number.
119340495ed39SKyle EvansThe Lua core should work correctly with libraries using their
119350495ed39SKyle Evansown static copies of the same core,
119360495ed39SKyle Evansso there is no need to check whether they are using the same
119370495ed39SKyle Evansaddress space.
119388e3e3a7aSWarner Losh</li>
119398e3e3a7aSWarner Losh
119408e3e3a7aSWarner Losh<li>
119410495ed39SKyle EvansThe constant <code>LUA_ERRGCMM</code> was removed.
119420495ed39SKyle EvansErrors in finalizers are never propagated;
119430495ed39SKyle Evansinstead, they generate a warning.
119440495ed39SKyle Evans</li>
119450495ed39SKyle Evans
119460495ed39SKyle Evans<li>
119470495ed39SKyle EvansThe options <code>LUA_GCSETPAUSE</code> and <code>LUA_GCSETSTEPMUL</code>
119480495ed39SKyle Evansof the function <a href="#lua_gc"><code>lua_gc</code></a> are deprecated.
119490495ed39SKyle EvansYou should use the new option <code>LUA_GCINC</code> to set them.
119508e3e3a7aSWarner Losh</li>
119518e3e3a7aSWarner Losh
119528e3e3a7aSWarner Losh</ul>
119538e3e3a7aSWarner Losh
119548e3e3a7aSWarner Losh
119558e3e3a7aSWarner Losh
119568e3e3a7aSWarner Losh
119578e3e3a7aSWarner Losh<h1>9 &ndash; <a name="9">The Complete Syntax of Lua</a></h1>
119588e3e3a7aSWarner Losh
119598e3e3a7aSWarner Losh<p>
119608e3e3a7aSWarner LoshHere is the complete syntax of Lua in extended BNF.
119618e3e3a7aSWarner LoshAs usual in extended BNF,
119628e3e3a7aSWarner Losh{A} means 0 or more As,
119638e3e3a7aSWarner Loshand [A] means an optional A.
119648e3e3a7aSWarner Losh(For operator precedences, see <a href="#3.4.8">&sect;3.4.8</a>;
119658e3e3a7aSWarner Loshfor a description of the terminals
119668e3e3a7aSWarner LoshName, Numeral,
119678e3e3a7aSWarner Loshand LiteralString, see <a href="#3.1">&sect;3.1</a>.)
119688e3e3a7aSWarner Losh
119698e3e3a7aSWarner Losh
119708e3e3a7aSWarner Losh
119718e3e3a7aSWarner Losh
119728e3e3a7aSWarner Losh<pre>
119738e3e3a7aSWarner Losh
119748e3e3a7aSWarner Losh	chunk ::= block
119758e3e3a7aSWarner Losh
119768e3e3a7aSWarner Losh	block ::= {stat} [retstat]
119778e3e3a7aSWarner Losh
119788e3e3a7aSWarner Losh	stat ::=  &lsquo;<b>;</b>&rsquo; |
119798e3e3a7aSWarner Losh		 varlist &lsquo;<b>=</b>&rsquo; explist |
119808e3e3a7aSWarner Losh		 functioncall |
119818e3e3a7aSWarner Losh		 label |
119828e3e3a7aSWarner Losh		 <b>break</b> |
119838e3e3a7aSWarner Losh		 <b>goto</b> Name |
119848e3e3a7aSWarner Losh		 <b>do</b> block <b>end</b> |
119858e3e3a7aSWarner Losh		 <b>while</b> exp <b>do</b> block <b>end</b> |
119868e3e3a7aSWarner Losh		 <b>repeat</b> block <b>until</b> exp |
119878e3e3a7aSWarner Losh		 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> |
119888e3e3a7aSWarner Losh		 <b>for</b> Name &lsquo;<b>=</b>&rsquo; exp &lsquo;<b>,</b>&rsquo; exp [&lsquo;<b>,</b>&rsquo; exp] <b>do</b> block <b>end</b> |
119898e3e3a7aSWarner Losh		 <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> |
119908e3e3a7aSWarner Losh		 <b>function</b> funcname funcbody |
119918e3e3a7aSWarner Losh		 <b>local</b> <b>function</b> Name funcbody |
119920495ed39SKyle Evans		 <b>local</b> attnamelist [&lsquo;<b>=</b>&rsquo; explist]
119930495ed39SKyle Evans
119940495ed39SKyle Evans	attnamelist ::=  Name attrib {&lsquo;<b>,</b>&rsquo; Name attrib}
119950495ed39SKyle Evans
119960495ed39SKyle Evans	attrib ::= [&lsquo;<b>&lt;</b>&rsquo; Name &lsquo;<b>&gt;</b>&rsquo;]
119978e3e3a7aSWarner Losh
119988e3e3a7aSWarner Losh	retstat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
119998e3e3a7aSWarner Losh
120008e3e3a7aSWarner Losh	label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
120018e3e3a7aSWarner Losh
120028e3e3a7aSWarner Losh	funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
120038e3e3a7aSWarner Losh
120048e3e3a7aSWarner Losh	varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
120058e3e3a7aSWarner Losh
120068e3e3a7aSWarner Losh	var ::=  Name | prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; | prefixexp &lsquo;<b>.</b>&rsquo; Name
120078e3e3a7aSWarner Losh
120088e3e3a7aSWarner Losh	namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
120098e3e3a7aSWarner Losh
120108e3e3a7aSWarner Losh	explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
120118e3e3a7aSWarner Losh
120128e3e3a7aSWarner Losh	exp ::=  <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | &lsquo;<b>...</b>&rsquo; | functiondef |
120138e3e3a7aSWarner Losh		 prefixexp | tableconstructor | exp binop exp | unop exp
120148e3e3a7aSWarner Losh
120158e3e3a7aSWarner Losh	prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
120168e3e3a7aSWarner Losh
120178e3e3a7aSWarner Losh	functioncall ::=  prefixexp args | prefixexp &lsquo;<b>:</b>&rsquo; Name args
120188e3e3a7aSWarner Losh
120198e3e3a7aSWarner Losh	args ::=  &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo; | tableconstructor | LiteralString
120208e3e3a7aSWarner Losh
120218e3e3a7aSWarner Losh	functiondef ::= <b>function</b> funcbody
120228e3e3a7aSWarner Losh
120238e3e3a7aSWarner Losh	funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
120248e3e3a7aSWarner Losh
120258e3e3a7aSWarner Losh	parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
120268e3e3a7aSWarner Losh
120278e3e3a7aSWarner Losh	tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
120288e3e3a7aSWarner Losh
120298e3e3a7aSWarner Losh	fieldlist ::= field {fieldsep field} [fieldsep]
120308e3e3a7aSWarner Losh
120318e3e3a7aSWarner Losh	field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
120328e3e3a7aSWarner Losh
120338e3e3a7aSWarner Losh	fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
120348e3e3a7aSWarner Losh
120358e3e3a7aSWarner Losh	binop ::=  &lsquo;<b>+</b>&rsquo; | &lsquo;<b>-</b>&rsquo; | &lsquo;<b>*</b>&rsquo; | &lsquo;<b>/</b>&rsquo; | &lsquo;<b>//</b>&rsquo; | &lsquo;<b>^</b>&rsquo; | &lsquo;<b>%</b>&rsquo; |
120368e3e3a7aSWarner Losh		 &lsquo;<b>&amp;</b>&rsquo; | &lsquo;<b>~</b>&rsquo; | &lsquo;<b>|</b>&rsquo; | &lsquo;<b>&gt;&gt;</b>&rsquo; | &lsquo;<b>&lt;&lt;</b>&rsquo; | &lsquo;<b>..</b>&rsquo; |
120378e3e3a7aSWarner Losh		 &lsquo;<b>&lt;</b>&rsquo; | &lsquo;<b>&lt;=</b>&rsquo; | &lsquo;<b>&gt;</b>&rsquo; | &lsquo;<b>&gt;=</b>&rsquo; | &lsquo;<b>==</b>&rsquo; | &lsquo;<b>~=</b>&rsquo; |
120388e3e3a7aSWarner Losh		 <b>and</b> | <b>or</b>
120398e3e3a7aSWarner Losh
120408e3e3a7aSWarner Losh	unop ::= &lsquo;<b>-</b>&rsquo; | <b>not</b> | &lsquo;<b>#</b>&rsquo; | &lsquo;<b>~</b>&rsquo;
120418e3e3a7aSWarner Losh
120428e3e3a7aSWarner Losh</pre>
120438e3e3a7aSWarner Losh
120448e3e3a7aSWarner Losh<p>
120458e3e3a7aSWarner Losh
120468e3e3a7aSWarner Losh
120478e3e3a7aSWarner Losh
120488e3e3a7aSWarner Losh
120498e3e3a7aSWarner Losh
120508e3e3a7aSWarner Losh
120518e3e3a7aSWarner Losh<P CLASS="footer">
120528e3e3a7aSWarner LoshLast update:
12053*3068d706SWarner LoshWed May 21 21:09:59 UTC 2025
120548e3e3a7aSWarner Losh</P>
120558e3e3a7aSWarner Losh<!--
12056*3068d706SWarner LoshLast change: revised for Lua 5.4.8
120578e3e3a7aSWarner Losh-->
120588e3e3a7aSWarner Losh
120598e3e3a7aSWarner Losh</body></html>
120608e3e3a7aSWarner Losh
12061