xref: /freebsd/contrib/lua/doc/manual.html (revision a9490b81b032b43cdb3c8c76b4d01bbad9ff82c1) 
18e3e3a7aSWarner Losh<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
28e3e3a7aSWarner Losh<HTML>
38e3e3a7aSWarner Losh<HEAD>
40495ed39SKyle Evans<TITLE>Lua 5.4 Reference Manual</TITLE>
58e3e3a7aSWarner Losh<LINK REL="stylesheet" TYPE="text/css" HREF="lua.css">
68e3e3a7aSWarner Losh<LINK REL="stylesheet" TYPE="text/css" HREF="manual.css">
78e3e3a7aSWarner Losh<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1">
88e3e3a7aSWarner Losh</HEAD>
98e3e3a7aSWarner Losh
108e3e3a7aSWarner Losh<BODY>
118e3e3a7aSWarner Losh
128e3e3a7aSWarner Losh<H1>
138e3e3a7aSWarner Losh<A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A>
140495ed39SKyle EvansLua 5.4 Reference Manual
158e3e3a7aSWarner Losh</H1>
168e3e3a7aSWarner Losh
178e3e3a7aSWarner Losh<P>
188e3e3a7aSWarner Loshby Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
198e3e3a7aSWarner Losh
208e3e3a7aSWarner Losh<P>
218e3e3a7aSWarner Losh<SMALL>
22*a9490b81SWarner LoshCopyright &copy; 2020&ndash;2023 Lua.org, PUC-Rio.
238e3e3a7aSWarner LoshFreely available under the terms of the
248e3e3a7aSWarner Losh<a href="http://www.lua.org/license.html">Lua license</a>.
258e3e3a7aSWarner Losh</SMALL>
268e3e3a7aSWarner Losh
278e3e3a7aSWarner Losh<DIV CLASS="menubar">
288e3e3a7aSWarner Losh<A HREF="contents.html#contents">contents</A>
298e3e3a7aSWarner Losh&middot;
308e3e3a7aSWarner Losh<A HREF="contents.html#index">index</A>
318e3e3a7aSWarner Losh&middot;
328e3e3a7aSWarner Losh<A HREF="http://www.lua.org/manual/">other versions</A>
338e3e3a7aSWarner Losh</DIV>
348e3e3a7aSWarner Losh
358e3e3a7aSWarner Losh<!-- ====================================================================== -->
368e3e3a7aSWarner Losh<p>
378e3e3a7aSWarner Losh
380495ed39SKyle Evans<!-- $Id: manual.of $ -->
398e3e3a7aSWarner Losh
408e3e3a7aSWarner Losh
418e3e3a7aSWarner Losh
428e3e3a7aSWarner Losh
438e3e3a7aSWarner Losh<h1>1 &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>,
66*a9490b81SWarner 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,
3948e3e3a7aSWarner Loshbut programs may generate errors with
3958e3e3a7aSWarner Loshany value as the error object.
3968e3e3a7aSWarner LoshIt is up to the Lua program or its host to handle such error objects.
3970495ed39SKyle EvansFor historical reasons,
3980495ed39SKyle Evansan error object is often called an <em>error message</em>,
3990495ed39SKyle Evanseven though it does not have to be a string.
4008e3e3a7aSWarner Losh
4018e3e3a7aSWarner Losh
4028e3e3a7aSWarner Losh<p>
4030495ed39SKyle EvansWhen you use <a href="#pdf-xpcall"><code>xpcall</code></a> (or <a href="#lua_pcall"><code>lua_pcall</code></a>, in C)
4048e3e3a7aSWarner Loshyou may give a <em>message handler</em>
4058e3e3a7aSWarner Loshto be called in case of errors.
4068e3e3a7aSWarner LoshThis function is called with the original error object
4078e3e3a7aSWarner Loshand returns a new error object.
4088e3e3a7aSWarner LoshIt is called before the error unwinds the stack,
4098e3e3a7aSWarner Loshso that it can gather more information about the error,
4108e3e3a7aSWarner Loshfor instance by inspecting the stack and creating a stack traceback.
4118e3e3a7aSWarner LoshThis message handler is still protected by the protected call;
4128e3e3a7aSWarner Loshso, an error inside the message handler
4138e3e3a7aSWarner Loshwill call the message handler again.
4148e3e3a7aSWarner LoshIf this loop goes on for too long,
4158e3e3a7aSWarner LoshLua breaks it and returns an appropriate message.
4160495ed39SKyle EvansThe message handler is called only for regular runtime errors.
4178e3e3a7aSWarner LoshIt is not called for memory-allocation errors
4180495ed39SKyle Evansnor for errors while running finalizers or other message handlers.
4190495ed39SKyle Evans
4200495ed39SKyle Evans
4210495ed39SKyle Evans<p>
4220495ed39SKyle EvansLua also offers a system of <em>warnings</em> (see <a href="#pdf-warn"><code>warn</code></a>).
4230495ed39SKyle EvansUnlike errors, warnings do not interfere
4240495ed39SKyle Evansin any way with program execution.
4250495ed39SKyle EvansThey typically only generate a message to the user,
4260495ed39SKyle Evansalthough this behavior can be adapted from C (see <a href="#lua_setwarnf"><code>lua_setwarnf</code></a>).
4278e3e3a7aSWarner Losh
4288e3e3a7aSWarner Losh
4298e3e3a7aSWarner Losh
4308e3e3a7aSWarner Losh
4318e3e3a7aSWarner Losh
4328e3e3a7aSWarner Losh<h2>2.4 &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,
4560495ed39SKyle Evansa metamethod may in fact be any callable value,
4570495ed39SKyle Evanswhich is either a function or a value with a <code>__call</code> metamethod.
4588e3e3a7aSWarner Losh
4598e3e3a7aSWarner Losh
4608e3e3a7aSWarner Losh<p>
4618e3e3a7aSWarner LoshYou can query the metatable of any value
4628e3e3a7aSWarner Loshusing the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function.
4638e3e3a7aSWarner LoshLua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>).
4648e3e3a7aSWarner Losh
4658e3e3a7aSWarner Losh
4668e3e3a7aSWarner Losh<p>
4678e3e3a7aSWarner LoshYou can replace the metatable of tables
4688e3e3a7aSWarner Loshusing the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function.
4690495ed39SKyle EvansYou cannot change the metatable of other types from Lua code,
4700495ed39SKyle Evansexcept by using the debug library (<a href="#6.10">&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,
1382*a9490b81SWarner Loshmarked by a letter '<code>p</code>' or '<code>P</code>' and written in decimal.
1383*a9490b81SWarner Losh(For instance, <code>0x1.fp10</code> denotes 1984,
1384*a9490b81SWarner Loshwhich is <em>0x1f / 16</em> multiplied by <em>2<sup>10</sup></em>.)
13850495ed39SKyle Evans
13860495ed39SKyle Evans
13870495ed39SKyle Evans<p>
13888e3e3a7aSWarner LoshA numeric constant with a radix point or an exponent
13898e3e3a7aSWarner Loshdenotes a float;
13908e3e3a7aSWarner Loshotherwise,
13910495ed39SKyle Evansif its value fits in an integer or it is a hexadecimal constant,
13920495ed39SKyle Evansit denotes an integer;
13930495ed39SKyle Evansotherwise (that is, a decimal integer numeral that overflows),
13940495ed39SKyle Evansit denotes a float.
13950495ed39SKyle EvansHexadecimal numerals with neither a radix point nor an exponent
13960495ed39SKyle Evansalways denote an integer value;
13970495ed39SKyle Evansif the value overflows, it <em>wraps around</em>
13980495ed39SKyle Evansto fit into a valid integer.
13990495ed39SKyle Evans
14000495ed39SKyle Evans
14010495ed39SKyle Evans<p>
14028e3e3a7aSWarner LoshExamples of valid integer constants are
14038e3e3a7aSWarner Losh
14048e3e3a7aSWarner Losh<pre>
14058e3e3a7aSWarner Losh     3   345   0xff   0xBEBADA
14068e3e3a7aSWarner Losh</pre><p>
14078e3e3a7aSWarner LoshExamples of valid float constants are
14088e3e3a7aSWarner Losh
14098e3e3a7aSWarner Losh<pre>
14108e3e3a7aSWarner Losh     3.0     3.1416     314.16e-2     0.31416E1     34e1
14118e3e3a7aSWarner Losh     0x0.1E  0xA23p-4   0X1.921FB54442D18P+1
14128e3e3a7aSWarner Losh</pre>
14138e3e3a7aSWarner Losh
14148e3e3a7aSWarner Losh<p>
14158e3e3a7aSWarner LoshA <em>comment</em> starts with a double hyphen (<code>--</code>)
14168e3e3a7aSWarner Loshanywhere outside a string.
14178e3e3a7aSWarner LoshIf the text immediately after <code>--</code> is not an opening long bracket,
14188e3e3a7aSWarner Loshthe comment is a <em>short comment</em>,
14198e3e3a7aSWarner Loshwhich runs until the end of the line.
14208e3e3a7aSWarner LoshOtherwise, it is a <em>long comment</em>,
14218e3e3a7aSWarner Loshwhich runs until the corresponding closing long bracket.
14228e3e3a7aSWarner Losh
14238e3e3a7aSWarner Losh
14248e3e3a7aSWarner Losh
14258e3e3a7aSWarner Losh
14268e3e3a7aSWarner Losh
14278e3e3a7aSWarner Losh<h2>3.2 &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
1626*a9490b81SWarner 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,
1632*a9490b81SWarner LoshLua ensures that all reads get the value of the variable
16338c784bb8SWarner Loshbefore the assignment.
16348e3e3a7aSWarner LoshThus the code
16358e3e3a7aSWarner Losh
16368e3e3a7aSWarner Losh<pre>
16378e3e3a7aSWarner Losh     i = 3
16388e3e3a7aSWarner Losh     i, a[i] = i+1, 20
16398e3e3a7aSWarner Losh</pre><p>
16408e3e3a7aSWarner Loshsets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
16418e3e3a7aSWarner Loshbecause the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
16428e3e3a7aSWarner Loshbefore it is assigned&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.
17288e3e3a7aSWarner LoshA goto may jump to any visible label as long as it does not
17298e3e3a7aSWarner Loshenter into the scope of a local variable.
17300495ed39SKyle EvansA label should not be declared
17310495ed39SKyle Evanswhere a label with the same name is visible,
17320495ed39SKyle Evanseven if this other label has been declared in an enclosing block.
17338e3e3a7aSWarner Losh
17348e3e3a7aSWarner Losh
17358e3e3a7aSWarner Losh<p>
17368e3e3a7aSWarner LoshThe <b>break</b> statement terminates the execution of a
17378e3e3a7aSWarner Losh<b>while</b>, <b>repeat</b>, or <b>for</b> loop,
17388e3e3a7aSWarner Loshskipping to the next statement after the loop:
17398e3e3a7aSWarner Losh
17408e3e3a7aSWarner Losh
17418e3e3a7aSWarner Losh<pre>
17428e3e3a7aSWarner Losh	stat ::= <b>break</b>
17438e3e3a7aSWarner Losh</pre><p>
17448e3e3a7aSWarner LoshA <b>break</b> ends the innermost enclosing loop.
17458e3e3a7aSWarner Losh
17468e3e3a7aSWarner Losh
17478e3e3a7aSWarner Losh<p>
17488e3e3a7aSWarner LoshThe <b>return</b> statement is used to return values
17498e3e3a7aSWarner Loshfrom a function or a chunk
17500495ed39SKyle Evans(which is handled as an anonymous function).
17518e3e3a7aSWarner Losh
17528e3e3a7aSWarner LoshFunctions can return more than one value,
17538e3e3a7aSWarner Loshso the syntax for the <b>return</b> statement is
17548e3e3a7aSWarner Losh
17558e3e3a7aSWarner Losh<pre>
17568e3e3a7aSWarner Losh	stat ::= <b>return</b> [explist] [&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
2051*a9490b81SWarner 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>
2198*a9490b81SWarner LoshIt is always a good practice not to rely on the
2199*a9490b81SWarner Loshimplicit coercions from strings to numbers,
2200*a9490b81SWarner Loshas they are not always applied;
22010495ed39SKyle Evansin particular, <code>"1"==1</code> is false and <code>"1"&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>
2505*a9490b81SWarner Loshand the expression is a multires expression,
25068e3e3a7aSWarner Loshthen all values returned by this expression enter the list consecutively
2507*a9490b81SWarner Losh(see <a href="#3.4.12">&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>):
2571*a9490b81SWarner LoshIn a tail call,
25728e3e3a7aSWarner Loshthe called function reuses the stack entry of the calling function.
25738e3e3a7aSWarner LoshTherefore, there is no limit on the number of nested tail calls that
25748e3e3a7aSWarner Losha program can execute.
25758e3e3a7aSWarner LoshHowever, a tail call erases any debug information about the
25768e3e3a7aSWarner Loshcalling function.
25778e3e3a7aSWarner LoshNote that a tail call only happens with a particular syntax,
25780495ed39SKyle Evanswhere the <b>return</b> has one single function call as argument,
25790495ed39SKyle Evansand it is outside the scope of any to-be-closed variable.
25800495ed39SKyle EvansThis syntax makes the calling function return exactly
25810495ed39SKyle Evansthe returns of the called function,
25820495ed39SKyle Evanswithout any intervening action.
25838e3e3a7aSWarner LoshSo, none of the following examples are tail calls:
25848e3e3a7aSWarner Losh
25858e3e3a7aSWarner Losh<pre>
25868e3e3a7aSWarner Losh     return (f(x))        -- results adjusted to 1
25870495ed39SKyle Evans     return 2 * f(x)      -- result multiplied by 2
25888e3e3a7aSWarner Losh     return x, f(x)       -- additional results
25898e3e3a7aSWarner Losh     f(x); return         -- results discarded
25908e3e3a7aSWarner Losh     return x or f(x)     -- results adjusted to 1
25918e3e3a7aSWarner Losh</pre>
25928e3e3a7aSWarner Losh
25938e3e3a7aSWarner Losh
25948e3e3a7aSWarner Losh
25958e3e3a7aSWarner Losh
25968e3e3a7aSWarner Losh<h3>3.4.11 &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
2674*a9490b81SWarner Loshthe length of its list of parameters (see <a href="#3.4.12">&sect;3.4.12</a>),
2675*a9490b81SWarner Loshunless the function is a <em>variadic function</em>,
26768e3e3a7aSWarner Loshwhich is indicated by three dots ('<code>...</code>')
26778e3e3a7aSWarner Loshat the end of its parameter list.
2678*a9490b81SWarner LoshA variadic function does not adjust its argument list;
26798e3e3a7aSWarner Loshinstead, it collects all extra arguments and supplies them
26808e3e3a7aSWarner Loshto the function through a <em>vararg expression</em>,
26818e3e3a7aSWarner Loshwhich is also written as three dots.
26828e3e3a7aSWarner LoshThe value of this expression is a list of all actual extra arguments,
2683*a9490b81SWarner Loshsimilar to a function with multiple results (see <a href="#3.4.12">&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
2744*a9490b81SWarner Losh<h3>3.4.12 &ndash; <a name="3.4.12">Lists of expressions, multiple results,
2745*a9490b81SWarner Loshand adjustment</a></h3>
2746*a9490b81SWarner Losh
2747*a9490b81SWarner Losh<p>
2748*a9490b81SWarner LoshBoth function calls and vararg expressions can result in multiple values.
2749*a9490b81SWarner LoshThese expressions are called <em>multires expressions</em>.
2750*a9490b81SWarner Losh
2751*a9490b81SWarner Losh
2752*a9490b81SWarner Losh<p>
2753*a9490b81SWarner LoshWhen a multires expression is used as the last element
2754*a9490b81SWarner Loshof a list of expressions,
2755*a9490b81SWarner Loshall results from the expression are added to the
2756*a9490b81SWarner Loshlist of values produced by the list of expressions.
2757*a9490b81SWarner LoshNote that a single expression
2758*a9490b81SWarner Loshin a place that expects a list of expressions
2759*a9490b81SWarner Loshis the last expression in that (singleton) list.
2760*a9490b81SWarner Losh
2761*a9490b81SWarner Losh
2762*a9490b81SWarner Losh<p>
2763*a9490b81SWarner LoshThese are the places where Lua expects a list of expressions:
2764*a9490b81SWarner Losh
2765*a9490b81SWarner Losh<ul>
2766*a9490b81SWarner Losh
2767*a9490b81SWarner Losh<li>A <b>return</b> statement,
2768*a9490b81SWarner Loshfor instance <code>return e1, e2, e3</code> (see <a href="#3.3.4">&sect;3.3.4</a>).</li>
2769*a9490b81SWarner Losh
2770*a9490b81SWarner Losh<li>A table constructor,
2771*a9490b81SWarner Loshfor instance <code>{e1, e2, e3}</code> (see <a href="#3.4.9">&sect;3.4.9</a>).</li>
2772*a9490b81SWarner Losh
2773*a9490b81SWarner Losh<li>The arguments of a function call,
2774*a9490b81SWarner Loshfor instance <code>foo(e1, e2, e3)</code> (see <a href="#3.4.10">&sect;3.4.10</a>).</li>
2775*a9490b81SWarner Losh
2776*a9490b81SWarner Losh<li>A multiple assignment,
2777*a9490b81SWarner Loshfor instance <code>a , b, c = e1, e2, e3</code> (see <a href="#3.3.3">&sect;3.3.3</a>).</li>
2778*a9490b81SWarner Losh
2779*a9490b81SWarner Losh<li>A local declaration,
2780*a9490b81SWarner Loshfor instance <code>local a , b, c = e1, e2, e3</code> (see <a href="#3.3.7">&sect;3.3.7</a>).</li>
2781*a9490b81SWarner Losh
2782*a9490b81SWarner Losh<li>The initial values in a generic <b>for</b> loop,
2783*a9490b81SWarner Loshfor instance <code>for k in e1, e2, e3 do ... end</code> (see <a href="#3.3.5">&sect;3.3.5</a>).</li>
2784*a9490b81SWarner Losh
2785*a9490b81SWarner Losh</ul><p>
2786*a9490b81SWarner LoshIn the last four cases,
2787*a9490b81SWarner Loshthe list of values from the list of expressions
2788*a9490b81SWarner Loshmust be <em>adjusted</em> to a specific length:
2789*a9490b81SWarner Loshthe number of parameters in a call to a non-variadic function
2790*a9490b81SWarner Losh(see <a href="#3.4.11">&sect;3.4.11</a>),
2791*a9490b81SWarner Loshthe number of variables in a multiple assignment or
2792*a9490b81SWarner Losha local declaration,
2793*a9490b81SWarner Loshand exactly four values for a generic <b>for</b> loop.
2794*a9490b81SWarner LoshThe <em>adjustment</em> follows these rules:
2795*a9490b81SWarner LoshIf there are more values than needed,
2796*a9490b81SWarner Loshthe extra values are thrown away;
2797*a9490b81SWarner Loshif there are fewer values than needed,
2798*a9490b81SWarner Loshthe list is extended with <b>nil</b>'s.
2799*a9490b81SWarner LoshWhen the list of expressions ends with a multires expression,
2800*a9490b81SWarner Loshall results from that expression enter the list of values
2801*a9490b81SWarner Loshbefore the adjustment.
2802*a9490b81SWarner Losh
2803*a9490b81SWarner Losh
2804*a9490b81SWarner Losh<p>
2805*a9490b81SWarner LoshWhen a multires expression is used
2806*a9490b81SWarner Loshin a list of expressions without being the last element,
2807*a9490b81SWarner Loshor in a place where the syntax expects a single expression,
2808*a9490b81SWarner LoshLua adjusts the result list of that expression to one element.
2809*a9490b81SWarner LoshAs a particular case,
2810*a9490b81SWarner Loshthe syntax expects a single expression inside a parenthesized expression;
2811*a9490b81SWarner Loshtherefore, adding parentheses around a multires expression
2812*a9490b81SWarner Loshforces it to produce exactly one result.
2813*a9490b81SWarner Losh
2814*a9490b81SWarner Losh
2815*a9490b81SWarner Losh<p>
2816*a9490b81SWarner LoshWe seldom need to use a vararg expression in a place
2817*a9490b81SWarner Loshwhere the syntax expects a single expression.
2818*a9490b81SWarner Losh(Usually it is simpler to add a regular parameter before
2819*a9490b81SWarner Loshthe variadic part and use that parameter.)
2820*a9490b81SWarner LoshWhen there is such a need,
2821*a9490b81SWarner Loshwe recommend assigning the vararg expression
2822*a9490b81SWarner Loshto a single variable and using that variable
2823*a9490b81SWarner Loshin its place.
2824*a9490b81SWarner Losh
2825*a9490b81SWarner Losh
2826*a9490b81SWarner Losh<p>
2827*a9490b81SWarner LoshHere are some examples of uses of mutlres expressions.
2828*a9490b81SWarner LoshIn all cases, when the construction needs
2829*a9490b81SWarner Losh"the n-th result" and there is no such result,
2830*a9490b81SWarner Loshit uses a <b>nil</b>.
2831*a9490b81SWarner Losh
2832*a9490b81SWarner Losh<pre>
2833*a9490b81SWarner Losh     print(x, f())      -- prints x and all results from f().
2834*a9490b81SWarner Losh     print(x, (f()))    -- prints x and the first result from f().
2835*a9490b81SWarner Losh     print(f(), x)      -- prints the first result from f() and x.
2836*a9490b81SWarner Losh     print(1 + f())     -- prints 1 added to the first result from f().
2837*a9490b81SWarner Losh     local x = ...      -- x gets the first vararg argument.
2838*a9490b81SWarner Losh     x,y = ...          -- x gets the first vararg argument,
2839*a9490b81SWarner Losh                        -- y gets the second vararg argument.
2840*a9490b81SWarner Losh     x,y,z = w, f()     -- x gets w, y gets the first result from f(),
2841*a9490b81SWarner Losh                        -- z gets the second result from f().
2842*a9490b81SWarner Losh     x,y,z = f()        -- x gets the first result from f(),
2843*a9490b81SWarner Losh                        -- y gets the second result from f(),
2844*a9490b81SWarner Losh                        -- z gets the third result from f().
2845*a9490b81SWarner Losh     x,y,z = f(), g()   -- x gets the first result from f(),
2846*a9490b81SWarner Losh                        -- y gets the first result from g(),
2847*a9490b81SWarner Losh                        -- z gets the second result from g().
2848*a9490b81SWarner Losh     x,y,z = (f())      -- x gets the first result from f(), y and z get nil.
2849*a9490b81SWarner Losh     return f()         -- returns all results from f().
2850*a9490b81SWarner Losh     return x, ...      -- returns x and all received vararg arguments.
2851*a9490b81SWarner Losh     return x,y,f()     -- returns x, y, and all results from f().
2852*a9490b81SWarner Losh     {f()}              -- creates a list with all results from f().
2853*a9490b81SWarner Losh     {...}              -- creates a list with all vararg arguments.
2854*a9490b81SWarner Losh     {f(), 5}           -- creates a list with the first result from f() and 5.
2855*a9490b81SWarner Losh</pre>
2856*a9490b81SWarner Losh
2857*a9490b81SWarner Losh
2858*a9490b81SWarner Losh
2859*a9490b81SWarner Losh
28608e3e3a7aSWarner Losh
28618e3e3a7aSWarner Losh
28628e3e3a7aSWarner Losh<h2>3.5 &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.
2870*a9490b81SWarner Losh(<em>Void statements</em> are labels and empty statements.)
28718e3e3a7aSWarner LoshConsider the following example:
28728e3e3a7aSWarner Losh
28738e3e3a7aSWarner Losh<pre>
28748e3e3a7aSWarner Losh     x = 10                -- global variable
28758e3e3a7aSWarner Losh     do                    -- new block
28768e3e3a7aSWarner Losh       local x = x         -- new 'x', with value 10
28778e3e3a7aSWarner Losh       print(x)            --&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,
3129*a9490b81SWarner Loshthe API guarantees that any pointer to a string in a stack index
31300495ed39SKyle Evansis valid while the string value at that index is not removed from the stack.
31310495ed39SKyle Evans(It can be moved to another index, though.)
31320495ed39SKyle EvansWhen the index is a pseudo-index (referring to an upvalue),
31330495ed39SKyle Evansthe pointer is valid while the corresponding call is active and
31340495ed39SKyle Evansthe corresponding upvalue is not modified.
31350495ed39SKyle Evans
31360495ed39SKyle Evans
31370495ed39SKyle Evans<p>
31380495ed39SKyle EvansSome functions in the debug interface
31390495ed39SKyle Evansalso return pointers to strings,
31400495ed39SKyle Evansnamely <a href="#lua_getlocal"><code>lua_getlocal</code></a>, <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>,
31410495ed39SKyle Evans<a href="#lua_setlocal"><code>lua_setlocal</code></a>, and <a href="#lua_setupvalue"><code>lua_setupvalue</code></a>.
31420495ed39SKyle EvansFor these functions, the pointer is guaranteed to
31430495ed39SKyle Evansbe valid while the caller function is active and
31440495ed39SKyle Evansthe given closure (if one was given) is in the stack.
31450495ed39SKyle Evans
31460495ed39SKyle Evans
31470495ed39SKyle Evans<p>
31480495ed39SKyle EvansExcept for these guarantees,
31490495ed39SKyle Evansthe garbage collector is free to invalidate
31500495ed39SKyle Evansany pointer to internal strings.
31510495ed39SKyle Evans
31520495ed39SKyle Evans
31530495ed39SKyle Evans
31540495ed39SKyle Evans
31550495ed39SKyle Evans
31560495ed39SKyle Evans
31570495ed39SKyle Evans
31580495ed39SKyle Evans<h2>4.2 &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>
3595*a9490b81SWarner 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>
3843*a9490b81SWarner Losh(This function was introduced in release&nbsp;5.4.3.)
3844*a9490b81SWarner Losh
3845*a9490b81SWarner Losh
3846*a9490b81SWarner Losh
3847*a9490b81SWarner Losh
3848*a9490b81SWarner Losh
3849*a9490b81SWarner Losh<hr><h3><a name="lua_closethread"><code>lua_closethread</code></a></h3><p>
3850*a9490b81SWarner Losh<span class="apii">[-0, +?, &ndash;]</span>
3851*a9490b81SWarner Losh<pre>int lua_closethread (lua_State *L, lua_State *from);</pre>
3852*a9490b81SWarner Losh
3853*a9490b81SWarner Losh<p>
3854*a9490b81SWarner LoshResets a thread, cleaning its call stack and closing all pending
3855*a9490b81SWarner Loshto-be-closed variables.
3856*a9490b81SWarner LoshReturns a status code:
3857*a9490b81SWarner Losh<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for no errors in the thread
3858*a9490b81SWarner Losh(either the original error that stopped the thread or
3859*a9490b81SWarner Losherrors in closing methods),
3860*a9490b81SWarner Loshor an error status otherwise.
3861*a9490b81SWarner LoshIn case of error,
3862*a9490b81SWarner Loshleaves the error object on the top of the stack.
3863*a9490b81SWarner Losh
3864*a9490b81SWarner Losh
3865*a9490b81SWarner Losh<p>
3866*a9490b81SWarner LoshThe parameter <code>from</code> represents the coroutine that is resetting <code>L</code>.
3867*a9490b81SWarner LoshIf there is no such coroutine,
3868*a9490b81SWarner Loshthis parameter can be <code>NULL</code>.
3869*a9490b81SWarner Losh
3870*a9490b81SWarner Losh
3871*a9490b81SWarner Losh<p>
3872*a9490b81SWarner Losh(This function was introduced in release&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,
4628*a9490b81SWarner 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).
5071*a9490b81SWarner LoshThe value at <code>index</code> must be a table.
50728e3e3a7aSWarner Losh
50738e3e3a7aSWarner Losh
50748e3e3a7aSWarner Losh
50758e3e3a7aSWarner Losh
50768e3e3a7aSWarner Losh
50778e3e3a7aSWarner Losh<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p>
50788e3e3a7aSWarner Losh<span class="apii">[-0, +1, &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).
5138*a9490b81SWarner LoshThe value at <code>index</code> must be a table.
51398e3e3a7aSWarner Losh
51408e3e3a7aSWarner Losh
51418e3e3a7aSWarner Losh
51428e3e3a7aSWarner Losh
51438e3e3a7aSWarner Losh
51448e3e3a7aSWarner Losh<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p>
51458e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span>
51468e3e3a7aSWarner Losh<pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre>
51478e3e3a7aSWarner Losh
51488e3e3a7aSWarner Losh<p>
51498e3e3a7aSWarner LoshDoes the equivalent of <code>t[i] = v</code>,
51508e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index
51510495ed39SKyle Evansand <code>v</code> is the value on the top of the stack.
51528e3e3a7aSWarner Losh
51538e3e3a7aSWarner Losh
51548e3e3a7aSWarner Losh<p>
51558e3e3a7aSWarner LoshThis function pops the value from the stack.
51568e3e3a7aSWarner LoshThe assignment is raw,
51570495ed39SKyle Evansthat is, it does not use the <code>__newindex</code> metavalue.
51588e3e3a7aSWarner Losh
51598e3e3a7aSWarner Losh
51608e3e3a7aSWarner Losh
51618e3e3a7aSWarner Losh
51628e3e3a7aSWarner Losh
51638e3e3a7aSWarner Losh<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p>
51648e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span>
51658e3e3a7aSWarner Losh<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre>
51668e3e3a7aSWarner Losh
51678e3e3a7aSWarner Losh<p>
51688e3e3a7aSWarner LoshDoes the equivalent of <code>t[p] = v</code>,
51698e3e3a7aSWarner Loshwhere <code>t</code> is the table at the given index,
51708e3e3a7aSWarner Losh<code>p</code> is encoded as a light userdata,
51710495ed39SKyle Evansand <code>v</code> is the value on the top of the stack.
51728e3e3a7aSWarner Losh
51738e3e3a7aSWarner Losh
51748e3e3a7aSWarner Losh<p>
51758e3e3a7aSWarner LoshThis function pops the value from the stack.
51768e3e3a7aSWarner LoshThe assignment is raw,
51770495ed39SKyle Evansthat is, it does not use the <code>__newindex</code> metavalue.
51788e3e3a7aSWarner Losh
51798e3e3a7aSWarner Losh
51808e3e3a7aSWarner Losh
51818e3e3a7aSWarner Losh
51828e3e3a7aSWarner Losh
51838e3e3a7aSWarner Losh<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3>
51848e3e3a7aSWarner Losh<pre>typedef const char * (*lua_Reader) (lua_State *L,
51858e3e3a7aSWarner Losh                                    void *data,
51868e3e3a7aSWarner Losh                                    size_t *size);</pre>
51878e3e3a7aSWarner Losh
51888e3e3a7aSWarner Losh<p>
51898e3e3a7aSWarner LoshThe reader function used by <a href="#lua_load"><code>lua_load</code></a>.
51900495ed39SKyle EvansEvery time <a href="#lua_load"><code>lua_load</code></a> needs another piece of the chunk,
51910495ed39SKyle Evansit calls the reader,
51928e3e3a7aSWarner Loshpassing along its <code>data</code> parameter.
51938e3e3a7aSWarner LoshThe reader must return a pointer to a block of memory
51948e3e3a7aSWarner Loshwith a new piece of the chunk
51958e3e3a7aSWarner Loshand set <code>size</code> to the block size.
51968e3e3a7aSWarner LoshThe block must exist until the reader function is called again.
51978e3e3a7aSWarner LoshTo signal the end of the chunk,
51988e3e3a7aSWarner Loshthe reader must return <code>NULL</code> or set <code>size</code> to zero.
51998e3e3a7aSWarner LoshThe reader function may return pieces of any size greater than zero.
52008e3e3a7aSWarner Losh
52018e3e3a7aSWarner Losh
52028e3e3a7aSWarner Losh
52038e3e3a7aSWarner Losh
52048e3e3a7aSWarner Losh
52058e3e3a7aSWarner Losh<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p>
52068e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span>
52078e3e3a7aSWarner Losh<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre>
52088e3e3a7aSWarner Losh
52098e3e3a7aSWarner Losh<p>
52108e3e3a7aSWarner LoshSets the C&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>
5254*a9490b81SWarner LoshThis function is deprecated;
5255*a9490b81SWarner Loshit is equivalent to <a href="#lua_closethread"><code>lua_closethread</code></a> with
5256*a9490b81SWarner Losh<code>from</code> being <code>NULL</code>.
52570495ed39SKyle Evans
52580495ed39SKyle Evans
52590495ed39SKyle Evans
52600495ed39SKyle Evans
52610495ed39SKyle Evans
52628e3e3a7aSWarner Losh<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p>
52638e3e3a7aSWarner Losh<span class="apii">[-?, +?, &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>
55740495ed39SKyle Evans<span class="apii">[-0, +0, <em>m</em>]</span>
55750495ed39SKyle Evans<pre>void lua_toclose (lua_State *L, int index);</pre>
55760495ed39SKyle Evans
55770495ed39SKyle Evans<p>
55780495ed39SKyle EvansMarks the given index in the stack as a
55798c784bb8SWarner Loshto-be-closed slot (see <a href="#3.3.8">&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>
55950495ed39SKyle EvansThis function should not be called for an index
55968c784bb8SWarner Loshthat is equal to or below an active to-be-closed slot.
55970495ed39SKyle Evans
55980495ed39SKyle Evans
55990495ed39SKyle Evans<p>
56000495ed39SKyle EvansNote that, both in case of errors and of a regular return,
56010495ed39SKyle Evansby the time the <code>__close</code> metamethod runs,
56020495ed39SKyle Evansthe C&nbsp;stack was already unwound,
56030495ed39SKyle Evansso that any automatic C&nbsp;variable declared in the calling function
56048c784bb8SWarner Losh(e.g., a buffer) will be out of scope.
56050495ed39SKyle Evans
56060495ed39SKyle Evans
56070495ed39SKyle Evans
56080495ed39SKyle Evans
56090495ed39SKyle Evans
56108e3e3a7aSWarner Losh<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p>
56118e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
56128e3e3a7aSWarner Losh<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre>
56138e3e3a7aSWarner Losh
56148e3e3a7aSWarner Losh<p>
56158e3e3a7aSWarner LoshEquivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
56168e3e3a7aSWarner Losh
56178e3e3a7aSWarner Losh
56188e3e3a7aSWarner Losh
56198e3e3a7aSWarner Losh
56208e3e3a7aSWarner Losh
56218e3e3a7aSWarner Losh<hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p>
56228e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
56238e3e3a7aSWarner Losh<pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre>
56248e3e3a7aSWarner Losh
56258e3e3a7aSWarner Losh<p>
56268e3e3a7aSWarner LoshConverts the Lua value at the given index
56278e3e3a7aSWarner Loshto the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>.
56288e3e3a7aSWarner LoshThe Lua value must be an integer,
56298e3e3a7aSWarner Loshor a number or string convertible to an integer (see <a href="#3.4.3">&sect;3.4.3</a>);
56308e3e3a7aSWarner Loshotherwise, <code>lua_tointegerx</code> returns&nbsp;0.
56318e3e3a7aSWarner Losh
56328e3e3a7aSWarner Losh
56338e3e3a7aSWarner Losh<p>
56348e3e3a7aSWarner LoshIf <code>isnum</code> is not <code>NULL</code>,
56358e3e3a7aSWarner Loshits referent is assigned a boolean value that
56368e3e3a7aSWarner Loshindicates whether the operation succeeded.
56378e3e3a7aSWarner Losh
56388e3e3a7aSWarner Losh
56398e3e3a7aSWarner Losh
56408e3e3a7aSWarner Losh
56418e3e3a7aSWarner Losh
56428e3e3a7aSWarner Losh<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p>
56438e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span>
56448e3e3a7aSWarner Losh<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre>
56458e3e3a7aSWarner Losh
56468e3e3a7aSWarner Losh<p>
56478e3e3a7aSWarner LoshConverts the Lua value at the given index to a C&nbsp;string.
56488e3e3a7aSWarner LoshIf <code>len</code> is not <code>NULL</code>,
56498e3e3a7aSWarner Loshit sets <code>*len</code> with the string length.
56508e3e3a7aSWarner LoshThe Lua value must be a string or a number;
56518e3e3a7aSWarner Loshotherwise, the function returns <code>NULL</code>.
56528e3e3a7aSWarner LoshIf the value is a number,
56538e3e3a7aSWarner Loshthen <code>lua_tolstring</code> also
56548e3e3a7aSWarner Losh<em>changes the actual value in the stack to a string</em>.
56558e3e3a7aSWarner Losh(This change confuses <a href="#lua_next"><code>lua_next</code></a>
56568e3e3a7aSWarner Loshwhen <code>lua_tolstring</code> is applied to keys during a table traversal.)
56578e3e3a7aSWarner Losh
56588e3e3a7aSWarner Losh
56598e3e3a7aSWarner Losh<p>
56608e3e3a7aSWarner Losh<code>lua_tolstring</code> returns a pointer
56610495ed39SKyle Evansto a string inside the Lua state (see <a href="#4.1.3">&sect;4.1.3</a>).
56628e3e3a7aSWarner LoshThis string always has a zero ('<code>\0</code>')
56638e3e3a7aSWarner Loshafter its last character (as in&nbsp;C),
56648e3e3a7aSWarner Loshbut can contain other zeros in its body.
56658e3e3a7aSWarner Losh
56668e3e3a7aSWarner Losh
56678e3e3a7aSWarner Losh
56688e3e3a7aSWarner Losh
56698e3e3a7aSWarner Losh
56708e3e3a7aSWarner Losh<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p>
56718e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
56728e3e3a7aSWarner Losh<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre>
56738e3e3a7aSWarner Losh
56748e3e3a7aSWarner Losh<p>
56758e3e3a7aSWarner LoshEquivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
56768e3e3a7aSWarner Losh
56778e3e3a7aSWarner Losh
56788e3e3a7aSWarner Losh
56798e3e3a7aSWarner Losh
56808e3e3a7aSWarner Losh
56818e3e3a7aSWarner Losh<hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p>
56828e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
56838e3e3a7aSWarner Losh<pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre>
56848e3e3a7aSWarner Losh
56858e3e3a7aSWarner Losh<p>
56868e3e3a7aSWarner LoshConverts the Lua value at the given index
56878e3e3a7aSWarner Loshto the C&nbsp;type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>).
56888e3e3a7aSWarner LoshThe Lua value must be a number or a string convertible to a number
56898e3e3a7aSWarner Losh(see <a href="#3.4.3">&sect;3.4.3</a>);
56908e3e3a7aSWarner Loshotherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns&nbsp;0.
56918e3e3a7aSWarner Losh
56928e3e3a7aSWarner Losh
56938e3e3a7aSWarner Losh<p>
56948e3e3a7aSWarner LoshIf <code>isnum</code> is not <code>NULL</code>,
56958e3e3a7aSWarner Loshits referent is assigned a boolean value that
56968e3e3a7aSWarner Loshindicates whether the operation succeeded.
56978e3e3a7aSWarner Losh
56988e3e3a7aSWarner Losh
56998e3e3a7aSWarner Losh
57008e3e3a7aSWarner Losh
57018e3e3a7aSWarner Losh
57028e3e3a7aSWarner Losh<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p>
57038e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
57048e3e3a7aSWarner Losh<pre>const void *lua_topointer (lua_State *L, int index);</pre>
57058e3e3a7aSWarner Losh
57068e3e3a7aSWarner Losh<p>
57078e3e3a7aSWarner LoshConverts the value at the given index to a generic
57088e3e3a7aSWarner LoshC&nbsp;pointer (<code>void*</code>).
57090495ed39SKyle EvansThe value can be a userdata, a table, a thread, a string, or a function;
57108e3e3a7aSWarner Loshotherwise, <code>lua_topointer</code> returns <code>NULL</code>.
57118e3e3a7aSWarner LoshDifferent objects will give different pointers.
57128e3e3a7aSWarner LoshThere is no way to convert the pointer back to its original value.
57138e3e3a7aSWarner Losh
57148e3e3a7aSWarner Losh
57158e3e3a7aSWarner Losh<p>
57168e3e3a7aSWarner LoshTypically this function is used only for hashing and debug information.
57178e3e3a7aSWarner Losh
57188e3e3a7aSWarner Losh
57198e3e3a7aSWarner Losh
57208e3e3a7aSWarner Losh
57218e3e3a7aSWarner Losh
57228e3e3a7aSWarner Losh<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p>
57238e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span>
57248e3e3a7aSWarner Losh<pre>const char *lua_tostring (lua_State *L, int index);</pre>
57258e3e3a7aSWarner Losh
57268e3e3a7aSWarner Losh<p>
57278e3e3a7aSWarner LoshEquivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>.
57288e3e3a7aSWarner Losh
57298e3e3a7aSWarner Losh
57308e3e3a7aSWarner Losh
57318e3e3a7aSWarner Losh
57328e3e3a7aSWarner Losh
57338e3e3a7aSWarner Losh<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p>
57348e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
57358e3e3a7aSWarner Losh<pre>lua_State *lua_tothread (lua_State *L, int index);</pre>
57368e3e3a7aSWarner Losh
57378e3e3a7aSWarner Losh<p>
57388e3e3a7aSWarner LoshConverts the value at the given index to a Lua thread
57398e3e3a7aSWarner Losh(represented as <code>lua_State*</code>).
57408e3e3a7aSWarner LoshThis value must be a thread;
57418e3e3a7aSWarner Loshotherwise, the function returns <code>NULL</code>.
57428e3e3a7aSWarner Losh
57438e3e3a7aSWarner Losh
57448e3e3a7aSWarner Losh
57458e3e3a7aSWarner Losh
57468e3e3a7aSWarner Losh
57478e3e3a7aSWarner Losh<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p>
57488e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
57498e3e3a7aSWarner Losh<pre>void *lua_touserdata (lua_State *L, int index);</pre>
57508e3e3a7aSWarner Losh
57518e3e3a7aSWarner Losh<p>
57528e3e3a7aSWarner LoshIf the value at the given index is a full userdata,
57530495ed39SKyle Evansreturns its memory-block address.
57548e3e3a7aSWarner LoshIf the value is a light userdata,
57550495ed39SKyle Evansreturns its value (a pointer).
57568e3e3a7aSWarner LoshOtherwise, returns <code>NULL</code>.
57578e3e3a7aSWarner Losh
57588e3e3a7aSWarner Losh
57598e3e3a7aSWarner Losh
57608e3e3a7aSWarner Losh
57618e3e3a7aSWarner Losh
57628e3e3a7aSWarner Losh<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p>
57638e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
57648e3e3a7aSWarner Losh<pre>int lua_type (lua_State *L, int index);</pre>
57658e3e3a7aSWarner Losh
57668e3e3a7aSWarner Losh<p>
57678e3e3a7aSWarner LoshReturns the type of the value in the given valid index,
57680495ed39SKyle Evansor <code>LUA_TNONE</code> for a non-valid but acceptable index.
57698e3e3a7aSWarner LoshThe types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants
57708e3e3a7aSWarner Loshdefined in <code>lua.h</code>:
57710495ed39SKyle Evans<a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a>,
57728e3e3a7aSWarner Losh<a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>,
57738e3e3a7aSWarner Losh<a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>,
57748e3e3a7aSWarner Losh<a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>,
57758e3e3a7aSWarner Losh<a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>,
57768e3e3a7aSWarner Losh<a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>,
57778e3e3a7aSWarner Losh<a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>,
57788e3e3a7aSWarner Losh<a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>,
57798e3e3a7aSWarner Loshand
57808e3e3a7aSWarner Losh<a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>.
57818e3e3a7aSWarner Losh
57828e3e3a7aSWarner Losh
57838e3e3a7aSWarner Losh
57848e3e3a7aSWarner Losh
57858e3e3a7aSWarner Losh
57868e3e3a7aSWarner Losh<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p>
57878e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
57888e3e3a7aSWarner Losh<pre>const char *lua_typename (lua_State *L, int tp);</pre>
57898e3e3a7aSWarner Losh
57908e3e3a7aSWarner Losh<p>
57918e3e3a7aSWarner LoshReturns the name of the type encoded by the value <code>tp</code>,
57928e3e3a7aSWarner Loshwhich must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>.
57938e3e3a7aSWarner Losh
57948e3e3a7aSWarner Losh
57958e3e3a7aSWarner Losh
57968e3e3a7aSWarner Losh
57978e3e3a7aSWarner Losh
57988e3e3a7aSWarner Losh<hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3>
57998e3e3a7aSWarner Losh<pre>typedef ... lua_Unsigned;</pre>
58008e3e3a7aSWarner Losh
58018e3e3a7aSWarner Losh<p>
58028e3e3a7aSWarner LoshThe unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>.
58038e3e3a7aSWarner Losh
58048e3e3a7aSWarner Losh
58058e3e3a7aSWarner Losh
58068e3e3a7aSWarner Losh
58078e3e3a7aSWarner Losh
58088e3e3a7aSWarner Losh<hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p>
58098e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
58108e3e3a7aSWarner Losh<pre>int lua_upvalueindex (int i);</pre>
58118e3e3a7aSWarner Losh
58128e3e3a7aSWarner Losh<p>
58138e3e3a7aSWarner LoshReturns the pseudo-index that represents the <code>i</code>-th upvalue of
58140495ed39SKyle Evansthe running function (see <a href="#4.2">&sect;4.2</a>).
58150495ed39SKyle Evans<code>i</code> must be in the range <em>[1,256]</em>.
58168e3e3a7aSWarner Losh
58178e3e3a7aSWarner Losh
58188e3e3a7aSWarner Losh
58198e3e3a7aSWarner Losh
58208e3e3a7aSWarner Losh
58218e3e3a7aSWarner Losh<hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p>
58228e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
58230495ed39SKyle Evans<pre>lua_Number lua_version (lua_State *L);</pre>
58248e3e3a7aSWarner Losh
58258e3e3a7aSWarner Losh<p>
58260495ed39SKyle EvansReturns the version number of this core.
58270495ed39SKyle Evans
58280495ed39SKyle Evans
58290495ed39SKyle Evans
58300495ed39SKyle Evans
58310495ed39SKyle Evans
58320495ed39SKyle Evans<hr><h3><a name="lua_WarnFunction"><code>lua_WarnFunction</code></a></h3>
58330495ed39SKyle Evans<pre>typedef void (*lua_WarnFunction) (void *ud, const char *msg, int tocont);</pre>
58340495ed39SKyle Evans
58350495ed39SKyle Evans<p>
58360495ed39SKyle EvansThe type of warning functions, called by Lua to emit warnings.
58370495ed39SKyle EvansThe first parameter is an opaque pointer
58380495ed39SKyle Evansset by <a href="#lua_setwarnf"><code>lua_setwarnf</code></a>.
58390495ed39SKyle EvansThe second parameter is the warning message.
58400495ed39SKyle EvansThe third parameter is a boolean that
58410495ed39SKyle Evansindicates whether the message is
58420495ed39SKyle Evansto be continued by the message in the next call.
58430495ed39SKyle Evans
58440495ed39SKyle Evans
58450495ed39SKyle Evans<p>
58460495ed39SKyle EvansSee <a href="#pdf-warn"><code>warn</code></a> for more details about warnings.
58470495ed39SKyle Evans
58480495ed39SKyle Evans
58490495ed39SKyle Evans
58500495ed39SKyle Evans
58510495ed39SKyle Evans
58520495ed39SKyle Evans<hr><h3><a name="lua_warning"><code>lua_warning</code></a></h3><p>
58530495ed39SKyle Evans<span class="apii">[-0, +0, &ndash;]</span>
58540495ed39SKyle Evans<pre>void lua_warning (lua_State *L, const char *msg, int tocont);</pre>
58550495ed39SKyle Evans
58560495ed39SKyle Evans<p>
58570495ed39SKyle EvansEmits a warning with the given message.
58580495ed39SKyle EvansA message in a call with <code>tocont</code> true should be
58590495ed39SKyle Evanscontinued in another call to this function.
58600495ed39SKyle Evans
58610495ed39SKyle Evans
58620495ed39SKyle Evans<p>
58630495ed39SKyle EvansSee <a href="#pdf-warn"><code>warn</code></a> for more details about warnings.
58648e3e3a7aSWarner Losh
58658e3e3a7aSWarner Losh
58668e3e3a7aSWarner Losh
58678e3e3a7aSWarner Losh
58688e3e3a7aSWarner Losh
58698e3e3a7aSWarner Losh<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3>
58708e3e3a7aSWarner Losh<pre>typedef int (*lua_Writer) (lua_State *L,
58718e3e3a7aSWarner Losh                           const void* p,
58728e3e3a7aSWarner Losh                           size_t sz,
58738e3e3a7aSWarner Losh                           void* ud);</pre>
58748e3e3a7aSWarner Losh
58758e3e3a7aSWarner Losh<p>
58768e3e3a7aSWarner LoshThe type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>.
58770495ed39SKyle EvansEvery time <a href="#lua_dump"><code>lua_dump</code></a> produces another piece of chunk,
58780495ed39SKyle Evansit calls the writer,
58798e3e3a7aSWarner Loshpassing along the buffer to be written (<code>p</code>),
58808e3e3a7aSWarner Loshits size (<code>sz</code>),
58810495ed39SKyle Evansand the <code>ud</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>.
58828e3e3a7aSWarner Losh
58838e3e3a7aSWarner Losh
58848e3e3a7aSWarner Losh<p>
58858e3e3a7aSWarner LoshThe writer returns an error code:
58868e3e3a7aSWarner Losh0&nbsp;means no errors;
58878e3e3a7aSWarner Loshany other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from
58888e3e3a7aSWarner Loshcalling the writer again.
58898e3e3a7aSWarner Losh
58908e3e3a7aSWarner Losh
58918e3e3a7aSWarner Losh
58928e3e3a7aSWarner Losh
58938e3e3a7aSWarner Losh
58948e3e3a7aSWarner Losh<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p>
58958e3e3a7aSWarner Losh<span class="apii">[-?, +?, &ndash;]</span>
58968e3e3a7aSWarner Losh<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre>
58978e3e3a7aSWarner Losh
58988e3e3a7aSWarner Losh<p>
58998e3e3a7aSWarner LoshExchange values between different threads of the same state.
59008e3e3a7aSWarner Losh
59018e3e3a7aSWarner Losh
59028e3e3a7aSWarner Losh<p>
59038e3e3a7aSWarner LoshThis function pops <code>n</code> values from the stack <code>from</code>,
59048e3e3a7aSWarner Loshand pushes them onto the stack <code>to</code>.
59058e3e3a7aSWarner Losh
59068e3e3a7aSWarner Losh
59078e3e3a7aSWarner Losh
59088e3e3a7aSWarner Losh
59098e3e3a7aSWarner Losh
59108e3e3a7aSWarner Losh<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p>
59110495ed39SKyle Evans<span class="apii">[-?, +?, <em>v</em>]</span>
59128e3e3a7aSWarner Losh<pre>int lua_yield (lua_State *L, int nresults);</pre>
59138e3e3a7aSWarner Losh
59148e3e3a7aSWarner Losh<p>
59158e3e3a7aSWarner LoshThis function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
59160495ed39SKyle Evansbut it has no continuation (see <a href="#4.5">&sect;4.5</a>).
59178e3e3a7aSWarner LoshTherefore, when the thread resumes,
59188e3e3a7aSWarner Loshit continues the function that called
59198e3e3a7aSWarner Loshthe function calling <code>lua_yield</code>.
59200495ed39SKyle EvansTo avoid surprises,
59210495ed39SKyle Evansthis function should be called only in a tail call.
59228e3e3a7aSWarner Losh
59238e3e3a7aSWarner Losh
59248e3e3a7aSWarner Losh
59258e3e3a7aSWarner Losh
59268e3e3a7aSWarner Losh
59278e3e3a7aSWarner Losh<hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p>
59280495ed39SKyle Evans<span class="apii">[-?, +?, <em>v</em>]</span>
59298e3e3a7aSWarner Losh<pre>int lua_yieldk (lua_State *L,
59308e3e3a7aSWarner Losh                int nresults,
59318e3e3a7aSWarner Losh                lua_KContext ctx,
59328e3e3a7aSWarner Losh                lua_KFunction k);</pre>
59338e3e3a7aSWarner Losh
59348e3e3a7aSWarner Losh<p>
59358e3e3a7aSWarner LoshYields a coroutine (thread).
59368e3e3a7aSWarner Losh
59378e3e3a7aSWarner Losh
59388e3e3a7aSWarner Losh<p>
59398e3e3a7aSWarner LoshWhen a C&nbsp;function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
59408e3e3a7aSWarner Loshthe running coroutine suspends its execution,
59418e3e3a7aSWarner Loshand the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns.
59428e3e3a7aSWarner LoshThe parameter <code>nresults</code> is the number of values from the stack
59438e3e3a7aSWarner Loshthat will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>.
59448e3e3a7aSWarner Losh
59458e3e3a7aSWarner Losh
59468e3e3a7aSWarner Losh<p>
59478e3e3a7aSWarner LoshWhen the coroutine is resumed again,
59488e3e3a7aSWarner LoshLua calls the given continuation function <code>k</code> to continue
59490495ed39SKyle Evansthe execution of the C&nbsp;function that yielded (see <a href="#4.5">&sect;4.5</a>).
59508e3e3a7aSWarner LoshThis continuation function receives the same stack
59518e3e3a7aSWarner Loshfrom the previous function,
59528e3e3a7aSWarner Loshwith the <code>n</code> results removed and
59538e3e3a7aSWarner Loshreplaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>.
59548e3e3a7aSWarner LoshMoreover,
59558e3e3a7aSWarner Loshthe continuation function receives the value <code>ctx</code>
59568e3e3a7aSWarner Loshthat was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>.
59578e3e3a7aSWarner Losh
59588e3e3a7aSWarner Losh
59598e3e3a7aSWarner Losh<p>
59608e3e3a7aSWarner LoshUsually, this function does not return;
59618e3e3a7aSWarner Loshwhen the coroutine eventually resumes,
59628e3e3a7aSWarner Loshit continues executing the continuation function.
59638e3e3a7aSWarner LoshHowever, there is one special case,
59648e3e3a7aSWarner Loshwhich is when this function is called
59650495ed39SKyle Evansfrom inside a line or a count hook (see <a href="#4.7">&sect;4.7</a>).
59668e3e3a7aSWarner LoshIn that case, <code>lua_yieldk</code> should be called with no continuation
59678e3e3a7aSWarner Losh(probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results,
59688e3e3a7aSWarner Loshand the hook should return immediately after the call.
59698e3e3a7aSWarner LoshLua will yield and,
59708e3e3a7aSWarner Loshwhen the coroutine resumes again,
59718e3e3a7aSWarner Loshit will continue the normal execution
59728e3e3a7aSWarner Loshof the (Lua) function that triggered the hook.
59738e3e3a7aSWarner Losh
59748e3e3a7aSWarner Losh
59758e3e3a7aSWarner Losh<p>
59768e3e3a7aSWarner LoshThis function can raise an error if it is called from a thread
59770495ed39SKyle Evanswith a pending C call with no continuation function
59780495ed39SKyle Evans(what is called a <em>C-call boundary</em>),
59798e3e3a7aSWarner Loshor it is called from a thread that is not running inside a resume
59800495ed39SKyle Evans(typically the main thread).
59818e3e3a7aSWarner Losh
59828e3e3a7aSWarner Losh
59838e3e3a7aSWarner Losh
59848e3e3a7aSWarner Losh
59858e3e3a7aSWarner Losh
59868e3e3a7aSWarner Losh
59878e3e3a7aSWarner Losh
59880495ed39SKyle Evans<h2>4.7 &ndash; <a name="4.7">The Debug Interface</a></h2>
59898e3e3a7aSWarner Losh
59908e3e3a7aSWarner Losh<p>
59918e3e3a7aSWarner LoshLua has no built-in debugging facilities.
59928e3e3a7aSWarner LoshInstead, it offers a special interface
59938e3e3a7aSWarner Loshby means of functions and <em>hooks</em>.
59948e3e3a7aSWarner LoshThis interface allows the construction of different
59958e3e3a7aSWarner Loshkinds of debuggers, profilers, and other tools
59968e3e3a7aSWarner Loshthat need "inside information" from the interpreter.
59978e3e3a7aSWarner Losh
59988e3e3a7aSWarner Losh
59998e3e3a7aSWarner Losh
60008e3e3a7aSWarner Losh<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3>
60018e3e3a7aSWarner Losh<pre>typedef struct lua_Debug {
60028e3e3a7aSWarner Losh  int event;
60038e3e3a7aSWarner Losh  const char *name;           /* (n) */
60048e3e3a7aSWarner Losh  const char *namewhat;       /* (n) */
60058e3e3a7aSWarner Losh  const char *what;           /* (S) */
60068e3e3a7aSWarner Losh  const char *source;         /* (S) */
60070495ed39SKyle Evans  size_t srclen;              /* (S) */
60088e3e3a7aSWarner Losh  int currentline;            /* (l) */
60098e3e3a7aSWarner Losh  int linedefined;            /* (S) */
60108e3e3a7aSWarner Losh  int lastlinedefined;        /* (S) */
60118e3e3a7aSWarner Losh  unsigned char nups;         /* (u) number of upvalues */
60128e3e3a7aSWarner Losh  unsigned char nparams;      /* (u) number of parameters */
60138e3e3a7aSWarner Losh  char isvararg;              /* (u) */
60148e3e3a7aSWarner Losh  char istailcall;            /* (t) */
60150495ed39SKyle Evans  unsigned short ftransfer;   /* (r) index of first value transferred */
60160495ed39SKyle Evans  unsigned short ntransfer;   /* (r) number of transferred values */
60178e3e3a7aSWarner Losh  char short_src[LUA_IDSIZE]; /* (S) */
60188e3e3a7aSWarner Losh  /* private part */
60198e3e3a7aSWarner Losh  <em>other fields</em>
60208e3e3a7aSWarner Losh} lua_Debug;</pre>
60218e3e3a7aSWarner Losh
60228e3e3a7aSWarner Losh<p>
60238e3e3a7aSWarner LoshA structure used to carry different pieces of
60248e3e3a7aSWarner Loshinformation about a function or an activation record.
60258e3e3a7aSWarner Losh<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part
60268e3e3a7aSWarner Loshof this structure, for later use.
60278e3e3a7aSWarner LoshTo fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information,
60288c784bb8SWarner Loshyou must call <a href="#lua_getinfo"><code>lua_getinfo</code></a> with an appropriate parameter.
60298c784bb8SWarner Losh(Specifically, to get a field,
60308c784bb8SWarner Loshyou must add the letter between parentheses in the field's comment
60318c784bb8SWarner Loshto the parameter <code>what</code> of <a href="#lua_getinfo"><code>lua_getinfo</code></a>.)
60328e3e3a7aSWarner Losh
60338e3e3a7aSWarner Losh
60348e3e3a7aSWarner Losh<p>
60358e3e3a7aSWarner LoshThe fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning:
60368e3e3a7aSWarner Losh
60378e3e3a7aSWarner Losh<ul>
60388e3e3a7aSWarner Losh
60398e3e3a7aSWarner Losh<li><b><code>source</code>: </b>
60400495ed39SKyle Evansthe source of the chunk that created the function.
60418e3e3a7aSWarner LoshIf <code>source</code> starts with a '<code>@</code>',
60428e3e3a7aSWarner Loshit means that the function was defined in a file where
60438e3e3a7aSWarner Loshthe file name follows the '<code>@</code>'.
60448e3e3a7aSWarner LoshIf <code>source</code> starts with a '<code>=</code>',
60450495ed39SKyle Evansthe remainder of its contents describes the source in a user-dependent manner.
60468e3e3a7aSWarner LoshOtherwise,
60478e3e3a7aSWarner Loshthe function was defined in a string where
60488e3e3a7aSWarner Losh<code>source</code> is that string.
60498e3e3a7aSWarner Losh</li>
60508e3e3a7aSWarner Losh
60510495ed39SKyle Evans<li><b><code>srclen</code>: </b>
60520495ed39SKyle EvansThe length of the string <code>source</code>.
60530495ed39SKyle Evans</li>
60540495ed39SKyle Evans
60558e3e3a7aSWarner Losh<li><b><code>short_src</code>: </b>
60568e3e3a7aSWarner Losha "printable" version of <code>source</code>, to be used in error messages.
60578e3e3a7aSWarner Losh</li>
60588e3e3a7aSWarner Losh
60598e3e3a7aSWarner Losh<li><b><code>linedefined</code>: </b>
60608e3e3a7aSWarner Loshthe line number where the definition of the function starts.
60618e3e3a7aSWarner Losh</li>
60628e3e3a7aSWarner Losh
60638e3e3a7aSWarner Losh<li><b><code>lastlinedefined</code>: </b>
60648e3e3a7aSWarner Loshthe line number where the definition of the function ends.
60658e3e3a7aSWarner Losh</li>
60668e3e3a7aSWarner Losh
60678e3e3a7aSWarner Losh<li><b><code>what</code>: </b>
60688e3e3a7aSWarner Loshthe string <code>"Lua"</code> if the function is a Lua function,
60698e3e3a7aSWarner Losh<code>"C"</code> if it is a C&nbsp;function,
60708e3e3a7aSWarner Losh<code>"main"</code> if it is the main part of a chunk.
60718e3e3a7aSWarner Losh</li>
60728e3e3a7aSWarner Losh
60738e3e3a7aSWarner Losh<li><b><code>currentline</code>: </b>
60748e3e3a7aSWarner Loshthe current line where the given function is executing.
60758e3e3a7aSWarner LoshWhen no line information is available,
60768e3e3a7aSWarner Losh<code>currentline</code> is set to -1.
60778e3e3a7aSWarner Losh</li>
60788e3e3a7aSWarner Losh
60798e3e3a7aSWarner Losh<li><b><code>name</code>: </b>
60808e3e3a7aSWarner Losha reasonable name for the given function.
60818e3e3a7aSWarner LoshBecause functions in Lua are first-class values,
60828e3e3a7aSWarner Loshthey do not have a fixed name:
60838e3e3a7aSWarner Loshsome functions can be the value of multiple global variables,
60848e3e3a7aSWarner Loshwhile others can be stored only in a table field.
60858e3e3a7aSWarner LoshThe <code>lua_getinfo</code> function checks how the function was
60868e3e3a7aSWarner Loshcalled to find a suitable name.
60878e3e3a7aSWarner LoshIf it cannot find a name,
60888e3e3a7aSWarner Loshthen <code>name</code> is set to <code>NULL</code>.
60898e3e3a7aSWarner Losh</li>
60908e3e3a7aSWarner Losh
60918e3e3a7aSWarner Losh<li><b><code>namewhat</code>: </b>
60928e3e3a7aSWarner Loshexplains the <code>name</code> field.
60938e3e3a7aSWarner LoshThe value of <code>namewhat</code> can be
60948e3e3a7aSWarner Losh<code>"global"</code>, <code>"local"</code>, <code>"method"</code>,
60958e3e3a7aSWarner Losh<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string),
60968e3e3a7aSWarner Loshaccording to how the function was called.
60978e3e3a7aSWarner Losh(Lua uses the empty string when no other option seems to apply.)
60988e3e3a7aSWarner Losh</li>
60998e3e3a7aSWarner Losh
61008e3e3a7aSWarner Losh<li><b><code>istailcall</code>: </b>
61018e3e3a7aSWarner Loshtrue if this function invocation was called by a tail call.
61028e3e3a7aSWarner LoshIn this case, the caller of this level is not in the stack.
61038e3e3a7aSWarner Losh</li>
61048e3e3a7aSWarner Losh
61058e3e3a7aSWarner Losh<li><b><code>nups</code>: </b>
61068e3e3a7aSWarner Loshthe number of upvalues of the function.
61078e3e3a7aSWarner Losh</li>
61088e3e3a7aSWarner Losh
61098e3e3a7aSWarner Losh<li><b><code>nparams</code>: </b>
61100495ed39SKyle Evansthe number of parameters of the function
61118e3e3a7aSWarner Losh(always 0&nbsp;for C&nbsp;functions).
61128e3e3a7aSWarner Losh</li>
61138e3e3a7aSWarner Losh
61148e3e3a7aSWarner Losh<li><b><code>isvararg</code>: </b>
6115*a9490b81SWarner Loshtrue if the function is a variadic function
61168e3e3a7aSWarner Losh(always true for C&nbsp;functions).
61178e3e3a7aSWarner Losh</li>
61188e3e3a7aSWarner Losh
61190495ed39SKyle Evans<li><b><code>ftransfer</code>: </b>
61200495ed39SKyle Evansthe index in the stack of the first value being "transferred",
61210495ed39SKyle Evansthat is, parameters in a call or return values in a return.
61220495ed39SKyle Evans(The other values are in consecutive indices.)
61230495ed39SKyle EvansUsing this index, you can access and modify these values
61240495ed39SKyle Evansthrough <a href="#lua_getlocal"><code>lua_getlocal</code></a> and <a href="#lua_setlocal"><code>lua_setlocal</code></a>.
61250495ed39SKyle EvansThis field is only meaningful during a
61260495ed39SKyle Evanscall hook, denoting the first parameter,
61270495ed39SKyle Evansor a return hook, denoting the first value being returned.
61280495ed39SKyle Evans(For call hooks, this value is always 1.)
61290495ed39SKyle Evans</li>
61300495ed39SKyle Evans
61310495ed39SKyle Evans<li><b><code>ntransfer</code>: </b>
61320495ed39SKyle EvansThe number of values being transferred (see previous item).
61330495ed39SKyle Evans(For calls of Lua functions,
61340495ed39SKyle Evansthis value is always equal to <code>nparams</code>.)
61350495ed39SKyle Evans</li>
61360495ed39SKyle Evans
61378e3e3a7aSWarner Losh</ul>
61388e3e3a7aSWarner Losh
61398e3e3a7aSWarner Losh
61408e3e3a7aSWarner Losh
61418e3e3a7aSWarner Losh
61428e3e3a7aSWarner Losh<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p>
61438e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
61448e3e3a7aSWarner Losh<pre>lua_Hook lua_gethook (lua_State *L);</pre>
61458e3e3a7aSWarner Losh
61468e3e3a7aSWarner Losh<p>
61478e3e3a7aSWarner LoshReturns the current hook function.
61488e3e3a7aSWarner Losh
61498e3e3a7aSWarner Losh
61508e3e3a7aSWarner Losh
61518e3e3a7aSWarner Losh
61528e3e3a7aSWarner Losh
61538e3e3a7aSWarner Losh<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p>
61548e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
61558e3e3a7aSWarner Losh<pre>int lua_gethookcount (lua_State *L);</pre>
61568e3e3a7aSWarner Losh
61578e3e3a7aSWarner Losh<p>
61588e3e3a7aSWarner LoshReturns the current hook count.
61598e3e3a7aSWarner Losh
61608e3e3a7aSWarner Losh
61618e3e3a7aSWarner Losh
61628e3e3a7aSWarner Losh
61638e3e3a7aSWarner Losh
61648e3e3a7aSWarner Losh<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p>
61658e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
61668e3e3a7aSWarner Losh<pre>int lua_gethookmask (lua_State *L);</pre>
61678e3e3a7aSWarner Losh
61688e3e3a7aSWarner Losh<p>
61698e3e3a7aSWarner LoshReturns the current hook mask.
61708e3e3a7aSWarner Losh
61718e3e3a7aSWarner Losh
61728e3e3a7aSWarner Losh
61738e3e3a7aSWarner Losh
61748e3e3a7aSWarner Losh
61758e3e3a7aSWarner Losh<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p>
61760495ed39SKyle Evans<span class="apii">[-(0|1), +(0|1|2), <em>m</em>]</span>
61778e3e3a7aSWarner Losh<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre>
61788e3e3a7aSWarner Losh
61798e3e3a7aSWarner Losh<p>
61808e3e3a7aSWarner LoshGets information about a specific function or function invocation.
61818e3e3a7aSWarner Losh
61828e3e3a7aSWarner Losh
61838e3e3a7aSWarner Losh<p>
61848e3e3a7aSWarner LoshTo get information about a function invocation,
61858e3e3a7aSWarner Loshthe parameter <code>ar</code> must be a valid activation record that was
61868e3e3a7aSWarner Loshfilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
61878e3e3a7aSWarner Loshgiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
61888e3e3a7aSWarner Losh
61898e3e3a7aSWarner Losh
61908e3e3a7aSWarner Losh<p>
6191e112e9d2SKyle EvansTo get information about a function, you push it onto the stack
61928e3e3a7aSWarner Loshand start the <code>what</code> string with the character '<code>&gt;</code>'.
61938e3e3a7aSWarner Losh(In that case,
61948e3e3a7aSWarner Losh<code>lua_getinfo</code> pops the function from the top of the stack.)
61958e3e3a7aSWarner LoshFor instance, to know in which line a function <code>f</code> was defined,
61968e3e3a7aSWarner Loshyou can write the following code:
61978e3e3a7aSWarner Losh
61988e3e3a7aSWarner Losh<pre>
61998e3e3a7aSWarner Losh     lua_Debug ar;
62008e3e3a7aSWarner Losh     lua_getglobal(L, "f");  /* get global 'f' */
62018e3e3a7aSWarner Losh     lua_getinfo(L, "&gt;S", &amp;ar);
62028e3e3a7aSWarner Losh     printf("%d\n", ar.linedefined);
62038e3e3a7aSWarner Losh</pre>
62048e3e3a7aSWarner Losh
62058e3e3a7aSWarner Losh<p>
62068e3e3a7aSWarner LoshEach character in the string <code>what</code>
62078e3e3a7aSWarner Loshselects some fields of the structure <code>ar</code> to be filled or
62088c784bb8SWarner Losha value to be pushed on the stack.
62098c784bb8SWarner Losh(These characters are also documented in the declaration of
62108c784bb8SWarner Loshthe structure <a href="#lua_Debug"><code>lua_Debug</code></a>,
62118c784bb8SWarner Loshbetween parentheses in the comments following each field.)
62128e3e3a7aSWarner Losh
62138e3e3a7aSWarner Losh<ul>
62148e3e3a7aSWarner Losh
62158c784bb8SWarner Losh<li><b>'<code>f</code>': </b>
62168c784bb8SWarner Loshpushes onto the stack the function that is
62178c784bb8SWarner Loshrunning at the given level;
62188c784bb8SWarner Losh</li>
62198c784bb8SWarner Losh
62208c784bb8SWarner Losh<li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>;
62218c784bb8SWarner Losh</li>
62228c784bb8SWarner Losh
62238c784bb8SWarner Losh<li><b>'<code>n</code>': </b> fills in the fields <code>name</code> and <code>namewhat</code>;
62248c784bb8SWarner Losh</li>
62258c784bb8SWarner Losh
62268c784bb8SWarner Losh<li><b>'<code>r</code>': </b> fills in the fields <code>ftransfer</code> and <code>ntransfer</code>;
62278e3e3a7aSWarner Losh</li>
62288e3e3a7aSWarner Losh
62298e3e3a7aSWarner Losh<li><b>'<code>S</code>': </b>
62308e3e3a7aSWarner Loshfills in the fields <code>source</code>, <code>short_src</code>,
62318e3e3a7aSWarner Losh<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>;
62328e3e3a7aSWarner Losh</li>
62338e3e3a7aSWarner Losh
62348e3e3a7aSWarner Losh<li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>;
62358e3e3a7aSWarner Losh</li>
62368e3e3a7aSWarner Losh
62378e3e3a7aSWarner Losh<li><b>'<code>u</code>': </b> fills in the fields
62388e3e3a7aSWarner Losh<code>nups</code>, <code>nparams</code>, and <code>isvararg</code>;
62398e3e3a7aSWarner Losh</li>
62408e3e3a7aSWarner Losh
62418e3e3a7aSWarner Losh<li><b>'<code>L</code>': </b>
62428c784bb8SWarner Loshpushes onto the stack a table whose indices are
62438c784bb8SWarner Loshthe lines on the function with some associated code,
62448c784bb8SWarner Loshthat is, the lines where you can put a break point.
62458c784bb8SWarner Losh(Lines with no code include empty lines and comments.)
62468e3e3a7aSWarner LoshIf this option is given together with option '<code>f</code>',
62478e3e3a7aSWarner Loshits table is pushed after the function.
62480495ed39SKyle EvansThis is the only option that can raise a memory error.
62498e3e3a7aSWarner Losh</li>
62508e3e3a7aSWarner Losh
62518e3e3a7aSWarner Losh</ul>
62528e3e3a7aSWarner Losh
62538e3e3a7aSWarner Losh<p>
62540495ed39SKyle EvansThis function returns 0 to signal an invalid option in <code>what</code>;
62550495ed39SKyle Evanseven then the valid options are handled correctly.
62568e3e3a7aSWarner Losh
62578e3e3a7aSWarner Losh
62588e3e3a7aSWarner Losh
62598e3e3a7aSWarner Losh
62608e3e3a7aSWarner Losh
62618e3e3a7aSWarner Losh<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p>
62628e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), &ndash;]</span>
62638e3e3a7aSWarner Losh<pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre>
62648e3e3a7aSWarner Losh
62658e3e3a7aSWarner Losh<p>
62660495ed39SKyle EvansGets information about a local variable or a temporary value
62670495ed39SKyle Evansof a given activation record or a given function.
62688e3e3a7aSWarner Losh
62698e3e3a7aSWarner Losh
62708e3e3a7aSWarner Losh<p>
62718e3e3a7aSWarner LoshIn the first case,
62728e3e3a7aSWarner Loshthe parameter <code>ar</code> must be a valid activation record that was
62738e3e3a7aSWarner Loshfilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
62748e3e3a7aSWarner Loshgiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
62758e3e3a7aSWarner LoshThe index <code>n</code> selects which local variable to inspect;
62768e3e3a7aSWarner Loshsee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices
62778e3e3a7aSWarner Loshand names.
62788e3e3a7aSWarner Losh
62798e3e3a7aSWarner Losh
62808e3e3a7aSWarner Losh<p>
62818e3e3a7aSWarner Losh<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack
62828e3e3a7aSWarner Loshand returns its name.
62838e3e3a7aSWarner Losh
62848e3e3a7aSWarner Losh
62858e3e3a7aSWarner Losh<p>
62868e3e3a7aSWarner LoshIn the second case, <code>ar</code> must be <code>NULL</code> and the function
62870495ed39SKyle Evansto be inspected must be on the top of the stack.
62888e3e3a7aSWarner LoshIn this case, only parameters of Lua functions are visible
62898e3e3a7aSWarner Losh(as there is no information about what variables are active)
62908e3e3a7aSWarner Loshand no values are pushed onto the stack.
62918e3e3a7aSWarner Losh
62928e3e3a7aSWarner Losh
62938e3e3a7aSWarner Losh<p>
62948e3e3a7aSWarner LoshReturns <code>NULL</code> (and pushes nothing)
62958e3e3a7aSWarner Loshwhen the index is greater than
62968e3e3a7aSWarner Loshthe number of active local variables.
62978e3e3a7aSWarner Losh
62988e3e3a7aSWarner Losh
62998e3e3a7aSWarner Losh
63008e3e3a7aSWarner Losh
63018e3e3a7aSWarner Losh
63028e3e3a7aSWarner Losh<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p>
63038e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
63048e3e3a7aSWarner Losh<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre>
63058e3e3a7aSWarner Losh
63068e3e3a7aSWarner Losh<p>
63078e3e3a7aSWarner LoshGets information about the interpreter runtime stack.
63088e3e3a7aSWarner Losh
63098e3e3a7aSWarner Losh
63108e3e3a7aSWarner Losh<p>
63118e3e3a7aSWarner LoshThis function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with
63128e3e3a7aSWarner Loshan identification of the <em>activation record</em>
63138e3e3a7aSWarner Loshof the function executing at a given level.
63148e3e3a7aSWarner LoshLevel&nbsp;0 is the current running function,
63158e3e3a7aSWarner Loshwhereas level <em>n+1</em> is the function that has called level <em>n</em>
63160495ed39SKyle Evans(except for tail calls, which do not count in the stack).
63170495ed39SKyle EvansWhen called with a level greater than the stack depth,
63180495ed39SKyle Evans<a href="#lua_getstack"><code>lua_getstack</code></a> returns 0;
63190495ed39SKyle Evansotherwise it returns 1.
63208e3e3a7aSWarner Losh
63218e3e3a7aSWarner Losh
63228e3e3a7aSWarner Losh
63238e3e3a7aSWarner Losh
63248e3e3a7aSWarner Losh
63258e3e3a7aSWarner Losh<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p>
63268e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), &ndash;]</span>
63278e3e3a7aSWarner Losh<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre>
63288e3e3a7aSWarner Losh
63298e3e3a7aSWarner Losh<p>
63308e3e3a7aSWarner LoshGets information about the <code>n</code>-th upvalue
63318e3e3a7aSWarner Loshof the closure at index <code>funcindex</code>.
63328e3e3a7aSWarner LoshIt pushes the upvalue's value onto the stack
63338e3e3a7aSWarner Loshand returns its name.
63348e3e3a7aSWarner LoshReturns <code>NULL</code> (and pushes nothing)
63358e3e3a7aSWarner Loshwhen the index <code>n</code> is greater than the number of upvalues.
63368e3e3a7aSWarner Losh
63378e3e3a7aSWarner Losh
63388e3e3a7aSWarner Losh<p>
63390495ed39SKyle EvansSee <a href="#pdf-debug.getupvalue"><code>debug.getupvalue</code></a> for more information about upvalues.
63408e3e3a7aSWarner Losh
63418e3e3a7aSWarner Losh
63428e3e3a7aSWarner Losh
63438e3e3a7aSWarner Losh
63448e3e3a7aSWarner Losh
63458e3e3a7aSWarner Losh<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3>
63468e3e3a7aSWarner Losh<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre>
63478e3e3a7aSWarner Losh
63488e3e3a7aSWarner Losh<p>
63498e3e3a7aSWarner LoshType for debugging hook functions.
63508e3e3a7aSWarner Losh
63518e3e3a7aSWarner Losh
63528e3e3a7aSWarner Losh<p>
63538e3e3a7aSWarner LoshWhenever a hook is called, its <code>ar</code> argument has its field
63548e3e3a7aSWarner Losh<code>event</code> set to the specific event that triggered the hook.
63558e3e3a7aSWarner LoshLua identifies these events with the following constants:
63568e3e3a7aSWarner Losh<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>,
63578e3e3a7aSWarner Losh<a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>,
63588e3e3a7aSWarner Loshand <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>.
63598e3e3a7aSWarner LoshMoreover, for line events, the field <code>currentline</code> is also set.
63608e3e3a7aSWarner LoshTo get the value of any other field in <code>ar</code>,
63618e3e3a7aSWarner Loshthe hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
63628e3e3a7aSWarner Losh
63638e3e3a7aSWarner Losh
63648e3e3a7aSWarner Losh<p>
63658e3e3a7aSWarner LoshFor call events, <code>event</code> can be <code>LUA_HOOKCALL</code>,
63668e3e3a7aSWarner Loshthe normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call;
63678e3e3a7aSWarner Loshin this case, there will be no corresponding return event.
63688e3e3a7aSWarner Losh
63698e3e3a7aSWarner Losh
63708e3e3a7aSWarner Losh<p>
63718e3e3a7aSWarner LoshWhile Lua is running a hook, it disables other calls to hooks.
63728e3e3a7aSWarner LoshTherefore, if a hook calls back Lua to execute a function or a chunk,
63738e3e3a7aSWarner Loshthis execution occurs without any calls to hooks.
63748e3e3a7aSWarner Losh
63758e3e3a7aSWarner Losh
63768e3e3a7aSWarner Losh<p>
63778e3e3a7aSWarner LoshHook functions cannot have continuations,
63788e3e3a7aSWarner Loshthat is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
63798e3e3a7aSWarner Losh<a href="#lua_pcallk"><code>lua_pcallk</code></a>, or <a href="#lua_callk"><code>lua_callk</code></a> with a non-null <code>k</code>.
63808e3e3a7aSWarner Losh
63818e3e3a7aSWarner Losh
63828e3e3a7aSWarner Losh<p>
63838e3e3a7aSWarner LoshHook functions can yield under the following conditions:
63848e3e3a7aSWarner LoshOnly count and line events can yield;
63858e3e3a7aSWarner Loshto yield, a hook function must finish its execution
63868e3e3a7aSWarner Loshcalling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero
63878e3e3a7aSWarner Losh(that is, with no values).
63888e3e3a7aSWarner Losh
63898e3e3a7aSWarner Losh
63908e3e3a7aSWarner Losh
63918e3e3a7aSWarner Losh
63928e3e3a7aSWarner Losh
63938e3e3a7aSWarner Losh<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p>
63948e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
63958e3e3a7aSWarner Losh<pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre>
63968e3e3a7aSWarner Losh
63978e3e3a7aSWarner Losh<p>
63988e3e3a7aSWarner LoshSets the debugging hook function.
63998e3e3a7aSWarner Losh
64008e3e3a7aSWarner Losh
64018e3e3a7aSWarner Losh<p>
64028e3e3a7aSWarner LoshArgument <code>f</code> is the hook function.
64038e3e3a7aSWarner Losh<code>mask</code> specifies on which events the hook will be called:
64048e3e3a7aSWarner Loshit is formed by a bitwise OR of the constants
64058e3e3a7aSWarner Losh<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>,
64068e3e3a7aSWarner Losh<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>,
64078e3e3a7aSWarner Losh<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>,
64088e3e3a7aSWarner Loshand <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>.
64098e3e3a7aSWarner LoshThe <code>count</code> argument is only meaningful when the mask
64108e3e3a7aSWarner Loshincludes <code>LUA_MASKCOUNT</code>.
64118e3e3a7aSWarner LoshFor each event, the hook is called as explained below:
64128e3e3a7aSWarner Losh
64138e3e3a7aSWarner Losh<ul>
64148e3e3a7aSWarner Losh
64158e3e3a7aSWarner Losh<li><b>The call hook: </b> is called when the interpreter calls a function.
64160495ed39SKyle EvansThe hook is called just after Lua enters the new function.
64178e3e3a7aSWarner Losh</li>
64188e3e3a7aSWarner Losh
64198e3e3a7aSWarner Losh<li><b>The return hook: </b> is called when the interpreter returns from a function.
64208e3e3a7aSWarner LoshThe hook is called just before Lua leaves the function.
64218e3e3a7aSWarner Losh</li>
64228e3e3a7aSWarner Losh
64238e3e3a7aSWarner Losh<li><b>The line hook: </b> is called when the interpreter is about to
64248e3e3a7aSWarner Loshstart the execution of a new line of code,
64258e3e3a7aSWarner Loshor when it jumps back in the code (even to the same line).
64260495ed39SKyle EvansThis event only happens while Lua is executing a Lua function.
64278e3e3a7aSWarner Losh</li>
64288e3e3a7aSWarner Losh
64298e3e3a7aSWarner Losh<li><b>The count hook: </b> is called after the interpreter executes every
64308e3e3a7aSWarner Losh<code>count</code> instructions.
64310495ed39SKyle EvansThis event only happens while Lua is executing a Lua function.
64328e3e3a7aSWarner Losh</li>
64338e3e3a7aSWarner Losh
64348e3e3a7aSWarner Losh</ul>
64358e3e3a7aSWarner Losh
64368e3e3a7aSWarner Losh<p>
64370495ed39SKyle EvansHooks are disabled by setting <code>mask</code> to zero.
64388e3e3a7aSWarner Losh
64398e3e3a7aSWarner Losh
64408e3e3a7aSWarner Losh
64418e3e3a7aSWarner Losh
64428e3e3a7aSWarner Losh
64438e3e3a7aSWarner Losh<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p>
64448e3e3a7aSWarner Losh<span class="apii">[-(0|1), +0, &ndash;]</span>
64458e3e3a7aSWarner Losh<pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre>
64468e3e3a7aSWarner Losh
64478e3e3a7aSWarner Losh<p>
64488e3e3a7aSWarner LoshSets the value of a local variable of a given activation record.
64490495ed39SKyle EvansIt assigns the value on the top of the stack
64508e3e3a7aSWarner Loshto the variable and returns its name.
64518e3e3a7aSWarner LoshIt also pops the value from the stack.
64528e3e3a7aSWarner Losh
64538e3e3a7aSWarner Losh
64548e3e3a7aSWarner Losh<p>
64558e3e3a7aSWarner LoshReturns <code>NULL</code> (and pops nothing)
64568e3e3a7aSWarner Loshwhen the index is greater than
64578e3e3a7aSWarner Loshthe number of active local variables.
64588e3e3a7aSWarner Losh
64598e3e3a7aSWarner Losh
64608e3e3a7aSWarner Losh<p>
64610495ed39SKyle EvansParameters <code>ar</code> and <code>n</code> are as in the function <a href="#lua_getlocal"><code>lua_getlocal</code></a>.
64628e3e3a7aSWarner Losh
64638e3e3a7aSWarner Losh
64648e3e3a7aSWarner Losh
64658e3e3a7aSWarner Losh
64668e3e3a7aSWarner Losh
64678e3e3a7aSWarner Losh<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p>
64688e3e3a7aSWarner Losh<span class="apii">[-(0|1), +0, &ndash;]</span>
64698e3e3a7aSWarner Losh<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre>
64708e3e3a7aSWarner Losh
64718e3e3a7aSWarner Losh<p>
64728e3e3a7aSWarner LoshSets the value of a closure's upvalue.
64730495ed39SKyle EvansIt assigns the value on the top of the stack
64748e3e3a7aSWarner Loshto the upvalue and returns its name.
64758e3e3a7aSWarner LoshIt also pops the value from the stack.
64768e3e3a7aSWarner Losh
64778e3e3a7aSWarner Losh
64788e3e3a7aSWarner Losh<p>
64798e3e3a7aSWarner LoshReturns <code>NULL</code> (and pops nothing)
64808e3e3a7aSWarner Loshwhen the index <code>n</code> is greater than the number of upvalues.
64818e3e3a7aSWarner Losh
64828e3e3a7aSWarner Losh
64838e3e3a7aSWarner Losh<p>
64840495ed39SKyle EvansParameters <code>funcindex</code> and <code>n</code> are as in
64850495ed39SKyle Evansthe function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>.
64868e3e3a7aSWarner Losh
64878e3e3a7aSWarner Losh
64888e3e3a7aSWarner Losh
64898e3e3a7aSWarner Losh
64908e3e3a7aSWarner Losh
64918e3e3a7aSWarner Losh<hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p>
64928e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
64938e3e3a7aSWarner Losh<pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre>
64948e3e3a7aSWarner Losh
64958e3e3a7aSWarner Losh<p>
64968e3e3a7aSWarner LoshReturns a unique identifier for the upvalue numbered <code>n</code>
64978e3e3a7aSWarner Loshfrom the closure at index <code>funcindex</code>.
64988e3e3a7aSWarner Losh
64998e3e3a7aSWarner Losh
65008e3e3a7aSWarner Losh<p>
65018e3e3a7aSWarner LoshThese unique identifiers allow a program to check whether different
65028e3e3a7aSWarner Loshclosures share upvalues.
65038e3e3a7aSWarner LoshLua closures that share an upvalue
65048e3e3a7aSWarner Losh(that is, that access a same external local variable)
65058e3e3a7aSWarner Loshwill return identical ids for those upvalue indices.
65068e3e3a7aSWarner Losh
65078e3e3a7aSWarner Losh
65088e3e3a7aSWarner Losh<p>
65090495ed39SKyle EvansParameters <code>funcindex</code> and <code>n</code> are as in
65100495ed39SKyle Evansthe function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>,
65118e3e3a7aSWarner Loshbut <code>n</code> cannot be greater than the number of upvalues.
65128e3e3a7aSWarner Losh
65138e3e3a7aSWarner Losh
65148e3e3a7aSWarner Losh
65158e3e3a7aSWarner Losh
65168e3e3a7aSWarner Losh
65178e3e3a7aSWarner Losh<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p>
65188e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
65198e3e3a7aSWarner Losh<pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
65208e3e3a7aSWarner Losh                                    int funcindex2, int n2);</pre>
65218e3e3a7aSWarner Losh
65228e3e3a7aSWarner Losh<p>
65238e3e3a7aSWarner LoshMake the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code>
65248e3e3a7aSWarner Loshrefer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>.
65258e3e3a7aSWarner Losh
65268e3e3a7aSWarner Losh
65278e3e3a7aSWarner Losh
65288e3e3a7aSWarner Losh
65298e3e3a7aSWarner Losh
65308e3e3a7aSWarner Losh
65318e3e3a7aSWarner Losh
65328e3e3a7aSWarner Losh<h1>5 &ndash; <a name="5">The Auxiliary Library</a></h1>
65338e3e3a7aSWarner Losh
65340495ed39SKyle Evans
65350495ed39SKyle Evans
65368e3e3a7aSWarner Losh<p>
65378e3e3a7aSWarner Losh
65388e3e3a7aSWarner LoshThe <em>auxiliary library</em> provides several convenient functions
65398e3e3a7aSWarner Loshto interface C with Lua.
65408e3e3a7aSWarner LoshWhile the basic API provides the primitive functions for all
65418e3e3a7aSWarner Loshinteractions between C and Lua,
65428e3e3a7aSWarner Loshthe auxiliary library provides higher-level functions for some
65438e3e3a7aSWarner Loshcommon tasks.
65448e3e3a7aSWarner Losh
65458e3e3a7aSWarner Losh
65468e3e3a7aSWarner Losh<p>
65478e3e3a7aSWarner LoshAll functions and types from the auxiliary library
65488e3e3a7aSWarner Loshare defined in header file <code>lauxlib.h</code> and
65498e3e3a7aSWarner Loshhave a prefix <code>luaL_</code>.
65508e3e3a7aSWarner Losh
65518e3e3a7aSWarner Losh
65528e3e3a7aSWarner Losh<p>
65538e3e3a7aSWarner LoshAll functions in the auxiliary library are built on
65548e3e3a7aSWarner Loshtop of the basic API,
65558e3e3a7aSWarner Loshand so they provide nothing that cannot be done with that API.
65568e3e3a7aSWarner LoshNevertheless, the use of the auxiliary library ensures
65578e3e3a7aSWarner Loshmore consistency to your code.
65588e3e3a7aSWarner Losh
65598e3e3a7aSWarner Losh
65608e3e3a7aSWarner Losh<p>
65618e3e3a7aSWarner LoshSeveral functions in the auxiliary library use internally some
65628e3e3a7aSWarner Loshextra stack slots.
65638e3e3a7aSWarner LoshWhen a function in the auxiliary library uses less than five slots,
65648e3e3a7aSWarner Loshit does not check the stack size;
65658e3e3a7aSWarner Loshit simply assumes that there are enough slots.
65668e3e3a7aSWarner Losh
65678e3e3a7aSWarner Losh
65688e3e3a7aSWarner Losh<p>
65698e3e3a7aSWarner LoshSeveral functions in the auxiliary library are used to
65708e3e3a7aSWarner Loshcheck C&nbsp;function arguments.
65718e3e3a7aSWarner LoshBecause the error message is formatted for arguments
65728e3e3a7aSWarner Losh(e.g., "<code>bad argument #1</code>"),
65738e3e3a7aSWarner Loshyou should not use these functions for other stack values.
65748e3e3a7aSWarner Losh
65758e3e3a7aSWarner Losh
65768e3e3a7aSWarner Losh<p>
65778e3e3a7aSWarner LoshFunctions called <code>luaL_check*</code>
65788e3e3a7aSWarner Loshalways raise an error if the check is not satisfied.
65798e3e3a7aSWarner Losh
65808e3e3a7aSWarner Losh
65818e3e3a7aSWarner Losh
65820495ed39SKyle Evans
65830495ed39SKyle Evans
65848e3e3a7aSWarner Losh<h2>5.1 &ndash; <a name="5.1">Functions and Types</a></h2>
65858e3e3a7aSWarner Losh
65868e3e3a7aSWarner Losh<p>
65878e3e3a7aSWarner LoshHere we list all functions and types from the auxiliary library
65888e3e3a7aSWarner Loshin alphabetical order.
65898e3e3a7aSWarner Losh
65908e3e3a7aSWarner Losh
65918e3e3a7aSWarner Losh
65928e3e3a7aSWarner Losh<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p>
65938e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span>
65948e3e3a7aSWarner Losh<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre>
65958e3e3a7aSWarner Losh
65968e3e3a7aSWarner Losh<p>
65978e3e3a7aSWarner LoshAdds the byte <code>c</code> to the buffer <code>B</code>
65988e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
65998e3e3a7aSWarner Losh
66008e3e3a7aSWarner Losh
66018e3e3a7aSWarner Losh
66028e3e3a7aSWarner Losh
66038e3e3a7aSWarner Losh
66040495ed39SKyle Evans<hr><h3><a name="luaL_addgsub"><code>luaL_addgsub</code></a></h3><p>
66058c784bb8SWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span>
66060495ed39SKyle Evans<pre>const void luaL_addgsub (luaL_Buffer *B, const char *s,
66070495ed39SKyle Evans                         const char *p, const char *r);</pre>
66080495ed39SKyle Evans
66090495ed39SKyle Evans<p>
66100495ed39SKyle EvansAdds a copy of the string <code>s</code> to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>),
66110495ed39SKyle Evansreplacing any occurrence of the string <code>p</code>
66120495ed39SKyle Evanswith the string <code>r</code>.
66130495ed39SKyle Evans
66140495ed39SKyle Evans
66150495ed39SKyle Evans
66160495ed39SKyle Evans
66170495ed39SKyle Evans
66188e3e3a7aSWarner Losh<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p>
66198e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span>
66208e3e3a7aSWarner Losh<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre>
66218e3e3a7aSWarner Losh
66228e3e3a7aSWarner Losh<p>
66238e3e3a7aSWarner LoshAdds the string pointed to by <code>s</code> with length <code>l</code> to
66248e3e3a7aSWarner Loshthe buffer <code>B</code>
66258e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
66268e3e3a7aSWarner LoshThe string can contain embedded zeros.
66278e3e3a7aSWarner Losh
66288e3e3a7aSWarner Losh
66298e3e3a7aSWarner Losh
66308e3e3a7aSWarner Losh
66318e3e3a7aSWarner Losh
66328e3e3a7aSWarner Losh<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p>
66338e3e3a7aSWarner Losh<span class="apii">[-?, +?, &ndash;]</span>
66348e3e3a7aSWarner Losh<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre>
66358e3e3a7aSWarner Losh
66368e3e3a7aSWarner Losh<p>
66370495ed39SKyle EvansAdds to the buffer <code>B</code>
66388e3e3a7aSWarner Losha string of length <code>n</code> previously copied to the
66398e3e3a7aSWarner Loshbuffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>).
66408e3e3a7aSWarner Losh
66418e3e3a7aSWarner Losh
66428e3e3a7aSWarner Losh
66438e3e3a7aSWarner Losh
66448e3e3a7aSWarner Losh
66458e3e3a7aSWarner Losh<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p>
66468e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span>
66478e3e3a7aSWarner Losh<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre>
66488e3e3a7aSWarner Losh
66498e3e3a7aSWarner Losh<p>
66508e3e3a7aSWarner LoshAdds the zero-terminated string pointed to by <code>s</code>
66518e3e3a7aSWarner Loshto the buffer <code>B</code>
66528e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
66538e3e3a7aSWarner Losh
66548e3e3a7aSWarner Losh
66558e3e3a7aSWarner Losh
66568e3e3a7aSWarner Losh
66578e3e3a7aSWarner Losh
66588e3e3a7aSWarner Losh<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p>
66598c784bb8SWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span>
66608e3e3a7aSWarner Losh<pre>void luaL_addvalue (luaL_Buffer *B);</pre>
66618e3e3a7aSWarner Losh
66628e3e3a7aSWarner Losh<p>
66630495ed39SKyle EvansAdds the value on the top of the stack
66648e3e3a7aSWarner Loshto the buffer <code>B</code>
66658e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
66668e3e3a7aSWarner LoshPops the value.
66678e3e3a7aSWarner Losh
66688e3e3a7aSWarner Losh
66698e3e3a7aSWarner Losh<p>
66708e3e3a7aSWarner LoshThis is the only function on string buffers that can (and must)
66718e3e3a7aSWarner Loshbe called with an extra element on the stack,
66728e3e3a7aSWarner Loshwhich is the value to be added to the buffer.
66738e3e3a7aSWarner Losh
66748e3e3a7aSWarner Losh
66758e3e3a7aSWarner Losh
66768e3e3a7aSWarner Losh
66778e3e3a7aSWarner Losh
66788e3e3a7aSWarner Losh<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p>
66798e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
66808e3e3a7aSWarner Losh<pre>void luaL_argcheck (lua_State *L,
66818e3e3a7aSWarner Losh                    int cond,
66828e3e3a7aSWarner Losh                    int arg,
66838e3e3a7aSWarner Losh                    const char *extramsg);</pre>
66848e3e3a7aSWarner Losh
66858e3e3a7aSWarner Losh<p>
66868e3e3a7aSWarner LoshChecks whether <code>cond</code> is true.
66878e3e3a7aSWarner LoshIf it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>).
66888e3e3a7aSWarner Losh
66898e3e3a7aSWarner Losh
66908e3e3a7aSWarner Losh
66918e3e3a7aSWarner Losh
66928e3e3a7aSWarner Losh
66938e3e3a7aSWarner Losh<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p>
66948e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
66958e3e3a7aSWarner Losh<pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre>
66968e3e3a7aSWarner Losh
66978e3e3a7aSWarner Losh<p>
66988e3e3a7aSWarner LoshRaises an error reporting a problem with argument <code>arg</code>
66998e3e3a7aSWarner Loshof the C&nbsp;function that called it,
67008e3e3a7aSWarner Loshusing a standard message
67018e3e3a7aSWarner Loshthat includes <code>extramsg</code> as a comment:
67028e3e3a7aSWarner Losh
67038e3e3a7aSWarner Losh<pre>
67048e3e3a7aSWarner Losh     bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>)
67058e3e3a7aSWarner Losh</pre><p>
67068e3e3a7aSWarner LoshThis function never returns.
67078e3e3a7aSWarner Losh
67088e3e3a7aSWarner Losh
67098e3e3a7aSWarner Losh
67108e3e3a7aSWarner Losh
67118e3e3a7aSWarner Losh
67120495ed39SKyle Evans<hr><h3><a name="luaL_argexpected"><code>luaL_argexpected</code></a></h3><p>
67130495ed39SKyle Evans<span class="apii">[-0, +0, <em>v</em>]</span>
67140495ed39SKyle Evans<pre>void luaL_argexpected (lua_State *L,
67150495ed39SKyle Evans                       int cond,
67160495ed39SKyle Evans                       int arg,
67170495ed39SKyle Evans                       const char *tname);</pre>
67180495ed39SKyle Evans
67190495ed39SKyle Evans<p>
67200495ed39SKyle EvansChecks whether <code>cond</code> is true.
67210495ed39SKyle EvansIf it is not, raises an error about the type of the argument <code>arg</code>
67220495ed39SKyle Evanswith a standard message (see <a href="#luaL_typeerror"><code>luaL_typeerror</code></a>).
67230495ed39SKyle Evans
67240495ed39SKyle Evans
67250495ed39SKyle Evans
67260495ed39SKyle Evans
67270495ed39SKyle Evans
67288e3e3a7aSWarner Losh<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3>
67298e3e3a7aSWarner Losh<pre>typedef struct luaL_Buffer luaL_Buffer;</pre>
67308e3e3a7aSWarner Losh
67318e3e3a7aSWarner Losh<p>
67328e3e3a7aSWarner LoshType for a <em>string buffer</em>.
67338e3e3a7aSWarner Losh
67348e3e3a7aSWarner Losh
67358e3e3a7aSWarner Losh<p>
67368e3e3a7aSWarner LoshA string buffer allows C&nbsp;code to build Lua strings piecemeal.
67378e3e3a7aSWarner LoshIts pattern of use is as follows:
67388e3e3a7aSWarner Losh
67398e3e3a7aSWarner Losh<ul>
67408e3e3a7aSWarner Losh
67418e3e3a7aSWarner Losh<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
67428e3e3a7aSWarner Losh
67438e3e3a7aSWarner Losh<li>Then initialize it with a call <code>luaL_buffinit(L, &amp;b)</code>.</li>
67448e3e3a7aSWarner Losh
67458e3e3a7aSWarner Losh<li>
67468e3e3a7aSWarner LoshThen add string pieces to the buffer calling any of
67478e3e3a7aSWarner Loshthe <code>luaL_add*</code> functions.
67488e3e3a7aSWarner Losh</li>
67498e3e3a7aSWarner Losh
67508e3e3a7aSWarner Losh<li>
67518e3e3a7aSWarner LoshFinish by calling <code>luaL_pushresult(&amp;b)</code>.
67528e3e3a7aSWarner LoshThis call leaves the final string on the top of the stack.
67538e3e3a7aSWarner Losh</li>
67548e3e3a7aSWarner Losh
67558e3e3a7aSWarner Losh</ul>
67568e3e3a7aSWarner Losh
67578e3e3a7aSWarner Losh<p>
67580495ed39SKyle EvansIf you know beforehand the maximum size of the resulting string,
67598e3e3a7aSWarner Loshyou can use the buffer like this:
67608e3e3a7aSWarner Losh
67618e3e3a7aSWarner Losh<ul>
67628e3e3a7aSWarner Losh
67638e3e3a7aSWarner Losh<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
67648e3e3a7aSWarner Losh
67658e3e3a7aSWarner Losh<li>Then initialize it and preallocate a space of
67668e3e3a7aSWarner Loshsize <code>sz</code> with a call <code>luaL_buffinitsize(L, &amp;b, sz)</code>.</li>
67678e3e3a7aSWarner Losh
67680495ed39SKyle Evans<li>Then produce the string into that space.</li>
67698e3e3a7aSWarner Losh
67708e3e3a7aSWarner Losh<li>
67718e3e3a7aSWarner LoshFinish by calling <code>luaL_pushresultsize(&amp;b, sz)</code>,
67728e3e3a7aSWarner Loshwhere <code>sz</code> is the total size of the resulting string
67730495ed39SKyle Evanscopied into that space (which may be less than or
67740495ed39SKyle Evansequal to the preallocated size).
67758e3e3a7aSWarner Losh</li>
67768e3e3a7aSWarner Losh
67778e3e3a7aSWarner Losh</ul>
67788e3e3a7aSWarner Losh
67798e3e3a7aSWarner Losh<p>
67808e3e3a7aSWarner LoshDuring its normal operation,
67818e3e3a7aSWarner Losha string buffer uses a variable number of stack slots.
67828e3e3a7aSWarner LoshSo, while using a buffer, you cannot assume that you know where
67838e3e3a7aSWarner Loshthe top of the stack is.
67848e3e3a7aSWarner LoshYou can use the stack between successive calls to buffer operations
67858e3e3a7aSWarner Loshas long as that use is balanced;
67868e3e3a7aSWarner Loshthat is,
67878e3e3a7aSWarner Loshwhen you call a buffer operation,
67888e3e3a7aSWarner Loshthe stack is at the same level
67898e3e3a7aSWarner Loshit was immediately after the previous buffer operation.
67908e3e3a7aSWarner Losh(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.)
67910495ed39SKyle EvansAfter calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>,
67920495ed39SKyle Evansthe stack is back to its level when the buffer was initialized,
67938e3e3a7aSWarner Loshplus the final string on its top.
67948e3e3a7aSWarner Losh
67958e3e3a7aSWarner Losh
67968e3e3a7aSWarner Losh
67978e3e3a7aSWarner Losh
67988e3e3a7aSWarner Losh
67990495ed39SKyle Evans<hr><h3><a name="luaL_buffaddr"><code>luaL_buffaddr</code></a></h3><p>
68000495ed39SKyle Evans<span class="apii">[-0, +0, &ndash;]</span>
68010495ed39SKyle Evans<pre>char *luaL_buffaddr (luaL_Buffer *B);</pre>
68020495ed39SKyle Evans
68030495ed39SKyle Evans<p>
68040495ed39SKyle EvansReturns the address of the current content of buffer <code>B</code>
68050495ed39SKyle Evans(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
68060495ed39SKyle EvansNote that any addition to the buffer may invalidate this address.
68070495ed39SKyle Evans
68080495ed39SKyle Evans
68090495ed39SKyle Evans
68100495ed39SKyle Evans
68110495ed39SKyle Evans
68128e3e3a7aSWarner Losh<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p>
68138c784bb8SWarner Losh<span class="apii">[-0, +?, &ndash;]</span>
68148e3e3a7aSWarner Losh<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre>
68158e3e3a7aSWarner Losh
68168e3e3a7aSWarner Losh<p>
68170495ed39SKyle EvansInitializes a buffer <code>B</code>
68180495ed39SKyle Evans(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
68198e3e3a7aSWarner LoshThis function does not allocate any space;
68200495ed39SKyle Evansthe buffer must be declared as a variable.
68210495ed39SKyle Evans
68220495ed39SKyle Evans
68230495ed39SKyle Evans
68240495ed39SKyle Evans
68250495ed39SKyle Evans
68260495ed39SKyle Evans<hr><h3><a name="luaL_bufflen"><code>luaL_bufflen</code></a></h3><p>
68270495ed39SKyle Evans<span class="apii">[-0, +0, &ndash;]</span>
68280495ed39SKyle Evans<pre>size_t luaL_bufflen (luaL_Buffer *B);</pre>
68290495ed39SKyle Evans
68300495ed39SKyle Evans<p>
68310495ed39SKyle EvansReturns the length of the current content of buffer <code>B</code>
68328e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
68338e3e3a7aSWarner Losh
68348e3e3a7aSWarner Losh
68358e3e3a7aSWarner Losh
68368e3e3a7aSWarner Losh
68378e3e3a7aSWarner Losh
68388e3e3a7aSWarner Losh<hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p>
68398e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span>
68408e3e3a7aSWarner Losh<pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre>
68418e3e3a7aSWarner Losh
68428e3e3a7aSWarner Losh<p>
68438e3e3a7aSWarner LoshEquivalent to the sequence
68448e3e3a7aSWarner Losh<a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>.
68458e3e3a7aSWarner Losh
68468e3e3a7aSWarner Losh
68478e3e3a7aSWarner Losh
68488e3e3a7aSWarner Losh
68498e3e3a7aSWarner Losh
68500495ed39SKyle Evans<hr><h3><a name="luaL_buffsub"><code>luaL_buffsub</code></a></h3><p>
68518c784bb8SWarner Losh<span class="apii">[-?, +?, &ndash;]</span>
68520495ed39SKyle Evans<pre>void luaL_buffsub (luaL_Buffer *B, int n);</pre>
68530495ed39SKyle Evans
68540495ed39SKyle Evans<p>
6855*a9490b81SWarner LoshRemoves <code>n</code> bytes from the buffer <code>B</code>
68560495ed39SKyle Evans(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
68570495ed39SKyle EvansThe buffer must have at least that many bytes.
68580495ed39SKyle Evans
68590495ed39SKyle Evans
68600495ed39SKyle Evans
68610495ed39SKyle Evans
68620495ed39SKyle Evans
68638e3e3a7aSWarner Losh<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p>
68648e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), <em>e</em>]</span>
68658e3e3a7aSWarner Losh<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre>
68668e3e3a7aSWarner Losh
68678e3e3a7aSWarner Losh<p>
68688e3e3a7aSWarner LoshCalls a metamethod.
68698e3e3a7aSWarner Losh
68708e3e3a7aSWarner Losh
68718e3e3a7aSWarner Losh<p>
68728e3e3a7aSWarner LoshIf the object at index <code>obj</code> has a metatable and this
68738e3e3a7aSWarner Loshmetatable has a field <code>e</code>,
68748e3e3a7aSWarner Loshthis function calls this field passing the object as its only argument.
68758e3e3a7aSWarner LoshIn this case this function returns true and pushes onto the
68768e3e3a7aSWarner Loshstack the value returned by the call.
68778e3e3a7aSWarner LoshIf there is no metatable or no metamethod,
68780495ed39SKyle Evansthis function returns false without pushing any value on the stack.
68798e3e3a7aSWarner Losh
68808e3e3a7aSWarner Losh
68818e3e3a7aSWarner Losh
68828e3e3a7aSWarner Losh
68838e3e3a7aSWarner Losh
68848e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p>
68858e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
68868e3e3a7aSWarner Losh<pre>void luaL_checkany (lua_State *L, int arg);</pre>
68878e3e3a7aSWarner Losh
68888e3e3a7aSWarner Losh<p>
68898e3e3a7aSWarner LoshChecks whether the function has an argument
68908e3e3a7aSWarner Loshof any type (including <b>nil</b>) at position <code>arg</code>.
68918e3e3a7aSWarner Losh
68928e3e3a7aSWarner Losh
68938e3e3a7aSWarner Losh
68948e3e3a7aSWarner Losh
68958e3e3a7aSWarner Losh
68968e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p>
68978e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
68988e3e3a7aSWarner Losh<pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre>
68998e3e3a7aSWarner Losh
69008e3e3a7aSWarner Losh<p>
69018e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is an integer
69028e3e3a7aSWarner Losh(or can be converted to an integer)
69030495ed39SKyle Evansand returns this integer.
69048e3e3a7aSWarner Losh
69058e3e3a7aSWarner Losh
69068e3e3a7aSWarner Losh
69078e3e3a7aSWarner Losh
69088e3e3a7aSWarner Losh
69098e3e3a7aSWarner Losh<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p>
69108e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
69118e3e3a7aSWarner Losh<pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre>
69128e3e3a7aSWarner Losh
69138e3e3a7aSWarner Losh<p>
69148e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string
69158e3e3a7aSWarner Loshand returns this string;
69160495ed39SKyle Evansif <code>l</code> is not <code>NULL</code> fills its referent
69178e3e3a7aSWarner Loshwith the string's length.
69188e3e3a7aSWarner Losh
69198e3e3a7aSWarner Losh
69208e3e3a7aSWarner Losh<p>
69218e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
69228e3e3a7aSWarner Loshso all conversions and caveats of that function apply here.
69238e3e3a7aSWarner Losh
69248e3e3a7aSWarner Losh
69258e3e3a7aSWarner Losh
69268e3e3a7aSWarner Losh
69278e3e3a7aSWarner Losh
69288e3e3a7aSWarner Losh<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p>
69298e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
69308e3e3a7aSWarner Losh<pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre>
69318e3e3a7aSWarner Losh
69328e3e3a7aSWarner Losh<p>
69338e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a number
69340495ed39SKyle Evansand returns this number converted to a <code>lua_Number</code>.
69358e3e3a7aSWarner Losh
69368e3e3a7aSWarner Losh
69378e3e3a7aSWarner Losh
69388e3e3a7aSWarner Losh
69398e3e3a7aSWarner Losh
69408e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p>
69418e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
69428e3e3a7aSWarner Losh<pre>int luaL_checkoption (lua_State *L,
69438e3e3a7aSWarner Losh                      int arg,
69448e3e3a7aSWarner Losh                      const char *def,
69458e3e3a7aSWarner Losh                      const char *const lst[]);</pre>
69468e3e3a7aSWarner Losh
69478e3e3a7aSWarner Losh<p>
69488e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string and
69498e3e3a7aSWarner Loshsearches for this string in the array <code>lst</code>
69508e3e3a7aSWarner Losh(which must be NULL-terminated).
69518e3e3a7aSWarner LoshReturns the index in the array where the string was found.
69528e3e3a7aSWarner LoshRaises an error if the argument is not a string or
69538e3e3a7aSWarner Loshif the string cannot be found.
69548e3e3a7aSWarner Losh
69558e3e3a7aSWarner Losh
69568e3e3a7aSWarner Losh<p>
69578e3e3a7aSWarner LoshIf <code>def</code> is not <code>NULL</code>,
69588e3e3a7aSWarner Loshthe function uses <code>def</code> as a default value when
69598e3e3a7aSWarner Loshthere is no argument <code>arg</code> or when this argument is <b>nil</b>.
69608e3e3a7aSWarner Losh
69618e3e3a7aSWarner Losh
69628e3e3a7aSWarner Losh<p>
69638e3e3a7aSWarner LoshThis is a useful function for mapping strings to C&nbsp;enums.
69648e3e3a7aSWarner Losh(The usual convention in Lua libraries is
69658e3e3a7aSWarner Loshto use strings instead of numbers to select options.)
69668e3e3a7aSWarner Losh
69678e3e3a7aSWarner Losh
69688e3e3a7aSWarner Losh
69698e3e3a7aSWarner Losh
69708e3e3a7aSWarner Losh
69718e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p>
69728e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
69738e3e3a7aSWarner Losh<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre>
69748e3e3a7aSWarner Losh
69758e3e3a7aSWarner Losh<p>
69768e3e3a7aSWarner LoshGrows the stack size to <code>top + sz</code> elements,
69778e3e3a7aSWarner Loshraising an error if the stack cannot grow to that size.
69788e3e3a7aSWarner Losh<code>msg</code> is an additional text to go into the error message
69798e3e3a7aSWarner Losh(or <code>NULL</code> for no additional text).
69808e3e3a7aSWarner Losh
69818e3e3a7aSWarner Losh
69828e3e3a7aSWarner Losh
69838e3e3a7aSWarner Losh
69848e3e3a7aSWarner Losh
69858e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p>
69868e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
69878e3e3a7aSWarner Losh<pre>const char *luaL_checkstring (lua_State *L, int arg);</pre>
69888e3e3a7aSWarner Losh
69898e3e3a7aSWarner Losh<p>
69908e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a string
69918e3e3a7aSWarner Loshand returns this string.
69928e3e3a7aSWarner Losh
69938e3e3a7aSWarner Losh
69948e3e3a7aSWarner Losh<p>
69958e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
69968e3e3a7aSWarner Loshso all conversions and caveats of that function apply here.
69978e3e3a7aSWarner Losh
69988e3e3a7aSWarner Losh
69998e3e3a7aSWarner Losh
70008e3e3a7aSWarner Losh
70018e3e3a7aSWarner Losh
70028e3e3a7aSWarner Losh<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p>
70038e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
70048e3e3a7aSWarner Losh<pre>void luaL_checktype (lua_State *L, int arg, int t);</pre>
70058e3e3a7aSWarner Losh
70068e3e3a7aSWarner Losh<p>
70078e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> has type <code>t</code>.
70088e3e3a7aSWarner LoshSee <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>.
70098e3e3a7aSWarner Losh
70108e3e3a7aSWarner Losh
70118e3e3a7aSWarner Losh
70128e3e3a7aSWarner Losh
70138e3e3a7aSWarner Losh
70148e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p>
70158e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
70168e3e3a7aSWarner Losh<pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre>
70178e3e3a7aSWarner Losh
70188e3e3a7aSWarner Losh<p>
70198e3e3a7aSWarner LoshChecks whether the function argument <code>arg</code> is a userdata
70208e3e3a7aSWarner Loshof the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and
70210495ed39SKyle Evansreturns the userdata's memory-block address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>).
70228e3e3a7aSWarner Losh
70238e3e3a7aSWarner Losh
70248e3e3a7aSWarner Losh
70258e3e3a7aSWarner Losh
70268e3e3a7aSWarner Losh
70278e3e3a7aSWarner Losh<hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p>
70288e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
70298e3e3a7aSWarner Losh<pre>void luaL_checkversion (lua_State *L);</pre>
70308e3e3a7aSWarner Losh
70318e3e3a7aSWarner Losh<p>
70320495ed39SKyle EvansChecks whether the code making the call and the Lua library being called
70330495ed39SKyle Evansare using the same version of Lua and the same numeric types.
70348e3e3a7aSWarner Losh
70358e3e3a7aSWarner Losh
70368e3e3a7aSWarner Losh
70378e3e3a7aSWarner Losh
70388e3e3a7aSWarner Losh
70398e3e3a7aSWarner Losh<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p>
70400495ed39SKyle Evans<span class="apii">[-0, +?, <em>m</em>]</span>
70418e3e3a7aSWarner Losh<pre>int luaL_dofile (lua_State *L, const char *filename);</pre>
70428e3e3a7aSWarner Losh
70438e3e3a7aSWarner Losh<p>
70448e3e3a7aSWarner LoshLoads and runs the given file.
70458e3e3a7aSWarner LoshIt is defined as the following macro:
70468e3e3a7aSWarner Losh
70478e3e3a7aSWarner Losh<pre>
70488e3e3a7aSWarner Losh     (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
70498e3e3a7aSWarner Losh</pre><p>
7050*a9490b81SWarner LoshIt returns&nbsp;0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) if there are no errors,
7051*a9490b81SWarner Loshor 1 in case of errors.
70528e3e3a7aSWarner Losh
70538e3e3a7aSWarner Losh
70548e3e3a7aSWarner Losh
70558e3e3a7aSWarner Losh
70568e3e3a7aSWarner Losh
70578e3e3a7aSWarner Losh<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p>
70588e3e3a7aSWarner Losh<span class="apii">[-0, +?, &ndash;]</span>
70598e3e3a7aSWarner Losh<pre>int luaL_dostring (lua_State *L, const char *str);</pre>
70608e3e3a7aSWarner Losh
70618e3e3a7aSWarner Losh<p>
70628e3e3a7aSWarner LoshLoads and runs the given string.
70638e3e3a7aSWarner LoshIt is defined as the following macro:
70648e3e3a7aSWarner Losh
70658e3e3a7aSWarner Losh<pre>
70668e3e3a7aSWarner Losh     (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
70678e3e3a7aSWarner Losh</pre><p>
7068*a9490b81SWarner LoshIt returns&nbsp;0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) if there are no errors,
7069*a9490b81SWarner Loshor 1 in case of errors.
70708e3e3a7aSWarner Losh
70718e3e3a7aSWarner Losh
70728e3e3a7aSWarner Losh
70738e3e3a7aSWarner Losh
70748e3e3a7aSWarner Losh
70758e3e3a7aSWarner Losh<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p>
70768e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
70778e3e3a7aSWarner Losh<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre>
70788e3e3a7aSWarner Losh
70798e3e3a7aSWarner Losh<p>
70808e3e3a7aSWarner LoshRaises an error.
70818e3e3a7aSWarner LoshThe error message format is given by <code>fmt</code>
70828e3e3a7aSWarner Loshplus any extra arguments,
70838e3e3a7aSWarner Loshfollowing the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>.
70848e3e3a7aSWarner LoshIt also adds at the beginning of the message the file name and
70858e3e3a7aSWarner Loshthe line number where the error occurred,
70868e3e3a7aSWarner Loshif this information is available.
70878e3e3a7aSWarner Losh
70888e3e3a7aSWarner Losh
70898e3e3a7aSWarner Losh<p>
70908e3e3a7aSWarner LoshThis function never returns,
70918e3e3a7aSWarner Loshbut it is an idiom to use it in C&nbsp;functions
70928e3e3a7aSWarner Loshas <code>return luaL_error(<em>args</em>)</code>.
70938e3e3a7aSWarner Losh
70948e3e3a7aSWarner Losh
70958e3e3a7aSWarner Losh
70968e3e3a7aSWarner Losh
70978e3e3a7aSWarner Losh
70988e3e3a7aSWarner Losh<hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p>
70998e3e3a7aSWarner Losh<span class="apii">[-0, +3, <em>m</em>]</span>
71008e3e3a7aSWarner Losh<pre>int luaL_execresult (lua_State *L, int stat);</pre>
71018e3e3a7aSWarner Losh
71028e3e3a7aSWarner Losh<p>
71038e3e3a7aSWarner LoshThis function produces the return values for
71048e3e3a7aSWarner Loshprocess-related functions in the standard library
71058e3e3a7aSWarner Losh(<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>).
71068e3e3a7aSWarner Losh
71078e3e3a7aSWarner Losh
71088e3e3a7aSWarner Losh
71098e3e3a7aSWarner Losh
71108e3e3a7aSWarner Losh
71118e3e3a7aSWarner Losh<hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p>
71128e3e3a7aSWarner Losh<span class="apii">[-0, +(1|3), <em>m</em>]</span>
71138e3e3a7aSWarner Losh<pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre>
71148e3e3a7aSWarner Losh
71158e3e3a7aSWarner Losh<p>
71168e3e3a7aSWarner LoshThis function produces the return values for
71178e3e3a7aSWarner Loshfile-related functions in the standard library
71188e3e3a7aSWarner Losh(<a href="#pdf-io.open"><code>io.open</code></a>, <a href="#pdf-os.rename"><code>os.rename</code></a>, <a href="#pdf-file:seek"><code>file:seek</code></a>, etc.).
71198e3e3a7aSWarner Losh
71208e3e3a7aSWarner Losh
71218e3e3a7aSWarner Losh
71228e3e3a7aSWarner Losh
71238e3e3a7aSWarner Losh
71248e3e3a7aSWarner Losh<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p>
71258e3e3a7aSWarner Losh<span class="apii">[-0, +(0|1), <em>m</em>]</span>
71268e3e3a7aSWarner Losh<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre>
71278e3e3a7aSWarner Losh
71288e3e3a7aSWarner Losh<p>
71298e3e3a7aSWarner LoshPushes onto the stack the field <code>e</code> from the metatable
7130e112e9d2SKyle Evansof the object at index <code>obj</code> and returns the type of the pushed value.
71318e3e3a7aSWarner LoshIf the object does not have a metatable,
71328e3e3a7aSWarner Loshor if the metatable does not have this field,
71338e3e3a7aSWarner Loshpushes nothing and returns <code>LUA_TNIL</code>.
71348e3e3a7aSWarner Losh
71358e3e3a7aSWarner Losh
71368e3e3a7aSWarner Losh
71378e3e3a7aSWarner Losh
71388e3e3a7aSWarner Losh
71398e3e3a7aSWarner Losh<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p>
71408e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
71418e3e3a7aSWarner Losh<pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre>
71428e3e3a7aSWarner Losh
71438e3e3a7aSWarner Losh<p>
71440495ed39SKyle EvansPushes onto the stack the metatable associated with the name <code>tname</code>
71450495ed39SKyle Evansin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>),
71460495ed39SKyle Evansor <b>nil</b> if there is no metatable associated with that name.
71478e3e3a7aSWarner LoshReturns the type of the pushed value.
71488e3e3a7aSWarner Losh
71498e3e3a7aSWarner Losh
71508e3e3a7aSWarner Losh
71518e3e3a7aSWarner Losh
71528e3e3a7aSWarner Losh
71538e3e3a7aSWarner Losh<hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p>
71548e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span>
71558e3e3a7aSWarner Losh<pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre>
71568e3e3a7aSWarner Losh
71578e3e3a7aSWarner Losh<p>
71588e3e3a7aSWarner LoshEnsures that the value <code>t[fname]</code>,
71598e3e3a7aSWarner Loshwhere <code>t</code> is the value at index <code>idx</code>,
71608e3e3a7aSWarner Loshis a table,
71618e3e3a7aSWarner Loshand pushes that table onto the stack.
71628e3e3a7aSWarner LoshReturns true if it finds a previous table there
71638e3e3a7aSWarner Loshand false if it creates a new table.
71648e3e3a7aSWarner Losh
71658e3e3a7aSWarner Losh
71668e3e3a7aSWarner Losh
71678e3e3a7aSWarner Losh
71688e3e3a7aSWarner Losh
71698e3e3a7aSWarner Losh<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p>
71708e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
71718e3e3a7aSWarner Losh<pre>const char *luaL_gsub (lua_State *L,
71728e3e3a7aSWarner Losh                       const char *s,
71738e3e3a7aSWarner Losh                       const char *p,
71748e3e3a7aSWarner Losh                       const char *r);</pre>
71758e3e3a7aSWarner Losh
71768e3e3a7aSWarner Losh<p>
71770495ed39SKyle EvansCreates a copy of string <code>s</code>,
71780495ed39SKyle Evansreplacing any occurrence of the string <code>p</code>
71798e3e3a7aSWarner Loshwith the string <code>r</code>.
71808e3e3a7aSWarner LoshPushes the resulting string on the stack and returns it.
71818e3e3a7aSWarner Losh
71828e3e3a7aSWarner Losh
71838e3e3a7aSWarner Losh
71848e3e3a7aSWarner Losh
71858e3e3a7aSWarner Losh
71868e3e3a7aSWarner Losh<hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p>
71878e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span>
71888e3e3a7aSWarner Losh<pre>lua_Integer luaL_len (lua_State *L, int index);</pre>
71898e3e3a7aSWarner Losh
71908e3e3a7aSWarner Losh<p>
71918e3e3a7aSWarner LoshReturns the "length" of the value at the given index
71928e3e3a7aSWarner Loshas a number;
71938e3e3a7aSWarner Loshit is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">&sect;3.4.7</a>).
71948e3e3a7aSWarner LoshRaises an error if the result of the operation is not an integer.
71950495ed39SKyle Evans(This case can only happen through metamethods.)
71968e3e3a7aSWarner Losh
71978e3e3a7aSWarner Losh
71988e3e3a7aSWarner Losh
71998e3e3a7aSWarner Losh
72008e3e3a7aSWarner Losh
72018e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p>
72028e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
72038e3e3a7aSWarner Losh<pre>int luaL_loadbuffer (lua_State *L,
72048e3e3a7aSWarner Losh                     const char *buff,
72058e3e3a7aSWarner Losh                     size_t sz,
72068e3e3a7aSWarner Losh                     const char *name);</pre>
72078e3e3a7aSWarner Losh
72088e3e3a7aSWarner Losh<p>
72098e3e3a7aSWarner LoshEquivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>.
72108e3e3a7aSWarner Losh
72118e3e3a7aSWarner Losh
72128e3e3a7aSWarner Losh
72138e3e3a7aSWarner Losh
72148e3e3a7aSWarner Losh
72158e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p>
72168e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
72178e3e3a7aSWarner Losh<pre>int luaL_loadbufferx (lua_State *L,
72188e3e3a7aSWarner Losh                      const char *buff,
72198e3e3a7aSWarner Losh                      size_t sz,
72208e3e3a7aSWarner Losh                      const char *name,
72218e3e3a7aSWarner Losh                      const char *mode);</pre>
72228e3e3a7aSWarner Losh
72238e3e3a7aSWarner Losh<p>
72248e3e3a7aSWarner LoshLoads a buffer as a Lua chunk.
72258e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the
72268e3e3a7aSWarner Loshbuffer pointed to by <code>buff</code> with size <code>sz</code>.
72278e3e3a7aSWarner Losh
72288e3e3a7aSWarner Losh
72298e3e3a7aSWarner Losh<p>
72308e3e3a7aSWarner LoshThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
72318e3e3a7aSWarner Losh<code>name</code> is the chunk name,
72328e3e3a7aSWarner Loshused for debug information and error messages.
72330495ed39SKyle EvansThe string <code>mode</code> works as in the function <a href="#lua_load"><code>lua_load</code></a>.
72348e3e3a7aSWarner Losh
72358e3e3a7aSWarner Losh
72368e3e3a7aSWarner Losh
72378e3e3a7aSWarner Losh
72388e3e3a7aSWarner Losh
72398e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p>
72408e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
72418e3e3a7aSWarner Losh<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre>
72428e3e3a7aSWarner Losh
72438e3e3a7aSWarner Losh<p>
72448e3e3a7aSWarner LoshEquivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>.
72458e3e3a7aSWarner Losh
72468e3e3a7aSWarner Losh
72478e3e3a7aSWarner Losh
72488e3e3a7aSWarner Losh
72498e3e3a7aSWarner Losh
72508e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p>
72518e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
72528e3e3a7aSWarner Losh<pre>int luaL_loadfilex (lua_State *L, const char *filename,
72538e3e3a7aSWarner Losh                                            const char *mode);</pre>
72548e3e3a7aSWarner Losh
72558e3e3a7aSWarner Losh<p>
72568e3e3a7aSWarner LoshLoads a file as a Lua chunk.
72578e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file
72588e3e3a7aSWarner Loshnamed <code>filename</code>.
72598e3e3a7aSWarner LoshIf <code>filename</code> is <code>NULL</code>,
72608e3e3a7aSWarner Loshthen it loads from the standard input.
72618e3e3a7aSWarner LoshThe first line in the file is ignored if it starts with a <code>#</code>.
72628e3e3a7aSWarner Losh
72638e3e3a7aSWarner Losh
72648e3e3a7aSWarner Losh<p>
72650495ed39SKyle EvansThe string <code>mode</code> works as in the function <a href="#lua_load"><code>lua_load</code></a>.
72668e3e3a7aSWarner Losh
72678e3e3a7aSWarner Losh
72688e3e3a7aSWarner Losh<p>
72690495ed39SKyle EvansThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>
72700495ed39SKyle Evansor <a href="#pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> for file-related errors.
72718e3e3a7aSWarner Losh
72728e3e3a7aSWarner Losh
72738e3e3a7aSWarner Losh<p>
72748e3e3a7aSWarner LoshAs <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
72758e3e3a7aSWarner Loshit does not run it.
72768e3e3a7aSWarner Losh
72778e3e3a7aSWarner Losh
72788e3e3a7aSWarner Losh
72798e3e3a7aSWarner Losh
72808e3e3a7aSWarner Losh
72818e3e3a7aSWarner Losh<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p>
72828e3e3a7aSWarner Losh<span class="apii">[-0, +1, &ndash;]</span>
72838e3e3a7aSWarner Losh<pre>int luaL_loadstring (lua_State *L, const char *s);</pre>
72848e3e3a7aSWarner Losh
72858e3e3a7aSWarner Losh<p>
72868e3e3a7aSWarner LoshLoads a string as a Lua chunk.
72878e3e3a7aSWarner LoshThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in
72888e3e3a7aSWarner Loshthe zero-terminated string <code>s</code>.
72898e3e3a7aSWarner Losh
72908e3e3a7aSWarner Losh
72918e3e3a7aSWarner Losh<p>
72928e3e3a7aSWarner LoshThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
72938e3e3a7aSWarner Losh
72948e3e3a7aSWarner Losh
72958e3e3a7aSWarner Losh<p>
72968e3e3a7aSWarner LoshAlso as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
72978e3e3a7aSWarner Loshit does not run it.
72988e3e3a7aSWarner Losh
72998e3e3a7aSWarner Losh
73008e3e3a7aSWarner Losh
73018e3e3a7aSWarner Losh
73028e3e3a7aSWarner Losh
73038e3e3a7aSWarner Losh<hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p>
73048e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
73058e3e3a7aSWarner Losh<pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre>
73068e3e3a7aSWarner Losh
73078e3e3a7aSWarner Losh<p>
73088e3e3a7aSWarner LoshCreates a new table and registers there
73090495ed39SKyle Evansthe functions in the list <code>l</code>.
73108e3e3a7aSWarner Losh
73118e3e3a7aSWarner Losh
73128e3e3a7aSWarner Losh<p>
73138e3e3a7aSWarner LoshIt is implemented as the following macro:
73148e3e3a7aSWarner Losh
73158e3e3a7aSWarner Losh<pre>
73168e3e3a7aSWarner Losh     (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
73178e3e3a7aSWarner Losh</pre><p>
73188e3e3a7aSWarner LoshThe array <code>l</code> must be the actual array,
73198e3e3a7aSWarner Loshnot a pointer to it.
73208e3e3a7aSWarner Losh
73218e3e3a7aSWarner Losh
73228e3e3a7aSWarner Losh
73238e3e3a7aSWarner Losh
73248e3e3a7aSWarner Losh
73258e3e3a7aSWarner Losh<hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p>
73268e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
73278e3e3a7aSWarner Losh<pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre>
73288e3e3a7aSWarner Losh
73298e3e3a7aSWarner Losh<p>
73308e3e3a7aSWarner LoshCreates a new table with a size optimized
73318e3e3a7aSWarner Loshto store all entries in the array <code>l</code>
73328e3e3a7aSWarner Losh(but does not actually store them).
73338e3e3a7aSWarner LoshIt is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>
73348e3e3a7aSWarner Losh(see <a href="#luaL_newlib"><code>luaL_newlib</code></a>).
73358e3e3a7aSWarner Losh
73368e3e3a7aSWarner Losh
73378e3e3a7aSWarner Losh<p>
73388e3e3a7aSWarner LoshIt is implemented as a macro.
73398e3e3a7aSWarner LoshThe array <code>l</code> must be the actual array,
73408e3e3a7aSWarner Loshnot a pointer to it.
73418e3e3a7aSWarner Losh
73428e3e3a7aSWarner Losh
73438e3e3a7aSWarner Losh
73448e3e3a7aSWarner Losh
73458e3e3a7aSWarner Losh
73468e3e3a7aSWarner Losh<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p>
73478e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
73488e3e3a7aSWarner Losh<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre>
73498e3e3a7aSWarner Losh
73508e3e3a7aSWarner Losh<p>
73518e3e3a7aSWarner LoshIf the registry already has the key <code>tname</code>,
73528e3e3a7aSWarner Loshreturns 0.
73538e3e3a7aSWarner LoshOtherwise,
73548e3e3a7aSWarner Loshcreates a new table to be used as a metatable for userdata,
73558e3e3a7aSWarner Loshadds to this new table the pair <code>__name = tname</code>,
73568e3e3a7aSWarner Loshadds to the registry the pair <code>[tname] = new table</code>,
73578e3e3a7aSWarner Loshand returns 1.
73588e3e3a7aSWarner Losh
73598e3e3a7aSWarner Losh
73608e3e3a7aSWarner Losh<p>
73610495ed39SKyle EvansIn both cases,
73620495ed39SKyle Evansthe function pushes onto the stack the final value associated
73638e3e3a7aSWarner Loshwith <code>tname</code> in the registry.
73648e3e3a7aSWarner Losh
73658e3e3a7aSWarner Losh
73668e3e3a7aSWarner Losh
73678e3e3a7aSWarner Losh
73688e3e3a7aSWarner Losh
73698e3e3a7aSWarner Losh<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p>
73708e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
73718e3e3a7aSWarner Losh<pre>lua_State *luaL_newstate (void);</pre>
73728e3e3a7aSWarner Losh
73738e3e3a7aSWarner Losh<p>
73748e3e3a7aSWarner LoshCreates a new Lua state.
73758e3e3a7aSWarner LoshIt calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an
7376*a9490b81SWarner Loshallocator based on the ISO&nbsp;C allocation functions
73770495ed39SKyle Evansand then sets a warning function and a panic function (see <a href="#4.4">&sect;4.4</a>)
73780495ed39SKyle Evansthat print messages to the standard error output.
73798e3e3a7aSWarner Losh
73808e3e3a7aSWarner Losh
73818e3e3a7aSWarner Losh<p>
73828e3e3a7aSWarner LoshReturns the new state,
73838e3e3a7aSWarner Loshor <code>NULL</code> if there is a memory allocation error.
73848e3e3a7aSWarner Losh
73858e3e3a7aSWarner Losh
73868e3e3a7aSWarner Losh
73878e3e3a7aSWarner Losh
73888e3e3a7aSWarner Losh
73898e3e3a7aSWarner Losh<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p>
73908e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>e</em>]</span>
73918e3e3a7aSWarner Losh<pre>void luaL_openlibs (lua_State *L);</pre>
73928e3e3a7aSWarner Losh
73938e3e3a7aSWarner Losh<p>
73948e3e3a7aSWarner LoshOpens all standard Lua libraries into the given state.
73958e3e3a7aSWarner Losh
73968e3e3a7aSWarner Losh
73978e3e3a7aSWarner Losh
73988e3e3a7aSWarner Losh
73998e3e3a7aSWarner Losh
74008e3e3a7aSWarner Losh<hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p>
74010495ed39SKyle Evans<span class="apii">[-0, +0, &ndash;]</span>
74028e3e3a7aSWarner Losh<pre>T luaL_opt (L, func, arg, dflt);</pre>
74038e3e3a7aSWarner Losh
74048e3e3a7aSWarner Losh<p>
74058e3e3a7aSWarner LoshThis macro is defined as follows:
74068e3e3a7aSWarner Losh
74078e3e3a7aSWarner Losh<pre>
74088e3e3a7aSWarner Losh     (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))
74098e3e3a7aSWarner Losh</pre><p>
74108e3e3a7aSWarner LoshIn words, if the argument <code>arg</code> is nil or absent,
74118e3e3a7aSWarner Loshthe macro results in the default <code>dflt</code>.
74128e3e3a7aSWarner LoshOtherwise, it results in the result of calling <code>func</code>
74138e3e3a7aSWarner Loshwith the state <code>L</code> and the argument index <code>arg</code> as
7414e112e9d2SKyle Evansarguments.
74158e3e3a7aSWarner LoshNote that it evaluates the expression <code>dflt</code> only if needed.
74168e3e3a7aSWarner Losh
74178e3e3a7aSWarner Losh
74188e3e3a7aSWarner Losh
74198e3e3a7aSWarner Losh
74208e3e3a7aSWarner Losh
74218e3e3a7aSWarner Losh<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p>
74228e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
74238e3e3a7aSWarner Losh<pre>lua_Integer luaL_optinteger (lua_State *L,
74248e3e3a7aSWarner Losh                             int arg,
74258e3e3a7aSWarner Losh                             lua_Integer d);</pre>
74268e3e3a7aSWarner Losh
74278e3e3a7aSWarner Losh<p>
74288e3e3a7aSWarner LoshIf the function argument <code>arg</code> is an integer
74290495ed39SKyle Evans(or it is convertible to an integer),
74308e3e3a7aSWarner Loshreturns this integer.
74318e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>,
74328e3e3a7aSWarner Loshreturns <code>d</code>.
74338e3e3a7aSWarner LoshOtherwise, raises an error.
74348e3e3a7aSWarner Losh
74358e3e3a7aSWarner Losh
74368e3e3a7aSWarner Losh
74378e3e3a7aSWarner Losh
74388e3e3a7aSWarner Losh
74398e3e3a7aSWarner Losh<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p>
74408e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
74418e3e3a7aSWarner Losh<pre>const char *luaL_optlstring (lua_State *L,
74428e3e3a7aSWarner Losh                             int arg,
74438e3e3a7aSWarner Losh                             const char *d,
74448e3e3a7aSWarner Losh                             size_t *l);</pre>
74458e3e3a7aSWarner Losh
74468e3e3a7aSWarner Losh<p>
74478e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a string,
74488e3e3a7aSWarner Loshreturns this string.
74498e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>,
74508e3e3a7aSWarner Loshreturns <code>d</code>.
74518e3e3a7aSWarner LoshOtherwise, raises an error.
74528e3e3a7aSWarner Losh
74538e3e3a7aSWarner Losh
74548e3e3a7aSWarner Losh<p>
74558e3e3a7aSWarner LoshIf <code>l</code> is not <code>NULL</code>,
74560495ed39SKyle Evansfills its referent with the result's length.
74578e3e3a7aSWarner LoshIf the result is <code>NULL</code>
74588e3e3a7aSWarner Losh(only possible when returning <code>d</code> and <code>d == NULL</code>),
74598e3e3a7aSWarner Loshits length is considered zero.
74608e3e3a7aSWarner Losh
74618e3e3a7aSWarner Losh
74628e3e3a7aSWarner Losh<p>
74638e3e3a7aSWarner LoshThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
74648e3e3a7aSWarner Loshso all conversions and caveats of that function apply here.
74658e3e3a7aSWarner Losh
74668e3e3a7aSWarner Losh
74678e3e3a7aSWarner Losh
74688e3e3a7aSWarner Losh
74698e3e3a7aSWarner Losh
74708e3e3a7aSWarner Losh<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p>
74718e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
74728e3e3a7aSWarner Losh<pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre>
74738e3e3a7aSWarner Losh
74748e3e3a7aSWarner Losh<p>
74758e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a number,
74760495ed39SKyle Evansreturns this number as a <code>lua_Number</code>.
74778e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>,
74788e3e3a7aSWarner Loshreturns <code>d</code>.
74798e3e3a7aSWarner LoshOtherwise, raises an error.
74808e3e3a7aSWarner Losh
74818e3e3a7aSWarner Losh
74828e3e3a7aSWarner Losh
74838e3e3a7aSWarner Losh
74848e3e3a7aSWarner Losh
74858e3e3a7aSWarner Losh<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p>
74868e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>v</em>]</span>
74878e3e3a7aSWarner Losh<pre>const char *luaL_optstring (lua_State *L,
74888e3e3a7aSWarner Losh                            int arg,
74898e3e3a7aSWarner Losh                            const char *d);</pre>
74908e3e3a7aSWarner Losh
74918e3e3a7aSWarner Losh<p>
74928e3e3a7aSWarner LoshIf the function argument <code>arg</code> is a string,
74938e3e3a7aSWarner Loshreturns this string.
74948e3e3a7aSWarner LoshIf this argument is absent or is <b>nil</b>,
74958e3e3a7aSWarner Loshreturns <code>d</code>.
74968e3e3a7aSWarner LoshOtherwise, raises an error.
74978e3e3a7aSWarner Losh
74988e3e3a7aSWarner Losh
74998e3e3a7aSWarner Losh
75008e3e3a7aSWarner Losh
75018e3e3a7aSWarner Losh
75028e3e3a7aSWarner Losh<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p>
75038e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span>
75048e3e3a7aSWarner Losh<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre>
75058e3e3a7aSWarner Losh
75068e3e3a7aSWarner Losh<p>
75078e3e3a7aSWarner LoshEquivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>
75088e3e3a7aSWarner Loshwith the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>.
75098e3e3a7aSWarner Losh
75108e3e3a7aSWarner Losh
75118e3e3a7aSWarner Losh
75128e3e3a7aSWarner Losh
75138e3e3a7aSWarner Losh
75148e3e3a7aSWarner Losh<hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p>
75158e3e3a7aSWarner Losh<span class="apii">[-?, +?, <em>m</em>]</span>
75168e3e3a7aSWarner Losh<pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre>
75178e3e3a7aSWarner Losh
75188e3e3a7aSWarner Losh<p>
75198e3e3a7aSWarner LoshReturns an address to a space of size <code>sz</code>
75208e3e3a7aSWarner Loshwhere you can copy a string to be added to buffer <code>B</code>
75218e3e3a7aSWarner Losh(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
75228e3e3a7aSWarner LoshAfter copying the string into this space you must call
75238e3e3a7aSWarner Losh<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add
75248e3e3a7aSWarner Loshit to the buffer.
75258e3e3a7aSWarner Losh
75268e3e3a7aSWarner Losh
75278e3e3a7aSWarner Losh
75288e3e3a7aSWarner Losh
75298e3e3a7aSWarner Losh
75300495ed39SKyle Evans<hr><h3><a name="luaL_pushfail"><code>luaL_pushfail</code></a></h3><p>
75310495ed39SKyle Evans<span class="apii">[-0, +1, &ndash;]</span>
75320495ed39SKyle Evans<pre>void luaL_pushfail (lua_State *L);</pre>
75330495ed39SKyle Evans
75340495ed39SKyle Evans<p>
75350495ed39SKyle EvansPushes the <b>fail</b> value onto the stack (see <a href="#6">&sect;6</a>).
75360495ed39SKyle Evans
75370495ed39SKyle Evans
75380495ed39SKyle Evans
75390495ed39SKyle Evans
75400495ed39SKyle Evans
75418e3e3a7aSWarner Losh<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p>
75428e3e3a7aSWarner Losh<span class="apii">[-?, +1, <em>m</em>]</span>
75438e3e3a7aSWarner Losh<pre>void luaL_pushresult (luaL_Buffer *B);</pre>
75448e3e3a7aSWarner Losh
75458e3e3a7aSWarner Losh<p>
75468e3e3a7aSWarner LoshFinishes the use of buffer <code>B</code> leaving the final string on
75478e3e3a7aSWarner Loshthe top of the stack.
75488e3e3a7aSWarner Losh
75498e3e3a7aSWarner Losh
75508e3e3a7aSWarner Losh
75518e3e3a7aSWarner Losh
75528e3e3a7aSWarner Losh
75538e3e3a7aSWarner Losh<hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p>
75548e3e3a7aSWarner Losh<span class="apii">[-?, +1, <em>m</em>]</span>
75558e3e3a7aSWarner Losh<pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre>
75568e3e3a7aSWarner Losh
75578e3e3a7aSWarner Losh<p>
75588e3e3a7aSWarner LoshEquivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>.
75598e3e3a7aSWarner Losh
75608e3e3a7aSWarner Losh
75618e3e3a7aSWarner Losh
75628e3e3a7aSWarner Losh
75638e3e3a7aSWarner Losh
75648e3e3a7aSWarner Losh<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p>
75658e3e3a7aSWarner Losh<span class="apii">[-1, +0, <em>m</em>]</span>
75668e3e3a7aSWarner Losh<pre>int luaL_ref (lua_State *L, int t);</pre>
75678e3e3a7aSWarner Losh
75688e3e3a7aSWarner Losh<p>
75698e3e3a7aSWarner LoshCreates and returns a <em>reference</em>,
75708e3e3a7aSWarner Loshin the table at index <code>t</code>,
75710495ed39SKyle Evansfor the object on the top of the stack (and pops the object).
75728e3e3a7aSWarner Losh
75738e3e3a7aSWarner Losh
75748e3e3a7aSWarner Losh<p>
75758e3e3a7aSWarner LoshA reference is a unique integer key.
75760495ed39SKyle EvansAs long as you do not manually add integer keys into the table <code>t</code>,
75778e3e3a7aSWarner Losh<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns.
75780495ed39SKyle EvansYou can retrieve an object referred by the reference <code>r</code>
75798e3e3a7aSWarner Loshby calling <code>lua_rawgeti(L, t, r)</code>.
75800495ed39SKyle EvansThe function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference.
75818e3e3a7aSWarner Losh
75828e3e3a7aSWarner Losh
75838e3e3a7aSWarner Losh<p>
75840495ed39SKyle EvansIf the object on the top of the stack is <b>nil</b>,
75858e3e3a7aSWarner Losh<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>.
75868e3e3a7aSWarner LoshThe constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different
75878e3e3a7aSWarner Loshfrom any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>.
75888e3e3a7aSWarner Losh
75898e3e3a7aSWarner Losh
75908e3e3a7aSWarner Losh
75918e3e3a7aSWarner Losh
75928e3e3a7aSWarner Losh
75938e3e3a7aSWarner Losh<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3>
75948e3e3a7aSWarner Losh<pre>typedef struct luaL_Reg {
75958e3e3a7aSWarner Losh  const char *name;
75968e3e3a7aSWarner Losh  lua_CFunction func;
75978e3e3a7aSWarner Losh} luaL_Reg;</pre>
75988e3e3a7aSWarner Losh
75998e3e3a7aSWarner Losh<p>
76008e3e3a7aSWarner LoshType for arrays of functions to be registered by
76018e3e3a7aSWarner Losh<a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>.
76028e3e3a7aSWarner Losh<code>name</code> is the function name and <code>func</code> is a pointer to
76038e3e3a7aSWarner Loshthe function.
76048e3e3a7aSWarner LoshAny array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry
76058e3e3a7aSWarner Loshin which both <code>name</code> and <code>func</code> are <code>NULL</code>.
76068e3e3a7aSWarner Losh
76078e3e3a7aSWarner Losh
76088e3e3a7aSWarner Losh
76098e3e3a7aSWarner Losh
76108e3e3a7aSWarner Losh
76118e3e3a7aSWarner Losh<hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p>
76128e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span>
76138e3e3a7aSWarner Losh<pre>void luaL_requiref (lua_State *L, const char *modname,
76148e3e3a7aSWarner Losh                    lua_CFunction openf, int glb);</pre>
76158e3e3a7aSWarner Losh
76168e3e3a7aSWarner Losh<p>
76170495ed39SKyle EvansIf <code>package.loaded[modname]</code> is not true,
76180495ed39SKyle Evanscalls the function <code>openf</code> with the string <code>modname</code> as an argument
76190495ed39SKyle Evansand sets the call result to <code>package.loaded[modname]</code>,
76208e3e3a7aSWarner Loshas if that function has been called through <a href="#pdf-require"><code>require</code></a>.
76218e3e3a7aSWarner Losh
76228e3e3a7aSWarner Losh
76238e3e3a7aSWarner Losh<p>
76248e3e3a7aSWarner LoshIf <code>glb</code> is true,
76250495ed39SKyle Evansalso stores the module into the global <code>modname</code>.
76268e3e3a7aSWarner Losh
76278e3e3a7aSWarner Losh
76288e3e3a7aSWarner Losh<p>
76298e3e3a7aSWarner LoshLeaves a copy of the module on the stack.
76308e3e3a7aSWarner Losh
76318e3e3a7aSWarner Losh
76328e3e3a7aSWarner Losh
76338e3e3a7aSWarner Losh
76348e3e3a7aSWarner Losh
76358e3e3a7aSWarner Losh<hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p>
76368e3e3a7aSWarner Losh<span class="apii">[-nup, +0, <em>m</em>]</span>
76378e3e3a7aSWarner Losh<pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre>
76388e3e3a7aSWarner Losh
76398e3e3a7aSWarner Losh<p>
76408e3e3a7aSWarner LoshRegisters all functions in the array <code>l</code>
76418e3e3a7aSWarner Losh(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack
76428e3e3a7aSWarner Losh(below optional upvalues, see next).
76438e3e3a7aSWarner Losh
76448e3e3a7aSWarner Losh
76458e3e3a7aSWarner Losh<p>
76468e3e3a7aSWarner LoshWhen <code>nup</code> is not zero,
76470495ed39SKyle Evansall functions are created with <code>nup</code> upvalues,
76480495ed39SKyle Evansinitialized with copies of the <code>nup</code> values
76490495ed39SKyle Evanspreviously pushed on the stack
76508e3e3a7aSWarner Loshon top of the library table.
76518e3e3a7aSWarner LoshThese values are popped from the stack after the registration.
76528e3e3a7aSWarner Losh
76538e3e3a7aSWarner Losh
76548c784bb8SWarner Losh<p>
76558c784bb8SWarner LoshA function with a <code>NULL</code> value represents a placeholder,
76568c784bb8SWarner Loshwhich is filled with <b>false</b>.
76578c784bb8SWarner Losh
76588c784bb8SWarner Losh
76598e3e3a7aSWarner Losh
76608e3e3a7aSWarner Losh
76618e3e3a7aSWarner Losh
76628e3e3a7aSWarner Losh<hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p>
76638e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
76648e3e3a7aSWarner Losh<pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre>
76658e3e3a7aSWarner Losh
76668e3e3a7aSWarner Losh<p>
76670495ed39SKyle EvansSets the metatable of the object on the top of the stack
76688e3e3a7aSWarner Loshas the metatable associated with name <code>tname</code>
76698e3e3a7aSWarner Loshin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
76708e3e3a7aSWarner Losh
76718e3e3a7aSWarner Losh
76728e3e3a7aSWarner Losh
76738e3e3a7aSWarner Losh
76748e3e3a7aSWarner Losh
76758e3e3a7aSWarner Losh<hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3>
76768e3e3a7aSWarner Losh<pre>typedef struct luaL_Stream {
76778e3e3a7aSWarner Losh  FILE *f;
76788e3e3a7aSWarner Losh  lua_CFunction closef;
76798e3e3a7aSWarner Losh} luaL_Stream;</pre>
76808e3e3a7aSWarner Losh
76818e3e3a7aSWarner Losh<p>
76820495ed39SKyle EvansThe standard representation for file handles
76830495ed39SKyle Evansused by the standard I/O library.
76848e3e3a7aSWarner Losh
76858e3e3a7aSWarner Losh
76868e3e3a7aSWarner Losh<p>
76878e3e3a7aSWarner LoshA file handle is implemented as a full userdata,
76888e3e3a7aSWarner Loshwith a metatable called <code>LUA_FILEHANDLE</code>
76898e3e3a7aSWarner Losh(where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name).
76908e3e3a7aSWarner LoshThe metatable is created by the I/O library
76918e3e3a7aSWarner Losh(see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
76928e3e3a7aSWarner Losh
76938e3e3a7aSWarner Losh
76948e3e3a7aSWarner Losh<p>
76958e3e3a7aSWarner LoshThis userdata must start with the structure <code>luaL_Stream</code>;
76968e3e3a7aSWarner Loshit can contain other data after this initial structure.
76970495ed39SKyle EvansThe field <code>f</code> points to the corresponding C stream
76988e3e3a7aSWarner Losh(or it can be <code>NULL</code> to indicate an incompletely created handle).
76990495ed39SKyle EvansThe field <code>closef</code> points to a Lua function
77008e3e3a7aSWarner Loshthat will be called to close the stream
77018e3e3a7aSWarner Loshwhen the handle is closed or collected;
77028e3e3a7aSWarner Loshthis function receives the file handle as its sole argument and
77030495ed39SKyle Evansmust return either a true value, in case of success,
77040495ed39SKyle Evansor a false value plus an error message, in case of error.
77058e3e3a7aSWarner LoshOnce Lua calls this field,
77068e3e3a7aSWarner Loshit changes the field value to <code>NULL</code>
77078e3e3a7aSWarner Loshto signal that the handle is closed.
77088e3e3a7aSWarner Losh
77098e3e3a7aSWarner Losh
77108e3e3a7aSWarner Losh
77118e3e3a7aSWarner Losh
77128e3e3a7aSWarner Losh
77138e3e3a7aSWarner Losh<hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p>
77148e3e3a7aSWarner Losh<span class="apii">[-0, +0, <em>m</em>]</span>
77158e3e3a7aSWarner Losh<pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre>
77168e3e3a7aSWarner Losh
77178e3e3a7aSWarner Losh<p>
77188e3e3a7aSWarner LoshThis function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>,
77198e3e3a7aSWarner Loshexcept that, when the test fails,
77208e3e3a7aSWarner Loshit returns <code>NULL</code> instead of raising an error.
77218e3e3a7aSWarner Losh
77228e3e3a7aSWarner Losh
77238e3e3a7aSWarner Losh
77248e3e3a7aSWarner Losh
77258e3e3a7aSWarner Losh
77268e3e3a7aSWarner Losh<hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p>
77278e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>e</em>]</span>
77288e3e3a7aSWarner Losh<pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre>
77298e3e3a7aSWarner Losh
77308e3e3a7aSWarner Losh<p>
77318e3e3a7aSWarner LoshConverts any Lua value at the given index to a C&nbsp;string
77328e3e3a7aSWarner Loshin a reasonable format.
77338e3e3a7aSWarner LoshThe resulting string is pushed onto the stack and also
77340495ed39SKyle Evansreturned by the function (see <a href="#4.1.3">&sect;4.1.3</a>).
77358e3e3a7aSWarner LoshIf <code>len</code> is not <code>NULL</code>,
77368e3e3a7aSWarner Loshthe function also sets <code>*len</code> with the string length.
77378e3e3a7aSWarner Losh
77388e3e3a7aSWarner Losh
77398e3e3a7aSWarner Losh<p>
77408e3e3a7aSWarner LoshIf the value has a metatable with a <code>__tostring</code> field,
77418e3e3a7aSWarner Loshthen <code>luaL_tolstring</code> calls the corresponding metamethod
77428e3e3a7aSWarner Loshwith the value as argument,
77438e3e3a7aSWarner Loshand uses the result of the call as its result.
77448e3e3a7aSWarner Losh
77458e3e3a7aSWarner Losh
77468e3e3a7aSWarner Losh
77478e3e3a7aSWarner Losh
77488e3e3a7aSWarner Losh
77498e3e3a7aSWarner Losh<hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p>
77508e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
77518e3e3a7aSWarner Losh<pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg,
77528e3e3a7aSWarner Losh                     int level);</pre>
77538e3e3a7aSWarner Losh
77548e3e3a7aSWarner Losh<p>
77558e3e3a7aSWarner LoshCreates and pushes a traceback of the stack <code>L1</code>.
77560495ed39SKyle EvansIf <code>msg</code> is not <code>NULL</code>, it is appended
77578e3e3a7aSWarner Loshat the beginning of the traceback.
77588e3e3a7aSWarner LoshThe <code>level</code> parameter tells at which level
77598e3e3a7aSWarner Loshto start the traceback.
77608e3e3a7aSWarner Losh
77618e3e3a7aSWarner Losh
77628e3e3a7aSWarner Losh
77638e3e3a7aSWarner Losh
77648e3e3a7aSWarner Losh
77650495ed39SKyle Evans<hr><h3><a name="luaL_typeerror"><code>luaL_typeerror</code></a></h3><p>
77660495ed39SKyle Evans<span class="apii">[-0, +0, <em>v</em>]</span>
7767*a9490b81SWarner Losh<pre>int luaL_typeerror (lua_State *L, int arg, const char *tname);</pre>
77680495ed39SKyle Evans
77690495ed39SKyle Evans<p>
77700495ed39SKyle EvansRaises a type error for the argument <code>arg</code>
77710495ed39SKyle Evansof the C&nbsp;function that called it,
77720495ed39SKyle Evansusing a standard message;
77730495ed39SKyle Evans<code>tname</code> is a "name" for the expected type.
77740495ed39SKyle EvansThis function never returns.
77750495ed39SKyle Evans
77760495ed39SKyle Evans
77770495ed39SKyle Evans
77780495ed39SKyle Evans
77790495ed39SKyle Evans
77808e3e3a7aSWarner Losh<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p>
77818e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
77828e3e3a7aSWarner Losh<pre>const char *luaL_typename (lua_State *L, int index);</pre>
77838e3e3a7aSWarner Losh
77848e3e3a7aSWarner Losh<p>
77858e3e3a7aSWarner LoshReturns the name of the type of the value at the given index.
77868e3e3a7aSWarner Losh
77878e3e3a7aSWarner Losh
77888e3e3a7aSWarner Losh
77898e3e3a7aSWarner Losh
77908e3e3a7aSWarner Losh
77918e3e3a7aSWarner Losh<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p>
77928e3e3a7aSWarner Losh<span class="apii">[-0, +0, &ndash;]</span>
77938e3e3a7aSWarner Losh<pre>void luaL_unref (lua_State *L, int t, int ref);</pre>
77948e3e3a7aSWarner Losh
77958e3e3a7aSWarner Losh<p>
77960495ed39SKyle EvansReleases the reference <code>ref</code> from the table at index <code>t</code>
77978e3e3a7aSWarner Losh(see <a href="#luaL_ref"><code>luaL_ref</code></a>).
77988e3e3a7aSWarner LoshThe entry is removed from the table,
77998e3e3a7aSWarner Loshso that the referred object can be collected.
78008e3e3a7aSWarner LoshThe reference <code>ref</code> is also freed to be used again.
78018e3e3a7aSWarner Losh
78028e3e3a7aSWarner Losh
78038e3e3a7aSWarner Losh<p>
78048e3e3a7aSWarner LoshIf <code>ref</code> is <a href="#pdf-LUA_NOREF"><code>LUA_NOREF</code></a> or <a href="#pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>,
78058e3e3a7aSWarner Losh<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing.
78068e3e3a7aSWarner Losh
78078e3e3a7aSWarner Losh
78088e3e3a7aSWarner Losh
78098e3e3a7aSWarner Losh
78108e3e3a7aSWarner Losh
78118e3e3a7aSWarner Losh<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p>
78128e3e3a7aSWarner Losh<span class="apii">[-0, +1, <em>m</em>]</span>
78138e3e3a7aSWarner Losh<pre>void luaL_where (lua_State *L, int lvl);</pre>
78148e3e3a7aSWarner Losh
78158e3e3a7aSWarner Losh<p>
78168e3e3a7aSWarner LoshPushes onto the stack a string identifying the current position
78178e3e3a7aSWarner Loshof the control at level <code>lvl</code> in the call stack.
78188e3e3a7aSWarner LoshTypically this string has the following format:
78198e3e3a7aSWarner Losh
78208e3e3a7aSWarner Losh<pre>
78218e3e3a7aSWarner Losh     <em>chunkname</em>:<em>currentline</em>:
78228e3e3a7aSWarner Losh</pre><p>
78238e3e3a7aSWarner LoshLevel&nbsp;0 is the running function,
78248e3e3a7aSWarner Loshlevel&nbsp;1 is the function that called the running function,
78258e3e3a7aSWarner Loshetc.
78268e3e3a7aSWarner Losh
78278e3e3a7aSWarner Losh
78288e3e3a7aSWarner Losh<p>
78298e3e3a7aSWarner LoshThis function is used to build a prefix for error messages.
78308e3e3a7aSWarner Losh
78318e3e3a7aSWarner Losh
78328e3e3a7aSWarner Losh
78338e3e3a7aSWarner Losh
78348e3e3a7aSWarner Losh
78358e3e3a7aSWarner Losh
78368e3e3a7aSWarner Losh
78370495ed39SKyle Evans<h1>6 &ndash; <a name="6">The Standard Libraries</a></h1>
78380495ed39SKyle Evans
78390495ed39SKyle Evans
78408e3e3a7aSWarner Losh
78418e3e3a7aSWarner Losh<p>
78428e3e3a7aSWarner LoshThe standard Lua libraries provide useful functions
78430495ed39SKyle Evansthat are implemented in&nbsp;C through the C&nbsp;API.
78448e3e3a7aSWarner LoshSome of these functions provide essential services to the language
78458e3e3a7aSWarner Losh(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>);
78460495ed39SKyle Evansothers provide access to outside services (e.g., I/O);
78478e3e3a7aSWarner Loshand others could be implemented in Lua itself,
78480495ed39SKyle Evansbut that for different reasons
78498e3e3a7aSWarner Loshdeserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>).
78508e3e3a7aSWarner Losh
78518e3e3a7aSWarner Losh
78528e3e3a7aSWarner Losh<p>
78538e3e3a7aSWarner LoshAll libraries are implemented through the official C&nbsp;API
78548e3e3a7aSWarner Loshand are provided as separate C&nbsp;modules.
78550495ed39SKyle EvansUnless otherwise noted,
78560495ed39SKyle Evansthese library functions do not adjust its number of arguments
78570495ed39SKyle Evansto its expected parameters.
78580495ed39SKyle EvansFor instance, a function documented as <code>foo(arg)</code>
78590495ed39SKyle Evansshould not be called without an argument.
78600495ed39SKyle Evans
78610495ed39SKyle Evans
78620495ed39SKyle Evans<p>
78630495ed39SKyle EvansThe notation <b>fail</b> means a false value representing
78640495ed39SKyle Evanssome kind of failure.
78650495ed39SKyle Evans(Currently, <b>fail</b> is equal to <b>nil</b>,
78660495ed39SKyle Evansbut that may change in future versions.
78670495ed39SKyle EvansThe recommendation is to always test the success of these functions
78680495ed39SKyle Evanswith <code>(not status)</code>, instead of <code>(status == nil)</code>.)
78690495ed39SKyle Evans
78700495ed39SKyle Evans
78710495ed39SKyle Evans<p>
78728e3e3a7aSWarner LoshCurrently, Lua has the following standard libraries:
78738e3e3a7aSWarner Losh
78748e3e3a7aSWarner Losh<ul>
78758e3e3a7aSWarner Losh
78768e3e3a7aSWarner Losh<li>basic library (<a href="#6.1">&sect;6.1</a>);</li>
78778e3e3a7aSWarner Losh
78788e3e3a7aSWarner Losh<li>coroutine library (<a href="#6.2">&sect;6.2</a>);</li>
78798e3e3a7aSWarner Losh
78808e3e3a7aSWarner Losh<li>package library (<a href="#6.3">&sect;6.3</a>);</li>
78818e3e3a7aSWarner Losh
78828e3e3a7aSWarner Losh<li>string manipulation (<a href="#6.4">&sect;6.4</a>);</li>
78838e3e3a7aSWarner Losh
78848e3e3a7aSWarner Losh<li>basic UTF-8 support (<a href="#6.5">&sect;6.5</a>);</li>
78858e3e3a7aSWarner Losh
78868e3e3a7aSWarner Losh<li>table manipulation (<a href="#6.6">&sect;6.6</a>);</li>
78878e3e3a7aSWarner Losh
78888e3e3a7aSWarner Losh<li>mathematical functions (<a href="#6.7">&sect;6.7</a>) (sin, log, etc.);</li>
78898e3e3a7aSWarner Losh
78908e3e3a7aSWarner Losh<li>input and output (<a href="#6.8">&sect;6.8</a>);</li>
78918e3e3a7aSWarner Losh
78928e3e3a7aSWarner Losh<li>operating system facilities (<a href="#6.9">&sect;6.9</a>);</li>
78938e3e3a7aSWarner Losh
78948e3e3a7aSWarner Losh<li>debug facilities (<a href="#6.10">&sect;6.10</a>).</li>
78958e3e3a7aSWarner Losh
78968e3e3a7aSWarner Losh</ul><p>
78978e3e3a7aSWarner LoshExcept for the basic and the package libraries,
78988e3e3a7aSWarner Losheach library provides all its functions as fields of a global table
78998e3e3a7aSWarner Loshor as methods of its objects.
79008e3e3a7aSWarner Losh
79018e3e3a7aSWarner Losh
79028e3e3a7aSWarner Losh<p>
79038e3e3a7aSWarner LoshTo have access to these libraries,
79048e3e3a7aSWarner Loshthe C&nbsp;host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function,
79058e3e3a7aSWarner Loshwhich opens all standard libraries.
79068e3e3a7aSWarner LoshAlternatively,
79078e3e3a7aSWarner Loshthe host program can open them individually by using
79088e3e3a7aSWarner Losh<a href="#luaL_requiref"><code>luaL_requiref</code></a> to call
79098e3e3a7aSWarner Losh<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library),
79108e3e3a7aSWarner Losh<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library),
79118e3e3a7aSWarner Losh<a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library),
79128e3e3a7aSWarner Losh<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library),
79130495ed39SKyle Evans<a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF-8 library),
79148e3e3a7aSWarner Losh<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library),
79158e3e3a7aSWarner Losh<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library),
79168e3e3a7aSWarner Losh<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library),
79178e3e3a7aSWarner Losh<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library),
79188e3e3a7aSWarner Loshand <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library).
79198e3e3a7aSWarner LoshThese functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>.
79208e3e3a7aSWarner Losh
79218e3e3a7aSWarner Losh
79228e3e3a7aSWarner Losh
79230495ed39SKyle Evans
79240495ed39SKyle Evans
79258e3e3a7aSWarner Losh<h2>6.1 &ndash; <a name="6.1">Basic Functions</a></h2>
79268e3e3a7aSWarner Losh
79278e3e3a7aSWarner Losh<p>
79288e3e3a7aSWarner LoshThe basic library provides core functions to Lua.
79298e3e3a7aSWarner LoshIf you do not include this library in your application,
79308e3e3a7aSWarner Loshyou should check carefully whether you need to provide
79318e3e3a7aSWarner Loshimplementations for some of its facilities.
79328e3e3a7aSWarner Losh
79338e3e3a7aSWarner Losh
79348e3e3a7aSWarner Losh<p>
79358e3e3a7aSWarner Losh<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3>
79368e3e3a7aSWarner Losh
79378e3e3a7aSWarner Losh
79388e3e3a7aSWarner Losh<p>
79390495ed39SKyle EvansRaises an error if
79408e3e3a7aSWarner Loshthe value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>);
79418e3e3a7aSWarner Loshotherwise, returns all its arguments.
79428e3e3a7aSWarner LoshIn case of error,
79438e3e3a7aSWarner Losh<code>message</code> is the error object;
79448e3e3a7aSWarner Loshwhen absent, it defaults to "<code>assertion failed!</code>"
79458e3e3a7aSWarner Losh
79468e3e3a7aSWarner Losh
79478e3e3a7aSWarner Losh
79488e3e3a7aSWarner Losh
79498e3e3a7aSWarner Losh<p>
79508e3e3a7aSWarner Losh<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3>
79518e3e3a7aSWarner Losh
79528e3e3a7aSWarner Losh
79538e3e3a7aSWarner Losh<p>
79548e3e3a7aSWarner LoshThis function is a generic interface to the garbage collector.
79558e3e3a7aSWarner LoshIt performs different functions according to its first argument, <code>opt</code>:
79568e3e3a7aSWarner Losh
79578e3e3a7aSWarner Losh<ul>
79588e3e3a7aSWarner Losh
79598e3e3a7aSWarner Losh<li><b>"<code>collect</code>": </b>
79600495ed39SKyle EvansPerforms a full garbage-collection cycle.
79618e3e3a7aSWarner LoshThis is the default option.
79628e3e3a7aSWarner Losh</li>
79638e3e3a7aSWarner Losh
79648e3e3a7aSWarner Losh<li><b>"<code>stop</code>": </b>
79650495ed39SKyle EvansStops automatic execution of the garbage collector.
79668e3e3a7aSWarner LoshThe collector will run only when explicitly invoked,
79678e3e3a7aSWarner Loshuntil a call to restart it.
79688e3e3a7aSWarner Losh</li>
79698e3e3a7aSWarner Losh
79708e3e3a7aSWarner Losh<li><b>"<code>restart</code>": </b>
79710495ed39SKyle EvansRestarts automatic execution of the garbage collector.
79728e3e3a7aSWarner Losh</li>
79738e3e3a7aSWarner Losh
79748e3e3a7aSWarner Losh<li><b>"<code>count</code>": </b>
79750495ed39SKyle EvansReturns the total memory in use by Lua in Kbytes.
79768e3e3a7aSWarner LoshThe value has a fractional part,
79778e3e3a7aSWarner Loshso that it multiplied by 1024
79780495ed39SKyle Evansgives the exact number of bytes in use by Lua.
79798e3e3a7aSWarner Losh</li>
79808e3e3a7aSWarner Losh
79818e3e3a7aSWarner Losh<li><b>"<code>step</code>": </b>
79820495ed39SKyle EvansPerforms a garbage-collection step.
79838e3e3a7aSWarner LoshThe step "size" is controlled by <code>arg</code>.
79848e3e3a7aSWarner LoshWith a zero value,
79858e3e3a7aSWarner Loshthe collector will perform one basic (indivisible) step.
79868e3e3a7aSWarner LoshFor non-zero values,
79878e3e3a7aSWarner Loshthe collector will perform as if that amount of memory
79880495ed39SKyle Evans(in Kbytes) had been allocated by Lua.
79898e3e3a7aSWarner LoshReturns <b>true</b> if the step finished a collection cycle.
79908e3e3a7aSWarner Losh</li>
79918e3e3a7aSWarner Losh
79928e3e3a7aSWarner Losh<li><b>"<code>isrunning</code>": </b>
79930495ed39SKyle EvansReturns a boolean that tells whether the collector is running
79948e3e3a7aSWarner Losh(i.e., not stopped).
79958e3e3a7aSWarner Losh</li>
79968e3e3a7aSWarner Losh
79970495ed39SKyle Evans<li><b>"<code>incremental</code>": </b>
79980495ed39SKyle EvansChange the collector mode to incremental.
79990495ed39SKyle EvansThis option can be followed by three numbers:
80000495ed39SKyle Evansthe garbage-collector pause,
80010495ed39SKyle Evansthe step multiplier,
80020495ed39SKyle Evansand the step size (see <a href="#2.5.1">&sect;2.5.1</a>).
80030495ed39SKyle EvansA zero means to not change that value.
80040495ed39SKyle Evans</li>
80050495ed39SKyle Evans
80060495ed39SKyle Evans<li><b>"<code>generational</code>": </b>
80070495ed39SKyle EvansChange the collector mode to generational.
80080495ed39SKyle EvansThis option can be followed by two numbers:
80090495ed39SKyle Evansthe garbage-collector minor multiplier
80100495ed39SKyle Evansand the major multiplier (see <a href="#2.5.2">&sect;2.5.2</a>).
80110495ed39SKyle EvansA zero means to not change that value.
80120495ed39SKyle Evans</li>
80130495ed39SKyle Evans
80140495ed39SKyle Evans</ul><p>
80150495ed39SKyle EvansSee <a href="#2.5">&sect;2.5</a> for more details about garbage collection
80160495ed39SKyle Evansand some of these options.
80170495ed39SKyle Evans
80188e3e3a7aSWarner Losh
80198c784bb8SWarner Losh<p>
80208c784bb8SWarner LoshThis function should not be called by a finalizer.
80218c784bb8SWarner Losh
80228c784bb8SWarner Losh
80238e3e3a7aSWarner Losh
80248e3e3a7aSWarner Losh
80258e3e3a7aSWarner Losh<p>
80268e3e3a7aSWarner Losh<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3>
80270495ed39SKyle EvansOpens the named file and executes its content as a Lua chunk.
80288e3e3a7aSWarner LoshWhen called without arguments,
80290495ed39SKyle Evans<code>dofile</code> executes the content of the standard input (<code>stdin</code>).
80308e3e3a7aSWarner LoshReturns all values returned by the chunk.
80318e3e3a7aSWarner LoshIn case of errors, <code>dofile</code> propagates the error
80320495ed39SKyle Evansto its caller.
80330495ed39SKyle Evans(That is, <code>dofile</code> does not run in protected mode.)
80348e3e3a7aSWarner Losh
80358e3e3a7aSWarner Losh
80368e3e3a7aSWarner Losh
80378e3e3a7aSWarner Losh
80388e3e3a7aSWarner Losh<p>
80398e3e3a7aSWarner Losh<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3>
80408c784bb8SWarner LoshRaises an error (see <a href="#2.3">&sect;2.3</a>) with <code>message</code> as the error object.
80410495ed39SKyle EvansThis function never returns.
80428e3e3a7aSWarner Losh
80438e3e3a7aSWarner Losh
80448e3e3a7aSWarner Losh<p>
80458e3e3a7aSWarner LoshUsually, <code>error</code> adds some information about the error position
80468e3e3a7aSWarner Loshat the beginning of the message, if the message is a string.
80478e3e3a7aSWarner LoshThe <code>level</code> argument specifies how to get the error position.
80488e3e3a7aSWarner LoshWith level&nbsp;1 (the default), the error position is where the
80498e3e3a7aSWarner Losh<code>error</code> function was called.
80508e3e3a7aSWarner LoshLevel&nbsp;2 points the error to where the function
80518e3e3a7aSWarner Loshthat called <code>error</code> was called; and so on.
80528e3e3a7aSWarner LoshPassing a level&nbsp;0 avoids the addition of error position information
80538e3e3a7aSWarner Loshto the message.
80548e3e3a7aSWarner Losh
80558e3e3a7aSWarner Losh
80568e3e3a7aSWarner Losh
80578e3e3a7aSWarner Losh
80588e3e3a7aSWarner Losh<p>
80598e3e3a7aSWarner Losh<hr><h3><a name="pdf-_G"><code>_G</code></a></h3>
80608e3e3a7aSWarner LoshA global variable (not a function) that
80618e3e3a7aSWarner Loshholds the global environment (see <a href="#2.2">&sect;2.2</a>).
80628e3e3a7aSWarner LoshLua itself does not use this variable;
80638e3e3a7aSWarner Loshchanging its value does not affect any environment,
80648e3e3a7aSWarner Loshnor vice versa.
80658e3e3a7aSWarner Losh
80668e3e3a7aSWarner Losh
80678e3e3a7aSWarner Losh
80688e3e3a7aSWarner Losh
80698e3e3a7aSWarner Losh<p>
80708e3e3a7aSWarner Losh<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3>
80718e3e3a7aSWarner Losh
80728e3e3a7aSWarner Losh
80738e3e3a7aSWarner Losh<p>
80748e3e3a7aSWarner LoshIf <code>object</code> does not have a metatable, returns <b>nil</b>.
80758e3e3a7aSWarner LoshOtherwise,
80768e3e3a7aSWarner Loshif the object's metatable has a <code>__metatable</code> field,
80778e3e3a7aSWarner Loshreturns the associated value.
80788e3e3a7aSWarner LoshOtherwise, returns the metatable of the given object.
80798e3e3a7aSWarner Losh
80808e3e3a7aSWarner Losh
80818e3e3a7aSWarner Losh
80828e3e3a7aSWarner Losh
80838e3e3a7aSWarner Losh<p>
80848e3e3a7aSWarner Losh<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3>
80858e3e3a7aSWarner Losh
80868e3e3a7aSWarner Losh
80878e3e3a7aSWarner Losh<p>
80888e3e3a7aSWarner LoshReturns three values (an iterator function, the table <code>t</code>, and 0)
80898e3e3a7aSWarner Loshso that the construction
80908e3e3a7aSWarner Losh
80918e3e3a7aSWarner Losh<pre>
80928e3e3a7aSWarner Losh     for i,v in ipairs(t) do <em>body</em> end
80938e3e3a7aSWarner Losh</pre><p>
80948e3e3a7aSWarner Loshwill iterate over the key&ndash;value pairs
80958e3e3a7aSWarner Losh(<code>1,t[1]</code>), (<code>2,t[2]</code>), ...,
80960495ed39SKyle Evansup to the first absent index.
80978e3e3a7aSWarner Losh
80988e3e3a7aSWarner Losh
80998e3e3a7aSWarner Losh
81008e3e3a7aSWarner Losh
81018e3e3a7aSWarner Losh<p>
81028e3e3a7aSWarner Losh<hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3>
81038e3e3a7aSWarner Losh
81048e3e3a7aSWarner Losh
81058e3e3a7aSWarner Losh<p>
81068e3e3a7aSWarner LoshLoads a chunk.
81078e3e3a7aSWarner Losh
81088e3e3a7aSWarner Losh
81098e3e3a7aSWarner Losh<p>
81108e3e3a7aSWarner LoshIf <code>chunk</code> is a string, the chunk is this string.
81118e3e3a7aSWarner LoshIf <code>chunk</code> is a function,
81128e3e3a7aSWarner Losh<code>load</code> calls it repeatedly to get the chunk pieces.
81138e3e3a7aSWarner LoshEach call to <code>chunk</code> must return a string that concatenates
81148e3e3a7aSWarner Loshwith previous results.
81158e3e3a7aSWarner LoshA return of an empty string, <b>nil</b>, or no value signals the end of the chunk.
81168e3e3a7aSWarner Losh
81178e3e3a7aSWarner Losh
81188e3e3a7aSWarner Losh<p>
81198e3e3a7aSWarner LoshIf there are no syntactic errors,
81200495ed39SKyle Evans<code>load</code> returns the compiled chunk as a function;
81210495ed39SKyle Evansotherwise, it returns <b>fail</b> plus the error message.
81228e3e3a7aSWarner Losh
81238e3e3a7aSWarner Losh
81248e3e3a7aSWarner Losh<p>
81250495ed39SKyle EvansWhen you load a main chunk,
81268e3e3a7aSWarner Loshthe resulting function will always have exactly one upvalue,
81278e3e3a7aSWarner Loshthe <code>_ENV</code> variable (see <a href="#2.2">&sect;2.2</a>).
81288e3e3a7aSWarner LoshHowever,
81298e3e3a7aSWarner Loshwhen you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>),
81300495ed39SKyle Evansthe resulting function can have an arbitrary number of upvalues,
81310495ed39SKyle Evansand there is no guarantee that its first upvalue will be
81320495ed39SKyle Evansthe <code>_ENV</code> variable.
81330495ed39SKyle Evans(A non-main function may not even have an <code>_ENV</code> upvalue.)
81340495ed39SKyle Evans
81350495ed39SKyle Evans
81360495ed39SKyle Evans<p>
81370495ed39SKyle EvansRegardless, if the resulting function has any upvalues,
81380495ed39SKyle Evansits first upvalue is set to the value of <code>env</code>,
81390495ed39SKyle Evansif that parameter is given,
81400495ed39SKyle Evansor to the value of the global environment.
81410495ed39SKyle EvansOther upvalues are initialized with <b>nil</b>.
81428e3e3a7aSWarner LoshAll upvalues are fresh, that is,
81438e3e3a7aSWarner Loshthey are not shared with any other function.
81448e3e3a7aSWarner Losh
81458e3e3a7aSWarner Losh
81468e3e3a7aSWarner Losh<p>
81478e3e3a7aSWarner Losh<code>chunkname</code> is used as the name of the chunk for error messages
81480495ed39SKyle Evansand debug information (see <a href="#4.7">&sect;4.7</a>).
81498e3e3a7aSWarner LoshWhen absent,
81508e3e3a7aSWarner Loshit defaults to <code>chunk</code>, if <code>chunk</code> is a string,
81518e3e3a7aSWarner Loshor to "<code>=(load)</code>" otherwise.
81528e3e3a7aSWarner Losh
81538e3e3a7aSWarner Losh
81548e3e3a7aSWarner Losh<p>
81558e3e3a7aSWarner LoshThe string <code>mode</code> controls whether the chunk can be text or binary
81568e3e3a7aSWarner Losh(that is, a precompiled chunk).
81578e3e3a7aSWarner LoshIt may be the string "<code>b</code>" (only binary chunks),
81588e3e3a7aSWarner Losh"<code>t</code>" (only text chunks),
81598e3e3a7aSWarner Loshor "<code>bt</code>" (both binary and text).
81608e3e3a7aSWarner LoshThe default is "<code>bt</code>".
81618e3e3a7aSWarner Losh
81628e3e3a7aSWarner Losh
81638e3e3a7aSWarner Losh<p>
81640495ed39SKyle EvansIt is safe to load malformed binary chunks;
81650495ed39SKyle Evans<code>load</code> signals an appropriate error.
81660495ed39SKyle EvansHowever,
81670495ed39SKyle EvansLua does not check the consistency of the code inside binary chunks;
81680495ed39SKyle Evansrunning maliciously crafted bytecode can crash the interpreter.
81698e3e3a7aSWarner Losh
81708e3e3a7aSWarner Losh
81718e3e3a7aSWarner Losh
81728e3e3a7aSWarner Losh
81738e3e3a7aSWarner Losh<p>
81748e3e3a7aSWarner Losh<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3>
81758e3e3a7aSWarner Losh
81768e3e3a7aSWarner Losh
81778e3e3a7aSWarner Losh<p>
81788e3e3a7aSWarner LoshSimilar to <a href="#pdf-load"><code>load</code></a>,
81798e3e3a7aSWarner Loshbut gets the chunk from file <code>filename</code>
81808e3e3a7aSWarner Loshor from the standard input,
81818e3e3a7aSWarner Loshif no file name is given.
81828e3e3a7aSWarner Losh
81838e3e3a7aSWarner Losh
81848e3e3a7aSWarner Losh
81858e3e3a7aSWarner Losh
81868e3e3a7aSWarner Losh<p>
81878e3e3a7aSWarner Losh<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3>
81888e3e3a7aSWarner Losh
81898e3e3a7aSWarner Losh
81908e3e3a7aSWarner Losh<p>
81918e3e3a7aSWarner LoshAllows a program to traverse all fields of a table.
81928e3e3a7aSWarner LoshIts first argument is a table and its second argument
81938e3e3a7aSWarner Loshis an index in this table.
81940495ed39SKyle EvansA call to <code>next</code> returns the next index of the table
81958e3e3a7aSWarner Loshand its associated value.
81968e3e3a7aSWarner LoshWhen called with <b>nil</b> as its second argument,
81978e3e3a7aSWarner Losh<code>next</code> returns an initial index
81988e3e3a7aSWarner Loshand its associated value.
81998e3e3a7aSWarner LoshWhen called with the last index,
82008e3e3a7aSWarner Loshor with <b>nil</b> in an empty table,
82018e3e3a7aSWarner Losh<code>next</code> returns <b>nil</b>.
82028e3e3a7aSWarner LoshIf the second argument is absent, then it is interpreted as <b>nil</b>.
82038e3e3a7aSWarner LoshIn particular,
82048e3e3a7aSWarner Loshyou can use <code>next(t)</code> to check whether a table is empty.
82058e3e3a7aSWarner Losh
82068e3e3a7aSWarner Losh
82078e3e3a7aSWarner Losh<p>
82088e3e3a7aSWarner LoshThe order in which the indices are enumerated is not specified,
82098e3e3a7aSWarner Losh<em>even for numeric indices</em>.
82108e3e3a7aSWarner Losh(To traverse a table in numerical order,
82118e3e3a7aSWarner Loshuse a numerical <b>for</b>.)
82128e3e3a7aSWarner Losh
82138e3e3a7aSWarner Losh
82148e3e3a7aSWarner Losh<p>
82158c784bb8SWarner LoshYou should not assign any value to a non-existent field in a table
82168c784bb8SWarner Loshduring its traversal.
82178e3e3a7aSWarner LoshYou may however modify existing fields.
82180495ed39SKyle EvansIn particular, you may set existing fields to nil.
82198e3e3a7aSWarner Losh
82208e3e3a7aSWarner Losh
82218e3e3a7aSWarner Losh
82228e3e3a7aSWarner Losh
82238e3e3a7aSWarner Losh<p>
82248e3e3a7aSWarner Losh<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3>
82258e3e3a7aSWarner Losh
82268e3e3a7aSWarner Losh
82278e3e3a7aSWarner Losh<p>
82288e3e3a7aSWarner LoshIf <code>t</code> has a metamethod <code>__pairs</code>,
82298e3e3a7aSWarner Loshcalls it with <code>t</code> as argument and returns the first three
82308e3e3a7aSWarner Loshresults from the call.
82318e3e3a7aSWarner Losh
82328e3e3a7aSWarner Losh
82338e3e3a7aSWarner Losh<p>
82348e3e3a7aSWarner LoshOtherwise,
82358e3e3a7aSWarner Loshreturns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>,
82368e3e3a7aSWarner Loshso that the construction
82378e3e3a7aSWarner Losh
82388e3e3a7aSWarner Losh<pre>
82398e3e3a7aSWarner Losh     for k,v in pairs(t) do <em>body</em> end
82408e3e3a7aSWarner Losh</pre><p>
82418e3e3a7aSWarner Loshwill iterate over all key&ndash;value pairs of table <code>t</code>.
82428e3e3a7aSWarner Losh
82438e3e3a7aSWarner Losh
82448e3e3a7aSWarner Losh<p>
82458e3e3a7aSWarner LoshSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
82468e3e3a7aSWarner Loshthe table during its traversal.
82478e3e3a7aSWarner Losh
82488e3e3a7aSWarner Losh
82498e3e3a7aSWarner Losh
82508e3e3a7aSWarner Losh
82518e3e3a7aSWarner Losh<p>
82528e3e3a7aSWarner Losh<hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, &middot;&middot;&middot;])</code></a></h3>
82538e3e3a7aSWarner Losh
82548e3e3a7aSWarner Losh
82558e3e3a7aSWarner Losh<p>
82560495ed39SKyle EvansCalls the function <code>f</code> with
82578e3e3a7aSWarner Loshthe given arguments in <em>protected mode</em>.
82588e3e3a7aSWarner LoshThis means that any error inside&nbsp;<code>f</code> is not propagated;
82598e3e3a7aSWarner Loshinstead, <code>pcall</code> catches the error
82608e3e3a7aSWarner Loshand returns a status code.
82618e3e3a7aSWarner LoshIts first result is the status code (a boolean),
82628c784bb8SWarner Loshwhich is <b>true</b> if the call succeeds without errors.
82638e3e3a7aSWarner LoshIn such case, <code>pcall</code> also returns all results from the call,
82648e3e3a7aSWarner Loshafter this first result.
82650495ed39SKyle EvansIn case of any error, <code>pcall</code> returns <b>false</b> plus the error object.
82660495ed39SKyle EvansNote that errors caught by <code>pcall</code> do not call a message handler.
82678e3e3a7aSWarner Losh
82688e3e3a7aSWarner Losh
82698e3e3a7aSWarner Losh
82708e3e3a7aSWarner Losh
82718e3e3a7aSWarner Losh<p>
82728e3e3a7aSWarner Losh<hr><h3><a name="pdf-print"><code>print (&middot;&middot;&middot;)</code></a></h3>
82738e3e3a7aSWarner LoshReceives any number of arguments
82748e3e3a7aSWarner Loshand prints their values to <code>stdout</code>,
82750495ed39SKyle Evansconverting each argument to a string
82760495ed39SKyle Evansfollowing the same rules of <a href="#pdf-tostring"><code>tostring</code></a>.
82770495ed39SKyle Evans
82780495ed39SKyle Evans
82790495ed39SKyle Evans<p>
82800495ed39SKyle EvansThe function <code>print</code> is not intended for formatted output,
82818e3e3a7aSWarner Loshbut only as a quick way to show a value,
82828e3e3a7aSWarner Loshfor instance for debugging.
82838e3e3a7aSWarner LoshFor complete control over the output,
82848e3e3a7aSWarner Loshuse <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>.
82858e3e3a7aSWarner Losh
82868e3e3a7aSWarner Losh
82878e3e3a7aSWarner Losh
82888e3e3a7aSWarner Losh
82898e3e3a7aSWarner Losh<p>
82908e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3>
82918e3e3a7aSWarner LoshChecks whether <code>v1</code> is equal to <code>v2</code>,
82928e3e3a7aSWarner Loshwithout invoking the <code>__eq</code> metamethod.
82938e3e3a7aSWarner LoshReturns a boolean.
82948e3e3a7aSWarner Losh
82958e3e3a7aSWarner Losh
82968e3e3a7aSWarner Losh
82978e3e3a7aSWarner Losh
82988e3e3a7aSWarner Losh<p>
82998e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3>
83008e3e3a7aSWarner LoshGets the real value of <code>table[index]</code>,
83010495ed39SKyle Evanswithout using the <code>__index</code> metavalue.
83028e3e3a7aSWarner Losh<code>table</code> must be a table;
83038e3e3a7aSWarner Losh<code>index</code> may be any value.
83048e3e3a7aSWarner Losh
83058e3e3a7aSWarner Losh
83068e3e3a7aSWarner Losh
83078e3e3a7aSWarner Losh
83088e3e3a7aSWarner Losh<p>
83098e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3>
83108e3e3a7aSWarner LoshReturns the length of the object <code>v</code>,
83118e3e3a7aSWarner Loshwhich must be a table or a string,
83128e3e3a7aSWarner Loshwithout invoking the <code>__len</code> metamethod.
83138e3e3a7aSWarner LoshReturns an integer.
83148e3e3a7aSWarner Losh
83158e3e3a7aSWarner Losh
83168e3e3a7aSWarner Losh
83178e3e3a7aSWarner Losh
83188e3e3a7aSWarner Losh<p>
83198e3e3a7aSWarner Losh<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3>
83208e3e3a7aSWarner LoshSets the real value of <code>table[index]</code> to <code>value</code>,
83210495ed39SKyle Evanswithout using the <code>__newindex</code> metavalue.
83228e3e3a7aSWarner Losh<code>table</code> must be a table,
83238e3e3a7aSWarner Losh<code>index</code> any value different from <b>nil</b> and NaN,
83248e3e3a7aSWarner Loshand <code>value</code> any Lua value.
83258e3e3a7aSWarner Losh
83268e3e3a7aSWarner Losh
83278e3e3a7aSWarner Losh<p>
83288e3e3a7aSWarner LoshThis function returns <code>table</code>.
83298e3e3a7aSWarner Losh
83308e3e3a7aSWarner Losh
83318e3e3a7aSWarner Losh
83328e3e3a7aSWarner Losh
83338e3e3a7aSWarner Losh<p>
83348e3e3a7aSWarner Losh<hr><h3><a name="pdf-select"><code>select (index, &middot;&middot;&middot;)</code></a></h3>
83358e3e3a7aSWarner Losh
83368e3e3a7aSWarner Losh
83378e3e3a7aSWarner Losh<p>
83388e3e3a7aSWarner LoshIf <code>index</code> is a number,
83398e3e3a7aSWarner Loshreturns all arguments after argument number <code>index</code>;
83408e3e3a7aSWarner Losha negative number indexes from the end (-1 is the last argument).
83418e3e3a7aSWarner LoshOtherwise, <code>index</code> must be the string <code>"#"</code>,
83428e3e3a7aSWarner Loshand <code>select</code> returns the total number of extra arguments it received.
83438e3e3a7aSWarner Losh
83448e3e3a7aSWarner Losh
83458e3e3a7aSWarner Losh
83468e3e3a7aSWarner Losh
83478e3e3a7aSWarner Losh<p>
83488e3e3a7aSWarner Losh<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3>
83498e3e3a7aSWarner Losh
83508e3e3a7aSWarner Losh
83518e3e3a7aSWarner Losh<p>
83528e3e3a7aSWarner LoshSets the metatable for the given table.
83538e3e3a7aSWarner LoshIf <code>metatable</code> is <b>nil</b>,
83548e3e3a7aSWarner Loshremoves the metatable of the given table.
83558e3e3a7aSWarner LoshIf the original metatable has a <code>__metatable</code> field,
83568e3e3a7aSWarner Loshraises an error.
83578e3e3a7aSWarner Losh
83588e3e3a7aSWarner Losh
83598e3e3a7aSWarner Losh<p>
83608e3e3a7aSWarner LoshThis function returns <code>table</code>.
83618e3e3a7aSWarner Losh
83628e3e3a7aSWarner Losh
83630495ed39SKyle Evans<p>
83640495ed39SKyle EvansTo change the metatable of other types from Lua code,
83650495ed39SKyle Evansyou must use the debug library (<a href="#6.10">&sect;6.10</a>).
83660495ed39SKyle Evans
83670495ed39SKyle Evans
83688e3e3a7aSWarner Losh
83698e3e3a7aSWarner Losh
83708e3e3a7aSWarner Losh<p>
83718e3e3a7aSWarner Losh<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3>
83728e3e3a7aSWarner Losh
83738e3e3a7aSWarner Losh
83748e3e3a7aSWarner Losh<p>
83758e3e3a7aSWarner LoshWhen called with no <code>base</code>,
83768e3e3a7aSWarner Losh<code>tonumber</code> tries to convert its argument to a number.
83778e3e3a7aSWarner LoshIf the argument is already a number or
83788e3e3a7aSWarner Losha string convertible to a number,
83798e3e3a7aSWarner Loshthen <code>tonumber</code> returns this number;
83800495ed39SKyle Evansotherwise, it returns <b>fail</b>.
83818e3e3a7aSWarner Losh
83828e3e3a7aSWarner Losh
83838e3e3a7aSWarner Losh<p>
83848e3e3a7aSWarner LoshThe conversion of strings can result in integers or floats,
83858e3e3a7aSWarner Loshaccording to the lexical conventions of Lua (see <a href="#3.1">&sect;3.1</a>).
83860495ed39SKyle EvansThe string may have leading and trailing spaces and a sign.
83878e3e3a7aSWarner Losh
83888e3e3a7aSWarner Losh
83898e3e3a7aSWarner Losh<p>
83908e3e3a7aSWarner LoshWhen called with <code>base</code>,
83918e3e3a7aSWarner Loshthen <code>e</code> must be a string to be interpreted as
83928e3e3a7aSWarner Loshan integer numeral in that base.
83938e3e3a7aSWarner LoshThe base may be any integer between 2 and 36, inclusive.
83948e3e3a7aSWarner LoshIn bases above&nbsp;10, the letter '<code>A</code>' (in either upper or lower case)
83958e3e3a7aSWarner Loshrepresents&nbsp;10, '<code>B</code>' represents&nbsp;11, and so forth,
83968e3e3a7aSWarner Loshwith '<code>Z</code>' representing 35.
83978e3e3a7aSWarner LoshIf the string <code>e</code> is not a valid numeral in the given base,
83980495ed39SKyle Evansthe function returns <b>fail</b>.
83998e3e3a7aSWarner Losh
84008e3e3a7aSWarner Losh
84018e3e3a7aSWarner Losh
84028e3e3a7aSWarner Losh
84038e3e3a7aSWarner Losh<p>
84048e3e3a7aSWarner Losh<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3>
84050495ed39SKyle Evans
84060495ed39SKyle Evans
84070495ed39SKyle Evans<p>
84088e3e3a7aSWarner LoshReceives a value of any type and
84098e3e3a7aSWarner Loshconverts it to a string in a human-readable format.
84108e3e3a7aSWarner Losh
84118e3e3a7aSWarner Losh
84128e3e3a7aSWarner Losh<p>
84138e3e3a7aSWarner LoshIf the metatable of <code>v</code> has a <code>__tostring</code> field,
84148e3e3a7aSWarner Loshthen <code>tostring</code> calls the corresponding value
84158e3e3a7aSWarner Loshwith <code>v</code> as argument,
84168e3e3a7aSWarner Loshand uses the result of the call as its result.
84170495ed39SKyle EvansOtherwise, if the metatable of <code>v</code> has a <code>__name</code> field
84180495ed39SKyle Evanswith a string value,
84190495ed39SKyle Evans<code>tostring</code> may use that string in its final result.
84200495ed39SKyle Evans
84210495ed39SKyle Evans
84220495ed39SKyle Evans<p>
84230495ed39SKyle EvansFor complete control of how numbers are converted,
84240495ed39SKyle Evansuse <a href="#pdf-string.format"><code>string.format</code></a>.
84258e3e3a7aSWarner Losh
84268e3e3a7aSWarner Losh
84278e3e3a7aSWarner Losh
84288e3e3a7aSWarner Losh
84298e3e3a7aSWarner Losh<p>
84308e3e3a7aSWarner Losh<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3>
84310495ed39SKyle Evans
84320495ed39SKyle Evans
84330495ed39SKyle Evans<p>
84348e3e3a7aSWarner LoshReturns the type of its only argument, coded as a string.
84358e3e3a7aSWarner LoshThe possible results of this function are
84368e3e3a7aSWarner Losh"<code>nil</code>" (a string, not the value <b>nil</b>),
84378e3e3a7aSWarner Losh"<code>number</code>",
84388e3e3a7aSWarner Losh"<code>string</code>",
84398e3e3a7aSWarner Losh"<code>boolean</code>",
84408e3e3a7aSWarner Losh"<code>table</code>",
84418e3e3a7aSWarner Losh"<code>function</code>",
84428e3e3a7aSWarner Losh"<code>thread</code>",
84438e3e3a7aSWarner Loshand "<code>userdata</code>".
84448e3e3a7aSWarner Losh
84458e3e3a7aSWarner Losh
84468e3e3a7aSWarner Losh
84478e3e3a7aSWarner Losh
84488e3e3a7aSWarner Losh<p>
84498e3e3a7aSWarner Losh<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3>
84508e3e3a7aSWarner Losh
84518e3e3a7aSWarner Losh
84528e3e3a7aSWarner Losh<p>
84538e3e3a7aSWarner LoshA global variable (not a function) that
84548e3e3a7aSWarner Loshholds a string containing the running Lua version.
84550495ed39SKyle EvansThe current value of this variable is "<code>Lua 5.4</code>".
84560495ed39SKyle Evans
84570495ed39SKyle Evans
84580495ed39SKyle Evans
84590495ed39SKyle Evans
84600495ed39SKyle Evans<p>
84610495ed39SKyle Evans<hr><h3><a name="pdf-warn"><code>warn (msg1, &middot;&middot;&middot;)</code></a></h3>
84620495ed39SKyle Evans
84630495ed39SKyle Evans
84640495ed39SKyle Evans<p>
84650495ed39SKyle EvansEmits a warning with a message composed by the concatenation
84660495ed39SKyle Evansof all its arguments (which should be strings).
84670495ed39SKyle Evans
84680495ed39SKyle Evans
84690495ed39SKyle Evans<p>
84700495ed39SKyle EvansBy convention,
84710495ed39SKyle Evansa one-piece message starting with '<code>@</code>'
84720495ed39SKyle Evansis intended to be a <em>control message</em>,
84730495ed39SKyle Evanswhich is a message to the warning system itself.
84740495ed39SKyle EvansIn particular, the standard warning function in Lua
84750495ed39SKyle Evansrecognizes the control messages "<code>@off</code>",
84760495ed39SKyle Evansto stop the emission of warnings,
84770495ed39SKyle Evansand "<code>@on</code>", to (re)start the emission;
84780495ed39SKyle Evansit ignores unknown control messages.
84798e3e3a7aSWarner Losh
84808e3e3a7aSWarner Losh
84818e3e3a7aSWarner Losh
84828e3e3a7aSWarner Losh
84838e3e3a7aSWarner Losh<p>
84848e3e3a7aSWarner Losh<hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, &middot;&middot;&middot;])</code></a></h3>
84858e3e3a7aSWarner Losh
84868e3e3a7aSWarner Losh
84878e3e3a7aSWarner Losh<p>
84888e3e3a7aSWarner LoshThis function is similar to <a href="#pdf-pcall"><code>pcall</code></a>,
84898e3e3a7aSWarner Loshexcept that it sets a new message handler <code>msgh</code>.
84908e3e3a7aSWarner Losh
84918e3e3a7aSWarner Losh
84928e3e3a7aSWarner Losh
84938e3e3a7aSWarner Losh
84948e3e3a7aSWarner Losh
84958e3e3a7aSWarner Losh
84968e3e3a7aSWarner Losh
84978e3e3a7aSWarner Losh<h2>6.2 &ndash; <a name="6.2">Coroutine Manipulation</a></h2>
84988e3e3a7aSWarner Losh
84998e3e3a7aSWarner Losh<p>
85008e3e3a7aSWarner LoshThis library comprises the operations to manipulate coroutines,
85018e3e3a7aSWarner Loshwhich come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>.
85028e3e3a7aSWarner LoshSee <a href="#2.6">&sect;2.6</a> for a general description of coroutines.
85038e3e3a7aSWarner Losh
85048e3e3a7aSWarner Losh
85058e3e3a7aSWarner Losh<p>
85060495ed39SKyle Evans<hr><h3><a name="pdf-coroutine.close"><code>coroutine.close (co)</code></a></h3>
85070495ed39SKyle Evans
85080495ed39SKyle Evans
85090495ed39SKyle Evans<p>
85100495ed39SKyle EvansCloses coroutine <code>co</code>,
85110495ed39SKyle Evansthat is,
85120495ed39SKyle Evanscloses all its pending to-be-closed variables
85130495ed39SKyle Evansand puts the coroutine in a dead state.
85140495ed39SKyle EvansThe given coroutine must be dead or suspended.
85158c784bb8SWarner LoshIn case of error
85168c784bb8SWarner Losh(either the original error that stopped the coroutine or
85178c784bb8SWarner Losherrors in closing methods),
85180495ed39SKyle Evansreturns <b>false</b> plus the error object;
85190495ed39SKyle Evansotherwise returns <b>true</b>.
85200495ed39SKyle Evans
85210495ed39SKyle Evans
85220495ed39SKyle Evans
85230495ed39SKyle Evans
85240495ed39SKyle Evans<p>
85258e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3>
85268e3e3a7aSWarner Losh
85278e3e3a7aSWarner Losh
85288e3e3a7aSWarner Losh<p>
85298e3e3a7aSWarner LoshCreates a new coroutine, with body <code>f</code>.
85308e3e3a7aSWarner Losh<code>f</code> must be a function.
85318e3e3a7aSWarner LoshReturns this new coroutine,
85328e3e3a7aSWarner Loshan object with type <code>"thread"</code>.
85338e3e3a7aSWarner Losh
85348e3e3a7aSWarner Losh
85358e3e3a7aSWarner Losh
85368e3e3a7aSWarner Losh
85378e3e3a7aSWarner Losh<p>
85380495ed39SKyle Evans<hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ([co])</code></a></h3>
85398e3e3a7aSWarner Losh
85408e3e3a7aSWarner Losh
85418e3e3a7aSWarner Losh<p>
85428c784bb8SWarner LoshReturns <b>true</b> when the coroutine <code>co</code> can yield.
85430495ed39SKyle EvansThe default for <code>co</code> is the running coroutine.
85448e3e3a7aSWarner Losh
85458e3e3a7aSWarner Losh
85468e3e3a7aSWarner Losh<p>
85470495ed39SKyle EvansA coroutine is yieldable if it is not the main thread and
85488e3e3a7aSWarner Loshit is not inside a non-yieldable C&nbsp;function.
85498e3e3a7aSWarner Losh
85508e3e3a7aSWarner Losh
85518e3e3a7aSWarner Losh
85528e3e3a7aSWarner Losh
85538e3e3a7aSWarner Losh<p>
85548e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, &middot;&middot;&middot;])</code></a></h3>
85558e3e3a7aSWarner Losh
85568e3e3a7aSWarner Losh
85578e3e3a7aSWarner Losh<p>
85588e3e3a7aSWarner LoshStarts or continues the execution of coroutine <code>co</code>.
85598e3e3a7aSWarner LoshThe first time you resume a coroutine,
85608e3e3a7aSWarner Loshit starts running its body.
85618e3e3a7aSWarner LoshThe values <code>val1</code>, ... are passed
85628e3e3a7aSWarner Loshas the arguments to the body function.
85638e3e3a7aSWarner LoshIf the coroutine has yielded,
85648e3e3a7aSWarner Losh<code>resume</code> restarts it;
85658e3e3a7aSWarner Loshthe values <code>val1</code>, ... are passed
85668e3e3a7aSWarner Loshas the results from the yield.
85678e3e3a7aSWarner Losh
85688e3e3a7aSWarner Losh
85698e3e3a7aSWarner Losh<p>
85708e3e3a7aSWarner LoshIf the coroutine runs without any errors,
85718e3e3a7aSWarner Losh<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code>
85728e3e3a7aSWarner Losh(when the coroutine yields) or any values returned by the body function
85738e3e3a7aSWarner Losh(when the coroutine terminates).
85748e3e3a7aSWarner LoshIf there is any error,
85758e3e3a7aSWarner Losh<code>resume</code> returns <b>false</b> plus the error message.
85768e3e3a7aSWarner Losh
85778e3e3a7aSWarner Losh
85788e3e3a7aSWarner Losh
85798e3e3a7aSWarner Losh
85808e3e3a7aSWarner Losh<p>
85818e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3>
85828e3e3a7aSWarner Losh
85838e3e3a7aSWarner Losh
85848e3e3a7aSWarner Losh<p>
85858e3e3a7aSWarner LoshReturns the running coroutine plus a boolean,
85868c784bb8SWarner Losh<b>true</b> when the running coroutine is the main one.
85878e3e3a7aSWarner Losh
85888e3e3a7aSWarner Losh
85898e3e3a7aSWarner Losh
85908e3e3a7aSWarner Losh
85918e3e3a7aSWarner Losh<p>
85928e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3>
85938e3e3a7aSWarner Losh
85948e3e3a7aSWarner Losh
85958e3e3a7aSWarner Losh<p>
85960495ed39SKyle EvansReturns the status of the coroutine <code>co</code>, as a string:
85978e3e3a7aSWarner Losh<code>"running"</code>,
85980495ed39SKyle Evansif the coroutine is running
85990495ed39SKyle Evans(that is, it is the one that called <code>status</code>);
86008e3e3a7aSWarner Losh<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>,
86018e3e3a7aSWarner Loshor if it has not started running yet;
86028e3e3a7aSWarner Losh<code>"normal"</code> if the coroutine is active but not running
86038e3e3a7aSWarner Losh(that is, it has resumed another coroutine);
86048e3e3a7aSWarner Loshand <code>"dead"</code> if the coroutine has finished its body function,
86058e3e3a7aSWarner Loshor if it has stopped with an error.
86068e3e3a7aSWarner Losh
86078e3e3a7aSWarner Losh
86088e3e3a7aSWarner Losh
86098e3e3a7aSWarner Losh
86108e3e3a7aSWarner Losh<p>
86118e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3>
86128e3e3a7aSWarner Losh
86138e3e3a7aSWarner Losh
86148e3e3a7aSWarner Losh<p>
86150495ed39SKyle EvansCreates a new coroutine, with body <code>f</code>;
86168e3e3a7aSWarner Losh<code>f</code> must be a function.
86178e3e3a7aSWarner LoshReturns a function that resumes the coroutine each time it is called.
86180495ed39SKyle EvansAny arguments passed to this function behave as the
86198e3e3a7aSWarner Loshextra arguments to <code>resume</code>.
86200495ed39SKyle EvansThe function returns the same values returned by <code>resume</code>,
86218e3e3a7aSWarner Loshexcept the first boolean.
86220495ed39SKyle EvansIn case of error,
86230495ed39SKyle Evansthe function closes the coroutine and propagates the error.
86248e3e3a7aSWarner Losh
86258e3e3a7aSWarner Losh
86268e3e3a7aSWarner Losh
86278e3e3a7aSWarner Losh
86288e3e3a7aSWarner Losh<p>
86298e3e3a7aSWarner Losh<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (&middot;&middot;&middot;)</code></a></h3>
86308e3e3a7aSWarner Losh
86318e3e3a7aSWarner Losh
86328e3e3a7aSWarner Losh<p>
86338e3e3a7aSWarner LoshSuspends the execution of the calling coroutine.
86348e3e3a7aSWarner LoshAny arguments to <code>yield</code> are passed as extra results to <code>resume</code>.
86358e3e3a7aSWarner Losh
86368e3e3a7aSWarner Losh
86378e3e3a7aSWarner Losh
86388e3e3a7aSWarner Losh
86398e3e3a7aSWarner Losh
86408e3e3a7aSWarner Losh
86418e3e3a7aSWarner Losh
86428e3e3a7aSWarner Losh<h2>6.3 &ndash; <a name="6.3">Modules</a></h2>
86438e3e3a7aSWarner Losh
86448e3e3a7aSWarner Losh<p>
86458e3e3a7aSWarner LoshThe package library provides basic
86468e3e3a7aSWarner Loshfacilities for loading modules in Lua.
86478e3e3a7aSWarner LoshIt exports one function directly in the global environment:
86488e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a>.
86490495ed39SKyle EvansEverything else is exported in the table <a name="pdf-package"><code>package</code></a>.
86508e3e3a7aSWarner Losh
86518e3e3a7aSWarner Losh
86528e3e3a7aSWarner Losh<p>
86538e3e3a7aSWarner Losh<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3>
86548e3e3a7aSWarner Losh
86558e3e3a7aSWarner Losh
86568e3e3a7aSWarner Losh<p>
86578e3e3a7aSWarner LoshLoads the given module.
86588e3e3a7aSWarner LoshThe function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table
86598e3e3a7aSWarner Loshto determine whether <code>modname</code> is already loaded.
86608e3e3a7aSWarner LoshIf it is, then <code>require</code> returns the value stored
86618e3e3a7aSWarner Loshat <code>package.loaded[modname]</code>.
86620495ed39SKyle Evans(The absence of a second result in this case
86630495ed39SKyle Evanssignals that this call did not have to load the module.)
86648e3e3a7aSWarner LoshOtherwise, it tries to find a <em>loader</em> for the module.
86658e3e3a7aSWarner Losh
86668e3e3a7aSWarner Losh
86678e3e3a7aSWarner Losh<p>
86688e3e3a7aSWarner LoshTo find a loader,
86690495ed39SKyle Evans<code>require</code> is guided by the table <a href="#pdf-package.searchers"><code>package.searchers</code></a>.
86700495ed39SKyle EvansEach item in this table is a search function,
86710495ed39SKyle Evansthat searches for the module in a particular way.
86720495ed39SKyle EvansBy changing this table,
86738e3e3a7aSWarner Loshwe can change how <code>require</code> looks for a module.
86748e3e3a7aSWarner LoshThe following explanation is based on the default configuration
86758e3e3a7aSWarner Loshfor <a href="#pdf-package.searchers"><code>package.searchers</code></a>.
86768e3e3a7aSWarner Losh
86778e3e3a7aSWarner Losh
86788e3e3a7aSWarner Losh<p>
86798e3e3a7aSWarner LoshFirst <code>require</code> queries <code>package.preload[modname]</code>.
86808e3e3a7aSWarner LoshIf it has a value,
86818e3e3a7aSWarner Loshthis value (which must be a function) is the loader.
86828e3e3a7aSWarner LoshOtherwise <code>require</code> searches for a Lua loader using the
86838e3e3a7aSWarner Loshpath stored in <a href="#pdf-package.path"><code>package.path</code></a>.
86848e3e3a7aSWarner LoshIf that also fails, it searches for a C&nbsp;loader using the
86858e3e3a7aSWarner Loshpath stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
86868e3e3a7aSWarner LoshIf that also fails,
86878e3e3a7aSWarner Loshit tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>).
86888e3e3a7aSWarner Losh
86898e3e3a7aSWarner Losh
86908e3e3a7aSWarner Losh<p>
86918e3e3a7aSWarner LoshOnce a loader is found,
86928e3e3a7aSWarner Losh<code>require</code> calls the loader with two arguments:
86930495ed39SKyle Evans<code>modname</code> and an extra value,
86940495ed39SKyle Evansa <em>loader data</em>,
86950495ed39SKyle Evansalso returned by the searcher.
86960495ed39SKyle EvansThe loader data can be any value useful to the module;
86970495ed39SKyle Evansfor the default searchers,
86980495ed39SKyle Evansit indicates where the loader was found.
86990495ed39SKyle Evans(For instance, if the loader came from a file,
87000495ed39SKyle Evansthis extra value is the file path.)
87018e3e3a7aSWarner LoshIf the loader returns any non-nil value,
87028e3e3a7aSWarner Losh<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>.
87038e3e3a7aSWarner LoshIf the loader does not return a non-nil value and
87048e3e3a7aSWarner Loshhas not assigned any value to <code>package.loaded[modname]</code>,
87058e3e3a7aSWarner Loshthen <code>require</code> assigns <b>true</b> to this entry.
87068e3e3a7aSWarner LoshIn any case, <code>require</code> returns the
87078e3e3a7aSWarner Loshfinal value of <code>package.loaded[modname]</code>.
87080495ed39SKyle EvansBesides that value, <code>require</code> also returns as a second result
87090495ed39SKyle Evansthe loader data returned by the searcher,
87100495ed39SKyle Evanswhich indicates how <code>require</code> found the module.
87118e3e3a7aSWarner Losh
87128e3e3a7aSWarner Losh
87138e3e3a7aSWarner Losh<p>
87148e3e3a7aSWarner LoshIf there is any error loading or running the module,
87158e3e3a7aSWarner Loshor if it cannot find any loader for the module,
87168e3e3a7aSWarner Loshthen <code>require</code> raises an error.
87178e3e3a7aSWarner Losh
87188e3e3a7aSWarner Losh
87198e3e3a7aSWarner Losh
87208e3e3a7aSWarner Losh
87218e3e3a7aSWarner Losh<p>
87228e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3>
87238e3e3a7aSWarner Losh
87248e3e3a7aSWarner Losh
87258e3e3a7aSWarner Losh<p>
87268e3e3a7aSWarner LoshA string describing some compile-time configurations for packages.
87278e3e3a7aSWarner LoshThis string is a sequence of lines:
87288e3e3a7aSWarner Losh
87298e3e3a7aSWarner Losh<ul>
87308e3e3a7aSWarner Losh
87318e3e3a7aSWarner Losh<li>The first line is the directory separator string.
87328e3e3a7aSWarner LoshDefault is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li>
87338e3e3a7aSWarner Losh
87348e3e3a7aSWarner Losh<li>The second line is the character that separates templates in a path.
87358e3e3a7aSWarner LoshDefault is '<code>;</code>'.</li>
87368e3e3a7aSWarner Losh
87378e3e3a7aSWarner Losh<li>The third line is the string that marks the
87388e3e3a7aSWarner Loshsubstitution points in a template.
87398e3e3a7aSWarner LoshDefault is '<code>?</code>'.</li>
87408e3e3a7aSWarner Losh
87418e3e3a7aSWarner Losh<li>The fourth line is a string that, in a path in Windows,
87428e3e3a7aSWarner Loshis replaced by the executable's directory.
87438e3e3a7aSWarner LoshDefault is '<code>!</code>'.</li>
87448e3e3a7aSWarner Losh
87458e3e3a7aSWarner Losh<li>The fifth line is a mark to ignore all text after it
87468e3e3a7aSWarner Loshwhen building the <code>luaopen_</code> function name.
87478e3e3a7aSWarner LoshDefault is '<code>-</code>'.</li>
87488e3e3a7aSWarner Losh
87498e3e3a7aSWarner Losh</ul>
87508e3e3a7aSWarner Losh
87518e3e3a7aSWarner Losh
87528e3e3a7aSWarner Losh
87538e3e3a7aSWarner Losh<p>
87548e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3>
87558e3e3a7aSWarner Losh
87568e3e3a7aSWarner Losh
87578e3e3a7aSWarner Losh<p>
87580495ed39SKyle EvansA string with the path used by <a href="#pdf-require"><code>require</code></a>
87590495ed39SKyle Evansto search for a C&nbsp;loader.
87608e3e3a7aSWarner Losh
87618e3e3a7aSWarner Losh
87628e3e3a7aSWarner Losh<p>
87638e3e3a7aSWarner LoshLua initializes the C&nbsp;path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
87648e3e3a7aSWarner Loshit initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
87650495ed39SKyle Evansusing the environment variable <a name="pdf-LUA_CPATH_5_4"><code>LUA_CPATH_5_4</code></a>,
87668e3e3a7aSWarner Loshor the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>,
87678e3e3a7aSWarner Loshor a default path defined in <code>luaconf.h</code>.
87688e3e3a7aSWarner Losh
87698e3e3a7aSWarner Losh
87708e3e3a7aSWarner Losh
87718e3e3a7aSWarner Losh
87728e3e3a7aSWarner Losh<p>
87738e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3>
87748e3e3a7aSWarner Losh
87758e3e3a7aSWarner Losh
87768e3e3a7aSWarner Losh<p>
87778e3e3a7aSWarner LoshA table used by <a href="#pdf-require"><code>require</code></a> to control which
87788e3e3a7aSWarner Loshmodules are already loaded.
87798e3e3a7aSWarner LoshWhen you require a module <code>modname</code> and
87808e3e3a7aSWarner Losh<code>package.loaded[modname]</code> is not false,
87818e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a> simply returns the value stored there.
87828e3e3a7aSWarner Losh
87838e3e3a7aSWarner Losh
87848e3e3a7aSWarner Losh<p>
87858e3e3a7aSWarner LoshThis variable is only a reference to the real table;
87868e3e3a7aSWarner Loshassignments to this variable do not change the
87878e3e3a7aSWarner Loshtable used by <a href="#pdf-require"><code>require</code></a>.
8788*a9490b81SWarner LoshThe real table is stored in the C registry (see <a href="#4.3">&sect;4.3</a>),
8789*a9490b81SWarner Loshindexed by the key <a name="pdf-LUA_LOADED_TABLE"><code>LUA_LOADED_TABLE</code></a>, a string.
87908e3e3a7aSWarner Losh
87918e3e3a7aSWarner Losh
87928e3e3a7aSWarner Losh
87938e3e3a7aSWarner Losh
87948e3e3a7aSWarner Losh<p>
87958e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
87968e3e3a7aSWarner Losh
87978e3e3a7aSWarner Losh
87988e3e3a7aSWarner Losh<p>
87998e3e3a7aSWarner LoshDynamically links the host program with the C&nbsp;library <code>libname</code>.
88008e3e3a7aSWarner Losh
88018e3e3a7aSWarner Losh
88028e3e3a7aSWarner Losh<p>
88038e3e3a7aSWarner LoshIf <code>funcname</code> is "<code>*</code>",
88048e3e3a7aSWarner Loshthen it only links with the library,
88058e3e3a7aSWarner Loshmaking the symbols exported by the library
88068e3e3a7aSWarner Loshavailable to other dynamically linked libraries.
88078e3e3a7aSWarner LoshOtherwise,
88088e3e3a7aSWarner Loshit looks for a function <code>funcname</code> inside the library
88098e3e3a7aSWarner Loshand returns this function as a C&nbsp;function.
88108e3e3a7aSWarner LoshSo, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype
88118e3e3a7aSWarner Losh(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
88128e3e3a7aSWarner Losh
88138e3e3a7aSWarner Losh
88148e3e3a7aSWarner Losh<p>
88158e3e3a7aSWarner LoshThis is a low-level function.
88168e3e3a7aSWarner LoshIt completely bypasses the package and module system.
88178e3e3a7aSWarner LoshUnlike <a href="#pdf-require"><code>require</code></a>,
88188e3e3a7aSWarner Loshit does not perform any path searching and
88198e3e3a7aSWarner Loshdoes not automatically adds extensions.
88208e3e3a7aSWarner Losh<code>libname</code> must be the complete file name of the C&nbsp;library,
88218e3e3a7aSWarner Loshincluding if necessary a path and an extension.
88228e3e3a7aSWarner Losh<code>funcname</code> must be the exact name exported by the C&nbsp;library
88238e3e3a7aSWarner Losh(which may depend on the C&nbsp;compiler and linker used).
88248e3e3a7aSWarner Losh
88258e3e3a7aSWarner Losh
88268e3e3a7aSWarner Losh<p>
8827*a9490b81SWarner LoshThis functionality is not supported by ISO&nbsp;C.
88288e3e3a7aSWarner LoshAs such, it is only available on some platforms
88298e3e3a7aSWarner Losh(Windows, Linux, Mac OS X, Solaris, BSD,
88308e3e3a7aSWarner Loshplus other Unix systems that support the <code>dlfcn</code> standard).
88318e3e3a7aSWarner Losh
88328e3e3a7aSWarner Losh
88330495ed39SKyle Evans<p>
88340495ed39SKyle EvansThis function is inherently insecure,
88350495ed39SKyle Evansas it allows Lua to call any function in any readable dynamic
88360495ed39SKyle Evanslibrary in the system.
88370495ed39SKyle Evans(Lua calls any function assuming the function
88380495ed39SKyle Evanshas a proper prototype and respects a proper protocol
88390495ed39SKyle Evans(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
88400495ed39SKyle EvansTherefore,
88410495ed39SKyle Evanscalling an arbitrary function in an arbitrary dynamic library
88420495ed39SKyle Evansmore often than not results in an access violation.)
88430495ed39SKyle Evans
88440495ed39SKyle Evans
88458e3e3a7aSWarner Losh
88468e3e3a7aSWarner Losh
88478e3e3a7aSWarner Losh<p>
88488e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3>
88498e3e3a7aSWarner Losh
88508e3e3a7aSWarner Losh
88518e3e3a7aSWarner Losh<p>
88520495ed39SKyle EvansA string with the path used by <a href="#pdf-require"><code>require</code></a>
88530495ed39SKyle Evansto search for a Lua loader.
88548e3e3a7aSWarner Losh
88558e3e3a7aSWarner Losh
88568e3e3a7aSWarner Losh<p>
88578e3e3a7aSWarner LoshAt start-up, Lua initializes this variable with
88580495ed39SKyle Evansthe value of the environment variable <a name="pdf-LUA_PATH_5_4"><code>LUA_PATH_5_4</code></a> or
88598e3e3a7aSWarner Loshthe environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or
88608e3e3a7aSWarner Loshwith a default path defined in <code>luaconf.h</code>,
88618e3e3a7aSWarner Loshif those environment variables are not defined.
88620495ed39SKyle EvansA "<code>;;</code>" in the value of the environment variable
88638e3e3a7aSWarner Loshis replaced by the default path.
88648e3e3a7aSWarner Losh
88658e3e3a7aSWarner Losh
88668e3e3a7aSWarner Losh
88678e3e3a7aSWarner Losh
88688e3e3a7aSWarner Losh<p>
88698e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3>
88708e3e3a7aSWarner Losh
88718e3e3a7aSWarner Losh
88728e3e3a7aSWarner Losh<p>
88738e3e3a7aSWarner LoshA table to store loaders for specific modules
88748e3e3a7aSWarner Losh(see <a href="#pdf-require"><code>require</code></a>).
88758e3e3a7aSWarner Losh
88768e3e3a7aSWarner Losh
88778e3e3a7aSWarner Losh<p>
88788e3e3a7aSWarner LoshThis variable is only a reference to the real table;
88798e3e3a7aSWarner Loshassignments to this variable do not change the
88808e3e3a7aSWarner Loshtable used by <a href="#pdf-require"><code>require</code></a>.
8881*a9490b81SWarner LoshThe real table is stored in the C registry (see <a href="#4.3">&sect;4.3</a>),
8882*a9490b81SWarner Loshindexed by the key <a name="pdf-LUA_PRELOAD_TABLE"><code>LUA_PRELOAD_TABLE</code></a>, a string.
88838e3e3a7aSWarner Losh
88848e3e3a7aSWarner Losh
88858e3e3a7aSWarner Losh
88868e3e3a7aSWarner Losh
88878e3e3a7aSWarner Losh<p>
88888e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3>
88898e3e3a7aSWarner Losh
88908e3e3a7aSWarner Losh
88918e3e3a7aSWarner Losh<p>
88920495ed39SKyle EvansA table used by <a href="#pdf-require"><code>require</code></a> to control how to find modules.
88938e3e3a7aSWarner Losh
88948e3e3a7aSWarner Losh
88958e3e3a7aSWarner Losh<p>
88968e3e3a7aSWarner LoshEach entry in this table is a <em>searcher function</em>.
88978e3e3a7aSWarner LoshWhen looking for a module,
88988e3e3a7aSWarner Losh<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order,
88998e3e3a7aSWarner Loshwith the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its
89000495ed39SKyle Evanssole argument.
89010495ed39SKyle EvansIf the searcher finds the module,
89020495ed39SKyle Evansit returns another function, the module <em>loader</em>,
89030495ed39SKyle Evansplus an extra value, a <em>loader data</em>,
89040495ed39SKyle Evansthat will be passed to that loader and
89050495ed39SKyle Evansreturned as a second result by <a href="#pdf-require"><code>require</code></a>.
89060495ed39SKyle EvansIf it cannot find the module,
89070495ed39SKyle Evansit returns a string explaining why
89088e3e3a7aSWarner Losh(or <b>nil</b> if it has nothing to say).
89098e3e3a7aSWarner Losh
89108e3e3a7aSWarner Losh
89118e3e3a7aSWarner Losh<p>
89128e3e3a7aSWarner LoshLua initializes this table with four searcher functions.
89138e3e3a7aSWarner Losh
89148e3e3a7aSWarner Losh
89158e3e3a7aSWarner Losh<p>
89168e3e3a7aSWarner LoshThe first searcher simply looks for a loader in the
89178e3e3a7aSWarner Losh<a href="#pdf-package.preload"><code>package.preload</code></a> table.
89188e3e3a7aSWarner Losh
89198e3e3a7aSWarner Losh
89208e3e3a7aSWarner Losh<p>
89218e3e3a7aSWarner LoshThe second searcher looks for a loader as a Lua library,
89228e3e3a7aSWarner Loshusing the path stored at <a href="#pdf-package.path"><code>package.path</code></a>.
89238e3e3a7aSWarner LoshThe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
89248e3e3a7aSWarner Losh
89258e3e3a7aSWarner Losh
89268e3e3a7aSWarner Losh<p>
89278e3e3a7aSWarner LoshThe third searcher looks for a loader as a C&nbsp;library,
89288e3e3a7aSWarner Loshusing the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
89298e3e3a7aSWarner LoshAgain,
89308e3e3a7aSWarner Loshthe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
89318e3e3a7aSWarner LoshFor instance,
89328e3e3a7aSWarner Loshif the C&nbsp;path is the string
89338e3e3a7aSWarner Losh
89348e3e3a7aSWarner Losh<pre>
89358e3e3a7aSWarner Losh     "./?.so;./?.dll;/usr/local/?/init.so"
89368e3e3a7aSWarner Losh</pre><p>
89378e3e3a7aSWarner Loshthe searcher for module <code>foo</code>
89388e3e3a7aSWarner Loshwill try to open the files <code>./foo.so</code>, <code>./foo.dll</code>,
89398e3e3a7aSWarner Loshand <code>/usr/local/foo/init.so</code>, in that order.
89408e3e3a7aSWarner LoshOnce it finds a C&nbsp;library,
89418e3e3a7aSWarner Loshthis searcher first uses a dynamic link facility to link the
89428e3e3a7aSWarner Loshapplication with the library.
89438e3e3a7aSWarner LoshThen it tries to find a C&nbsp;function inside the library to
89448e3e3a7aSWarner Loshbe used as the loader.
89458e3e3a7aSWarner LoshThe name of this C&nbsp;function is the string "<code>luaopen_</code>"
89468e3e3a7aSWarner Loshconcatenated with a copy of the module name where each dot
89478e3e3a7aSWarner Loshis replaced by an underscore.
89488e3e3a7aSWarner LoshMoreover, if the module name has a hyphen,
89498e3e3a7aSWarner Loshits suffix after (and including) the first hyphen is removed.
89508e3e3a7aSWarner LoshFor instance, if the module name is <code>a.b.c-v2.1</code>,
89518e3e3a7aSWarner Loshthe function name will be <code>luaopen_a_b_c</code>.
89528e3e3a7aSWarner Losh
89538e3e3a7aSWarner Losh
89548e3e3a7aSWarner Losh<p>
89558e3e3a7aSWarner LoshThe fourth searcher tries an <em>all-in-one loader</em>.
89568e3e3a7aSWarner LoshIt searches the C&nbsp;path for a library for
89578e3e3a7aSWarner Loshthe root name of the given module.
89588e3e3a7aSWarner LoshFor instance, when requiring <code>a.b.c</code>,
89598e3e3a7aSWarner Loshit will search for a C&nbsp;library for <code>a</code>.
89608e3e3a7aSWarner LoshIf found, it looks into it for an open function for
89618e3e3a7aSWarner Loshthe submodule;
89628e3e3a7aSWarner Loshin our example, that would be <code>luaopen_a_b_c</code>.
89638e3e3a7aSWarner LoshWith this facility, a package can pack several C&nbsp;submodules
89648e3e3a7aSWarner Loshinto one single library,
89658e3e3a7aSWarner Loshwith each submodule keeping its original open function.
89668e3e3a7aSWarner Losh
89678e3e3a7aSWarner Losh
89688e3e3a7aSWarner Losh<p>
89698e3e3a7aSWarner LoshAll searchers except the first one (preload) return as the extra value
89700495ed39SKyle Evansthe file path where the module was found,
89718e3e3a7aSWarner Loshas returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
89720495ed39SKyle EvansThe first searcher always returns the string "<code>:preload:</code>".
89730495ed39SKyle Evans
89740495ed39SKyle Evans
89750495ed39SKyle Evans<p>
89760495ed39SKyle EvansSearchers should raise no errors and have no side effects in Lua.
89770495ed39SKyle Evans(They may have side effects in C,
89780495ed39SKyle Evansfor instance by linking the application with a library.)
89798e3e3a7aSWarner Losh
89808e3e3a7aSWarner Losh
89818e3e3a7aSWarner Losh
89828e3e3a7aSWarner Losh
89838e3e3a7aSWarner Losh<p>
89848e3e3a7aSWarner Losh<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3>
89858e3e3a7aSWarner Losh
89868e3e3a7aSWarner Losh
89878e3e3a7aSWarner Losh<p>
89888e3e3a7aSWarner LoshSearches for the given <code>name</code> in the given <code>path</code>.
89898e3e3a7aSWarner Losh
89908e3e3a7aSWarner Losh
89918e3e3a7aSWarner Losh<p>
89928e3e3a7aSWarner LoshA path is a string containing a sequence of
89938e3e3a7aSWarner Losh<em>templates</em> separated by semicolons.
89948e3e3a7aSWarner LoshFor each template,
89958e3e3a7aSWarner Loshthe function replaces each interrogation mark (if any)
89968e3e3a7aSWarner Loshin the template with a copy of <code>name</code>
89978e3e3a7aSWarner Loshwherein all occurrences of <code>sep</code>
89988e3e3a7aSWarner Losh(a dot, by default)
89998e3e3a7aSWarner Loshwere replaced by <code>rep</code>
90008e3e3a7aSWarner Losh(the system's directory separator, by default),
90018e3e3a7aSWarner Loshand then tries to open the resulting file name.
90028e3e3a7aSWarner Losh
90038e3e3a7aSWarner Losh
90048e3e3a7aSWarner Losh<p>
90058e3e3a7aSWarner LoshFor instance, if the path is the string
90068e3e3a7aSWarner Losh
90078e3e3a7aSWarner Losh<pre>
90088e3e3a7aSWarner Losh     "./?.lua;./?.lc;/usr/local/?/init.lua"
90098e3e3a7aSWarner Losh</pre><p>
90108e3e3a7aSWarner Loshthe search for the name <code>foo.a</code>
90118e3e3a7aSWarner Loshwill try to open the files
90128e3e3a7aSWarner Losh<code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and
90138e3e3a7aSWarner Losh<code>/usr/local/foo/a/init.lua</code>, in that order.
90148e3e3a7aSWarner Losh
90158e3e3a7aSWarner Losh
90168e3e3a7aSWarner Losh<p>
90178e3e3a7aSWarner LoshReturns the resulting name of the first file that it can
90188e3e3a7aSWarner Loshopen in read mode (after closing the file),
90190495ed39SKyle Evansor <b>fail</b> plus an error message if none succeeds.
90208e3e3a7aSWarner Losh(This error message lists all file names it tried to open.)
90218e3e3a7aSWarner Losh
90228e3e3a7aSWarner Losh
90238e3e3a7aSWarner Losh
90248e3e3a7aSWarner Losh
90258e3e3a7aSWarner Losh
90268e3e3a7aSWarner Losh
90278e3e3a7aSWarner Losh
90288e3e3a7aSWarner Losh<h2>6.4 &ndash; <a name="6.4">String Manipulation</a></h2>
90298e3e3a7aSWarner Losh
90300495ed39SKyle Evans
90310495ed39SKyle Evans
90328e3e3a7aSWarner Losh<p>
90338e3e3a7aSWarner LoshThis library provides generic functions for string manipulation,
90348e3e3a7aSWarner Loshsuch as finding and extracting substrings, and pattern matching.
90358e3e3a7aSWarner LoshWhen indexing a string in Lua, the first character is at position&nbsp;1
90368e3e3a7aSWarner Losh(not at&nbsp;0, as in C).
90378e3e3a7aSWarner LoshIndices are allowed to be negative and are interpreted as indexing backwards,
90388e3e3a7aSWarner Loshfrom the end of the string.
90398e3e3a7aSWarner LoshThus, the last character is at position -1, and so on.
90408e3e3a7aSWarner Losh
90418e3e3a7aSWarner Losh
90428e3e3a7aSWarner Losh<p>
90438e3e3a7aSWarner LoshThe string library provides all its functions inside the table
90448e3e3a7aSWarner Losh<a name="pdf-string"><code>string</code></a>.
90458e3e3a7aSWarner LoshIt also sets a metatable for strings
90468e3e3a7aSWarner Loshwhere the <code>__index</code> field points to the <code>string</code> table.
90478e3e3a7aSWarner LoshTherefore, you can use the string functions in object-oriented style.
90488e3e3a7aSWarner LoshFor instance, <code>string.byte(s,i)</code>
90498e3e3a7aSWarner Loshcan be written as <code>s:byte(i)</code>.
90508e3e3a7aSWarner Losh
90518e3e3a7aSWarner Losh
90528e3e3a7aSWarner Losh<p>
90538e3e3a7aSWarner LoshThe string library assumes one-byte character encodings.
90548e3e3a7aSWarner Losh
90558e3e3a7aSWarner Losh
90568e3e3a7aSWarner Losh<p>
90578e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>
90588e3e3a7aSWarner LoshReturns the internal numeric codes of the characters <code>s[i]</code>,
90598e3e3a7aSWarner Losh<code>s[i+1]</code>, ..., <code>s[j]</code>.
90608e3e3a7aSWarner LoshThe default value for <code>i</code> is&nbsp;1;
90618e3e3a7aSWarner Loshthe default value for <code>j</code> is&nbsp;<code>i</code>.
90628e3e3a7aSWarner LoshThese indices are corrected
90638e3e3a7aSWarner Loshfollowing the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>.
90648e3e3a7aSWarner Losh
90658e3e3a7aSWarner Losh
90668e3e3a7aSWarner Losh<p>
90678e3e3a7aSWarner LoshNumeric codes are not necessarily portable across platforms.
90688e3e3a7aSWarner Losh
90698e3e3a7aSWarner Losh
90708e3e3a7aSWarner Losh
90718e3e3a7aSWarner Losh
90728e3e3a7aSWarner Losh<p>
90738e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.char"><code>string.char (&middot;&middot;&middot;)</code></a></h3>
90748e3e3a7aSWarner LoshReceives zero or more integers.
90758e3e3a7aSWarner LoshReturns a string with length equal to the number of arguments,
90768e3e3a7aSWarner Loshin which each character has the internal numeric code equal
90778e3e3a7aSWarner Loshto its corresponding argument.
90788e3e3a7aSWarner Losh
90798e3e3a7aSWarner Losh
90808e3e3a7aSWarner Losh<p>
90818e3e3a7aSWarner LoshNumeric codes are not necessarily portable across platforms.
90828e3e3a7aSWarner Losh
90838e3e3a7aSWarner Losh
90848e3e3a7aSWarner Losh
90858e3e3a7aSWarner Losh
90868e3e3a7aSWarner Losh<p>
90878e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3>
90888e3e3a7aSWarner Losh
90898e3e3a7aSWarner Losh
90908e3e3a7aSWarner Losh<p>
90918e3e3a7aSWarner LoshReturns a string containing a binary representation
90928e3e3a7aSWarner Losh(a <em>binary chunk</em>)
90938e3e3a7aSWarner Loshof the given function,
90948e3e3a7aSWarner Loshso that a later <a href="#pdf-load"><code>load</code></a> on this string returns
90958e3e3a7aSWarner Losha copy of the function (but with new upvalues).
90968e3e3a7aSWarner LoshIf <code>strip</code> is a true value,
90978e3e3a7aSWarner Loshthe binary representation may not include all debug information
90988e3e3a7aSWarner Loshabout the function,
90998e3e3a7aSWarner Loshto save space.
91008e3e3a7aSWarner Losh
91018e3e3a7aSWarner Losh
91028e3e3a7aSWarner Losh<p>
91038e3e3a7aSWarner LoshFunctions with upvalues have only their number of upvalues saved.
91048e3e3a7aSWarner LoshWhen (re)loaded,
91050495ed39SKyle Evansthose upvalues receive fresh instances.
91060495ed39SKyle Evans(See the <a href="#pdf-load"><code>load</code></a> function for details about
91070495ed39SKyle Evanshow these upvalues are initialized.
91080495ed39SKyle EvansYou can use the debug library to serialize
91098e3e3a7aSWarner Loshand reload the upvalues of a function
91108e3e3a7aSWarner Loshin a way adequate to your needs.)
91118e3e3a7aSWarner Losh
91128e3e3a7aSWarner Losh
91138e3e3a7aSWarner Losh
91148e3e3a7aSWarner Losh
91158e3e3a7aSWarner Losh<p>
91168e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
91178e3e3a7aSWarner Losh
91188e3e3a7aSWarner Losh
91198e3e3a7aSWarner Losh<p>
91208e3e3a7aSWarner LoshLooks for the first match of
91218e3e3a7aSWarner Losh<code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) in the string <code>s</code>.
91228e3e3a7aSWarner LoshIf it finds a match, then <code>find</code> returns the indices of&nbsp;<code>s</code>
91238e3e3a7aSWarner Loshwhere this occurrence starts and ends;
91240495ed39SKyle Evansotherwise, it returns <b>fail</b>.
91258e3e3a7aSWarner LoshA third, optional numeric argument <code>init</code> specifies
91268e3e3a7aSWarner Loshwhere to start the search;
91278e3e3a7aSWarner Loshits default value is&nbsp;1 and can be negative.
91288c784bb8SWarner LoshA <b>true</b> as a fourth, optional argument <code>plain</code>
91298e3e3a7aSWarner Loshturns off the pattern matching facilities,
91308e3e3a7aSWarner Loshso the function does a plain "find substring" operation,
91318e3e3a7aSWarner Loshwith no characters in <code>pattern</code> being considered magic.
91328e3e3a7aSWarner Losh
91338e3e3a7aSWarner Losh
91348e3e3a7aSWarner Losh<p>
91358e3e3a7aSWarner LoshIf the pattern has captures,
91368e3e3a7aSWarner Loshthen in a successful match
91378e3e3a7aSWarner Loshthe captured values are also returned,
91388e3e3a7aSWarner Loshafter the two indices.
91398e3e3a7aSWarner Losh
91408e3e3a7aSWarner Losh
91418e3e3a7aSWarner Losh
91428e3e3a7aSWarner Losh
91438e3e3a7aSWarner Losh<p>
91448e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, &middot;&middot;&middot;)</code></a></h3>
91458e3e3a7aSWarner Losh
91468e3e3a7aSWarner Losh
91478e3e3a7aSWarner Losh<p>
91488e3e3a7aSWarner LoshReturns a formatted version of its variable number of arguments
91490495ed39SKyle Evansfollowing the description given in its first argument,
91500495ed39SKyle Evanswhich must be a string.
91518e3e3a7aSWarner LoshThe format string follows the same rules as the ISO&nbsp;C function <code>sprintf</code>.
91520495ed39SKyle EvansThe only differences are that the conversion specifiers and modifiers
91538c784bb8SWarner Losh<code>F</code>, <code>n</code>, <code>*</code>, <code>h</code>, <code>L</code>, and <code>l</code> are not supported
91540495ed39SKyle Evansand that there is an extra specifier, <code>q</code>.
91558c784bb8SWarner LoshBoth width and precision, when present,
91568c784bb8SWarner Loshare limited to two digits.
91578e3e3a7aSWarner Losh
91588e3e3a7aSWarner Losh
91598e3e3a7aSWarner Losh<p>
91600495ed39SKyle EvansThe specifier <code>q</code> formats booleans, nil, numbers, and strings
91610495ed39SKyle Evansin a way that the result is a valid constant in Lua source code.
91620495ed39SKyle EvansBooleans and nil are written in the obvious way
91630495ed39SKyle Evans(<code>true</code>, <code>false</code>, <code>nil</code>).
91640495ed39SKyle EvansFloats are written in hexadecimal,
91650495ed39SKyle Evansto preserve full precision.
91660495ed39SKyle EvansA string is written between double quotes,
91678e3e3a7aSWarner Loshusing escape sequences when necessary to ensure that
91688e3e3a7aSWarner Loshit can safely be read back by the Lua interpreter.
91698e3e3a7aSWarner LoshFor instance, the call
91708e3e3a7aSWarner Losh
91718e3e3a7aSWarner Losh<pre>
91728e3e3a7aSWarner Losh     string.format('%q', 'a string with "quotes" and \n new line')
91738e3e3a7aSWarner Losh</pre><p>
91748e3e3a7aSWarner Loshmay produce the string:
91758e3e3a7aSWarner Losh
91768e3e3a7aSWarner Losh<pre>
91778e3e3a7aSWarner Losh     "a string with \"quotes\" and \
91788e3e3a7aSWarner Losh      new line"
91790495ed39SKyle Evans</pre><p>
91808c784bb8SWarner LoshThis specifier does not support modifiers (flags, width, precision).
91810495ed39SKyle Evans
91828e3e3a7aSWarner Losh
91838e3e3a7aSWarner Losh<p>
91840495ed39SKyle EvansThe conversion specifiers
91858e3e3a7aSWarner Losh<code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>,
91868e3e3a7aSWarner Losh<code>G</code>, and <code>g</code> all expect a number as argument.
91870495ed39SKyle EvansThe specifiers <code>c</code>, <code>d</code>,
91888e3e3a7aSWarner Losh<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code>
91898e3e3a7aSWarner Loshexpect an integer.
91908e3e3a7aSWarner LoshWhen Lua is compiled with a C89 compiler,
91910495ed39SKyle Evansthe specifiers <code>A</code> and <code>a</code> (hexadecimal floats)
91920495ed39SKyle Evansdo not support modifiers.
91938e3e3a7aSWarner Losh
91948e3e3a7aSWarner Losh
91958e3e3a7aSWarner Losh<p>
91960495ed39SKyle EvansThe specifier <code>s</code> expects a string;
91978e3e3a7aSWarner Loshif its argument is not a string,
91988e3e3a7aSWarner Loshit is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>.
91990495ed39SKyle EvansIf the specifier has any modifier,
92000495ed39SKyle Evansthe corresponding string argument should not contain embedded zeros.
92010495ed39SKyle Evans
92020495ed39SKyle Evans
92030495ed39SKyle Evans<p>
92040495ed39SKyle EvansThe specifier <code>p</code> formats the pointer
92050495ed39SKyle Evansreturned by <a href="#lua_topointer"><code>lua_topointer</code></a>.
92060495ed39SKyle EvansThat gives a unique string identifier for tables, userdata,
92070495ed39SKyle Evansthreads, strings, and functions.
92080495ed39SKyle EvansFor other values (numbers, nil, booleans),
92090495ed39SKyle Evansthis specifier results in a string representing
92100495ed39SKyle Evansthe pointer <code>NULL</code>.
92118e3e3a7aSWarner Losh
92128e3e3a7aSWarner Losh
92138e3e3a7aSWarner Losh
92148e3e3a7aSWarner Losh
92158e3e3a7aSWarner Losh<p>
92160495ed39SKyle Evans<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern [, init])</code></a></h3>
92178e3e3a7aSWarner LoshReturns an iterator function that,
92188e3e3a7aSWarner Losheach time it is called,
92198e3e3a7aSWarner Loshreturns the next captures from <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>)
92208e3e3a7aSWarner Loshover the string <code>s</code>.
92218e3e3a7aSWarner LoshIf <code>pattern</code> specifies no captures,
92228e3e3a7aSWarner Loshthen the whole match is produced in each call.
92230495ed39SKyle EvansA third, optional numeric argument <code>init</code> specifies
92240495ed39SKyle Evanswhere to start the search;
92250495ed39SKyle Evansits default value is&nbsp;1 and can be negative.
92268e3e3a7aSWarner Losh
92278e3e3a7aSWarner Losh
92288e3e3a7aSWarner Losh<p>
92298e3e3a7aSWarner LoshAs an example, the following loop
92308e3e3a7aSWarner Loshwill iterate over all the words from string <code>s</code>,
92318e3e3a7aSWarner Loshprinting one per line:
92328e3e3a7aSWarner Losh
92338e3e3a7aSWarner Losh<pre>
92348e3e3a7aSWarner Losh     s = "hello world from Lua"
92358e3e3a7aSWarner Losh     for w in string.gmatch(s, "%a+") do
92368e3e3a7aSWarner Losh       print(w)
92378e3e3a7aSWarner Losh     end
92388e3e3a7aSWarner Losh</pre><p>
92398e3e3a7aSWarner LoshThe next example collects all pairs <code>key=value</code> from the
92408e3e3a7aSWarner Loshgiven string into a table:
92418e3e3a7aSWarner Losh
92428e3e3a7aSWarner Losh<pre>
92438e3e3a7aSWarner Losh     t = {}
92448e3e3a7aSWarner Losh     s = "from=world, to=Lua"
92458e3e3a7aSWarner Losh     for k, v in string.gmatch(s, "(%w+)=(%w+)") do
92468e3e3a7aSWarner Losh       t[k] = v
92478e3e3a7aSWarner Losh     end
92488e3e3a7aSWarner Losh</pre>
92498e3e3a7aSWarner Losh
92508e3e3a7aSWarner Losh<p>
92518e3e3a7aSWarner LoshFor this function, a caret '<code>^</code>' at the start of a pattern does not
92528e3e3a7aSWarner Loshwork as an anchor, as this would prevent the iteration.
92538e3e3a7aSWarner Losh
92548e3e3a7aSWarner Losh
92558e3e3a7aSWarner Losh
92568e3e3a7aSWarner Losh
92578e3e3a7aSWarner Losh<p>
92588e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3>
92598e3e3a7aSWarner LoshReturns a copy of <code>s</code>
92608e3e3a7aSWarner Loshin which all (or the first <code>n</code>, if given)
92618e3e3a7aSWarner Loshoccurrences of the <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) have been
92628e3e3a7aSWarner Loshreplaced by a replacement string specified by <code>repl</code>,
92638e3e3a7aSWarner Loshwhich can be a string, a table, or a function.
92648e3e3a7aSWarner Losh<code>gsub</code> also returns, as its second value,
92658e3e3a7aSWarner Loshthe total number of matches that occurred.
92668e3e3a7aSWarner LoshThe name <code>gsub</code> comes from <em>Global SUBstitution</em>.
92678e3e3a7aSWarner Losh
92688e3e3a7aSWarner Losh
92698e3e3a7aSWarner Losh<p>
92708e3e3a7aSWarner LoshIf <code>repl</code> is a string, then its value is used for replacement.
92718e3e3a7aSWarner LoshThe character&nbsp;<code>%</code> works as an escape character:
92728e3e3a7aSWarner Loshany sequence in <code>repl</code> of the form <code>%<em>d</em></code>,
92738e3e3a7aSWarner Loshwith <em>d</em> between 1 and 9,
92740495ed39SKyle Evansstands for the value of the <em>d</em>-th captured substring;
92750495ed39SKyle Evansthe sequence <code>%0</code> stands for the whole match;
92760495ed39SKyle Evansthe sequence <code>%%</code> stands for a single&nbsp;<code>%</code>.
92778e3e3a7aSWarner Losh
92788e3e3a7aSWarner Losh
92798e3e3a7aSWarner Losh<p>
92808e3e3a7aSWarner LoshIf <code>repl</code> is a table, then the table is queried for every match,
92818e3e3a7aSWarner Loshusing the first capture as the key.
92828e3e3a7aSWarner Losh
92838e3e3a7aSWarner Losh
92848e3e3a7aSWarner Losh<p>
92858e3e3a7aSWarner LoshIf <code>repl</code> is a function, then this function is called every time a
92868e3e3a7aSWarner Loshmatch occurs, with all captured substrings passed as arguments,
92878e3e3a7aSWarner Loshin order.
92888e3e3a7aSWarner Losh
92898e3e3a7aSWarner Losh
92908e3e3a7aSWarner Losh<p>
92918e3e3a7aSWarner LoshIn any case,
92928e3e3a7aSWarner Loshif the pattern specifies no captures,
92938e3e3a7aSWarner Loshthen it behaves as if the whole pattern was inside a capture.
92948e3e3a7aSWarner Losh
92958e3e3a7aSWarner Losh
92968e3e3a7aSWarner Losh<p>
92978e3e3a7aSWarner LoshIf the value returned by the table query or by the function call
92988e3e3a7aSWarner Loshis a string or a number,
92998e3e3a7aSWarner Loshthen it is used as the replacement string;
93008e3e3a7aSWarner Loshotherwise, if it is <b>false</b> or <b>nil</b>,
93018e3e3a7aSWarner Loshthen there is no replacement
93028e3e3a7aSWarner Losh(that is, the original match is kept in the string).
93038e3e3a7aSWarner Losh
93048e3e3a7aSWarner Losh
93058e3e3a7aSWarner Losh<p>
93068e3e3a7aSWarner LoshHere are some examples:
93078e3e3a7aSWarner Losh
93088e3e3a7aSWarner Losh<pre>
93098e3e3a7aSWarner Losh     x = string.gsub("hello world", "(%w+)", "%1 %1")
93108e3e3a7aSWarner Losh     --&gt; x="hello hello world world"
93118e3e3a7aSWarner Losh
93128e3e3a7aSWarner Losh     x = string.gsub("hello world", "%w+", "%0 %0", 1)
93138e3e3a7aSWarner Losh     --&gt; x="hello hello world"
93148e3e3a7aSWarner Losh
93158e3e3a7aSWarner Losh     x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
93168e3e3a7aSWarner Losh     --&gt; x="world hello Lua from"
93178e3e3a7aSWarner Losh
93188e3e3a7aSWarner Losh     x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
93198e3e3a7aSWarner Losh     --&gt; x="home = /home/roberto, user = roberto"
93208e3e3a7aSWarner Losh
93218e3e3a7aSWarner Losh     x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
93228e3e3a7aSWarner Losh           return load(s)()
93238e3e3a7aSWarner Losh         end)
93248e3e3a7aSWarner Losh     --&gt; x="4+5 = 9"
93258e3e3a7aSWarner Losh
93260495ed39SKyle Evans     local t = {name="lua", version="5.4"}
93278e3e3a7aSWarner Losh     x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
93280495ed39SKyle Evans     --&gt; x="lua-5.4.tar.gz"
93298e3e3a7aSWarner Losh</pre>
93308e3e3a7aSWarner Losh
93318e3e3a7aSWarner Losh
93328e3e3a7aSWarner Losh
93338e3e3a7aSWarner Losh<p>
93348e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3>
93350495ed39SKyle Evans
93360495ed39SKyle Evans
93370495ed39SKyle Evans<p>
93388e3e3a7aSWarner LoshReceives a string and returns its length.
93398e3e3a7aSWarner LoshThe empty string <code>""</code> has length 0.
93408e3e3a7aSWarner LoshEmbedded zeros are counted,
93418e3e3a7aSWarner Loshso <code>"a\000bc\000"</code> has length 5.
93428e3e3a7aSWarner Losh
93438e3e3a7aSWarner Losh
93448e3e3a7aSWarner Losh
93458e3e3a7aSWarner Losh
93468e3e3a7aSWarner Losh<p>
93478e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3>
93480495ed39SKyle Evans
93490495ed39SKyle Evans
93500495ed39SKyle Evans<p>
93518e3e3a7aSWarner LoshReceives a string and returns a copy of this string with all
93528e3e3a7aSWarner Loshuppercase letters changed to lowercase.
93538e3e3a7aSWarner LoshAll other characters are left unchanged.
93548e3e3a7aSWarner LoshThe definition of what an uppercase letter is depends on the current locale.
93558e3e3a7aSWarner Losh
93568e3e3a7aSWarner Losh
93578e3e3a7aSWarner Losh
93588e3e3a7aSWarner Losh
93598e3e3a7aSWarner Losh<p>
93608e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3>
93610495ed39SKyle Evans
93620495ed39SKyle Evans
93630495ed39SKyle Evans<p>
93648e3e3a7aSWarner LoshLooks for the first <em>match</em> of
93650495ed39SKyle Evansthe <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) in the string <code>s</code>.
93668e3e3a7aSWarner LoshIf it finds one, then <code>match</code> returns
93678e3e3a7aSWarner Loshthe captures from the pattern;
93680495ed39SKyle Evansotherwise it returns <b>fail</b>.
93698e3e3a7aSWarner LoshIf <code>pattern</code> specifies no captures,
93708e3e3a7aSWarner Loshthen the whole match is returned.
93718e3e3a7aSWarner LoshA third, optional numeric argument <code>init</code> specifies
93728e3e3a7aSWarner Loshwhere to start the search;
93738e3e3a7aSWarner Loshits default value is&nbsp;1 and can be negative.
93748e3e3a7aSWarner Losh
93758e3e3a7aSWarner Losh
93768e3e3a7aSWarner Losh
93778e3e3a7aSWarner Losh
93788e3e3a7aSWarner Losh<p>
93798e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, &middot;&middot;&middot;)</code></a></h3>
93808e3e3a7aSWarner Losh
93818e3e3a7aSWarner Losh
93828e3e3a7aSWarner Losh<p>
93838e3e3a7aSWarner LoshReturns a binary string containing the values <code>v1</code>, <code>v2</code>, etc.
93840495ed39SKyle Evansserialized in binary form (packed)
93858e3e3a7aSWarner Loshaccording to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;6.4.2</a>).
93868e3e3a7aSWarner Losh
93878e3e3a7aSWarner Losh
93888e3e3a7aSWarner Losh
93898e3e3a7aSWarner Losh
93908e3e3a7aSWarner Losh<p>
93918e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3>
93928e3e3a7aSWarner Losh
93938e3e3a7aSWarner Losh
93948e3e3a7aSWarner Losh<p>
9395*a9490b81SWarner LoshReturns the length of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a>
93968e3e3a7aSWarner Loshwith the given format.
93978e3e3a7aSWarner LoshThe format string cannot have the variable-length options
93988e3e3a7aSWarner Losh'<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">&sect;6.4.2</a>).
93998e3e3a7aSWarner Losh
94008e3e3a7aSWarner Losh
94018e3e3a7aSWarner Losh
94028e3e3a7aSWarner Losh
94038e3e3a7aSWarner Losh<p>
94048e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3>
94050495ed39SKyle Evans
94060495ed39SKyle Evans
94070495ed39SKyle Evans<p>
94088e3e3a7aSWarner LoshReturns a string that is the concatenation of <code>n</code> copies of
94098e3e3a7aSWarner Loshthe string <code>s</code> separated by the string <code>sep</code>.
94108e3e3a7aSWarner LoshThe default value for <code>sep</code> is the empty string
94118e3e3a7aSWarner Losh(that is, no separator).
94128e3e3a7aSWarner LoshReturns the empty string if <code>n</code> is not positive.
94138e3e3a7aSWarner Losh
94148e3e3a7aSWarner Losh
94158e3e3a7aSWarner Losh<p>
94168e3e3a7aSWarner Losh(Note that it is very easy to exhaust the memory of your machine
94178e3e3a7aSWarner Loshwith a single call to this function.)
94188e3e3a7aSWarner Losh
94198e3e3a7aSWarner Losh
94208e3e3a7aSWarner Losh
94218e3e3a7aSWarner Losh
94228e3e3a7aSWarner Losh<p>
94238e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3>
94240495ed39SKyle Evans
94250495ed39SKyle Evans
94260495ed39SKyle Evans<p>
94278e3e3a7aSWarner LoshReturns a string that is the string <code>s</code> reversed.
94288e3e3a7aSWarner Losh
94298e3e3a7aSWarner Losh
94308e3e3a7aSWarner Losh
94318e3e3a7aSWarner Losh
94328e3e3a7aSWarner Losh<p>
94338e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3>
94340495ed39SKyle Evans
94350495ed39SKyle Evans
94360495ed39SKyle Evans<p>
94378e3e3a7aSWarner LoshReturns the substring of <code>s</code> that
94388e3e3a7aSWarner Loshstarts at <code>i</code>  and continues until <code>j</code>;
94398e3e3a7aSWarner Losh<code>i</code> and <code>j</code> can be negative.
94408e3e3a7aSWarner LoshIf <code>j</code> is absent, then it is assumed to be equal to -1
94418e3e3a7aSWarner Losh(which is the same as the string length).
94428e3e3a7aSWarner LoshIn particular,
94438e3e3a7aSWarner Loshthe call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
94448e3e3a7aSWarner Loshwith length <code>j</code>,
94458e3e3a7aSWarner Loshand <code>string.sub(s, -i)</code> (for a positive <code>i</code>)
94468e3e3a7aSWarner Loshreturns a suffix of <code>s</code>
94478e3e3a7aSWarner Loshwith length <code>i</code>.
94488e3e3a7aSWarner Losh
94498e3e3a7aSWarner Losh
94508e3e3a7aSWarner Losh<p>
94518e3e3a7aSWarner LoshIf, after the translation of negative indices,
94528e3e3a7aSWarner Losh<code>i</code> is less than 1,
94538e3e3a7aSWarner Loshit is corrected to 1.
94548e3e3a7aSWarner LoshIf <code>j</code> is greater than the string length,
94558e3e3a7aSWarner Loshit is corrected to that length.
94568e3e3a7aSWarner LoshIf, after these corrections,
94578e3e3a7aSWarner Losh<code>i</code> is greater than <code>j</code>,
94588e3e3a7aSWarner Loshthe function returns the empty string.
94598e3e3a7aSWarner Losh
94608e3e3a7aSWarner Losh
94618e3e3a7aSWarner Losh
94628e3e3a7aSWarner Losh
94638e3e3a7aSWarner Losh<p>
94648e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3>
94658e3e3a7aSWarner Losh
94668e3e3a7aSWarner Losh
94678e3e3a7aSWarner Losh<p>
94688e3e3a7aSWarner LoshReturns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>)
94698e3e3a7aSWarner Loshaccording to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;6.4.2</a>).
94708e3e3a7aSWarner LoshAn optional <code>pos</code> marks where
94718e3e3a7aSWarner Loshto start reading in <code>s</code> (default is 1).
94728e3e3a7aSWarner LoshAfter the read values,
94738e3e3a7aSWarner Loshthis function also returns the index of the first unread byte in <code>s</code>.
94748e3e3a7aSWarner Losh
94758e3e3a7aSWarner Losh
94768e3e3a7aSWarner Losh
94778e3e3a7aSWarner Losh
94788e3e3a7aSWarner Losh<p>
94798e3e3a7aSWarner Losh<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3>
94800495ed39SKyle Evans
94810495ed39SKyle Evans
94820495ed39SKyle Evans<p>
94838e3e3a7aSWarner LoshReceives a string and returns a copy of this string with all
94848e3e3a7aSWarner Loshlowercase letters changed to uppercase.
94858e3e3a7aSWarner LoshAll other characters are left unchanged.
94868e3e3a7aSWarner LoshThe definition of what a lowercase letter is depends on the current locale.
94878e3e3a7aSWarner Losh
94888e3e3a7aSWarner Losh
94898e3e3a7aSWarner Losh
94908e3e3a7aSWarner Losh
94918e3e3a7aSWarner Losh
94920495ed39SKyle Evans
94930495ed39SKyle Evans
94948e3e3a7aSWarner Losh<h3>6.4.1 &ndash; <a name="6.4.1">Patterns</a></h3>
94958e3e3a7aSWarner Losh
94960495ed39SKyle Evans
94970495ed39SKyle Evans
94988e3e3a7aSWarner Losh<p>
94998e3e3a7aSWarner LoshPatterns in Lua are described by regular strings,
95008e3e3a7aSWarner Loshwhich are interpreted as patterns by the pattern-matching functions
95018e3e3a7aSWarner Losh<a href="#pdf-string.find"><code>string.find</code></a>,
95028e3e3a7aSWarner Losh<a href="#pdf-string.gmatch"><code>string.gmatch</code></a>,
95038e3e3a7aSWarner Losh<a href="#pdf-string.gsub"><code>string.gsub</code></a>,
95048e3e3a7aSWarner Loshand <a href="#pdf-string.match"><code>string.match</code></a>.
95058e3e3a7aSWarner LoshThis section describes the syntax and the meaning
95068e3e3a7aSWarner Losh(that is, what they match) of these strings.
95078e3e3a7aSWarner Losh
95088e3e3a7aSWarner Losh
95098e3e3a7aSWarner Losh
95100495ed39SKyle Evans
95110495ed39SKyle Evans
95128e3e3a7aSWarner Losh<h4>Character Class:</h4><p>
95138e3e3a7aSWarner LoshA <em>character class</em> is used to represent a set of characters.
95148e3e3a7aSWarner LoshThe following combinations are allowed in describing a character class:
95158e3e3a7aSWarner Losh
95168e3e3a7aSWarner Losh<ul>
95178e3e3a7aSWarner Losh
95188e3e3a7aSWarner Losh<li><b><em>x</em>: </b>
95198e3e3a7aSWarner Losh(where <em>x</em> is not one of the <em>magic characters</em>
95208e3e3a7aSWarner Losh<code>^$()%.[]*+-?</code>)
95218e3e3a7aSWarner Loshrepresents the character <em>x</em> itself.
95228e3e3a7aSWarner Losh</li>
95238e3e3a7aSWarner Losh
95248e3e3a7aSWarner Losh<li><b><code>.</code>: </b> (a dot) represents all characters.</li>
95258e3e3a7aSWarner Losh
95268e3e3a7aSWarner Losh<li><b><code>%a</code>: </b> represents all letters.</li>
95278e3e3a7aSWarner Losh
95288e3e3a7aSWarner Losh<li><b><code>%c</code>: </b> represents all control characters.</li>
95298e3e3a7aSWarner Losh
95308e3e3a7aSWarner Losh<li><b><code>%d</code>: </b> represents all digits.</li>
95318e3e3a7aSWarner Losh
95328e3e3a7aSWarner Losh<li><b><code>%g</code>: </b> represents all printable characters except space.</li>
95338e3e3a7aSWarner Losh
95348e3e3a7aSWarner Losh<li><b><code>%l</code>: </b> represents all lowercase letters.</li>
95358e3e3a7aSWarner Losh
95368e3e3a7aSWarner Losh<li><b><code>%p</code>: </b> represents all punctuation characters.</li>
95378e3e3a7aSWarner Losh
95388e3e3a7aSWarner Losh<li><b><code>%s</code>: </b> represents all space characters.</li>
95398e3e3a7aSWarner Losh
95408e3e3a7aSWarner Losh<li><b><code>%u</code>: </b> represents all uppercase letters.</li>
95418e3e3a7aSWarner Losh
95428e3e3a7aSWarner Losh<li><b><code>%w</code>: </b> represents all alphanumeric characters.</li>
95438e3e3a7aSWarner Losh
95448e3e3a7aSWarner Losh<li><b><code>%x</code>: </b> represents all hexadecimal digits.</li>
95458e3e3a7aSWarner Losh
95468e3e3a7aSWarner Losh<li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character)
95478e3e3a7aSWarner Loshrepresents the character <em>x</em>.
95488e3e3a7aSWarner LoshThis is the standard way to escape the magic characters.
95498e3e3a7aSWarner LoshAny non-alphanumeric character
95508e3e3a7aSWarner Losh(including all punctuation characters, even the non-magical)
95510495ed39SKyle Evanscan be preceded by a '<code>%</code>' to represent itself in a pattern.
95528e3e3a7aSWarner Losh</li>
95538e3e3a7aSWarner Losh
95548e3e3a7aSWarner Losh<li><b><code>[<em>set</em>]</code>: </b>
95558e3e3a7aSWarner Loshrepresents the class which is the union of all
95568e3e3a7aSWarner Loshcharacters in <em>set</em>.
95578e3e3a7aSWarner LoshA range of characters can be specified by
95588e3e3a7aSWarner Loshseparating the end characters of the range,
95598e3e3a7aSWarner Loshin ascending order, with a '<code>-</code>'.
95608e3e3a7aSWarner LoshAll classes <code>%</code><em>x</em> described above can also be used as
95618e3e3a7aSWarner Loshcomponents in <em>set</em>.
95628e3e3a7aSWarner LoshAll other characters in <em>set</em> represent themselves.
95638e3e3a7aSWarner LoshFor example, <code>[%w_]</code> (or <code>[_%w]</code>)
95648e3e3a7aSWarner Loshrepresents all alphanumeric characters plus the underscore,
95658e3e3a7aSWarner Losh<code>[0-7]</code> represents the octal digits,
95668e3e3a7aSWarner Loshand <code>[0-7%l%-]</code> represents the octal digits plus
95678e3e3a7aSWarner Loshthe lowercase letters plus the '<code>-</code>' character.
95688e3e3a7aSWarner Losh
95698e3e3a7aSWarner Losh
95708e3e3a7aSWarner Losh<p>
95718e3e3a7aSWarner LoshYou can put a closing square bracket in a set
95728e3e3a7aSWarner Loshby positioning it as the first character in the set.
9573e112e9d2SKyle EvansYou can put a hyphen in a set
95748e3e3a7aSWarner Loshby positioning it as the first or the last character in the set.
95758e3e3a7aSWarner Losh(You can also use an escape for both cases.)
95768e3e3a7aSWarner Losh
95778e3e3a7aSWarner Losh
95788e3e3a7aSWarner Losh<p>
95798e3e3a7aSWarner LoshThe interaction between ranges and classes is not defined.
95808e3e3a7aSWarner LoshTherefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code>
95818e3e3a7aSWarner Loshhave no meaning.
95828e3e3a7aSWarner Losh</li>
95838e3e3a7aSWarner Losh
95848e3e3a7aSWarner Losh<li><b><code>[^<em>set</em>]</code>: </b>
95858e3e3a7aSWarner Loshrepresents the complement of <em>set</em>,
95868e3e3a7aSWarner Loshwhere <em>set</em> is interpreted as above.
95878e3e3a7aSWarner Losh</li>
95888e3e3a7aSWarner Losh
95898e3e3a7aSWarner Losh</ul><p>
95908e3e3a7aSWarner LoshFor all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.),
95918e3e3a7aSWarner Loshthe corresponding uppercase letter represents the complement of the class.
95928e3e3a7aSWarner LoshFor instance, <code>%S</code> represents all non-space characters.
95938e3e3a7aSWarner Losh
95948e3e3a7aSWarner Losh
95958e3e3a7aSWarner Losh<p>
95968e3e3a7aSWarner LoshThe definitions of letter, space, and other character groups
95978e3e3a7aSWarner Loshdepend on the current locale.
95988e3e3a7aSWarner LoshIn particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>.
95998e3e3a7aSWarner Losh
96008e3e3a7aSWarner Losh
96018e3e3a7aSWarner Losh
96028e3e3a7aSWarner Losh
96038e3e3a7aSWarner Losh
96048e3e3a7aSWarner Losh<h4>Pattern Item:</h4><p>
96058e3e3a7aSWarner LoshA <em>pattern item</em> can be
96068e3e3a7aSWarner Losh
96078e3e3a7aSWarner Losh<ul>
96088e3e3a7aSWarner Losh
96098e3e3a7aSWarner Losh<li>
96108e3e3a7aSWarner Losha single character class,
96118e3e3a7aSWarner Loshwhich matches any single character in the class;
96128e3e3a7aSWarner Losh</li>
96138e3e3a7aSWarner Losh
96148e3e3a7aSWarner Losh<li>
96158e3e3a7aSWarner Losha single character class followed by '<code>*</code>',
96160495ed39SKyle Evanswhich matches sequences of zero or more characters in the class.
96178e3e3a7aSWarner LoshThese repetition items will always match the longest possible sequence;
96188e3e3a7aSWarner Losh</li>
96198e3e3a7aSWarner Losh
96208e3e3a7aSWarner Losh<li>
96218e3e3a7aSWarner Losha single character class followed by '<code>+</code>',
96220495ed39SKyle Evanswhich matches sequences of one or more characters in the class.
96238e3e3a7aSWarner LoshThese repetition items will always match the longest possible sequence;
96248e3e3a7aSWarner Losh</li>
96258e3e3a7aSWarner Losh
96268e3e3a7aSWarner Losh<li>
96278e3e3a7aSWarner Losha single character class followed by '<code>-</code>',
96280495ed39SKyle Evanswhich also matches sequences of zero or more characters in the class.
96298e3e3a7aSWarner LoshUnlike '<code>*</code>',
96308e3e3a7aSWarner Loshthese repetition items will always match the shortest possible sequence;
96318e3e3a7aSWarner Losh</li>
96328e3e3a7aSWarner Losh
96338e3e3a7aSWarner Losh<li>
96348e3e3a7aSWarner Losha single character class followed by '<code>?</code>',
96358e3e3a7aSWarner Loshwhich matches zero or one occurrence of a character in the class.
96368e3e3a7aSWarner LoshIt always matches one occurrence if possible;
96378e3e3a7aSWarner Losh</li>
96388e3e3a7aSWarner Losh
96398e3e3a7aSWarner Losh<li>
96408e3e3a7aSWarner Losh<code>%<em>n</em></code>, for <em>n</em> between 1 and 9;
96418e3e3a7aSWarner Loshsuch item matches a substring equal to the <em>n</em>-th captured string
96428e3e3a7aSWarner Losh(see below);
96438e3e3a7aSWarner Losh</li>
96448e3e3a7aSWarner Losh
96458e3e3a7aSWarner Losh<li>
96468e3e3a7aSWarner Losh<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters;
96478e3e3a7aSWarner Loshsuch item matches strings that start with&nbsp;<em>x</em>, end with&nbsp;<em>y</em>,
96488e3e3a7aSWarner Loshand where the <em>x</em> and <em>y</em> are <em>balanced</em>.
96498e3e3a7aSWarner LoshThis means that, if one reads the string from left to right,
96508e3e3a7aSWarner Loshcounting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>,
96518e3e3a7aSWarner Loshthe ending <em>y</em> is the first <em>y</em> where the count reaches 0.
96528e3e3a7aSWarner LoshFor instance, the item <code>%b()</code> matches expressions with
96538e3e3a7aSWarner Loshbalanced parentheses.
96548e3e3a7aSWarner Losh</li>
96558e3e3a7aSWarner Losh
96568e3e3a7aSWarner Losh<li>
96578e3e3a7aSWarner Losh<code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>;
96588e3e3a7aSWarner Loshsuch item matches an empty string at any position such that
96598e3e3a7aSWarner Loshthe next character belongs to <em>set</em>
96608e3e3a7aSWarner Loshand the previous character does not belong to <em>set</em>.
96618e3e3a7aSWarner LoshThe set <em>set</em> is interpreted as previously described.
96628e3e3a7aSWarner LoshThe beginning and the end of the subject are handled as if
96638e3e3a7aSWarner Loshthey were the character '<code>\0</code>'.
96648e3e3a7aSWarner Losh</li>
96658e3e3a7aSWarner Losh
96668e3e3a7aSWarner Losh</ul>
96678e3e3a7aSWarner Losh
96688e3e3a7aSWarner Losh
96698e3e3a7aSWarner Losh
96708e3e3a7aSWarner Losh
96718e3e3a7aSWarner Losh<h4>Pattern:</h4><p>
96728e3e3a7aSWarner LoshA <em>pattern</em> is a sequence of pattern items.
96738e3e3a7aSWarner LoshA caret '<code>^</code>' at the beginning of a pattern anchors the match at the
96748e3e3a7aSWarner Loshbeginning of the subject string.
96758e3e3a7aSWarner LoshA '<code>$</code>' at the end of a pattern anchors the match at the
96768e3e3a7aSWarner Loshend of the subject string.
96778e3e3a7aSWarner LoshAt other positions,
96788e3e3a7aSWarner Losh'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves.
96798e3e3a7aSWarner Losh
96808e3e3a7aSWarner Losh
96818e3e3a7aSWarner Losh
96828e3e3a7aSWarner Losh
96838e3e3a7aSWarner Losh
96848e3e3a7aSWarner Losh<h4>Captures:</h4><p>
96858e3e3a7aSWarner LoshA pattern can contain sub-patterns enclosed in parentheses;
96868e3e3a7aSWarner Loshthey describe <em>captures</em>.
96878e3e3a7aSWarner LoshWhen a match succeeds, the substrings of the subject string
96888e3e3a7aSWarner Loshthat match captures are stored (<em>captured</em>) for future use.
96898e3e3a7aSWarner LoshCaptures are numbered according to their left parentheses.
96908e3e3a7aSWarner LoshFor instance, in the pattern <code>"(a*(.)%w(%s*))"</code>,
96918e3e3a7aSWarner Loshthe part of the string matching <code>"a*(.)%w(%s*)"</code> is
96920495ed39SKyle Evansstored as the first capture, and therefore has number&nbsp;1;
96938e3e3a7aSWarner Loshthe character matching "<code>.</code>" is captured with number&nbsp;2,
96948e3e3a7aSWarner Loshand the part matching "<code>%s*</code>" has number&nbsp;3.
96958e3e3a7aSWarner Losh
96968e3e3a7aSWarner Losh
96978e3e3a7aSWarner Losh<p>
96980495ed39SKyle EvansAs a special case, the capture <code>()</code> captures
96998e3e3a7aSWarner Loshthe current string position (a number).
97008e3e3a7aSWarner LoshFor instance, if we apply the pattern <code>"()aa()"</code> on the
97018e3e3a7aSWarner Loshstring <code>"flaaap"</code>, there will be two captures: 3&nbsp;and&nbsp;5.
97028e3e3a7aSWarner Losh
97038e3e3a7aSWarner Losh
97048e3e3a7aSWarner Losh
97058e3e3a7aSWarner Losh
97068e3e3a7aSWarner Losh
97070495ed39SKyle Evans<h4>Multiple matches:</h4><p>
97080495ed39SKyle EvansThe function <a href="#pdf-string.gsub"><code>string.gsub</code></a> and the iterator <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>
97090495ed39SKyle Evansmatch multiple occurrences of the given pattern in the subject.
97100495ed39SKyle EvansFor these functions,
97110495ed39SKyle Evansa new match is considered valid only
97120495ed39SKyle Evansif it ends at least one byte after the end of the previous match.
97130495ed39SKyle EvansIn other words, the pattern machine never accepts the
97140495ed39SKyle Evansempty string as a match immediately after another match.
97150495ed39SKyle EvansAs an example,
97160495ed39SKyle Evansconsider the results of the following code:
97170495ed39SKyle Evans
97180495ed39SKyle Evans<pre>
97190495ed39SKyle Evans     &gt; string.gsub("abc", "()a*()", print);
97200495ed39SKyle Evans     --&gt; 1   2
97210495ed39SKyle Evans     --&gt; 3   3
97220495ed39SKyle Evans     --&gt; 4   4
97230495ed39SKyle Evans</pre><p>
97240495ed39SKyle EvansThe second and third results come from Lua matching an empty
97250495ed39SKyle Evansstring after '<code>b</code>' and another one after '<code>c</code>'.
97260495ed39SKyle EvansLua does not match an empty string after '<code>a</code>',
97270495ed39SKyle Evansbecause it would end at the same position of the previous match.
97280495ed39SKyle Evans
97290495ed39SKyle Evans
97300495ed39SKyle Evans
97310495ed39SKyle Evans
97320495ed39SKyle Evans
97338e3e3a7aSWarner Losh
97348e3e3a7aSWarner Losh
97358e3e3a7aSWarner Losh<h3>6.4.2 &ndash; <a name="6.4.2">Format Strings for Pack and Unpack</a></h3>
97368e3e3a7aSWarner Losh
97378e3e3a7aSWarner Losh<p>
97388e3e3a7aSWarner LoshThe first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>,
97398e3e3a7aSWarner Losh<a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a>
97408e3e3a7aSWarner Loshis a format string,
97418e3e3a7aSWarner Loshwhich describes the layout of the structure being created or read.
97428e3e3a7aSWarner Losh
97438e3e3a7aSWarner Losh
97448e3e3a7aSWarner Losh<p>
97458e3e3a7aSWarner LoshA format string is a sequence of conversion options.
97468e3e3a7aSWarner LoshThe conversion options are as follows:
97478e3e3a7aSWarner Losh
97488e3e3a7aSWarner Losh<ul>
97498e3e3a7aSWarner Losh<li><b><code>&lt;</code>: </b>sets little endian</li>
97508e3e3a7aSWarner Losh<li><b><code>&gt;</code>: </b>sets big endian</li>
97518e3e3a7aSWarner Losh<li><b><code>=</code>: </b>sets native endian</li>
97528e3e3a7aSWarner Losh<li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code>
97538e3e3a7aSWarner Losh(default is native alignment)</li>
97548e3e3a7aSWarner Losh<li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li>
97558e3e3a7aSWarner Losh<li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li>
97568e3e3a7aSWarner Losh<li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li>
97578e3e3a7aSWarner Losh<li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li>
97588e3e3a7aSWarner Losh<li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li>
97598e3e3a7aSWarner Losh<li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li>
97608e3e3a7aSWarner Losh<li><b><code>j</code>: </b>a <code>lua_Integer</code></li>
97618e3e3a7aSWarner Losh<li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li>
97628e3e3a7aSWarner Losh<li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li>
97638e3e3a7aSWarner Losh<li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes
97648e3e3a7aSWarner Losh(default is native size)</li>
97658e3e3a7aSWarner Losh<li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes
97668e3e3a7aSWarner Losh(default is native size)</li>
97678e3e3a7aSWarner Losh<li><b><code>f</code>: </b>a <code>float</code> (native size)</li>
97688e3e3a7aSWarner Losh<li><b><code>d</code>: </b>a <code>double</code> (native size)</li>
97698e3e3a7aSWarner Losh<li><b><code>n</code>: </b>a <code>lua_Number</code></li>
97708e3e3a7aSWarner Losh<li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li>
97718e3e3a7aSWarner Losh<li><b><code>z</code>: </b>a zero-terminated string</li>
97728e3e3a7aSWarner Losh<li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length
97738e3e3a7aSWarner Loshcoded as an unsigned integer with <code>n</code> bytes
97748e3e3a7aSWarner Losh(default is a <code>size_t</code>)</li>
97758e3e3a7aSWarner Losh<li><b><code>x</code>: </b>one byte of padding</li>
97768e3e3a7aSWarner Losh<li><b><code>X<em>op</em></code>: </b>an empty item that aligns
97778e3e3a7aSWarner Loshaccording to option <code>op</code>
97788e3e3a7aSWarner Losh(which is otherwise ignored)</li>
97790495ed39SKyle Evans<li><b>'<code> </code>': </b>(space) ignored</li>
97808e3e3a7aSWarner Losh</ul><p>
97818e3e3a7aSWarner Losh(A "<code>[<em>n</em>]</code>" means an optional integral numeral.)
97828e3e3a7aSWarner LoshExcept for padding, spaces, and configurations
97838e3e3a7aSWarner Losh(options "<code>xX &lt;=&gt;!</code>"),
97840495ed39SKyle Evanseach option corresponds to an argument in <a href="#pdf-string.pack"><code>string.pack</code></a>
97850495ed39SKyle Evansor a result in <a href="#pdf-string.unpack"><code>string.unpack</code></a>.
97868e3e3a7aSWarner Losh
97878e3e3a7aSWarner Losh
97888e3e3a7aSWarner Losh<p>
97898e3e3a7aSWarner LoshFor options "<code>!<em>n</em></code>", "<code>s<em>n</em></code>", "<code>i<em>n</em></code>", and "<code>I<em>n</em></code>",
97908e3e3a7aSWarner Losh<code>n</code> can be any integer between 1 and 16.
97918e3e3a7aSWarner LoshAll integral options check overflows;
97928e3e3a7aSWarner Losh<a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size;
97938e3e3a7aSWarner Losh<a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer.
97940495ed39SKyle EvansFor the unsigned options,
97950495ed39SKyle EvansLua integers are treated as unsigned values too.
97968e3e3a7aSWarner Losh
97978e3e3a7aSWarner Losh
97988e3e3a7aSWarner Losh<p>
97998e3e3a7aSWarner LoshAny format string starts as if prefixed by "<code>!1=</code>",
98008e3e3a7aSWarner Loshthat is,
98018e3e3a7aSWarner Loshwith maximum alignment of 1 (no alignment)
98028e3e3a7aSWarner Loshand native endianness.
98038e3e3a7aSWarner Losh
98048e3e3a7aSWarner Losh
98058e3e3a7aSWarner Losh<p>
98060495ed39SKyle EvansNative endianness assumes that the whole system is
98070495ed39SKyle Evanseither big or little endian.
98080495ed39SKyle EvansThe packing functions will not emulate correctly the behavior
98090495ed39SKyle Evansof mixed-endian formats.
98100495ed39SKyle Evans
98110495ed39SKyle Evans
98120495ed39SKyle Evans<p>
98138e3e3a7aSWarner LoshAlignment works as follows:
98148e3e3a7aSWarner LoshFor each option,
98158e3e3a7aSWarner Loshthe format gets extra padding until the data starts
98168e3e3a7aSWarner Loshat an offset that is a multiple of the minimum between the
98178e3e3a7aSWarner Loshoption size and the maximum alignment;
98188e3e3a7aSWarner Loshthis minimum must be a power of 2.
98198e3e3a7aSWarner LoshOptions "<code>c</code>" and "<code>z</code>" are not aligned;
98208e3e3a7aSWarner Loshoption "<code>s</code>" follows the alignment of its starting integer.
98218e3e3a7aSWarner Losh
98228e3e3a7aSWarner Losh
98238e3e3a7aSWarner Losh<p>
98248e3e3a7aSWarner LoshAll padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a>
98250495ed39SKyle Evansand ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>.
98268e3e3a7aSWarner Losh
98278e3e3a7aSWarner Losh
98288e3e3a7aSWarner Losh
98298e3e3a7aSWarner Losh
98308e3e3a7aSWarner Losh
98318e3e3a7aSWarner Losh
98328e3e3a7aSWarner Losh
98338e3e3a7aSWarner Losh<h2>6.5 &ndash; <a name="6.5">UTF-8 Support</a></h2>
98348e3e3a7aSWarner Losh
98358e3e3a7aSWarner Losh<p>
98368e3e3a7aSWarner LoshThis library provides basic support for UTF-8 encoding.
98378e3e3a7aSWarner LoshIt provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>.
98388e3e3a7aSWarner LoshThis library does not provide any support for Unicode other
98398e3e3a7aSWarner Loshthan the handling of the encoding.
98408e3e3a7aSWarner LoshAny operation that needs the meaning of a character,
98418e3e3a7aSWarner Loshsuch as character classification, is outside its scope.
98428e3e3a7aSWarner Losh
98438e3e3a7aSWarner Losh
98448e3e3a7aSWarner Losh<p>
98458e3e3a7aSWarner LoshUnless stated otherwise,
98468e3e3a7aSWarner Loshall functions that expect a byte position as a parameter
98478e3e3a7aSWarner Loshassume that the given position is either the start of a byte sequence
98488e3e3a7aSWarner Loshor one plus the length of the subject string.
98498e3e3a7aSWarner LoshAs in the string library,
98508e3e3a7aSWarner Loshnegative indices count from the end of the string.
98518e3e3a7aSWarner Losh
98528e3e3a7aSWarner Losh
98538e3e3a7aSWarner Losh<p>
98540495ed39SKyle EvansFunctions that create byte sequences
98550495ed39SKyle Evansaccept all values up to <code>0x7FFFFFFF</code>,
98560495ed39SKyle Evansas defined in the original UTF-8 specification;
98570495ed39SKyle Evansthat implies byte sequences of up to six bytes.
98580495ed39SKyle Evans
98590495ed39SKyle Evans
98600495ed39SKyle Evans<p>
98610495ed39SKyle EvansFunctions that interpret byte sequences only accept
98620495ed39SKyle Evansvalid sequences (well formed and not overlong).
98630495ed39SKyle EvansBy default, they only accept byte sequences
98640495ed39SKyle Evansthat result in valid Unicode code points,
98650495ed39SKyle Evansrejecting values greater than <code>10FFFF</code> and surrogates.
98660495ed39SKyle EvansA boolean argument <code>lax</code>, when available,
98670495ed39SKyle Evanslifts these checks,
98680495ed39SKyle Evansso that all values up to <code>0x7FFFFFFF</code> are accepted.
98690495ed39SKyle Evans(Not well formed and overlong sequences are still rejected.)
98700495ed39SKyle Evans
98710495ed39SKyle Evans
98720495ed39SKyle Evans<p>
98738e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.char"><code>utf8.char (&middot;&middot;&middot;)</code></a></h3>
98740495ed39SKyle Evans
98750495ed39SKyle Evans
98760495ed39SKyle Evans<p>
98778e3e3a7aSWarner LoshReceives zero or more integers,
98788e3e3a7aSWarner Loshconverts each one to its corresponding UTF-8 byte sequence
98798e3e3a7aSWarner Loshand returns a string with the concatenation of all these sequences.
98808e3e3a7aSWarner Losh
98818e3e3a7aSWarner Losh
98828e3e3a7aSWarner Losh
98838e3e3a7aSWarner Losh
98848e3e3a7aSWarner Losh<p>
98858e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3>
98860495ed39SKyle Evans
98870495ed39SKyle Evans
98880495ed39SKyle Evans<p>
98890495ed39SKyle EvansThe pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xFD][\x80-\xBF]*</code>"
98908e3e3a7aSWarner Losh(see <a href="#6.4.1">&sect;6.4.1</a>),
98918e3e3a7aSWarner Loshwhich matches exactly one UTF-8 byte sequence,
98928e3e3a7aSWarner Loshassuming that the subject is a valid UTF-8 string.
98938e3e3a7aSWarner Losh
98948e3e3a7aSWarner Losh
98958e3e3a7aSWarner Losh
98968e3e3a7aSWarner Losh
98978e3e3a7aSWarner Losh<p>
98980495ed39SKyle Evans<hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s [, lax])</code></a></h3>
98998e3e3a7aSWarner Losh
99008e3e3a7aSWarner Losh
99018e3e3a7aSWarner Losh<p>
99028e3e3a7aSWarner LoshReturns values so that the construction
99038e3e3a7aSWarner Losh
99048e3e3a7aSWarner Losh<pre>
99058e3e3a7aSWarner Losh     for p, c in utf8.codes(s) do <em>body</em> end
99068e3e3a7aSWarner Losh</pre><p>
99070495ed39SKyle Evanswill iterate over all UTF-8 characters in string <code>s</code>,
99088e3e3a7aSWarner Loshwith <code>p</code> being the position (in bytes) and <code>c</code> the code point
99098e3e3a7aSWarner Loshof each character.
99108e3e3a7aSWarner LoshIt raises an error if it meets any invalid byte sequence.
99118e3e3a7aSWarner Losh
99128e3e3a7aSWarner Losh
99138e3e3a7aSWarner Losh
99148e3e3a7aSWarner Losh
99158e3e3a7aSWarner Losh<p>
99160495ed39SKyle Evans<hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j [, lax]]])</code></a></h3>
99170495ed39SKyle Evans
99180495ed39SKyle Evans
99190495ed39SKyle Evans<p>
99208e3e3a7aSWarner LoshReturns the code points (as integers) from all characters in <code>s</code>
99218e3e3a7aSWarner Loshthat start between byte position <code>i</code> and <code>j</code> (both included).
99228e3e3a7aSWarner LoshThe default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>.
99238e3e3a7aSWarner LoshIt raises an error if it meets any invalid byte sequence.
99248e3e3a7aSWarner Losh
99258e3e3a7aSWarner Losh
99268e3e3a7aSWarner Losh
99278e3e3a7aSWarner Losh
99288e3e3a7aSWarner Losh<p>
99290495ed39SKyle Evans<hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j [, lax]]])</code></a></h3>
99300495ed39SKyle Evans
99310495ed39SKyle Evans
99320495ed39SKyle Evans<p>
99338e3e3a7aSWarner LoshReturns the number of UTF-8 characters in string <code>s</code>
99348e3e3a7aSWarner Loshthat start between positions <code>i</code> and <code>j</code> (both inclusive).
99358e3e3a7aSWarner LoshThe default for <code>i</code> is 1 and for <code>j</code> is -1.
99368e3e3a7aSWarner LoshIf it finds any invalid byte sequence,
99370495ed39SKyle Evansreturns <b>fail</b> plus the position of the first invalid byte.
99388e3e3a7aSWarner Losh
99398e3e3a7aSWarner Losh
99408e3e3a7aSWarner Losh
99418e3e3a7aSWarner Losh
99428e3e3a7aSWarner Losh<p>
99438e3e3a7aSWarner Losh<hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3>
99440495ed39SKyle Evans
99450495ed39SKyle Evans
99460495ed39SKyle Evans<p>
99478e3e3a7aSWarner LoshReturns the position (in bytes) where the encoding of the
99488e3e3a7aSWarner Losh<code>n</code>-th character of <code>s</code>
99498e3e3a7aSWarner Losh(counting from position <code>i</code>) starts.
99508e3e3a7aSWarner LoshA negative <code>n</code> gets characters before position <code>i</code>.
99518e3e3a7aSWarner LoshThe default for <code>i</code> is 1 when <code>n</code> is non-negative
99528e3e3a7aSWarner Loshand <code>#s + 1</code> otherwise,
99538e3e3a7aSWarner Loshso that <code>utf8.offset(s, -n)</code> gets the offset of the
99548e3e3a7aSWarner Losh<code>n</code>-th character from the end of the string.
99558e3e3a7aSWarner LoshIf the specified character is neither in the subject
99568e3e3a7aSWarner Loshnor right after its end,
99570495ed39SKyle Evansthe function returns <b>fail</b>.
99588e3e3a7aSWarner Losh
99598e3e3a7aSWarner Losh
99608e3e3a7aSWarner Losh<p>
99618e3e3a7aSWarner LoshAs a special case,
99628e3e3a7aSWarner Loshwhen <code>n</code> is 0 the function returns the start of the encoding
99638e3e3a7aSWarner Loshof the character that contains the <code>i</code>-th byte of <code>s</code>.
99648e3e3a7aSWarner Losh
99658e3e3a7aSWarner Losh
99668e3e3a7aSWarner Losh<p>
99678e3e3a7aSWarner LoshThis function assumes that <code>s</code> is a valid UTF-8 string.
99688e3e3a7aSWarner Losh
99698e3e3a7aSWarner Losh
99708e3e3a7aSWarner Losh
99718e3e3a7aSWarner Losh
99728e3e3a7aSWarner Losh
99738e3e3a7aSWarner Losh
99748e3e3a7aSWarner Losh
99758e3e3a7aSWarner Losh<h2>6.6 &ndash; <a name="6.6">Table Manipulation</a></h2>
99768e3e3a7aSWarner Losh
99778e3e3a7aSWarner Losh<p>
99788e3e3a7aSWarner LoshThis library provides generic functions for table manipulation.
99798e3e3a7aSWarner LoshIt provides all its functions inside the table <a name="pdf-table"><code>table</code></a>.
99808e3e3a7aSWarner Losh
99818e3e3a7aSWarner Losh
99828e3e3a7aSWarner Losh<p>
99838e3e3a7aSWarner LoshRemember that, whenever an operation needs the length of a table,
99848e3e3a7aSWarner Loshall caveats about the length operator apply (see <a href="#3.4.7">&sect;3.4.7</a>).
99858e3e3a7aSWarner LoshAll functions ignore non-numeric keys
99868e3e3a7aSWarner Loshin the tables given as arguments.
99878e3e3a7aSWarner Losh
99888e3e3a7aSWarner Losh
99898e3e3a7aSWarner Losh<p>
99908e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3>
99918e3e3a7aSWarner Losh
99928e3e3a7aSWarner Losh
99938e3e3a7aSWarner Losh<p>
99948e3e3a7aSWarner LoshGiven a list where all elements are strings or numbers,
99958e3e3a7aSWarner Loshreturns the string <code>list[i]..sep..list[i+1] &middot;&middot;&middot; sep..list[j]</code>.
99968e3e3a7aSWarner LoshThe default value for <code>sep</code> is the empty string,
99978e3e3a7aSWarner Loshthe default for <code>i</code> is 1,
99988e3e3a7aSWarner Loshand the default for <code>j</code> is <code>#list</code>.
99998e3e3a7aSWarner LoshIf <code>i</code> is greater than <code>j</code>, returns the empty string.
100008e3e3a7aSWarner Losh
100018e3e3a7aSWarner Losh
100028e3e3a7aSWarner Losh
100038e3e3a7aSWarner Losh
100048e3e3a7aSWarner Losh<p>
100058e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3>
100068e3e3a7aSWarner Losh
100078e3e3a7aSWarner Losh
100088e3e3a7aSWarner Losh<p>
100098e3e3a7aSWarner LoshInserts element <code>value</code> at position <code>pos</code> in <code>list</code>,
100108e3e3a7aSWarner Loshshifting up the elements
100118e3e3a7aSWarner Losh<code>list[pos], list[pos+1], &middot;&middot;&middot;, list[#list]</code>.
100128e3e3a7aSWarner LoshThe default value for <code>pos</code> is <code>#list+1</code>,
100138e3e3a7aSWarner Loshso that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end
100140495ed39SKyle Evansof the list <code>t</code>.
100158e3e3a7aSWarner Losh
100168e3e3a7aSWarner Losh
100178e3e3a7aSWarner Losh
100188e3e3a7aSWarner Losh
100198e3e3a7aSWarner Losh<p>
100208e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3>
100218e3e3a7aSWarner Losh
100228e3e3a7aSWarner Losh
100238e3e3a7aSWarner Losh<p>
100240495ed39SKyle EvansMoves elements from the table <code>a1</code> to the table <code>a2</code>,
100258e3e3a7aSWarner Loshperforming the equivalent to the following
100268e3e3a7aSWarner Loshmultiple assignment:
100278e3e3a7aSWarner Losh<code>a2[t],&middot;&middot;&middot; = a1[f],&middot;&middot;&middot;,a1[e]</code>.
100288e3e3a7aSWarner LoshThe default for <code>a2</code> is <code>a1</code>.
100298e3e3a7aSWarner LoshThe destination range can overlap with the source range.
100308e3e3a7aSWarner LoshThe number of elements to be moved must fit in a Lua integer.
100318e3e3a7aSWarner Losh
100328e3e3a7aSWarner Losh
100338e3e3a7aSWarner Losh<p>
100348e3e3a7aSWarner LoshReturns the destination table <code>a2</code>.
100358e3e3a7aSWarner Losh
100368e3e3a7aSWarner Losh
100378e3e3a7aSWarner Losh
100388e3e3a7aSWarner Losh
100398e3e3a7aSWarner Losh<p>
100408e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.pack"><code>table.pack (&middot;&middot;&middot;)</code></a></h3>
100418e3e3a7aSWarner Losh
100428e3e3a7aSWarner Losh
100438e3e3a7aSWarner Losh<p>
10044e112e9d2SKyle EvansReturns a new table with all arguments stored into keys 1, 2, etc.
10045e112e9d2SKyle Evansand with a field "<code>n</code>" with the total number of arguments.
100460495ed39SKyle EvansNote that the resulting table may not be a sequence,
100470495ed39SKyle Evansif some arguments are <b>nil</b>.
100488e3e3a7aSWarner Losh
100498e3e3a7aSWarner Losh
100508e3e3a7aSWarner Losh
100518e3e3a7aSWarner Losh
100528e3e3a7aSWarner Losh<p>
100538e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3>
100548e3e3a7aSWarner Losh
100558e3e3a7aSWarner Losh
100568e3e3a7aSWarner Losh<p>
100578e3e3a7aSWarner LoshRemoves from <code>list</code> the element at position <code>pos</code>,
100588e3e3a7aSWarner Loshreturning the value of the removed element.
100598e3e3a7aSWarner LoshWhen <code>pos</code> is an integer between 1 and <code>#list</code>,
100608e3e3a7aSWarner Loshit shifts down the elements
100618e3e3a7aSWarner Losh<code>list[pos+1], list[pos+2], &middot;&middot;&middot;, list[#list]</code>
100628e3e3a7aSWarner Loshand erases element <code>list[#list]</code>;
100638e3e3a7aSWarner LoshThe index <code>pos</code> can also be 0 when <code>#list</code> is 0,
100640495ed39SKyle Evansor <code>#list + 1</code>.
100658e3e3a7aSWarner Losh
100668e3e3a7aSWarner Losh
100678e3e3a7aSWarner Losh<p>
100688e3e3a7aSWarner LoshThe default value for <code>pos</code> is <code>#list</code>,
100698e3e3a7aSWarner Loshso that a call <code>table.remove(l)</code> removes the last element
100700495ed39SKyle Evansof the list <code>l</code>.
100718e3e3a7aSWarner Losh
100728e3e3a7aSWarner Losh
100738e3e3a7aSWarner Losh
100748e3e3a7aSWarner Losh
100758e3e3a7aSWarner Losh<p>
100768e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3>
100778e3e3a7aSWarner Losh
100788e3e3a7aSWarner Losh
100798e3e3a7aSWarner Losh<p>
100800495ed39SKyle EvansSorts the list elements in a given order, <em>in-place</em>,
100818e3e3a7aSWarner Loshfrom <code>list[1]</code> to <code>list[#list]</code>.
100828e3e3a7aSWarner LoshIf <code>comp</code> is given,
100838e3e3a7aSWarner Loshthen it must be a function that receives two list elements
100848e3e3a7aSWarner Loshand returns true when the first element must come
100858c784bb8SWarner Loshbefore the second in the final order,
100868c784bb8SWarner Loshso that, after the sort,
100878c784bb8SWarner Losh<code>i &lt;= j</code> implies <code>not comp(list[j],list[i])</code>.
100888e3e3a7aSWarner LoshIf <code>comp</code> is not given,
100898e3e3a7aSWarner Loshthen the standard Lua operator <code>&lt;</code> is used instead.
100908e3e3a7aSWarner Losh
100918e3e3a7aSWarner Losh
100928e3e3a7aSWarner Losh<p>
100938c784bb8SWarner LoshThe <code>comp</code> function must define a consistent order;
100948c784bb8SWarner Loshmore formally, the function must define a strict weak order.
100958c784bb8SWarner Losh(A weak order is similar to a total order,
100968c784bb8SWarner Loshbut it can equate different elements for comparison purposes.)
100978e3e3a7aSWarner Losh
100988e3e3a7aSWarner Losh
100998e3e3a7aSWarner Losh<p>
101008e3e3a7aSWarner LoshThe sort algorithm is not stable:
101018c784bb8SWarner LoshDifferent elements considered equal by the given order
101028e3e3a7aSWarner Loshmay have their relative positions changed by the sort.
101038e3e3a7aSWarner Losh
101048e3e3a7aSWarner Losh
101058e3e3a7aSWarner Losh
101068e3e3a7aSWarner Losh
101078e3e3a7aSWarner Losh<p>
101088e3e3a7aSWarner Losh<hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3>
101098e3e3a7aSWarner Losh
101108e3e3a7aSWarner Losh
101118e3e3a7aSWarner Losh<p>
101128e3e3a7aSWarner LoshReturns the elements from the given list.
101138e3e3a7aSWarner LoshThis function is equivalent to
101148e3e3a7aSWarner Losh
101158e3e3a7aSWarner Losh<pre>
101168e3e3a7aSWarner Losh     return list[i], list[i+1], &middot;&middot;&middot;, list[j]
101178e3e3a7aSWarner Losh</pre><p>
101188e3e3a7aSWarner LoshBy default, <code>i</code> is&nbsp;1 and <code>j</code> is <code>#list</code>.
101198e3e3a7aSWarner Losh
101208e3e3a7aSWarner Losh
101218e3e3a7aSWarner Losh
101228e3e3a7aSWarner Losh
101238e3e3a7aSWarner Losh
101248e3e3a7aSWarner Losh
101258e3e3a7aSWarner Losh
101268e3e3a7aSWarner Losh<h2>6.7 &ndash; <a name="6.7">Mathematical Functions</a></h2>
101278e3e3a7aSWarner Losh
101288e3e3a7aSWarner Losh<p>
101298e3e3a7aSWarner LoshThis library provides basic mathematical functions.
101308e3e3a7aSWarner LoshIt provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>.
101318e3e3a7aSWarner LoshFunctions with the annotation "<code>integer/float</code>" give
101328e3e3a7aSWarner Loshinteger results for integer arguments
101330495ed39SKyle Evansand float results for non-integer arguments.
101340495ed39SKyle EvansThe rounding functions
101350495ed39SKyle Evans<a href="#pdf-math.ceil"><code>math.ceil</code></a>, <a href="#pdf-math.floor"><code>math.floor</code></a>, and <a href="#pdf-math.modf"><code>math.modf</code></a>
101368e3e3a7aSWarner Loshreturn an integer when the result fits in the range of an integer,
101378e3e3a7aSWarner Loshor a float otherwise.
101388e3e3a7aSWarner Losh
101398e3e3a7aSWarner Losh
101408e3e3a7aSWarner Losh<p>
101418e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3>
101428e3e3a7aSWarner Losh
101438e3e3a7aSWarner Losh
101448e3e3a7aSWarner Losh<p>
101450495ed39SKyle EvansReturns the maximum value between <code>x</code> and <code>-x</code>. (integer/float)
101468e3e3a7aSWarner Losh
101478e3e3a7aSWarner Losh
101488e3e3a7aSWarner Losh
101498e3e3a7aSWarner Losh
101508e3e3a7aSWarner Losh<p>
101518e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3>
101528e3e3a7aSWarner Losh
101538e3e3a7aSWarner Losh
101548e3e3a7aSWarner Losh<p>
101558e3e3a7aSWarner LoshReturns the arc cosine of <code>x</code> (in radians).
101568e3e3a7aSWarner Losh
101578e3e3a7aSWarner Losh
101588e3e3a7aSWarner Losh
101598e3e3a7aSWarner Losh
101608e3e3a7aSWarner Losh<p>
101618e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3>
101628e3e3a7aSWarner Losh
101638e3e3a7aSWarner Losh
101648e3e3a7aSWarner Losh<p>
101658e3e3a7aSWarner LoshReturns the arc sine of <code>x</code> (in radians).
101668e3e3a7aSWarner Losh
101678e3e3a7aSWarner Losh
101688e3e3a7aSWarner Losh
101698e3e3a7aSWarner Losh
101708e3e3a7aSWarner Losh<p>
101718e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3>
101728e3e3a7aSWarner Losh
101738e3e3a7aSWarner Losh
101748e3e3a7aSWarner Losh<p>
101758e3e3a7aSWarner Losh
101768e3e3a7aSWarner LoshReturns the arc tangent of <code>y/x</code> (in radians),
10177*a9490b81SWarner Loshusing the signs of both arguments to find the
101788e3e3a7aSWarner Loshquadrant of the result.
101790495ed39SKyle EvansIt also handles correctly the case of <code>x</code> being zero.
101808e3e3a7aSWarner Losh
101818e3e3a7aSWarner Losh
101828e3e3a7aSWarner Losh<p>
101838e3e3a7aSWarner LoshThe default value for <code>x</code> is 1,
101848e3e3a7aSWarner Loshso that the call <code>math.atan(y)</code>
101858e3e3a7aSWarner Loshreturns the arc tangent of <code>y</code>.
101868e3e3a7aSWarner Losh
101878e3e3a7aSWarner Losh
101888e3e3a7aSWarner Losh
101898e3e3a7aSWarner Losh
101908e3e3a7aSWarner Losh<p>
101918e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3>
101928e3e3a7aSWarner Losh
101938e3e3a7aSWarner Losh
101948e3e3a7aSWarner Losh<p>
101950495ed39SKyle EvansReturns the smallest integral value greater than or equal to <code>x</code>.
101968e3e3a7aSWarner Losh
101978e3e3a7aSWarner Losh
101988e3e3a7aSWarner Losh
101998e3e3a7aSWarner Losh
102008e3e3a7aSWarner Losh<p>
102018e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3>
102028e3e3a7aSWarner Losh
102038e3e3a7aSWarner Losh
102048e3e3a7aSWarner Losh<p>
102058e3e3a7aSWarner LoshReturns the cosine of <code>x</code> (assumed to be in radians).
102068e3e3a7aSWarner Losh
102078e3e3a7aSWarner Losh
102088e3e3a7aSWarner Losh
102098e3e3a7aSWarner Losh
102108e3e3a7aSWarner Losh<p>
102118e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3>
102128e3e3a7aSWarner Losh
102138e3e3a7aSWarner Losh
102148e3e3a7aSWarner Losh<p>
102158e3e3a7aSWarner LoshConverts the angle <code>x</code> from radians to degrees.
102168e3e3a7aSWarner Losh
102178e3e3a7aSWarner Losh
102188e3e3a7aSWarner Losh
102198e3e3a7aSWarner Losh
102208e3e3a7aSWarner Losh<p>
102218e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3>
102228e3e3a7aSWarner Losh
102238e3e3a7aSWarner Losh
102248e3e3a7aSWarner Losh<p>
102258e3e3a7aSWarner LoshReturns the value <em>e<sup>x</sup></em>
102268e3e3a7aSWarner Losh(where <code>e</code> is the base of natural logarithms).
102278e3e3a7aSWarner Losh
102288e3e3a7aSWarner Losh
102298e3e3a7aSWarner Losh
102308e3e3a7aSWarner Losh
102318e3e3a7aSWarner Losh<p>
102328e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3>
102338e3e3a7aSWarner Losh
102348e3e3a7aSWarner Losh
102358e3e3a7aSWarner Losh<p>
102360495ed39SKyle EvansReturns the largest integral value less than or equal to <code>x</code>.
102378e3e3a7aSWarner Losh
102388e3e3a7aSWarner Losh
102398e3e3a7aSWarner Losh
102408e3e3a7aSWarner Losh
102418e3e3a7aSWarner Losh<p>
102428e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3>
102438e3e3a7aSWarner Losh
102448e3e3a7aSWarner Losh
102458e3e3a7aSWarner Losh<p>
102468e3e3a7aSWarner LoshReturns the remainder of the division of <code>x</code> by <code>y</code>
102478e3e3a7aSWarner Loshthat rounds the quotient towards zero. (integer/float)
102488e3e3a7aSWarner Losh
102498e3e3a7aSWarner Losh
102508e3e3a7aSWarner Losh
102518e3e3a7aSWarner Losh
102528e3e3a7aSWarner Losh<p>
102538e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3>
102548e3e3a7aSWarner Losh
102558e3e3a7aSWarner Losh
102568e3e3a7aSWarner Losh<p>
102578e3e3a7aSWarner LoshThe float value <code>HUGE_VAL</code>,
102580495ed39SKyle Evansa value greater than any other numeric value.
102598e3e3a7aSWarner Losh
102608e3e3a7aSWarner Losh
102618e3e3a7aSWarner Losh
102628e3e3a7aSWarner Losh
102638e3e3a7aSWarner Losh<p>
102648e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3>
102658e3e3a7aSWarner Losh
102668e3e3a7aSWarner Losh
102678e3e3a7aSWarner Losh<p>
102688e3e3a7aSWarner LoshReturns the logarithm of <code>x</code> in the given base.
102698e3e3a7aSWarner LoshThe default for <code>base</code> is <em>e</em>
102708e3e3a7aSWarner Losh(so that the function returns the natural logarithm of <code>x</code>).
102718e3e3a7aSWarner Losh
102728e3e3a7aSWarner Losh
102738e3e3a7aSWarner Losh
102748e3e3a7aSWarner Losh
102758e3e3a7aSWarner Losh<p>
102768e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.max"><code>math.max (x, &middot;&middot;&middot;)</code></a></h3>
102778e3e3a7aSWarner Losh
102788e3e3a7aSWarner Losh
102798e3e3a7aSWarner Losh<p>
102808e3e3a7aSWarner LoshReturns the argument with the maximum value,
102810495ed39SKyle Evansaccording to the Lua operator <code>&lt;</code>.
102828e3e3a7aSWarner Losh
102838e3e3a7aSWarner Losh
102848e3e3a7aSWarner Losh
102858e3e3a7aSWarner Losh
102868e3e3a7aSWarner Losh<p>
102878e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3>
102888e3e3a7aSWarner LoshAn integer with the maximum value for an integer.
102898e3e3a7aSWarner Losh
102908e3e3a7aSWarner Losh
102918e3e3a7aSWarner Losh
102928e3e3a7aSWarner Losh
102938e3e3a7aSWarner Losh<p>
102948e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.min"><code>math.min (x, &middot;&middot;&middot;)</code></a></h3>
102958e3e3a7aSWarner Losh
102968e3e3a7aSWarner Losh
102978e3e3a7aSWarner Losh<p>
102988e3e3a7aSWarner LoshReturns the argument with the minimum value,
102990495ed39SKyle Evansaccording to the Lua operator <code>&lt;</code>.
103008e3e3a7aSWarner Losh
103018e3e3a7aSWarner Losh
103028e3e3a7aSWarner Losh
103038e3e3a7aSWarner Losh
103048e3e3a7aSWarner Losh<p>
103058e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3>
103068e3e3a7aSWarner LoshAn integer with the minimum value for an integer.
103078e3e3a7aSWarner Losh
103088e3e3a7aSWarner Losh
103098e3e3a7aSWarner Losh
103108e3e3a7aSWarner Losh
103118e3e3a7aSWarner Losh<p>
103128e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3>
103138e3e3a7aSWarner Losh
103148e3e3a7aSWarner Losh
103158e3e3a7aSWarner Losh<p>
103168e3e3a7aSWarner LoshReturns the integral part of <code>x</code> and the fractional part of <code>x</code>.
103178e3e3a7aSWarner LoshIts second result is always a float.
103188e3e3a7aSWarner Losh
103198e3e3a7aSWarner Losh
103208e3e3a7aSWarner Losh
103218e3e3a7aSWarner Losh
103228e3e3a7aSWarner Losh<p>
103238e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3>
103248e3e3a7aSWarner Losh
103258e3e3a7aSWarner Losh
103268e3e3a7aSWarner Losh<p>
103278e3e3a7aSWarner LoshThe value of <em>&pi;</em>.
103288e3e3a7aSWarner Losh
103298e3e3a7aSWarner Losh
103308e3e3a7aSWarner Losh
103318e3e3a7aSWarner Losh
103328e3e3a7aSWarner Losh<p>
103338e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3>
103348e3e3a7aSWarner Losh
103358e3e3a7aSWarner Losh
103368e3e3a7aSWarner Losh<p>
103378e3e3a7aSWarner LoshConverts the angle <code>x</code> from degrees to radians.
103388e3e3a7aSWarner Losh
103398e3e3a7aSWarner Losh
103408e3e3a7aSWarner Losh
103418e3e3a7aSWarner Losh
103428e3e3a7aSWarner Losh<p>
103438e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3>
103448e3e3a7aSWarner Losh
103458e3e3a7aSWarner Losh
103468e3e3a7aSWarner Losh<p>
103478e3e3a7aSWarner LoshWhen called without arguments,
103488e3e3a7aSWarner Loshreturns a pseudo-random float with uniform distribution
103498e3e3a7aSWarner Loshin the range  <em>[0,1)</em>.
103508e3e3a7aSWarner LoshWhen called with two integers <code>m</code> and <code>n</code>,
103518e3e3a7aSWarner Losh<code>math.random</code> returns a pseudo-random integer
103528e3e3a7aSWarner Loshwith uniform distribution in the range <em>[m, n]</em>.
103530495ed39SKyle EvansThe call <code>math.random(n)</code>, for a positive <code>n</code>,
103540495ed39SKyle Evansis equivalent to <code>math.random(1,n)</code>.
103550495ed39SKyle EvansThe call <code>math.random(0)</code> produces an integer with
103560495ed39SKyle Evansall bits (pseudo)random.
103578e3e3a7aSWarner Losh
103588e3e3a7aSWarner Losh
103598e3e3a7aSWarner Losh<p>
103600495ed39SKyle EvansThis function uses the <code>xoshiro256**</code> algorithm to produce
103610495ed39SKyle Evanspseudo-random 64-bit integers,
103620495ed39SKyle Evanswhich are the results of calls with argument&nbsp;0.
103630495ed39SKyle EvansOther results (ranges and floats)
103640495ed39SKyle Evansare unbiased extracted from these integers.
103650495ed39SKyle Evans
103660495ed39SKyle Evans
103670495ed39SKyle Evans<p>
103680495ed39SKyle EvansLua initializes its pseudo-random generator with the equivalent of
103690495ed39SKyle Evansa call to <a href="#pdf-math.randomseed"><code>math.randomseed</code></a> with no arguments,
103700495ed39SKyle Evansso that <code>math.random</code> should generate
103710495ed39SKyle Evansdifferent sequences of results each time the program runs.
103728e3e3a7aSWarner Losh
103738e3e3a7aSWarner Losh
103748e3e3a7aSWarner Losh
103758e3e3a7aSWarner Losh
103768e3e3a7aSWarner Losh<p>
103770495ed39SKyle Evans<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed ([x [, y]])</code></a></h3>
103788e3e3a7aSWarner Losh
103798e3e3a7aSWarner Losh
103808e3e3a7aSWarner Losh<p>
103810495ed39SKyle EvansWhen called with at least one argument,
103820495ed39SKyle Evansthe integer parameters <code>x</code> and <code>y</code> are
103830495ed39SKyle Evansjoined into a 128-bit <em>seed</em> that
103840495ed39SKyle Evansis used to reinitialize the pseudo-random generator;
103858e3e3a7aSWarner Loshequal seeds produce equal sequences of numbers.
103860495ed39SKyle EvansThe default for <code>y</code> is zero.
103870495ed39SKyle Evans
103880495ed39SKyle Evans
103890495ed39SKyle Evans<p>
103900495ed39SKyle EvansWhen called with no arguments,
103910495ed39SKyle EvansLua generates a seed with
103920495ed39SKyle Evansa weak attempt for randomness.
103930495ed39SKyle Evans
103940495ed39SKyle Evans
103950495ed39SKyle Evans<p>
103960495ed39SKyle EvansThis function returns the two seed components
103970495ed39SKyle Evansthat were effectively used,
103980495ed39SKyle Evansso that setting them again repeats the sequence.
103990495ed39SKyle Evans
104000495ed39SKyle Evans
104010495ed39SKyle Evans<p>
104020495ed39SKyle EvansTo ensure a required level of randomness to the initial state
104030495ed39SKyle Evans(or contrarily, to have a deterministic sequence,
104040495ed39SKyle Evansfor instance when debugging a program),
104050495ed39SKyle Evansyou should call <a href="#pdf-math.randomseed"><code>math.randomseed</code></a> with explicit arguments.
104068e3e3a7aSWarner Losh
104078e3e3a7aSWarner Losh
104088e3e3a7aSWarner Losh
104098e3e3a7aSWarner Losh
104108e3e3a7aSWarner Losh<p>
104118e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3>
104128e3e3a7aSWarner Losh
104138e3e3a7aSWarner Losh
104148e3e3a7aSWarner Losh<p>
104158e3e3a7aSWarner LoshReturns the sine of <code>x</code> (assumed to be in radians).
104168e3e3a7aSWarner Losh
104178e3e3a7aSWarner Losh
104188e3e3a7aSWarner Losh
104198e3e3a7aSWarner Losh
104208e3e3a7aSWarner Losh<p>
104218e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3>
104228e3e3a7aSWarner Losh
104238e3e3a7aSWarner Losh
104248e3e3a7aSWarner Losh<p>
104258e3e3a7aSWarner LoshReturns the square root of <code>x</code>.
104268e3e3a7aSWarner Losh(You can also use the expression <code>x^0.5</code> to compute this value.)
104278e3e3a7aSWarner Losh
104288e3e3a7aSWarner Losh
104298e3e3a7aSWarner Losh
104308e3e3a7aSWarner Losh
104318e3e3a7aSWarner Losh<p>
104328e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3>
104338e3e3a7aSWarner Losh
104348e3e3a7aSWarner Losh
104358e3e3a7aSWarner Losh<p>
104368e3e3a7aSWarner LoshReturns the tangent of <code>x</code> (assumed to be in radians).
104378e3e3a7aSWarner Losh
104388e3e3a7aSWarner Losh
104398e3e3a7aSWarner Losh
104408e3e3a7aSWarner Losh
104418e3e3a7aSWarner Losh<p>
104428e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3>
104438e3e3a7aSWarner Losh
104448e3e3a7aSWarner Losh
104458e3e3a7aSWarner Losh<p>
104468e3e3a7aSWarner LoshIf the value <code>x</code> is convertible to an integer,
104478e3e3a7aSWarner Loshreturns that integer.
104480495ed39SKyle EvansOtherwise, returns <b>fail</b>.
104498e3e3a7aSWarner Losh
104508e3e3a7aSWarner Losh
104518e3e3a7aSWarner Losh
104528e3e3a7aSWarner Losh
104538e3e3a7aSWarner Losh<p>
104548e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3>
104558e3e3a7aSWarner Losh
104568e3e3a7aSWarner Losh
104578e3e3a7aSWarner Losh<p>
104588e3e3a7aSWarner LoshReturns "<code>integer</code>" if <code>x</code> is an integer,
104598e3e3a7aSWarner Losh"<code>float</code>" if it is a float,
104600495ed39SKyle Evansor <b>fail</b> if <code>x</code> is not a number.
104618e3e3a7aSWarner Losh
104628e3e3a7aSWarner Losh
104638e3e3a7aSWarner Losh
104648e3e3a7aSWarner Losh
104658e3e3a7aSWarner Losh<p>
104668e3e3a7aSWarner Losh<hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3>
104678e3e3a7aSWarner Losh
104688e3e3a7aSWarner Losh
104698e3e3a7aSWarner Losh<p>
104708e3e3a7aSWarner LoshReturns a boolean,
104718c784bb8SWarner Losh<b>true</b> if and only if integer <code>m</code> is below integer <code>n</code> when
104728e3e3a7aSWarner Loshthey are compared as unsigned integers.
104738e3e3a7aSWarner Losh
104748e3e3a7aSWarner Losh
104758e3e3a7aSWarner Losh
104768e3e3a7aSWarner Losh
104778e3e3a7aSWarner Losh
104788e3e3a7aSWarner Losh
104798e3e3a7aSWarner Losh
104808e3e3a7aSWarner Losh<h2>6.8 &ndash; <a name="6.8">Input and Output Facilities</a></h2>
104818e3e3a7aSWarner Losh
104828e3e3a7aSWarner Losh<p>
104838e3e3a7aSWarner LoshThe I/O library provides two different styles for file manipulation.
104848e3e3a7aSWarner LoshThe first one uses implicit file handles;
104858e3e3a7aSWarner Loshthat is, there are operations to set a default input file and a
104868e3e3a7aSWarner Loshdefault output file,
104870495ed39SKyle Evansand all input/output operations are done over these default files.
104888e3e3a7aSWarner LoshThe second style uses explicit file handles.
104898e3e3a7aSWarner Losh
104908e3e3a7aSWarner Losh
104918e3e3a7aSWarner Losh<p>
104928e3e3a7aSWarner LoshWhen using implicit file handles,
104938e3e3a7aSWarner Loshall operations are supplied by table <a name="pdf-io"><code>io</code></a>.
104948e3e3a7aSWarner LoshWhen using explicit file handles,
104958e3e3a7aSWarner Loshthe operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle
104968e3e3a7aSWarner Loshand then all operations are supplied as methods of the file handle.
104978e3e3a7aSWarner Losh
104988e3e3a7aSWarner Losh
104998e3e3a7aSWarner Losh<p>
105000495ed39SKyle EvansThe metatable for file handles provides metamethods
105010495ed39SKyle Evansfor <code>__gc</code> and <code>__close</code> that try
105020495ed39SKyle Evansto close the file when called.
105030495ed39SKyle Evans
105040495ed39SKyle Evans
105050495ed39SKyle Evans<p>
105068e3e3a7aSWarner LoshThe table <code>io</code> also provides
105078e3e3a7aSWarner Loshthree predefined file handles with their usual meanings from C:
105088e3e3a7aSWarner Losh<a name="pdf-io.stdin"><code>io.stdin</code></a>, <a name="pdf-io.stdout"><code>io.stdout</code></a>, and <a name="pdf-io.stderr"><code>io.stderr</code></a>.
105098e3e3a7aSWarner LoshThe I/O library never closes these files.
105108e3e3a7aSWarner Losh
105118e3e3a7aSWarner Losh
105128e3e3a7aSWarner Losh<p>
105138e3e3a7aSWarner LoshUnless otherwise stated,
105140495ed39SKyle Evansall I/O functions return <b>fail</b> on failure,
105150495ed39SKyle Evansplus an error message as a second result and
105160495ed39SKyle Evansa system-dependent error code as a third result,
105170495ed39SKyle Evansand some non-false value on success.
105180495ed39SKyle EvansOn non-POSIX systems,
105198e3e3a7aSWarner Loshthe computation of the error message and error code
105208e3e3a7aSWarner Loshin case of errors
105218e3e3a7aSWarner Loshmay be not thread safe,
105228e3e3a7aSWarner Loshbecause they rely on the global C variable <code>errno</code>.
105238e3e3a7aSWarner Losh
105248e3e3a7aSWarner Losh
105258e3e3a7aSWarner Losh<p>
105268e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3>
105278e3e3a7aSWarner Losh
105288e3e3a7aSWarner Losh
105298e3e3a7aSWarner Losh<p>
105308e3e3a7aSWarner LoshEquivalent to <code>file:close()</code>.
105318e3e3a7aSWarner LoshWithout a <code>file</code>, closes the default output file.
105328e3e3a7aSWarner Losh
105338e3e3a7aSWarner Losh
105348e3e3a7aSWarner Losh
105358e3e3a7aSWarner Losh
105368e3e3a7aSWarner Losh<p>
105378e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3>
105388e3e3a7aSWarner Losh
105398e3e3a7aSWarner Losh
105408e3e3a7aSWarner Losh<p>
105418e3e3a7aSWarner LoshEquivalent to <code>io.output():flush()</code>.
105428e3e3a7aSWarner Losh
105438e3e3a7aSWarner Losh
105448e3e3a7aSWarner Losh
105458e3e3a7aSWarner Losh
105468e3e3a7aSWarner Losh<p>
105478e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3>
105488e3e3a7aSWarner Losh
105498e3e3a7aSWarner Losh
105508e3e3a7aSWarner Losh<p>
105518e3e3a7aSWarner LoshWhen called with a file name, it opens the named file (in text mode),
105528e3e3a7aSWarner Loshand sets its handle as the default input file.
105538e3e3a7aSWarner LoshWhen called with a file handle,
105548e3e3a7aSWarner Loshit simply sets this file handle as the default input file.
10555e112e9d2SKyle EvansWhen called without arguments,
105568e3e3a7aSWarner Loshit returns the current default input file.
105578e3e3a7aSWarner Losh
105588e3e3a7aSWarner Losh
105598e3e3a7aSWarner Losh<p>
105608e3e3a7aSWarner LoshIn case of errors this function raises the error,
105618e3e3a7aSWarner Loshinstead of returning an error code.
105628e3e3a7aSWarner Losh
105638e3e3a7aSWarner Losh
105648e3e3a7aSWarner Losh
105658e3e3a7aSWarner Losh
105668e3e3a7aSWarner Losh<p>
105678e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, &middot;&middot;&middot;])</code></a></h3>
105688e3e3a7aSWarner Losh
105698e3e3a7aSWarner Losh
105708e3e3a7aSWarner Losh<p>
105718e3e3a7aSWarner LoshOpens the given file name in read mode
105728e3e3a7aSWarner Loshand returns an iterator function that
105738e3e3a7aSWarner Loshworks like <code>file:lines(&middot;&middot;&middot;)</code> over the opened file.
105740495ed39SKyle EvansWhen the iterator function fails to read any value,
105750495ed39SKyle Evansit automatically closes the file.
105760495ed39SKyle EvansBesides the iterator function,
105770495ed39SKyle Evans<code>io.lines</code> returns three other values:
105780495ed39SKyle Evanstwo <b>nil</b> values as placeholders,
105790495ed39SKyle Evansplus the created file handle.
105800495ed39SKyle EvansTherefore, when used in a generic <b>for</b> loop,
105810495ed39SKyle Evansthe file is closed also if the loop is interrupted by an
105820495ed39SKyle Evanserror or a <b>break</b>.
105838e3e3a7aSWarner Losh
105848e3e3a7aSWarner Losh
105858e3e3a7aSWarner Losh<p>
105868e3e3a7aSWarner LoshThe call <code>io.lines()</code> (with no file name) is equivalent
105870495ed39SKyle Evansto <code>io.input():lines("l")</code>;
105888e3e3a7aSWarner Loshthat is, it iterates over the lines of the default input file.
10589e112e9d2SKyle EvansIn this case, the iterator does not close the file when the loop ends.
105908e3e3a7aSWarner Losh
105918e3e3a7aSWarner Losh
105928e3e3a7aSWarner Losh<p>
105930495ed39SKyle EvansIn case of errors opening the file,
105940495ed39SKyle Evansthis function raises the error,
105958e3e3a7aSWarner Loshinstead of returning an error code.
105968e3e3a7aSWarner Losh
105978e3e3a7aSWarner Losh
105988e3e3a7aSWarner Losh
105998e3e3a7aSWarner Losh
106008e3e3a7aSWarner Losh<p>
106018e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3>
106028e3e3a7aSWarner Losh
106038e3e3a7aSWarner Losh
106048e3e3a7aSWarner Losh<p>
106058e3e3a7aSWarner LoshThis function opens a file,
106068e3e3a7aSWarner Loshin the mode specified in the string <code>mode</code>.
106078e3e3a7aSWarner LoshIn case of success,
106088e3e3a7aSWarner Loshit returns a new file handle.
106098e3e3a7aSWarner Losh
106108e3e3a7aSWarner Losh
106118e3e3a7aSWarner Losh<p>
106128e3e3a7aSWarner LoshThe <code>mode</code> string can be any of the following:
106138e3e3a7aSWarner Losh
106148e3e3a7aSWarner Losh<ul>
106158e3e3a7aSWarner Losh<li><b>"<code>r</code>": </b> read mode (the default);</li>
106168e3e3a7aSWarner Losh<li><b>"<code>w</code>": </b> write mode;</li>
106178e3e3a7aSWarner Losh<li><b>"<code>a</code>": </b> append mode;</li>
106188e3e3a7aSWarner Losh<li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li>
106198e3e3a7aSWarner Losh<li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li>
106208e3e3a7aSWarner Losh<li><b>"<code>a+</code>": </b> append update mode, previous data is preserved,
106218e3e3a7aSWarner Losh  writing is only allowed at the end of file.</li>
106228e3e3a7aSWarner Losh</ul><p>
106238e3e3a7aSWarner LoshThe <code>mode</code> string can also have a '<code>b</code>' at the end,
106248e3e3a7aSWarner Loshwhich is needed in some systems to open the file in binary mode.
106258e3e3a7aSWarner Losh
106268e3e3a7aSWarner Losh
106278e3e3a7aSWarner Losh
106288e3e3a7aSWarner Losh
106298e3e3a7aSWarner Losh<p>
106308e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3>
106318e3e3a7aSWarner Losh
106328e3e3a7aSWarner Losh
106338e3e3a7aSWarner Losh<p>
106348e3e3a7aSWarner LoshSimilar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file.
106358e3e3a7aSWarner Losh
106368e3e3a7aSWarner Losh
106378e3e3a7aSWarner Losh
106388e3e3a7aSWarner Losh
106398e3e3a7aSWarner Losh<p>
106408e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3>
106418e3e3a7aSWarner Losh
106428e3e3a7aSWarner Losh
106438e3e3a7aSWarner Losh<p>
106448e3e3a7aSWarner LoshThis function is system dependent and is not available
106458e3e3a7aSWarner Loshon all platforms.
106468e3e3a7aSWarner Losh
106478e3e3a7aSWarner Losh
106488e3e3a7aSWarner Losh<p>
106490495ed39SKyle EvansStarts the program <code>prog</code> in a separated process and returns
106508e3e3a7aSWarner Losha file handle that you can use to read data from this program
106518e3e3a7aSWarner Losh(if <code>mode</code> is <code>"r"</code>, the default)
106528e3e3a7aSWarner Loshor to write data to this program
106538e3e3a7aSWarner Losh(if <code>mode</code> is <code>"w"</code>).
106548e3e3a7aSWarner Losh
106558e3e3a7aSWarner Losh
106568e3e3a7aSWarner Losh
106578e3e3a7aSWarner Losh
106588e3e3a7aSWarner Losh<p>
106598e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.read"><code>io.read (&middot;&middot;&middot;)</code></a></h3>
106608e3e3a7aSWarner Losh
106618e3e3a7aSWarner Losh
106628e3e3a7aSWarner Losh<p>
106638e3e3a7aSWarner LoshEquivalent to <code>io.input():read(&middot;&middot;&middot;)</code>.
106648e3e3a7aSWarner Losh
106658e3e3a7aSWarner Losh
106668e3e3a7aSWarner Losh
106678e3e3a7aSWarner Losh
106688e3e3a7aSWarner Losh<p>
106698e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3>
106708e3e3a7aSWarner Losh
106718e3e3a7aSWarner Losh
106728e3e3a7aSWarner Losh<p>
106738e3e3a7aSWarner LoshIn case of success,
106748e3e3a7aSWarner Loshreturns a handle for a temporary file.
106758e3e3a7aSWarner LoshThis file is opened in update mode
106768e3e3a7aSWarner Loshand it is automatically removed when the program ends.
106778e3e3a7aSWarner Losh
106788e3e3a7aSWarner Losh
106798e3e3a7aSWarner Losh
106808e3e3a7aSWarner Losh
106818e3e3a7aSWarner Losh<p>
106828e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3>
106838e3e3a7aSWarner Losh
106848e3e3a7aSWarner Losh
106858e3e3a7aSWarner Losh<p>
106868e3e3a7aSWarner LoshChecks whether <code>obj</code> is a valid file handle.
106878e3e3a7aSWarner LoshReturns the string <code>"file"</code> if <code>obj</code> is an open file handle,
106888e3e3a7aSWarner Losh<code>"closed file"</code> if <code>obj</code> is a closed file handle,
106890495ed39SKyle Evansor <b>fail</b> if <code>obj</code> is not a file handle.
106908e3e3a7aSWarner Losh
106918e3e3a7aSWarner Losh
106928e3e3a7aSWarner Losh
106938e3e3a7aSWarner Losh
106948e3e3a7aSWarner Losh<p>
106958e3e3a7aSWarner Losh<hr><h3><a name="pdf-io.write"><code>io.write (&middot;&middot;&middot;)</code></a></h3>
106968e3e3a7aSWarner Losh
106978e3e3a7aSWarner Losh
106988e3e3a7aSWarner Losh<p>
106998e3e3a7aSWarner LoshEquivalent to <code>io.output():write(&middot;&middot;&middot;)</code>.
107008e3e3a7aSWarner Losh
107018e3e3a7aSWarner Losh
107028e3e3a7aSWarner Losh
107038e3e3a7aSWarner Losh
107048e3e3a7aSWarner Losh<p>
107058e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3>
107068e3e3a7aSWarner Losh
107078e3e3a7aSWarner Losh
107088e3e3a7aSWarner Losh<p>
107098e3e3a7aSWarner LoshCloses <code>file</code>.
107108e3e3a7aSWarner LoshNote that files are automatically closed when
107118e3e3a7aSWarner Loshtheir handles are garbage collected,
107128e3e3a7aSWarner Loshbut that takes an unpredictable amount of time to happen.
107138e3e3a7aSWarner Losh
107148e3e3a7aSWarner Losh
107158e3e3a7aSWarner Losh<p>
107168e3e3a7aSWarner LoshWhen closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>,
107178e3e3a7aSWarner Losh<a href="#pdf-file:close"><code>file:close</code></a> returns the same values
107188e3e3a7aSWarner Loshreturned by <a href="#pdf-os.execute"><code>os.execute</code></a>.
107198e3e3a7aSWarner Losh
107208e3e3a7aSWarner Losh
107218e3e3a7aSWarner Losh
107228e3e3a7aSWarner Losh
107238e3e3a7aSWarner Losh<p>
107248e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3>
107258e3e3a7aSWarner Losh
107268e3e3a7aSWarner Losh
107278e3e3a7aSWarner Losh<p>
107288e3e3a7aSWarner LoshSaves any written data to <code>file</code>.
107298e3e3a7aSWarner Losh
107308e3e3a7aSWarner Losh
107318e3e3a7aSWarner Losh
107328e3e3a7aSWarner Losh
107338e3e3a7aSWarner Losh<p>
107348e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:lines"><code>file:lines (&middot;&middot;&middot;)</code></a></h3>
107358e3e3a7aSWarner Losh
107368e3e3a7aSWarner Losh
107378e3e3a7aSWarner Losh<p>
107388e3e3a7aSWarner LoshReturns an iterator function that,
107398e3e3a7aSWarner Losheach time it is called,
107408e3e3a7aSWarner Loshreads the file according to the given formats.
107418e3e3a7aSWarner LoshWhen no format is given,
107428e3e3a7aSWarner Loshuses "<code>l</code>" as a default.
107438e3e3a7aSWarner LoshAs an example, the construction
107448e3e3a7aSWarner Losh
107458e3e3a7aSWarner Losh<pre>
107468e3e3a7aSWarner Losh     for c in file:lines(1) do <em>body</em> end
107478e3e3a7aSWarner Losh</pre><p>
107488e3e3a7aSWarner Loshwill iterate over all characters of the file,
107498e3e3a7aSWarner Loshstarting at the current position.
107508e3e3a7aSWarner LoshUnlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
107518e3e3a7aSWarner Loshwhen the loop ends.
107528e3e3a7aSWarner Losh
107538e3e3a7aSWarner Losh
107548e3e3a7aSWarner Losh
107558e3e3a7aSWarner Losh
107568e3e3a7aSWarner Losh<p>
107578e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:read"><code>file:read (&middot;&middot;&middot;)</code></a></h3>
107588e3e3a7aSWarner Losh
107598e3e3a7aSWarner Losh
107608e3e3a7aSWarner Losh<p>
107618e3e3a7aSWarner LoshReads the file <code>file</code>,
107628e3e3a7aSWarner Loshaccording to the given formats, which specify what to read.
107638e3e3a7aSWarner LoshFor each format,
107648e3e3a7aSWarner Loshthe function returns a string or a number with the characters read,
107650495ed39SKyle Evansor <b>fail</b> if it cannot read data with the specified format.
107668e3e3a7aSWarner Losh(In this latter case,
107678e3e3a7aSWarner Loshthe function does not read subsequent formats.)
107680495ed39SKyle EvansWhen called without arguments,
107698e3e3a7aSWarner Loshit uses a default format that reads the next line
107708e3e3a7aSWarner Losh(see below).
107718e3e3a7aSWarner Losh
107728e3e3a7aSWarner Losh
107738e3e3a7aSWarner Losh<p>
107748e3e3a7aSWarner LoshThe available formats are
107758e3e3a7aSWarner Losh
107768e3e3a7aSWarner Losh<ul>
107778e3e3a7aSWarner Losh
107788e3e3a7aSWarner Losh<li><b>"<code>n</code>": </b>
107798e3e3a7aSWarner Loshreads a numeral and returns it as a float or an integer,
107808e3e3a7aSWarner Loshfollowing the lexical conventions of Lua.
107810495ed39SKyle Evans(The numeral may have leading whitespaces and a sign.)
107828e3e3a7aSWarner LoshThis format always reads the longest input sequence that
107838e3e3a7aSWarner Loshis a valid prefix for a numeral;
107848e3e3a7aSWarner Loshif that prefix does not form a valid numeral
107850495ed39SKyle Evans(e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>")
107860495ed39SKyle Evansor it is too long (more than 200 characters),
107870495ed39SKyle Evansit is discarded and the format returns <b>fail</b>.
107888e3e3a7aSWarner Losh</li>
107898e3e3a7aSWarner Losh
107908e3e3a7aSWarner Losh<li><b>"<code>a</code>": </b>
107918e3e3a7aSWarner Loshreads the whole file, starting at the current position.
107920495ed39SKyle EvansOn end of file, it returns the empty string;
107930495ed39SKyle Evansthis format never fails.
107948e3e3a7aSWarner Losh</li>
107958e3e3a7aSWarner Losh
107968e3e3a7aSWarner Losh<li><b>"<code>l</code>": </b>
107978e3e3a7aSWarner Loshreads the next line skipping the end of line,
107980495ed39SKyle Evansreturning <b>fail</b> on end of file.
107998e3e3a7aSWarner LoshThis is the default format.
108008e3e3a7aSWarner Losh</li>
108018e3e3a7aSWarner Losh
108028e3e3a7aSWarner Losh<li><b>"<code>L</code>": </b>
108038e3e3a7aSWarner Loshreads the next line keeping the end-of-line character (if present),
108040495ed39SKyle Evansreturning <b>fail</b> on end of file.
108058e3e3a7aSWarner Losh</li>
108068e3e3a7aSWarner Losh
108078e3e3a7aSWarner Losh<li><b><em>number</em>: </b>
108088e3e3a7aSWarner Loshreads a string with up to this number of bytes,
108090495ed39SKyle Evansreturning <b>fail</b> on end of file.
108108e3e3a7aSWarner LoshIf <code>number</code> is zero,
108118e3e3a7aSWarner Loshit reads nothing and returns an empty string,
108120495ed39SKyle Evansor <b>fail</b> on end of file.
108138e3e3a7aSWarner Losh</li>
108148e3e3a7aSWarner Losh
108158e3e3a7aSWarner Losh</ul><p>
108168e3e3a7aSWarner LoshThe formats "<code>l</code>" and "<code>L</code>" should be used only for text files.
108178e3e3a7aSWarner Losh
108188e3e3a7aSWarner Losh
108198e3e3a7aSWarner Losh
108208e3e3a7aSWarner Losh
108218e3e3a7aSWarner Losh<p>
108228e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3>
108238e3e3a7aSWarner Losh
108248e3e3a7aSWarner Losh
108258e3e3a7aSWarner Losh<p>
108268e3e3a7aSWarner LoshSets and gets the file position,
108278e3e3a7aSWarner Loshmeasured from the beginning of the file,
108288e3e3a7aSWarner Loshto the position given by <code>offset</code> plus a base
108298e3e3a7aSWarner Loshspecified by the string <code>whence</code>, as follows:
108308e3e3a7aSWarner Losh
108318e3e3a7aSWarner Losh<ul>
108328e3e3a7aSWarner Losh<li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li>
108338e3e3a7aSWarner Losh<li><b>"<code>cur</code>": </b> base is current position;</li>
108348e3e3a7aSWarner Losh<li><b>"<code>end</code>": </b> base is end of file;</li>
108358e3e3a7aSWarner Losh</ul><p>
108368e3e3a7aSWarner LoshIn case of success, <code>seek</code> returns the final file position,
108378e3e3a7aSWarner Loshmeasured in bytes from the beginning of the file.
108380495ed39SKyle EvansIf <code>seek</code> fails, it returns <b>fail</b>,
108398e3e3a7aSWarner Loshplus a string describing the error.
108408e3e3a7aSWarner Losh
108418e3e3a7aSWarner Losh
108428e3e3a7aSWarner Losh<p>
108438e3e3a7aSWarner LoshThe default value for <code>whence</code> is <code>"cur"</code>,
108448e3e3a7aSWarner Loshand for <code>offset</code> is 0.
108458e3e3a7aSWarner LoshTherefore, the call <code>file:seek()</code> returns the current
108468e3e3a7aSWarner Loshfile position, without changing it;
108478e3e3a7aSWarner Loshthe call <code>file:seek("set")</code> sets the position to the
108488e3e3a7aSWarner Loshbeginning of the file (and returns 0);
108498e3e3a7aSWarner Loshand the call <code>file:seek("end")</code> sets the position to the
108508e3e3a7aSWarner Loshend of the file, and returns its size.
108518e3e3a7aSWarner Losh
108528e3e3a7aSWarner Losh
108538e3e3a7aSWarner Losh
108548e3e3a7aSWarner Losh
108558e3e3a7aSWarner Losh<p>
108568e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3>
108578e3e3a7aSWarner Losh
108588e3e3a7aSWarner Losh
108598e3e3a7aSWarner Losh<p>
108600495ed39SKyle EvansSets the buffering mode for a file.
108618e3e3a7aSWarner LoshThere are three available modes:
108628e3e3a7aSWarner Losh
108638e3e3a7aSWarner Losh<ul>
108640495ed39SKyle Evans<li><b>"<code>no</code>": </b> no buffering.</li>
108650495ed39SKyle Evans<li><b>"<code>full</code>": </b> full buffering.</li>
108660495ed39SKyle Evans<li><b>"<code>line</code>": </b> line buffering.</li>
108670495ed39SKyle Evans</ul>
108688e3e3a7aSWarner Losh
108690495ed39SKyle Evans<p>
108700495ed39SKyle EvansFor the last two cases,
108710495ed39SKyle Evans<code>size</code> is a hint for the size of the buffer, in bytes.
108728e3e3a7aSWarner LoshThe default is an appropriate size.
108738e3e3a7aSWarner Losh
108748e3e3a7aSWarner Losh
108750495ed39SKyle Evans<p>
108760495ed39SKyle EvansThe specific behavior of each mode is non portable;
108770495ed39SKyle Evanscheck the underlying ISO&nbsp;C function <code>setvbuf</code> in your platform for
108780495ed39SKyle Evansmore details.
108790495ed39SKyle Evans
108800495ed39SKyle Evans
108818e3e3a7aSWarner Losh
108828e3e3a7aSWarner Losh
108838e3e3a7aSWarner Losh<p>
108848e3e3a7aSWarner Losh<hr><h3><a name="pdf-file:write"><code>file:write (&middot;&middot;&middot;)</code></a></h3>
108858e3e3a7aSWarner Losh
108868e3e3a7aSWarner Losh
108878e3e3a7aSWarner Losh<p>
108888e3e3a7aSWarner LoshWrites the value of each of its arguments to <code>file</code>.
108898e3e3a7aSWarner LoshThe arguments must be strings or numbers.
108908e3e3a7aSWarner Losh
108918e3e3a7aSWarner Losh
108928e3e3a7aSWarner Losh<p>
108938e3e3a7aSWarner LoshIn case of success, this function returns <code>file</code>.
108948e3e3a7aSWarner Losh
108958e3e3a7aSWarner Losh
108968e3e3a7aSWarner Losh
108978e3e3a7aSWarner Losh
108988e3e3a7aSWarner Losh
108998e3e3a7aSWarner Losh
109008e3e3a7aSWarner Losh
109018e3e3a7aSWarner Losh<h2>6.9 &ndash; <a name="6.9">Operating System Facilities</a></h2>
109028e3e3a7aSWarner Losh
109038e3e3a7aSWarner Losh<p>
109048e3e3a7aSWarner LoshThis library is implemented through table <a name="pdf-os"><code>os</code></a>.
109058e3e3a7aSWarner Losh
109068e3e3a7aSWarner Losh
109078e3e3a7aSWarner Losh<p>
109088e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3>
109098e3e3a7aSWarner Losh
109108e3e3a7aSWarner Losh
109118e3e3a7aSWarner Losh<p>
109128e3e3a7aSWarner LoshReturns an approximation of the amount in seconds of CPU time
109130495ed39SKyle Evansused by the program,
109140495ed39SKyle Evansas returned by the underlying ISO&nbsp;C function <code>clock</code>.
109158e3e3a7aSWarner Losh
109168e3e3a7aSWarner Losh
109178e3e3a7aSWarner Losh
109188e3e3a7aSWarner Losh
109198e3e3a7aSWarner Losh<p>
109208e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3>
109218e3e3a7aSWarner Losh
109228e3e3a7aSWarner Losh
109238e3e3a7aSWarner Losh<p>
109248e3e3a7aSWarner LoshReturns a string or a table containing date and time,
109258e3e3a7aSWarner Loshformatted according to the given string <code>format</code>.
109268e3e3a7aSWarner Losh
109278e3e3a7aSWarner Losh
109288e3e3a7aSWarner Losh<p>
109298e3e3a7aSWarner LoshIf the <code>time</code> argument is present,
109308e3e3a7aSWarner Loshthis is the time to be formatted
109318e3e3a7aSWarner Losh(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
109328e3e3a7aSWarner LoshOtherwise, <code>date</code> formats the current time.
109338e3e3a7aSWarner Losh
109348e3e3a7aSWarner Losh
109358e3e3a7aSWarner Losh<p>
109368e3e3a7aSWarner LoshIf <code>format</code> starts with '<code>!</code>',
109378e3e3a7aSWarner Loshthen the date is formatted in Coordinated Universal Time.
109388e3e3a7aSWarner LoshAfter this optional character,
109398e3e3a7aSWarner Loshif <code>format</code> is the string "<code>*t</code>",
109408e3e3a7aSWarner Loshthen <code>date</code> returns a table with the following fields:
109418e3e3a7aSWarner Losh<code>year</code>, <code>month</code> (1&ndash;12), <code>day</code> (1&ndash;31),
109420495ed39SKyle Evans<code>hour</code> (0&ndash;23), <code>min</code> (0&ndash;59),
109430495ed39SKyle Evans<code>sec</code> (0&ndash;61, due to leap seconds),
109448e3e3a7aSWarner Losh<code>wday</code> (weekday, 1&ndash;7, Sunday is&nbsp;1),
109458e3e3a7aSWarner Losh<code>yday</code> (day of the year, 1&ndash;366),
109468e3e3a7aSWarner Loshand <code>isdst</code> (daylight saving flag, a boolean).
109478e3e3a7aSWarner LoshThis last field may be absent
109488e3e3a7aSWarner Loshif the information is not available.
109498e3e3a7aSWarner Losh
109508e3e3a7aSWarner Losh
109518e3e3a7aSWarner Losh<p>
109528e3e3a7aSWarner LoshIf <code>format</code> is not "<code>*t</code>",
109538e3e3a7aSWarner Loshthen <code>date</code> returns the date as a string,
109548e3e3a7aSWarner Loshformatted according to the same rules as the ISO&nbsp;C function <code>strftime</code>.
109558e3e3a7aSWarner Losh
109568e3e3a7aSWarner Losh
109578e3e3a7aSWarner Losh<p>
109580495ed39SKyle EvansIf <code>format</code> is absent, it defaults to "<code>%c</code>",
109590495ed39SKyle Evanswhich gives a human-readable date and time representation
109600495ed39SKyle Evansusing the current locale.
109618e3e3a7aSWarner Losh
109628e3e3a7aSWarner Losh
109638e3e3a7aSWarner Losh<p>
109640495ed39SKyle EvansOn non-POSIX systems,
109658e3e3a7aSWarner Loshthis function may be not thread safe
109668e3e3a7aSWarner Loshbecause of its reliance on C&nbsp;function <code>gmtime</code> and C&nbsp;function <code>localtime</code>.
109678e3e3a7aSWarner Losh
109688e3e3a7aSWarner Losh
109698e3e3a7aSWarner Losh
109708e3e3a7aSWarner Losh
109718e3e3a7aSWarner Losh<p>
109728e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>
109738e3e3a7aSWarner Losh
109748e3e3a7aSWarner Losh
109758e3e3a7aSWarner Losh<p>
109768e3e3a7aSWarner LoshReturns the difference, in seconds,
109778e3e3a7aSWarner Loshfrom time <code>t1</code> to time <code>t2</code>
109788e3e3a7aSWarner Losh(where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>).
109798e3e3a7aSWarner LoshIn POSIX, Windows, and some other systems,
109808e3e3a7aSWarner Loshthis value is exactly <code>t2</code><em>-</em><code>t1</code>.
109818e3e3a7aSWarner Losh
109828e3e3a7aSWarner Losh
109838e3e3a7aSWarner Losh
109848e3e3a7aSWarner Losh
109858e3e3a7aSWarner Losh<p>
109868e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3>
109878e3e3a7aSWarner Losh
109888e3e3a7aSWarner Losh
109898e3e3a7aSWarner Losh<p>
109908e3e3a7aSWarner LoshThis function is equivalent to the ISO&nbsp;C function <code>system</code>.
109918e3e3a7aSWarner LoshIt passes <code>command</code> to be executed by an operating system shell.
109928e3e3a7aSWarner LoshIts first result is <b>true</b>
109938e3e3a7aSWarner Loshif the command terminated successfully,
109940495ed39SKyle Evansor <b>fail</b> otherwise.
109958e3e3a7aSWarner LoshAfter this first result
109968e3e3a7aSWarner Loshthe function returns a string plus a number,
109978e3e3a7aSWarner Loshas follows:
109988e3e3a7aSWarner Losh
109998e3e3a7aSWarner Losh<ul>
110008e3e3a7aSWarner Losh
110018e3e3a7aSWarner Losh<li><b>"<code>exit</code>": </b>
110028e3e3a7aSWarner Loshthe command terminated normally;
110038e3e3a7aSWarner Loshthe following number is the exit status of the command.
110048e3e3a7aSWarner Losh</li>
110058e3e3a7aSWarner Losh
110068e3e3a7aSWarner Losh<li><b>"<code>signal</code>": </b>
110078e3e3a7aSWarner Loshthe command was terminated by a signal;
110088e3e3a7aSWarner Loshthe following number is the signal that terminated the command.
110098e3e3a7aSWarner Losh</li>
110108e3e3a7aSWarner Losh
110118e3e3a7aSWarner Losh</ul>
110128e3e3a7aSWarner Losh
110138e3e3a7aSWarner Losh<p>
110148e3e3a7aSWarner LoshWhen called without a <code>command</code>,
110158e3e3a7aSWarner Losh<code>os.execute</code> returns a boolean that is true if a shell is available.
110168e3e3a7aSWarner Losh
110178e3e3a7aSWarner Losh
110188e3e3a7aSWarner Losh
110198e3e3a7aSWarner Losh
110208e3e3a7aSWarner Losh<p>
110218e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3>
110228e3e3a7aSWarner Losh
110238e3e3a7aSWarner Losh
110248e3e3a7aSWarner Losh<p>
110258e3e3a7aSWarner LoshCalls the ISO&nbsp;C function <code>exit</code> to terminate the host program.
110268e3e3a7aSWarner LoshIf <code>code</code> is <b>true</b>,
110278e3e3a7aSWarner Loshthe returned status is <code>EXIT_SUCCESS</code>;
110288e3e3a7aSWarner Loshif <code>code</code> is <b>false</b>,
110298e3e3a7aSWarner Loshthe returned status is <code>EXIT_FAILURE</code>;
110308e3e3a7aSWarner Loshif <code>code</code> is a number,
110318e3e3a7aSWarner Loshthe returned status is this number.
110328e3e3a7aSWarner LoshThe default value for <code>code</code> is <b>true</b>.
110338e3e3a7aSWarner Losh
110348e3e3a7aSWarner Losh
110358e3e3a7aSWarner Losh<p>
110368e3e3a7aSWarner LoshIf the optional second argument <code>close</code> is true,
11037*a9490b81SWarner Loshthe function closes the Lua state before exiting (see <a href="#lua_close"><code>lua_close</code></a>).
110388e3e3a7aSWarner Losh
110398e3e3a7aSWarner Losh
110408e3e3a7aSWarner Losh
110418e3e3a7aSWarner Losh
110428e3e3a7aSWarner Losh<p>
110438e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3>
110448e3e3a7aSWarner Losh
110458e3e3a7aSWarner Losh
110468e3e3a7aSWarner Losh<p>
110470495ed39SKyle EvansReturns the value of the process environment variable <code>varname</code>
110480495ed39SKyle Evansor <b>fail</b> if the variable is not defined.
110498e3e3a7aSWarner Losh
110508e3e3a7aSWarner Losh
110518e3e3a7aSWarner Losh
110528e3e3a7aSWarner Losh
110538e3e3a7aSWarner Losh<p>
110548e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3>
110558e3e3a7aSWarner Losh
110568e3e3a7aSWarner Losh
110578e3e3a7aSWarner Losh<p>
110588e3e3a7aSWarner LoshDeletes the file (or empty directory, on POSIX systems)
110598e3e3a7aSWarner Loshwith the given name.
110600495ed39SKyle EvansIf this function fails, it returns <b>fail</b>
110618e3e3a7aSWarner Loshplus a string describing the error and the error code.
110628e3e3a7aSWarner LoshOtherwise, it returns true.
110638e3e3a7aSWarner Losh
110648e3e3a7aSWarner Losh
110658e3e3a7aSWarner Losh
110668e3e3a7aSWarner Losh
110678e3e3a7aSWarner Losh<p>
110688e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3>
110698e3e3a7aSWarner Losh
110708e3e3a7aSWarner Losh
110718e3e3a7aSWarner Losh<p>
110728e3e3a7aSWarner LoshRenames the file or directory named <code>oldname</code> to <code>newname</code>.
110730495ed39SKyle EvansIf this function fails, it returns <b>fail</b>,
110748e3e3a7aSWarner Loshplus a string describing the error and the error code.
110758e3e3a7aSWarner LoshOtherwise, it returns true.
110768e3e3a7aSWarner Losh
110778e3e3a7aSWarner Losh
110788e3e3a7aSWarner Losh
110798e3e3a7aSWarner Losh
110808e3e3a7aSWarner Losh<p>
110818e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3>
110828e3e3a7aSWarner Losh
110838e3e3a7aSWarner Losh
110848e3e3a7aSWarner Losh<p>
110858e3e3a7aSWarner LoshSets the current locale of the program.
110868e3e3a7aSWarner Losh<code>locale</code> is a system-dependent string specifying a locale;
110878e3e3a7aSWarner Losh<code>category</code> is an optional string describing which category to change:
110888e3e3a7aSWarner Losh<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>,
110898e3e3a7aSWarner Losh<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>;
110908e3e3a7aSWarner Loshthe default category is <code>"all"</code>.
110918e3e3a7aSWarner LoshThe function returns the name of the new locale,
110920495ed39SKyle Evansor <b>fail</b> if the request cannot be honored.
110938e3e3a7aSWarner Losh
110948e3e3a7aSWarner Losh
110958e3e3a7aSWarner Losh<p>
110968e3e3a7aSWarner LoshIf <code>locale</code> is the empty string,
110978e3e3a7aSWarner Loshthe current locale is set to an implementation-defined native locale.
110988e3e3a7aSWarner LoshIf <code>locale</code> is the string "<code>C</code>",
110998e3e3a7aSWarner Loshthe current locale is set to the standard C locale.
111008e3e3a7aSWarner Losh
111018e3e3a7aSWarner Losh
111028e3e3a7aSWarner Losh<p>
111038e3e3a7aSWarner LoshWhen called with <b>nil</b> as the first argument,
111048e3e3a7aSWarner Loshthis function only returns the name of the current locale
111058e3e3a7aSWarner Loshfor the given category.
111068e3e3a7aSWarner Losh
111078e3e3a7aSWarner Losh
111088e3e3a7aSWarner Losh<p>
111098e3e3a7aSWarner LoshThis function may be not thread safe
111108e3e3a7aSWarner Loshbecause of its reliance on C&nbsp;function <code>setlocale</code>.
111118e3e3a7aSWarner Losh
111128e3e3a7aSWarner Losh
111138e3e3a7aSWarner Losh
111148e3e3a7aSWarner Losh
111158e3e3a7aSWarner Losh<p>
111168e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3>
111178e3e3a7aSWarner Losh
111188e3e3a7aSWarner Losh
111198e3e3a7aSWarner Losh<p>
111208e3e3a7aSWarner LoshReturns the current time when called without arguments,
111218e3e3a7aSWarner Loshor a time representing the local date and time specified by the given table.
111228e3e3a7aSWarner LoshThis table must have fields <code>year</code>, <code>month</code>, and <code>day</code>,
111238e3e3a7aSWarner Loshand may have fields
111248e3e3a7aSWarner Losh<code>hour</code> (default is 12),
111258e3e3a7aSWarner Losh<code>min</code> (default is 0),
111268e3e3a7aSWarner Losh<code>sec</code> (default is 0),
111278e3e3a7aSWarner Loshand <code>isdst</code> (default is <b>nil</b>).
111288e3e3a7aSWarner LoshOther fields are ignored.
111298e3e3a7aSWarner LoshFor a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function.
111308e3e3a7aSWarner Losh
111318e3e3a7aSWarner Losh
111328e3e3a7aSWarner Losh<p>
111330495ed39SKyle EvansWhen the function is called,
111340495ed39SKyle Evansthe values in these fields do not need to be inside their valid ranges.
111358e3e3a7aSWarner LoshFor instance, if <code>sec</code> is -10,
111360495ed39SKyle Evansit means 10 seconds before the time specified by the other fields;
111378e3e3a7aSWarner Loshif <code>hour</code> is 1000,
111380495ed39SKyle Evansit means 1000 hours after the time specified by the other fields.
111398e3e3a7aSWarner Losh
111408e3e3a7aSWarner Losh
111418e3e3a7aSWarner Losh<p>
111428e3e3a7aSWarner LoshThe returned value is a number, whose meaning depends on your system.
111438e3e3a7aSWarner LoshIn POSIX, Windows, and some other systems,
111448e3e3a7aSWarner Loshthis number counts the number
111458e3e3a7aSWarner Loshof seconds since some given start time (the "epoch").
111468e3e3a7aSWarner LoshIn other systems, the meaning is not specified,
111478e3e3a7aSWarner Loshand the number returned by <code>time</code> can be used only as an argument to
111488e3e3a7aSWarner Losh<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>.
111498e3e3a7aSWarner Losh
111508e3e3a7aSWarner Losh
111510495ed39SKyle Evans<p>
111520495ed39SKyle EvansWhen called with a table,
111530495ed39SKyle Evans<code>os.time</code> also normalizes all the fields
111540495ed39SKyle Evansdocumented in the <a href="#pdf-os.date"><code>os.date</code></a> function,
111550495ed39SKyle Evansso that they represent the same time as before the call
111560495ed39SKyle Evansbut with values inside their valid ranges.
111570495ed39SKyle Evans
111580495ed39SKyle Evans
111598e3e3a7aSWarner Losh
111608e3e3a7aSWarner Losh
111618e3e3a7aSWarner Losh<p>
111628e3e3a7aSWarner Losh<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3>
111638e3e3a7aSWarner Losh
111648e3e3a7aSWarner Losh
111658e3e3a7aSWarner Losh<p>
111668e3e3a7aSWarner LoshReturns a string with a file name that can
111678e3e3a7aSWarner Loshbe used for a temporary file.
111688e3e3a7aSWarner LoshThe file must be explicitly opened before its use
111698e3e3a7aSWarner Loshand explicitly removed when no longer needed.
111708e3e3a7aSWarner Losh
111718e3e3a7aSWarner Losh
111728e3e3a7aSWarner Losh<p>
11173e112e9d2SKyle EvansIn POSIX systems,
111748e3e3a7aSWarner Loshthis function also creates a file with that name,
111758e3e3a7aSWarner Loshto avoid security risks.
111768e3e3a7aSWarner Losh(Someone else might create the file with wrong permissions
111778e3e3a7aSWarner Loshin the time between getting the name and creating the file.)
111788e3e3a7aSWarner LoshYou still have to open the file to use it
111798e3e3a7aSWarner Loshand to remove it (even if you do not use it).
111808e3e3a7aSWarner Losh
111818e3e3a7aSWarner Losh
111828e3e3a7aSWarner Losh<p>
111838e3e3a7aSWarner LoshWhen possible,
111848e3e3a7aSWarner Loshyou may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>,
111858e3e3a7aSWarner Loshwhich automatically removes the file when the program ends.
111868e3e3a7aSWarner Losh
111878e3e3a7aSWarner Losh
111888e3e3a7aSWarner Losh
111898e3e3a7aSWarner Losh
111908e3e3a7aSWarner Losh
111918e3e3a7aSWarner Losh
111928e3e3a7aSWarner Losh
111938e3e3a7aSWarner Losh<h2>6.10 &ndash; <a name="6.10">The Debug Library</a></h2>
111948e3e3a7aSWarner Losh
111958e3e3a7aSWarner Losh<p>
111968e3e3a7aSWarner LoshThis library provides
111970495ed39SKyle Evansthe functionality of the debug interface (<a href="#4.7">&sect;4.7</a>) to Lua programs.
111988e3e3a7aSWarner LoshYou should exert care when using this library.
111998e3e3a7aSWarner LoshSeveral of its functions
112008e3e3a7aSWarner Loshviolate basic assumptions about Lua code
112018e3e3a7aSWarner Losh(e.g., that variables local to a function
112028e3e3a7aSWarner Loshcannot be accessed from outside;
112038e3e3a7aSWarner Loshthat userdata metatables cannot be changed by Lua code;
112048e3e3a7aSWarner Loshthat Lua programs do not crash)
112058e3e3a7aSWarner Loshand therefore can compromise otherwise secure code.
112068e3e3a7aSWarner LoshMoreover, some functions in this library may be slow.
112078e3e3a7aSWarner Losh
112088e3e3a7aSWarner Losh
112098e3e3a7aSWarner Losh<p>
112108e3e3a7aSWarner LoshAll functions in this library are provided
112118e3e3a7aSWarner Loshinside the <a name="pdf-debug"><code>debug</code></a> table.
112128e3e3a7aSWarner LoshAll functions that operate over a thread
112138e3e3a7aSWarner Loshhave an optional first argument which is the
112148e3e3a7aSWarner Loshthread to operate over.
112158e3e3a7aSWarner LoshThe default is always the current thread.
112168e3e3a7aSWarner Losh
112178e3e3a7aSWarner Losh
112188e3e3a7aSWarner Losh<p>
112198e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3>
112208e3e3a7aSWarner Losh
112218e3e3a7aSWarner Losh
112228e3e3a7aSWarner Losh<p>
112238e3e3a7aSWarner LoshEnters an interactive mode with the user,
112248e3e3a7aSWarner Loshrunning each string that the user enters.
112258e3e3a7aSWarner LoshUsing simple commands and other debug facilities,
112268e3e3a7aSWarner Loshthe user can inspect global and local variables,
112278e3e3a7aSWarner Loshchange their values, evaluate expressions, and so on.
112288e3e3a7aSWarner LoshA line containing only the word <code>cont</code> finishes this function,
112298e3e3a7aSWarner Loshso that the caller continues its execution.
112308e3e3a7aSWarner Losh
112318e3e3a7aSWarner Losh
112328e3e3a7aSWarner Losh<p>
112338e3e3a7aSWarner LoshNote that commands for <code>debug.debug</code> are not lexically nested
112348e3e3a7aSWarner Loshwithin any function and so have no direct access to local variables.
112358e3e3a7aSWarner Losh
112368e3e3a7aSWarner Losh
112378e3e3a7aSWarner Losh
112388e3e3a7aSWarner Losh
112398e3e3a7aSWarner Losh<p>
112408e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3>
112418e3e3a7aSWarner Losh
112428e3e3a7aSWarner Losh
112438e3e3a7aSWarner Losh<p>
112448e3e3a7aSWarner LoshReturns the current hook settings of the thread, as three values:
112458e3e3a7aSWarner Loshthe current hook function, the current hook mask,
112460495ed39SKyle Evansand the current hook count,
112470495ed39SKyle Evansas set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function.
112480495ed39SKyle Evans
112490495ed39SKyle Evans
112500495ed39SKyle Evans<p>
112510495ed39SKyle EvansReturns <b>fail</b> if there is no active hook.
112528e3e3a7aSWarner Losh
112538e3e3a7aSWarner Losh
112548e3e3a7aSWarner Losh
112558e3e3a7aSWarner Losh
112568e3e3a7aSWarner Losh<p>
112578e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3>
112588e3e3a7aSWarner Losh
112598e3e3a7aSWarner Losh
112608e3e3a7aSWarner Losh<p>
112618e3e3a7aSWarner LoshReturns a table with information about a function.
112628e3e3a7aSWarner LoshYou can give the function directly
112638e3e3a7aSWarner Loshor you can give a number as the value of <code>f</code>,
112648e3e3a7aSWarner Loshwhich means the function running at level <code>f</code> of the call stack
112658e3e3a7aSWarner Loshof the given thread:
112668e3e3a7aSWarner Loshlevel&nbsp;0 is the current function (<code>getinfo</code> itself);
112678e3e3a7aSWarner Loshlevel&nbsp;1 is the function that called <code>getinfo</code>
112680495ed39SKyle Evans(except for tail calls, which do not count in the stack);
112698e3e3a7aSWarner Loshand so on.
112700495ed39SKyle EvansIf <code>f</code> is a number greater than the number of active functions,
112710495ed39SKyle Evansthen <code>getinfo</code> returns <b>fail</b>.
112728e3e3a7aSWarner Losh
112738e3e3a7aSWarner Losh
112748e3e3a7aSWarner Losh<p>
112758e3e3a7aSWarner LoshThe returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>,
112768e3e3a7aSWarner Loshwith the string <code>what</code> describing which fields to fill in.
112778e3e3a7aSWarner LoshThe default for <code>what</code> is to get all information available,
112788e3e3a7aSWarner Loshexcept the table of valid lines.
112798e3e3a7aSWarner LoshIf present,
112808e3e3a7aSWarner Loshthe option '<code>f</code>'
112818e3e3a7aSWarner Loshadds a field named <code>func</code> with the function itself.
112828e3e3a7aSWarner LoshIf present,
112838e3e3a7aSWarner Loshthe option '<code>L</code>'
112848e3e3a7aSWarner Loshadds a field named <code>activelines</code> with the table of
112858e3e3a7aSWarner Loshvalid lines.
112868e3e3a7aSWarner Losh
112878e3e3a7aSWarner Losh
112888e3e3a7aSWarner Losh<p>
112898e3e3a7aSWarner LoshFor instance, the expression <code>debug.getinfo(1,"n").name</code> returns
112908e3e3a7aSWarner Losha name for the current function,
112918e3e3a7aSWarner Loshif a reasonable name can be found,
112928e3e3a7aSWarner Loshand the expression <code>debug.getinfo(print)</code>
112938e3e3a7aSWarner Loshreturns a table with all available information
112948e3e3a7aSWarner Loshabout the <a href="#pdf-print"><code>print</code></a> function.
112958e3e3a7aSWarner Losh
112968e3e3a7aSWarner Losh
112978e3e3a7aSWarner Losh
112988e3e3a7aSWarner Losh
112998e3e3a7aSWarner Losh<p>
113008e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3>
113018e3e3a7aSWarner Losh
113028e3e3a7aSWarner Losh
113038e3e3a7aSWarner Losh<p>
113048e3e3a7aSWarner LoshThis function returns the name and the value of the local variable
113058e3e3a7aSWarner Loshwith index <code>local</code> of the function at level <code>f</code> of the stack.
113068e3e3a7aSWarner LoshThis function accesses not only explicit local variables,
113070495ed39SKyle Evansbut also parameters and temporary values.
113088e3e3a7aSWarner Losh
113098e3e3a7aSWarner Losh
113108e3e3a7aSWarner Losh<p>
113118e3e3a7aSWarner LoshThe first parameter or local variable has index&nbsp;1, and so on,
113128e3e3a7aSWarner Loshfollowing the order that they are declared in the code,
113138e3e3a7aSWarner Loshcounting only the variables that are active
113148e3e3a7aSWarner Loshin the current scope of the function.
113150495ed39SKyle EvansCompile-time constants may not appear in this listing,
113160495ed39SKyle Evansif they were optimized away by the compiler.
11317e112e9d2SKyle EvansNegative indices refer to vararg arguments;
11318e112e9d2SKyle Evans-1 is the first vararg argument.
113190495ed39SKyle EvansThe function returns <b>fail</b>
113200495ed39SKyle Evansif there is no variable with the given index,
113218e3e3a7aSWarner Loshand raises an error when called with a level out of range.
113228e3e3a7aSWarner Losh(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.)
113238e3e3a7aSWarner Losh
113248e3e3a7aSWarner Losh
113258e3e3a7aSWarner Losh<p>
113268e3e3a7aSWarner LoshVariable names starting with '<code>(</code>' (open parenthesis)
113278e3e3a7aSWarner Loshrepresent variables with no known names
113288e3e3a7aSWarner Losh(internal variables such as loop control variables,
113298e3e3a7aSWarner Loshand variables from chunks saved without debug information).
113308e3e3a7aSWarner Losh
113318e3e3a7aSWarner Losh
113328e3e3a7aSWarner Losh<p>
113338e3e3a7aSWarner LoshThe parameter <code>f</code> may also be a function.
113348e3e3a7aSWarner LoshIn that case, <code>getlocal</code> returns only the name of function parameters.
113358e3e3a7aSWarner Losh
113368e3e3a7aSWarner Losh
113378e3e3a7aSWarner Losh
113388e3e3a7aSWarner Losh
113398e3e3a7aSWarner Losh<p>
113408e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3>
113418e3e3a7aSWarner Losh
113428e3e3a7aSWarner Losh
113438e3e3a7aSWarner Losh<p>
113448e3e3a7aSWarner LoshReturns the metatable of the given <code>value</code>
113458e3e3a7aSWarner Loshor <b>nil</b> if it does not have a metatable.
113468e3e3a7aSWarner Losh
113478e3e3a7aSWarner Losh
113488e3e3a7aSWarner Losh
113498e3e3a7aSWarner Losh
113508e3e3a7aSWarner Losh<p>
113518e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3>
113528e3e3a7aSWarner Losh
113538e3e3a7aSWarner Losh
113548e3e3a7aSWarner Losh<p>
113550495ed39SKyle EvansReturns the registry table (see <a href="#4.3">&sect;4.3</a>).
113568e3e3a7aSWarner Losh
113578e3e3a7aSWarner Losh
113588e3e3a7aSWarner Losh
113598e3e3a7aSWarner Losh
113608e3e3a7aSWarner Losh<p>
113618e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3>
113628e3e3a7aSWarner Losh
113638e3e3a7aSWarner Losh
113648e3e3a7aSWarner Losh<p>
113658e3e3a7aSWarner LoshThis function returns the name and the value of the upvalue
113668e3e3a7aSWarner Loshwith index <code>up</code> of the function <code>f</code>.
113670495ed39SKyle EvansThe function returns <b>fail</b>
113680495ed39SKyle Evansif there is no upvalue with the given index.
113698e3e3a7aSWarner Losh
113708e3e3a7aSWarner Losh
113718e3e3a7aSWarner Losh<p>
113720495ed39SKyle Evans(For Lua functions,
113730495ed39SKyle Evansupvalues are the external local variables that the function uses,
113740495ed39SKyle Evansand that are consequently included in its closure.)
113750495ed39SKyle Evans
113760495ed39SKyle Evans
113770495ed39SKyle Evans<p>
113780495ed39SKyle EvansFor C&nbsp;functions, this function uses the empty string <code>""</code>
113790495ed39SKyle Evansas a name for all upvalues.
113800495ed39SKyle Evans
113810495ed39SKyle Evans
113820495ed39SKyle Evans<p>
113830495ed39SKyle EvansVariable name '<code>?</code>' (interrogation mark)
113840495ed39SKyle Evansrepresents variables with no known names
113858e3e3a7aSWarner Losh(variables from chunks saved without debug information).
113868e3e3a7aSWarner Losh
113878e3e3a7aSWarner Losh
113888e3e3a7aSWarner Losh
113898e3e3a7aSWarner Losh
113908e3e3a7aSWarner Losh<p>
113910495ed39SKyle Evans<hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u, n)</code></a></h3>
113928e3e3a7aSWarner Losh
113938e3e3a7aSWarner Losh
113948e3e3a7aSWarner Losh<p>
113950495ed39SKyle EvansReturns the <code>n</code>-th user value associated
113960495ed39SKyle Evansto the userdata <code>u</code> plus a boolean,
113970495ed39SKyle Evans<b>false</b> if the userdata does not have that value.
113988e3e3a7aSWarner Losh
113998e3e3a7aSWarner Losh
114008e3e3a7aSWarner Losh
114018e3e3a7aSWarner Losh
114028e3e3a7aSWarner Losh<p>
114038e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3>
114048e3e3a7aSWarner Losh
114058e3e3a7aSWarner Losh
114068e3e3a7aSWarner Losh<p>
114070495ed39SKyle EvansSets the given function as the debug hook.
114088e3e3a7aSWarner LoshThe string <code>mask</code> and the number <code>count</code> describe
114098e3e3a7aSWarner Loshwhen the hook will be called.
114108e3e3a7aSWarner LoshThe string mask may have any combination of the following characters,
114118e3e3a7aSWarner Loshwith the given meaning:
114128e3e3a7aSWarner Losh
114138e3e3a7aSWarner Losh<ul>
114148e3e3a7aSWarner Losh<li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li>
114158e3e3a7aSWarner Losh<li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li>
114168e3e3a7aSWarner Losh<li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li>
114178e3e3a7aSWarner Losh</ul><p>
114188e3e3a7aSWarner LoshMoreover,
114198e3e3a7aSWarner Loshwith a <code>count</code> different from zero,
114208e3e3a7aSWarner Loshthe hook is called also after every <code>count</code> instructions.
114218e3e3a7aSWarner Losh
114228e3e3a7aSWarner Losh
114238e3e3a7aSWarner Losh<p>
114248e3e3a7aSWarner LoshWhen called without arguments,
114258e3e3a7aSWarner Losh<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook.
114268e3e3a7aSWarner Losh
114278e3e3a7aSWarner Losh
114288e3e3a7aSWarner Losh<p>
114290495ed39SKyle EvansWhen the hook is called, its first parameter is a string
114308e3e3a7aSWarner Loshdescribing the event that has triggered its call:
114310495ed39SKyle Evans<code>"call"</code>, <code>"tail call"</code>, <code>"return"</code>,
114328e3e3a7aSWarner Losh<code>"line"</code>, and <code>"count"</code>.
114338e3e3a7aSWarner LoshFor line events,
114348e3e3a7aSWarner Loshthe hook also gets the new line number as its second parameter.
114358e3e3a7aSWarner LoshInside a hook,
114368e3e3a7aSWarner Loshyou can call <code>getinfo</code> with level&nbsp;2 to get more information about
114370495ed39SKyle Evansthe running function.
114380495ed39SKyle Evans(Level&nbsp;0 is the <code>getinfo</code> function,
114390495ed39SKyle Evansand level&nbsp;1 is the hook function.)
114408e3e3a7aSWarner Losh
114418e3e3a7aSWarner Losh
114428e3e3a7aSWarner Losh
114438e3e3a7aSWarner Losh
114448e3e3a7aSWarner Losh<p>
114458e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3>
114468e3e3a7aSWarner Losh
114478e3e3a7aSWarner Losh
114488e3e3a7aSWarner Losh<p>
114498e3e3a7aSWarner LoshThis function assigns the value <code>value</code> to the local variable
114508e3e3a7aSWarner Loshwith index <code>local</code> of the function at level <code>level</code> of the stack.
114510495ed39SKyle EvansThe function returns <b>fail</b> if there is no local
114528e3e3a7aSWarner Loshvariable with the given index,
114538e3e3a7aSWarner Loshand raises an error when called with a <code>level</code> out of range.
114548e3e3a7aSWarner Losh(You can call <code>getinfo</code> to check whether the level is valid.)
114558e3e3a7aSWarner LoshOtherwise, it returns the name of the local variable.
114568e3e3a7aSWarner Losh
114578e3e3a7aSWarner Losh
114588e3e3a7aSWarner Losh<p>
114598e3e3a7aSWarner LoshSee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about
114608e3e3a7aSWarner Loshvariable indices and names.
114618e3e3a7aSWarner Losh
114628e3e3a7aSWarner Losh
114638e3e3a7aSWarner Losh
114648e3e3a7aSWarner Losh
114658e3e3a7aSWarner Losh<p>
114668e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3>
114678e3e3a7aSWarner Losh
114688e3e3a7aSWarner Losh
114698e3e3a7aSWarner Losh<p>
114708e3e3a7aSWarner LoshSets the metatable for the given <code>value</code> to the given <code>table</code>
114718e3e3a7aSWarner Losh(which can be <b>nil</b>).
114728e3e3a7aSWarner LoshReturns <code>value</code>.
114738e3e3a7aSWarner Losh
114748e3e3a7aSWarner Losh
114758e3e3a7aSWarner Losh
114768e3e3a7aSWarner Losh
114778e3e3a7aSWarner Losh<p>
114788e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3>
114798e3e3a7aSWarner Losh
114808e3e3a7aSWarner Losh
114818e3e3a7aSWarner Losh<p>
114828e3e3a7aSWarner LoshThis function assigns the value <code>value</code> to the upvalue
114838e3e3a7aSWarner Loshwith index <code>up</code> of the function <code>f</code>.
114840495ed39SKyle EvansThe function returns <b>fail</b> if there is no upvalue
114858e3e3a7aSWarner Loshwith the given index.
114868e3e3a7aSWarner LoshOtherwise, it returns the name of the upvalue.
114878e3e3a7aSWarner Losh
114888e3e3a7aSWarner Losh
114890495ed39SKyle Evans<p>
114900495ed39SKyle EvansSee <a href="#pdf-debug.getupvalue"><code>debug.getupvalue</code></a> for more information about upvalues.
114910495ed39SKyle Evans
114920495ed39SKyle Evans
114938e3e3a7aSWarner Losh
114948e3e3a7aSWarner Losh
114958e3e3a7aSWarner Losh<p>
114960495ed39SKyle Evans<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value, n)</code></a></h3>
114978e3e3a7aSWarner Losh
114988e3e3a7aSWarner Losh
114998e3e3a7aSWarner Losh<p>
115008e3e3a7aSWarner LoshSets the given <code>value</code> as
115010495ed39SKyle Evansthe <code>n</code>-th user value associated to the given <code>udata</code>.
115028e3e3a7aSWarner Losh<code>udata</code> must be a full userdata.
115038e3e3a7aSWarner Losh
115048e3e3a7aSWarner Losh
115058e3e3a7aSWarner Losh<p>
115060495ed39SKyle EvansReturns <code>udata</code>,
115070495ed39SKyle Evansor <b>fail</b> if the userdata does not have that value.
115088e3e3a7aSWarner Losh
115098e3e3a7aSWarner Losh
115108e3e3a7aSWarner Losh
115118e3e3a7aSWarner Losh
115128e3e3a7aSWarner Losh<p>
115138e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3>
115148e3e3a7aSWarner Losh
115158e3e3a7aSWarner Losh
115168e3e3a7aSWarner Losh<p>
115178e3e3a7aSWarner LoshIf <code>message</code> is present but is neither a string nor <b>nil</b>,
115188e3e3a7aSWarner Loshthis function returns <code>message</code> without further processing.
115198e3e3a7aSWarner LoshOtherwise,
115208e3e3a7aSWarner Loshit returns a string with a traceback of the call stack.
115218e3e3a7aSWarner LoshThe optional <code>message</code> string is appended
115228e3e3a7aSWarner Loshat the beginning of the traceback.
115238e3e3a7aSWarner LoshAn optional <code>level</code> number tells at which level
115248e3e3a7aSWarner Loshto start the traceback
115258e3e3a7aSWarner Losh(default is 1, the function calling <code>traceback</code>).
115268e3e3a7aSWarner Losh
115278e3e3a7aSWarner Losh
115288e3e3a7aSWarner Losh
115298e3e3a7aSWarner Losh
115308e3e3a7aSWarner Losh<p>
115318e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3>
115328e3e3a7aSWarner Losh
115338e3e3a7aSWarner Losh
115348e3e3a7aSWarner Losh<p>
115358e3e3a7aSWarner LoshReturns a unique identifier (as a light userdata)
115368e3e3a7aSWarner Loshfor the upvalue numbered <code>n</code>
115378e3e3a7aSWarner Loshfrom the given function.
115388e3e3a7aSWarner Losh
115398e3e3a7aSWarner Losh
115408e3e3a7aSWarner Losh<p>
115418e3e3a7aSWarner LoshThese unique identifiers allow a program to check whether different
115428e3e3a7aSWarner Loshclosures share upvalues.
115438e3e3a7aSWarner LoshLua closures that share an upvalue
115448e3e3a7aSWarner Losh(that is, that access a same external local variable)
115458e3e3a7aSWarner Loshwill return identical ids for those upvalue indices.
115468e3e3a7aSWarner Losh
115478e3e3a7aSWarner Losh
115488e3e3a7aSWarner Losh
115498e3e3a7aSWarner Losh
115508e3e3a7aSWarner Losh<p>
115518e3e3a7aSWarner Losh<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3>
115528e3e3a7aSWarner Losh
115538e3e3a7aSWarner Losh
115548e3e3a7aSWarner Losh<p>
115558e3e3a7aSWarner LoshMake the <code>n1</code>-th upvalue of the Lua closure <code>f1</code>
115568e3e3a7aSWarner Loshrefer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>.
115578e3e3a7aSWarner Losh
115588e3e3a7aSWarner Losh
115598e3e3a7aSWarner Losh
115608e3e3a7aSWarner Losh
115618e3e3a7aSWarner Losh
115628e3e3a7aSWarner Losh
115638e3e3a7aSWarner Losh
115648e3e3a7aSWarner Losh<h1>7 &ndash; <a name="7">Lua Standalone</a></h1>
115658e3e3a7aSWarner Losh
115668e3e3a7aSWarner Losh<p>
115678e3e3a7aSWarner LoshAlthough Lua has been designed as an extension language,
115688e3e3a7aSWarner Loshto be embedded in a host C&nbsp;program,
115698e3e3a7aSWarner Loshit is also frequently used as a standalone language.
115708e3e3a7aSWarner LoshAn interpreter for Lua as a standalone language,
115718e3e3a7aSWarner Loshcalled simply <code>lua</code>,
115728e3e3a7aSWarner Loshis provided with the standard distribution.
115738e3e3a7aSWarner LoshThe standalone interpreter includes
115740495ed39SKyle Evansall standard libraries.
115758e3e3a7aSWarner LoshIts usage is:
115768e3e3a7aSWarner Losh
115778e3e3a7aSWarner Losh<pre>
115788e3e3a7aSWarner Losh     lua [options] [script [args]]
115798e3e3a7aSWarner Losh</pre><p>
115808e3e3a7aSWarner LoshThe options are:
115818e3e3a7aSWarner Losh
115828e3e3a7aSWarner Losh<ul>
115830495ed39SKyle Evans<li><b><code>-e <em>stat</em></code>: </b> execute string <em>stat</em>;</li>
115840495ed39SKyle Evans<li><b><code>-i</code>: </b> enter interactive mode after running <em>script</em>;</li>
115850495ed39SKyle Evans<li><b><code>-l <em>mod</em></code>: </b> "require" <em>mod</em> and assign the
115860495ed39SKyle Evans  result to global <em>mod</em>;</li>
11587*a9490b81SWarner Losh<li><b><code>-l <em>g=mod</em></code>: </b> "require" <em>mod</em> and assign the
11588*a9490b81SWarner Losh  result to global <em>g</em>;</li>
115890495ed39SKyle Evans<li><b><code>-v</code>: </b> print version information;</li>
115900495ed39SKyle Evans<li><b><code>-E</code>: </b> ignore environment variables;</li>
115910495ed39SKyle Evans<li><b><code>-W</code>: </b> turn warnings on;</li>
115920495ed39SKyle Evans<li><b><code>--</code>: </b> stop handling options;</li>
115930495ed39SKyle Evans<li><b><code>-</code>: </b> execute <code>stdin</code> as a file and stop handling options.</li>
115948e3e3a7aSWarner Losh</ul><p>
11595*a9490b81SWarner Losh(The form <code>-l <em>g=mod</em></code> was introduced in release&nbsp;5.4.4.)
11596*a9490b81SWarner Losh
11597*a9490b81SWarner Losh
11598*a9490b81SWarner Losh<p>
115998e3e3a7aSWarner LoshAfter handling its options, <code>lua</code> runs the given <em>script</em>.
116008e3e3a7aSWarner LoshWhen called without arguments,
116018e3e3a7aSWarner Losh<code>lua</code> behaves as <code>lua -v -i</code>
116028e3e3a7aSWarner Loshwhen the standard input (<code>stdin</code>) is a terminal,
116038e3e3a7aSWarner Loshand as <code>lua -</code> otherwise.
116048e3e3a7aSWarner Losh
116058e3e3a7aSWarner Losh
116068e3e3a7aSWarner Losh<p>
116070495ed39SKyle EvansWhen called without the option <code>-E</code>,
116080495ed39SKyle Evansthe interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_4"><code>LUA_INIT_5_4</code></a>
116098e3e3a7aSWarner Losh(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined)
116108e3e3a7aSWarner Loshbefore running any argument.
116118e3e3a7aSWarner LoshIf the variable content has the format <code>@<em>filename</em></code>,
116128e3e3a7aSWarner Loshthen <code>lua</code> executes the file.
116138e3e3a7aSWarner LoshOtherwise, <code>lua</code> executes the string itself.
116148e3e3a7aSWarner Losh
116158e3e3a7aSWarner Losh
116168e3e3a7aSWarner Losh<p>
116170495ed39SKyle EvansWhen called with the option <code>-E</code>,
116180495ed39SKyle EvansLua does not consult any environment variables.
116190495ed39SKyle EvansIn particular,
116200495ed39SKyle Evansthe values of <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a>
116210495ed39SKyle Evansare set with the default paths defined in <code>luaconf.h</code>.
116228e3e3a7aSWarner Losh
116238e3e3a7aSWarner Losh
116248e3e3a7aSWarner Losh<p>
116250495ed39SKyle EvansThe options <code>-e</code>, <code>-l</code>, and <code>-W</code> are handled in
116260495ed39SKyle Evansthe order they appear.
116278e3e3a7aSWarner LoshFor instance, an invocation like
116288e3e3a7aSWarner Losh
116298e3e3a7aSWarner Losh<pre>
116300495ed39SKyle Evans     $ lua -e 'a=1' -llib1 script.lua
116318e3e3a7aSWarner Losh</pre><p>
116320495ed39SKyle Evanswill first set <code>a</code> to 1, then require the library <code>lib1</code>,
116338e3e3a7aSWarner Loshand finally run the file <code>script.lua</code> with no arguments.
116348e3e3a7aSWarner Losh(Here <code>$</code> is the shell prompt. Your prompt may be different.)
116358e3e3a7aSWarner Losh
116368e3e3a7aSWarner Losh
116378e3e3a7aSWarner Losh<p>
116388e3e3a7aSWarner LoshBefore running any code,
116398e3e3a7aSWarner Losh<code>lua</code> collects all command-line arguments
116408e3e3a7aSWarner Loshin a global table called <code>arg</code>.
116418e3e3a7aSWarner LoshThe script name goes to index 0,
116428e3e3a7aSWarner Loshthe first argument after the script name goes to index 1,
116438e3e3a7aSWarner Loshand so on.
116448e3e3a7aSWarner LoshAny arguments before the script name
116458e3e3a7aSWarner Losh(that is, the interpreter name plus its options)
116468e3e3a7aSWarner Loshgo to negative indices.
116478e3e3a7aSWarner LoshFor instance, in the call
116488e3e3a7aSWarner Losh
116498e3e3a7aSWarner Losh<pre>
116508e3e3a7aSWarner Losh     $ lua -la b.lua t1 t2
116518e3e3a7aSWarner Losh</pre><p>
116528e3e3a7aSWarner Loshthe table is like this:
116538e3e3a7aSWarner Losh
116548e3e3a7aSWarner Losh<pre>
116558e3e3a7aSWarner Losh     arg = { [-2] = "lua", [-1] = "-la",
116568e3e3a7aSWarner Losh             [0] = "b.lua",
116578e3e3a7aSWarner Losh             [1] = "t1", [2] = "t2" }
116588e3e3a7aSWarner Losh</pre><p>
116598e3e3a7aSWarner LoshIf there is no script in the call,
116608e3e3a7aSWarner Loshthe interpreter name goes to index 0,
116618e3e3a7aSWarner Loshfollowed by the other arguments.
116628e3e3a7aSWarner LoshFor instance, the call
116638e3e3a7aSWarner Losh
116648e3e3a7aSWarner Losh<pre>
116658e3e3a7aSWarner Losh     $ lua -e "print(arg[1])"
116668e3e3a7aSWarner Losh</pre><p>
116678e3e3a7aSWarner Loshwill print "<code>-e</code>".
116688e3e3a7aSWarner LoshIf there is a script,
11669e112e9d2SKyle Evansthe script is called with arguments
116708e3e3a7aSWarner Losh<code>arg[1]</code>, &middot;&middot;&middot;, <code>arg[#arg]</code>.
116710495ed39SKyle EvansLike all chunks in Lua,
11672*a9490b81SWarner Loshthe script is compiled as a variadic function.
116738e3e3a7aSWarner Losh
116748e3e3a7aSWarner Losh
116758e3e3a7aSWarner Losh<p>
116768e3e3a7aSWarner LoshIn interactive mode,
116778e3e3a7aSWarner LoshLua repeatedly prompts and waits for a line.
116788e3e3a7aSWarner LoshAfter reading a line,
116798e3e3a7aSWarner LoshLua first try to interpret the line as an expression.
116808e3e3a7aSWarner LoshIf it succeeds, it prints its value.
116818e3e3a7aSWarner LoshOtherwise, it interprets the line as a statement.
116828e3e3a7aSWarner LoshIf you write an incomplete statement,
116838e3e3a7aSWarner Loshthe interpreter waits for its completion
116848e3e3a7aSWarner Loshby issuing a different prompt.
116858e3e3a7aSWarner Losh
116868e3e3a7aSWarner Losh
116878e3e3a7aSWarner Losh<p>
116888e3e3a7aSWarner LoshIf the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string,
116898e3e3a7aSWarner Loshthen its value is used as the prompt.
116908e3e3a7aSWarner LoshSimilarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string,
116918e3e3a7aSWarner Loshits value is used as the secondary prompt
116928e3e3a7aSWarner Losh(issued during incomplete statements).
116938e3e3a7aSWarner Losh
116948e3e3a7aSWarner Losh
116958e3e3a7aSWarner Losh<p>
116968e3e3a7aSWarner LoshIn case of unprotected errors in the script,
116978e3e3a7aSWarner Loshthe interpreter reports the error to the standard error stream.
116988e3e3a7aSWarner LoshIf the error object is not a string but
116998e3e3a7aSWarner Loshhas a metamethod <code>__tostring</code>,
117008e3e3a7aSWarner Loshthe interpreter calls this metamethod to produce the final message.
117018e3e3a7aSWarner LoshOtherwise, the interpreter converts the error object to a string
117028e3e3a7aSWarner Loshand adds a stack traceback to it.
117030495ed39SKyle EvansWhen warnings are on,
117040495ed39SKyle Evansthey are simply printed in the standard error output.
117058e3e3a7aSWarner Losh
117068e3e3a7aSWarner Losh
117078e3e3a7aSWarner Losh<p>
117088e3e3a7aSWarner LoshWhen finishing normally,
117098e3e3a7aSWarner Loshthe interpreter closes its main Lua state
117108e3e3a7aSWarner Losh(see <a href="#lua_close"><code>lua_close</code></a>).
117118e3e3a7aSWarner LoshThe script can avoid this step by
117128e3e3a7aSWarner Loshcalling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate.
117138e3e3a7aSWarner Losh
117148e3e3a7aSWarner Losh
117158e3e3a7aSWarner Losh<p>
117168e3e3a7aSWarner LoshTo allow the use of Lua as a
117178e3e3a7aSWarner Loshscript interpreter in Unix systems,
117180495ed39SKyle EvansLua skips the first line of a file chunk if it starts with <code>#</code>.
117198e3e3a7aSWarner LoshTherefore, Lua scripts can be made into executable programs
117208e3e3a7aSWarner Loshby using <code>chmod +x</code> and the&nbsp;<code>#!</code> form,
117218e3e3a7aSWarner Loshas in
117228e3e3a7aSWarner Losh
117238e3e3a7aSWarner Losh<pre>
117248e3e3a7aSWarner Losh     #!/usr/local/bin/lua
117258e3e3a7aSWarner Losh</pre><p>
117260495ed39SKyle EvansOf course,
117278e3e3a7aSWarner Loshthe location of the Lua interpreter may be different in your machine.
117288e3e3a7aSWarner LoshIf <code>lua</code> is in your <code>PATH</code>,
117298e3e3a7aSWarner Loshthen
117308e3e3a7aSWarner Losh
117318e3e3a7aSWarner Losh<pre>
117328e3e3a7aSWarner Losh     #!/usr/bin/env lua
117338e3e3a7aSWarner Losh</pre><p>
117340495ed39SKyle Evansis a more portable solution.
117358e3e3a7aSWarner Losh
117368e3e3a7aSWarner Losh
117378e3e3a7aSWarner Losh
117388e3e3a7aSWarner Losh<h1>8 &ndash; <a name="8">Incompatibilities with the Previous Version</a></h1>
117398e3e3a7aSWarner Losh
117400495ed39SKyle Evans
117410495ed39SKyle Evans
117428e3e3a7aSWarner Losh<p>
117438e3e3a7aSWarner LoshHere we list the incompatibilities that you may find when moving a program
117440495ed39SKyle Evansfrom Lua&nbsp;5.3 to Lua&nbsp;5.4.
117450495ed39SKyle Evans
117460495ed39SKyle Evans
117470495ed39SKyle Evans<p>
117488e3e3a7aSWarner LoshYou can avoid some incompatibilities by compiling Lua with
117498e3e3a7aSWarner Loshappropriate options (see file <code>luaconf.h</code>).
117508e3e3a7aSWarner LoshHowever,
117518e3e3a7aSWarner Loshall these compatibility options will be removed in the future.
117520495ed39SKyle EvansMore often than not,
117530495ed39SKyle Evanscompatibility issues arise when these compatibility options
117540495ed39SKyle Evansare removed.
117550495ed39SKyle EvansSo, whenever you have the chance,
117560495ed39SKyle Evansyou should try to test your code with a version of Lua compiled
117570495ed39SKyle Evanswith all compatibility options turned off.
117580495ed39SKyle EvansThat will ease transitions to newer versions of Lua.
117598e3e3a7aSWarner Losh
117608e3e3a7aSWarner Losh
117618e3e3a7aSWarner Losh<p>
117628e3e3a7aSWarner LoshLua versions can always change the C API in ways that
117638e3e3a7aSWarner Loshdo not imply source-code changes in a program,
117648e3e3a7aSWarner Loshsuch as the numeric values for constants
117658e3e3a7aSWarner Loshor the implementation of functions as macros.
117668e3e3a7aSWarner LoshTherefore,
117670495ed39SKyle Evansyou should never assume that binaries are compatible between
117688e3e3a7aSWarner Loshdifferent Lua versions.
117698e3e3a7aSWarner LoshAlways recompile clients of the Lua API when
117708e3e3a7aSWarner Loshusing a new version.
117718e3e3a7aSWarner Losh
117728e3e3a7aSWarner Losh
117738e3e3a7aSWarner Losh<p>
117748e3e3a7aSWarner LoshSimilarly, Lua versions can always change the internal representation
117758e3e3a7aSWarner Loshof precompiled chunks;
117768e3e3a7aSWarner Loshprecompiled chunks are not compatible between different Lua versions.
117778e3e3a7aSWarner Losh
117788e3e3a7aSWarner Losh
117798e3e3a7aSWarner Losh<p>
117808e3e3a7aSWarner LoshThe standard paths in the official distribution may
117818e3e3a7aSWarner Loshchange between versions.
117828e3e3a7aSWarner Losh
117838e3e3a7aSWarner Losh
117848e3e3a7aSWarner Losh
117850495ed39SKyle Evans
117860495ed39SKyle Evans
117870495ed39SKyle Evans<h2>8.1 &ndash; <a name="8.1">Incompatibilities in the Language</a></h2>
117888e3e3a7aSWarner Losh<ul>
117898e3e3a7aSWarner Losh
117908e3e3a7aSWarner Losh<li>
117910495ed39SKyle EvansThe coercion of strings to numbers in
117920495ed39SKyle Evansarithmetic and bitwise operations
117930495ed39SKyle Evanshas been removed from the core language.
117940495ed39SKyle EvansThe string library does a similar job
117950495ed39SKyle Evansfor arithmetic (but not for bitwise) operations
117960495ed39SKyle Evansusing the string metamethods.
117970495ed39SKyle EvansHowever, unlike in previous versions,
117980495ed39SKyle Evansthe new implementation preserves the implicit type of the numeral
117990495ed39SKyle Evansin the string.
118000495ed39SKyle EvansFor instance, the result of <code>"1" + "2"</code> now is an integer,
118010495ed39SKyle Evansnot a float.
118028e3e3a7aSWarner Losh</li>
118038e3e3a7aSWarner Losh
118048e3e3a7aSWarner Losh<li>
118050495ed39SKyle EvansLiteral decimal integer constants that overflow are read as floats,
118060495ed39SKyle Evansinstead of wrapping around.
118070495ed39SKyle EvansYou can use hexadecimal notation for such constants if you
118080495ed39SKyle Evanswant the old behavior
118090495ed39SKyle Evans(reading them as integers with wrap around).
118108e3e3a7aSWarner Losh</li>
118118e3e3a7aSWarner Losh
118128e3e3a7aSWarner Losh<li>
118130495ed39SKyle EvansThe use of the <code>__lt</code> metamethod to emulate <code>__le</code>
118140495ed39SKyle Evanshas been removed.
118150495ed39SKyle EvansWhen needed, this metamethod must be explicitly defined.
118160495ed39SKyle Evans</li>
118170495ed39SKyle Evans
118180495ed39SKyle Evans<li>
118190495ed39SKyle EvansThe semantics of the numerical <b>for</b> loop
118200495ed39SKyle Evansover integers changed in some details.
118210495ed39SKyle EvansIn particular, the control variable never wraps around.
118220495ed39SKyle Evans</li>
118230495ed39SKyle Evans
118240495ed39SKyle Evans<li>
118250495ed39SKyle EvansA label for a <b>goto</b> cannot be declared where a label with the same
118260495ed39SKyle Evansname is visible, even if this other label is declared in an enclosing
118270495ed39SKyle Evansblock.
118280495ed39SKyle Evans</li>
118290495ed39SKyle Evans
118300495ed39SKyle Evans<li>
118310495ed39SKyle EvansWhen finalizing an object,
118320495ed39SKyle EvansLua does not ignore <code>__gc</code> metamethods that are not functions.
118330495ed39SKyle EvansAny value will be called, if present.
118340495ed39SKyle Evans(Non-callable values will generate a warning,
118350495ed39SKyle Evanslike any other error when calling a finalizer.)
118368e3e3a7aSWarner Losh</li>
118378e3e3a7aSWarner Losh
118388e3e3a7aSWarner Losh</ul>
118398e3e3a7aSWarner Losh
118408e3e3a7aSWarner Losh
118418e3e3a7aSWarner Losh
118428e3e3a7aSWarner Losh
118430495ed39SKyle Evans<h2>8.2 &ndash; <a name="8.2">Incompatibilities in the Libraries</a></h2>
118448e3e3a7aSWarner Losh<ul>
118458e3e3a7aSWarner Losh
118468e3e3a7aSWarner Losh<li>
118470495ed39SKyle EvansThe function <a href="#pdf-print"><code>print</code></a> does not call <a href="#pdf-tostring"><code>tostring</code></a>
118480495ed39SKyle Evansto format its arguments;
118490495ed39SKyle Evansinstead, it has this functionality hardwired.
118500495ed39SKyle EvansYou should use <code>__tostring</code> to modify how values are printed.
118518e3e3a7aSWarner Losh</li>
118528e3e3a7aSWarner Losh
118538e3e3a7aSWarner Losh<li>
118540495ed39SKyle EvansThe pseudo-random number generator used by the function <a href="#pdf-math.random"><code>math.random</code></a>
118550495ed39SKyle Evansnow starts with a somewhat random seed.
118560495ed39SKyle EvansMoreover, it uses a different algorithm.
118578e3e3a7aSWarner Losh</li>
118588e3e3a7aSWarner Losh
118598e3e3a7aSWarner Losh<li>
118600495ed39SKyle EvansBy default, the decoding functions in the <a href="#pdf-utf8"><code>utf8</code></a> library
118610495ed39SKyle Evansdo not accept surrogates as valid code points.
118620495ed39SKyle EvansAn extra parameter in these functions makes them more permissive.
118638e3e3a7aSWarner Losh</li>
118648e3e3a7aSWarner Losh
118658e3e3a7aSWarner Losh<li>
118660495ed39SKyle EvansThe options "<code>setpause</code>" and "<code>setstepmul</code>"
118670495ed39SKyle Evansof the function <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> are deprecated.
118680495ed39SKyle EvansYou should use the new option "<code>incremental</code>" to set them.
118698e3e3a7aSWarner Losh</li>
118708e3e3a7aSWarner Losh
118718e3e3a7aSWarner Losh<li>
118720495ed39SKyle EvansThe function <a href="#pdf-io.lines"><code>io.lines</code></a> now returns four values,
118730495ed39SKyle Evansinstead of just one.
118740495ed39SKyle EvansThat can be a problem when it is used as the sole
118750495ed39SKyle Evansargument to another function that has optional parameters,
118760495ed39SKyle Evanssuch as in <code>load(io.lines(filename, "L"))</code>.
118770495ed39SKyle EvansTo fix that issue,
118780495ed39SKyle Evansyou can wrap the call into parentheses,
118790495ed39SKyle Evansto adjust its number of results to one.
118808e3e3a7aSWarner Losh</li>
118818e3e3a7aSWarner Losh
118828e3e3a7aSWarner Losh</ul>
118838e3e3a7aSWarner Losh
118848e3e3a7aSWarner Losh
118858e3e3a7aSWarner Losh
118868e3e3a7aSWarner Losh
118870495ed39SKyle Evans<h2>8.3 &ndash; <a name="8.3">Incompatibilities in the API</a></h2>
118888e3e3a7aSWarner Losh
118898e3e3a7aSWarner Losh
118908e3e3a7aSWarner Losh<ul>
118918e3e3a7aSWarner Losh
118928e3e3a7aSWarner Losh<li>
118930495ed39SKyle EvansFull userdata now has an arbitrary number of associated user values.
118940495ed39SKyle EvansTherefore, the functions <code>lua_newuserdata</code>,
118950495ed39SKyle Evans<code>lua_setuservalue</code>, and <code>lua_getuservalue</code> were
118960495ed39SKyle Evansreplaced by <a href="#lua_newuserdatauv"><code>lua_newuserdatauv</code></a>,
118970495ed39SKyle Evans<a href="#lua_setiuservalue"><code>lua_setiuservalue</code></a>, and <a href="#lua_getiuservalue"><code>lua_getiuservalue</code></a>,
118980495ed39SKyle Evanswhich have an extra argument.
118990495ed39SKyle Evans
119000495ed39SKyle Evans
119010495ed39SKyle Evans<p>
119020495ed39SKyle EvansFor compatibility, the old names still work as macros assuming
119030495ed39SKyle Evansone single user value.
119040495ed39SKyle EvansNote, however, that userdata with zero user values
119050495ed39SKyle Evansare more efficient memory-wise.
119068e3e3a7aSWarner Losh</li>
119078e3e3a7aSWarner Losh
119088e3e3a7aSWarner Losh<li>
119090495ed39SKyle EvansThe function <a href="#lua_resume"><code>lua_resume</code></a> has an extra parameter.
119100495ed39SKyle EvansThis out parameter returns the number of values on
119110495ed39SKyle Evansthe top of the stack that were yielded or returned by the coroutine.
119120495ed39SKyle Evans(In previous versions,
119130495ed39SKyle Evansthose values were the entire stack.)
119148e3e3a7aSWarner Losh</li>
119158e3e3a7aSWarner Losh
119168e3e3a7aSWarner Losh<li>
119170495ed39SKyle EvansThe function <a href="#lua_version"><code>lua_version</code></a> returns the version number,
119180495ed39SKyle Evansinstead of an address of the version number.
119190495ed39SKyle EvansThe Lua core should work correctly with libraries using their
119200495ed39SKyle Evansown static copies of the same core,
119210495ed39SKyle Evansso there is no need to check whether they are using the same
119220495ed39SKyle Evansaddress space.
119238e3e3a7aSWarner Losh</li>
119248e3e3a7aSWarner Losh
119258e3e3a7aSWarner Losh<li>
119260495ed39SKyle EvansThe constant <code>LUA_ERRGCMM</code> was removed.
119270495ed39SKyle EvansErrors in finalizers are never propagated;
119280495ed39SKyle Evansinstead, they generate a warning.
119290495ed39SKyle Evans</li>
119300495ed39SKyle Evans
119310495ed39SKyle Evans<li>
119320495ed39SKyle EvansThe options <code>LUA_GCSETPAUSE</code> and <code>LUA_GCSETSTEPMUL</code>
119330495ed39SKyle Evansof the function <a href="#lua_gc"><code>lua_gc</code></a> are deprecated.
119340495ed39SKyle EvansYou should use the new option <code>LUA_GCINC</code> to set them.
119358e3e3a7aSWarner Losh</li>
119368e3e3a7aSWarner Losh
119378e3e3a7aSWarner Losh</ul>
119388e3e3a7aSWarner Losh
119398e3e3a7aSWarner Losh
119408e3e3a7aSWarner Losh
119418e3e3a7aSWarner Losh
119428e3e3a7aSWarner Losh<h1>9 &ndash; <a name="9">The Complete Syntax of Lua</a></h1>
119438e3e3a7aSWarner Losh
119448e3e3a7aSWarner Losh<p>
119458e3e3a7aSWarner LoshHere is the complete syntax of Lua in extended BNF.
119468e3e3a7aSWarner LoshAs usual in extended BNF,
119478e3e3a7aSWarner Losh{A} means 0 or more As,
119488e3e3a7aSWarner Loshand [A] means an optional A.
119498e3e3a7aSWarner Losh(For operator precedences, see <a href="#3.4.8">&sect;3.4.8</a>;
119508e3e3a7aSWarner Loshfor a description of the terminals
119518e3e3a7aSWarner LoshName, Numeral,
119528e3e3a7aSWarner Loshand LiteralString, see <a href="#3.1">&sect;3.1</a>.)
119538e3e3a7aSWarner Losh
119548e3e3a7aSWarner Losh
119558e3e3a7aSWarner Losh
119568e3e3a7aSWarner Losh
119578e3e3a7aSWarner Losh<pre>
119588e3e3a7aSWarner Losh
119598e3e3a7aSWarner Losh	chunk ::= block
119608e3e3a7aSWarner Losh
119618e3e3a7aSWarner Losh	block ::= {stat} [retstat]
119628e3e3a7aSWarner Losh
119638e3e3a7aSWarner Losh	stat ::=  &lsquo;<b>;</b>&rsquo; |
119648e3e3a7aSWarner Losh		 varlist &lsquo;<b>=</b>&rsquo; explist |
119658e3e3a7aSWarner Losh		 functioncall |
119668e3e3a7aSWarner Losh		 label |
119678e3e3a7aSWarner Losh		 <b>break</b> |
119688e3e3a7aSWarner Losh		 <b>goto</b> Name |
119698e3e3a7aSWarner Losh		 <b>do</b> block <b>end</b> |
119708e3e3a7aSWarner Losh		 <b>while</b> exp <b>do</b> block <b>end</b> |
119718e3e3a7aSWarner Losh		 <b>repeat</b> block <b>until</b> exp |
119728e3e3a7aSWarner Losh		 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> |
119738e3e3a7aSWarner Losh		 <b>for</b> Name &lsquo;<b>=</b>&rsquo; exp &lsquo;<b>,</b>&rsquo; exp [&lsquo;<b>,</b>&rsquo; exp] <b>do</b> block <b>end</b> |
119748e3e3a7aSWarner Losh		 <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> |
119758e3e3a7aSWarner Losh		 <b>function</b> funcname funcbody |
119768e3e3a7aSWarner Losh		 <b>local</b> <b>function</b> Name funcbody |
119770495ed39SKyle Evans		 <b>local</b> attnamelist [&lsquo;<b>=</b>&rsquo; explist]
119780495ed39SKyle Evans
119790495ed39SKyle Evans	attnamelist ::=  Name attrib {&lsquo;<b>,</b>&rsquo; Name attrib}
119800495ed39SKyle Evans
119810495ed39SKyle Evans	attrib ::= [&lsquo;<b>&lt;</b>&rsquo; Name &lsquo;<b>&gt;</b>&rsquo;]
119828e3e3a7aSWarner Losh
119838e3e3a7aSWarner Losh	retstat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
119848e3e3a7aSWarner Losh
119858e3e3a7aSWarner Losh	label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
119868e3e3a7aSWarner Losh
119878e3e3a7aSWarner Losh	funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
119888e3e3a7aSWarner Losh
119898e3e3a7aSWarner Losh	varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
119908e3e3a7aSWarner Losh
119918e3e3a7aSWarner Losh	var ::=  Name | prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; | prefixexp &lsquo;<b>.</b>&rsquo; Name
119928e3e3a7aSWarner Losh
119938e3e3a7aSWarner Losh	namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
119948e3e3a7aSWarner Losh
119958e3e3a7aSWarner Losh	explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
119968e3e3a7aSWarner Losh
119978e3e3a7aSWarner Losh	exp ::=  <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | &lsquo;<b>...</b>&rsquo; | functiondef |
119988e3e3a7aSWarner Losh		 prefixexp | tableconstructor | exp binop exp | unop exp
119998e3e3a7aSWarner Losh
120008e3e3a7aSWarner Losh	prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
120018e3e3a7aSWarner Losh
120028e3e3a7aSWarner Losh	functioncall ::=  prefixexp args | prefixexp &lsquo;<b>:</b>&rsquo; Name args
120038e3e3a7aSWarner Losh
120048e3e3a7aSWarner Losh	args ::=  &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo; | tableconstructor | LiteralString
120058e3e3a7aSWarner Losh
120068e3e3a7aSWarner Losh	functiondef ::= <b>function</b> funcbody
120078e3e3a7aSWarner Losh
120088e3e3a7aSWarner Losh	funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
120098e3e3a7aSWarner Losh
120108e3e3a7aSWarner Losh	parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
120118e3e3a7aSWarner Losh
120128e3e3a7aSWarner Losh	tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
120138e3e3a7aSWarner Losh
120148e3e3a7aSWarner Losh	fieldlist ::= field {fieldsep field} [fieldsep]
120158e3e3a7aSWarner Losh
120168e3e3a7aSWarner Losh	field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
120178e3e3a7aSWarner Losh
120188e3e3a7aSWarner Losh	fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
120198e3e3a7aSWarner Losh
120208e3e3a7aSWarner 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; |
120218e3e3a7aSWarner 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; |
120228e3e3a7aSWarner 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; |
120238e3e3a7aSWarner Losh		 <b>and</b> | <b>or</b>
120248e3e3a7aSWarner Losh
120258e3e3a7aSWarner Losh	unop ::= &lsquo;<b>-</b>&rsquo; | <b>not</b> | &lsquo;<b>#</b>&rsquo; | &lsquo;<b>~</b>&rsquo;
120268e3e3a7aSWarner Losh
120278e3e3a7aSWarner Losh</pre>
120288e3e3a7aSWarner Losh
120298e3e3a7aSWarner Losh<p>
120308e3e3a7aSWarner Losh
120318e3e3a7aSWarner Losh
120328e3e3a7aSWarner Losh
120338e3e3a7aSWarner Losh
120348e3e3a7aSWarner Losh
120358e3e3a7aSWarner Losh
120368e3e3a7aSWarner Losh
120378e3e3a7aSWarner Losh<P CLASS="footer">
120388e3e3a7aSWarner LoshLast update:
12039*a9490b81SWarner LoshTue May  2 20:09:38 UTC 2023
120408e3e3a7aSWarner Losh</P>
120418e3e3a7aSWarner Losh<!--
12042*a9490b81SWarner LoshLast change: revised for Lua 5.4.6
120438e3e3a7aSWarner Losh-->
120448e3e3a7aSWarner Losh
120458e3e3a7aSWarner Losh</body></html>
120468e3e3a7aSWarner Losh
12047