121d3294cSantirez<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 221d3294cSantirez<html> 321d3294cSantirez 421d3294cSantirez<head> 521d3294cSantirez<title>Lua 5.1 Reference Manual</title> 621d3294cSantirez<link rel="stylesheet" type="text/css" href="lua.css"> 721d3294cSantirez<link rel="stylesheet" type="text/css" href="manual.css"> 821d3294cSantirez<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> 921d3294cSantirez</head> 1021d3294cSantirez 1121d3294cSantirez<body> 1221d3294cSantirez 1321d3294cSantirez<hr> 1421d3294cSantirez<h1> 1521d3294cSantirez<a href="http://www.lua.org/"><img src="logo.gif" alt="" border="0"></a> 1621d3294cSantirezLua 5.1 Reference Manual 1721d3294cSantirez</h1> 1821d3294cSantirez 1921d3294cSantirezby Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes 2021d3294cSantirez<p> 2121d3294cSantirez<small> 22*214adc50SantirezCopyright © 2006–2012 Lua.org, PUC-Rio. 2321d3294cSantirezFreely available under the terms of the 24*214adc50Santirez<a href="http://www.lua.org/license.html">Lua license</a>. 2521d3294cSantirez</small> 2621d3294cSantirez<hr> 2721d3294cSantirez<p> 2821d3294cSantirez 2921d3294cSantirez<a href="contents.html#contents">contents</A> 3021d3294cSantirez· 3121d3294cSantirez<a href="contents.html#index">index</A> 32*214adc50Santirez· 33*214adc50Santirez<A HREF="http://www.lua.org/manual/">other versions</A> 3421d3294cSantirez 3521d3294cSantirez<!-- ====================================================================== --> 3621d3294cSantirez<p> 3721d3294cSantirez 38*214adc50Santirez<!-- $Id: manual.of,v 1.49.1.2 2012/01/13 20:23:26 roberto Exp $ --> 3921d3294cSantirez 4021d3294cSantirez 4121d3294cSantirez 4221d3294cSantirez 4321d3294cSantirez<h1>1 - <a name="1">Introduction</a></h1> 4421d3294cSantirez 4521d3294cSantirez<p> 4621d3294cSantirezLua is an extension programming language designed to support 4721d3294cSantirezgeneral procedural programming with data description 4821d3294cSantirezfacilities. 4921d3294cSantirezIt also offers good support for object-oriented programming, 5021d3294cSantirezfunctional programming, and data-driven programming. 5121d3294cSantirezLua is intended to be used as a powerful, light-weight 5221d3294cSantirezscripting language for any program that needs one. 5321d3294cSantirezLua is implemented as a library, written in <em>clean</em> C 5421d3294cSantirez(that is, in the common subset of ANSI C and C++). 5521d3294cSantirez 5621d3294cSantirez 5721d3294cSantirez<p> 5821d3294cSantirezBeing an extension language, Lua has no notion of a "main" program: 5921d3294cSantirezit only works <em>embedded</em> in a host client, 6021d3294cSantirezcalled the <em>embedding program</em> or simply the <em>host</em>. 6121d3294cSantirezThis host program can invoke functions to execute a piece of Lua code, 6221d3294cSantirezcan write and read Lua variables, 6321d3294cSantirezand can register C functions to be called by Lua code. 6421d3294cSantirezThrough the use of C functions, Lua can be augmented to cope with 6521d3294cSantireza wide range of different domains, 6621d3294cSantirezthus creating customized programming languages sharing a syntactical framework. 6721d3294cSantirezThe Lua distribution includes a sample host program called <code>lua</code>, 6821d3294cSantirezwhich uses the Lua library to offer a complete, stand-alone Lua interpreter. 6921d3294cSantirez 7021d3294cSantirez 7121d3294cSantirez<p> 7221d3294cSantirezLua is free software, 7321d3294cSantirezand is provided as usual with no guarantees, 7421d3294cSantirezas stated in its license. 7521d3294cSantirezThe implementation described in this manual is available 7621d3294cSantirezat Lua's official web site, <code>www.lua.org</code>. 7721d3294cSantirez 7821d3294cSantirez 7921d3294cSantirez<p> 8021d3294cSantirezLike any other reference manual, 8121d3294cSantirezthis document is dry in places. 8221d3294cSantirezFor a discussion of the decisions behind the design of Lua, 8321d3294cSantirezsee the technical papers available at Lua's web site. 8421d3294cSantirezFor a detailed introduction to programming in Lua, 8521d3294cSantirezsee Roberto's book, <em>Programming in Lua (Second Edition)</em>. 8621d3294cSantirez 8721d3294cSantirez 8821d3294cSantirez 8921d3294cSantirez<h1>2 - <a name="2">The Language</a></h1> 9021d3294cSantirez 9121d3294cSantirez<p> 9221d3294cSantirezThis section describes the lexis, the syntax, and the semantics of Lua. 9321d3294cSantirezIn other words, 9421d3294cSantirezthis section describes 9521d3294cSantirezwhich tokens are valid, 9621d3294cSantirezhow they can be combined, 9721d3294cSantirezand what their combinations mean. 9821d3294cSantirez 9921d3294cSantirez 10021d3294cSantirez<p> 10121d3294cSantirezThe language constructs will be explained using the usual extended BNF notation, 10221d3294cSantirezin which 10321d3294cSantirez{<em>a</em>} means 0 or more <em>a</em>'s, and 10421d3294cSantirez[<em>a</em>] means an optional <em>a</em>. 10521d3294cSantirezNon-terminals are shown like non-terminal, 10621d3294cSantirezkeywords are shown like <b>kword</b>, 10721d3294cSantirezand other terminal symbols are shown like `<b>=</b>´. 10821d3294cSantirezThe complete syntax of Lua can be found in <a href="#8">§8</a> 10921d3294cSantirezat the end of this manual. 11021d3294cSantirez 11121d3294cSantirez 11221d3294cSantirez 11321d3294cSantirez<h2>2.1 - <a name="2.1">Lexical Conventions</a></h2> 11421d3294cSantirez 11521d3294cSantirez<p> 11621d3294cSantirez<em>Names</em> 11721d3294cSantirez(also called <em>identifiers</em>) 11821d3294cSantirezin Lua can be any string of letters, 11921d3294cSantirezdigits, and underscores, 12021d3294cSantireznot beginning with a digit. 12121d3294cSantirezThis coincides with the definition of names in most languages. 12221d3294cSantirez(The definition of letter depends on the current locale: 12321d3294cSantirezany character considered alphabetic by the current locale 12421d3294cSantirezcan be used in an identifier.) 12521d3294cSantirezIdentifiers are used to name variables and table fields. 12621d3294cSantirez 12721d3294cSantirez 12821d3294cSantirez<p> 12921d3294cSantirezThe following <em>keywords</em> are reserved 13021d3294cSantirezand cannot be used as names: 13121d3294cSantirez 13221d3294cSantirez 13321d3294cSantirez<pre> 13421d3294cSantirez and break do else elseif 13521d3294cSantirez end false for function if 13621d3294cSantirez in local nil not or 13721d3294cSantirez repeat return then true until while 13821d3294cSantirez</pre> 13921d3294cSantirez 14021d3294cSantirez<p> 14121d3294cSantirezLua is a case-sensitive language: 14221d3294cSantirez<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> 14321d3294cSantirezare two different, valid names. 14421d3294cSantirezAs a convention, names starting with an underscore followed by 14521d3294cSantirezuppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>) 14621d3294cSantirezare reserved for internal global variables used by Lua. 14721d3294cSantirez 14821d3294cSantirez 14921d3294cSantirez<p> 15021d3294cSantirezThe following strings denote other tokens: 15121d3294cSantirez 15221d3294cSantirez<pre> 15321d3294cSantirez + - * / % ^ # 15421d3294cSantirez == ~= <= >= < > = 15521d3294cSantirez ( ) { } [ ] 15621d3294cSantirez ; : , . .. ... 15721d3294cSantirez</pre> 15821d3294cSantirez 15921d3294cSantirez<p> 16021d3294cSantirez<em>Literal strings</em> 16121d3294cSantirezcan be delimited by matching single or double quotes, 16221d3294cSantirezand can contain the following C-like escape sequences: 16321d3294cSantirez'<code>\a</code>' (bell), 16421d3294cSantirez'<code>\b</code>' (backspace), 16521d3294cSantirez'<code>\f</code>' (form feed), 16621d3294cSantirez'<code>\n</code>' (newline), 16721d3294cSantirez'<code>\r</code>' (carriage return), 16821d3294cSantirez'<code>\t</code>' (horizontal tab), 16921d3294cSantirez'<code>\v</code>' (vertical tab), 17021d3294cSantirez'<code>\\</code>' (backslash), 17121d3294cSantirez'<code>\"</code>' (quotation mark [double quote]), 17221d3294cSantirezand '<code>\'</code>' (apostrophe [single quote]). 17321d3294cSantirezMoreover, a backslash followed by a real newline 17421d3294cSantirezresults in a newline in the string. 17521d3294cSantirezA character in a string can also be specified by its numerical value 17621d3294cSantirezusing the escape sequence <code>\<em>ddd</em></code>, 17721d3294cSantirezwhere <em>ddd</em> is a sequence of up to three decimal digits. 17821d3294cSantirez(Note that if a numerical escape is to be followed by a digit, 17921d3294cSantirezit must be expressed using exactly three digits.) 18021d3294cSantirezStrings in Lua can contain any 8-bit value, including embedded zeros, 18121d3294cSantirezwhich can be specified as '<code>\0</code>'. 18221d3294cSantirez 18321d3294cSantirez 18421d3294cSantirez<p> 18521d3294cSantirezLiteral strings can also be defined using a long format 18621d3294cSantirezenclosed by <em>long brackets</em>. 18721d3294cSantirezWe define an <em>opening long bracket of level <em>n</em></em> as an opening 18821d3294cSantirezsquare bracket followed by <em>n</em> equal signs followed by another 18921d3294cSantirezopening square bracket. 19021d3294cSantirezSo, an opening long bracket of level 0 is written as <code>[[</code>, 19121d3294cSantirezan opening long bracket of level 1 is written as <code>[=[</code>, 19221d3294cSantirezand so on. 19321d3294cSantirezA <em>closing long bracket</em> is defined similarly; 19421d3294cSantirezfor instance, a closing long bracket of level 4 is written as <code>]====]</code>. 19521d3294cSantirezA long string starts with an opening long bracket of any level and 19621d3294cSantirezends at the first closing long bracket of the same level. 19721d3294cSantirezLiterals in this bracketed form can run for several lines, 19821d3294cSantirezdo not interpret any escape sequences, 19921d3294cSantirezand ignore long brackets of any other level. 20021d3294cSantirezThey can contain anything except a closing bracket of the proper level. 20121d3294cSantirez 20221d3294cSantirez 20321d3294cSantirez<p> 20421d3294cSantirezFor convenience, 20521d3294cSantirezwhen the opening long bracket is immediately followed by a newline, 20621d3294cSantirezthe newline is not included in the string. 20721d3294cSantirezAs an example, in a system using ASCII 20821d3294cSantirez(in which '<code>a</code>' is coded as 97, 20921d3294cSantireznewline is coded as 10, and '<code>1</code>' is coded as 49), 21021d3294cSantirezthe five literal strings below denote the same string: 21121d3294cSantirez 21221d3294cSantirez<pre> 21321d3294cSantirez a = 'alo\n123"' 21421d3294cSantirez a = "alo\n123\"" 21521d3294cSantirez a = '\97lo\10\04923"' 21621d3294cSantirez a = [[alo 21721d3294cSantirez 123"]] 21821d3294cSantirez a = [==[ 21921d3294cSantirez alo 22021d3294cSantirez 123"]==] 22121d3294cSantirez</pre> 22221d3294cSantirez 22321d3294cSantirez<p> 22421d3294cSantirezA <em>numerical constant</em> can be written with an optional decimal part 22521d3294cSantirezand an optional decimal exponent. 22621d3294cSantirezLua also accepts integer hexadecimal constants, 22721d3294cSantirezby prefixing them with <code>0x</code>. 22821d3294cSantirezExamples of valid numerical constants are 22921d3294cSantirez 23021d3294cSantirez<pre> 23121d3294cSantirez 3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56 23221d3294cSantirez</pre> 23321d3294cSantirez 23421d3294cSantirez<p> 23521d3294cSantirezA <em>comment</em> starts with a double hyphen (<code>--</code>) 23621d3294cSantirezanywhere outside a string. 23721d3294cSantirezIf the text immediately after <code>--</code> is not an opening long bracket, 23821d3294cSantirezthe comment is a <em>short comment</em>, 23921d3294cSantirezwhich runs until the end of the line. 24021d3294cSantirezOtherwise, it is a <em>long comment</em>, 24121d3294cSantirezwhich runs until the corresponding closing long bracket. 24221d3294cSantirezLong comments are frequently used to disable code temporarily. 24321d3294cSantirez 24421d3294cSantirez 24521d3294cSantirez 24621d3294cSantirez 24721d3294cSantirez 24821d3294cSantirez<h2>2.2 - <a name="2.2">Values and Types</a></h2> 24921d3294cSantirez 25021d3294cSantirez<p> 25121d3294cSantirezLua is a <em>dynamically typed language</em>. 25221d3294cSantirezThis means that 25321d3294cSantirezvariables do not have types; only values do. 25421d3294cSantirezThere are no type definitions in the language. 25521d3294cSantirezAll values carry their own type. 25621d3294cSantirez 25721d3294cSantirez 25821d3294cSantirez<p> 25921d3294cSantirezAll values in Lua are <em>first-class values</em>. 26021d3294cSantirezThis means that all values can be stored in variables, 26121d3294cSantirezpassed as arguments to other functions, and returned as results. 26221d3294cSantirez 26321d3294cSantirez 26421d3294cSantirez<p> 26521d3294cSantirezThere are eight basic types in Lua: 26621d3294cSantirez<em>nil</em>, <em>boolean</em>, <em>number</em>, 26721d3294cSantirez<em>string</em>, <em>function</em>, <em>userdata</em>, 26821d3294cSantirez<em>thread</em>, and <em>table</em>. 26921d3294cSantirez<em>Nil</em> is the type of the value <b>nil</b>, 27021d3294cSantirezwhose main property is to be different from any other value; 27121d3294cSantirezit usually represents the absence of a useful value. 27221d3294cSantirez<em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>. 27321d3294cSantirezBoth <b>nil</b> and <b>false</b> make a condition false; 27421d3294cSantirezany other value makes it true. 27521d3294cSantirez<em>Number</em> represents real (double-precision floating-point) numbers. 27621d3294cSantirez(It is easy to build Lua interpreters that use other 27721d3294cSantirezinternal representations for numbers, 27821d3294cSantirezsuch as single-precision float or long integers; 27921d3294cSantirezsee file <code>luaconf.h</code>.) 28021d3294cSantirez<em>String</em> represents arrays of characters. 28121d3294cSantirez 28221d3294cSantirezLua is 8-bit clean: 28321d3294cSantirezstrings can contain any 8-bit character, 28421d3294cSantirezincluding embedded zeros ('<code>\0</code>') (see <a href="#2.1">§2.1</a>). 28521d3294cSantirez 28621d3294cSantirez 28721d3294cSantirez<p> 28821d3294cSantirezLua can call (and manipulate) functions written in Lua and 28921d3294cSantirezfunctions written in C 29021d3294cSantirez(see <a href="#2.5.8">§2.5.8</a>). 29121d3294cSantirez 29221d3294cSantirez 29321d3294cSantirez<p> 29421d3294cSantirezThe type <em>userdata</em> is provided to allow arbitrary C data to 29521d3294cSantirezbe stored in Lua variables. 29621d3294cSantirezThis type corresponds to a block of raw memory 29721d3294cSantirezand has no pre-defined operations in Lua, 29821d3294cSantirezexcept assignment and identity test. 29921d3294cSantirezHowever, by using <em>metatables</em>, 30021d3294cSantirezthe programmer can define operations for userdata values 30121d3294cSantirez(see <a href="#2.8">§2.8</a>). 30221d3294cSantirezUserdata values cannot be created or modified in Lua, 30321d3294cSantirezonly through the C API. 30421d3294cSantirezThis guarantees the integrity of data owned by the host program. 30521d3294cSantirez 30621d3294cSantirez 30721d3294cSantirez<p> 30821d3294cSantirezThe type <em>thread</em> represents independent threads of execution 30921d3294cSantirezand it is used to implement coroutines (see <a href="#2.11">§2.11</a>). 31021d3294cSantirezDo not confuse Lua threads with operating-system threads. 31121d3294cSantirezLua supports coroutines on all systems, 31221d3294cSantirezeven those that do not support threads. 31321d3294cSantirez 31421d3294cSantirez 31521d3294cSantirez<p> 31621d3294cSantirezThe type <em>table</em> implements associative arrays, 31721d3294cSantirezthat is, arrays that can be indexed not only with numbers, 31821d3294cSantirezbut with any value (except <b>nil</b>). 31921d3294cSantirezTables can be <em>heterogeneous</em>; 32021d3294cSantirezthat is, they can contain values of all types (except <b>nil</b>). 32121d3294cSantirezTables are the sole data structuring mechanism in Lua; 32221d3294cSantirezthey can be used to represent ordinary arrays, 32321d3294cSantirezsymbol tables, sets, records, graphs, trees, etc. 32421d3294cSantirezTo represent records, Lua uses the field name as an index. 32521d3294cSantirezThe language supports this representation by 32621d3294cSantirezproviding <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. 32721d3294cSantirezThere are several convenient ways to create tables in Lua 32821d3294cSantirez(see <a href="#2.5.7">§2.5.7</a>). 32921d3294cSantirez 33021d3294cSantirez 33121d3294cSantirez<p> 33221d3294cSantirezLike indices, 33321d3294cSantirezthe value of a table field can be of any type (except <b>nil</b>). 33421d3294cSantirezIn particular, 33521d3294cSantirezbecause functions are first-class values, 33621d3294cSantireztable fields can contain functions. 33721d3294cSantirezThus tables can also carry <em>methods</em> (see <a href="#2.5.9">§2.5.9</a>). 33821d3294cSantirez 33921d3294cSantirez 34021d3294cSantirez<p> 34121d3294cSantirezTables, functions, threads, and (full) userdata values are <em>objects</em>: 34221d3294cSantirezvariables do not actually <em>contain</em> these values, 34321d3294cSantirezonly <em>references</em> to them. 34421d3294cSantirezAssignment, parameter passing, and function returns 34521d3294cSantirezalways manipulate references to such values; 34621d3294cSantirezthese operations do not imply any kind of copy. 34721d3294cSantirez 34821d3294cSantirez 34921d3294cSantirez<p> 35021d3294cSantirezThe library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type 35121d3294cSantirezof a given value. 35221d3294cSantirez 35321d3294cSantirez 35421d3294cSantirez 35521d3294cSantirez<h3>2.2.1 - <a name="2.2.1">Coercion</a></h3> 35621d3294cSantirez 35721d3294cSantirez<p> 35821d3294cSantirezLua provides automatic conversion between 35921d3294cSantirezstring and number values at run time. 36021d3294cSantirezAny arithmetic operation applied to a string tries to convert 36121d3294cSantirezthis string to a number, following the usual conversion rules. 36221d3294cSantirezConversely, whenever a number is used where a string is expected, 36321d3294cSantirezthe number is converted to a string, in a reasonable format. 36421d3294cSantirezFor complete control over how numbers are converted to strings, 36521d3294cSantirezuse the <code>format</code> function from the string library 36621d3294cSantirez(see <a href="#pdf-string.format"><code>string.format</code></a>). 36721d3294cSantirez 36821d3294cSantirez 36921d3294cSantirez 37021d3294cSantirez 37121d3294cSantirez 37221d3294cSantirez 37321d3294cSantirez 37421d3294cSantirez<h2>2.3 - <a name="2.3">Variables</a></h2> 37521d3294cSantirez 37621d3294cSantirez<p> 37721d3294cSantirezVariables are places that store values. 37821d3294cSantirez 37921d3294cSantirezThere are three kinds of variables in Lua: 38021d3294cSantirezglobal variables, local variables, and table fields. 38121d3294cSantirez 38221d3294cSantirez 38321d3294cSantirez<p> 38421d3294cSantirezA single name can denote a global variable or a local variable 38521d3294cSantirez(or a function's formal parameter, 38621d3294cSantirezwhich is a particular kind of local variable): 38721d3294cSantirez 38821d3294cSantirez<pre> 38921d3294cSantirez var ::= Name 39021d3294cSantirez</pre><p> 39121d3294cSantirezName denotes identifiers, as defined in <a href="#2.1">§2.1</a>. 39221d3294cSantirez 39321d3294cSantirez 39421d3294cSantirez<p> 39521d3294cSantirezAny variable is assumed to be global unless explicitly declared 39621d3294cSantirezas a local (see <a href="#2.4.7">§2.4.7</a>). 39721d3294cSantirezLocal variables are <em>lexically scoped</em>: 39821d3294cSantirezlocal variables can be freely accessed by functions 39921d3294cSantirezdefined inside their scope (see <a href="#2.6">§2.6</a>). 40021d3294cSantirez 40121d3294cSantirez 40221d3294cSantirez<p> 40321d3294cSantirezBefore the first assignment to a variable, its value is <b>nil</b>. 40421d3294cSantirez 40521d3294cSantirez 40621d3294cSantirez<p> 40721d3294cSantirezSquare brackets are used to index a table: 40821d3294cSantirez 40921d3294cSantirez<pre> 41021d3294cSantirez var ::= prefixexp `<b>[</b>´ exp `<b>]</b>´ 41121d3294cSantirez</pre><p> 41221d3294cSantirezThe meaning of accesses to global variables 41321d3294cSantirezand table fields can be changed via metatables. 41421d3294cSantirezAn access to an indexed variable <code>t[i]</code> is equivalent to 41521d3294cSantireza call <code>gettable_event(t,i)</code>. 41621d3294cSantirez(See <a href="#2.8">§2.8</a> for a complete description of the 41721d3294cSantirez<code>gettable_event</code> function. 41821d3294cSantirezThis function is not defined or callable in Lua. 41921d3294cSantirezWe use it here only for explanatory purposes.) 42021d3294cSantirez 42121d3294cSantirez 42221d3294cSantirez<p> 42321d3294cSantirezThe syntax <code>var.Name</code> is just syntactic sugar for 42421d3294cSantirez<code>var["Name"]</code>: 42521d3294cSantirez 42621d3294cSantirez<pre> 42721d3294cSantirez var ::= prefixexp `<b>.</b>´ Name 42821d3294cSantirez</pre> 42921d3294cSantirez 43021d3294cSantirez<p> 43121d3294cSantirezAll global variables live as fields in ordinary Lua tables, 43221d3294cSantirezcalled <em>environment tables</em> or simply 43321d3294cSantirez<em>environments</em> (see <a href="#2.9">§2.9</a>). 43421d3294cSantirezEach function has its own reference to an environment, 43521d3294cSantirezso that all global variables in this function 43621d3294cSantirezwill refer to this environment table. 43721d3294cSantirezWhen a function is created, 43821d3294cSantirezit inherits the environment from the function that created it. 43921d3294cSantirezTo get the environment table of a Lua function, 44021d3294cSantirezyou call <a href="#pdf-getfenv"><code>getfenv</code></a>. 44121d3294cSantirezTo replace it, 44221d3294cSantirezyou call <a href="#pdf-setfenv"><code>setfenv</code></a>. 44321d3294cSantirez(You can only manipulate the environment of C functions 44421d3294cSantirezthrough the debug library; (see <a href="#5.9">§5.9</a>).) 44521d3294cSantirez 44621d3294cSantirez 44721d3294cSantirez<p> 44821d3294cSantirezAn access to a global variable <code>x</code> 44921d3294cSantirezis equivalent to <code>_env.x</code>, 45021d3294cSantirezwhich in turn is equivalent to 45121d3294cSantirez 45221d3294cSantirez<pre> 45321d3294cSantirez gettable_event(_env, "x") 45421d3294cSantirez</pre><p> 45521d3294cSantirezwhere <code>_env</code> is the environment of the running function. 45621d3294cSantirez(See <a href="#2.8">§2.8</a> for a complete description of the 45721d3294cSantirez<code>gettable_event</code> function. 45821d3294cSantirezThis function is not defined or callable in Lua. 45921d3294cSantirezSimilarly, the <code>_env</code> variable is not defined in Lua. 46021d3294cSantirezWe use them here only for explanatory purposes.) 46121d3294cSantirez 46221d3294cSantirez 46321d3294cSantirez 46421d3294cSantirez 46521d3294cSantirez 46621d3294cSantirez<h2>2.4 - <a name="2.4">Statements</a></h2> 46721d3294cSantirez 46821d3294cSantirez<p> 46921d3294cSantirezLua supports an almost conventional set of statements, 47021d3294cSantirezsimilar to those in Pascal or C. 47121d3294cSantirezThis set includes 47221d3294cSantirezassignments, control structures, function calls, 47321d3294cSantirezand variable declarations. 47421d3294cSantirez 47521d3294cSantirez 47621d3294cSantirez 47721d3294cSantirez<h3>2.4.1 - <a name="2.4.1">Chunks</a></h3> 47821d3294cSantirez 47921d3294cSantirez<p> 48021d3294cSantirezThe unit of execution of Lua is called a <em>chunk</em>. 48121d3294cSantirezA chunk is simply a sequence of statements, 48221d3294cSantirezwhich are executed sequentially. 48321d3294cSantirezEach statement can be optionally followed by a semicolon: 48421d3294cSantirez 48521d3294cSantirez<pre> 48621d3294cSantirez chunk ::= {stat [`<b>;</b>´]} 48721d3294cSantirez</pre><p> 48821d3294cSantirezThere are no empty statements and thus '<code>;;</code>' is not legal. 48921d3294cSantirez 49021d3294cSantirez 49121d3294cSantirez<p> 49221d3294cSantirezLua handles a chunk as the body of an anonymous function 49321d3294cSantirezwith a variable number of arguments 49421d3294cSantirez(see <a href="#2.5.9">§2.5.9</a>). 49521d3294cSantirezAs such, chunks can define local variables, 49621d3294cSantirezreceive arguments, and return values. 49721d3294cSantirez 49821d3294cSantirez 49921d3294cSantirez<p> 50021d3294cSantirezA chunk can be stored in a file or in a string inside the host program. 50121d3294cSantirezTo execute a chunk, 50221d3294cSantirezLua first pre-compiles the chunk into instructions for a virtual machine, 50321d3294cSantirezand then it executes the compiled code 50421d3294cSantirezwith an interpreter for the virtual machine. 50521d3294cSantirez 50621d3294cSantirez 50721d3294cSantirez<p> 50821d3294cSantirezChunks can also be pre-compiled into binary form; 50921d3294cSantirezsee program <code>luac</code> for details. 51021d3294cSantirezPrograms in source and compiled forms are interchangeable; 51121d3294cSantirezLua automatically detects the file type and acts accordingly. 51221d3294cSantirez 51321d3294cSantirez 51421d3294cSantirez 51521d3294cSantirez 51621d3294cSantirez 51721d3294cSantirez 51821d3294cSantirez<h3>2.4.2 - <a name="2.4.2">Blocks</a></h3><p> 51921d3294cSantirezA block is a list of statements; 52021d3294cSantirezsyntactically, a block is the same as a chunk: 52121d3294cSantirez 52221d3294cSantirez<pre> 52321d3294cSantirez block ::= chunk 52421d3294cSantirez</pre> 52521d3294cSantirez 52621d3294cSantirez<p> 52721d3294cSantirezA block can be explicitly delimited to produce a single statement: 52821d3294cSantirez 52921d3294cSantirez<pre> 53021d3294cSantirez stat ::= <b>do</b> block <b>end</b> 53121d3294cSantirez</pre><p> 53221d3294cSantirezExplicit blocks are useful 53321d3294cSantirezto control the scope of variable declarations. 53421d3294cSantirezExplicit blocks are also sometimes used to 53521d3294cSantirezadd a <b>return</b> or <b>break</b> statement in the middle 53621d3294cSantirezof another block (see <a href="#2.4.4">§2.4.4</a>). 53721d3294cSantirez 53821d3294cSantirez 53921d3294cSantirez 54021d3294cSantirez 54121d3294cSantirez 54221d3294cSantirez<h3>2.4.3 - <a name="2.4.3">Assignment</a></h3> 54321d3294cSantirez 54421d3294cSantirez<p> 54521d3294cSantirezLua allows multiple assignments. 54621d3294cSantirezTherefore, the syntax for assignment 54721d3294cSantirezdefines a list of variables on the left side 54821d3294cSantirezand a list of expressions on the right side. 54921d3294cSantirezThe elements in both lists are separated by commas: 55021d3294cSantirez 55121d3294cSantirez<pre> 55221d3294cSantirez stat ::= varlist `<b>=</b>´ explist 55321d3294cSantirez varlist ::= var {`<b>,</b>´ var} 55421d3294cSantirez explist ::= exp {`<b>,</b>´ exp} 55521d3294cSantirez</pre><p> 55621d3294cSantirezExpressions are discussed in <a href="#2.5">§2.5</a>. 55721d3294cSantirez 55821d3294cSantirez 55921d3294cSantirez<p> 56021d3294cSantirezBefore the assignment, 56121d3294cSantirezthe list of values is <em>adjusted</em> to the length of 56221d3294cSantirezthe list of variables. 56321d3294cSantirezIf there are more values than needed, 56421d3294cSantirezthe excess values are thrown away. 56521d3294cSantirezIf there are fewer values than needed, 56621d3294cSantirezthe list is extended with as many <b>nil</b>'s as needed. 56721d3294cSantirezIf the list of expressions ends with a function call, 56821d3294cSantirezthen all values returned by that call enter the list of values, 56921d3294cSantirezbefore the adjustment 57021d3294cSantirez(except when the call is enclosed in parentheses; see <a href="#2.5">§2.5</a>). 57121d3294cSantirez 57221d3294cSantirez 57321d3294cSantirez<p> 57421d3294cSantirezThe assignment statement first evaluates all its expressions 57521d3294cSantirezand only then are the assignments performed. 57621d3294cSantirezThus the code 57721d3294cSantirez 57821d3294cSantirez<pre> 57921d3294cSantirez i = 3 58021d3294cSantirez i, a[i] = i+1, 20 58121d3294cSantirez</pre><p> 58221d3294cSantirezsets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 58321d3294cSantirezbecause the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 58421d3294cSantirezbefore it is assigned 4. 58521d3294cSantirezSimilarly, the line 58621d3294cSantirez 58721d3294cSantirez<pre> 58821d3294cSantirez x, y = y, x 58921d3294cSantirez</pre><p> 59021d3294cSantirezexchanges the values of <code>x</code> and <code>y</code>, 59121d3294cSantirezand 59221d3294cSantirez 59321d3294cSantirez<pre> 59421d3294cSantirez x, y, z = y, z, x 59521d3294cSantirez</pre><p> 59621d3294cSantirezcyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 59721d3294cSantirez 59821d3294cSantirez 59921d3294cSantirez<p> 60021d3294cSantirezThe meaning of assignments to global variables 60121d3294cSantirezand table fields can be changed via metatables. 60221d3294cSantirezAn assignment to an indexed variable <code>t[i] = val</code> is equivalent to 60321d3294cSantirez<code>settable_event(t,i,val)</code>. 60421d3294cSantirez(See <a href="#2.8">§2.8</a> for a complete description of the 60521d3294cSantirez<code>settable_event</code> function. 60621d3294cSantirezThis function is not defined or callable in Lua. 60721d3294cSantirezWe use it here only for explanatory purposes.) 60821d3294cSantirez 60921d3294cSantirez 61021d3294cSantirez<p> 61121d3294cSantirezAn assignment to a global variable <code>x = val</code> 61221d3294cSantirezis equivalent to the assignment 61321d3294cSantirez<code>_env.x = val</code>, 61421d3294cSantirezwhich in turn is equivalent to 61521d3294cSantirez 61621d3294cSantirez<pre> 61721d3294cSantirez settable_event(_env, "x", val) 61821d3294cSantirez</pre><p> 61921d3294cSantirezwhere <code>_env</code> is the environment of the running function. 62021d3294cSantirez(The <code>_env</code> variable is not defined in Lua. 62121d3294cSantirezWe use it here only for explanatory purposes.) 62221d3294cSantirez 62321d3294cSantirez 62421d3294cSantirez 62521d3294cSantirez 62621d3294cSantirez 62721d3294cSantirez<h3>2.4.4 - <a name="2.4.4">Control Structures</a></h3><p> 62821d3294cSantirezThe control structures 62921d3294cSantirez<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 63021d3294cSantirezfamiliar syntax: 63121d3294cSantirez 63221d3294cSantirez 63321d3294cSantirez 63421d3294cSantirez 63521d3294cSantirez<pre> 63621d3294cSantirez stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 63721d3294cSantirez stat ::= <b>repeat</b> block <b>until</b> exp 63821d3294cSantirez stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> 63921d3294cSantirez</pre><p> 64021d3294cSantirezLua also has a <b>for</b> statement, in two flavors (see <a href="#2.4.5">§2.4.5</a>). 64121d3294cSantirez 64221d3294cSantirez 64321d3294cSantirez<p> 64421d3294cSantirezThe condition expression of a 64521d3294cSantirezcontrol structure can return any value. 64621d3294cSantirezBoth <b>false</b> and <b>nil</b> are considered false. 64721d3294cSantirezAll values different from <b>nil</b> and <b>false</b> are considered true 64821d3294cSantirez(in particular, the number 0 and the empty string are also true). 64921d3294cSantirez 65021d3294cSantirez 65121d3294cSantirez<p> 65221d3294cSantirezIn the <b>repeat</b>–<b>until</b> loop, 65321d3294cSantirezthe inner block does not end at the <b>until</b> keyword, 65421d3294cSantirezbut only after the condition. 65521d3294cSantirezSo, the condition can refer to local variables 65621d3294cSantirezdeclared inside the loop block. 65721d3294cSantirez 65821d3294cSantirez 65921d3294cSantirez<p> 66021d3294cSantirezThe <b>return</b> statement is used to return values 66121d3294cSantirezfrom a function or a chunk (which is just a function). 66221d3294cSantirez 66321d3294cSantirezFunctions and chunks can return more than one value, 66421d3294cSantirezand so the syntax for the <b>return</b> statement is 66521d3294cSantirez 66621d3294cSantirez<pre> 66721d3294cSantirez stat ::= <b>return</b> [explist] 66821d3294cSantirez</pre> 66921d3294cSantirez 67021d3294cSantirez<p> 67121d3294cSantirezThe <b>break</b> statement is used to terminate the execution of a 67221d3294cSantirez<b>while</b>, <b>repeat</b>, or <b>for</b> loop, 67321d3294cSantirezskipping to the next statement after the loop: 67421d3294cSantirez 67521d3294cSantirez 67621d3294cSantirez<pre> 67721d3294cSantirez stat ::= <b>break</b> 67821d3294cSantirez</pre><p> 67921d3294cSantirezA <b>break</b> ends the innermost enclosing loop. 68021d3294cSantirez 68121d3294cSantirez 68221d3294cSantirez<p> 68321d3294cSantirezThe <b>return</b> and <b>break</b> 68421d3294cSantirezstatements can only be written as the <em>last</em> statement of a block. 68521d3294cSantirezIf it is really necessary to <b>return</b> or <b>break</b> in the 68621d3294cSantirezmiddle of a block, 68721d3294cSantirezthen an explicit inner block can be used, 68821d3294cSantirezas in the idioms 68921d3294cSantirez<code>do return end</code> and <code>do break end</code>, 69021d3294cSantirezbecause now <b>return</b> and <b>break</b> are the last statements in 69121d3294cSantireztheir (inner) blocks. 69221d3294cSantirez 69321d3294cSantirez 69421d3294cSantirez 69521d3294cSantirez 69621d3294cSantirez 69721d3294cSantirez<h3>2.4.5 - <a name="2.4.5">For Statement</a></h3> 69821d3294cSantirez 69921d3294cSantirez<p> 70021d3294cSantirez 70121d3294cSantirezThe <b>for</b> statement has two forms: 70221d3294cSantirezone numeric and one generic. 70321d3294cSantirez 70421d3294cSantirez 70521d3294cSantirez<p> 70621d3294cSantirezThe numeric <b>for</b> loop repeats a block of code while a 70721d3294cSantirezcontrol variable runs through an arithmetic progression. 70821d3294cSantirezIt has the following syntax: 70921d3294cSantirez 71021d3294cSantirez<pre> 71121d3294cSantirez stat ::= <b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b> 71221d3294cSantirez</pre><p> 71321d3294cSantirezThe <em>block</em> is repeated for <em>name</em> starting at the value of 71421d3294cSantirezthe first <em>exp</em>, until it passes the second <em>exp</em> by steps of the 71521d3294cSantirezthird <em>exp</em>. 71621d3294cSantirezMore precisely, a <b>for</b> statement like 71721d3294cSantirez 71821d3294cSantirez<pre> 71921d3294cSantirez for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end 72021d3294cSantirez</pre><p> 72121d3294cSantirezis equivalent to the code: 72221d3294cSantirez 72321d3294cSantirez<pre> 72421d3294cSantirez do 72521d3294cSantirez local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>) 72621d3294cSantirez if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end 72721d3294cSantirez while (<em>step</em> > 0 and <em>var</em> <= <em>limit</em>) or (<em>step</em> <= 0 and <em>var</em> >= <em>limit</em>) do 72821d3294cSantirez local v = <em>var</em> 72921d3294cSantirez <em>block</em> 73021d3294cSantirez <em>var</em> = <em>var</em> + <em>step</em> 73121d3294cSantirez end 73221d3294cSantirez end 73321d3294cSantirez</pre><p> 73421d3294cSantirezNote the following: 73521d3294cSantirez 73621d3294cSantirez<ul> 73721d3294cSantirez 73821d3294cSantirez<li> 73921d3294cSantirezAll three control expressions are evaluated only once, 74021d3294cSantirezbefore the loop starts. 74121d3294cSantirezThey must all result in numbers. 74221d3294cSantirez</li> 74321d3294cSantirez 74421d3294cSantirez<li> 74521d3294cSantirez<code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables. 74621d3294cSantirezThe names shown here are for explanatory purposes only. 74721d3294cSantirez</li> 74821d3294cSantirez 74921d3294cSantirez<li> 75021d3294cSantirezIf the third expression (the step) is absent, 75121d3294cSantirezthen a step of 1 is used. 75221d3294cSantirez</li> 75321d3294cSantirez 75421d3294cSantirez<li> 75521d3294cSantirezYou can use <b>break</b> to exit a <b>for</b> loop. 75621d3294cSantirez</li> 75721d3294cSantirez 75821d3294cSantirez<li> 75921d3294cSantirezThe loop variable <code>v</code> is local to the loop; 76021d3294cSantirezyou cannot use its value after the <b>for</b> ends or is broken. 76121d3294cSantirezIf you need this value, 76221d3294cSantirezassign it to another variable before breaking or exiting the loop. 76321d3294cSantirez</li> 76421d3294cSantirez 76521d3294cSantirez</ul> 76621d3294cSantirez 76721d3294cSantirez<p> 76821d3294cSantirezThe generic <b>for</b> statement works over functions, 76921d3294cSantirezcalled <em>iterators</em>. 77021d3294cSantirezOn each iteration, the iterator function is called to produce a new value, 77121d3294cSantirezstopping when this new value is <b>nil</b>. 77221d3294cSantirezThe generic <b>for</b> loop has the following syntax: 77321d3294cSantirez 77421d3294cSantirez<pre> 77521d3294cSantirez stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> 77621d3294cSantirez namelist ::= Name {`<b>,</b>´ Name} 77721d3294cSantirez</pre><p> 77821d3294cSantirezA <b>for</b> statement like 77921d3294cSantirez 78021d3294cSantirez<pre> 78121d3294cSantirez for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end 78221d3294cSantirez</pre><p> 78321d3294cSantirezis equivalent to the code: 78421d3294cSantirez 78521d3294cSantirez<pre> 78621d3294cSantirez do 78721d3294cSantirez local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em> 78821d3294cSantirez while true do 78921d3294cSantirez local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>) 79021d3294cSantirez <em>var</em> = <em>var_1</em> 79121d3294cSantirez if <em>var</em> == nil then break end 79221d3294cSantirez <em>block</em> 79321d3294cSantirez end 79421d3294cSantirez end 79521d3294cSantirez</pre><p> 79621d3294cSantirezNote the following: 79721d3294cSantirez 79821d3294cSantirez<ul> 79921d3294cSantirez 80021d3294cSantirez<li> 80121d3294cSantirez<code><em>explist</em></code> is evaluated only once. 80221d3294cSantirezIts results are an <em>iterator</em> function, 80321d3294cSantireza <em>state</em>, 80421d3294cSantirezand an initial value for the first <em>iterator variable</em>. 80521d3294cSantirez</li> 80621d3294cSantirez 80721d3294cSantirez<li> 80821d3294cSantirez<code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables. 80921d3294cSantirezThe names are here for explanatory purposes only. 81021d3294cSantirez</li> 81121d3294cSantirez 81221d3294cSantirez<li> 81321d3294cSantirezYou can use <b>break</b> to exit a <b>for</b> loop. 81421d3294cSantirez</li> 81521d3294cSantirez 81621d3294cSantirez<li> 81721d3294cSantirezThe loop variables <code><em>var_i</em></code> are local to the loop; 81821d3294cSantirezyou cannot use their values after the <b>for</b> ends. 81921d3294cSantirezIf you need these values, 82021d3294cSantirezthen assign them to other variables before breaking or exiting the loop. 82121d3294cSantirez</li> 82221d3294cSantirez 82321d3294cSantirez</ul> 82421d3294cSantirez 82521d3294cSantirez 82621d3294cSantirez 82721d3294cSantirez 82821d3294cSantirez<h3>2.4.6 - <a name="2.4.6">Function Calls as Statements</a></h3><p> 82921d3294cSantirezTo allow possible side-effects, 83021d3294cSantirezfunction calls can be executed as statements: 83121d3294cSantirez 83221d3294cSantirez<pre> 83321d3294cSantirez stat ::= functioncall 83421d3294cSantirez</pre><p> 83521d3294cSantirezIn this case, all returned values are thrown away. 83621d3294cSantirezFunction calls are explained in <a href="#2.5.8">§2.5.8</a>. 83721d3294cSantirez 83821d3294cSantirez 83921d3294cSantirez 84021d3294cSantirez 84121d3294cSantirez 84221d3294cSantirez<h3>2.4.7 - <a name="2.4.7">Local Declarations</a></h3><p> 84321d3294cSantirezLocal variables can be declared anywhere inside a block. 84421d3294cSantirezThe declaration can include an initial assignment: 84521d3294cSantirez 84621d3294cSantirez<pre> 84721d3294cSantirez stat ::= <b>local</b> namelist [`<b>=</b>´ explist] 84821d3294cSantirez</pre><p> 84921d3294cSantirezIf present, an initial assignment has the same semantics 85021d3294cSantirezof a multiple assignment (see <a href="#2.4.3">§2.4.3</a>). 85121d3294cSantirezOtherwise, all variables are initialized with <b>nil</b>. 85221d3294cSantirez 85321d3294cSantirez 85421d3294cSantirez<p> 85521d3294cSantirezA chunk is also a block (see <a href="#2.4.1">§2.4.1</a>), 85621d3294cSantirezand so local variables can be declared in a chunk outside any explicit block. 85721d3294cSantirezThe scope of such local variables extends until the end of the chunk. 85821d3294cSantirez 85921d3294cSantirez 86021d3294cSantirez<p> 86121d3294cSantirezThe visibility rules for local variables are explained in <a href="#2.6">§2.6</a>. 86221d3294cSantirez 86321d3294cSantirez 86421d3294cSantirez 86521d3294cSantirez 86621d3294cSantirez 86721d3294cSantirez 86821d3294cSantirez 86921d3294cSantirez<h2>2.5 - <a name="2.5">Expressions</a></h2> 87021d3294cSantirez 87121d3294cSantirez<p> 87221d3294cSantirezThe basic expressions in Lua are the following: 87321d3294cSantirez 87421d3294cSantirez<pre> 87521d3294cSantirez exp ::= prefixexp 87621d3294cSantirez exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 87721d3294cSantirez exp ::= Number 87821d3294cSantirez exp ::= String 87921d3294cSantirez exp ::= function 88021d3294cSantirez exp ::= tableconstructor 88121d3294cSantirez exp ::= `<b>...</b>´ 88221d3294cSantirez exp ::= exp binop exp 88321d3294cSantirez exp ::= unop exp 88421d3294cSantirez prefixexp ::= var | functioncall | `<b>(</b>´ exp `<b>)</b>´ 88521d3294cSantirez</pre> 88621d3294cSantirez 88721d3294cSantirez<p> 88821d3294cSantirezNumbers and literal strings are explained in <a href="#2.1">§2.1</a>; 88921d3294cSantirezvariables are explained in <a href="#2.3">§2.3</a>; 89021d3294cSantirezfunction definitions are explained in <a href="#2.5.9">§2.5.9</a>; 89121d3294cSantirezfunction calls are explained in <a href="#2.5.8">§2.5.8</a>; 89221d3294cSantireztable constructors are explained in <a href="#2.5.7">§2.5.7</a>. 89321d3294cSantirezVararg expressions, 89421d3294cSantirezdenoted by three dots ('<code>...</code>'), can only be used when 89521d3294cSantirezdirectly inside a vararg function; 89621d3294cSantirezthey are explained in <a href="#2.5.9">§2.5.9</a>. 89721d3294cSantirez 89821d3294cSantirez 89921d3294cSantirez<p> 90021d3294cSantirezBinary operators comprise arithmetic operators (see <a href="#2.5.1">§2.5.1</a>), 90121d3294cSantirezrelational operators (see <a href="#2.5.2">§2.5.2</a>), logical operators (see <a href="#2.5.3">§2.5.3</a>), 90221d3294cSantirezand the concatenation operator (see <a href="#2.5.4">§2.5.4</a>). 90321d3294cSantirezUnary operators comprise the unary minus (see <a href="#2.5.1">§2.5.1</a>), 90421d3294cSantirezthe unary <b>not</b> (see <a href="#2.5.3">§2.5.3</a>), 90521d3294cSantirezand the unary <em>length operator</em> (see <a href="#2.5.5">§2.5.5</a>). 90621d3294cSantirez 90721d3294cSantirez 90821d3294cSantirez<p> 90921d3294cSantirezBoth function calls and vararg expressions can result in multiple values. 91021d3294cSantirezIf an expression is used as a statement 91121d3294cSantirez(only possible for function calls (see <a href="#2.4.6">§2.4.6</a>)), 91221d3294cSantirezthen its return list is adjusted to zero elements, 91321d3294cSantirezthus discarding all returned values. 91421d3294cSantirezIf an expression is used as the last (or the only) element 91521d3294cSantirezof a list of expressions, 91621d3294cSantirezthen no adjustment is made 91721d3294cSantirez(unless the call is enclosed in parentheses). 91821d3294cSantirezIn all other contexts, 91921d3294cSantirezLua adjusts the result list to one element, 92021d3294cSantirezdiscarding all values except the first one. 92121d3294cSantirez 92221d3294cSantirez 92321d3294cSantirez<p> 92421d3294cSantirezHere are some examples: 92521d3294cSantirez 92621d3294cSantirez<pre> 92721d3294cSantirez f() -- adjusted to 0 results 92821d3294cSantirez g(f(), x) -- f() is adjusted to 1 result 92921d3294cSantirez g(x, f()) -- g gets x plus all results from f() 93021d3294cSantirez a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) 93121d3294cSantirez a,b = ... -- a gets the first vararg parameter, b gets 93221d3294cSantirez -- the second (both a and b can get nil if there 93321d3294cSantirez -- is no corresponding vararg parameter) 93421d3294cSantirez 93521d3294cSantirez a,b,c = x, f() -- f() is adjusted to 2 results 93621d3294cSantirez a,b,c = f() -- f() is adjusted to 3 results 93721d3294cSantirez return f() -- returns all results from f() 93821d3294cSantirez return ... -- returns all received vararg parameters 93921d3294cSantirez return x,y,f() -- returns x, y, and all results from f() 94021d3294cSantirez {f()} -- creates a list with all results from f() 94121d3294cSantirez {...} -- creates a list with all vararg parameters 94221d3294cSantirez {f(), nil} -- f() is adjusted to 1 result 94321d3294cSantirez</pre> 94421d3294cSantirez 94521d3294cSantirez<p> 94621d3294cSantirezAny expression enclosed in parentheses always results in only one value. 94721d3294cSantirezThus, 94821d3294cSantirez<code>(f(x,y,z))</code> is always a single value, 94921d3294cSantirezeven if <code>f</code> returns several values. 95021d3294cSantirez(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> 95121d3294cSantirezor <b>nil</b> if <code>f</code> does not return any values.) 95221d3294cSantirez 95321d3294cSantirez 95421d3294cSantirez 95521d3294cSantirez<h3>2.5.1 - <a name="2.5.1">Arithmetic Operators</a></h3><p> 95621d3294cSantirezLua supports the usual arithmetic operators: 95721d3294cSantirezthe binary <code>+</code> (addition), 95821d3294cSantirez<code>-</code> (subtraction), <code>*</code> (multiplication), 95921d3294cSantirez<code>/</code> (division), <code>%</code> (modulo), and <code>^</code> (exponentiation); 96021d3294cSantirezand unary <code>-</code> (negation). 96121d3294cSantirezIf the operands are numbers, or strings that can be converted to 96221d3294cSantireznumbers (see <a href="#2.2.1">§2.2.1</a>), 96321d3294cSantirezthen all operations have the usual meaning. 96421d3294cSantirezExponentiation works for any exponent. 96521d3294cSantirezFor instance, <code>x^(-0.5)</code> computes the inverse of the square root of <code>x</code>. 96621d3294cSantirezModulo is defined as 96721d3294cSantirez 96821d3294cSantirez<pre> 96921d3294cSantirez a % b == a - math.floor(a/b)*b 97021d3294cSantirez</pre><p> 97121d3294cSantirezThat is, it is the remainder of a division that rounds 97221d3294cSantirezthe quotient towards minus infinity. 97321d3294cSantirez 97421d3294cSantirez 97521d3294cSantirez 97621d3294cSantirez 97721d3294cSantirez 97821d3294cSantirez<h3>2.5.2 - <a name="2.5.2">Relational Operators</a></h3><p> 97921d3294cSantirezThe relational operators in Lua are 98021d3294cSantirez 98121d3294cSantirez<pre> 98221d3294cSantirez == ~= < > <= >= 98321d3294cSantirez</pre><p> 98421d3294cSantirezThese operators always result in <b>false</b> or <b>true</b>. 98521d3294cSantirez 98621d3294cSantirez 98721d3294cSantirez<p> 98821d3294cSantirezEquality (<code>==</code>) first compares the type of its operands. 98921d3294cSantirezIf the types are different, then the result is <b>false</b>. 99021d3294cSantirezOtherwise, the values of the operands are compared. 99121d3294cSantirezNumbers and strings are compared in the usual way. 99221d3294cSantirezObjects (tables, userdata, threads, and functions) 99321d3294cSantirezare compared by <em>reference</em>: 99421d3294cSantireztwo objects are considered equal only if they are the <em>same</em> object. 99521d3294cSantirezEvery time you create a new object 99621d3294cSantirez(a table, userdata, thread, or function), 99721d3294cSantirezthis new object is different from any previously existing object. 99821d3294cSantirez 99921d3294cSantirez 100021d3294cSantirez<p> 100121d3294cSantirezYou can change the way that Lua compares tables and userdata 100221d3294cSantirezby using the "eq" metamethod (see <a href="#2.8">§2.8</a>). 100321d3294cSantirez 100421d3294cSantirez 100521d3294cSantirez<p> 100621d3294cSantirezThe conversion rules of <a href="#2.2.1">§2.2.1</a> 100721d3294cSantirez<em>do not</em> apply to equality comparisons. 100821d3294cSantirezThus, <code>"0"==0</code> evaluates to <b>false</b>, 100921d3294cSantirezand <code>t[0]</code> and <code>t["0"]</code> denote different 101021d3294cSantirezentries in a table. 101121d3294cSantirez 101221d3294cSantirez 101321d3294cSantirez<p> 101421d3294cSantirezThe operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 101521d3294cSantirez 101621d3294cSantirez 101721d3294cSantirez<p> 101821d3294cSantirezThe order operators work as follows. 101921d3294cSantirezIf both arguments are numbers, then they are compared as such. 102021d3294cSantirezOtherwise, if both arguments are strings, 102121d3294cSantirezthen their values are compared according to the current locale. 102221d3294cSantirezOtherwise, Lua tries to call the "lt" or the "le" 102321d3294cSantirezmetamethod (see <a href="#2.8">§2.8</a>). 102421d3294cSantirezA comparison <code>a > b</code> is translated to <code>b < a</code> 102521d3294cSantirezand <code>a >= b</code> is translated to <code>b <= a</code>. 102621d3294cSantirez 102721d3294cSantirez 102821d3294cSantirez 102921d3294cSantirez 103021d3294cSantirez 103121d3294cSantirez<h3>2.5.3 - <a name="2.5.3">Logical Operators</a></h3><p> 103221d3294cSantirezThe logical operators in Lua are 103321d3294cSantirez<b>and</b>, <b>or</b>, and <b>not</b>. 103421d3294cSantirezLike the control structures (see <a href="#2.4.4">§2.4.4</a>), 103521d3294cSantirezall logical operators consider both <b>false</b> and <b>nil</b> as false 103621d3294cSantirezand anything else as true. 103721d3294cSantirez 103821d3294cSantirez 103921d3294cSantirez<p> 104021d3294cSantirezThe negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 104121d3294cSantirezThe conjunction operator <b>and</b> returns its first argument 104221d3294cSantirezif this value is <b>false</b> or <b>nil</b>; 104321d3294cSantirezotherwise, <b>and</b> returns its second argument. 104421d3294cSantirezThe disjunction operator <b>or</b> returns its first argument 104521d3294cSantirezif this value is different from <b>nil</b> and <b>false</b>; 104621d3294cSantirezotherwise, <b>or</b> returns its second argument. 104721d3294cSantirezBoth <b>and</b> and <b>or</b> use short-cut evaluation; 104821d3294cSantirezthat is, 104921d3294cSantirezthe second operand is evaluated only if necessary. 105021d3294cSantirezHere are some examples: 105121d3294cSantirez 105221d3294cSantirez<pre> 105321d3294cSantirez 10 or 20 --> 10 105421d3294cSantirez 10 or error() --> 10 105521d3294cSantirez nil or "a" --> "a" 105621d3294cSantirez nil and 10 --> nil 105721d3294cSantirez false and error() --> false 105821d3294cSantirez false and nil --> false 105921d3294cSantirez false or nil --> nil 106021d3294cSantirez 10 and 20 --> 20 106121d3294cSantirez</pre><p> 106221d3294cSantirez(In this manual, 106321d3294cSantirez<code>--></code> indicates the result of the preceding expression.) 106421d3294cSantirez 106521d3294cSantirez 106621d3294cSantirez 106721d3294cSantirez 106821d3294cSantirez 106921d3294cSantirez<h3>2.5.4 - <a name="2.5.4">Concatenation</a></h3><p> 107021d3294cSantirezThe string concatenation operator in Lua is 107121d3294cSantirezdenoted by two dots ('<code>..</code>'). 107221d3294cSantirezIf both operands are strings or numbers, then they are converted to 107321d3294cSantirezstrings according to the rules mentioned in <a href="#2.2.1">§2.2.1</a>. 107421d3294cSantirezOtherwise, the "concat" metamethod is called (see <a href="#2.8">§2.8</a>). 107521d3294cSantirez 107621d3294cSantirez 107721d3294cSantirez 107821d3294cSantirez 107921d3294cSantirez 108021d3294cSantirez<h3>2.5.5 - <a name="2.5.5">The Length Operator</a></h3> 108121d3294cSantirez 108221d3294cSantirez<p> 108321d3294cSantirezThe length operator is denoted by the unary operator <code>#</code>. 108421d3294cSantirezThe length of a string is its number of bytes 108521d3294cSantirez(that is, the usual meaning of string length when each 108621d3294cSantirezcharacter is one byte). 108721d3294cSantirez 108821d3294cSantirez 108921d3294cSantirez<p> 109021d3294cSantirezThe length of a table <code>t</code> is defined to be any 109121d3294cSantirezinteger index <code>n</code> 109221d3294cSantirezsuch that <code>t[n]</code> is not <b>nil</b> and <code>t[n+1]</code> is <b>nil</b>; 109321d3294cSantirezmoreover, if <code>t[1]</code> is <b>nil</b>, <code>n</code> can be zero. 109421d3294cSantirezFor a regular array, with non-nil values from 1 to a given <code>n</code>, 109521d3294cSantirezits length is exactly that <code>n</code>, 109621d3294cSantirezthe index of its last value. 109721d3294cSantirezIf the array has "holes" 109821d3294cSantirez(that is, <b>nil</b> values between other non-nil values), 109921d3294cSantirezthen <code>#t</code> can be any of the indices that 110021d3294cSantirezdirectly precedes a <b>nil</b> value 110121d3294cSantirez(that is, it may consider any such <b>nil</b> value as the end of 110221d3294cSantirezthe array). 110321d3294cSantirez 110421d3294cSantirez 110521d3294cSantirez 110621d3294cSantirez 110721d3294cSantirez 110821d3294cSantirez<h3>2.5.6 - <a name="2.5.6">Precedence</a></h3><p> 110921d3294cSantirezOperator precedence in Lua follows the table below, 111021d3294cSantirezfrom lower to higher priority: 111121d3294cSantirez 111221d3294cSantirez<pre> 111321d3294cSantirez or 111421d3294cSantirez and 111521d3294cSantirez < > <= >= ~= == 111621d3294cSantirez .. 111721d3294cSantirez + - 111821d3294cSantirez * / % 111921d3294cSantirez not # - (unary) 112021d3294cSantirez ^ 112121d3294cSantirez</pre><p> 112221d3294cSantirezAs usual, 112321d3294cSantirezyou can use parentheses to change the precedences of an expression. 112421d3294cSantirezThe concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 112521d3294cSantirezoperators are right associative. 112621d3294cSantirezAll other binary operators are left associative. 112721d3294cSantirez 112821d3294cSantirez 112921d3294cSantirez 113021d3294cSantirez 113121d3294cSantirez 113221d3294cSantirez<h3>2.5.7 - <a name="2.5.7">Table Constructors</a></h3><p> 113321d3294cSantirezTable constructors are expressions that create tables. 113421d3294cSantirezEvery time a constructor is evaluated, a new table is created. 113521d3294cSantirezA constructor can be used to create an empty table 113621d3294cSantirezor to create a table and initialize some of its fields. 113721d3294cSantirezThe general syntax for constructors is 113821d3294cSantirez 113921d3294cSantirez<pre> 114021d3294cSantirez tableconstructor ::= `<b>{</b>´ [fieldlist] `<b>}</b>´ 114121d3294cSantirez fieldlist ::= field {fieldsep field} [fieldsep] 114221d3294cSantirez field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp 114321d3294cSantirez fieldsep ::= `<b>,</b>´ | `<b>;</b>´ 114421d3294cSantirez</pre> 114521d3294cSantirez 114621d3294cSantirez<p> 114721d3294cSantirezEach field of the form <code>[exp1] = exp2</code> adds to the new table an entry 114821d3294cSantirezwith key <code>exp1</code> and value <code>exp2</code>. 114921d3294cSantirezA field of the form <code>name = exp</code> is equivalent to 115021d3294cSantirez<code>["name"] = exp</code>. 115121d3294cSantirezFinally, fields of the form <code>exp</code> are equivalent to 115221d3294cSantirez<code>[i] = exp</code>, where <code>i</code> are consecutive numerical integers, 115321d3294cSantirezstarting with 1. 115421d3294cSantirezFields in the other formats do not affect this counting. 115521d3294cSantirezFor example, 115621d3294cSantirez 115721d3294cSantirez<pre> 115821d3294cSantirez a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 115921d3294cSantirez</pre><p> 116021d3294cSantirezis equivalent to 116121d3294cSantirez 116221d3294cSantirez<pre> 116321d3294cSantirez do 116421d3294cSantirez local t = {} 116521d3294cSantirez t[f(1)] = g 116621d3294cSantirez t[1] = "x" -- 1st exp 116721d3294cSantirez t[2] = "y" -- 2nd exp 116821d3294cSantirez t.x = 1 -- t["x"] = 1 116921d3294cSantirez t[3] = f(x) -- 3rd exp 117021d3294cSantirez t[30] = 23 117121d3294cSantirez t[4] = 45 -- 4th exp 117221d3294cSantirez a = t 117321d3294cSantirez end 117421d3294cSantirez</pre> 117521d3294cSantirez 117621d3294cSantirez<p> 117721d3294cSantirezIf the last field in the list has the form <code>exp</code> 117821d3294cSantirezand the expression is a function call or a vararg expression, 117921d3294cSantirezthen all values returned by this expression enter the list consecutively 118021d3294cSantirez(see <a href="#2.5.8">§2.5.8</a>). 118121d3294cSantirezTo avoid this, 118221d3294cSantirezenclose the function call or the vararg expression 118321d3294cSantirezin parentheses (see <a href="#2.5">§2.5</a>). 118421d3294cSantirez 118521d3294cSantirez 118621d3294cSantirez<p> 118721d3294cSantirezThe field list can have an optional trailing separator, 118821d3294cSantirezas a convenience for machine-generated code. 118921d3294cSantirez 119021d3294cSantirez 119121d3294cSantirez 119221d3294cSantirez 119321d3294cSantirez 119421d3294cSantirez<h3>2.5.8 - <a name="2.5.8">Function Calls</a></h3><p> 119521d3294cSantirezA function call in Lua has the following syntax: 119621d3294cSantirez 119721d3294cSantirez<pre> 119821d3294cSantirez functioncall ::= prefixexp args 119921d3294cSantirez</pre><p> 120021d3294cSantirezIn a function call, 120121d3294cSantirezfirst prefixexp and args are evaluated. 120221d3294cSantirezIf the value of prefixexp has type <em>function</em>, 120321d3294cSantirezthen this function is called 120421d3294cSantirezwith the given arguments. 120521d3294cSantirezOtherwise, the prefixexp "call" metamethod is called, 120621d3294cSantirezhaving as first parameter the value of prefixexp, 120721d3294cSantirezfollowed by the original call arguments 120821d3294cSantirez(see <a href="#2.8">§2.8</a>). 120921d3294cSantirez 121021d3294cSantirez 121121d3294cSantirez<p> 121221d3294cSantirezThe form 121321d3294cSantirez 121421d3294cSantirez<pre> 121521d3294cSantirez functioncall ::= prefixexp `<b>:</b>´ Name args 121621d3294cSantirez</pre><p> 121721d3294cSantirezcan be used to call "methods". 121821d3294cSantirezA call <code>v:name(<em>args</em>)</code> 121921d3294cSantirezis syntactic sugar for <code>v.name(v,<em>args</em>)</code>, 122021d3294cSantirezexcept that <code>v</code> is evaluated only once. 122121d3294cSantirez 122221d3294cSantirez 122321d3294cSantirez<p> 122421d3294cSantirezArguments have the following syntax: 122521d3294cSantirez 122621d3294cSantirez<pre> 122721d3294cSantirez args ::= `<b>(</b>´ [explist] `<b>)</b>´ 122821d3294cSantirez args ::= tableconstructor 122921d3294cSantirez args ::= String 123021d3294cSantirez</pre><p> 123121d3294cSantirezAll argument expressions are evaluated before the call. 123221d3294cSantirezA call of the form <code>f{<em>fields</em>}</code> is 123321d3294cSantirezsyntactic sugar for <code>f({<em>fields</em>})</code>; 123421d3294cSantirezthat is, the argument list is a single new table. 123521d3294cSantirezA call of the form <code>f'<em>string</em>'</code> 123621d3294cSantirez(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 123721d3294cSantirezis syntactic sugar for <code>f('<em>string</em>')</code>; 123821d3294cSantirezthat is, the argument list is a single literal string. 123921d3294cSantirez 124021d3294cSantirez 124121d3294cSantirez<p> 124221d3294cSantirezAs an exception to the free-format syntax of Lua, 124321d3294cSantirezyou cannot put a line break before the '<code>(</code>' in a function call. 124421d3294cSantirezThis restriction avoids some ambiguities in the language. 124521d3294cSantirezIf you write 124621d3294cSantirez 124721d3294cSantirez<pre> 124821d3294cSantirez a = f 124921d3294cSantirez (g).x(a) 125021d3294cSantirez</pre><p> 125121d3294cSantirezLua would see that as a single statement, <code>a = f(g).x(a)</code>. 125221d3294cSantirezSo, if you want two statements, you must add a semi-colon between them. 125321d3294cSantirezIf you actually want to call <code>f</code>, 125421d3294cSantirezyou must remove the line break before <code>(g)</code>. 125521d3294cSantirez 125621d3294cSantirez 125721d3294cSantirez<p> 125821d3294cSantirezA call of the form <code>return</code> <em>functioncall</em> is called 125921d3294cSantireza <em>tail call</em>. 126021d3294cSantirezLua implements <em>proper tail calls</em> 126121d3294cSantirez(or <em>proper tail recursion</em>): 126221d3294cSantirezin a tail call, 126321d3294cSantirezthe called function reuses the stack entry of the calling function. 126421d3294cSantirezTherefore, there is no limit on the number of nested tail calls that 126521d3294cSantireza program can execute. 126621d3294cSantirezHowever, a tail call erases any debug information about the 126721d3294cSantirezcalling function. 126821d3294cSantirezNote that a tail call only happens with a particular syntax, 126921d3294cSantirezwhere the <b>return</b> has one single function call as argument; 127021d3294cSantirezthis syntax makes the calling function return exactly 127121d3294cSantirezthe returns of the called function. 127221d3294cSantirezSo, none of the following examples are tail calls: 127321d3294cSantirez 127421d3294cSantirez<pre> 127521d3294cSantirez return (f(x)) -- results adjusted to 1 127621d3294cSantirez return 2 * f(x) 127721d3294cSantirez return x, f(x) -- additional results 127821d3294cSantirez f(x); return -- results discarded 127921d3294cSantirez return x or f(x) -- results adjusted to 1 128021d3294cSantirez</pre> 128121d3294cSantirez 128221d3294cSantirez 128321d3294cSantirez 128421d3294cSantirez 128521d3294cSantirez<h3>2.5.9 - <a name="2.5.9">Function Definitions</a></h3> 128621d3294cSantirez 128721d3294cSantirez<p> 128821d3294cSantirezThe syntax for function definition is 128921d3294cSantirez 129021d3294cSantirez<pre> 129121d3294cSantirez function ::= <b>function</b> funcbody 129221d3294cSantirez funcbody ::= `<b>(</b>´ [parlist] `<b>)</b>´ block <b>end</b> 129321d3294cSantirez</pre> 129421d3294cSantirez 129521d3294cSantirez<p> 129621d3294cSantirezThe following syntactic sugar simplifies function definitions: 129721d3294cSantirez 129821d3294cSantirez<pre> 129921d3294cSantirez stat ::= <b>function</b> funcname funcbody 130021d3294cSantirez stat ::= <b>local</b> <b>function</b> Name funcbody 130121d3294cSantirez funcname ::= Name {`<b>.</b>´ Name} [`<b>:</b>´ Name] 130221d3294cSantirez</pre><p> 130321d3294cSantirezThe statement 130421d3294cSantirez 130521d3294cSantirez<pre> 130621d3294cSantirez function f () <em>body</em> end 130721d3294cSantirez</pre><p> 130821d3294cSantireztranslates to 130921d3294cSantirez 131021d3294cSantirez<pre> 131121d3294cSantirez f = function () <em>body</em> end 131221d3294cSantirez</pre><p> 131321d3294cSantirezThe statement 131421d3294cSantirez 131521d3294cSantirez<pre> 131621d3294cSantirez function t.a.b.c.f () <em>body</em> end 131721d3294cSantirez</pre><p> 131821d3294cSantireztranslates to 131921d3294cSantirez 132021d3294cSantirez<pre> 132121d3294cSantirez t.a.b.c.f = function () <em>body</em> end 132221d3294cSantirez</pre><p> 132321d3294cSantirezThe statement 132421d3294cSantirez 132521d3294cSantirez<pre> 132621d3294cSantirez local function f () <em>body</em> end 132721d3294cSantirez</pre><p> 132821d3294cSantireztranslates to 132921d3294cSantirez 133021d3294cSantirez<pre> 133121d3294cSantirez local f; f = function () <em>body</em> end 133221d3294cSantirez</pre><p> 133321d3294cSantirez<em>not</em> to 133421d3294cSantirez 133521d3294cSantirez<pre> 133621d3294cSantirez local f = function () <em>body</em> end 133721d3294cSantirez</pre><p> 133821d3294cSantirez(This only makes a difference when the body of the function 133921d3294cSantirezcontains references to <code>f</code>.) 134021d3294cSantirez 134121d3294cSantirez 134221d3294cSantirez<p> 134321d3294cSantirezA function definition is an executable expression, 134421d3294cSantirezwhose value has type <em>function</em>. 134521d3294cSantirezWhen Lua pre-compiles a chunk, 134621d3294cSantirezall its function bodies are pre-compiled too. 134721d3294cSantirezThen, whenever Lua executes the function definition, 134821d3294cSantirezthe function is <em>instantiated</em> (or <em>closed</em>). 134921d3294cSantirezThis function instance (or <em>closure</em>) 135021d3294cSantirezis the final value of the expression. 135121d3294cSantirezDifferent instances of the same function 135221d3294cSantirezcan refer to different external local variables 135321d3294cSantirezand can have different environment tables. 135421d3294cSantirez 135521d3294cSantirez 135621d3294cSantirez<p> 135721d3294cSantirezParameters act as local variables that are 135821d3294cSantirezinitialized with the argument values: 135921d3294cSantirez 136021d3294cSantirez<pre> 136121d3294cSantirez parlist ::= namelist [`<b>,</b>´ `<b>...</b>´] | `<b>...</b>´ 136221d3294cSantirez</pre><p> 136321d3294cSantirezWhen a function is called, 136421d3294cSantirezthe list of arguments is adjusted to 136521d3294cSantirezthe length of the list of parameters, 136621d3294cSantirezunless the function is a variadic or <em>vararg function</em>, 136721d3294cSantirezwhich is 136821d3294cSantirezindicated by three dots ('<code>...</code>') at the end of its parameter list. 136921d3294cSantirezA vararg function does not adjust its argument list; 137021d3294cSantirezinstead, it collects all extra arguments and supplies them 137121d3294cSantirezto the function through a <em>vararg expression</em>, 137221d3294cSantirezwhich is also written as three dots. 137321d3294cSantirezThe value of this expression is a list of all actual extra arguments, 137421d3294cSantirezsimilar to a function with multiple results. 137521d3294cSantirezIf a vararg expression is used inside another expression 137621d3294cSantirezor in the middle of a list of expressions, 137721d3294cSantirezthen its return list is adjusted to one element. 137821d3294cSantirezIf the expression is used as the last element of a list of expressions, 137921d3294cSantirezthen no adjustment is made 138021d3294cSantirez(unless that last expression is enclosed in parentheses). 138121d3294cSantirez 138221d3294cSantirez 138321d3294cSantirez<p> 138421d3294cSantirezAs an example, consider the following definitions: 138521d3294cSantirez 138621d3294cSantirez<pre> 138721d3294cSantirez function f(a, b) end 138821d3294cSantirez function g(a, b, ...) end 138921d3294cSantirez function r() return 1,2,3 end 139021d3294cSantirez</pre><p> 139121d3294cSantirezThen, we have the following mapping from arguments to parameters and 139221d3294cSantirezto the vararg expression: 139321d3294cSantirez 139421d3294cSantirez<pre> 139521d3294cSantirez CALL PARAMETERS 139621d3294cSantirez 139721d3294cSantirez f(3) a=3, b=nil 139821d3294cSantirez f(3, 4) a=3, b=4 139921d3294cSantirez f(3, 4, 5) a=3, b=4 140021d3294cSantirez f(r(), 10) a=1, b=10 140121d3294cSantirez f(r()) a=1, b=2 140221d3294cSantirez 140321d3294cSantirez g(3) a=3, b=nil, ... --> (nothing) 140421d3294cSantirez g(3, 4) a=3, b=4, ... --> (nothing) 140521d3294cSantirez g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 140621d3294cSantirez g(5, r()) a=5, b=1, ... --> 2 3 140721d3294cSantirez</pre> 140821d3294cSantirez 140921d3294cSantirez<p> 141021d3294cSantirezResults are returned using the <b>return</b> statement (see <a href="#2.4.4">§2.4.4</a>). 141121d3294cSantirezIf control reaches the end of a function 141221d3294cSantirezwithout encountering a <b>return</b> statement, 141321d3294cSantirezthen the function returns with no results. 141421d3294cSantirez 141521d3294cSantirez 141621d3294cSantirez<p> 141721d3294cSantirezThe <em>colon</em> syntax 141821d3294cSantirezis used for defining <em>methods</em>, 141921d3294cSantirezthat is, functions that have an implicit extra parameter <code>self</code>. 142021d3294cSantirezThus, the statement 142121d3294cSantirez 142221d3294cSantirez<pre> 142321d3294cSantirez function t.a.b.c:f (<em>params</em>) <em>body</em> end 142421d3294cSantirez</pre><p> 142521d3294cSantirezis syntactic sugar for 142621d3294cSantirez 142721d3294cSantirez<pre> 142821d3294cSantirez t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end 142921d3294cSantirez</pre> 143021d3294cSantirez 143121d3294cSantirez 143221d3294cSantirez 143321d3294cSantirez 143421d3294cSantirez 143521d3294cSantirez 143621d3294cSantirez<h2>2.6 - <a name="2.6">Visibility Rules</a></h2> 143721d3294cSantirez 143821d3294cSantirez<p> 143921d3294cSantirez 144021d3294cSantirezLua is a lexically scoped language. 144121d3294cSantirezThe scope of variables begins at the first statement <em>after</em> 144221d3294cSantireztheir declaration and lasts until the end of the innermost block that 144321d3294cSantirezincludes the declaration. 144421d3294cSantirezConsider the following example: 144521d3294cSantirez 144621d3294cSantirez<pre> 144721d3294cSantirez x = 10 -- global variable 144821d3294cSantirez do -- new block 144921d3294cSantirez local x = x -- new 'x', with value 10 145021d3294cSantirez print(x) --> 10 145121d3294cSantirez x = x+1 145221d3294cSantirez do -- another block 145321d3294cSantirez local x = x+1 -- another 'x' 145421d3294cSantirez print(x) --> 12 145521d3294cSantirez end 145621d3294cSantirez print(x) --> 11 145721d3294cSantirez end 145821d3294cSantirez print(x) --> 10 (the global one) 145921d3294cSantirez</pre> 146021d3294cSantirez 146121d3294cSantirez<p> 146221d3294cSantirezNotice that, in a declaration like <code>local x = x</code>, 146321d3294cSantirezthe new <code>x</code> being declared is not in scope yet, 146421d3294cSantirezand so the second <code>x</code> refers to the outside variable. 146521d3294cSantirez 146621d3294cSantirez 146721d3294cSantirez<p> 146821d3294cSantirezBecause of the lexical scoping rules, 146921d3294cSantirezlocal variables can be freely accessed by functions 147021d3294cSantirezdefined inside their scope. 147121d3294cSantirezA local variable used by an inner function is called 147221d3294cSantirezan <em>upvalue</em>, or <em>external local variable</em>, 147321d3294cSantirezinside the inner function. 147421d3294cSantirez 147521d3294cSantirez 147621d3294cSantirez<p> 147721d3294cSantirezNotice that each execution of a <b>local</b> statement 147821d3294cSantirezdefines new local variables. 147921d3294cSantirezConsider the following example: 148021d3294cSantirez 148121d3294cSantirez<pre> 148221d3294cSantirez a = {} 148321d3294cSantirez local x = 20 148421d3294cSantirez for i=1,10 do 148521d3294cSantirez local y = 0 148621d3294cSantirez a[i] = function () y=y+1; return x+y end 148721d3294cSantirez end 148821d3294cSantirez</pre><p> 148921d3294cSantirezThe loop creates ten closures 149021d3294cSantirez(that is, ten instances of the anonymous function). 149121d3294cSantirezEach of these closures uses a different <code>y</code> variable, 149221d3294cSantirezwhile all of them share the same <code>x</code>. 149321d3294cSantirez 149421d3294cSantirez 149521d3294cSantirez 149621d3294cSantirez 149721d3294cSantirez 149821d3294cSantirez<h2>2.7 - <a name="2.7">Error Handling</a></h2> 149921d3294cSantirez 150021d3294cSantirez<p> 150121d3294cSantirezBecause Lua is an embedded extension language, 150221d3294cSantirezall Lua actions start from C code in the host program 150321d3294cSantirezcalling a function from the Lua library (see <a href="#lua_pcall"><code>lua_pcall</code></a>). 150421d3294cSantirezWhenever an error occurs during Lua compilation or execution, 150521d3294cSantirezcontrol returns to C, 150621d3294cSantirezwhich can take appropriate measures 150721d3294cSantirez(such as printing an error message). 150821d3294cSantirez 150921d3294cSantirez 151021d3294cSantirez<p> 151121d3294cSantirezLua code can explicitly generate an error by calling the 151221d3294cSantirez<a href="#pdf-error"><code>error</code></a> function. 151321d3294cSantirezIf you need to catch errors in Lua, 151421d3294cSantirezyou can use the <a href="#pdf-pcall"><code>pcall</code></a> function. 151521d3294cSantirez 151621d3294cSantirez 151721d3294cSantirez 151821d3294cSantirez 151921d3294cSantirez 152021d3294cSantirez<h2>2.8 - <a name="2.8">Metatables</a></h2> 152121d3294cSantirez 152221d3294cSantirez<p> 152321d3294cSantirezEvery value in Lua can have a <em>metatable</em>. 152421d3294cSantirezThis <em>metatable</em> is an ordinary Lua table 152521d3294cSantirezthat defines the behavior of the original value 152621d3294cSantirezunder certain special operations. 152721d3294cSantirezYou can change several aspects of the behavior 152821d3294cSantirezof operations over a value by setting specific fields in its metatable. 152921d3294cSantirezFor instance, when a non-numeric value is the operand of an addition, 153021d3294cSantirezLua checks for a function in the field <code>"__add"</code> in its metatable. 153121d3294cSantirezIf it finds one, 153221d3294cSantirezLua calls this function to perform the addition. 153321d3294cSantirez 153421d3294cSantirez 153521d3294cSantirez<p> 153621d3294cSantirezWe call the keys in a metatable <em>events</em> 153721d3294cSantirezand the values <em>metamethods</em>. 153821d3294cSantirezIn the previous example, the event is <code>"add"</code> 153921d3294cSantirezand the metamethod is the function that performs the addition. 154021d3294cSantirez 154121d3294cSantirez 154221d3294cSantirez<p> 154321d3294cSantirezYou can query the metatable of any value 154421d3294cSantirezthrough the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function. 154521d3294cSantirez 154621d3294cSantirez 154721d3294cSantirez<p> 154821d3294cSantirezYou can replace the metatable of tables 154921d3294cSantirezthrough the <a href="#pdf-setmetatable"><code>setmetatable</code></a> 155021d3294cSantirezfunction. 155121d3294cSantirezYou cannot change the metatable of other types from Lua 155221d3294cSantirez(except by using the debug library); 155321d3294cSantirezyou must use the C API for that. 155421d3294cSantirez 155521d3294cSantirez 155621d3294cSantirez<p> 155721d3294cSantirezTables and full userdata have individual metatables 155821d3294cSantirez(although multiple tables and userdata can share their metatables). 155921d3294cSantirezValues of all other types share one single metatable per type; 156021d3294cSantirezthat is, there is one single metatable for all numbers, 156121d3294cSantirezone for all strings, etc. 156221d3294cSantirez 156321d3294cSantirez 156421d3294cSantirez<p> 156521d3294cSantirezA metatable controls how an object behaves in arithmetic operations, 156621d3294cSantirezorder comparisons, concatenation, length operation, and indexing. 156721d3294cSantirezA metatable also can define a function to be called when a userdata 156821d3294cSantirezis garbage collected. 156921d3294cSantirezFor each of these operations Lua associates a specific key 157021d3294cSantirezcalled an <em>event</em>. 157121d3294cSantirezWhen Lua performs one of these operations over a value, 157221d3294cSantirezit checks whether this value has a metatable with the corresponding event. 157321d3294cSantirezIf so, the value associated with that key (the metamethod) 157421d3294cSantirezcontrols how Lua will perform the operation. 157521d3294cSantirez 157621d3294cSantirez 157721d3294cSantirez<p> 157821d3294cSantirezMetatables control the operations listed next. 157921d3294cSantirezEach operation is identified by its corresponding name. 158021d3294cSantirezThe key for each operation is a string with its name prefixed by 158121d3294cSantireztwo underscores, '<code>__</code>'; 158221d3294cSantirezfor instance, the key for operation "add" is the 158321d3294cSantirezstring <code>"__add"</code>. 158421d3294cSantirezThe semantics of these operations is better explained by a Lua function 158521d3294cSantirezdescribing how the interpreter executes the operation. 158621d3294cSantirez 158721d3294cSantirez 158821d3294cSantirez<p> 158921d3294cSantirezThe code shown here in Lua is only illustrative; 159021d3294cSantirezthe real behavior is hard coded in the interpreter 159121d3294cSantirezand it is much more efficient than this simulation. 159221d3294cSantirezAll functions used in these descriptions 159321d3294cSantirez(<a href="#pdf-rawget"><code>rawget</code></a>, <a href="#pdf-tonumber"><code>tonumber</code></a>, etc.) 159421d3294cSantirezare described in <a href="#5.1">§5.1</a>. 159521d3294cSantirezIn particular, to retrieve the metamethod of a given object, 159621d3294cSantirezwe use the expression 159721d3294cSantirez 159821d3294cSantirez<pre> 159921d3294cSantirez metatable(obj)[event] 160021d3294cSantirez</pre><p> 160121d3294cSantirezThis should be read as 160221d3294cSantirez 160321d3294cSantirez<pre> 160421d3294cSantirez rawget(getmetatable(obj) or {}, event) 160521d3294cSantirez</pre><p> 160621d3294cSantirez 160721d3294cSantirezThat is, the access to a metamethod does not invoke other metamethods, 160821d3294cSantirezand the access to objects with no metatables does not fail 160921d3294cSantirez(it simply results in <b>nil</b>). 161021d3294cSantirez 161121d3294cSantirez 161221d3294cSantirez 161321d3294cSantirez<ul> 161421d3294cSantirez 161521d3294cSantirez<li><b>"add":</b> 161621d3294cSantirezthe <code>+</code> operation. 161721d3294cSantirez 161821d3294cSantirez 161921d3294cSantirez 162021d3294cSantirez<p> 162121d3294cSantirezThe function <code>getbinhandler</code> below defines how Lua chooses a handler 162221d3294cSantirezfor a binary operation. 162321d3294cSantirezFirst, Lua tries the first operand. 162421d3294cSantirezIf its type does not define a handler for the operation, 162521d3294cSantirezthen Lua tries the second operand. 162621d3294cSantirez 162721d3294cSantirez<pre> 162821d3294cSantirez function getbinhandler (op1, op2, event) 162921d3294cSantirez return metatable(op1)[event] or metatable(op2)[event] 163021d3294cSantirez end 163121d3294cSantirez</pre><p> 163221d3294cSantirezBy using this function, 163321d3294cSantirezthe behavior of the <code>op1 + op2</code> is 163421d3294cSantirez 163521d3294cSantirez<pre> 163621d3294cSantirez function add_event (op1, op2) 163721d3294cSantirez local o1, o2 = tonumber(op1), tonumber(op2) 163821d3294cSantirez if o1 and o2 then -- both operands are numeric? 163921d3294cSantirez return o1 + o2 -- '+' here is the primitive 'add' 164021d3294cSantirez else -- at least one of the operands is not numeric 164121d3294cSantirez local h = getbinhandler(op1, op2, "__add") 164221d3294cSantirez if h then 164321d3294cSantirez -- call the handler with both operands 164421d3294cSantirez return (h(op1, op2)) 164521d3294cSantirez else -- no handler available: default behavior 164621d3294cSantirez error(···) 164721d3294cSantirez end 164821d3294cSantirez end 164921d3294cSantirez end 165021d3294cSantirez</pre><p> 165121d3294cSantirez</li> 165221d3294cSantirez 165321d3294cSantirez<li><b>"sub":</b> 165421d3294cSantirezthe <code>-</code> operation. 165521d3294cSantirez 165621d3294cSantirezBehavior similar to the "add" operation. 165721d3294cSantirez</li> 165821d3294cSantirez 165921d3294cSantirez<li><b>"mul":</b> 166021d3294cSantirezthe <code>*</code> operation. 166121d3294cSantirez 166221d3294cSantirezBehavior similar to the "add" operation. 166321d3294cSantirez</li> 166421d3294cSantirez 166521d3294cSantirez<li><b>"div":</b> 166621d3294cSantirezthe <code>/</code> operation. 166721d3294cSantirez 166821d3294cSantirezBehavior similar to the "add" operation. 166921d3294cSantirez</li> 167021d3294cSantirez 167121d3294cSantirez<li><b>"mod":</b> 167221d3294cSantirezthe <code>%</code> operation. 167321d3294cSantirez 167421d3294cSantirezBehavior similar to the "add" operation, 167521d3294cSantirezwith the operation 167621d3294cSantirez<code>o1 - floor(o1/o2)*o2</code> as the primitive operation. 167721d3294cSantirez</li> 167821d3294cSantirez 167921d3294cSantirez<li><b>"pow":</b> 168021d3294cSantirezthe <code>^</code> (exponentiation) operation. 168121d3294cSantirez 168221d3294cSantirezBehavior similar to the "add" operation, 168321d3294cSantirezwith the function <code>pow</code> (from the C math library) 168421d3294cSantirezas the primitive operation. 168521d3294cSantirez</li> 168621d3294cSantirez 168721d3294cSantirez<li><b>"unm":</b> 168821d3294cSantirezthe unary <code>-</code> operation. 168921d3294cSantirez 169021d3294cSantirez 169121d3294cSantirez<pre> 169221d3294cSantirez function unm_event (op) 169321d3294cSantirez local o = tonumber(op) 169421d3294cSantirez if o then -- operand is numeric? 169521d3294cSantirez return -o -- '-' here is the primitive 'unm' 169621d3294cSantirez else -- the operand is not numeric. 169721d3294cSantirez -- Try to get a handler from the operand 169821d3294cSantirez local h = metatable(op).__unm 169921d3294cSantirez if h then 170021d3294cSantirez -- call the handler with the operand 170121d3294cSantirez return (h(op)) 170221d3294cSantirez else -- no handler available: default behavior 170321d3294cSantirez error(···) 170421d3294cSantirez end 170521d3294cSantirez end 170621d3294cSantirez end 170721d3294cSantirez</pre><p> 170821d3294cSantirez</li> 170921d3294cSantirez 171021d3294cSantirez<li><b>"concat":</b> 171121d3294cSantirezthe <code>..</code> (concatenation) operation. 171221d3294cSantirez 171321d3294cSantirez 171421d3294cSantirez<pre> 171521d3294cSantirez function concat_event (op1, op2) 171621d3294cSantirez if (type(op1) == "string" or type(op1) == "number") and 171721d3294cSantirez (type(op2) == "string" or type(op2) == "number") then 171821d3294cSantirez return op1 .. op2 -- primitive string concatenation 171921d3294cSantirez else 172021d3294cSantirez local h = getbinhandler(op1, op2, "__concat") 172121d3294cSantirez if h then 172221d3294cSantirez return (h(op1, op2)) 172321d3294cSantirez else 172421d3294cSantirez error(···) 172521d3294cSantirez end 172621d3294cSantirez end 172721d3294cSantirez end 172821d3294cSantirez</pre><p> 172921d3294cSantirez</li> 173021d3294cSantirez 173121d3294cSantirez<li><b>"len":</b> 173221d3294cSantirezthe <code>#</code> operation. 173321d3294cSantirez 173421d3294cSantirez 173521d3294cSantirez<pre> 173621d3294cSantirez function len_event (op) 173721d3294cSantirez if type(op) == "string" then 173821d3294cSantirez return strlen(op) -- primitive string length 173921d3294cSantirez elseif type(op) == "table" then 174021d3294cSantirez return #op -- primitive table length 174121d3294cSantirez else 174221d3294cSantirez local h = metatable(op).__len 174321d3294cSantirez if h then 174421d3294cSantirez -- call the handler with the operand 174521d3294cSantirez return (h(op)) 174621d3294cSantirez else -- no handler available: default behavior 174721d3294cSantirez error(···) 174821d3294cSantirez end 174921d3294cSantirez end 175021d3294cSantirez end 175121d3294cSantirez</pre><p> 175221d3294cSantirezSee <a href="#2.5.5">§2.5.5</a> for a description of the length of a table. 175321d3294cSantirez</li> 175421d3294cSantirez 175521d3294cSantirez<li><b>"eq":</b> 175621d3294cSantirezthe <code>==</code> operation. 175721d3294cSantirez 175821d3294cSantirezThe function <code>getcomphandler</code> defines how Lua chooses a metamethod 175921d3294cSantirezfor comparison operators. 176021d3294cSantirezA metamethod only is selected when both objects 176121d3294cSantirezbeing compared have the same type 176221d3294cSantirezand the same metamethod for the selected operation. 176321d3294cSantirez 176421d3294cSantirez<pre> 176521d3294cSantirez function getcomphandler (op1, op2, event) 176621d3294cSantirez if type(op1) ~= type(op2) then return nil end 176721d3294cSantirez local mm1 = metatable(op1)[event] 176821d3294cSantirez local mm2 = metatable(op2)[event] 176921d3294cSantirez if mm1 == mm2 then return mm1 else return nil end 177021d3294cSantirez end 177121d3294cSantirez</pre><p> 177221d3294cSantirezThe "eq" event is defined as follows: 177321d3294cSantirez 177421d3294cSantirez<pre> 177521d3294cSantirez function eq_event (op1, op2) 177621d3294cSantirez if type(op1) ~= type(op2) then -- different types? 177721d3294cSantirez return false -- different objects 177821d3294cSantirez end 177921d3294cSantirez if op1 == op2 then -- primitive equal? 178021d3294cSantirez return true -- objects are equal 178121d3294cSantirez end 178221d3294cSantirez -- try metamethod 178321d3294cSantirez local h = getcomphandler(op1, op2, "__eq") 178421d3294cSantirez if h then 178521d3294cSantirez return (h(op1, op2)) 178621d3294cSantirez else 178721d3294cSantirez return false 178821d3294cSantirez end 178921d3294cSantirez end 179021d3294cSantirez</pre><p> 179121d3294cSantirez<code>a ~= b</code> is equivalent to <code>not (a == b)</code>. 179221d3294cSantirez</li> 179321d3294cSantirez 179421d3294cSantirez<li><b>"lt":</b> 179521d3294cSantirezthe <code><</code> operation. 179621d3294cSantirez 179721d3294cSantirez 179821d3294cSantirez<pre> 179921d3294cSantirez function lt_event (op1, op2) 180021d3294cSantirez if type(op1) == "number" and type(op2) == "number" then 180121d3294cSantirez return op1 < op2 -- numeric comparison 180221d3294cSantirez elseif type(op1) == "string" and type(op2) == "string" then 180321d3294cSantirez return op1 < op2 -- lexicographic comparison 180421d3294cSantirez else 180521d3294cSantirez local h = getcomphandler(op1, op2, "__lt") 180621d3294cSantirez if h then 180721d3294cSantirez return (h(op1, op2)) 180821d3294cSantirez else 180921d3294cSantirez error(···) 181021d3294cSantirez end 181121d3294cSantirez end 181221d3294cSantirez end 181321d3294cSantirez</pre><p> 181421d3294cSantirez<code>a > b</code> is equivalent to <code>b < a</code>. 181521d3294cSantirez</li> 181621d3294cSantirez 181721d3294cSantirez<li><b>"le":</b> 181821d3294cSantirezthe <code><=</code> operation. 181921d3294cSantirez 182021d3294cSantirez 182121d3294cSantirez<pre> 182221d3294cSantirez function le_event (op1, op2) 182321d3294cSantirez if type(op1) == "number" and type(op2) == "number" then 182421d3294cSantirez return op1 <= op2 -- numeric comparison 182521d3294cSantirez elseif type(op1) == "string" and type(op2) == "string" then 182621d3294cSantirez return op1 <= op2 -- lexicographic comparison 182721d3294cSantirez else 182821d3294cSantirez local h = getcomphandler(op1, op2, "__le") 182921d3294cSantirez if h then 183021d3294cSantirez return (h(op1, op2)) 183121d3294cSantirez else 183221d3294cSantirez h = getcomphandler(op1, op2, "__lt") 183321d3294cSantirez if h then 183421d3294cSantirez return not h(op2, op1) 183521d3294cSantirez else 183621d3294cSantirez error(···) 183721d3294cSantirez end 183821d3294cSantirez end 183921d3294cSantirez end 184021d3294cSantirez end 184121d3294cSantirez</pre><p> 184221d3294cSantirez<code>a >= b</code> is equivalent to <code>b <= a</code>. 184321d3294cSantirezNote that, in the absence of a "le" metamethod, 184421d3294cSantirezLua tries the "lt", assuming that <code>a <= b</code> is 184521d3294cSantirezequivalent to <code>not (b < a)</code>. 184621d3294cSantirez</li> 184721d3294cSantirez 184821d3294cSantirez<li><b>"index":</b> 184921d3294cSantirezThe indexing access <code>table[key]</code>. 185021d3294cSantirez 185121d3294cSantirez 185221d3294cSantirez<pre> 185321d3294cSantirez function gettable_event (table, key) 185421d3294cSantirez local h 185521d3294cSantirez if type(table) == "table" then 185621d3294cSantirez local v = rawget(table, key) 185721d3294cSantirez if v ~= nil then return v end 185821d3294cSantirez h = metatable(table).__index 185921d3294cSantirez if h == nil then return nil end 186021d3294cSantirez else 186121d3294cSantirez h = metatable(table).__index 186221d3294cSantirez if h == nil then 186321d3294cSantirez error(···) 186421d3294cSantirez end 186521d3294cSantirez end 186621d3294cSantirez if type(h) == "function" then 186721d3294cSantirez return (h(table, key)) -- call the handler 186821d3294cSantirez else return h[key] -- or repeat operation on it 186921d3294cSantirez end 187021d3294cSantirez end 187121d3294cSantirez</pre><p> 187221d3294cSantirez</li> 187321d3294cSantirez 187421d3294cSantirez<li><b>"newindex":</b> 187521d3294cSantirezThe indexing assignment <code>table[key] = value</code>. 187621d3294cSantirez 187721d3294cSantirez 187821d3294cSantirez<pre> 187921d3294cSantirez function settable_event (table, key, value) 188021d3294cSantirez local h 188121d3294cSantirez if type(table) == "table" then 188221d3294cSantirez local v = rawget(table, key) 188321d3294cSantirez if v ~= nil then rawset(table, key, value); return end 188421d3294cSantirez h = metatable(table).__newindex 188521d3294cSantirez if h == nil then rawset(table, key, value); return end 188621d3294cSantirez else 188721d3294cSantirez h = metatable(table).__newindex 188821d3294cSantirez if h == nil then 188921d3294cSantirez error(···) 189021d3294cSantirez end 189121d3294cSantirez end 189221d3294cSantirez if type(h) == "function" then 189321d3294cSantirez h(table, key,value) -- call the handler 189421d3294cSantirez else h[key] = value -- or repeat operation on it 189521d3294cSantirez end 189621d3294cSantirez end 189721d3294cSantirez</pre><p> 189821d3294cSantirez</li> 189921d3294cSantirez 190021d3294cSantirez<li><b>"call":</b> 190121d3294cSantirezcalled when Lua calls a value. 190221d3294cSantirez 190321d3294cSantirez 190421d3294cSantirez<pre> 190521d3294cSantirez function function_event (func, ...) 190621d3294cSantirez if type(func) == "function" then 190721d3294cSantirez return func(...) -- primitive call 190821d3294cSantirez else 190921d3294cSantirez local h = metatable(func).__call 191021d3294cSantirez if h then 191121d3294cSantirez return h(func, ...) 191221d3294cSantirez else 191321d3294cSantirez error(···) 191421d3294cSantirez end 191521d3294cSantirez end 191621d3294cSantirez end 191721d3294cSantirez</pre><p> 191821d3294cSantirez</li> 191921d3294cSantirez 192021d3294cSantirez</ul> 192121d3294cSantirez 192221d3294cSantirez 192321d3294cSantirez 192421d3294cSantirez 192521d3294cSantirez<h2>2.9 - <a name="2.9">Environments</a></h2> 192621d3294cSantirez 192721d3294cSantirez<p> 192821d3294cSantirezBesides metatables, 192921d3294cSantirezobjects of types thread, function, and userdata 193021d3294cSantirezhave another table associated with them, 193121d3294cSantirezcalled their <em>environment</em>. 193221d3294cSantirezLike metatables, environments are regular tables and 193321d3294cSantirezmultiple objects can share the same environment. 193421d3294cSantirez 193521d3294cSantirez 193621d3294cSantirez<p> 193721d3294cSantirezThreads are created sharing the environment of the creating thread. 193821d3294cSantirezUserdata and C functions are created sharing the environment 193921d3294cSantirezof the creating C function. 194021d3294cSantirezNon-nested Lua functions 194121d3294cSantirez(created by <a href="#pdf-loadfile"><code>loadfile</code></a>, <a href="#pdf-loadstring"><code>loadstring</code></a> or <a href="#pdf-load"><code>load</code></a>) 194221d3294cSantirezare created sharing the environment of the creating thread. 194321d3294cSantirezNested Lua functions are created sharing the environment of 194421d3294cSantirezthe creating Lua function. 194521d3294cSantirez 194621d3294cSantirez 194721d3294cSantirez<p> 194821d3294cSantirezEnvironments associated with userdata have no meaning for Lua. 194921d3294cSantirezIt is only a convenience feature for programmers to associate a table to 195021d3294cSantireza userdata. 195121d3294cSantirez 195221d3294cSantirez 195321d3294cSantirez<p> 195421d3294cSantirezEnvironments associated with threads are called 195521d3294cSantirez<em>global environments</em>. 195621d3294cSantirezThey are used as the default environment for threads and 195721d3294cSantireznon-nested Lua functions created by the thread 195821d3294cSantirezand can be directly accessed by C code (see <a href="#3.3">§3.3</a>). 195921d3294cSantirez 196021d3294cSantirez 196121d3294cSantirez<p> 196221d3294cSantirezThe environment associated with a C function can be directly 196321d3294cSantirezaccessed by C code (see <a href="#3.3">§3.3</a>). 196421d3294cSantirezIt is used as the default environment for other C functions 196521d3294cSantirezand userdata created by the function. 196621d3294cSantirez 196721d3294cSantirez 196821d3294cSantirez<p> 196921d3294cSantirezEnvironments associated with Lua functions are used to resolve 197021d3294cSantirezall accesses to global variables within the function (see <a href="#2.3">§2.3</a>). 197121d3294cSantirezThey are used as the default environment for nested Lua functions 197221d3294cSantirezcreated by the function. 197321d3294cSantirez 197421d3294cSantirez 197521d3294cSantirez<p> 197621d3294cSantirezYou can change the environment of a Lua function or the 197721d3294cSantirezrunning thread by calling <a href="#pdf-setfenv"><code>setfenv</code></a>. 197821d3294cSantirezYou can get the environment of a Lua function or the running thread 197921d3294cSantirezby calling <a href="#pdf-getfenv"><code>getfenv</code></a>. 198021d3294cSantirezTo manipulate the environment of other objects 198121d3294cSantirez(userdata, C functions, other threads) you must 198221d3294cSantirezuse the C API. 198321d3294cSantirez 198421d3294cSantirez 198521d3294cSantirez 198621d3294cSantirez 198721d3294cSantirez 198821d3294cSantirez<h2>2.10 - <a name="2.10">Garbage Collection</a></h2> 198921d3294cSantirez 199021d3294cSantirez<p> 199121d3294cSantirezLua performs automatic memory management. 199221d3294cSantirezThis means that 199321d3294cSantirezyou have to worry neither about allocating memory for new objects 199421d3294cSantireznor about freeing it when the objects are no longer needed. 199521d3294cSantirezLua manages memory automatically by running 199621d3294cSantireza <em>garbage collector</em> from time to time 199721d3294cSantirezto collect all <em>dead objects</em> 199821d3294cSantirez(that is, objects that are no longer accessible from Lua). 199921d3294cSantirezAll memory used by Lua is subject to automatic management: 200021d3294cSantireztables, userdata, functions, threads, strings, etc. 200121d3294cSantirez 200221d3294cSantirez 200321d3294cSantirez<p> 200421d3294cSantirezLua implements an incremental mark-and-sweep collector. 200521d3294cSantirezIt uses two numbers to control its garbage-collection cycles: 200621d3294cSantirezthe <em>garbage-collector pause</em> and 200721d3294cSantirezthe <em>garbage-collector step multiplier</em>. 200821d3294cSantirezBoth use percentage points as units 200921d3294cSantirez(so that a value of 100 means an internal value of 1). 201021d3294cSantirez 201121d3294cSantirez 201221d3294cSantirez<p> 201321d3294cSantirezThe garbage-collector pause 201421d3294cSantirezcontrols how long the collector waits before starting a new cycle. 201521d3294cSantirezLarger values make the collector less aggressive. 201621d3294cSantirezValues smaller than 100 mean the collector will not wait to 201721d3294cSantirezstart a new cycle. 201821d3294cSantirezA value of 200 means that the collector waits for the total memory in use 201921d3294cSantirezto double before starting a new cycle. 202021d3294cSantirez 202121d3294cSantirez 202221d3294cSantirez<p> 202321d3294cSantirezThe step multiplier 202421d3294cSantirezcontrols the relative speed of the collector relative to 202521d3294cSantirezmemory allocation. 202621d3294cSantirezLarger values make the collector more aggressive but also increase 202721d3294cSantirezthe size of each incremental step. 202821d3294cSantirezValues smaller than 100 make the collector too slow and 202921d3294cSantirezcan result in the collector never finishing a cycle. 203021d3294cSantirezThe default, 200, means that the collector runs at "twice" 203121d3294cSantirezthe speed of memory allocation. 203221d3294cSantirez 203321d3294cSantirez 203421d3294cSantirez<p> 203521d3294cSantirezYou can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C 203621d3294cSantirezor <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. 203721d3294cSantirezWith these functions you can also control 203821d3294cSantirezthe collector directly (e.g., stop and restart it). 203921d3294cSantirez 204021d3294cSantirez 204121d3294cSantirez 204221d3294cSantirez<h3>2.10.1 - <a name="2.10.1">Garbage-Collection Metamethods</a></h3> 204321d3294cSantirez 204421d3294cSantirez<p> 204521d3294cSantirezUsing the C API, 204621d3294cSantirezyou can set garbage-collector metamethods for userdata (see <a href="#2.8">§2.8</a>). 204721d3294cSantirezThese metamethods are also called <em>finalizers</em>. 204821d3294cSantirezFinalizers allow you to coordinate Lua's garbage collection 204921d3294cSantirezwith external resource management 205021d3294cSantirez(such as closing files, network or database connections, 205121d3294cSantirezor freeing your own memory). 205221d3294cSantirez 205321d3294cSantirez 205421d3294cSantirez<p> 205521d3294cSantirezGarbage userdata with a field <code>__gc</code> in their metatables are not 205621d3294cSantirezcollected immediately by the garbage collector. 205721d3294cSantirezInstead, Lua puts them in a list. 205821d3294cSantirezAfter the collection, 205921d3294cSantirezLua does the equivalent of the following function 206021d3294cSantirezfor each userdata in that list: 206121d3294cSantirez 206221d3294cSantirez<pre> 206321d3294cSantirez function gc_event (udata) 206421d3294cSantirez local h = metatable(udata).__gc 206521d3294cSantirez if h then 206621d3294cSantirez h(udata) 206721d3294cSantirez end 206821d3294cSantirez end 206921d3294cSantirez</pre> 207021d3294cSantirez 207121d3294cSantirez<p> 207221d3294cSantirezAt the end of each garbage-collection cycle, 207321d3294cSantirezthe finalizers for userdata are called in <em>reverse</em> 207421d3294cSantirezorder of their creation, 207521d3294cSantirezamong those collected in that cycle. 207621d3294cSantirezThat is, the first finalizer to be called is the one associated 207721d3294cSantirezwith the userdata created last in the program. 207821d3294cSantirezThe userdata itself is freed only in the next garbage-collection cycle. 207921d3294cSantirez 208021d3294cSantirez 208121d3294cSantirez 208221d3294cSantirez 208321d3294cSantirez 208421d3294cSantirez<h3>2.10.2 - <a name="2.10.2">Weak Tables</a></h3> 208521d3294cSantirez 208621d3294cSantirez<p> 208721d3294cSantirezA <em>weak table</em> is a table whose elements are 208821d3294cSantirez<em>weak references</em>. 208921d3294cSantirezA weak reference is ignored by the garbage collector. 209021d3294cSantirezIn other words, 209121d3294cSantirezif the only references to an object are weak references, 209221d3294cSantirezthen the garbage collector will collect this object. 209321d3294cSantirez 209421d3294cSantirez 209521d3294cSantirez<p> 209621d3294cSantirezA weak table can have weak keys, weak values, or both. 209721d3294cSantirezA table with weak keys allows the collection of its keys, 209821d3294cSantirezbut prevents the collection of its values. 209921d3294cSantirezA table with both weak keys and weak values allows the collection of 210021d3294cSantirezboth keys and values. 210121d3294cSantirezIn any case, if either the key or the value is collected, 210221d3294cSantirezthe whole pair is removed from the table. 210321d3294cSantirezThe weakness of a table is controlled by the 210421d3294cSantirez<code>__mode</code> field of its metatable. 210521d3294cSantirezIf the <code>__mode</code> field is a string containing the character '<code>k</code>', 210621d3294cSantirezthe keys in the table are weak. 210721d3294cSantirezIf <code>__mode</code> contains '<code>v</code>', 210821d3294cSantirezthe values in the table are weak. 210921d3294cSantirez 211021d3294cSantirez 211121d3294cSantirez<p> 211221d3294cSantirezAfter you use a table as a metatable, 211321d3294cSantirezyou should not change the value of its <code>__mode</code> field. 211421d3294cSantirezOtherwise, the weak behavior of the tables controlled by this 211521d3294cSantirezmetatable is undefined. 211621d3294cSantirez 211721d3294cSantirez 211821d3294cSantirez 211921d3294cSantirez 212021d3294cSantirez 212121d3294cSantirez 212221d3294cSantirez 212321d3294cSantirez<h2>2.11 - <a name="2.11">Coroutines</a></h2> 212421d3294cSantirez 212521d3294cSantirez<p> 212621d3294cSantirezLua supports coroutines, 212721d3294cSantirezalso called <em>collaborative multithreading</em>. 212821d3294cSantirezA coroutine in Lua represents an independent thread of execution. 212921d3294cSantirezUnlike threads in multithread systems, however, 213021d3294cSantireza coroutine only suspends its execution by explicitly calling 213121d3294cSantireza yield function. 213221d3294cSantirez 213321d3294cSantirez 213421d3294cSantirez<p> 213521d3294cSantirezYou create a coroutine with a call to <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>. 213621d3294cSantirezIts sole argument is a function 213721d3294cSantirezthat is the main function of the coroutine. 213821d3294cSantirezThe <code>create</code> function only creates a new coroutine and 213921d3294cSantirezreturns a handle to it (an object of type <em>thread</em>); 214021d3294cSantirezit does not start the coroutine execution. 214121d3294cSantirez 214221d3294cSantirez 214321d3294cSantirez<p> 214421d3294cSantirezWhen you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 214521d3294cSantirezpassing as its first argument 214621d3294cSantireza thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 214721d3294cSantirezthe coroutine starts its execution, 214821d3294cSantirezat the first line of its main function. 214921d3294cSantirezExtra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed on 215021d3294cSantirezto the coroutine main function. 215121d3294cSantirezAfter the coroutine starts running, 215221d3294cSantirezit runs until it terminates or <em>yields</em>. 215321d3294cSantirez 215421d3294cSantirez 215521d3294cSantirez<p> 215621d3294cSantirezA coroutine can terminate its execution in two ways: 215721d3294cSantireznormally, when its main function returns 215821d3294cSantirez(explicitly or implicitly, after the last instruction); 215921d3294cSantirezand abnormally, if there is an unprotected error. 216021d3294cSantirezIn the first case, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>, 216121d3294cSantirezplus any values returned by the coroutine main function. 216221d3294cSantirezIn case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b> 216321d3294cSantirezplus an error message. 216421d3294cSantirez 216521d3294cSantirez 216621d3294cSantirez<p> 216721d3294cSantirezA coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 216821d3294cSantirezWhen a coroutine yields, 216921d3294cSantirezthe corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately, 217021d3294cSantirezeven if the yield happens inside nested function calls 217121d3294cSantirez(that is, not in the main function, 217221d3294cSantirezbut in a function directly or indirectly called by the main function). 217321d3294cSantirezIn the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>, 217421d3294cSantirezplus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 217521d3294cSantirezThe next time you resume the same coroutine, 217621d3294cSantirezit continues its execution from the point where it yielded, 217721d3294cSantirezwith the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra 217821d3294cSantirezarguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 217921d3294cSantirez 218021d3294cSantirez 218121d3294cSantirez<p> 218221d3294cSantirezLike <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 218321d3294cSantirezthe <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine, 218421d3294cSantirezbut instead of returning the coroutine itself, 218521d3294cSantirezit returns a function that, when called, resumes the coroutine. 218621d3294cSantirezAny arguments passed to this function 218721d3294cSantirezgo as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 218821d3294cSantirez<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>, 218921d3294cSantirezexcept the first one (the boolean error code). 219021d3294cSantirezUnlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 219121d3294cSantirez<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors; 219221d3294cSantirezany error is propagated to the caller. 219321d3294cSantirez 219421d3294cSantirez 219521d3294cSantirez<p> 219621d3294cSantirezAs an example, 219721d3294cSantirezconsider the following code: 219821d3294cSantirez 219921d3294cSantirez<pre> 220021d3294cSantirez function foo (a) 220121d3294cSantirez print("foo", a) 220221d3294cSantirez return coroutine.yield(2*a) 220321d3294cSantirez end 220421d3294cSantirez 220521d3294cSantirez co = coroutine.create(function (a,b) 220621d3294cSantirez print("co-body", a, b) 220721d3294cSantirez local r = foo(a+1) 220821d3294cSantirez print("co-body", r) 220921d3294cSantirez local r, s = coroutine.yield(a+b, a-b) 221021d3294cSantirez print("co-body", r, s) 221121d3294cSantirez return b, "end" 221221d3294cSantirez end) 221321d3294cSantirez 221421d3294cSantirez print("main", coroutine.resume(co, 1, 10)) 221521d3294cSantirez print("main", coroutine.resume(co, "r")) 221621d3294cSantirez print("main", coroutine.resume(co, "x", "y")) 221721d3294cSantirez print("main", coroutine.resume(co, "x", "y")) 221821d3294cSantirez</pre><p> 221921d3294cSantirezWhen you run it, it produces the following output: 222021d3294cSantirez 222121d3294cSantirez<pre> 222221d3294cSantirez co-body 1 10 222321d3294cSantirez foo 2 222421d3294cSantirez 222521d3294cSantirez main true 4 222621d3294cSantirez co-body r 222721d3294cSantirez main true 11 -9 222821d3294cSantirez co-body x y 222921d3294cSantirez main true 10 end 223021d3294cSantirez main false cannot resume dead coroutine 223121d3294cSantirez</pre> 223221d3294cSantirez 223321d3294cSantirez 223421d3294cSantirez 223521d3294cSantirez 223621d3294cSantirez<h1>3 - <a name="3">The Application Program Interface</a></h1> 223721d3294cSantirez 223821d3294cSantirez<p> 223921d3294cSantirez 224021d3294cSantirezThis section describes the C API for Lua, that is, 224121d3294cSantirezthe set of C functions available to the host program to communicate 224221d3294cSantirezwith Lua. 224321d3294cSantirezAll API functions and related types and constants 224421d3294cSantirezare declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. 224521d3294cSantirez 224621d3294cSantirez 224721d3294cSantirez<p> 224821d3294cSantirezEven when we use the term "function", 224921d3294cSantirezany facility in the API may be provided as a macro instead. 225021d3294cSantirezAll such macros use each of their arguments exactly once 225121d3294cSantirez(except for the first argument, which is always a Lua state), 225221d3294cSantirezand so do not generate any hidden side-effects. 225321d3294cSantirez 225421d3294cSantirez 225521d3294cSantirez<p> 225621d3294cSantirezAs in most C libraries, 225721d3294cSantirezthe Lua API functions do not check their arguments for validity or consistency. 225821d3294cSantirezHowever, you can change this behavior by compiling Lua 225921d3294cSantirezwith a proper definition for the macro <a name="pdf-luai_apicheck"><code>luai_apicheck</code></a>, 226021d3294cSantirezin file <code>luaconf.h</code>. 226121d3294cSantirez 226221d3294cSantirez 226321d3294cSantirez 226421d3294cSantirez<h2>3.1 - <a name="3.1">The Stack</a></h2> 226521d3294cSantirez 226621d3294cSantirez<p> 226721d3294cSantirezLua uses a <em>virtual stack</em> to pass values to and from C. 226821d3294cSantirezEach element in this stack represents a Lua value 226921d3294cSantirez(<b>nil</b>, number, string, etc.). 227021d3294cSantirez 227121d3294cSantirez 227221d3294cSantirez<p> 227321d3294cSantirezWhenever Lua calls C, the called function gets a new stack, 227421d3294cSantirezwhich is independent of previous stacks and of stacks of 227521d3294cSantirezC functions that are still active. 227621d3294cSantirezThis stack initially contains any arguments to the C function 227721d3294cSantirezand it is where the C function pushes its results 227821d3294cSantirezto be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 227921d3294cSantirez 228021d3294cSantirez 228121d3294cSantirez<p> 228221d3294cSantirezFor convenience, 228321d3294cSantirezmost query operations in the API do not follow a strict stack discipline. 228421d3294cSantirezInstead, they can refer to any element in the stack 228521d3294cSantirezby using an <em>index</em>: 228621d3294cSantirezA positive index represents an <em>absolute</em> stack position 228721d3294cSantirez(starting at 1); 228821d3294cSantireza negative index represents an <em>offset</em> relative to the top of the stack. 228921d3294cSantirezMore specifically, if the stack has <em>n</em> elements, 229021d3294cSantirezthen index 1 represents the first element 229121d3294cSantirez(that is, the element that was pushed onto the stack first) 229221d3294cSantirezand 229321d3294cSantirezindex <em>n</em> represents the last element; 229421d3294cSantirezindex -1 also represents the last element 229521d3294cSantirez(that is, the element at the top) 229621d3294cSantirezand index <em>-n</em> represents the first element. 229721d3294cSantirezWe say that an index is <em>valid</em> 229821d3294cSantirezif it lies between 1 and the stack top 229921d3294cSantirez(that is, if <code>1 ≤ abs(index) ≤ top</code>). 230021d3294cSantirez 230121d3294cSantirez 230221d3294cSantirez 230321d3294cSantirez 230421d3294cSantirez 230521d3294cSantirez 230621d3294cSantirez<h2>3.2 - <a name="3.2">Stack Size</a></h2> 230721d3294cSantirez 230821d3294cSantirez<p> 230921d3294cSantirezWhen you interact with Lua API, 231021d3294cSantirezyou are responsible for ensuring consistency. 231121d3294cSantirezIn particular, 231221d3294cSantirez<em>you are responsible for controlling stack overflow</em>. 231321d3294cSantirezYou can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> 231421d3294cSantirezto grow the stack size. 231521d3294cSantirez 231621d3294cSantirez 231721d3294cSantirez<p> 231821d3294cSantirezWhenever Lua calls C, 231921d3294cSantirezit ensures that at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> stack positions are available. 232021d3294cSantirez<code>LUA_MINSTACK</code> is defined as 20, 232121d3294cSantirezso that usually you do not have to worry about stack space 232221d3294cSantirezunless your code has loops pushing elements onto the stack. 232321d3294cSantirez 232421d3294cSantirez 232521d3294cSantirez<p> 232621d3294cSantirezMost query functions accept as indices any value inside the 232721d3294cSantirezavailable stack space, that is, indices up to the maximum stack size 232821d3294cSantirezyou have set through <a href="#lua_checkstack"><code>lua_checkstack</code></a>. 232921d3294cSantirezSuch indices are called <em>acceptable indices</em>. 233021d3294cSantirezMore formally, we define an <em>acceptable index</em> 233121d3294cSantirezas follows: 233221d3294cSantirez 233321d3294cSantirez<pre> 233421d3294cSantirez (index < 0 && abs(index) <= top) || 233521d3294cSantirez (index > 0 && index <= stackspace) 233621d3294cSantirez</pre><p> 233721d3294cSantirezNote that 0 is never an acceptable index. 233821d3294cSantirez 233921d3294cSantirez 234021d3294cSantirez 234121d3294cSantirez 234221d3294cSantirez 234321d3294cSantirez<h2>3.3 - <a name="3.3">Pseudo-Indices</a></h2> 234421d3294cSantirez 234521d3294cSantirez<p> 234621d3294cSantirezUnless otherwise noted, 234721d3294cSantirezany function that accepts valid indices can also be called with 234821d3294cSantirez<em>pseudo-indices</em>, 234921d3294cSantirezwhich represent some Lua values that are accessible to C code 235021d3294cSantirezbut which are not in the stack. 235121d3294cSantirezPseudo-indices are used to access the thread environment, 235221d3294cSantirezthe function environment, 235321d3294cSantirezthe registry, 235421d3294cSantirezand the upvalues of a C function (see <a href="#3.4">§3.4</a>). 235521d3294cSantirez 235621d3294cSantirez 235721d3294cSantirez<p> 235821d3294cSantirezThe thread environment (where global variables live) is 235921d3294cSantirezalways at pseudo-index <a name="pdf-LUA_GLOBALSINDEX"><code>LUA_GLOBALSINDEX</code></a>. 236021d3294cSantirezThe environment of the running C function is always 236121d3294cSantirezat pseudo-index <a name="pdf-LUA_ENVIRONINDEX"><code>LUA_ENVIRONINDEX</code></a>. 236221d3294cSantirez 236321d3294cSantirez 236421d3294cSantirez<p> 236521d3294cSantirezTo access and change the value of global variables, 236621d3294cSantirezyou can use regular table operations over an environment table. 236721d3294cSantirezFor instance, to access the value of a global variable, do 236821d3294cSantirez 236921d3294cSantirez<pre> 237021d3294cSantirez lua_getfield(L, LUA_GLOBALSINDEX, varname); 237121d3294cSantirez</pre> 237221d3294cSantirez 237321d3294cSantirez 237421d3294cSantirez 237521d3294cSantirez 237621d3294cSantirez<h2>3.4 - <a name="3.4">C Closures</a></h2> 237721d3294cSantirez 237821d3294cSantirez<p> 237921d3294cSantirezWhen a C function is created, 238021d3294cSantirezit is possible to associate some values with it, 238121d3294cSantirezthus creating a <em>C closure</em>; 238221d3294cSantirezthese values are called <em>upvalues</em> and are 238321d3294cSantirezaccessible to the function whenever it is called 238421d3294cSantirez(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>). 238521d3294cSantirez 238621d3294cSantirez 238721d3294cSantirez<p> 238821d3294cSantirezWhenever a C function is called, 238921d3294cSantirezits upvalues are located at specific pseudo-indices. 239021d3294cSantirezThese pseudo-indices are produced by the macro 239121d3294cSantirez<a name="lua_upvalueindex"><code>lua_upvalueindex</code></a>. 239221d3294cSantirezThe first value associated with a function is at position 239321d3294cSantirez<code>lua_upvalueindex(1)</code>, and so on. 239421d3294cSantirezAny access to <code>lua_upvalueindex(<em>n</em>)</code>, 239521d3294cSantirezwhere <em>n</em> is greater than the number of upvalues of the 239621d3294cSantirezcurrent function (but not greater than 256), 239721d3294cSantirezproduces an acceptable (but invalid) index. 239821d3294cSantirez 239921d3294cSantirez 240021d3294cSantirez 240121d3294cSantirez 240221d3294cSantirez 240321d3294cSantirez<h2>3.5 - <a name="3.5">Registry</a></h2> 240421d3294cSantirez 240521d3294cSantirez<p> 240621d3294cSantirezLua provides a <em>registry</em>, 240721d3294cSantireza pre-defined table that can be used by any C code to 240821d3294cSantirezstore whatever Lua value it needs to store. 240921d3294cSantirezThis table is always located at pseudo-index 241021d3294cSantirez<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. 241121d3294cSantirezAny C library can store data into this table, 241221d3294cSantirezbut it should take care to choose keys different from those used 241321d3294cSantirezby other libraries, to avoid collisions. 241421d3294cSantirezTypically, you should use as key a string containing your library name 241521d3294cSantirezor a light userdata with the address of a C object in your code. 241621d3294cSantirez 241721d3294cSantirez 241821d3294cSantirez<p> 241921d3294cSantirezThe integer keys in the registry are used by the reference mechanism, 242021d3294cSantirezimplemented by the auxiliary library, 242121d3294cSantirezand therefore should not be used for other purposes. 242221d3294cSantirez 242321d3294cSantirez 242421d3294cSantirez 242521d3294cSantirez 242621d3294cSantirez 242721d3294cSantirez<h2>3.6 - <a name="3.6">Error Handling in C</a></h2> 242821d3294cSantirez 242921d3294cSantirez<p> 243021d3294cSantirezInternally, Lua uses the C <code>longjmp</code> facility to handle errors. 243121d3294cSantirez(You can also choose to use exceptions if you use C++; 243221d3294cSantirezsee file <code>luaconf.h</code>.) 243321d3294cSantirezWhen Lua faces any error 243421d3294cSantirez(such as memory allocation errors, type errors, syntax errors, 243521d3294cSantirezand runtime errors) 243621d3294cSantirezit <em>raises</em> an error; 243721d3294cSantirezthat is, it does a long jump. 243821d3294cSantirezA <em>protected environment</em> uses <code>setjmp</code> 243921d3294cSantirezto set a recover point; 244021d3294cSantirezany error jumps to the most recent active recover point. 244121d3294cSantirez 244221d3294cSantirez 244321d3294cSantirez<p> 244421d3294cSantirezMost functions in the API can throw an error, 244521d3294cSantirezfor instance due to a memory allocation error. 244621d3294cSantirezThe documentation for each function indicates whether 244721d3294cSantirezit can throw errors. 244821d3294cSantirez 244921d3294cSantirez 245021d3294cSantirez<p> 245121d3294cSantirezInside a C function you can throw an error by calling <a href="#lua_error"><code>lua_error</code></a>. 245221d3294cSantirez 245321d3294cSantirez 245421d3294cSantirez 245521d3294cSantirez 245621d3294cSantirez 245721d3294cSantirez<h2>3.7 - <a name="3.7">Functions and Types</a></h2> 245821d3294cSantirez 245921d3294cSantirez<p> 246021d3294cSantirezHere we list all functions and types from the C API in 246121d3294cSantirezalphabetical order. 246221d3294cSantirezEach function has an indicator like this: 246321d3294cSantirez<span class="apii">[-o, +p, <em>x</em>]</span> 246421d3294cSantirez 246521d3294cSantirez 246621d3294cSantirez<p> 246721d3294cSantirezThe first field, <code>o</code>, 246821d3294cSantirezis how many elements the function pops from the stack. 246921d3294cSantirezThe second field, <code>p</code>, 247021d3294cSantirezis how many elements the function pushes onto the stack. 247121d3294cSantirez(Any function always pushes its results after popping its arguments.) 247221d3294cSantirezA field in the form <code>x|y</code> means the function can push (or pop) 247321d3294cSantirez<code>x</code> or <code>y</code> elements, 247421d3294cSantirezdepending on the situation; 247521d3294cSantirezan interrogation mark '<code>?</code>' means that 247621d3294cSantirezwe cannot know how many elements the function pops/pushes 247721d3294cSantirezby looking only at its arguments 247821d3294cSantirez(e.g., they may depend on what is on the stack). 247921d3294cSantirezThe third field, <code>x</code>, 248021d3294cSantireztells whether the function may throw errors: 248121d3294cSantirez'<code>-</code>' means the function never throws any error; 248221d3294cSantirez'<code>m</code>' means the function may throw an error 248321d3294cSantirezonly due to not enough memory; 248421d3294cSantirez'<code>e</code>' means the function may throw other kinds of errors; 248521d3294cSantirez'<code>v</code>' means the function may throw an error on purpose. 248621d3294cSantirez 248721d3294cSantirez 248821d3294cSantirez 248921d3294cSantirez<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> 249021d3294cSantirez<pre>typedef void * (*lua_Alloc) (void *ud, 249121d3294cSantirez void *ptr, 249221d3294cSantirez size_t osize, 249321d3294cSantirez size_t nsize);</pre> 249421d3294cSantirez 249521d3294cSantirez<p> 249621d3294cSantirezThe type of the memory-allocation function used by Lua states. 249721d3294cSantirezThe allocator function must provide a 249821d3294cSantirezfunctionality similar to <code>realloc</code>, 249921d3294cSantirezbut not exactly the same. 250021d3294cSantirezIts arguments are 250121d3294cSantirez<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; 250221d3294cSantirez<code>ptr</code>, a pointer to the block being allocated/reallocated/freed; 250321d3294cSantirez<code>osize</code>, the original size of the block; 250421d3294cSantirez<code>nsize</code>, the new size of the block. 250521d3294cSantirez<code>ptr</code> is <code>NULL</code> if and only if <code>osize</code> is zero. 250621d3294cSantirezWhen <code>nsize</code> is zero, the allocator must return <code>NULL</code>; 250721d3294cSantirezif <code>osize</code> is not zero, 250821d3294cSantirezit should free the block pointed to by <code>ptr</code>. 250921d3294cSantirezWhen <code>nsize</code> is not zero, the allocator returns <code>NULL</code> 251021d3294cSantirezif and only if it cannot fill the request. 251121d3294cSantirezWhen <code>nsize</code> is not zero and <code>osize</code> is zero, 251221d3294cSantirezthe allocator should behave like <code>malloc</code>. 251321d3294cSantirezWhen <code>nsize</code> and <code>osize</code> are not zero, 251421d3294cSantirezthe allocator behaves like <code>realloc</code>. 251521d3294cSantirezLua assumes that the allocator never fails when 251621d3294cSantirez<code>osize >= nsize</code>. 251721d3294cSantirez 251821d3294cSantirez 251921d3294cSantirez<p> 252021d3294cSantirezHere is a simple implementation for the allocator function. 252121d3294cSantirezIt is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. 252221d3294cSantirez 252321d3294cSantirez<pre> 252421d3294cSantirez static void *l_alloc (void *ud, void *ptr, size_t osize, 252521d3294cSantirez size_t nsize) { 252621d3294cSantirez (void)ud; (void)osize; /* not used */ 252721d3294cSantirez if (nsize == 0) { 252821d3294cSantirez free(ptr); 252921d3294cSantirez return NULL; 253021d3294cSantirez } 253121d3294cSantirez else 253221d3294cSantirez return realloc(ptr, nsize); 253321d3294cSantirez } 253421d3294cSantirez</pre><p> 253521d3294cSantirezThis code assumes 253621d3294cSantirezthat <code>free(NULL)</code> has no effect and that 253721d3294cSantirez<code>realloc(NULL, size)</code> is equivalent to <code>malloc(size)</code>. 253821d3294cSantirezANSI C ensures both behaviors. 253921d3294cSantirez 254021d3294cSantirez 254121d3294cSantirez 254221d3294cSantirez 254321d3294cSantirez 254421d3294cSantirez<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> 254521d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 254621d3294cSantirez<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> 254721d3294cSantirez 254821d3294cSantirez<p> 254921d3294cSantirezSets a new panic function and returns the old one. 255021d3294cSantirez 255121d3294cSantirez 255221d3294cSantirez<p> 255321d3294cSantirezIf an error happens outside any protected environment, 255421d3294cSantirezLua calls a <em>panic function</em> 255521d3294cSantirezand then calls <code>exit(EXIT_FAILURE)</code>, 255621d3294cSantirezthus exiting the host application. 255721d3294cSantirezYour panic function can avoid this exit by 255821d3294cSantireznever returning (e.g., doing a long jump). 255921d3294cSantirez 256021d3294cSantirez 256121d3294cSantirez<p> 256221d3294cSantirezThe panic function can access the error message at the top of the stack. 256321d3294cSantirez 256421d3294cSantirez 256521d3294cSantirez 256621d3294cSantirez 256721d3294cSantirez 256821d3294cSantirez<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> 256921d3294cSantirez<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> 257021d3294cSantirez<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> 257121d3294cSantirez 257221d3294cSantirez<p> 257321d3294cSantirezCalls a function. 257421d3294cSantirez 257521d3294cSantirez 257621d3294cSantirez<p> 257721d3294cSantirezTo call a function you must use the following protocol: 257821d3294cSantirezfirst, the function to be called is pushed onto the stack; 257921d3294cSantirezthen, the arguments to the function are pushed 258021d3294cSantirezin direct order; 258121d3294cSantirezthat is, the first argument is pushed first. 258221d3294cSantirezFinally you call <a href="#lua_call"><code>lua_call</code></a>; 258321d3294cSantirez<code>nargs</code> is the number of arguments that you pushed onto the stack. 258421d3294cSantirezAll arguments and the function value are popped from the stack 258521d3294cSantirezwhen the function is called. 258621d3294cSantirezThe function results are pushed onto the stack when the function returns. 258721d3294cSantirezThe number of results is adjusted to <code>nresults</code>, 258821d3294cSantirezunless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. 258921d3294cSantirezIn this case, <em>all</em> results from the function are pushed. 259021d3294cSantirezLua takes care that the returned values fit into the stack space. 259121d3294cSantirezThe function results are pushed onto the stack in direct order 259221d3294cSantirez(the first result is pushed first), 259321d3294cSantirezso that after the call the last result is on the top of the stack. 259421d3294cSantirez 259521d3294cSantirez 259621d3294cSantirez<p> 259721d3294cSantirezAny error inside the called function is propagated upwards 259821d3294cSantirez(with a <code>longjmp</code>). 259921d3294cSantirez 260021d3294cSantirez 260121d3294cSantirez<p> 260221d3294cSantirezThe following example shows how the host program can do the 260321d3294cSantirezequivalent to this Lua code: 260421d3294cSantirez 260521d3294cSantirez<pre> 260621d3294cSantirez a = f("how", t.x, 14) 260721d3294cSantirez</pre><p> 260821d3294cSantirezHere it is in C: 260921d3294cSantirez 261021d3294cSantirez<pre> 261121d3294cSantirez lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* function to be called */ 261221d3294cSantirez lua_pushstring(L, "how"); /* 1st argument */ 261321d3294cSantirez lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* table to be indexed */ 261421d3294cSantirez lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 261521d3294cSantirez lua_remove(L, -2); /* remove 't' from the stack */ 261621d3294cSantirez lua_pushinteger(L, 14); /* 3rd argument */ 261721d3294cSantirez lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ 261821d3294cSantirez lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* set global 'a' */ 261921d3294cSantirez</pre><p> 262021d3294cSantirezNote that the code above is "balanced": 262121d3294cSantirezat its end, the stack is back to its original configuration. 262221d3294cSantirezThis is considered good programming practice. 262321d3294cSantirez 262421d3294cSantirez 262521d3294cSantirez 262621d3294cSantirez 262721d3294cSantirez 262821d3294cSantirez<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> 262921d3294cSantirez<pre>typedef int (*lua_CFunction) (lua_State *L);</pre> 263021d3294cSantirez 263121d3294cSantirez<p> 263221d3294cSantirezType for C functions. 263321d3294cSantirez 263421d3294cSantirez 263521d3294cSantirez<p> 263621d3294cSantirezIn order to communicate properly with Lua, 263721d3294cSantireza C function must use the following protocol, 263821d3294cSantirezwhich defines the way parameters and results are passed: 263921d3294cSantireza C function receives its arguments from Lua in its stack 264021d3294cSantirezin direct order (the first argument is pushed first). 264121d3294cSantirezSo, when the function starts, 264221d3294cSantirez<code>lua_gettop(L)</code> returns the number of arguments received by the function. 264321d3294cSantirezThe first argument (if any) is at index 1 264421d3294cSantirezand its last argument is at index <code>lua_gettop(L)</code>. 264521d3294cSantirezTo return values to Lua, a C function just pushes them onto the stack, 264621d3294cSantirezin direct order (the first result is pushed first), 264721d3294cSantirezand returns the number of results. 264821d3294cSantirezAny other value in the stack below the results will be properly 264921d3294cSantirezdiscarded by Lua. 265021d3294cSantirezLike a Lua function, a C function called by Lua can also return 265121d3294cSantirezmany results. 265221d3294cSantirez 265321d3294cSantirez 265421d3294cSantirez<p> 265521d3294cSantirezAs an example, the following function receives a variable number 265621d3294cSantirezof numerical arguments and returns their average and sum: 265721d3294cSantirez 265821d3294cSantirez<pre> 265921d3294cSantirez static int foo (lua_State *L) { 266021d3294cSantirez int n = lua_gettop(L); /* number of arguments */ 266121d3294cSantirez lua_Number sum = 0; 266221d3294cSantirez int i; 266321d3294cSantirez for (i = 1; i <= n; i++) { 266421d3294cSantirez if (!lua_isnumber(L, i)) { 266521d3294cSantirez lua_pushstring(L, "incorrect argument"); 266621d3294cSantirez lua_error(L); 266721d3294cSantirez } 266821d3294cSantirez sum += lua_tonumber(L, i); 266921d3294cSantirez } 267021d3294cSantirez lua_pushnumber(L, sum/n); /* first result */ 267121d3294cSantirez lua_pushnumber(L, sum); /* second result */ 267221d3294cSantirez return 2; /* number of results */ 267321d3294cSantirez } 267421d3294cSantirez</pre> 267521d3294cSantirez 267621d3294cSantirez 267721d3294cSantirez 267821d3294cSantirez 267921d3294cSantirez<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> 268021d3294cSantirez<span class="apii">[-0, +0, <em>m</em>]</span> 268121d3294cSantirez<pre>int lua_checkstack (lua_State *L, int extra);</pre> 268221d3294cSantirez 268321d3294cSantirez<p> 268421d3294cSantirezEnsures that there are at least <code>extra</code> free stack slots in the stack. 268521d3294cSantirezIt returns false if it cannot grow the stack to that size. 268621d3294cSantirezThis function never shrinks the stack; 268721d3294cSantirezif the stack is already larger than the new size, 268821d3294cSantirezit is left unchanged. 268921d3294cSantirez 269021d3294cSantirez 269121d3294cSantirez 269221d3294cSantirez 269321d3294cSantirez 269421d3294cSantirez<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> 269521d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 269621d3294cSantirez<pre>void lua_close (lua_State *L);</pre> 269721d3294cSantirez 269821d3294cSantirez<p> 269921d3294cSantirezDestroys all objects in the given Lua state 270021d3294cSantirez(calling the corresponding garbage-collection metamethods, if any) 270121d3294cSantirezand frees all dynamic memory used by this state. 270221d3294cSantirezOn several platforms, you may not need to call this function, 270321d3294cSantirezbecause all resources are naturally released when the host program ends. 270421d3294cSantirezOn the other hand, long-running programs, 270521d3294cSantirezsuch as a daemon or a web server, 270621d3294cSantirezmight need to release states as soon as they are not needed, 270721d3294cSantirezto avoid growing too large. 270821d3294cSantirez 270921d3294cSantirez 271021d3294cSantirez 271121d3294cSantirez 271221d3294cSantirez 271321d3294cSantirez<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> 271421d3294cSantirez<span class="apii">[-n, +1, <em>e</em>]</span> 271521d3294cSantirez<pre>void lua_concat (lua_State *L, int n);</pre> 271621d3294cSantirez 271721d3294cSantirez<p> 271821d3294cSantirezConcatenates the <code>n</code> values at the top of the stack, 271921d3294cSantirezpops them, and leaves the result at the top. 272021d3294cSantirezIf <code>n</code> is 1, the result is the single value on the stack 272121d3294cSantirez(that is, the function does nothing); 272221d3294cSantirezif <code>n</code> is 0, the result is the empty string. 272321d3294cSantirezConcatenation is performed following the usual semantics of Lua 272421d3294cSantirez(see <a href="#2.5.4">§2.5.4</a>). 272521d3294cSantirez 272621d3294cSantirez 272721d3294cSantirez 272821d3294cSantirez 272921d3294cSantirez 273021d3294cSantirez<hr><h3><a name="lua_cpcall"><code>lua_cpcall</code></a></h3><p> 273121d3294cSantirez<span class="apii">[-0, +(0|1), <em>-</em>]</span> 273221d3294cSantirez<pre>int lua_cpcall (lua_State *L, lua_CFunction func, void *ud);</pre> 273321d3294cSantirez 273421d3294cSantirez<p> 273521d3294cSantirezCalls the C function <code>func</code> in protected mode. 273621d3294cSantirez<code>func</code> starts with only one element in its stack, 273721d3294cSantireza light userdata containing <code>ud</code>. 273821d3294cSantirezIn case of errors, 273921d3294cSantirez<a href="#lua_cpcall"><code>lua_cpcall</code></a> returns the same error codes as <a href="#lua_pcall"><code>lua_pcall</code></a>, 274021d3294cSantirezplus the error object on the top of the stack; 274121d3294cSantirezotherwise, it returns zero, and does not change the stack. 274221d3294cSantirezAll values returned by <code>func</code> are discarded. 274321d3294cSantirez 274421d3294cSantirez 274521d3294cSantirez 274621d3294cSantirez 274721d3294cSantirez 274821d3294cSantirez<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> 274921d3294cSantirez<span class="apii">[-0, +1, <em>m</em>]</span> 275021d3294cSantirez<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> 275121d3294cSantirez 275221d3294cSantirez<p> 275321d3294cSantirezCreates a new empty table and pushes it onto the stack. 275421d3294cSantirezThe new table has space pre-allocated 275521d3294cSantirezfor <code>narr</code> array elements and <code>nrec</code> non-array elements. 275621d3294cSantirezThis pre-allocation is useful when you know exactly how many elements 275721d3294cSantirezthe table will have. 275821d3294cSantirezOtherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. 275921d3294cSantirez 276021d3294cSantirez 276121d3294cSantirez 276221d3294cSantirez 276321d3294cSantirez 276421d3294cSantirez<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> 276521d3294cSantirez<span class="apii">[-0, +0, <em>m</em>]</span> 276621d3294cSantirez<pre>int lua_dump (lua_State *L, lua_Writer writer, void *data);</pre> 276721d3294cSantirez 276821d3294cSantirez<p> 276921d3294cSantirezDumps a function as a binary chunk. 277021d3294cSantirezReceives a Lua function on the top of the stack 277121d3294cSantirezand produces a binary chunk that, 277221d3294cSantirezif loaded again, 277321d3294cSantirezresults in a function equivalent to the one dumped. 277421d3294cSantirezAs it produces parts of the chunk, 277521d3294cSantirez<a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>) 277621d3294cSantirezwith the given <code>data</code> 277721d3294cSantirezto write them. 277821d3294cSantirez 277921d3294cSantirez 278021d3294cSantirez<p> 278121d3294cSantirezThe value returned is the error code returned by the last 278221d3294cSantirezcall to the writer; 278321d3294cSantirez0 means no errors. 278421d3294cSantirez 278521d3294cSantirez 278621d3294cSantirez<p> 278721d3294cSantirezThis function does not pop the Lua function from the stack. 278821d3294cSantirez 278921d3294cSantirez 279021d3294cSantirez 279121d3294cSantirez 279221d3294cSantirez 279321d3294cSantirez<hr><h3><a name="lua_equal"><code>lua_equal</code></a></h3><p> 279421d3294cSantirez<span class="apii">[-0, +0, <em>e</em>]</span> 279521d3294cSantirez<pre>int lua_equal (lua_State *L, int index1, int index2);</pre> 279621d3294cSantirez 279721d3294cSantirez<p> 279821d3294cSantirezReturns 1 if the two values in acceptable indices <code>index1</code> and 279921d3294cSantirez<code>index2</code> are equal, 280021d3294cSantirezfollowing the semantics of the Lua <code>==</code> operator 280121d3294cSantirez(that is, may call metamethods). 280221d3294cSantirezOtherwise returns 0. 280321d3294cSantirezAlso returns 0 if any of the indices is non valid. 280421d3294cSantirez 280521d3294cSantirez 280621d3294cSantirez 280721d3294cSantirez 280821d3294cSantirez 280921d3294cSantirez<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> 281021d3294cSantirez<span class="apii">[-1, +0, <em>v</em>]</span> 281121d3294cSantirez<pre>int lua_error (lua_State *L);</pre> 281221d3294cSantirez 281321d3294cSantirez<p> 281421d3294cSantirezGenerates a Lua error. 281521d3294cSantirezThe error message (which can actually be a Lua value of any type) 281621d3294cSantirezmust be on the stack top. 281721d3294cSantirezThis function does a long jump, 281821d3294cSantirezand therefore never returns. 281921d3294cSantirez(see <a href="#luaL_error"><code>luaL_error</code></a>). 282021d3294cSantirez 282121d3294cSantirez 282221d3294cSantirez 282321d3294cSantirez 282421d3294cSantirez 282521d3294cSantirez<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> 282621d3294cSantirez<span class="apii">[-0, +0, <em>e</em>]</span> 282721d3294cSantirez<pre>int lua_gc (lua_State *L, int what, int data);</pre> 282821d3294cSantirez 282921d3294cSantirez<p> 283021d3294cSantirezControls the garbage collector. 283121d3294cSantirez 283221d3294cSantirez 283321d3294cSantirez<p> 283421d3294cSantirezThis function performs several tasks, 283521d3294cSantirezaccording to the value of the parameter <code>what</code>: 283621d3294cSantirez 283721d3294cSantirez<ul> 283821d3294cSantirez 283921d3294cSantirez<li><b><code>LUA_GCSTOP</code>:</b> 284021d3294cSantirezstops the garbage collector. 284121d3294cSantirez</li> 284221d3294cSantirez 284321d3294cSantirez<li><b><code>LUA_GCRESTART</code>:</b> 284421d3294cSantirezrestarts the garbage collector. 284521d3294cSantirez</li> 284621d3294cSantirez 284721d3294cSantirez<li><b><code>LUA_GCCOLLECT</code>:</b> 284821d3294cSantirezperforms a full garbage-collection cycle. 284921d3294cSantirez</li> 285021d3294cSantirez 285121d3294cSantirez<li><b><code>LUA_GCCOUNT</code>:</b> 285221d3294cSantirezreturns the current amount of memory (in Kbytes) in use by Lua. 285321d3294cSantirez</li> 285421d3294cSantirez 285521d3294cSantirez<li><b><code>LUA_GCCOUNTB</code>:</b> 285621d3294cSantirezreturns the remainder of dividing the current amount of bytes of 285721d3294cSantirezmemory in use by Lua by 1024. 285821d3294cSantirez</li> 285921d3294cSantirez 286021d3294cSantirez<li><b><code>LUA_GCSTEP</code>:</b> 286121d3294cSantirezperforms an incremental step of garbage collection. 286221d3294cSantirezThe step "size" is controlled by <code>data</code> 286321d3294cSantirez(larger values mean more steps) in a non-specified way. 286421d3294cSantirezIf you want to control the step size 286521d3294cSantirezyou must experimentally tune the value of <code>data</code>. 286621d3294cSantirezThe function returns 1 if the step finished a 286721d3294cSantirezgarbage-collection cycle. 286821d3294cSantirez</li> 286921d3294cSantirez 287021d3294cSantirez<li><b><code>LUA_GCSETPAUSE</code>:</b> 287121d3294cSantirezsets <code>data</code> as the new value 287221d3294cSantirezfor the <em>pause</em> of the collector (see <a href="#2.10">§2.10</a>). 287321d3294cSantirezThe function returns the previous value of the pause. 287421d3294cSantirez</li> 287521d3294cSantirez 287621d3294cSantirez<li><b><code>LUA_GCSETSTEPMUL</code>:</b> 287721d3294cSantirezsets <code>data</code> as the new value for the <em>step multiplier</em> of 287821d3294cSantirezthe collector (see <a href="#2.10">§2.10</a>). 287921d3294cSantirezThe function returns the previous value of the step multiplier. 288021d3294cSantirez</li> 288121d3294cSantirez 288221d3294cSantirez</ul> 288321d3294cSantirez 288421d3294cSantirez 288521d3294cSantirez 288621d3294cSantirez 288721d3294cSantirez<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> 288821d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 288921d3294cSantirez<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> 289021d3294cSantirez 289121d3294cSantirez<p> 289221d3294cSantirezReturns the memory-allocation function of a given state. 289321d3294cSantirezIf <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the 289421d3294cSantirezopaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>. 289521d3294cSantirez 289621d3294cSantirez 289721d3294cSantirez 289821d3294cSantirez 289921d3294cSantirez 290021d3294cSantirez<hr><h3><a name="lua_getfenv"><code>lua_getfenv</code></a></h3><p> 290121d3294cSantirez<span class="apii">[-0, +1, <em>-</em>]</span> 290221d3294cSantirez<pre>void lua_getfenv (lua_State *L, int index);</pre> 290321d3294cSantirez 290421d3294cSantirez<p> 290521d3294cSantirezPushes onto the stack the environment table of 290621d3294cSantirezthe value at the given index. 290721d3294cSantirez 290821d3294cSantirez 290921d3294cSantirez 291021d3294cSantirez 291121d3294cSantirez 291221d3294cSantirez<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> 291321d3294cSantirez<span class="apii">[-0, +1, <em>e</em>]</span> 291421d3294cSantirez<pre>void lua_getfield (lua_State *L, int index, const char *k);</pre> 291521d3294cSantirez 291621d3294cSantirez<p> 291721d3294cSantirezPushes onto the stack the value <code>t[k]</code>, 291821d3294cSantirezwhere <code>t</code> is the value at the given valid index. 291921d3294cSantirezAs in Lua, this function may trigger a metamethod 292021d3294cSantirezfor the "index" event (see <a href="#2.8">§2.8</a>). 292121d3294cSantirez 292221d3294cSantirez 292321d3294cSantirez 292421d3294cSantirez 292521d3294cSantirez 292621d3294cSantirez<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> 292721d3294cSantirez<span class="apii">[-0, +1, <em>e</em>]</span> 292821d3294cSantirez<pre>void lua_getglobal (lua_State *L, const char *name);</pre> 292921d3294cSantirez 293021d3294cSantirez<p> 293121d3294cSantirezPushes onto the stack the value of the global <code>name</code>. 293221d3294cSantirezIt is defined as a macro: 293321d3294cSantirez 293421d3294cSantirez<pre> 293521d3294cSantirez #define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s) 293621d3294cSantirez</pre> 293721d3294cSantirez 293821d3294cSantirez 293921d3294cSantirez 294021d3294cSantirez 294121d3294cSantirez<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> 294221d3294cSantirez<span class="apii">[-0, +(0|1), <em>-</em>]</span> 294321d3294cSantirez<pre>int lua_getmetatable (lua_State *L, int index);</pre> 294421d3294cSantirez 294521d3294cSantirez<p> 294621d3294cSantirezPushes onto the stack the metatable of the value at the given 294721d3294cSantirezacceptable index. 294821d3294cSantirezIf the index is not valid, 294921d3294cSantirezor if the value does not have a metatable, 295021d3294cSantirezthe function returns 0 and pushes nothing on the stack. 295121d3294cSantirez 295221d3294cSantirez 295321d3294cSantirez 295421d3294cSantirez 295521d3294cSantirez 295621d3294cSantirez<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> 295721d3294cSantirez<span class="apii">[-1, +1, <em>e</em>]</span> 295821d3294cSantirez<pre>void lua_gettable (lua_State *L, int index);</pre> 295921d3294cSantirez 296021d3294cSantirez<p> 296121d3294cSantirezPushes onto the stack the value <code>t[k]</code>, 296221d3294cSantirezwhere <code>t</code> is the value at the given valid index 296321d3294cSantirezand <code>k</code> is the value at the top of the stack. 296421d3294cSantirez 296521d3294cSantirez 296621d3294cSantirez<p> 296721d3294cSantirezThis function pops the key from the stack 296821d3294cSantirez(putting the resulting value in its place). 296921d3294cSantirezAs in Lua, this function may trigger a metamethod 297021d3294cSantirezfor the "index" event (see <a href="#2.8">§2.8</a>). 297121d3294cSantirez 297221d3294cSantirez 297321d3294cSantirez 297421d3294cSantirez 297521d3294cSantirez 297621d3294cSantirez<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> 297721d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 297821d3294cSantirez<pre>int lua_gettop (lua_State *L);</pre> 297921d3294cSantirez 298021d3294cSantirez<p> 298121d3294cSantirezReturns the index of the top element in the stack. 298221d3294cSantirezBecause indices start at 1, 298321d3294cSantirezthis result is equal to the number of elements in the stack 298421d3294cSantirez(and so 0 means an empty stack). 298521d3294cSantirez 298621d3294cSantirez 298721d3294cSantirez 298821d3294cSantirez 298921d3294cSantirez 299021d3294cSantirez<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> 299121d3294cSantirez<span class="apii">[-1, +1, <em>-</em>]</span> 299221d3294cSantirez<pre>void lua_insert (lua_State *L, int index);</pre> 299321d3294cSantirez 299421d3294cSantirez<p> 299521d3294cSantirezMoves the top element into the given valid index, 299621d3294cSantirezshifting up the elements above this index to open space. 299721d3294cSantirezCannot be called with a pseudo-index, 299821d3294cSantirezbecause a pseudo-index is not an actual stack position. 299921d3294cSantirez 300021d3294cSantirez 300121d3294cSantirez 300221d3294cSantirez 300321d3294cSantirez 300421d3294cSantirez<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> 300521d3294cSantirez<pre>typedef ptrdiff_t lua_Integer;</pre> 300621d3294cSantirez 300721d3294cSantirez<p> 300821d3294cSantirezThe type used by the Lua API to represent integral values. 300921d3294cSantirez 301021d3294cSantirez 301121d3294cSantirez<p> 301221d3294cSantirezBy default it is a <code>ptrdiff_t</code>, 301321d3294cSantirezwhich is usually the largest signed integral type the machine handles 301421d3294cSantirez"comfortably". 301521d3294cSantirez 301621d3294cSantirez 301721d3294cSantirez 301821d3294cSantirez 301921d3294cSantirez 302021d3294cSantirez<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> 302121d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 302221d3294cSantirez<pre>int lua_isboolean (lua_State *L, int index);</pre> 302321d3294cSantirez 302421d3294cSantirez<p> 302521d3294cSantirezReturns 1 if the value at the given acceptable index has type boolean, 302621d3294cSantirezand 0 otherwise. 302721d3294cSantirez 302821d3294cSantirez 302921d3294cSantirez 303021d3294cSantirez 303121d3294cSantirez 303221d3294cSantirez<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> 303321d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 303421d3294cSantirez<pre>int lua_iscfunction (lua_State *L, int index);</pre> 303521d3294cSantirez 303621d3294cSantirez<p> 303721d3294cSantirezReturns 1 if the value at the given acceptable index is a C function, 303821d3294cSantirezand 0 otherwise. 303921d3294cSantirez 304021d3294cSantirez 304121d3294cSantirez 304221d3294cSantirez 304321d3294cSantirez 304421d3294cSantirez<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> 304521d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 304621d3294cSantirez<pre>int lua_isfunction (lua_State *L, int index);</pre> 304721d3294cSantirez 304821d3294cSantirez<p> 304921d3294cSantirezReturns 1 if the value at the given acceptable index is a function 305021d3294cSantirez(either C or Lua), and 0 otherwise. 305121d3294cSantirez 305221d3294cSantirez 305321d3294cSantirez 305421d3294cSantirez 305521d3294cSantirez 305621d3294cSantirez<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> 305721d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 305821d3294cSantirez<pre>int lua_islightuserdata (lua_State *L, int index);</pre> 305921d3294cSantirez 306021d3294cSantirez<p> 306121d3294cSantirezReturns 1 if the value at the given acceptable index is a light userdata, 306221d3294cSantirezand 0 otherwise. 306321d3294cSantirez 306421d3294cSantirez 306521d3294cSantirez 306621d3294cSantirez 306721d3294cSantirez 306821d3294cSantirez<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> 306921d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 307021d3294cSantirez<pre>int lua_isnil (lua_State *L, int index);</pre> 307121d3294cSantirez 307221d3294cSantirez<p> 307321d3294cSantirezReturns 1 if the value at the given acceptable index is <b>nil</b>, 307421d3294cSantirezand 0 otherwise. 307521d3294cSantirez 307621d3294cSantirez 307721d3294cSantirez 307821d3294cSantirez 307921d3294cSantirez 308021d3294cSantirez<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> 308121d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 308221d3294cSantirez<pre>int lua_isnone (lua_State *L, int index);</pre> 308321d3294cSantirez 308421d3294cSantirez<p> 308521d3294cSantirezReturns 1 if the given acceptable index is not valid 308621d3294cSantirez(that is, it refers to an element outside the current stack), 308721d3294cSantirezand 0 otherwise. 308821d3294cSantirez 308921d3294cSantirez 309021d3294cSantirez 309121d3294cSantirez 309221d3294cSantirez 309321d3294cSantirez<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> 309421d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 309521d3294cSantirez<pre>int lua_isnoneornil (lua_State *L, int index);</pre> 309621d3294cSantirez 309721d3294cSantirez<p> 309821d3294cSantirezReturns 1 if the given acceptable index is not valid 309921d3294cSantirez(that is, it refers to an element outside the current stack) 310021d3294cSantirezor if the value at this index is <b>nil</b>, 310121d3294cSantirezand 0 otherwise. 310221d3294cSantirez 310321d3294cSantirez 310421d3294cSantirez 310521d3294cSantirez 310621d3294cSantirez 310721d3294cSantirez<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> 310821d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 310921d3294cSantirez<pre>int lua_isnumber (lua_State *L, int index);</pre> 311021d3294cSantirez 311121d3294cSantirez<p> 311221d3294cSantirezReturns 1 if the value at the given acceptable index is a number 311321d3294cSantirezor a string convertible to a number, 311421d3294cSantirezand 0 otherwise. 311521d3294cSantirez 311621d3294cSantirez 311721d3294cSantirez 311821d3294cSantirez 311921d3294cSantirez 312021d3294cSantirez<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> 312121d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 312221d3294cSantirez<pre>int lua_isstring (lua_State *L, int index);</pre> 312321d3294cSantirez 312421d3294cSantirez<p> 312521d3294cSantirezReturns 1 if the value at the given acceptable index is a string 312621d3294cSantirezor a number (which is always convertible to a string), 312721d3294cSantirezand 0 otherwise. 312821d3294cSantirez 312921d3294cSantirez 313021d3294cSantirez 313121d3294cSantirez 313221d3294cSantirez 313321d3294cSantirez<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> 313421d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 313521d3294cSantirez<pre>int lua_istable (lua_State *L, int index);</pre> 313621d3294cSantirez 313721d3294cSantirez<p> 313821d3294cSantirezReturns 1 if the value at the given acceptable index is a table, 313921d3294cSantirezand 0 otherwise. 314021d3294cSantirez 314121d3294cSantirez 314221d3294cSantirez 314321d3294cSantirez 314421d3294cSantirez 314521d3294cSantirez<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> 314621d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 314721d3294cSantirez<pre>int lua_isthread (lua_State *L, int index);</pre> 314821d3294cSantirez 314921d3294cSantirez<p> 315021d3294cSantirezReturns 1 if the value at the given acceptable index is a thread, 315121d3294cSantirezand 0 otherwise. 315221d3294cSantirez 315321d3294cSantirez 315421d3294cSantirez 315521d3294cSantirez 315621d3294cSantirez 315721d3294cSantirez<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> 315821d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 315921d3294cSantirez<pre>int lua_isuserdata (lua_State *L, int index);</pre> 316021d3294cSantirez 316121d3294cSantirez<p> 316221d3294cSantirezReturns 1 if the value at the given acceptable index is a userdata 316321d3294cSantirez(either full or light), and 0 otherwise. 316421d3294cSantirez 316521d3294cSantirez 316621d3294cSantirez 316721d3294cSantirez 316821d3294cSantirez 316921d3294cSantirez<hr><h3><a name="lua_lessthan"><code>lua_lessthan</code></a></h3><p> 317021d3294cSantirez<span class="apii">[-0, +0, <em>e</em>]</span> 317121d3294cSantirez<pre>int lua_lessthan (lua_State *L, int index1, int index2);</pre> 317221d3294cSantirez 317321d3294cSantirez<p> 317421d3294cSantirezReturns 1 if the value at acceptable index <code>index1</code> is smaller 317521d3294cSantirezthan the value at acceptable index <code>index2</code>, 317621d3294cSantirezfollowing the semantics of the Lua <code><</code> operator 317721d3294cSantirez(that is, may call metamethods). 317821d3294cSantirezOtherwise returns 0. 317921d3294cSantirezAlso returns 0 if any of the indices is non valid. 318021d3294cSantirez 318121d3294cSantirez 318221d3294cSantirez 318321d3294cSantirez 318421d3294cSantirez 318521d3294cSantirez<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> 318621d3294cSantirez<span class="apii">[-0, +1, <em>-</em>]</span> 318721d3294cSantirez<pre>int lua_load (lua_State *L, 318821d3294cSantirez lua_Reader reader, 318921d3294cSantirez void *data, 319021d3294cSantirez const char *chunkname);</pre> 319121d3294cSantirez 319221d3294cSantirez<p> 319321d3294cSantirezLoads a Lua chunk. 319421d3294cSantirezIf there are no errors, 319521d3294cSantirez<a href="#lua_load"><code>lua_load</code></a> pushes the compiled chunk as a Lua 319621d3294cSantirezfunction on top of the stack. 319721d3294cSantirezOtherwise, it pushes an error message. 319821d3294cSantirezThe return values of <a href="#lua_load"><code>lua_load</code></a> are: 319921d3294cSantirez 320021d3294cSantirez<ul> 320121d3294cSantirez 320221d3294cSantirez<li><b>0:</b> no errors;</li> 320321d3294cSantirez 320421d3294cSantirez<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>:</b> 320521d3294cSantirezsyntax error during pre-compilation;</li> 320621d3294cSantirez 320721d3294cSantirez<li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>:</b> 320821d3294cSantirezmemory allocation error.</li> 320921d3294cSantirez 321021d3294cSantirez</ul> 321121d3294cSantirez 321221d3294cSantirez<p> 321321d3294cSantirezThis function only loads a chunk; 321421d3294cSantirezit does not run it. 321521d3294cSantirez 321621d3294cSantirez 321721d3294cSantirez<p> 321821d3294cSantirez<a href="#lua_load"><code>lua_load</code></a> automatically detects whether the chunk is text or binary, 321921d3294cSantirezand loads it accordingly (see program <code>luac</code>). 322021d3294cSantirez 322121d3294cSantirez 322221d3294cSantirez<p> 322321d3294cSantirezThe <a href="#lua_load"><code>lua_load</code></a> function uses a user-supplied <code>reader</code> function 322421d3294cSantirezto read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). 322521d3294cSantirezThe <code>data</code> argument is an opaque value passed to the reader function. 322621d3294cSantirez 322721d3294cSantirez 322821d3294cSantirez<p> 322921d3294cSantirezThe <code>chunkname</code> argument gives a name to the chunk, 323021d3294cSantirezwhich is used for error messages and in debug information (see <a href="#3.8">§3.8</a>). 323121d3294cSantirez 323221d3294cSantirez 323321d3294cSantirez 323421d3294cSantirez 323521d3294cSantirez 323621d3294cSantirez<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> 323721d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 323821d3294cSantirez<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> 323921d3294cSantirez 324021d3294cSantirez<p> 324121d3294cSantirezCreates a new, independent state. 324221d3294cSantirezReturns <code>NULL</code> if cannot create the state 324321d3294cSantirez(due to lack of memory). 324421d3294cSantirezThe argument <code>f</code> is the allocator function; 324521d3294cSantirezLua does all memory allocation for this state through this function. 324621d3294cSantirezThe second argument, <code>ud</code>, is an opaque pointer that Lua 324721d3294cSantirezsimply passes to the allocator in every call. 324821d3294cSantirez 324921d3294cSantirez 325021d3294cSantirez 325121d3294cSantirez 325221d3294cSantirez 325321d3294cSantirez<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> 325421d3294cSantirez<span class="apii">[-0, +1, <em>m</em>]</span> 325521d3294cSantirez<pre>void lua_newtable (lua_State *L);</pre> 325621d3294cSantirez 325721d3294cSantirez<p> 325821d3294cSantirezCreates a new empty table and pushes it onto the stack. 325921d3294cSantirezIt is equivalent to <code>lua_createtable(L, 0, 0)</code>. 326021d3294cSantirez 326121d3294cSantirez 326221d3294cSantirez 326321d3294cSantirez 326421d3294cSantirez 326521d3294cSantirez<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> 326621d3294cSantirez<span class="apii">[-0, +1, <em>m</em>]</span> 326721d3294cSantirez<pre>lua_State *lua_newthread (lua_State *L);</pre> 326821d3294cSantirez 326921d3294cSantirez<p> 327021d3294cSantirezCreates a new thread, pushes it on the stack, 327121d3294cSantirezand returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. 327221d3294cSantirezThe new state returned by this function shares with the original state 327321d3294cSantirezall global objects (such as tables), 327421d3294cSantirezbut has an independent execution stack. 327521d3294cSantirez 327621d3294cSantirez 327721d3294cSantirez<p> 327821d3294cSantirezThere is no explicit function to close or to destroy a thread. 327921d3294cSantirezThreads are subject to garbage collection, 328021d3294cSantirezlike any Lua object. 328121d3294cSantirez 328221d3294cSantirez 328321d3294cSantirez 328421d3294cSantirez 328521d3294cSantirez 328621d3294cSantirez<hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p> 328721d3294cSantirez<span class="apii">[-0, +1, <em>m</em>]</span> 328821d3294cSantirez<pre>void *lua_newuserdata (lua_State *L, size_t size);</pre> 328921d3294cSantirez 329021d3294cSantirez<p> 329121d3294cSantirezThis function allocates a new block of memory with the given size, 329221d3294cSantirezpushes onto the stack a new full userdata with the block address, 329321d3294cSantirezand returns this address. 329421d3294cSantirez 329521d3294cSantirez 329621d3294cSantirez<p> 329721d3294cSantirezUserdata represent C values in Lua. 329821d3294cSantirezA <em>full userdata</em> represents a block of memory. 329921d3294cSantirezIt is an object (like a table): 330021d3294cSantirezyou must create it, it can have its own metatable, 330121d3294cSantirezand you can detect when it is being collected. 330221d3294cSantirezA full userdata is only equal to itself (under raw equality). 330321d3294cSantirez 330421d3294cSantirez 330521d3294cSantirez<p> 330621d3294cSantirezWhen Lua collects a full userdata with a <code>gc</code> metamethod, 330721d3294cSantirezLua calls the metamethod and marks the userdata as finalized. 330821d3294cSantirezWhen this userdata is collected again then 330921d3294cSantirezLua frees its corresponding memory. 331021d3294cSantirez 331121d3294cSantirez 331221d3294cSantirez 331321d3294cSantirez 331421d3294cSantirez 331521d3294cSantirez<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> 331621d3294cSantirez<span class="apii">[-1, +(2|0), <em>e</em>]</span> 331721d3294cSantirez<pre>int lua_next (lua_State *L, int index);</pre> 331821d3294cSantirez 331921d3294cSantirez<p> 332021d3294cSantirezPops a key from the stack, 332121d3294cSantirezand pushes a key-value pair from the table at the given index 332221d3294cSantirez(the "next" pair after the given key). 332321d3294cSantirezIf there are no more elements in the table, 332421d3294cSantirezthen <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). 332521d3294cSantirez 332621d3294cSantirez 332721d3294cSantirez<p> 332821d3294cSantirezA typical traversal looks like this: 332921d3294cSantirez 333021d3294cSantirez<pre> 333121d3294cSantirez /* table is in the stack at index 't' */ 333221d3294cSantirez lua_pushnil(L); /* first key */ 333321d3294cSantirez while (lua_next(L, t) != 0) { 333421d3294cSantirez /* uses 'key' (at index -2) and 'value' (at index -1) */ 333521d3294cSantirez printf("%s - %s\n", 333621d3294cSantirez lua_typename(L, lua_type(L, -2)), 333721d3294cSantirez lua_typename(L, lua_type(L, -1))); 333821d3294cSantirez /* removes 'value'; keeps 'key' for next iteration */ 333921d3294cSantirez lua_pop(L, 1); 334021d3294cSantirez } 334121d3294cSantirez</pre> 334221d3294cSantirez 334321d3294cSantirez<p> 334421d3294cSantirezWhile traversing a table, 334521d3294cSantirezdo not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, 334621d3294cSantirezunless you know that the key is actually a string. 334721d3294cSantirezRecall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> <em>changes</em> 334821d3294cSantirezthe value at the given index; 334921d3294cSantirezthis confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. 335021d3294cSantirez 335121d3294cSantirez 335221d3294cSantirez 335321d3294cSantirez 335421d3294cSantirez 335521d3294cSantirez<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> 335621d3294cSantirez<pre>typedef double lua_Number;</pre> 335721d3294cSantirez 335821d3294cSantirez<p> 335921d3294cSantirezThe type of numbers in Lua. 336021d3294cSantirezBy default, it is double, but that can be changed in <code>luaconf.h</code>. 336121d3294cSantirez 336221d3294cSantirez 336321d3294cSantirez<p> 336421d3294cSantirezThrough the configuration file you can change 336521d3294cSantirezLua to operate with another type for numbers (e.g., float or long). 336621d3294cSantirez 336721d3294cSantirez 336821d3294cSantirez 336921d3294cSantirez 337021d3294cSantirez 337121d3294cSantirez<hr><h3><a name="lua_objlen"><code>lua_objlen</code></a></h3><p> 337221d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 337321d3294cSantirez<pre>size_t lua_objlen (lua_State *L, int index);</pre> 337421d3294cSantirez 337521d3294cSantirez<p> 337621d3294cSantirezReturns the "length" of the value at the given acceptable index: 337721d3294cSantirezfor strings, this is the string length; 337821d3294cSantirezfor tables, this is the result of the length operator ('<code>#</code>'); 337921d3294cSantirezfor userdata, this is the size of the block of memory allocated 338021d3294cSantirezfor the userdata; 338121d3294cSantirezfor other values, it is 0. 338221d3294cSantirez 338321d3294cSantirez 338421d3294cSantirez 338521d3294cSantirez 338621d3294cSantirez 338721d3294cSantirez<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> 338821d3294cSantirez<span class="apii">[-(nargs + 1), +(nresults|1), <em>-</em>]</span> 338921d3294cSantirez<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);</pre> 339021d3294cSantirez 339121d3294cSantirez<p> 339221d3294cSantirezCalls a function in protected mode. 339321d3294cSantirez 339421d3294cSantirez 339521d3294cSantirez<p> 339621d3294cSantirezBoth <code>nargs</code> and <code>nresults</code> have the same meaning as 339721d3294cSantirezin <a href="#lua_call"><code>lua_call</code></a>. 339821d3294cSantirezIf there are no errors during the call, 339921d3294cSantirez<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. 340021d3294cSantirezHowever, if there is any error, 340121d3294cSantirez<a href="#lua_pcall"><code>lua_pcall</code></a> catches it, 340221d3294cSantirezpushes a single value on the stack (the error message), 340321d3294cSantirezand returns an error code. 340421d3294cSantirezLike <a href="#lua_call"><code>lua_call</code></a>, 340521d3294cSantirez<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function 340621d3294cSantirezand its arguments from the stack. 340721d3294cSantirez 340821d3294cSantirez 340921d3294cSantirez<p> 341021d3294cSantirezIf <code>errfunc</code> is 0, 341121d3294cSantirezthen the error message returned on the stack 341221d3294cSantirezis exactly the original error message. 341321d3294cSantirezOtherwise, <code>errfunc</code> is the stack index of an 341421d3294cSantirez<em>error handler function</em>. 341521d3294cSantirez(In the current implementation, this index cannot be a pseudo-index.) 341621d3294cSantirezIn case of runtime errors, 341721d3294cSantirezthis function will be called with the error message 341821d3294cSantirezand its return value will be the message returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. 341921d3294cSantirez 342021d3294cSantirez 342121d3294cSantirez<p> 342221d3294cSantirezTypically, the error handler function is used to add more debug 342321d3294cSantirezinformation to the error message, such as a stack traceback. 342421d3294cSantirezSuch information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, 342521d3294cSantirezsince by then the stack has unwound. 342621d3294cSantirez 342721d3294cSantirez 342821d3294cSantirez<p> 342921d3294cSantirezThe <a href="#lua_pcall"><code>lua_pcall</code></a> function returns 0 in case of success 343021d3294cSantirezor one of the following error codes 343121d3294cSantirez(defined in <code>lua.h</code>): 343221d3294cSantirez 343321d3294cSantirez<ul> 343421d3294cSantirez 343521d3294cSantirez<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>:</b> 343621d3294cSantireza runtime error. 343721d3294cSantirez</li> 343821d3294cSantirez 343921d3294cSantirez<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>:</b> 344021d3294cSantirezmemory allocation error. 344121d3294cSantirezFor such errors, Lua does not call the error handler function. 344221d3294cSantirez</li> 344321d3294cSantirez 344421d3294cSantirez<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>:</b> 344521d3294cSantirezerror while running the error handler function. 344621d3294cSantirez</li> 344721d3294cSantirez 344821d3294cSantirez</ul> 344921d3294cSantirez 345021d3294cSantirez 345121d3294cSantirez 345221d3294cSantirez 345321d3294cSantirez<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> 345421d3294cSantirez<span class="apii">[-n, +0, <em>-</em>]</span> 345521d3294cSantirez<pre>void lua_pop (lua_State *L, int n);</pre> 345621d3294cSantirez 345721d3294cSantirez<p> 345821d3294cSantirezPops <code>n</code> elements from the stack. 345921d3294cSantirez 346021d3294cSantirez 346121d3294cSantirez 346221d3294cSantirez 346321d3294cSantirez 346421d3294cSantirez<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> 346521d3294cSantirez<span class="apii">[-0, +1, <em>-</em>]</span> 346621d3294cSantirez<pre>void lua_pushboolean (lua_State *L, int b);</pre> 346721d3294cSantirez 346821d3294cSantirez<p> 346921d3294cSantirezPushes a boolean value with value <code>b</code> onto the stack. 347021d3294cSantirez 347121d3294cSantirez 347221d3294cSantirez 347321d3294cSantirez 347421d3294cSantirez 347521d3294cSantirez<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> 347621d3294cSantirez<span class="apii">[-n, +1, <em>m</em>]</span> 347721d3294cSantirez<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> 347821d3294cSantirez 347921d3294cSantirez<p> 348021d3294cSantirezPushes a new C closure onto the stack. 348121d3294cSantirez 348221d3294cSantirez 348321d3294cSantirez<p> 348421d3294cSantirezWhen a C function is created, 348521d3294cSantirezit is possible to associate some values with it, 348621d3294cSantirezthus creating a C closure (see <a href="#3.4">§3.4</a>); 348721d3294cSantirezthese values are then accessible to the function whenever it is called. 348821d3294cSantirezTo associate values with a C function, 348921d3294cSantirezfirst these values should be pushed onto the stack 349021d3294cSantirez(when there are multiple values, the first value is pushed first). 349121d3294cSantirezThen <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 349221d3294cSantirezis called to create and push the C function onto the stack, 349321d3294cSantirezwith the argument <code>n</code> telling how many values should be 349421d3294cSantirezassociated with the function. 349521d3294cSantirez<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. 349621d3294cSantirez 349721d3294cSantirez 349821d3294cSantirez<p> 349921d3294cSantirezThe maximum value for <code>n</code> is 255. 350021d3294cSantirez 350121d3294cSantirez 350221d3294cSantirez 350321d3294cSantirez 350421d3294cSantirez 350521d3294cSantirez<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> 350621d3294cSantirez<span class="apii">[-0, +1, <em>m</em>]</span> 350721d3294cSantirez<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> 350821d3294cSantirez 350921d3294cSantirez<p> 351021d3294cSantirezPushes a C function onto the stack. 351121d3294cSantirezThis function receives a pointer to a C function 351221d3294cSantirezand pushes onto the stack a Lua value of type <code>function</code> that, 351321d3294cSantirezwhen called, invokes the corresponding C function. 351421d3294cSantirez 351521d3294cSantirez 351621d3294cSantirez<p> 351721d3294cSantirezAny function to be registered in Lua must 351821d3294cSantirezfollow the correct protocol to receive its parameters 351921d3294cSantirezand return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 352021d3294cSantirez 352121d3294cSantirez 352221d3294cSantirez<p> 352321d3294cSantirez<code>lua_pushcfunction</code> is defined as a macro: 352421d3294cSantirez 352521d3294cSantirez<pre> 352621d3294cSantirez #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0) 352721d3294cSantirez</pre> 352821d3294cSantirez 352921d3294cSantirez 353021d3294cSantirez 353121d3294cSantirez 353221d3294cSantirez<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> 353321d3294cSantirez<span class="apii">[-0, +1, <em>m</em>]</span> 353421d3294cSantirez<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> 353521d3294cSantirez 353621d3294cSantirez<p> 353721d3294cSantirezPushes onto the stack a formatted string 353821d3294cSantirezand returns a pointer to this string. 353921d3294cSantirezIt is similar to the C function <code>sprintf</code>, 354021d3294cSantirezbut has some important differences: 354121d3294cSantirez 354221d3294cSantirez<ul> 354321d3294cSantirez 354421d3294cSantirez<li> 354521d3294cSantirezYou do not have to allocate space for the result: 354621d3294cSantirezthe result is a Lua string and Lua takes care of memory allocation 354721d3294cSantirez(and deallocation, through garbage collection). 354821d3294cSantirez</li> 354921d3294cSantirez 355021d3294cSantirez<li> 355121d3294cSantirezThe conversion specifiers are quite restricted. 355221d3294cSantirezThere are no flags, widths, or precisions. 355321d3294cSantirezThe conversion specifiers can only be 355421d3294cSantirez'<code>%%</code>' (inserts a '<code>%</code>' in the string), 355521d3294cSantirez'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), 355621d3294cSantirez'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), 355721d3294cSantirez'<code>%p</code>' (inserts a pointer as a hexadecimal numeral), 355821d3294cSantirez'<code>%d</code>' (inserts an <code>int</code>), and 355921d3294cSantirez'<code>%c</code>' (inserts an <code>int</code> as a character). 356021d3294cSantirez</li> 356121d3294cSantirez 356221d3294cSantirez</ul> 356321d3294cSantirez 356421d3294cSantirez 356521d3294cSantirez 356621d3294cSantirez 356721d3294cSantirez<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> 356821d3294cSantirez<span class="apii">[-0, +1, <em>-</em>]</span> 356921d3294cSantirez<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> 357021d3294cSantirez 357121d3294cSantirez<p> 357221d3294cSantirezPushes a number with value <code>n</code> onto the stack. 357321d3294cSantirez 357421d3294cSantirez 357521d3294cSantirez 357621d3294cSantirez 357721d3294cSantirez 357821d3294cSantirez<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> 357921d3294cSantirez<span class="apii">[-0, +1, <em>-</em>]</span> 358021d3294cSantirez<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> 358121d3294cSantirez 358221d3294cSantirez<p> 358321d3294cSantirezPushes a light userdata onto the stack. 358421d3294cSantirez 358521d3294cSantirez 358621d3294cSantirez<p> 358721d3294cSantirezUserdata represent C values in Lua. 358821d3294cSantirezA <em>light userdata</em> represents a pointer. 358921d3294cSantirezIt is a value (like a number): 359021d3294cSantirezyou do not create it, it has no individual metatable, 359121d3294cSantirezand it is not collected (as it was never created). 359221d3294cSantirezA light userdata is equal to "any" 359321d3294cSantirezlight userdata with the same C address. 359421d3294cSantirez 359521d3294cSantirez 359621d3294cSantirez 359721d3294cSantirez 359821d3294cSantirez 359921d3294cSantirez<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> 360021d3294cSantirez<span class="apii">[-0, +1, <em>m</em>]</span> 360121d3294cSantirez<pre>void lua_pushliteral (lua_State *L, const char *s);</pre> 360221d3294cSantirez 360321d3294cSantirez<p> 360421d3294cSantirezThis macro is equivalent to <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>, 360521d3294cSantirezbut can be used only when <code>s</code> is a literal string. 360621d3294cSantirezIn these cases, it automatically provides the string length. 360721d3294cSantirez 360821d3294cSantirez 360921d3294cSantirez 361021d3294cSantirez 361121d3294cSantirez 361221d3294cSantirez<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> 361321d3294cSantirez<span class="apii">[-0, +1, <em>m</em>]</span> 361421d3294cSantirez<pre>void lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> 361521d3294cSantirez 361621d3294cSantirez<p> 361721d3294cSantirezPushes the string pointed to by <code>s</code> with size <code>len</code> 361821d3294cSantirezonto the stack. 361921d3294cSantirezLua makes (or reuses) an internal copy of the given string, 362021d3294cSantirezso the memory at <code>s</code> can be freed or reused immediately after 362121d3294cSantirezthe function returns. 362221d3294cSantirezThe string can contain embedded zeros. 362321d3294cSantirez 362421d3294cSantirez 362521d3294cSantirez 362621d3294cSantirez 362721d3294cSantirez 362821d3294cSantirez<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> 362921d3294cSantirez<span class="apii">[-0, +1, <em>-</em>]</span> 363021d3294cSantirez<pre>void lua_pushnil (lua_State *L);</pre> 363121d3294cSantirez 363221d3294cSantirez<p> 363321d3294cSantirezPushes a nil value onto the stack. 363421d3294cSantirez 363521d3294cSantirez 363621d3294cSantirez 363721d3294cSantirez 363821d3294cSantirez 363921d3294cSantirez<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> 364021d3294cSantirez<span class="apii">[-0, +1, <em>-</em>]</span> 364121d3294cSantirez<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> 364221d3294cSantirez 364321d3294cSantirez<p> 364421d3294cSantirezPushes a number with value <code>n</code> onto the stack. 364521d3294cSantirez 364621d3294cSantirez 364721d3294cSantirez 364821d3294cSantirez 364921d3294cSantirez 365021d3294cSantirez<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> 365121d3294cSantirez<span class="apii">[-0, +1, <em>m</em>]</span> 365221d3294cSantirez<pre>void lua_pushstring (lua_State *L, const char *s);</pre> 365321d3294cSantirez 365421d3294cSantirez<p> 365521d3294cSantirezPushes the zero-terminated string pointed to by <code>s</code> 365621d3294cSantirezonto the stack. 365721d3294cSantirezLua makes (or reuses) an internal copy of the given string, 365821d3294cSantirezso the memory at <code>s</code> can be freed or reused immediately after 365921d3294cSantirezthe function returns. 366021d3294cSantirezThe string cannot contain embedded zeros; 366121d3294cSantirezit is assumed to end at the first zero. 366221d3294cSantirez 366321d3294cSantirez 366421d3294cSantirez 366521d3294cSantirez 366621d3294cSantirez 366721d3294cSantirez<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> 366821d3294cSantirez<span class="apii">[-0, +1, <em>-</em>]</span> 366921d3294cSantirez<pre>int lua_pushthread (lua_State *L);</pre> 367021d3294cSantirez 367121d3294cSantirez<p> 367221d3294cSantirezPushes the thread represented by <code>L</code> onto the stack. 367321d3294cSantirezReturns 1 if this thread is the main thread of its state. 367421d3294cSantirez 367521d3294cSantirez 367621d3294cSantirez 367721d3294cSantirez 367821d3294cSantirez 367921d3294cSantirez<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> 368021d3294cSantirez<span class="apii">[-0, +1, <em>-</em>]</span> 368121d3294cSantirez<pre>void lua_pushvalue (lua_State *L, int index);</pre> 368221d3294cSantirez 368321d3294cSantirez<p> 368421d3294cSantirezPushes a copy of the element at the given valid index 368521d3294cSantirezonto the stack. 368621d3294cSantirez 368721d3294cSantirez 368821d3294cSantirez 368921d3294cSantirez 369021d3294cSantirez 369121d3294cSantirez<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> 369221d3294cSantirez<span class="apii">[-0, +1, <em>m</em>]</span> 369321d3294cSantirez<pre>const char *lua_pushvfstring (lua_State *L, 369421d3294cSantirez const char *fmt, 369521d3294cSantirez va_list argp);</pre> 369621d3294cSantirez 369721d3294cSantirez<p> 369821d3294cSantirezEquivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> 369921d3294cSantirezinstead of a variable number of arguments. 370021d3294cSantirez 370121d3294cSantirez 370221d3294cSantirez 370321d3294cSantirez 370421d3294cSantirez 370521d3294cSantirez<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> 370621d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 370721d3294cSantirez<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> 370821d3294cSantirez 370921d3294cSantirez<p> 371021d3294cSantirezReturns 1 if the two values in acceptable indices <code>index1</code> and 371121d3294cSantirez<code>index2</code> are primitively equal 371221d3294cSantirez(that is, without calling metamethods). 371321d3294cSantirezOtherwise returns 0. 371421d3294cSantirezAlso returns 0 if any of the indices are non valid. 371521d3294cSantirez 371621d3294cSantirez 371721d3294cSantirez 371821d3294cSantirez 371921d3294cSantirez 372021d3294cSantirez<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> 372121d3294cSantirez<span class="apii">[-1, +1, <em>-</em>]</span> 372221d3294cSantirez<pre>void lua_rawget (lua_State *L, int index);</pre> 372321d3294cSantirez 372421d3294cSantirez<p> 372521d3294cSantirezSimilar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access 372621d3294cSantirez(i.e., without metamethods). 372721d3294cSantirez 372821d3294cSantirez 372921d3294cSantirez 373021d3294cSantirez 373121d3294cSantirez 373221d3294cSantirez<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> 373321d3294cSantirez<span class="apii">[-0, +1, <em>-</em>]</span> 373421d3294cSantirez<pre>void lua_rawgeti (lua_State *L, int index, int n);</pre> 373521d3294cSantirez 373621d3294cSantirez<p> 373721d3294cSantirezPushes onto the stack the value <code>t[n]</code>, 373821d3294cSantirezwhere <code>t</code> is the value at the given valid index. 373921d3294cSantirezThe access is raw; 374021d3294cSantirezthat is, it does not invoke metamethods. 374121d3294cSantirez 374221d3294cSantirez 374321d3294cSantirez 374421d3294cSantirez 374521d3294cSantirez 374621d3294cSantirez<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> 374721d3294cSantirez<span class="apii">[-2, +0, <em>m</em>]</span> 374821d3294cSantirez<pre>void lua_rawset (lua_State *L, int index);</pre> 374921d3294cSantirez 375021d3294cSantirez<p> 375121d3294cSantirezSimilar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment 375221d3294cSantirez(i.e., without metamethods). 375321d3294cSantirez 375421d3294cSantirez 375521d3294cSantirez 375621d3294cSantirez 375721d3294cSantirez 375821d3294cSantirez<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> 375921d3294cSantirez<span class="apii">[-1, +0, <em>m</em>]</span> 376021d3294cSantirez<pre>void lua_rawseti (lua_State *L, int index, int n);</pre> 376121d3294cSantirez 376221d3294cSantirez<p> 376321d3294cSantirezDoes the equivalent of <code>t[n] = v</code>, 376421d3294cSantirezwhere <code>t</code> is the value at the given valid index 376521d3294cSantirezand <code>v</code> is the value at the top of the stack. 376621d3294cSantirez 376721d3294cSantirez 376821d3294cSantirez<p> 376921d3294cSantirezThis function pops the value from the stack. 377021d3294cSantirezThe assignment is raw; 377121d3294cSantirezthat is, it does not invoke metamethods. 377221d3294cSantirez 377321d3294cSantirez 377421d3294cSantirez 377521d3294cSantirez 377621d3294cSantirez 377721d3294cSantirez<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> 377821d3294cSantirez<pre>typedef const char * (*lua_Reader) (lua_State *L, 377921d3294cSantirez void *data, 378021d3294cSantirez size_t *size);</pre> 378121d3294cSantirez 378221d3294cSantirez<p> 378321d3294cSantirezThe reader function used by <a href="#lua_load"><code>lua_load</code></a>. 378421d3294cSantirezEvery time it needs another piece of the chunk, 378521d3294cSantirez<a href="#lua_load"><code>lua_load</code></a> calls the reader, 378621d3294cSantirezpassing along its <code>data</code> parameter. 378721d3294cSantirezThe reader must return a pointer to a block of memory 378821d3294cSantirezwith a new piece of the chunk 378921d3294cSantirezand set <code>size</code> to the block size. 379021d3294cSantirezThe block must exist until the reader function is called again. 379121d3294cSantirezTo signal the end of the chunk, 379221d3294cSantirezthe reader must return <code>NULL</code> or set <code>size</code> to zero. 379321d3294cSantirezThe reader function may return pieces of any size greater than zero. 379421d3294cSantirez 379521d3294cSantirez 379621d3294cSantirez 379721d3294cSantirez 379821d3294cSantirez 379921d3294cSantirez<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> 380021d3294cSantirez<span class="apii">[-0, +0, <em>e</em>]</span> 380121d3294cSantirez<pre>void lua_register (lua_State *L, 380221d3294cSantirez const char *name, 380321d3294cSantirez lua_CFunction f);</pre> 380421d3294cSantirez 380521d3294cSantirez<p> 380621d3294cSantirezSets the C function <code>f</code> as the new value of global <code>name</code>. 380721d3294cSantirezIt is defined as a macro: 380821d3294cSantirez 380921d3294cSantirez<pre> 381021d3294cSantirez #define lua_register(L,n,f) \ 381121d3294cSantirez (lua_pushcfunction(L, f), lua_setglobal(L, n)) 381221d3294cSantirez</pre> 381321d3294cSantirez 381421d3294cSantirez 381521d3294cSantirez 381621d3294cSantirez 381721d3294cSantirez<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> 381821d3294cSantirez<span class="apii">[-1, +0, <em>-</em>]</span> 381921d3294cSantirez<pre>void lua_remove (lua_State *L, int index);</pre> 382021d3294cSantirez 382121d3294cSantirez<p> 382221d3294cSantirezRemoves the element at the given valid index, 382321d3294cSantirezshifting down the elements above this index to fill the gap. 382421d3294cSantirezCannot be called with a pseudo-index, 382521d3294cSantirezbecause a pseudo-index is not an actual stack position. 382621d3294cSantirez 382721d3294cSantirez 382821d3294cSantirez 382921d3294cSantirez 383021d3294cSantirez 383121d3294cSantirez<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> 383221d3294cSantirez<span class="apii">[-1, +0, <em>-</em>]</span> 383321d3294cSantirez<pre>void lua_replace (lua_State *L, int index);</pre> 383421d3294cSantirez 383521d3294cSantirez<p> 383621d3294cSantirezMoves the top element into the given position (and pops it), 383721d3294cSantirezwithout shifting any element 383821d3294cSantirez(therefore replacing the value at the given position). 383921d3294cSantirez 384021d3294cSantirez 384121d3294cSantirez 384221d3294cSantirez 384321d3294cSantirez 384421d3294cSantirez<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> 384521d3294cSantirez<span class="apii">[-?, +?, <em>-</em>]</span> 384621d3294cSantirez<pre>int lua_resume (lua_State *L, int narg);</pre> 384721d3294cSantirez 384821d3294cSantirez<p> 384921d3294cSantirezStarts and resumes a coroutine in a given thread. 385021d3294cSantirez 385121d3294cSantirez 385221d3294cSantirez<p> 385321d3294cSantirezTo start a coroutine, you first create a new thread 385421d3294cSantirez(see <a href="#lua_newthread"><code>lua_newthread</code></a>); 385521d3294cSantirezthen you push onto its stack the main function plus any arguments; 385621d3294cSantirezthen you call <a href="#lua_resume"><code>lua_resume</code></a>, 385721d3294cSantirezwith <code>narg</code> being the number of arguments. 385821d3294cSantirezThis call returns when the coroutine suspends or finishes its execution. 385921d3294cSantirezWhen it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>, 386021d3294cSantirezor all values returned by the body function. 386121d3294cSantirez<a href="#lua_resume"><code>lua_resume</code></a> returns 386221d3294cSantirez<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, 386321d3294cSantirez0 if the coroutine finishes its execution 386421d3294cSantirezwithout errors, 386521d3294cSantirezor an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). 386621d3294cSantirezIn case of errors, 386721d3294cSantirezthe stack is not unwound, 386821d3294cSantirezso you can use the debug API over it. 386921d3294cSantirezThe error message is on the top of the stack. 387021d3294cSantirezTo restart a coroutine, you put on its stack only the values to 387121d3294cSantirezbe passed as results from <code>yield</code>, 387221d3294cSantirezand then call <a href="#lua_resume"><code>lua_resume</code></a>. 387321d3294cSantirez 387421d3294cSantirez 387521d3294cSantirez 387621d3294cSantirez 387721d3294cSantirez 387821d3294cSantirez<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> 387921d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 388021d3294cSantirez<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> 388121d3294cSantirez 388221d3294cSantirez<p> 388321d3294cSantirezChanges the allocator function of a given state to <code>f</code> 388421d3294cSantirezwith user data <code>ud</code>. 388521d3294cSantirez 388621d3294cSantirez 388721d3294cSantirez 388821d3294cSantirez 388921d3294cSantirez 389021d3294cSantirez<hr><h3><a name="lua_setfenv"><code>lua_setfenv</code></a></h3><p> 389121d3294cSantirez<span class="apii">[-1, +0, <em>-</em>]</span> 389221d3294cSantirez<pre>int lua_setfenv (lua_State *L, int index);</pre> 389321d3294cSantirez 389421d3294cSantirez<p> 389521d3294cSantirezPops a table from the stack and sets it as 389621d3294cSantirezthe new environment for the value at the given index. 389721d3294cSantirezIf the value at the given index is 389821d3294cSantirezneither a function nor a thread nor a userdata, 389921d3294cSantirez<a href="#lua_setfenv"><code>lua_setfenv</code></a> returns 0. 390021d3294cSantirezOtherwise it returns 1. 390121d3294cSantirez 390221d3294cSantirez 390321d3294cSantirez 390421d3294cSantirez 390521d3294cSantirez 390621d3294cSantirez<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> 390721d3294cSantirez<span class="apii">[-1, +0, <em>e</em>]</span> 390821d3294cSantirez<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> 390921d3294cSantirez 391021d3294cSantirez<p> 391121d3294cSantirezDoes the equivalent to <code>t[k] = v</code>, 391221d3294cSantirezwhere <code>t</code> is the value at the given valid index 391321d3294cSantirezand <code>v</code> is the value at the top of the stack. 391421d3294cSantirez 391521d3294cSantirez 391621d3294cSantirez<p> 391721d3294cSantirezThis function pops the value from the stack. 391821d3294cSantirezAs in Lua, this function may trigger a metamethod 391921d3294cSantirezfor the "newindex" event (see <a href="#2.8">§2.8</a>). 392021d3294cSantirez 392121d3294cSantirez 392221d3294cSantirez 392321d3294cSantirez 392421d3294cSantirez 392521d3294cSantirez<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> 392621d3294cSantirez<span class="apii">[-1, +0, <em>e</em>]</span> 392721d3294cSantirez<pre>void lua_setglobal (lua_State *L, const char *name);</pre> 392821d3294cSantirez 392921d3294cSantirez<p> 393021d3294cSantirezPops a value from the stack and 393121d3294cSantirezsets it as the new value of global <code>name</code>. 393221d3294cSantirezIt is defined as a macro: 393321d3294cSantirez 393421d3294cSantirez<pre> 393521d3294cSantirez #define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s) 393621d3294cSantirez</pre> 393721d3294cSantirez 393821d3294cSantirez 393921d3294cSantirez 394021d3294cSantirez 394121d3294cSantirez<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> 394221d3294cSantirez<span class="apii">[-1, +0, <em>-</em>]</span> 394321d3294cSantirez<pre>int lua_setmetatable (lua_State *L, int index);</pre> 394421d3294cSantirez 394521d3294cSantirez<p> 394621d3294cSantirezPops a table from the stack and 394721d3294cSantirezsets it as the new metatable for the value at the given 394821d3294cSantirezacceptable index. 394921d3294cSantirez 395021d3294cSantirez 395121d3294cSantirez 395221d3294cSantirez 395321d3294cSantirez 395421d3294cSantirez<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> 395521d3294cSantirez<span class="apii">[-2, +0, <em>e</em>]</span> 395621d3294cSantirez<pre>void lua_settable (lua_State *L, int index);</pre> 395721d3294cSantirez 395821d3294cSantirez<p> 395921d3294cSantirezDoes the equivalent to <code>t[k] = v</code>, 396021d3294cSantirezwhere <code>t</code> is the value at the given valid index, 396121d3294cSantirez<code>v</code> is the value at the top of the stack, 396221d3294cSantirezand <code>k</code> is the value just below the top. 396321d3294cSantirez 396421d3294cSantirez 396521d3294cSantirez<p> 396621d3294cSantirezThis function pops both the key and the value from the stack. 396721d3294cSantirezAs in Lua, this function may trigger a metamethod 396821d3294cSantirezfor the "newindex" event (see <a href="#2.8">§2.8</a>). 396921d3294cSantirez 397021d3294cSantirez 397121d3294cSantirez 397221d3294cSantirez 397321d3294cSantirez 397421d3294cSantirez<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> 397521d3294cSantirez<span class="apii">[-?, +?, <em>-</em>]</span> 397621d3294cSantirez<pre>void lua_settop (lua_State *L, int index);</pre> 397721d3294cSantirez 397821d3294cSantirez<p> 397921d3294cSantirezAccepts any acceptable index, or 0, 398021d3294cSantirezand sets the stack top to this index. 398121d3294cSantirezIf the new top is larger than the old one, 398221d3294cSantirezthen the new elements are filled with <b>nil</b>. 398321d3294cSantirezIf <code>index</code> is 0, then all stack elements are removed. 398421d3294cSantirez 398521d3294cSantirez 398621d3294cSantirez 398721d3294cSantirez 398821d3294cSantirez 398921d3294cSantirez<hr><h3><a name="lua_State"><code>lua_State</code></a></h3> 399021d3294cSantirez<pre>typedef struct lua_State lua_State;</pre> 399121d3294cSantirez 399221d3294cSantirez<p> 399321d3294cSantirezOpaque structure that keeps the whole state of a Lua interpreter. 399421d3294cSantirezThe Lua library is fully reentrant: 399521d3294cSantirezit has no global variables. 399621d3294cSantirezAll information about a state is kept in this structure. 399721d3294cSantirez 399821d3294cSantirez 399921d3294cSantirez<p> 400021d3294cSantirezA pointer to this state must be passed as the first argument to 400121d3294cSantirezevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 400221d3294cSantirezwhich creates a Lua state from scratch. 400321d3294cSantirez 400421d3294cSantirez 400521d3294cSantirez 400621d3294cSantirez 400721d3294cSantirez 400821d3294cSantirez<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> 400921d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 401021d3294cSantirez<pre>int lua_status (lua_State *L);</pre> 401121d3294cSantirez 401221d3294cSantirez<p> 401321d3294cSantirezReturns the status of the thread <code>L</code>. 401421d3294cSantirez 401521d3294cSantirez 401621d3294cSantirez<p> 401721d3294cSantirezThe status can be 0 for a normal thread, 401821d3294cSantirezan error code if the thread finished its execution with an error, 401921d3294cSantirezor <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. 402021d3294cSantirez 402121d3294cSantirez 402221d3294cSantirez 402321d3294cSantirez 402421d3294cSantirez 402521d3294cSantirez<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> 402621d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 402721d3294cSantirez<pre>int lua_toboolean (lua_State *L, int index);</pre> 402821d3294cSantirez 402921d3294cSantirez<p> 403021d3294cSantirezConverts the Lua value at the given acceptable index to a C boolean 403121d3294cSantirezvalue (0 or 1). 403221d3294cSantirezLike all tests in Lua, 403321d3294cSantirez<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns 1 for any Lua value 403421d3294cSantirezdifferent from <b>false</b> and <b>nil</b>; 403521d3294cSantirezotherwise it returns 0. 403621d3294cSantirezIt also returns 0 when called with a non-valid index. 403721d3294cSantirez(If you want to accept only actual boolean values, 403821d3294cSantirezuse <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) 403921d3294cSantirez 404021d3294cSantirez 404121d3294cSantirez 404221d3294cSantirez 404321d3294cSantirez 404421d3294cSantirez<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> 404521d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 404621d3294cSantirez<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> 404721d3294cSantirez 404821d3294cSantirez<p> 404921d3294cSantirezConverts a value at the given acceptable index to a C function. 405021d3294cSantirezThat value must be a C function; 405121d3294cSantirezotherwise, returns <code>NULL</code>. 405221d3294cSantirez 405321d3294cSantirez 405421d3294cSantirez 405521d3294cSantirez 405621d3294cSantirez 405721d3294cSantirez<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> 405821d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 405921d3294cSantirez<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> 406021d3294cSantirez 406121d3294cSantirez<p> 406221d3294cSantirezConverts the Lua value at the given acceptable index 406321d3294cSantirezto the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. 406421d3294cSantirezThe Lua value must be a number or a string convertible to a number 406521d3294cSantirez(see <a href="#2.2.1">§2.2.1</a>); 406621d3294cSantirezotherwise, <a href="#lua_tointeger"><code>lua_tointeger</code></a> returns 0. 406721d3294cSantirez 406821d3294cSantirez 406921d3294cSantirez<p> 407021d3294cSantirezIf the number is not an integer, 407121d3294cSantirezit is truncated in some non-specified way. 407221d3294cSantirez 407321d3294cSantirez 407421d3294cSantirez 407521d3294cSantirez 407621d3294cSantirez 407721d3294cSantirez<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> 407821d3294cSantirez<span class="apii">[-0, +0, <em>m</em>]</span> 407921d3294cSantirez<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> 408021d3294cSantirez 408121d3294cSantirez<p> 408221d3294cSantirezConverts the Lua value at the given acceptable index to a C string. 408321d3294cSantirezIf <code>len</code> is not <code>NULL</code>, 408421d3294cSantirezit also sets <code>*len</code> with the string length. 408521d3294cSantirezThe Lua value must be a string or a number; 408621d3294cSantirezotherwise, the function returns <code>NULL</code>. 408721d3294cSantirezIf the value is a number, 408821d3294cSantirezthen <a href="#lua_tolstring"><code>lua_tolstring</code></a> also 408921d3294cSantirez<em>changes the actual value in the stack to a string</em>. 409021d3294cSantirez(This change confuses <a href="#lua_next"><code>lua_next</code></a> 409121d3294cSantirezwhen <a href="#lua_tolstring"><code>lua_tolstring</code></a> is applied to keys during a table traversal.) 409221d3294cSantirez 409321d3294cSantirez 409421d3294cSantirez<p> 409521d3294cSantirez<a href="#lua_tolstring"><code>lua_tolstring</code></a> returns a fully aligned pointer 409621d3294cSantirezto a string inside the Lua state. 409721d3294cSantirezThis string always has a zero ('<code>\0</code>') 409821d3294cSantirezafter its last character (as in C), 409921d3294cSantirezbut can contain other zeros in its body. 410021d3294cSantirezBecause Lua has garbage collection, 410121d3294cSantirezthere is no guarantee that the pointer returned by <a href="#lua_tolstring"><code>lua_tolstring</code></a> 410221d3294cSantirezwill be valid after the corresponding value is removed from the stack. 410321d3294cSantirez 410421d3294cSantirez 410521d3294cSantirez 410621d3294cSantirez 410721d3294cSantirez 410821d3294cSantirez<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> 410921d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 411021d3294cSantirez<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> 411121d3294cSantirez 411221d3294cSantirez<p> 411321d3294cSantirezConverts the Lua value at the given acceptable index 411421d3294cSantirezto the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). 411521d3294cSantirezThe Lua value must be a number or a string convertible to a number 411621d3294cSantirez(see <a href="#2.2.1">§2.2.1</a>); 411721d3294cSantirezotherwise, <a href="#lua_tonumber"><code>lua_tonumber</code></a> returns 0. 411821d3294cSantirez 411921d3294cSantirez 412021d3294cSantirez 412121d3294cSantirez 412221d3294cSantirez 412321d3294cSantirez<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> 412421d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 412521d3294cSantirez<pre>const void *lua_topointer (lua_State *L, int index);</pre> 412621d3294cSantirez 412721d3294cSantirez<p> 412821d3294cSantirezConverts the value at the given acceptable index to a generic 412921d3294cSantirezC pointer (<code>void*</code>). 413021d3294cSantirezThe value can be a userdata, a table, a thread, or a function; 413121d3294cSantirezotherwise, <a href="#lua_topointer"><code>lua_topointer</code></a> returns <code>NULL</code>. 413221d3294cSantirezDifferent objects will give different pointers. 413321d3294cSantirezThere is no way to convert the pointer back to its original value. 413421d3294cSantirez 413521d3294cSantirez 413621d3294cSantirez<p> 413721d3294cSantirezTypically this function is used only for debug information. 413821d3294cSantirez 413921d3294cSantirez 414021d3294cSantirez 414121d3294cSantirez 414221d3294cSantirez 414321d3294cSantirez<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> 414421d3294cSantirez<span class="apii">[-0, +0, <em>m</em>]</span> 414521d3294cSantirez<pre>const char *lua_tostring (lua_State *L, int index);</pre> 414621d3294cSantirez 414721d3294cSantirez<p> 414821d3294cSantirezEquivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. 414921d3294cSantirez 415021d3294cSantirez 415121d3294cSantirez 415221d3294cSantirez 415321d3294cSantirez 415421d3294cSantirez<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> 415521d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 415621d3294cSantirez<pre>lua_State *lua_tothread (lua_State *L, int index);</pre> 415721d3294cSantirez 415821d3294cSantirez<p> 415921d3294cSantirezConverts the value at the given acceptable index to a Lua thread 416021d3294cSantirez(represented as <code>lua_State*</code>). 416121d3294cSantirezThis value must be a thread; 416221d3294cSantirezotherwise, the function returns <code>NULL</code>. 416321d3294cSantirez 416421d3294cSantirez 416521d3294cSantirez 416621d3294cSantirez 416721d3294cSantirez 416821d3294cSantirez<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> 416921d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 417021d3294cSantirez<pre>void *lua_touserdata (lua_State *L, int index);</pre> 417121d3294cSantirez 417221d3294cSantirez<p> 417321d3294cSantirezIf the value at the given acceptable index is a full userdata, 417421d3294cSantirezreturns its block address. 417521d3294cSantirezIf the value is a light userdata, 417621d3294cSantirezreturns its pointer. 417721d3294cSantirezOtherwise, returns <code>NULL</code>. 417821d3294cSantirez 417921d3294cSantirez 418021d3294cSantirez 418121d3294cSantirez 418221d3294cSantirez 418321d3294cSantirez<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> 418421d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 418521d3294cSantirez<pre>int lua_type (lua_State *L, int index);</pre> 418621d3294cSantirez 418721d3294cSantirez<p> 418821d3294cSantirezReturns the type of the value in the given acceptable index, 418921d3294cSantirezor <code>LUA_TNONE</code> for a non-valid index 419021d3294cSantirez(that is, an index to an "empty" stack position). 419121d3294cSantirezThe types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants 419221d3294cSantirezdefined in <code>lua.h</code>: 419321d3294cSantirez<code>LUA_TNIL</code>, 419421d3294cSantirez<code>LUA_TNUMBER</code>, 419521d3294cSantirez<code>LUA_TBOOLEAN</code>, 419621d3294cSantirez<code>LUA_TSTRING</code>, 419721d3294cSantirez<code>LUA_TTABLE</code>, 419821d3294cSantirez<code>LUA_TFUNCTION</code>, 419921d3294cSantirez<code>LUA_TUSERDATA</code>, 420021d3294cSantirez<code>LUA_TTHREAD</code>, 420121d3294cSantirezand 420221d3294cSantirez<code>LUA_TLIGHTUSERDATA</code>. 420321d3294cSantirez 420421d3294cSantirez 420521d3294cSantirez 420621d3294cSantirez 420721d3294cSantirez 420821d3294cSantirez<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> 420921d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 421021d3294cSantirez<pre>const char *lua_typename (lua_State *L, int tp);</pre> 421121d3294cSantirez 421221d3294cSantirez<p> 421321d3294cSantirezReturns the name of the type encoded by the value <code>tp</code>, 421421d3294cSantirezwhich must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. 421521d3294cSantirez 421621d3294cSantirez 421721d3294cSantirez 421821d3294cSantirez 421921d3294cSantirez 422021d3294cSantirez<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> 422121d3294cSantirez<pre>typedef int (*lua_Writer) (lua_State *L, 422221d3294cSantirez const void* p, 422321d3294cSantirez size_t sz, 422421d3294cSantirez void* ud);</pre> 422521d3294cSantirez 422621d3294cSantirez<p> 422721d3294cSantirezThe type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. 422821d3294cSantirezEvery time it produces another piece of chunk, 422921d3294cSantirez<a href="#lua_dump"><code>lua_dump</code></a> calls the writer, 423021d3294cSantirezpassing along the buffer to be written (<code>p</code>), 423121d3294cSantirezits size (<code>sz</code>), 423221d3294cSantirezand the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. 423321d3294cSantirez 423421d3294cSantirez 423521d3294cSantirez<p> 423621d3294cSantirezThe writer returns an error code: 423721d3294cSantirez0 means no errors; 423821d3294cSantirezany other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from 423921d3294cSantirezcalling the writer again. 424021d3294cSantirez 424121d3294cSantirez 424221d3294cSantirez 424321d3294cSantirez 424421d3294cSantirez 424521d3294cSantirez<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> 424621d3294cSantirez<span class="apii">[-?, +?, <em>-</em>]</span> 424721d3294cSantirez<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> 424821d3294cSantirez 424921d3294cSantirez<p> 425021d3294cSantirezExchange values between different threads of the <em>same</em> global state. 425121d3294cSantirez 425221d3294cSantirez 425321d3294cSantirez<p> 425421d3294cSantirezThis function pops <code>n</code> values from the stack <code>from</code>, 425521d3294cSantirezand pushes them onto the stack <code>to</code>. 425621d3294cSantirez 425721d3294cSantirez 425821d3294cSantirez 425921d3294cSantirez 426021d3294cSantirez 426121d3294cSantirez<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> 426221d3294cSantirez<span class="apii">[-?, +?, <em>-</em>]</span> 426321d3294cSantirez<pre>int lua_yield (lua_State *L, int nresults);</pre> 426421d3294cSantirez 426521d3294cSantirez<p> 426621d3294cSantirezYields a coroutine. 426721d3294cSantirez 426821d3294cSantirez 426921d3294cSantirez<p> 427021d3294cSantirezThis function should only be called as the 427121d3294cSantirezreturn expression of a C function, as follows: 427221d3294cSantirez 427321d3294cSantirez<pre> 427421d3294cSantirez return lua_yield (L, nresults); 427521d3294cSantirez</pre><p> 427621d3294cSantirezWhen a C function calls <a href="#lua_yield"><code>lua_yield</code></a> in that way, 427721d3294cSantirezthe running coroutine suspends its execution, 427821d3294cSantirezand the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. 427921d3294cSantirezThe parameter <code>nresults</code> is the number of values from the stack 428021d3294cSantirezthat are passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. 428121d3294cSantirez 428221d3294cSantirez 428321d3294cSantirez 428421d3294cSantirez 428521d3294cSantirez 428621d3294cSantirez 428721d3294cSantirez 428821d3294cSantirez<h2>3.8 - <a name="3.8">The Debug Interface</a></h2> 428921d3294cSantirez 429021d3294cSantirez<p> 429121d3294cSantirezLua has no built-in debugging facilities. 429221d3294cSantirezInstead, it offers a special interface 429321d3294cSantirezby means of functions and <em>hooks</em>. 429421d3294cSantirezThis interface allows the construction of different 429521d3294cSantirezkinds of debuggers, profilers, and other tools 429621d3294cSantirezthat need "inside information" from the interpreter. 429721d3294cSantirez 429821d3294cSantirez 429921d3294cSantirez 430021d3294cSantirez<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> 430121d3294cSantirez<pre>typedef struct lua_Debug { 430221d3294cSantirez int event; 430321d3294cSantirez const char *name; /* (n) */ 430421d3294cSantirez const char *namewhat; /* (n) */ 430521d3294cSantirez const char *what; /* (S) */ 430621d3294cSantirez const char *source; /* (S) */ 430721d3294cSantirez int currentline; /* (l) */ 430821d3294cSantirez int nups; /* (u) number of upvalues */ 430921d3294cSantirez int linedefined; /* (S) */ 431021d3294cSantirez int lastlinedefined; /* (S) */ 431121d3294cSantirez char short_src[LUA_IDSIZE]; /* (S) */ 431221d3294cSantirez /* private part */ 431321d3294cSantirez <em>other fields</em> 431421d3294cSantirez} lua_Debug;</pre> 431521d3294cSantirez 431621d3294cSantirez<p> 431721d3294cSantirezA structure used to carry different pieces of 431821d3294cSantirezinformation about an active function. 431921d3294cSantirez<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part 432021d3294cSantirezof this structure, for later use. 432121d3294cSantirezTo fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, 432221d3294cSantirezcall <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 432321d3294cSantirez 432421d3294cSantirez 432521d3294cSantirez<p> 432621d3294cSantirezThe fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: 432721d3294cSantirez 432821d3294cSantirez<ul> 432921d3294cSantirez 433021d3294cSantirez<li><b><code>source</code>:</b> 433121d3294cSantirezIf the function was defined in a string, 433221d3294cSantirezthen <code>source</code> is that string. 433321d3294cSantirezIf the function was defined in a file, 433421d3294cSantirezthen <code>source</code> starts with a '<code>@</code>' followed by the file name. 433521d3294cSantirez</li> 433621d3294cSantirez 433721d3294cSantirez<li><b><code>short_src</code>:</b> 433821d3294cSantireza "printable" version of <code>source</code>, to be used in error messages. 433921d3294cSantirez</li> 434021d3294cSantirez 434121d3294cSantirez<li><b><code>linedefined</code>:</b> 434221d3294cSantirezthe line number where the definition of the function starts. 434321d3294cSantirez</li> 434421d3294cSantirez 434521d3294cSantirez<li><b><code>lastlinedefined</code>:</b> 434621d3294cSantirezthe line number where the definition of the function ends. 434721d3294cSantirez</li> 434821d3294cSantirez 434921d3294cSantirez<li><b><code>what</code>:</b> 435021d3294cSantirezthe string <code>"Lua"</code> if the function is a Lua function, 435121d3294cSantirez<code>"C"</code> if it is a C function, 435221d3294cSantirez<code>"main"</code> if it is the main part of a chunk, 435321d3294cSantirezand <code>"tail"</code> if it was a function that did a tail call. 435421d3294cSantirezIn the latter case, 435521d3294cSantirezLua has no other information about the function. 435621d3294cSantirez</li> 435721d3294cSantirez 435821d3294cSantirez<li><b><code>currentline</code>:</b> 435921d3294cSantirezthe current line where the given function is executing. 436021d3294cSantirezWhen no line information is available, 436121d3294cSantirez<code>currentline</code> is set to -1. 436221d3294cSantirez</li> 436321d3294cSantirez 436421d3294cSantirez<li><b><code>name</code>:</b> 436521d3294cSantireza reasonable name for the given function. 436621d3294cSantirezBecause functions in Lua are first-class values, 436721d3294cSantirezthey do not have a fixed name: 436821d3294cSantirezsome functions can be the value of multiple global variables, 436921d3294cSantirezwhile others can be stored only in a table field. 437021d3294cSantirezThe <code>lua_getinfo</code> function checks how the function was 437121d3294cSantirezcalled to find a suitable name. 437221d3294cSantirezIf it cannot find a name, 437321d3294cSantirezthen <code>name</code> is set to <code>NULL</code>. 437421d3294cSantirez</li> 437521d3294cSantirez 437621d3294cSantirez<li><b><code>namewhat</code>:</b> 437721d3294cSantirezexplains the <code>name</code> field. 437821d3294cSantirezThe value of <code>namewhat</code> can be 437921d3294cSantirez<code>"global"</code>, <code>"local"</code>, <code>"method"</code>, 438021d3294cSantirez<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), 438121d3294cSantirezaccording to how the function was called. 438221d3294cSantirez(Lua uses the empty string when no other option seems to apply.) 438321d3294cSantirez</li> 438421d3294cSantirez 438521d3294cSantirez<li><b><code>nups</code>:</b> 438621d3294cSantirezthe number of upvalues of the function. 438721d3294cSantirez</li> 438821d3294cSantirez 438921d3294cSantirez</ul> 439021d3294cSantirez 439121d3294cSantirez 439221d3294cSantirez 439321d3294cSantirez 439421d3294cSantirez<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> 439521d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 439621d3294cSantirez<pre>lua_Hook lua_gethook (lua_State *L);</pre> 439721d3294cSantirez 439821d3294cSantirez<p> 439921d3294cSantirezReturns the current hook function. 440021d3294cSantirez 440121d3294cSantirez 440221d3294cSantirez 440321d3294cSantirez 440421d3294cSantirez 440521d3294cSantirez<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> 440621d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 440721d3294cSantirez<pre>int lua_gethookcount (lua_State *L);</pre> 440821d3294cSantirez 440921d3294cSantirez<p> 441021d3294cSantirezReturns the current hook count. 441121d3294cSantirez 441221d3294cSantirez 441321d3294cSantirez 441421d3294cSantirez 441521d3294cSantirez 441621d3294cSantirez<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> 441721d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 441821d3294cSantirez<pre>int lua_gethookmask (lua_State *L);</pre> 441921d3294cSantirez 442021d3294cSantirez<p> 442121d3294cSantirezReturns the current hook mask. 442221d3294cSantirez 442321d3294cSantirez 442421d3294cSantirez 442521d3294cSantirez 442621d3294cSantirez 442721d3294cSantirez<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> 442821d3294cSantirez<span class="apii">[-(0|1), +(0|1|2), <em>m</em>]</span> 442921d3294cSantirez<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> 443021d3294cSantirez 443121d3294cSantirez<p> 443221d3294cSantirezReturns information about a specific function or function invocation. 443321d3294cSantirez 443421d3294cSantirez 443521d3294cSantirez<p> 443621d3294cSantirezTo get information about a function invocation, 443721d3294cSantirezthe parameter <code>ar</code> must be a valid activation record that was 443821d3294cSantirezfilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 443921d3294cSantirezgiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 444021d3294cSantirez 444121d3294cSantirez 444221d3294cSantirez<p> 444321d3294cSantirezTo get information about a function you push it onto the stack 444421d3294cSantirezand start the <code>what</code> string with the character '<code>></code>'. 444521d3294cSantirez(In that case, 444621d3294cSantirez<code>lua_getinfo</code> pops the function in the top of the stack.) 444721d3294cSantirezFor instance, to know in which line a function <code>f</code> was defined, 444821d3294cSantirezyou can write the following code: 444921d3294cSantirez 445021d3294cSantirez<pre> 445121d3294cSantirez lua_Debug ar; 445221d3294cSantirez lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* get global 'f' */ 445321d3294cSantirez lua_getinfo(L, ">S", &ar); 445421d3294cSantirez printf("%d\n", ar.linedefined); 445521d3294cSantirez</pre> 445621d3294cSantirez 445721d3294cSantirez<p> 445821d3294cSantirezEach character in the string <code>what</code> 445921d3294cSantirezselects some fields of the structure <code>ar</code> to be filled or 446021d3294cSantireza value to be pushed on the stack: 446121d3294cSantirez 446221d3294cSantirez<ul> 446321d3294cSantirez 446421d3294cSantirez<li><b>'<code>n</code>':</b> fills in the field <code>name</code> and <code>namewhat</code>; 446521d3294cSantirez</li> 446621d3294cSantirez 446721d3294cSantirez<li><b>'<code>S</code>':</b> 446821d3294cSantirezfills in the fields <code>source</code>, <code>short_src</code>, 446921d3294cSantirez<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; 447021d3294cSantirez</li> 447121d3294cSantirez 447221d3294cSantirez<li><b>'<code>l</code>':</b> fills in the field <code>currentline</code>; 447321d3294cSantirez</li> 447421d3294cSantirez 447521d3294cSantirez<li><b>'<code>u</code>':</b> fills in the field <code>nups</code>; 447621d3294cSantirez</li> 447721d3294cSantirez 447821d3294cSantirez<li><b>'<code>f</code>':</b> 447921d3294cSantirezpushes onto the stack the function that is 448021d3294cSantirezrunning at the given level; 448121d3294cSantirez</li> 448221d3294cSantirez 448321d3294cSantirez<li><b>'<code>L</code>':</b> 448421d3294cSantirezpushes onto the stack a table whose indices are the 448521d3294cSantireznumbers of the lines that are valid on the function. 448621d3294cSantirez(A <em>valid line</em> is a line with some associated code, 448721d3294cSantirezthat is, a line where you can put a break point. 448821d3294cSantirezNon-valid lines include empty lines and comments.) 448921d3294cSantirez</li> 449021d3294cSantirez 449121d3294cSantirez</ul> 449221d3294cSantirez 449321d3294cSantirez<p> 449421d3294cSantirezThis function returns 0 on error 449521d3294cSantirez(for instance, an invalid option in <code>what</code>). 449621d3294cSantirez 449721d3294cSantirez 449821d3294cSantirez 449921d3294cSantirez 450021d3294cSantirez 450121d3294cSantirez<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> 450221d3294cSantirez<span class="apii">[-0, +(0|1), <em>-</em>]</span> 450321d3294cSantirez<pre>const char *lua_getlocal (lua_State *L, lua_Debug *ar, int n);</pre> 450421d3294cSantirez 450521d3294cSantirez<p> 450621d3294cSantirezGets information about a local variable of a given activation record. 450721d3294cSantirezThe parameter <code>ar</code> must be a valid activation record that was 450821d3294cSantirezfilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 450921d3294cSantirezgiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 451021d3294cSantirezThe index <code>n</code> selects which local variable to inspect 451121d3294cSantirez(1 is the first parameter or active local variable, and so on, 451221d3294cSantirezuntil the last active local variable). 451321d3294cSantirez<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack 451421d3294cSantirezand returns its name. 451521d3294cSantirez 451621d3294cSantirez 451721d3294cSantirez<p> 451821d3294cSantirezVariable names starting with '<code>(</code>' (open parentheses) 451921d3294cSantirezrepresent internal variables 452021d3294cSantirez(loop control variables, temporaries, and C function locals). 452121d3294cSantirez 452221d3294cSantirez 452321d3294cSantirez<p> 452421d3294cSantirezReturns <code>NULL</code> (and pushes nothing) 452521d3294cSantirezwhen the index is greater than 452621d3294cSantirezthe number of active local variables. 452721d3294cSantirez 452821d3294cSantirez 452921d3294cSantirez 453021d3294cSantirez 453121d3294cSantirez 453221d3294cSantirez<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> 453321d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 453421d3294cSantirez<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> 453521d3294cSantirez 453621d3294cSantirez<p> 453721d3294cSantirezGet information about the interpreter runtime stack. 453821d3294cSantirez 453921d3294cSantirez 454021d3294cSantirez<p> 454121d3294cSantirezThis function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with 454221d3294cSantirezan identification of the <em>activation record</em> 454321d3294cSantirezof the function executing at a given level. 454421d3294cSantirezLevel 0 is the current running function, 454521d3294cSantirezwhereas level <em>n+1</em> is the function that has called level <em>n</em>. 454621d3294cSantirezWhen there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1; 454721d3294cSantirezwhen called with a level greater than the stack depth, 454821d3294cSantirezit returns 0. 454921d3294cSantirez 455021d3294cSantirez 455121d3294cSantirez 455221d3294cSantirez 455321d3294cSantirez 455421d3294cSantirez<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> 455521d3294cSantirez<span class="apii">[-0, +(0|1), <em>-</em>]</span> 455621d3294cSantirez<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> 455721d3294cSantirez 455821d3294cSantirez<p> 455921d3294cSantirezGets information about a closure's upvalue. 456021d3294cSantirez(For Lua functions, 456121d3294cSantirezupvalues are the external local variables that the function uses, 456221d3294cSantirezand that are consequently included in its closure.) 456321d3294cSantirez<a href="#lua_getupvalue"><code>lua_getupvalue</code></a> gets the index <code>n</code> of an upvalue, 456421d3294cSantirezpushes the upvalue's value onto the stack, 456521d3294cSantirezand returns its name. 456621d3294cSantirez<code>funcindex</code> points to the closure in the stack. 456721d3294cSantirez(Upvalues have no particular order, 456821d3294cSantirezas they are active through the whole function. 456921d3294cSantirezSo, they are numbered in an arbitrary order.) 457021d3294cSantirez 457121d3294cSantirez 457221d3294cSantirez<p> 457321d3294cSantirezReturns <code>NULL</code> (and pushes nothing) 457421d3294cSantirezwhen the index is greater than the number of upvalues. 457521d3294cSantirezFor C functions, this function uses the empty string <code>""</code> 457621d3294cSantirezas a name for all upvalues. 457721d3294cSantirez 457821d3294cSantirez 457921d3294cSantirez 458021d3294cSantirez 458121d3294cSantirez 458221d3294cSantirez<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> 458321d3294cSantirez<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> 458421d3294cSantirez 458521d3294cSantirez<p> 458621d3294cSantirezType for debugging hook functions. 458721d3294cSantirez 458821d3294cSantirez 458921d3294cSantirez<p> 459021d3294cSantirezWhenever a hook is called, its <code>ar</code> argument has its field 459121d3294cSantirez<code>event</code> set to the specific event that triggered the hook. 459221d3294cSantirezLua identifies these events with the following constants: 459321d3294cSantirez<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, 459421d3294cSantirez<a name="pdf-LUA_HOOKTAILRET"><code>LUA_HOOKTAILRET</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, 459521d3294cSantirezand <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. 459621d3294cSantirezMoreover, for line events, the field <code>currentline</code> is also set. 459721d3294cSantirezTo get the value of any other field in <code>ar</code>, 459821d3294cSantirezthe hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 459921d3294cSantirezFor return events, <code>event</code> can be <code>LUA_HOOKRET</code>, 460021d3294cSantirezthe normal value, or <code>LUA_HOOKTAILRET</code>. 460121d3294cSantirezIn the latter case, Lua is simulating a return from 460221d3294cSantireza function that did a tail call; 460321d3294cSantirezin this case, it is useless to call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 460421d3294cSantirez 460521d3294cSantirez 460621d3294cSantirez<p> 460721d3294cSantirezWhile Lua is running a hook, it disables other calls to hooks. 460821d3294cSantirezTherefore, if a hook calls back Lua to execute a function or a chunk, 460921d3294cSantirezthis execution occurs without any calls to hooks. 461021d3294cSantirez 461121d3294cSantirez 461221d3294cSantirez 461321d3294cSantirez 461421d3294cSantirez 461521d3294cSantirez<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> 461621d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 461721d3294cSantirez<pre>int lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> 461821d3294cSantirez 461921d3294cSantirez<p> 462021d3294cSantirezSets the debugging hook function. 462121d3294cSantirez 462221d3294cSantirez 462321d3294cSantirez<p> 462421d3294cSantirezArgument <code>f</code> is the hook function. 462521d3294cSantirez<code>mask</code> specifies on which events the hook will be called: 462621d3294cSantirezit is formed by a bitwise or of the constants 462721d3294cSantirez<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, 462821d3294cSantirez<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, 462921d3294cSantirez<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, 463021d3294cSantirezand <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. 463121d3294cSantirezThe <code>count</code> argument is only meaningful when the mask 463221d3294cSantirezincludes <code>LUA_MASKCOUNT</code>. 463321d3294cSantirezFor each event, the hook is called as explained below: 463421d3294cSantirez 463521d3294cSantirez<ul> 463621d3294cSantirez 463721d3294cSantirez<li><b>The call hook:</b> is called when the interpreter calls a function. 463821d3294cSantirezThe hook is called just after Lua enters the new function, 463921d3294cSantirezbefore the function gets its arguments. 464021d3294cSantirez</li> 464121d3294cSantirez 464221d3294cSantirez<li><b>The return hook:</b> is called when the interpreter returns from a function. 464321d3294cSantirezThe hook is called just before Lua leaves the function. 464421d3294cSantirezYou have no access to the values to be returned by the function. 464521d3294cSantirez</li> 464621d3294cSantirez 464721d3294cSantirez<li><b>The line hook:</b> is called when the interpreter is about to 464821d3294cSantirezstart the execution of a new line of code, 464921d3294cSantirezor when it jumps back in the code (even to the same line). 465021d3294cSantirez(This event only happens while Lua is executing a Lua function.) 465121d3294cSantirez</li> 465221d3294cSantirez 465321d3294cSantirez<li><b>The count hook:</b> is called after the interpreter executes every 465421d3294cSantirez<code>count</code> instructions. 465521d3294cSantirez(This event only happens while Lua is executing a Lua function.) 465621d3294cSantirez</li> 465721d3294cSantirez 465821d3294cSantirez</ul> 465921d3294cSantirez 466021d3294cSantirez<p> 466121d3294cSantirezA hook is disabled by setting <code>mask</code> to zero. 466221d3294cSantirez 466321d3294cSantirez 466421d3294cSantirez 466521d3294cSantirez 466621d3294cSantirez 466721d3294cSantirez<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> 466821d3294cSantirez<span class="apii">[-(0|1), +0, <em>-</em>]</span> 466921d3294cSantirez<pre>const char *lua_setlocal (lua_State *L, lua_Debug *ar, int n);</pre> 467021d3294cSantirez 467121d3294cSantirez<p> 467221d3294cSantirezSets the value of a local variable of a given activation record. 467321d3294cSantirezParameters <code>ar</code> and <code>n</code> are as in <a href="#lua_getlocal"><code>lua_getlocal</code></a> 467421d3294cSantirez(see <a href="#lua_getlocal"><code>lua_getlocal</code></a>). 467521d3294cSantirez<a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack 467621d3294cSantirezto the variable and returns its name. 467721d3294cSantirezIt also pops the value from the stack. 467821d3294cSantirez 467921d3294cSantirez 468021d3294cSantirez<p> 468121d3294cSantirezReturns <code>NULL</code> (and pops nothing) 468221d3294cSantirezwhen the index is greater than 468321d3294cSantirezthe number of active local variables. 468421d3294cSantirez 468521d3294cSantirez 468621d3294cSantirez 468721d3294cSantirez 468821d3294cSantirez 468921d3294cSantirez<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> 469021d3294cSantirez<span class="apii">[-(0|1), +0, <em>-</em>]</span> 469121d3294cSantirez<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> 469221d3294cSantirez 469321d3294cSantirez<p> 469421d3294cSantirezSets the value of a closure's upvalue. 469521d3294cSantirezIt assigns the value at the top of the stack 469621d3294cSantirezto the upvalue and returns its name. 469721d3294cSantirezIt also pops the value from the stack. 469821d3294cSantirezParameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> 469921d3294cSantirez(see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>). 470021d3294cSantirez 470121d3294cSantirez 470221d3294cSantirez<p> 470321d3294cSantirezReturns <code>NULL</code> (and pops nothing) 470421d3294cSantirezwhen the index is greater than the number of upvalues. 470521d3294cSantirez 470621d3294cSantirez 470721d3294cSantirez 470821d3294cSantirez 470921d3294cSantirez 471021d3294cSantirez 471121d3294cSantirez 471221d3294cSantirez<h1>4 - <a name="4">The Auxiliary Library</a></h1> 471321d3294cSantirez 471421d3294cSantirez<p> 471521d3294cSantirez 471621d3294cSantirezThe <em>auxiliary library</em> provides several convenient functions 471721d3294cSantirezto interface C with Lua. 471821d3294cSantirezWhile the basic API provides the primitive functions for all 471921d3294cSantirezinteractions between C and Lua, 472021d3294cSantirezthe auxiliary library provides higher-level functions for some 472121d3294cSantirezcommon tasks. 472221d3294cSantirez 472321d3294cSantirez 472421d3294cSantirez<p> 472521d3294cSantirezAll functions from the auxiliary library 472621d3294cSantirezare defined in header file <code>lauxlib.h</code> and 472721d3294cSantirezhave a prefix <code>luaL_</code>. 472821d3294cSantirez 472921d3294cSantirez 473021d3294cSantirez<p> 473121d3294cSantirezAll functions in the auxiliary library are built on 473221d3294cSantireztop of the basic API, 473321d3294cSantirezand so they provide nothing that cannot be done with this API. 473421d3294cSantirez 473521d3294cSantirez 473621d3294cSantirez<p> 473721d3294cSantirezSeveral functions in the auxiliary library are used to 473821d3294cSantirezcheck C function arguments. 473921d3294cSantirezTheir names are always <code>luaL_check*</code> or <code>luaL_opt*</code>. 474021d3294cSantirezAll of these functions throw an error if the check is not satisfied. 474121d3294cSantirezBecause the error message is formatted for arguments 474221d3294cSantirez(e.g., "<code>bad argument #1</code>"), 474321d3294cSantirezyou should not use these functions for other stack values. 474421d3294cSantirez 474521d3294cSantirez 474621d3294cSantirez 474721d3294cSantirez<h2>4.1 - <a name="4.1">Functions and Types</a></h2> 474821d3294cSantirez 474921d3294cSantirez<p> 475021d3294cSantirezHere we list all functions and types from the auxiliary library 475121d3294cSantirezin alphabetical order. 475221d3294cSantirez 475321d3294cSantirez 475421d3294cSantirez 475521d3294cSantirez<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> 475621d3294cSantirez<span class="apii">[-0, +0, <em>m</em>]</span> 475721d3294cSantirez<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> 475821d3294cSantirez 475921d3294cSantirez<p> 476021d3294cSantirezAdds the character <code>c</code> to the buffer <code>B</code> 476121d3294cSantirez(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 476221d3294cSantirez 476321d3294cSantirez 476421d3294cSantirez 476521d3294cSantirez 476621d3294cSantirez 476721d3294cSantirez<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> 476821d3294cSantirez<span class="apii">[-0, +0, <em>m</em>]</span> 476921d3294cSantirez<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> 477021d3294cSantirez 477121d3294cSantirez<p> 477221d3294cSantirezAdds the string pointed to by <code>s</code> with length <code>l</code> to 477321d3294cSantirezthe buffer <code>B</code> 477421d3294cSantirez(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 477521d3294cSantirezThe string may contain embedded zeros. 477621d3294cSantirez 477721d3294cSantirez 477821d3294cSantirez 477921d3294cSantirez 478021d3294cSantirez 478121d3294cSantirez<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> 478221d3294cSantirez<span class="apii">[-0, +0, <em>m</em>]</span> 478321d3294cSantirez<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> 478421d3294cSantirez 478521d3294cSantirez<p> 478621d3294cSantirezAdds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>) 478721d3294cSantireza string of length <code>n</code> previously copied to the 478821d3294cSantirezbuffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). 478921d3294cSantirez 479021d3294cSantirez 479121d3294cSantirez 479221d3294cSantirez 479321d3294cSantirez 479421d3294cSantirez<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> 479521d3294cSantirez<span class="apii">[-0, +0, <em>m</em>]</span> 479621d3294cSantirez<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> 479721d3294cSantirez 479821d3294cSantirez<p> 479921d3294cSantirezAdds the zero-terminated string pointed to by <code>s</code> 480021d3294cSantirezto the buffer <code>B</code> 480121d3294cSantirez(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 480221d3294cSantirezThe string may not contain embedded zeros. 480321d3294cSantirez 480421d3294cSantirez 480521d3294cSantirez 480621d3294cSantirez 480721d3294cSantirez 480821d3294cSantirez<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> 480921d3294cSantirez<span class="apii">[-1, +0, <em>m</em>]</span> 481021d3294cSantirez<pre>void luaL_addvalue (luaL_Buffer *B);</pre> 481121d3294cSantirez 481221d3294cSantirez<p> 481321d3294cSantirezAdds the value at the top of the stack 481421d3294cSantirezto the buffer <code>B</code> 481521d3294cSantirez(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 481621d3294cSantirezPops the value. 481721d3294cSantirez 481821d3294cSantirez 481921d3294cSantirez<p> 482021d3294cSantirezThis is the only function on string buffers that can (and must) 482121d3294cSantirezbe called with an extra element on the stack, 482221d3294cSantirezwhich is the value to be added to the buffer. 482321d3294cSantirez 482421d3294cSantirez 482521d3294cSantirez 482621d3294cSantirez 482721d3294cSantirez 482821d3294cSantirez<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> 482921d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 483021d3294cSantirez<pre>void luaL_argcheck (lua_State *L, 483121d3294cSantirez int cond, 483221d3294cSantirez int narg, 483321d3294cSantirez const char *extramsg);</pre> 483421d3294cSantirez 483521d3294cSantirez<p> 483621d3294cSantirezChecks whether <code>cond</code> is true. 483721d3294cSantirezIf not, raises an error with the following message, 483821d3294cSantirezwhere <code>func</code> is retrieved from the call stack: 483921d3294cSantirez 484021d3294cSantirez<pre> 484121d3294cSantirez bad argument #<narg> to <func> (<extramsg>) 484221d3294cSantirez</pre> 484321d3294cSantirez 484421d3294cSantirez 484521d3294cSantirez 484621d3294cSantirez 484721d3294cSantirez<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> 484821d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 484921d3294cSantirez<pre>int luaL_argerror (lua_State *L, int narg, const char *extramsg);</pre> 485021d3294cSantirez 485121d3294cSantirez<p> 485221d3294cSantirezRaises an error with the following message, 485321d3294cSantirezwhere <code>func</code> is retrieved from the call stack: 485421d3294cSantirez 485521d3294cSantirez<pre> 485621d3294cSantirez bad argument #<narg> to <func> (<extramsg>) 485721d3294cSantirez</pre> 485821d3294cSantirez 485921d3294cSantirez<p> 486021d3294cSantirezThis function never returns, 486121d3294cSantirezbut it is an idiom to use it in C functions 486221d3294cSantirezas <code>return luaL_argerror(<em>args</em>)</code>. 486321d3294cSantirez 486421d3294cSantirez 486521d3294cSantirez 486621d3294cSantirez 486721d3294cSantirez 486821d3294cSantirez<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> 486921d3294cSantirez<pre>typedef struct luaL_Buffer luaL_Buffer;</pre> 487021d3294cSantirez 487121d3294cSantirez<p> 487221d3294cSantirezType for a <em>string buffer</em>. 487321d3294cSantirez 487421d3294cSantirez 487521d3294cSantirez<p> 487621d3294cSantirezA string buffer allows C code to build Lua strings piecemeal. 487721d3294cSantirezIts pattern of use is as follows: 487821d3294cSantirez 487921d3294cSantirez<ul> 488021d3294cSantirez 488121d3294cSantirez<li>First you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 488221d3294cSantirez 488321d3294cSantirez<li>Then you initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> 488421d3294cSantirez 488521d3294cSantirez<li> 488621d3294cSantirezThen you add string pieces to the buffer calling any of 488721d3294cSantirezthe <code>luaL_add*</code> functions. 488821d3294cSantirez</li> 488921d3294cSantirez 489021d3294cSantirez<li> 489121d3294cSantirezYou finish by calling <code>luaL_pushresult(&b)</code>. 489221d3294cSantirezThis call leaves the final string on the top of the stack. 489321d3294cSantirez</li> 489421d3294cSantirez 489521d3294cSantirez</ul> 489621d3294cSantirez 489721d3294cSantirez<p> 489821d3294cSantirezDuring its normal operation, 489921d3294cSantireza string buffer uses a variable number of stack slots. 490021d3294cSantirezSo, while using a buffer, you cannot assume that you know where 490121d3294cSantirezthe top of the stack is. 490221d3294cSantirezYou can use the stack between successive calls to buffer operations 490321d3294cSantirezas long as that use is balanced; 490421d3294cSantirezthat is, 490521d3294cSantirezwhen you call a buffer operation, 490621d3294cSantirezthe stack is at the same level 490721d3294cSantirezit was immediately after the previous buffer operation. 490821d3294cSantirez(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) 490921d3294cSantirezAfter calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its 491021d3294cSantirezlevel when the buffer was initialized, 491121d3294cSantirezplus the final string on its top. 491221d3294cSantirez 491321d3294cSantirez 491421d3294cSantirez 491521d3294cSantirez 491621d3294cSantirez 491721d3294cSantirez<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> 491821d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 491921d3294cSantirez<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> 492021d3294cSantirez 492121d3294cSantirez<p> 492221d3294cSantirezInitializes a buffer <code>B</code>. 492321d3294cSantirezThis function does not allocate any space; 492421d3294cSantirezthe buffer must be declared as a variable 492521d3294cSantirez(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 492621d3294cSantirez 492721d3294cSantirez 492821d3294cSantirez 492921d3294cSantirez 493021d3294cSantirez 493121d3294cSantirez<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> 493221d3294cSantirez<span class="apii">[-0, +(0|1), <em>e</em>]</span> 493321d3294cSantirez<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> 493421d3294cSantirez 493521d3294cSantirez<p> 493621d3294cSantirezCalls a metamethod. 493721d3294cSantirez 493821d3294cSantirez 493921d3294cSantirez<p> 494021d3294cSantirezIf the object at index <code>obj</code> has a metatable and this 494121d3294cSantirezmetatable has a field <code>e</code>, 494221d3294cSantirezthis function calls this field and passes the object as its only argument. 494321d3294cSantirezIn this case this function returns 1 and pushes onto the 494421d3294cSantirezstack the value returned by the call. 494521d3294cSantirezIf there is no metatable or no metamethod, 494621d3294cSantirezthis function returns 0 (without pushing any value on the stack). 494721d3294cSantirez 494821d3294cSantirez 494921d3294cSantirez 495021d3294cSantirez 495121d3294cSantirez 495221d3294cSantirez<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> 495321d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 495421d3294cSantirez<pre>void luaL_checkany (lua_State *L, int narg);</pre> 495521d3294cSantirez 495621d3294cSantirez<p> 495721d3294cSantirezChecks whether the function has an argument 495821d3294cSantirezof any type (including <b>nil</b>) at position <code>narg</code>. 495921d3294cSantirez 496021d3294cSantirez 496121d3294cSantirez 496221d3294cSantirez 496321d3294cSantirez 496421d3294cSantirez<hr><h3><a name="luaL_checkint"><code>luaL_checkint</code></a></h3><p> 496521d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 496621d3294cSantirez<pre>int luaL_checkint (lua_State *L, int narg);</pre> 496721d3294cSantirez 496821d3294cSantirez<p> 496921d3294cSantirezChecks whether the function argument <code>narg</code> is a number 497021d3294cSantirezand returns this number cast to an <code>int</code>. 497121d3294cSantirez 497221d3294cSantirez 497321d3294cSantirez 497421d3294cSantirez 497521d3294cSantirez 497621d3294cSantirez<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> 497721d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 497821d3294cSantirez<pre>lua_Integer luaL_checkinteger (lua_State *L, int narg);</pre> 497921d3294cSantirez 498021d3294cSantirez<p> 498121d3294cSantirezChecks whether the function argument <code>narg</code> is a number 498221d3294cSantirezand returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. 498321d3294cSantirez 498421d3294cSantirez 498521d3294cSantirez 498621d3294cSantirez 498721d3294cSantirez 498821d3294cSantirez<hr><h3><a name="luaL_checklong"><code>luaL_checklong</code></a></h3><p> 498921d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 499021d3294cSantirez<pre>long luaL_checklong (lua_State *L, int narg);</pre> 499121d3294cSantirez 499221d3294cSantirez<p> 499321d3294cSantirezChecks whether the function argument <code>narg</code> is a number 499421d3294cSantirezand returns this number cast to a <code>long</code>. 499521d3294cSantirez 499621d3294cSantirez 499721d3294cSantirez 499821d3294cSantirez 499921d3294cSantirez 500021d3294cSantirez<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> 500121d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 500221d3294cSantirez<pre>const char *luaL_checklstring (lua_State *L, int narg, size_t *l);</pre> 500321d3294cSantirez 500421d3294cSantirez<p> 500521d3294cSantirezChecks whether the function argument <code>narg</code> is a string 500621d3294cSantirezand returns this string; 500721d3294cSantirezif <code>l</code> is not <code>NULL</code> fills <code>*l</code> 500821d3294cSantirezwith the string's length. 500921d3294cSantirez 501021d3294cSantirez 501121d3294cSantirez<p> 501221d3294cSantirezThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 501321d3294cSantirezso all conversions and caveats of that function apply here. 501421d3294cSantirez 501521d3294cSantirez 501621d3294cSantirez 501721d3294cSantirez 501821d3294cSantirez 501921d3294cSantirez<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> 502021d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 502121d3294cSantirez<pre>lua_Number luaL_checknumber (lua_State *L, int narg);</pre> 502221d3294cSantirez 502321d3294cSantirez<p> 502421d3294cSantirezChecks whether the function argument <code>narg</code> is a number 502521d3294cSantirezand returns this number. 502621d3294cSantirez 502721d3294cSantirez 502821d3294cSantirez 502921d3294cSantirez 503021d3294cSantirez 503121d3294cSantirez<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> 503221d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 503321d3294cSantirez<pre>int luaL_checkoption (lua_State *L, 503421d3294cSantirez int narg, 503521d3294cSantirez const char *def, 503621d3294cSantirez const char *const lst[]);</pre> 503721d3294cSantirez 503821d3294cSantirez<p> 503921d3294cSantirezChecks whether the function argument <code>narg</code> is a string and 504021d3294cSantirezsearches for this string in the array <code>lst</code> 504121d3294cSantirez(which must be NULL-terminated). 504221d3294cSantirezReturns the index in the array where the string was found. 504321d3294cSantirezRaises an error if the argument is not a string or 504421d3294cSantirezif the string cannot be found. 504521d3294cSantirez 504621d3294cSantirez 504721d3294cSantirez<p> 504821d3294cSantirezIf <code>def</code> is not <code>NULL</code>, 504921d3294cSantirezthe function uses <code>def</code> as a default value when 505021d3294cSantirezthere is no argument <code>narg</code> or if this argument is <b>nil</b>. 505121d3294cSantirez 505221d3294cSantirez 505321d3294cSantirez<p> 505421d3294cSantirezThis is a useful function for mapping strings to C enums. 505521d3294cSantirez(The usual convention in Lua libraries is 505621d3294cSantirezto use strings instead of numbers to select options.) 505721d3294cSantirez 505821d3294cSantirez 505921d3294cSantirez 506021d3294cSantirez 506121d3294cSantirez 506221d3294cSantirez<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> 506321d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 506421d3294cSantirez<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> 506521d3294cSantirez 506621d3294cSantirez<p> 506721d3294cSantirezGrows the stack size to <code>top + sz</code> elements, 506821d3294cSantirezraising an error if the stack cannot grow to that size. 506921d3294cSantirez<code>msg</code> is an additional text to go into the error message. 507021d3294cSantirez 507121d3294cSantirez 507221d3294cSantirez 507321d3294cSantirez 507421d3294cSantirez 507521d3294cSantirez<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> 507621d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 507721d3294cSantirez<pre>const char *luaL_checkstring (lua_State *L, int narg);</pre> 507821d3294cSantirez 507921d3294cSantirez<p> 508021d3294cSantirezChecks whether the function argument <code>narg</code> is a string 508121d3294cSantirezand returns this string. 508221d3294cSantirez 508321d3294cSantirez 508421d3294cSantirez<p> 508521d3294cSantirezThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 508621d3294cSantirezso all conversions and caveats of that function apply here. 508721d3294cSantirez 508821d3294cSantirez 508921d3294cSantirez 509021d3294cSantirez 509121d3294cSantirez 509221d3294cSantirez<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> 509321d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 509421d3294cSantirez<pre>void luaL_checktype (lua_State *L, int narg, int t);</pre> 509521d3294cSantirez 509621d3294cSantirez<p> 509721d3294cSantirezChecks whether the function argument <code>narg</code> has type <code>t</code>. 509821d3294cSantirezSee <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. 509921d3294cSantirez 510021d3294cSantirez 510121d3294cSantirez 510221d3294cSantirez 510321d3294cSantirez 510421d3294cSantirez<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> 510521d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 510621d3294cSantirez<pre>void *luaL_checkudata (lua_State *L, int narg, const char *tname);</pre> 510721d3294cSantirez 510821d3294cSantirez<p> 510921d3294cSantirezChecks whether the function argument <code>narg</code> is a userdata 511021d3294cSantirezof the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 511121d3294cSantirez 511221d3294cSantirez 511321d3294cSantirez 511421d3294cSantirez 511521d3294cSantirez 511621d3294cSantirez<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> 511721d3294cSantirez<span class="apii">[-0, +?, <em>m</em>]</span> 511821d3294cSantirez<pre>int luaL_dofile (lua_State *L, const char *filename);</pre> 511921d3294cSantirez 512021d3294cSantirez<p> 512121d3294cSantirezLoads and runs the given file. 512221d3294cSantirezIt is defined as the following macro: 512321d3294cSantirez 512421d3294cSantirez<pre> 512521d3294cSantirez (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) 512621d3294cSantirez</pre><p> 512721d3294cSantirezIt returns 0 if there are no errors 512821d3294cSantirezor 1 in case of errors. 512921d3294cSantirez 513021d3294cSantirez 513121d3294cSantirez 513221d3294cSantirez 513321d3294cSantirez 513421d3294cSantirez<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> 513521d3294cSantirez<span class="apii">[-0, +?, <em>m</em>]</span> 513621d3294cSantirez<pre>int luaL_dostring (lua_State *L, const char *str);</pre> 513721d3294cSantirez 513821d3294cSantirez<p> 513921d3294cSantirezLoads and runs the given string. 514021d3294cSantirezIt is defined as the following macro: 514121d3294cSantirez 514221d3294cSantirez<pre> 514321d3294cSantirez (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) 514421d3294cSantirez</pre><p> 514521d3294cSantirezIt returns 0 if there are no errors 514621d3294cSantirezor 1 in case of errors. 514721d3294cSantirez 514821d3294cSantirez 514921d3294cSantirez 515021d3294cSantirez 515121d3294cSantirez 515221d3294cSantirez<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> 515321d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 515421d3294cSantirez<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> 515521d3294cSantirez 515621d3294cSantirez<p> 515721d3294cSantirezRaises an error. 515821d3294cSantirezThe error message format is given by <code>fmt</code> 515921d3294cSantirezplus any extra arguments, 516021d3294cSantirezfollowing the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. 516121d3294cSantirezIt also adds at the beginning of the message the file name and 516221d3294cSantirezthe line number where the error occurred, 516321d3294cSantirezif this information is available. 516421d3294cSantirez 516521d3294cSantirez 516621d3294cSantirez<p> 516721d3294cSantirezThis function never returns, 516821d3294cSantirezbut it is an idiom to use it in C functions 516921d3294cSantirezas <code>return luaL_error(<em>args</em>)</code>. 517021d3294cSantirez 517121d3294cSantirez 517221d3294cSantirez 517321d3294cSantirez 517421d3294cSantirez 517521d3294cSantirez<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> 517621d3294cSantirez<span class="apii">[-0, +(0|1), <em>m</em>]</span> 517721d3294cSantirez<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> 517821d3294cSantirez 517921d3294cSantirez<p> 518021d3294cSantirezPushes onto the stack the field <code>e</code> from the metatable 518121d3294cSantirezof the object at index <code>obj</code>. 518221d3294cSantirezIf the object does not have a metatable, 518321d3294cSantirezor if the metatable does not have this field, 518421d3294cSantirezreturns 0 and pushes nothing. 518521d3294cSantirez 518621d3294cSantirez 518721d3294cSantirez 518821d3294cSantirez 518921d3294cSantirez 519021d3294cSantirez<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> 519121d3294cSantirez<span class="apii">[-0, +1, <em>-</em>]</span> 519221d3294cSantirez<pre>void luaL_getmetatable (lua_State *L, const char *tname);</pre> 519321d3294cSantirez 519421d3294cSantirez<p> 519521d3294cSantirezPushes onto the stack the metatable associated with name <code>tname</code> 519621d3294cSantirezin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 519721d3294cSantirez 519821d3294cSantirez 519921d3294cSantirez 520021d3294cSantirez 520121d3294cSantirez 520221d3294cSantirez<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> 520321d3294cSantirez<span class="apii">[-0, +1, <em>m</em>]</span> 520421d3294cSantirez<pre>const char *luaL_gsub (lua_State *L, 520521d3294cSantirez const char *s, 520621d3294cSantirez const char *p, 520721d3294cSantirez const char *r);</pre> 520821d3294cSantirez 520921d3294cSantirez<p> 521021d3294cSantirezCreates a copy of string <code>s</code> by replacing 521121d3294cSantirezany occurrence of the string <code>p</code> 521221d3294cSantirezwith the string <code>r</code>. 521321d3294cSantirezPushes the resulting string on the stack and returns it. 521421d3294cSantirez 521521d3294cSantirez 521621d3294cSantirez 521721d3294cSantirez 521821d3294cSantirez 521921d3294cSantirez<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> 522021d3294cSantirez<span class="apii">[-0, +1, <em>m</em>]</span> 522121d3294cSantirez<pre>int luaL_loadbuffer (lua_State *L, 522221d3294cSantirez const char *buff, 522321d3294cSantirez size_t sz, 522421d3294cSantirez const char *name);</pre> 522521d3294cSantirez 522621d3294cSantirez<p> 522721d3294cSantirezLoads a buffer as a Lua chunk. 522821d3294cSantirezThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the 522921d3294cSantirezbuffer pointed to by <code>buff</code> with size <code>sz</code>. 523021d3294cSantirez 523121d3294cSantirez 523221d3294cSantirez<p> 523321d3294cSantirezThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 523421d3294cSantirez<code>name</code> is the chunk name, 523521d3294cSantirezused for debug information and error messages. 523621d3294cSantirez 523721d3294cSantirez 523821d3294cSantirez 523921d3294cSantirez 524021d3294cSantirez 524121d3294cSantirez<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> 524221d3294cSantirez<span class="apii">[-0, +1, <em>m</em>]</span> 524321d3294cSantirez<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> 524421d3294cSantirez 524521d3294cSantirez<p> 524621d3294cSantirezLoads a file as a Lua chunk. 524721d3294cSantirezThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file 524821d3294cSantireznamed <code>filename</code>. 524921d3294cSantirezIf <code>filename</code> is <code>NULL</code>, 525021d3294cSantirezthen it loads from the standard input. 525121d3294cSantirezThe first line in the file is ignored if it starts with a <code>#</code>. 525221d3294cSantirez 525321d3294cSantirez 525421d3294cSantirez<p> 525521d3294cSantirezThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, 525621d3294cSantirezbut it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> 525721d3294cSantirezif it cannot open/read the file. 525821d3294cSantirez 525921d3294cSantirez 526021d3294cSantirez<p> 526121d3294cSantirezAs <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 526221d3294cSantirezit does not run it. 526321d3294cSantirez 526421d3294cSantirez 526521d3294cSantirez 526621d3294cSantirez 526721d3294cSantirez 526821d3294cSantirez<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> 526921d3294cSantirez<span class="apii">[-0, +1, <em>m</em>]</span> 527021d3294cSantirez<pre>int luaL_loadstring (lua_State *L, const char *s);</pre> 527121d3294cSantirez 527221d3294cSantirez<p> 527321d3294cSantirezLoads a string as a Lua chunk. 527421d3294cSantirezThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in 527521d3294cSantirezthe zero-terminated string <code>s</code>. 527621d3294cSantirez 527721d3294cSantirez 527821d3294cSantirez<p> 527921d3294cSantirezThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 528021d3294cSantirez 528121d3294cSantirez 528221d3294cSantirez<p> 528321d3294cSantirezAlso as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 528421d3294cSantirezit does not run it. 528521d3294cSantirez 528621d3294cSantirez 528721d3294cSantirez 528821d3294cSantirez 528921d3294cSantirez 529021d3294cSantirez<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> 529121d3294cSantirez<span class="apii">[-0, +1, <em>m</em>]</span> 529221d3294cSantirez<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> 529321d3294cSantirez 529421d3294cSantirez<p> 529521d3294cSantirezIf the registry already has the key <code>tname</code>, 529621d3294cSantirezreturns 0. 529721d3294cSantirezOtherwise, 529821d3294cSantirezcreates a new table to be used as a metatable for userdata, 529921d3294cSantirezadds it to the registry with key <code>tname</code>, 530021d3294cSantirezand returns 1. 530121d3294cSantirez 530221d3294cSantirez 530321d3294cSantirez<p> 530421d3294cSantirezIn both cases pushes onto the stack the final value associated 530521d3294cSantirezwith <code>tname</code> in the registry. 530621d3294cSantirez 530721d3294cSantirez 530821d3294cSantirez 530921d3294cSantirez 531021d3294cSantirez 531121d3294cSantirez<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> 531221d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 531321d3294cSantirez<pre>lua_State *luaL_newstate (void);</pre> 531421d3294cSantirez 531521d3294cSantirez<p> 531621d3294cSantirezCreates a new Lua state. 531721d3294cSantirezIt calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an 531821d3294cSantirezallocator based on the standard C <code>realloc</code> function 531921d3294cSantirezand then sets a panic function (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) that prints 532021d3294cSantirezan error message to the standard error output in case of fatal 532121d3294cSantirezerrors. 532221d3294cSantirez 532321d3294cSantirez 532421d3294cSantirez<p> 532521d3294cSantirezReturns the new state, 532621d3294cSantirezor <code>NULL</code> if there is a memory allocation error. 532721d3294cSantirez 532821d3294cSantirez 532921d3294cSantirez 533021d3294cSantirez 533121d3294cSantirez 533221d3294cSantirez<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> 533321d3294cSantirez<span class="apii">[-0, +0, <em>m</em>]</span> 533421d3294cSantirez<pre>void luaL_openlibs (lua_State *L);</pre> 533521d3294cSantirez 533621d3294cSantirez<p> 533721d3294cSantirezOpens all standard Lua libraries into the given state. 533821d3294cSantirez 533921d3294cSantirez 534021d3294cSantirez 534121d3294cSantirez 534221d3294cSantirez 534321d3294cSantirez<hr><h3><a name="luaL_optint"><code>luaL_optint</code></a></h3><p> 534421d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 534521d3294cSantirez<pre>int luaL_optint (lua_State *L, int narg, int d);</pre> 534621d3294cSantirez 534721d3294cSantirez<p> 534821d3294cSantirezIf the function argument <code>narg</code> is a number, 534921d3294cSantirezreturns this number cast to an <code>int</code>. 535021d3294cSantirezIf this argument is absent or is <b>nil</b>, 535121d3294cSantirezreturns <code>d</code>. 535221d3294cSantirezOtherwise, raises an error. 535321d3294cSantirez 535421d3294cSantirez 535521d3294cSantirez 535621d3294cSantirez 535721d3294cSantirez 535821d3294cSantirez<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> 535921d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 536021d3294cSantirez<pre>lua_Integer luaL_optinteger (lua_State *L, 536121d3294cSantirez int narg, 536221d3294cSantirez lua_Integer d);</pre> 536321d3294cSantirez 536421d3294cSantirez<p> 536521d3294cSantirezIf the function argument <code>narg</code> is a number, 536621d3294cSantirezreturns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. 536721d3294cSantirezIf this argument is absent or is <b>nil</b>, 536821d3294cSantirezreturns <code>d</code>. 536921d3294cSantirezOtherwise, raises an error. 537021d3294cSantirez 537121d3294cSantirez 537221d3294cSantirez 537321d3294cSantirez 537421d3294cSantirez 537521d3294cSantirez<hr><h3><a name="luaL_optlong"><code>luaL_optlong</code></a></h3><p> 537621d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 537721d3294cSantirez<pre>long luaL_optlong (lua_State *L, int narg, long d);</pre> 537821d3294cSantirez 537921d3294cSantirez<p> 538021d3294cSantirezIf the function argument <code>narg</code> is a number, 538121d3294cSantirezreturns this number cast to a <code>long</code>. 538221d3294cSantirezIf this argument is absent or is <b>nil</b>, 538321d3294cSantirezreturns <code>d</code>. 538421d3294cSantirezOtherwise, raises an error. 538521d3294cSantirez 538621d3294cSantirez 538721d3294cSantirez 538821d3294cSantirez 538921d3294cSantirez 539021d3294cSantirez<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> 539121d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 539221d3294cSantirez<pre>const char *luaL_optlstring (lua_State *L, 539321d3294cSantirez int narg, 539421d3294cSantirez const char *d, 539521d3294cSantirez size_t *l);</pre> 539621d3294cSantirez 539721d3294cSantirez<p> 539821d3294cSantirezIf the function argument <code>narg</code> is a string, 539921d3294cSantirezreturns this string. 540021d3294cSantirezIf this argument is absent or is <b>nil</b>, 540121d3294cSantirezreturns <code>d</code>. 540221d3294cSantirezOtherwise, raises an error. 540321d3294cSantirez 540421d3294cSantirez 540521d3294cSantirez<p> 540621d3294cSantirezIf <code>l</code> is not <code>NULL</code>, 540721d3294cSantirezfills the position <code>*l</code> with the results's length. 540821d3294cSantirez 540921d3294cSantirez 541021d3294cSantirez 541121d3294cSantirez 541221d3294cSantirez 541321d3294cSantirez<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> 541421d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 541521d3294cSantirez<pre>lua_Number luaL_optnumber (lua_State *L, int narg, lua_Number d);</pre> 541621d3294cSantirez 541721d3294cSantirez<p> 541821d3294cSantirezIf the function argument <code>narg</code> is a number, 541921d3294cSantirezreturns this number. 542021d3294cSantirezIf this argument is absent or is <b>nil</b>, 542121d3294cSantirezreturns <code>d</code>. 542221d3294cSantirezOtherwise, raises an error. 542321d3294cSantirez 542421d3294cSantirez 542521d3294cSantirez 542621d3294cSantirez 542721d3294cSantirez 542821d3294cSantirez<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> 542921d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 543021d3294cSantirez<pre>const char *luaL_optstring (lua_State *L, 543121d3294cSantirez int narg, 543221d3294cSantirez const char *d);</pre> 543321d3294cSantirez 543421d3294cSantirez<p> 543521d3294cSantirezIf the function argument <code>narg</code> is a string, 543621d3294cSantirezreturns this string. 543721d3294cSantirezIf this argument is absent or is <b>nil</b>, 543821d3294cSantirezreturns <code>d</code>. 543921d3294cSantirezOtherwise, raises an error. 544021d3294cSantirez 544121d3294cSantirez 544221d3294cSantirez 544321d3294cSantirez 544421d3294cSantirez 544521d3294cSantirez<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> 544621d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 544721d3294cSantirez<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> 544821d3294cSantirez 544921d3294cSantirez<p> 545021d3294cSantirezReturns an address to a space of size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a> 545121d3294cSantirezwhere you can copy a string to be added to buffer <code>B</code> 545221d3294cSantirez(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 545321d3294cSantirezAfter copying the string into this space you must call 545421d3294cSantirez<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add 545521d3294cSantirezit to the buffer. 545621d3294cSantirez 545721d3294cSantirez 545821d3294cSantirez 545921d3294cSantirez 546021d3294cSantirez 546121d3294cSantirez<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> 546221d3294cSantirez<span class="apii">[-?, +1, <em>m</em>]</span> 546321d3294cSantirez<pre>void luaL_pushresult (luaL_Buffer *B);</pre> 546421d3294cSantirez 546521d3294cSantirez<p> 546621d3294cSantirezFinishes the use of buffer <code>B</code> leaving the final string on 546721d3294cSantirezthe top of the stack. 546821d3294cSantirez 546921d3294cSantirez 547021d3294cSantirez 547121d3294cSantirez 547221d3294cSantirez 547321d3294cSantirez<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> 547421d3294cSantirez<span class="apii">[-1, +0, <em>m</em>]</span> 547521d3294cSantirez<pre>int luaL_ref (lua_State *L, int t);</pre> 547621d3294cSantirez 547721d3294cSantirez<p> 547821d3294cSantirezCreates and returns a <em>reference</em>, 547921d3294cSantirezin the table at index <code>t</code>, 548021d3294cSantirezfor the object at the top of the stack (and pops the object). 548121d3294cSantirez 548221d3294cSantirez 548321d3294cSantirez<p> 548421d3294cSantirezA reference is a unique integer key. 548521d3294cSantirezAs long as you do not manually add integer keys into table <code>t</code>, 548621d3294cSantirez<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. 548721d3294cSantirezYou can retrieve an object referred by reference <code>r</code> 548821d3294cSantirezby calling <code>lua_rawgeti(L, t, r)</code>. 548921d3294cSantirezFunction <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object. 549021d3294cSantirez 549121d3294cSantirez 549221d3294cSantirez<p> 549321d3294cSantirezIf the object at the top of the stack is <b>nil</b>, 549421d3294cSantirez<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>. 549521d3294cSantirezThe constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different 549621d3294cSantirezfrom any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. 549721d3294cSantirez 549821d3294cSantirez 549921d3294cSantirez 550021d3294cSantirez 550121d3294cSantirez 550221d3294cSantirez<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> 550321d3294cSantirez<pre>typedef struct luaL_Reg { 550421d3294cSantirez const char *name; 550521d3294cSantirez lua_CFunction func; 550621d3294cSantirez} luaL_Reg;</pre> 550721d3294cSantirez 550821d3294cSantirez<p> 550921d3294cSantirezType for arrays of functions to be registered by 551021d3294cSantirez<a href="#luaL_register"><code>luaL_register</code></a>. 551121d3294cSantirez<code>name</code> is the function name and <code>func</code> is a pointer to 551221d3294cSantirezthe function. 551321d3294cSantirezAny array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with an sentinel entry 551421d3294cSantirezin which both <code>name</code> and <code>func</code> are <code>NULL</code>. 551521d3294cSantirez 551621d3294cSantirez 551721d3294cSantirez 551821d3294cSantirez 551921d3294cSantirez 552021d3294cSantirez<hr><h3><a name="luaL_register"><code>luaL_register</code></a></h3><p> 552121d3294cSantirez<span class="apii">[-(0|1), +1, <em>m</em>]</span> 552221d3294cSantirez<pre>void luaL_register (lua_State *L, 552321d3294cSantirez const char *libname, 552421d3294cSantirez const luaL_Reg *l);</pre> 552521d3294cSantirez 552621d3294cSantirez<p> 552721d3294cSantirezOpens a library. 552821d3294cSantirez 552921d3294cSantirez 553021d3294cSantirez<p> 553121d3294cSantirezWhen called with <code>libname</code> equal to <code>NULL</code>, 553221d3294cSantirezit simply registers all functions in the list <code>l</code> 553321d3294cSantirez(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack. 553421d3294cSantirez 553521d3294cSantirez 553621d3294cSantirez<p> 553721d3294cSantirezWhen called with a non-null <code>libname</code>, 553821d3294cSantirez<code>luaL_register</code> creates a new table <code>t</code>, 553921d3294cSantirezsets it as the value of the global variable <code>libname</code>, 554021d3294cSantirezsets it as the value of <code>package.loaded[libname]</code>, 554121d3294cSantirezand registers on it all functions in the list <code>l</code>. 554221d3294cSantirezIf there is a table in <code>package.loaded[libname]</code> or in 554321d3294cSantirezvariable <code>libname</code>, 554421d3294cSantirezreuses this table instead of creating a new one. 554521d3294cSantirez 554621d3294cSantirez 554721d3294cSantirez<p> 554821d3294cSantirezIn any case the function leaves the table 554921d3294cSantirezon the top of the stack. 555021d3294cSantirez 555121d3294cSantirez 555221d3294cSantirez 555321d3294cSantirez 555421d3294cSantirez 555521d3294cSantirez<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> 555621d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 555721d3294cSantirez<pre>const char *luaL_typename (lua_State *L, int index);</pre> 555821d3294cSantirez 555921d3294cSantirez<p> 556021d3294cSantirezReturns the name of the type of the value at the given index. 556121d3294cSantirez 556221d3294cSantirez 556321d3294cSantirez 556421d3294cSantirez 556521d3294cSantirez 556621d3294cSantirez<hr><h3><a name="luaL_typerror"><code>luaL_typerror</code></a></h3><p> 556721d3294cSantirez<span class="apii">[-0, +0, <em>v</em>]</span> 556821d3294cSantirez<pre>int luaL_typerror (lua_State *L, int narg, const char *tname);</pre> 556921d3294cSantirez 557021d3294cSantirez<p> 557121d3294cSantirezGenerates an error with a message like the following: 557221d3294cSantirez 557321d3294cSantirez<pre> 557421d3294cSantirez <em>location</em>: bad argument <em>narg</em> to '<em>func</em>' (<em>tname</em> expected, got <em>rt</em>) 557521d3294cSantirez</pre><p> 557621d3294cSantirezwhere <code><em>location</em></code> is produced by <a href="#luaL_where"><code>luaL_where</code></a>, 557721d3294cSantirez<code><em>func</em></code> is the name of the current function, 557821d3294cSantirezand <code><em>rt</em></code> is the type name of the actual argument. 557921d3294cSantirez 558021d3294cSantirez 558121d3294cSantirez 558221d3294cSantirez 558321d3294cSantirez 558421d3294cSantirez<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> 558521d3294cSantirez<span class="apii">[-0, +0, <em>-</em>]</span> 558621d3294cSantirez<pre>void luaL_unref (lua_State *L, int t, int ref);</pre> 558721d3294cSantirez 558821d3294cSantirez<p> 558921d3294cSantirezReleases reference <code>ref</code> from the table at index <code>t</code> 559021d3294cSantirez(see <a href="#luaL_ref"><code>luaL_ref</code></a>). 559121d3294cSantirezThe entry is removed from the table, 559221d3294cSantirezso that the referred object can be collected. 559321d3294cSantirezThe reference <code>ref</code> is also freed to be used again. 559421d3294cSantirez 559521d3294cSantirez 559621d3294cSantirez<p> 559721d3294cSantirezIf <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>, 559821d3294cSantirez<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. 559921d3294cSantirez 560021d3294cSantirez 560121d3294cSantirez 560221d3294cSantirez 560321d3294cSantirez 560421d3294cSantirez<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> 560521d3294cSantirez<span class="apii">[-0, +1, <em>m</em>]</span> 560621d3294cSantirez<pre>void luaL_where (lua_State *L, int lvl);</pre> 560721d3294cSantirez 560821d3294cSantirez<p> 560921d3294cSantirezPushes onto the stack a string identifying the current position 561021d3294cSantirezof the control at level <code>lvl</code> in the call stack. 561121d3294cSantirezTypically this string has the following format: 561221d3294cSantirez 561321d3294cSantirez<pre> 561421d3294cSantirez <em>chunkname</em>:<em>currentline</em>: 561521d3294cSantirez</pre><p> 561621d3294cSantirezLevel 0 is the running function, 561721d3294cSantirezlevel 1 is the function that called the running function, 561821d3294cSantirezetc. 561921d3294cSantirez 562021d3294cSantirez 562121d3294cSantirez<p> 562221d3294cSantirezThis function is used to build a prefix for error messages. 562321d3294cSantirez 562421d3294cSantirez 562521d3294cSantirez 562621d3294cSantirez 562721d3294cSantirez 562821d3294cSantirez 562921d3294cSantirez 563021d3294cSantirez<h1>5 - <a name="5">Standard Libraries</a></h1> 563121d3294cSantirez 563221d3294cSantirez<p> 563321d3294cSantirezThe standard Lua libraries provide useful functions 563421d3294cSantirezthat are implemented directly through the C API. 563521d3294cSantirezSome of these functions provide essential services to the language 563621d3294cSantirez(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); 563721d3294cSantirezothers provide access to "outside" services (e.g., I/O); 563821d3294cSantirezand others could be implemented in Lua itself, 563921d3294cSantirezbut are quite useful or have critical performance requirements that 564021d3294cSantirezdeserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). 564121d3294cSantirez 564221d3294cSantirez 564321d3294cSantirez<p> 564421d3294cSantirezAll libraries are implemented through the official C API 564521d3294cSantirezand are provided as separate C modules. 564621d3294cSantirezCurrently, Lua has the following standard libraries: 564721d3294cSantirez 564821d3294cSantirez<ul> 564921d3294cSantirez 5650*214adc50Santirez<li>basic library, which includes the coroutine sub-library;</li> 565121d3294cSantirez 565221d3294cSantirez<li>package library;</li> 565321d3294cSantirez 565421d3294cSantirez<li>string manipulation;</li> 565521d3294cSantirez 565621d3294cSantirez<li>table manipulation;</li> 565721d3294cSantirez 565821d3294cSantirez<li>mathematical functions (sin, log, etc.);</li> 565921d3294cSantirez 566021d3294cSantirez<li>input and output;</li> 566121d3294cSantirez 566221d3294cSantirez<li>operating system facilities;</li> 566321d3294cSantirez 566421d3294cSantirez<li>debug facilities.</li> 566521d3294cSantirez 566621d3294cSantirez</ul><p> 566721d3294cSantirezExcept for the basic and package libraries, 566821d3294cSantirezeach library provides all its functions as fields of a global table 566921d3294cSantirezor as methods of its objects. 567021d3294cSantirez 567121d3294cSantirez 567221d3294cSantirez<p> 567321d3294cSantirezTo have access to these libraries, 567421d3294cSantirezthe C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, 567521d3294cSantirezwhich opens all standard libraries. 567621d3294cSantirezAlternatively, 567721d3294cSantirezit can open them individually by calling 567821d3294cSantirez<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), 567921d3294cSantirez<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), 568021d3294cSantirez<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), 568121d3294cSantirez<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), 568221d3294cSantirez<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), 568321d3294cSantirez<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), 568421d3294cSantirez<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the Operating System library), 568521d3294cSantirezand <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). 568621d3294cSantirezThese functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a> 568721d3294cSantirezand should not be called directly: 568821d3294cSantirezyou must call them like any other Lua C function, 568921d3294cSantireze.g., by using <a href="#lua_call"><code>lua_call</code></a>. 569021d3294cSantirez 569121d3294cSantirez 569221d3294cSantirez 569321d3294cSantirez<h2>5.1 - <a name="5.1">Basic Functions</a></h2> 569421d3294cSantirez 569521d3294cSantirez<p> 569621d3294cSantirezThe basic library provides some core functions to Lua. 569721d3294cSantirezIf you do not include this library in your application, 569821d3294cSantirezyou should check carefully whether you need to provide 569921d3294cSantirezimplementations for some of its facilities. 570021d3294cSantirez 570121d3294cSantirez 570221d3294cSantirez<p> 570321d3294cSantirez<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> 570421d3294cSantirezIssues an error when 570521d3294cSantirezthe value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); 570621d3294cSantirezotherwise, returns all its arguments. 570721d3294cSantirez<code>message</code> is an error message; 570821d3294cSantirezwhen absent, it defaults to "assertion failed!" 570921d3294cSantirez 571021d3294cSantirez 571121d3294cSantirez 571221d3294cSantirez 571321d3294cSantirez<p> 5714*214adc50Santirez<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3> 571521d3294cSantirez 571621d3294cSantirez 571721d3294cSantirez<p> 571821d3294cSantirezThis function is a generic interface to the garbage collector. 571921d3294cSantirezIt performs different functions according to its first argument, <code>opt</code>: 572021d3294cSantirez 572121d3294cSantirez<ul> 572221d3294cSantirez 5723*214adc50Santirez<li><b>"collect":</b> 5724*214adc50Santirezperforms a full garbage-collection cycle. 5725*214adc50SantirezThis is the default option. 5726*214adc50Santirez</li> 5727*214adc50Santirez 572821d3294cSantirez<li><b>"stop":</b> 572921d3294cSantirezstops the garbage collector. 573021d3294cSantirez</li> 573121d3294cSantirez 573221d3294cSantirez<li><b>"restart":</b> 573321d3294cSantirezrestarts the garbage collector. 573421d3294cSantirez</li> 573521d3294cSantirez 573621d3294cSantirez<li><b>"count":</b> 573721d3294cSantirezreturns the total memory in use by Lua (in Kbytes). 573821d3294cSantirez</li> 573921d3294cSantirez 574021d3294cSantirez<li><b>"step":</b> 574121d3294cSantirezperforms a garbage-collection step. 574221d3294cSantirezThe step "size" is controlled by <code>arg</code> 574321d3294cSantirez(larger values mean more steps) in a non-specified way. 574421d3294cSantirezIf you want to control the step size 574521d3294cSantirezyou must experimentally tune the value of <code>arg</code>. 574621d3294cSantirezReturns <b>true</b> if the step finished a collection cycle. 574721d3294cSantirez</li> 574821d3294cSantirez 574921d3294cSantirez<li><b>"setpause":</b> 575021d3294cSantirezsets <code>arg</code> as the new value for the <em>pause</em> of 575121d3294cSantirezthe collector (see <a href="#2.10">§2.10</a>). 575221d3294cSantirezReturns the previous value for <em>pause</em>. 575321d3294cSantirez</li> 575421d3294cSantirez 575521d3294cSantirez<li><b>"setstepmul":</b> 575621d3294cSantirezsets <code>arg</code> as the new value for the <em>step multiplier</em> of 575721d3294cSantirezthe collector (see <a href="#2.10">§2.10</a>). 575821d3294cSantirezReturns the previous value for <em>step</em>. 575921d3294cSantirez</li> 576021d3294cSantirez 576121d3294cSantirez</ul> 576221d3294cSantirez 576321d3294cSantirez 576421d3294cSantirez 576521d3294cSantirez<p> 5766*214adc50Santirez<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> 576721d3294cSantirezOpens the named file and executes its contents as a Lua chunk. 576821d3294cSantirezWhen called without arguments, 576921d3294cSantirez<code>dofile</code> executes the contents of the standard input (<code>stdin</code>). 577021d3294cSantirezReturns all values returned by the chunk. 577121d3294cSantirezIn case of errors, <code>dofile</code> propagates the error 577221d3294cSantirezto its caller (that is, <code>dofile</code> does not run in protected mode). 577321d3294cSantirez 577421d3294cSantirez 577521d3294cSantirez 577621d3294cSantirez 577721d3294cSantirez<p> 577821d3294cSantirez<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> 577921d3294cSantirezTerminates the last protected function called 578021d3294cSantirezand returns <code>message</code> as the error message. 578121d3294cSantirezFunction <code>error</code> never returns. 578221d3294cSantirez 578321d3294cSantirez 578421d3294cSantirez<p> 578521d3294cSantirezUsually, <code>error</code> adds some information about the error position 578621d3294cSantirezat the beginning of the message. 578721d3294cSantirezThe <code>level</code> argument specifies how to get the error position. 578821d3294cSantirezWith level 1 (the default), the error position is where the 578921d3294cSantirez<code>error</code> function was called. 579021d3294cSantirezLevel 2 points the error to where the function 579121d3294cSantirezthat called <code>error</code> was called; and so on. 579221d3294cSantirezPassing a level 0 avoids the addition of error position information 579321d3294cSantirezto the message. 579421d3294cSantirez 579521d3294cSantirez 579621d3294cSantirez 579721d3294cSantirez 579821d3294cSantirez<p> 579921d3294cSantirez<hr><h3><a name="pdf-_G"><code>_G</code></a></h3> 580021d3294cSantirezA global variable (not a function) that 580121d3294cSantirezholds the global environment (that is, <code>_G._G = _G</code>). 580221d3294cSantirezLua itself does not use this variable; 580321d3294cSantirezchanging its value does not affect any environment, 580421d3294cSantireznor vice-versa. 580521d3294cSantirez(Use <a href="#pdf-setfenv"><code>setfenv</code></a> to change environments.) 580621d3294cSantirez 580721d3294cSantirez 580821d3294cSantirez 580921d3294cSantirez 581021d3294cSantirez<p> 581121d3294cSantirez<hr><h3><a name="pdf-getfenv"><code>getfenv ([f])</code></a></h3> 581221d3294cSantirezReturns the current environment in use by the function. 581321d3294cSantirez<code>f</code> can be a Lua function or a number 581421d3294cSantirezthat specifies the function at that stack level: 581521d3294cSantirezLevel 1 is the function calling <code>getfenv</code>. 581621d3294cSantirezIf the given function is not a Lua function, 581721d3294cSantirezor if <code>f</code> is 0, 581821d3294cSantirez<code>getfenv</code> returns the global environment. 581921d3294cSantirezThe default for <code>f</code> is 1. 582021d3294cSantirez 582121d3294cSantirez 582221d3294cSantirez 582321d3294cSantirez 582421d3294cSantirez<p> 582521d3294cSantirez<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> 582621d3294cSantirez 582721d3294cSantirez 582821d3294cSantirez<p> 582921d3294cSantirezIf <code>object</code> does not have a metatable, returns <b>nil</b>. 583021d3294cSantirezOtherwise, 583121d3294cSantirezif the object's metatable has a <code>"__metatable"</code> field, 583221d3294cSantirezreturns the associated value. 583321d3294cSantirezOtherwise, returns the metatable of the given object. 583421d3294cSantirez 583521d3294cSantirez 583621d3294cSantirez 583721d3294cSantirez 583821d3294cSantirez<p> 583921d3294cSantirez<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> 584021d3294cSantirez 584121d3294cSantirez 584221d3294cSantirez<p> 584321d3294cSantirezReturns three values: an iterator function, the table <code>t</code>, and 0, 584421d3294cSantirezso that the construction 584521d3294cSantirez 584621d3294cSantirez<pre> 584721d3294cSantirez for i,v in ipairs(t) do <em>body</em> end 584821d3294cSantirez</pre><p> 584921d3294cSantirezwill iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ···, 585021d3294cSantirezup to the first integer key absent from the table. 585121d3294cSantirez 585221d3294cSantirez 585321d3294cSantirez 585421d3294cSantirez 585521d3294cSantirez<p> 585621d3294cSantirez<hr><h3><a name="pdf-load"><code>load (func [, chunkname])</code></a></h3> 585721d3294cSantirez 585821d3294cSantirez 585921d3294cSantirez<p> 586021d3294cSantirezLoads a chunk using function <code>func</code> to get its pieces. 586121d3294cSantirezEach call to <code>func</code> must return a string that concatenates 586221d3294cSantirezwith previous results. 586321d3294cSantirezA return of an empty string, <b>nil</b>, or no value signals the end of the chunk. 586421d3294cSantirez 586521d3294cSantirez 586621d3294cSantirez<p> 586721d3294cSantirezIf there are no errors, 586821d3294cSantirezreturns the compiled chunk as a function; 586921d3294cSantirezotherwise, returns <b>nil</b> plus the error message. 587021d3294cSantirezThe environment of the returned function is the global environment. 587121d3294cSantirez 587221d3294cSantirez 587321d3294cSantirez<p> 587421d3294cSantirez<code>chunkname</code> is used as the chunk name for error messages 587521d3294cSantirezand debug information. 587621d3294cSantirezWhen absent, 587721d3294cSantirezit defaults to "<code>=(load)</code>". 587821d3294cSantirez 587921d3294cSantirez 588021d3294cSantirez 588121d3294cSantirez 588221d3294cSantirez<p> 588321d3294cSantirez<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename])</code></a></h3> 588421d3294cSantirez 588521d3294cSantirez 588621d3294cSantirez<p> 588721d3294cSantirezSimilar to <a href="#pdf-load"><code>load</code></a>, 588821d3294cSantirezbut gets the chunk from file <code>filename</code> 588921d3294cSantirezor from the standard input, 589021d3294cSantirezif no file name is given. 589121d3294cSantirez 589221d3294cSantirez 589321d3294cSantirez 589421d3294cSantirez 589521d3294cSantirez<p> 589621d3294cSantirez<hr><h3><a name="pdf-loadstring"><code>loadstring (string [, chunkname])</code></a></h3> 589721d3294cSantirez 589821d3294cSantirez 589921d3294cSantirez<p> 590021d3294cSantirezSimilar to <a href="#pdf-load"><code>load</code></a>, 590121d3294cSantirezbut gets the chunk from the given string. 590221d3294cSantirez 590321d3294cSantirez 590421d3294cSantirez<p> 590521d3294cSantirezTo load and run a given string, use the idiom 590621d3294cSantirez 590721d3294cSantirez<pre> 590821d3294cSantirez assert(loadstring(s))() 590921d3294cSantirez</pre> 591021d3294cSantirez 591121d3294cSantirez<p> 591221d3294cSantirezWhen absent, 591321d3294cSantirez<code>chunkname</code> defaults to the given string. 591421d3294cSantirez 591521d3294cSantirez 591621d3294cSantirez 591721d3294cSantirez 591821d3294cSantirez<p> 591921d3294cSantirez<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> 592021d3294cSantirez 592121d3294cSantirez 592221d3294cSantirez<p> 592321d3294cSantirezAllows a program to traverse all fields of a table. 592421d3294cSantirezIts first argument is a table and its second argument 592521d3294cSantirezis an index in this table. 592621d3294cSantirez<code>next</code> returns the next index of the table 592721d3294cSantirezand its associated value. 592821d3294cSantirezWhen called with <b>nil</b> as its second argument, 592921d3294cSantirez<code>next</code> returns an initial index 593021d3294cSantirezand its associated value. 593121d3294cSantirezWhen called with the last index, 593221d3294cSantirezor with <b>nil</b> in an empty table, 593321d3294cSantirez<code>next</code> returns <b>nil</b>. 593421d3294cSantirezIf the second argument is absent, then it is interpreted as <b>nil</b>. 593521d3294cSantirezIn particular, 593621d3294cSantirezyou can use <code>next(t)</code> to check whether a table is empty. 593721d3294cSantirez 593821d3294cSantirez 593921d3294cSantirez<p> 594021d3294cSantirezThe order in which the indices are enumerated is not specified, 594121d3294cSantirez<em>even for numeric indices</em>. 594221d3294cSantirez(To traverse a table in numeric order, 594321d3294cSantirezuse a numerical <b>for</b> or the <a href="#pdf-ipairs"><code>ipairs</code></a> function.) 594421d3294cSantirez 594521d3294cSantirez 594621d3294cSantirez<p> 594721d3294cSantirezThe behavior of <code>next</code> is <em>undefined</em> if, 594821d3294cSantirezduring the traversal, 594921d3294cSantirezyou assign any value to a non-existent field in the table. 595021d3294cSantirezYou may however modify existing fields. 595121d3294cSantirezIn particular, you may clear existing fields. 595221d3294cSantirez 595321d3294cSantirez 595421d3294cSantirez 595521d3294cSantirez 595621d3294cSantirez<p> 595721d3294cSantirez<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> 595821d3294cSantirez 595921d3294cSantirez 596021d3294cSantirez<p> 596121d3294cSantirezReturns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, 596221d3294cSantirezso that the construction 596321d3294cSantirez 596421d3294cSantirez<pre> 596521d3294cSantirez for k,v in pairs(t) do <em>body</em> end 596621d3294cSantirez</pre><p> 596721d3294cSantirezwill iterate over all key–value pairs of table <code>t</code>. 596821d3294cSantirez 596921d3294cSantirez 597021d3294cSantirez<p> 597121d3294cSantirezSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 597221d3294cSantirezthe table during its traversal. 597321d3294cSantirez 597421d3294cSantirez 597521d3294cSantirez 597621d3294cSantirez 597721d3294cSantirez<p> 597821d3294cSantirez<hr><h3><a name="pdf-pcall"><code>pcall (f, arg1, ···)</code></a></h3> 597921d3294cSantirez 598021d3294cSantirez 598121d3294cSantirez<p> 598221d3294cSantirezCalls function <code>f</code> with 598321d3294cSantirezthe given arguments in <em>protected mode</em>. 598421d3294cSantirezThis means that any error inside <code>f</code> is not propagated; 598521d3294cSantirezinstead, <code>pcall</code> catches the error 598621d3294cSantirezand returns a status code. 598721d3294cSantirezIts first result is the status code (a boolean), 598821d3294cSantirezwhich is true if the call succeeds without errors. 598921d3294cSantirezIn such case, <code>pcall</code> also returns all results from the call, 599021d3294cSantirezafter this first result. 599121d3294cSantirezIn case of any error, <code>pcall</code> returns <b>false</b> plus the error message. 599221d3294cSantirez 599321d3294cSantirez 599421d3294cSantirez 599521d3294cSantirez 599621d3294cSantirez<p> 599721d3294cSantirez<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> 599821d3294cSantirezReceives any number of arguments, 599921d3294cSantirezand prints their values to <code>stdout</code>, 600021d3294cSantirezusing the <a href="#pdf-tostring"><code>tostring</code></a> function to convert them to strings. 600121d3294cSantirez<code>print</code> is not intended for formatted output, 600221d3294cSantirezbut only as a quick way to show a value, 600321d3294cSantireztypically for debugging. 600421d3294cSantirezFor formatted output, use <a href="#pdf-string.format"><code>string.format</code></a>. 600521d3294cSantirez 600621d3294cSantirez 600721d3294cSantirez 600821d3294cSantirez 600921d3294cSantirez<p> 601021d3294cSantirez<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> 601121d3294cSantirezChecks whether <code>v1</code> is equal to <code>v2</code>, 601221d3294cSantirezwithout invoking any metamethod. 601321d3294cSantirezReturns a boolean. 601421d3294cSantirez 601521d3294cSantirez 601621d3294cSantirez 601721d3294cSantirez 601821d3294cSantirez<p> 601921d3294cSantirez<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> 602021d3294cSantirezGets the real value of <code>table[index]</code>, 602121d3294cSantirezwithout invoking any metamethod. 602221d3294cSantirez<code>table</code> must be a table; 602321d3294cSantirez<code>index</code> may be any value. 602421d3294cSantirez 602521d3294cSantirez 602621d3294cSantirez 602721d3294cSantirez 602821d3294cSantirez<p> 602921d3294cSantirez<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> 603021d3294cSantirezSets the real value of <code>table[index]</code> to <code>value</code>, 603121d3294cSantirezwithout invoking any metamethod. 603221d3294cSantirez<code>table</code> must be a table, 603321d3294cSantirez<code>index</code> any value different from <b>nil</b>, 603421d3294cSantirezand <code>value</code> any Lua value. 603521d3294cSantirez 603621d3294cSantirez 603721d3294cSantirez<p> 603821d3294cSantirezThis function returns <code>table</code>. 603921d3294cSantirez 604021d3294cSantirez 604121d3294cSantirez 604221d3294cSantirez 604321d3294cSantirez<p> 604421d3294cSantirez<hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> 604521d3294cSantirez 604621d3294cSantirez 604721d3294cSantirez<p> 604821d3294cSantirezIf <code>index</code> is a number, 604921d3294cSantirezreturns all arguments after argument number <code>index</code>. 605021d3294cSantirezOtherwise, <code>index</code> must be the string <code>"#"</code>, 605121d3294cSantirezand <code>select</code> returns the total number of extra arguments it received. 605221d3294cSantirez 605321d3294cSantirez 605421d3294cSantirez 605521d3294cSantirez 605621d3294cSantirez<p> 605721d3294cSantirez<hr><h3><a name="pdf-setfenv"><code>setfenv (f, table)</code></a></h3> 605821d3294cSantirez 605921d3294cSantirez 606021d3294cSantirez<p> 606121d3294cSantirezSets the environment to be used by the given function. 606221d3294cSantirez<code>f</code> can be a Lua function or a number 606321d3294cSantirezthat specifies the function at that stack level: 606421d3294cSantirezLevel 1 is the function calling <code>setfenv</code>. 606521d3294cSantirez<code>setfenv</code> returns the given function. 606621d3294cSantirez 606721d3294cSantirez 606821d3294cSantirez<p> 606921d3294cSantirezAs a special case, when <code>f</code> is 0 <code>setfenv</code> changes 607021d3294cSantirezthe environment of the running thread. 607121d3294cSantirezIn this case, <code>setfenv</code> returns no values. 607221d3294cSantirez 607321d3294cSantirez 607421d3294cSantirez 607521d3294cSantirez 607621d3294cSantirez<p> 607721d3294cSantirez<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> 607821d3294cSantirez 607921d3294cSantirez 608021d3294cSantirez<p> 608121d3294cSantirezSets the metatable for the given table. 608221d3294cSantirez(You cannot change the metatable of other types from Lua, only from C.) 608321d3294cSantirezIf <code>metatable</code> is <b>nil</b>, 608421d3294cSantirezremoves the metatable of the given table. 608521d3294cSantirezIf the original metatable has a <code>"__metatable"</code> field, 608621d3294cSantirezraises an error. 608721d3294cSantirez 608821d3294cSantirez 608921d3294cSantirez<p> 609021d3294cSantirezThis function returns <code>table</code>. 609121d3294cSantirez 609221d3294cSantirez 609321d3294cSantirez 609421d3294cSantirez 609521d3294cSantirez<p> 609621d3294cSantirez<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> 609721d3294cSantirezTries to convert its argument to a number. 609821d3294cSantirezIf the argument is already a number or a string convertible 609921d3294cSantirezto a number, then <code>tonumber</code> returns this number; 610021d3294cSantirezotherwise, it returns <b>nil</b>. 610121d3294cSantirez 610221d3294cSantirez 610321d3294cSantirez<p> 610421d3294cSantirezAn optional argument specifies the base to interpret the numeral. 610521d3294cSantirezThe base may be any integer between 2 and 36, inclusive. 610621d3294cSantirezIn bases above 10, the letter '<code>A</code>' (in either upper or lower case) 610721d3294cSantirezrepresents 10, '<code>B</code>' represents 11, and so forth, 610821d3294cSantirezwith '<code>Z</code>' representing 35. 610921d3294cSantirezIn base 10 (the default), the number can have a decimal part, 611021d3294cSantirezas well as an optional exponent part (see <a href="#2.1">§2.1</a>). 611121d3294cSantirezIn other bases, only unsigned integers are accepted. 611221d3294cSantirez 611321d3294cSantirez 611421d3294cSantirez 611521d3294cSantirez 611621d3294cSantirez<p> 611721d3294cSantirez<hr><h3><a name="pdf-tostring"><code>tostring (e)</code></a></h3> 611821d3294cSantirezReceives an argument of any type and 611921d3294cSantirezconverts it to a string in a reasonable format. 612021d3294cSantirezFor complete control of how numbers are converted, 612121d3294cSantirezuse <a href="#pdf-string.format"><code>string.format</code></a>. 612221d3294cSantirez 612321d3294cSantirez 612421d3294cSantirez<p> 612521d3294cSantirezIf the metatable of <code>e</code> has a <code>"__tostring"</code> field, 612621d3294cSantirezthen <code>tostring</code> calls the corresponding value 612721d3294cSantirezwith <code>e</code> as argument, 612821d3294cSantirezand uses the result of the call as its result. 612921d3294cSantirez 613021d3294cSantirez 613121d3294cSantirez 613221d3294cSantirez 613321d3294cSantirez<p> 613421d3294cSantirez<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> 613521d3294cSantirezReturns the type of its only argument, coded as a string. 613621d3294cSantirezThe possible results of this function are 613721d3294cSantirez"<code>nil</code>" (a string, not the value <b>nil</b>), 613821d3294cSantirez"<code>number</code>", 613921d3294cSantirez"<code>string</code>", 614021d3294cSantirez"<code>boolean</code>", 614121d3294cSantirez"<code>table</code>", 614221d3294cSantirez"<code>function</code>", 614321d3294cSantirez"<code>thread</code>", 614421d3294cSantirezand "<code>userdata</code>". 614521d3294cSantirez 614621d3294cSantirez 614721d3294cSantirez 614821d3294cSantirez 614921d3294cSantirez<p> 615021d3294cSantirez<hr><h3><a name="pdf-unpack"><code>unpack (list [, i [, j]])</code></a></h3> 615121d3294cSantirezReturns the elements from the given table. 615221d3294cSantirezThis function is equivalent to 615321d3294cSantirez 615421d3294cSantirez<pre> 615521d3294cSantirez return list[i], list[i+1], ···, list[j] 615621d3294cSantirez</pre><p> 615721d3294cSantirezexcept that the above code can be written only for a fixed number 615821d3294cSantirezof elements. 615921d3294cSantirezBy default, <code>i</code> is 1 and <code>j</code> is the length of the list, 616021d3294cSantirezas defined by the length operator (see <a href="#2.5.5">§2.5.5</a>). 616121d3294cSantirez 616221d3294cSantirez 616321d3294cSantirez 616421d3294cSantirez 616521d3294cSantirez<p> 616621d3294cSantirez<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> 616721d3294cSantirezA global variable (not a function) that 616821d3294cSantirezholds a string containing the current interpreter version. 616921d3294cSantirezThe current contents of this variable is "<code>Lua 5.1</code>". 617021d3294cSantirez 617121d3294cSantirez 617221d3294cSantirez 617321d3294cSantirez 617421d3294cSantirez<p> 617521d3294cSantirez<hr><h3><a name="pdf-xpcall"><code>xpcall (f, err)</code></a></h3> 617621d3294cSantirez 617721d3294cSantirez 617821d3294cSantirez<p> 617921d3294cSantirezThis function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, 618021d3294cSantirezexcept that you can set a new error handler. 618121d3294cSantirez 618221d3294cSantirez 618321d3294cSantirez<p> 618421d3294cSantirez<code>xpcall</code> calls function <code>f</code> in protected mode, 618521d3294cSantirezusing <code>err</code> as the error handler. 618621d3294cSantirezAny error inside <code>f</code> is not propagated; 618721d3294cSantirezinstead, <code>xpcall</code> catches the error, 618821d3294cSantirezcalls the <code>err</code> function with the original error object, 618921d3294cSantirezand returns a status code. 619021d3294cSantirezIts first result is the status code (a boolean), 619121d3294cSantirezwhich is true if the call succeeds without errors. 619221d3294cSantirezIn this case, <code>xpcall</code> also returns all results from the call, 619321d3294cSantirezafter this first result. 619421d3294cSantirezIn case of any error, 619521d3294cSantirez<code>xpcall</code> returns <b>false</b> plus the result from <code>err</code>. 619621d3294cSantirez 619721d3294cSantirez 619821d3294cSantirez 619921d3294cSantirez 620021d3294cSantirez 620121d3294cSantirez 620221d3294cSantirez 620321d3294cSantirez<h2>5.2 - <a name="5.2">Coroutine Manipulation</a></h2> 620421d3294cSantirez 620521d3294cSantirez<p> 620621d3294cSantirezThe operations related to coroutines comprise a sub-library of 620721d3294cSantirezthe basic library and come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. 620821d3294cSantirezSee <a href="#2.11">§2.11</a> for a general description of coroutines. 620921d3294cSantirez 621021d3294cSantirez 621121d3294cSantirez<p> 621221d3294cSantirez<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> 621321d3294cSantirez 621421d3294cSantirez 621521d3294cSantirez<p> 621621d3294cSantirezCreates a new coroutine, with body <code>f</code>. 621721d3294cSantirez<code>f</code> must be a Lua function. 621821d3294cSantirezReturns this new coroutine, 621921d3294cSantirezan object with type <code>"thread"</code>. 622021d3294cSantirez 622121d3294cSantirez 622221d3294cSantirez 622321d3294cSantirez 622421d3294cSantirez<p> 622521d3294cSantirez<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> 622621d3294cSantirez 622721d3294cSantirez 622821d3294cSantirez<p> 622921d3294cSantirezStarts or continues the execution of coroutine <code>co</code>. 623021d3294cSantirezThe first time you resume a coroutine, 623121d3294cSantirezit starts running its body. 623221d3294cSantirezThe values <code>val1</code>, ··· are passed 623321d3294cSantirezas the arguments to the body function. 623421d3294cSantirezIf the coroutine has yielded, 623521d3294cSantirez<code>resume</code> restarts it; 623621d3294cSantirezthe values <code>val1</code>, ··· are passed 623721d3294cSantirezas the results from the yield. 623821d3294cSantirez 623921d3294cSantirez 624021d3294cSantirez<p> 624121d3294cSantirezIf the coroutine runs without any errors, 624221d3294cSantirez<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> 624321d3294cSantirez(if the coroutine yields) or any values returned by the body function 624421d3294cSantirez(if the coroutine terminates). 624521d3294cSantirezIf there is any error, 624621d3294cSantirez<code>resume</code> returns <b>false</b> plus the error message. 624721d3294cSantirez 624821d3294cSantirez 624921d3294cSantirez 625021d3294cSantirez 625121d3294cSantirez<p> 625221d3294cSantirez<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> 625321d3294cSantirez 625421d3294cSantirez 625521d3294cSantirez<p> 625621d3294cSantirezReturns the running coroutine, 625721d3294cSantirezor <b>nil</b> when called by the main thread. 625821d3294cSantirez 625921d3294cSantirez 626021d3294cSantirez 626121d3294cSantirez 626221d3294cSantirez<p> 626321d3294cSantirez<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> 626421d3294cSantirez 626521d3294cSantirez 626621d3294cSantirez<p> 626721d3294cSantirezReturns the status of coroutine <code>co</code>, as a string: 626821d3294cSantirez<code>"running"</code>, 626921d3294cSantirezif the coroutine is running (that is, it called <code>status</code>); 627021d3294cSantirez<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, 627121d3294cSantirezor if it has not started running yet; 627221d3294cSantirez<code>"normal"</code> if the coroutine is active but not running 627321d3294cSantirez(that is, it has resumed another coroutine); 627421d3294cSantirezand <code>"dead"</code> if the coroutine has finished its body function, 627521d3294cSantirezor if it has stopped with an error. 627621d3294cSantirez 627721d3294cSantirez 627821d3294cSantirez 627921d3294cSantirez 628021d3294cSantirez<p> 628121d3294cSantirez<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> 628221d3294cSantirez 628321d3294cSantirez 628421d3294cSantirez<p> 628521d3294cSantirezCreates a new coroutine, with body <code>f</code>. 628621d3294cSantirez<code>f</code> must be a Lua function. 628721d3294cSantirezReturns a function that resumes the coroutine each time it is called. 628821d3294cSantirezAny arguments passed to the function behave as the 628921d3294cSantirezextra arguments to <code>resume</code>. 629021d3294cSantirezReturns the same values returned by <code>resume</code>, 629121d3294cSantirezexcept the first boolean. 629221d3294cSantirezIn case of error, propagates the error. 629321d3294cSantirez 629421d3294cSantirez 629521d3294cSantirez 629621d3294cSantirez 629721d3294cSantirez<p> 629821d3294cSantirez<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> 629921d3294cSantirez 630021d3294cSantirez 630121d3294cSantirez<p> 630221d3294cSantirezSuspends the execution of the calling coroutine. 630321d3294cSantirezThe coroutine cannot be running a C function, 630421d3294cSantireza metamethod, or an iterator. 630521d3294cSantirezAny arguments to <code>yield</code> are passed as extra results to <code>resume</code>. 630621d3294cSantirez 630721d3294cSantirez 630821d3294cSantirez 630921d3294cSantirez 631021d3294cSantirez 631121d3294cSantirez 631221d3294cSantirez 631321d3294cSantirez<h2>5.3 - <a name="5.3">Modules</a></h2> 631421d3294cSantirez 631521d3294cSantirez<p> 631621d3294cSantirezThe package library provides basic 631721d3294cSantirezfacilities for loading and building modules in Lua. 631821d3294cSantirezIt exports two of its functions directly in the global environment: 631921d3294cSantirez<a href="#pdf-require"><code>require</code></a> and <a href="#pdf-module"><code>module</code></a>. 632021d3294cSantirezEverything else is exported in a table <a name="pdf-package"><code>package</code></a>. 632121d3294cSantirez 632221d3294cSantirez 632321d3294cSantirez<p> 632421d3294cSantirez<hr><h3><a name="pdf-module"><code>module (name [, ···])</code></a></h3> 632521d3294cSantirez 632621d3294cSantirez 632721d3294cSantirez<p> 632821d3294cSantirezCreates a module. 632921d3294cSantirezIf there is a table in <code>package.loaded[name]</code>, 633021d3294cSantirezthis table is the module. 633121d3294cSantirezOtherwise, if there is a global table <code>t</code> with the given name, 633221d3294cSantirezthis table is the module. 633321d3294cSantirezOtherwise creates a new table <code>t</code> and 633421d3294cSantirezsets it as the value of the global <code>name</code> and 633521d3294cSantirezthe value of <code>package.loaded[name]</code>. 633621d3294cSantirezThis function also initializes <code>t._NAME</code> with the given name, 633721d3294cSantirez<code>t._M</code> with the module (<code>t</code> itself), 633821d3294cSantirezand <code>t._PACKAGE</code> with the package name 633921d3294cSantirez(the full module name minus last component; see below). 634021d3294cSantirezFinally, <code>module</code> sets <code>t</code> as the new environment 634121d3294cSantirezof the current function and the new value of <code>package.loaded[name]</code>, 634221d3294cSantirezso that <a href="#pdf-require"><code>require</code></a> returns <code>t</code>. 634321d3294cSantirez 634421d3294cSantirez 634521d3294cSantirez<p> 634621d3294cSantirezIf <code>name</code> is a compound name 634721d3294cSantirez(that is, one with components separated by dots), 634821d3294cSantirez<code>module</code> creates (or reuses, if they already exist) 634921d3294cSantireztables for each component. 635021d3294cSantirezFor instance, if <code>name</code> is <code>a.b.c</code>, 635121d3294cSantirezthen <code>module</code> stores the module table in field <code>c</code> of 635221d3294cSantirezfield <code>b</code> of global <code>a</code>. 635321d3294cSantirez 635421d3294cSantirez 635521d3294cSantirez<p> 635621d3294cSantirezThis function can receive optional <em>options</em> after 635721d3294cSantirezthe module name, 635821d3294cSantirezwhere each option is a function to be applied over the module. 635921d3294cSantirez 636021d3294cSantirez 636121d3294cSantirez 636221d3294cSantirez 636321d3294cSantirez<p> 636421d3294cSantirez<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> 636521d3294cSantirez 636621d3294cSantirez 636721d3294cSantirez<p> 636821d3294cSantirezLoads the given module. 636921d3294cSantirezThe function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table 637021d3294cSantirezto determine whether <code>modname</code> is already loaded. 637121d3294cSantirezIf it is, then <code>require</code> returns the value stored 637221d3294cSantirezat <code>package.loaded[modname]</code>. 637321d3294cSantirezOtherwise, it tries to find a <em>loader</em> for the module. 637421d3294cSantirez 637521d3294cSantirez 637621d3294cSantirez<p> 637721d3294cSantirezTo find a loader, 637821d3294cSantirez<code>require</code> is guided by the <a href="#pdf-package.loaders"><code>package.loaders</code></a> array. 637921d3294cSantirezBy changing this array, 638021d3294cSantirezwe can change how <code>require</code> looks for a module. 638121d3294cSantirezThe following explanation is based on the default configuration 638221d3294cSantirezfor <a href="#pdf-package.loaders"><code>package.loaders</code></a>. 638321d3294cSantirez 638421d3294cSantirez 638521d3294cSantirez<p> 638621d3294cSantirezFirst <code>require</code> queries <code>package.preload[modname]</code>. 638721d3294cSantirezIf it has a value, 638821d3294cSantirezthis value (which should be a function) is the loader. 638921d3294cSantirezOtherwise <code>require</code> searches for a Lua loader using the 639021d3294cSantirezpath stored in <a href="#pdf-package.path"><code>package.path</code></a>. 639121d3294cSantirezIf that also fails, it searches for a C loader using the 639221d3294cSantirezpath stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 639321d3294cSantirezIf that also fails, 639421d3294cSantirezit tries an <em>all-in-one</em> loader (see <a href="#pdf-package.loaders"><code>package.loaders</code></a>). 639521d3294cSantirez 639621d3294cSantirez 639721d3294cSantirez<p> 639821d3294cSantirezOnce a loader is found, 639921d3294cSantirez<code>require</code> calls the loader with a single argument, <code>modname</code>. 640021d3294cSantirezIf the loader returns any value, 640121d3294cSantirez<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. 640221d3294cSantirezIf the loader returns no value and 640321d3294cSantirezhas not assigned any value to <code>package.loaded[modname]</code>, 640421d3294cSantirezthen <code>require</code> assigns <b>true</b> to this entry. 640521d3294cSantirezIn any case, <code>require</code> returns the 640621d3294cSantirezfinal value of <code>package.loaded[modname]</code>. 640721d3294cSantirez 640821d3294cSantirez 640921d3294cSantirez<p> 641021d3294cSantirezIf there is any error loading or running the module, 641121d3294cSantirezor if it cannot find any loader for the module, 641221d3294cSantirezthen <code>require</code> signals an error. 641321d3294cSantirez 641421d3294cSantirez 641521d3294cSantirez 641621d3294cSantirez 641721d3294cSantirez<p> 641821d3294cSantirez<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> 641921d3294cSantirez 642021d3294cSantirez 642121d3294cSantirez<p> 642221d3294cSantirezThe path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. 642321d3294cSantirez 642421d3294cSantirez 642521d3294cSantirez<p> 642621d3294cSantirezLua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way 642721d3294cSantirezit initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, 642821d3294cSantirezusing the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a> 642921d3294cSantirezor a default path defined in <code>luaconf.h</code>. 643021d3294cSantirez 643121d3294cSantirez 643221d3294cSantirez 643321d3294cSantirez 643421d3294cSantirez<p> 643521d3294cSantirez 643621d3294cSantirez<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> 643721d3294cSantirez 643821d3294cSantirez 643921d3294cSantirez<p> 644021d3294cSantirezA table used by <a href="#pdf-require"><code>require</code></a> to control which 644121d3294cSantirezmodules are already loaded. 644221d3294cSantirezWhen you require a module <code>modname</code> and 644321d3294cSantirez<code>package.loaded[modname]</code> is not false, 644421d3294cSantirez<a href="#pdf-require"><code>require</code></a> simply returns the value stored there. 644521d3294cSantirez 644621d3294cSantirez 644721d3294cSantirez 644821d3294cSantirez 644921d3294cSantirez<p> 645021d3294cSantirez<hr><h3><a name="pdf-package.loaders"><code>package.loaders</code></a></h3> 645121d3294cSantirez 645221d3294cSantirez 645321d3294cSantirez<p> 645421d3294cSantirezA table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules. 645521d3294cSantirez 645621d3294cSantirez 645721d3294cSantirez<p> 645821d3294cSantirezEach entry in this table is a <em>searcher function</em>. 645921d3294cSantirezWhen looking for a module, 646021d3294cSantirez<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, 646121d3294cSantirezwith the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its 646221d3294cSantirezsole parameter. 646321d3294cSantirezThe function can return another function (the module <em>loader</em>) 646421d3294cSantirezor a string explaining why it did not find that module 646521d3294cSantirez(or <b>nil</b> if it has nothing to say). 646621d3294cSantirezLua initializes this table with four functions. 646721d3294cSantirez 646821d3294cSantirez 646921d3294cSantirez<p> 647021d3294cSantirezThe first searcher simply looks for a loader in the 647121d3294cSantirez<a href="#pdf-package.preload"><code>package.preload</code></a> table. 647221d3294cSantirez 647321d3294cSantirez 647421d3294cSantirez<p> 647521d3294cSantirezThe second searcher looks for a loader as a Lua library, 647621d3294cSantirezusing the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. 647721d3294cSantirezA path is a sequence of <em>templates</em> separated by semicolons. 647821d3294cSantirezFor each template, 647921d3294cSantirezthe searcher will change each interrogation 648021d3294cSantirezmark in the template by <code>filename</code>, 648121d3294cSantirezwhich is the module name with each dot replaced by a 648221d3294cSantirez"directory separator" (such as "<code>/</code>" in Unix); 648321d3294cSantirezthen it will try to open the resulting file name. 648421d3294cSantirezSo, for instance, if the Lua path is the string 648521d3294cSantirez 648621d3294cSantirez<pre> 648721d3294cSantirez "./?.lua;./?.lc;/usr/local/?/init.lua" 648821d3294cSantirez</pre><p> 648921d3294cSantirezthe search for a Lua file for module <code>foo</code> 649021d3294cSantirezwill try to open the files 649121d3294cSantirez<code>./foo.lua</code>, <code>./foo.lc</code>, and 649221d3294cSantirez<code>/usr/local/foo/init.lua</code>, in that order. 649321d3294cSantirez 649421d3294cSantirez 649521d3294cSantirez<p> 649621d3294cSantirezThe third searcher looks for a loader as a C library, 649721d3294cSantirezusing the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 649821d3294cSantirezFor instance, 649921d3294cSantirezif the C path is the string 650021d3294cSantirez 650121d3294cSantirez<pre> 650221d3294cSantirez "./?.so;./?.dll;/usr/local/?/init.so" 650321d3294cSantirez</pre><p> 650421d3294cSantirezthe searcher for module <code>foo</code> 650521d3294cSantirezwill try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, 650621d3294cSantirezand <code>/usr/local/foo/init.so</code>, in that order. 650721d3294cSantirezOnce it finds a C library, 650821d3294cSantirezthis searcher first uses a dynamic link facility to link the 650921d3294cSantirezapplication with the library. 651021d3294cSantirezThen it tries to find a C function inside the library to 651121d3294cSantirezbe used as the loader. 651221d3294cSantirezThe name of this C function is the string "<code>luaopen_</code>" 651321d3294cSantirezconcatenated with a copy of the module name where each dot 651421d3294cSantirezis replaced by an underscore. 651521d3294cSantirezMoreover, if the module name has a hyphen, 651621d3294cSantirezits prefix up to (and including) the first hyphen is removed. 651721d3294cSantirezFor instance, if the module name is <code>a.v1-b.c</code>, 651821d3294cSantirezthe function name will be <code>luaopen_b_c</code>. 651921d3294cSantirez 652021d3294cSantirez 652121d3294cSantirez<p> 652221d3294cSantirezThe fourth searcher tries an <em>all-in-one loader</em>. 652321d3294cSantirezIt searches the C path for a library for 652421d3294cSantirezthe root name of the given module. 652521d3294cSantirezFor instance, when requiring <code>a.b.c</code>, 652621d3294cSantirezit will search for a C library for <code>a</code>. 652721d3294cSantirezIf found, it looks into it for an open function for 652821d3294cSantirezthe submodule; 652921d3294cSantirezin our example, that would be <code>luaopen_a_b_c</code>. 653021d3294cSantirezWith this facility, a package can pack several C submodules 653121d3294cSantirezinto one single library, 653221d3294cSantirezwith each submodule keeping its original open function. 653321d3294cSantirez 653421d3294cSantirez 653521d3294cSantirez 653621d3294cSantirez 653721d3294cSantirez<p> 653821d3294cSantirez<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> 653921d3294cSantirez 654021d3294cSantirez 654121d3294cSantirez<p> 654221d3294cSantirezDynamically links the host program with the C library <code>libname</code>. 654321d3294cSantirezInside this library, looks for a function <code>funcname</code> 654421d3294cSantirezand returns this function as a C function. 654521d3294cSantirez(So, <code>funcname</code> must follow the protocol (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>)). 654621d3294cSantirez 654721d3294cSantirez 654821d3294cSantirez<p> 654921d3294cSantirezThis is a low-level function. 655021d3294cSantirezIt completely bypasses the package and module system. 655121d3294cSantirezUnlike <a href="#pdf-require"><code>require</code></a>, 655221d3294cSantirezit does not perform any path searching and 655321d3294cSantirezdoes not automatically adds extensions. 655421d3294cSantirez<code>libname</code> must be the complete file name of the C library, 655521d3294cSantirezincluding if necessary a path and extension. 655621d3294cSantirez<code>funcname</code> must be the exact name exported by the C library 655721d3294cSantirez(which may depend on the C compiler and linker used). 655821d3294cSantirez 655921d3294cSantirez 656021d3294cSantirez<p> 656121d3294cSantirezThis function is not supported by ANSI C. 656221d3294cSantirezAs such, it is only available on some platforms 656321d3294cSantirez(Windows, Linux, Mac OS X, Solaris, BSD, 656421d3294cSantirezplus other Unix systems that support the <code>dlfcn</code> standard). 656521d3294cSantirez 656621d3294cSantirez 656721d3294cSantirez 656821d3294cSantirez 656921d3294cSantirez<p> 657021d3294cSantirez<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> 657121d3294cSantirez 657221d3294cSantirez 657321d3294cSantirez<p> 657421d3294cSantirezThe path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. 657521d3294cSantirez 657621d3294cSantirez 657721d3294cSantirez<p> 657821d3294cSantirezAt start-up, Lua initializes this variable with 657921d3294cSantirezthe value of the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or 658021d3294cSantirezwith a default path defined in <code>luaconf.h</code>, 658121d3294cSantirezif the environment variable is not defined. 658221d3294cSantirezAny "<code>;;</code>" in the value of the environment variable 658321d3294cSantirezis replaced by the default path. 658421d3294cSantirez 658521d3294cSantirez 658621d3294cSantirez 658721d3294cSantirez 658821d3294cSantirez<p> 658921d3294cSantirez<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> 659021d3294cSantirez 659121d3294cSantirez 659221d3294cSantirez<p> 659321d3294cSantirezA table to store loaders for specific modules 659421d3294cSantirez(see <a href="#pdf-require"><code>require</code></a>). 659521d3294cSantirez 659621d3294cSantirez 659721d3294cSantirez 659821d3294cSantirez 659921d3294cSantirez<p> 660021d3294cSantirez<hr><h3><a name="pdf-package.seeall"><code>package.seeall (module)</code></a></h3> 660121d3294cSantirez 660221d3294cSantirez 660321d3294cSantirez<p> 660421d3294cSantirezSets a metatable for <code>module</code> with 660521d3294cSantirezits <code>__index</code> field referring to the global environment, 660621d3294cSantirezso that this module inherits values 660721d3294cSantirezfrom the global environment. 660821d3294cSantirezTo be used as an option to function <a href="#pdf-module"><code>module</code></a>. 660921d3294cSantirez 661021d3294cSantirez 661121d3294cSantirez 661221d3294cSantirez 661321d3294cSantirez 661421d3294cSantirez 661521d3294cSantirez 661621d3294cSantirez<h2>5.4 - <a name="5.4">String Manipulation</a></h2> 661721d3294cSantirez 661821d3294cSantirez<p> 661921d3294cSantirezThis library provides generic functions for string manipulation, 662021d3294cSantirezsuch as finding and extracting substrings, and pattern matching. 662121d3294cSantirezWhen indexing a string in Lua, the first character is at position 1 662221d3294cSantirez(not at 0, as in C). 662321d3294cSantirezIndices are allowed to be negative and are interpreted as indexing backwards, 662421d3294cSantirezfrom the end of the string. 662521d3294cSantirezThus, the last character is at position -1, and so on. 662621d3294cSantirez 662721d3294cSantirez 662821d3294cSantirez<p> 662921d3294cSantirezThe string library provides all its functions inside the table 663021d3294cSantirez<a name="pdf-string"><code>string</code></a>. 663121d3294cSantirezIt also sets a metatable for strings 663221d3294cSantirezwhere the <code>__index</code> field points to the <code>string</code> table. 663321d3294cSantirezTherefore, you can use the string functions in object-oriented style. 663421d3294cSantirezFor instance, <code>string.byte(s, i)</code> 663521d3294cSantirezcan be written as <code>s:byte(i)</code>. 663621d3294cSantirez 663721d3294cSantirez 663821d3294cSantirez<p> 663921d3294cSantirezThe string library assumes one-byte character encodings. 664021d3294cSantirez 664121d3294cSantirez 664221d3294cSantirez<p> 664321d3294cSantirez<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> 664421d3294cSantirezReturns the internal numerical codes of the characters <code>s[i]</code>, 664521d3294cSantirez<code>s[i+1]</code>, ···, <code>s[j]</code>. 664621d3294cSantirezThe default value for <code>i</code> is 1; 664721d3294cSantirezthe default value for <code>j</code> is <code>i</code>. 664821d3294cSantirez 664921d3294cSantirez 665021d3294cSantirez<p> 665121d3294cSantirezNote that numerical codes are not necessarily portable across platforms. 665221d3294cSantirez 665321d3294cSantirez 665421d3294cSantirez 665521d3294cSantirez 665621d3294cSantirez<p> 665721d3294cSantirez<hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> 665821d3294cSantirezReceives zero or more integers. 665921d3294cSantirezReturns a string with length equal to the number of arguments, 666021d3294cSantirezin which each character has the internal numerical code equal 666121d3294cSantirezto its corresponding argument. 666221d3294cSantirez 666321d3294cSantirez 666421d3294cSantirez<p> 666521d3294cSantirezNote that numerical codes are not necessarily portable across platforms. 666621d3294cSantirez 666721d3294cSantirez 666821d3294cSantirez 666921d3294cSantirez 667021d3294cSantirez<p> 667121d3294cSantirez<hr><h3><a name="pdf-string.dump"><code>string.dump (function)</code></a></h3> 667221d3294cSantirez 667321d3294cSantirez 667421d3294cSantirez<p> 667521d3294cSantirezReturns a string containing a binary representation of the given function, 667621d3294cSantirezso that a later <a href="#pdf-loadstring"><code>loadstring</code></a> on this string returns 667721d3294cSantireza copy of the function. 667821d3294cSantirez<code>function</code> must be a Lua function without upvalues. 667921d3294cSantirez 668021d3294cSantirez 668121d3294cSantirez 668221d3294cSantirez 668321d3294cSantirez<p> 668421d3294cSantirez<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> 668521d3294cSantirezLooks for the first match of 668621d3294cSantirez<code>pattern</code> in the string <code>s</code>. 668721d3294cSantirezIf it finds a match, then <code>find</code> returns the indices of <code>s</code> 668821d3294cSantirezwhere this occurrence starts and ends; 668921d3294cSantirezotherwise, it returns <b>nil</b>. 669021d3294cSantirezA third, optional numerical argument <code>init</code> specifies 669121d3294cSantirezwhere to start the search; 669221d3294cSantirezits default value is 1 and can be negative. 669321d3294cSantirezA value of <b>true</b> as a fourth, optional argument <code>plain</code> 669421d3294cSantirezturns off the pattern matching facilities, 669521d3294cSantirezso the function does a plain "find substring" operation, 669621d3294cSantirezwith no characters in <code>pattern</code> being considered "magic". 669721d3294cSantirezNote that if <code>plain</code> is given, then <code>init</code> must be given as well. 669821d3294cSantirez 669921d3294cSantirez 670021d3294cSantirez<p> 670121d3294cSantirezIf the pattern has captures, 670221d3294cSantirezthen in a successful match 670321d3294cSantirezthe captured values are also returned, 670421d3294cSantirezafter the two indices. 670521d3294cSantirez 670621d3294cSantirez 670721d3294cSantirez 670821d3294cSantirez 670921d3294cSantirez<p> 671021d3294cSantirez<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> 671121d3294cSantirezReturns a formatted version of its variable number of arguments 671221d3294cSantirezfollowing the description given in its first argument (which must be a string). 671321d3294cSantirezThe format string follows the same rules as the <code>printf</code> family of 671421d3294cSantirezstandard C functions. 671521d3294cSantirezThe only differences are that the options/modifiers 671621d3294cSantirez<code>*</code>, <code>l</code>, <code>L</code>, <code>n</code>, <code>p</code>, 671721d3294cSantirezand <code>h</code> are not supported 671821d3294cSantirezand that there is an extra option, <code>q</code>. 671921d3294cSantirezThe <code>q</code> option formats a string in a form suitable to be safely read 672021d3294cSantirezback by the Lua interpreter: 672121d3294cSantirezthe string is written between double quotes, 672221d3294cSantirezand all double quotes, newlines, embedded zeros, 672321d3294cSantirezand backslashes in the string 672421d3294cSantirezare correctly escaped when written. 672521d3294cSantirezFor instance, the call 672621d3294cSantirez 672721d3294cSantirez<pre> 672821d3294cSantirez string.format('%q', 'a string with "quotes" and \n new line') 672921d3294cSantirez</pre><p> 673021d3294cSantirezwill produce the string: 673121d3294cSantirez 673221d3294cSantirez<pre> 673321d3294cSantirez "a string with \"quotes\" and \ 673421d3294cSantirez new line" 673521d3294cSantirez</pre> 673621d3294cSantirez 673721d3294cSantirez<p> 673821d3294cSantirezThe options <code>c</code>, <code>d</code>, <code>E</code>, <code>e</code>, <code>f</code>, 673921d3294cSantirez<code>g</code>, <code>G</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> all 674021d3294cSantirezexpect a number as argument, 674121d3294cSantirezwhereas <code>q</code> and <code>s</code> expect a string. 674221d3294cSantirez 674321d3294cSantirez 674421d3294cSantirez<p> 674521d3294cSantirezThis function does not accept string values 674621d3294cSantirezcontaining embedded zeros, 674721d3294cSantirezexcept as arguments to the <code>q</code> option. 674821d3294cSantirez 674921d3294cSantirez 675021d3294cSantirez 675121d3294cSantirez 675221d3294cSantirez<p> 675321d3294cSantirez<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3> 675421d3294cSantirezReturns an iterator function that, 675521d3294cSantirezeach time it is called, 675621d3294cSantirezreturns the next captures from <code>pattern</code> over string <code>s</code>. 675721d3294cSantirezIf <code>pattern</code> specifies no captures, 675821d3294cSantirezthen the whole match is produced in each call. 675921d3294cSantirez 676021d3294cSantirez 676121d3294cSantirez<p> 676221d3294cSantirezAs an example, the following loop 676321d3294cSantirez 676421d3294cSantirez<pre> 676521d3294cSantirez s = "hello world from Lua" 676621d3294cSantirez for w in string.gmatch(s, "%a+") do 676721d3294cSantirez print(w) 676821d3294cSantirez end 676921d3294cSantirez</pre><p> 677021d3294cSantirezwill iterate over all the words from string <code>s</code>, 677121d3294cSantirezprinting one per line. 677221d3294cSantirezThe next example collects all pairs <code>key=value</code> from the 677321d3294cSantirezgiven string into a table: 677421d3294cSantirez 677521d3294cSantirez<pre> 677621d3294cSantirez t = {} 677721d3294cSantirez s = "from=world, to=Lua" 677821d3294cSantirez for k, v in string.gmatch(s, "(%w+)=(%w+)") do 677921d3294cSantirez t[k] = v 678021d3294cSantirez end 678121d3294cSantirez</pre> 678221d3294cSantirez 678321d3294cSantirez<p> 678421d3294cSantirezFor this function, a '<code>^</code>' at the start of a pattern does not 678521d3294cSantirezwork as an anchor, as this would prevent the iteration. 678621d3294cSantirez 678721d3294cSantirez 678821d3294cSantirez 678921d3294cSantirez 679021d3294cSantirez<p> 679121d3294cSantirez<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> 679221d3294cSantirezReturns a copy of <code>s</code> 679321d3294cSantirezin which all (or the first <code>n</code>, if given) 679421d3294cSantirezoccurrences of the <code>pattern</code> have been 679521d3294cSantirezreplaced by a replacement string specified by <code>repl</code>, 679621d3294cSantirezwhich can be a string, a table, or a function. 679721d3294cSantirez<code>gsub</code> also returns, as its second value, 679821d3294cSantirezthe total number of matches that occurred. 679921d3294cSantirez 680021d3294cSantirez 680121d3294cSantirez<p> 680221d3294cSantirezIf <code>repl</code> is a string, then its value is used for replacement. 680321d3294cSantirezThe character <code>%</code> works as an escape character: 680421d3294cSantirezany sequence in <code>repl</code> of the form <code>%<em>n</em></code>, 680521d3294cSantirezwith <em>n</em> between 1 and 9, 680621d3294cSantirezstands for the value of the <em>n</em>-th captured substring (see below). 680721d3294cSantirezThe sequence <code>%0</code> stands for the whole match. 680821d3294cSantirezThe sequence <code>%%</code> stands for a single <code>%</code>. 680921d3294cSantirez 681021d3294cSantirez 681121d3294cSantirez<p> 681221d3294cSantirezIf <code>repl</code> is a table, then the table is queried for every match, 681321d3294cSantirezusing the first capture as the key; 681421d3294cSantirezif the pattern specifies no captures, 681521d3294cSantirezthen the whole match is used as the key. 681621d3294cSantirez 681721d3294cSantirez 681821d3294cSantirez<p> 681921d3294cSantirezIf <code>repl</code> is a function, then this function is called every time a 682021d3294cSantirezmatch occurs, with all captured substrings passed as arguments, 682121d3294cSantirezin order; 682221d3294cSantirezif the pattern specifies no captures, 682321d3294cSantirezthen the whole match is passed as a sole argument. 682421d3294cSantirez 682521d3294cSantirez 682621d3294cSantirez<p> 682721d3294cSantirezIf the value returned by the table query or by the function call 682821d3294cSantirezis a string or a number, 682921d3294cSantirezthen it is used as the replacement string; 683021d3294cSantirezotherwise, if it is <b>false</b> or <b>nil</b>, 683121d3294cSantirezthen there is no replacement 683221d3294cSantirez(that is, the original match is kept in the string). 683321d3294cSantirez 683421d3294cSantirez 683521d3294cSantirez<p> 683621d3294cSantirezHere are some examples: 683721d3294cSantirez 683821d3294cSantirez<pre> 683921d3294cSantirez x = string.gsub("hello world", "(%w+)", "%1 %1") 684021d3294cSantirez --> x="hello hello world world" 684121d3294cSantirez 684221d3294cSantirez x = string.gsub("hello world", "%w+", "%0 %0", 1) 684321d3294cSantirez --> x="hello hello world" 684421d3294cSantirez 684521d3294cSantirez x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 684621d3294cSantirez --> x="world hello Lua from" 684721d3294cSantirez 684821d3294cSantirez x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) 684921d3294cSantirez --> x="home = /home/roberto, user = roberto" 685021d3294cSantirez 685121d3294cSantirez x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 685221d3294cSantirez return loadstring(s)() 685321d3294cSantirez end) 685421d3294cSantirez --> x="4+5 = 9" 685521d3294cSantirez 685621d3294cSantirez local t = {name="lua", version="5.1"} 685721d3294cSantirez x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 685821d3294cSantirez --> x="lua-5.1.tar.gz" 685921d3294cSantirez</pre> 686021d3294cSantirez 686121d3294cSantirez 686221d3294cSantirez 686321d3294cSantirez<p> 686421d3294cSantirez<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> 686521d3294cSantirezReceives a string and returns its length. 686621d3294cSantirezThe empty string <code>""</code> has length 0. 686721d3294cSantirezEmbedded zeros are counted, 686821d3294cSantirezso <code>"a\000bc\000"</code> has length 5. 686921d3294cSantirez 687021d3294cSantirez 687121d3294cSantirez 687221d3294cSantirez 687321d3294cSantirez<p> 687421d3294cSantirez<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> 687521d3294cSantirezReceives a string and returns a copy of this string with all 687621d3294cSantirezuppercase letters changed to lowercase. 687721d3294cSantirezAll other characters are left unchanged. 687821d3294cSantirezThe definition of what an uppercase letter is depends on the current locale. 687921d3294cSantirez 688021d3294cSantirez 688121d3294cSantirez 688221d3294cSantirez 688321d3294cSantirez<p> 688421d3294cSantirez<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> 688521d3294cSantirezLooks for the first <em>match</em> of 688621d3294cSantirez<code>pattern</code> in the string <code>s</code>. 688721d3294cSantirezIf it finds one, then <code>match</code> returns 688821d3294cSantirezthe captures from the pattern; 688921d3294cSantirezotherwise it returns <b>nil</b>. 689021d3294cSantirezIf <code>pattern</code> specifies no captures, 689121d3294cSantirezthen the whole match is returned. 689221d3294cSantirezA third, optional numerical argument <code>init</code> specifies 689321d3294cSantirezwhere to start the search; 689421d3294cSantirezits default value is 1 and can be negative. 689521d3294cSantirez 689621d3294cSantirez 689721d3294cSantirez 689821d3294cSantirez 689921d3294cSantirez<p> 690021d3294cSantirez<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n)</code></a></h3> 690121d3294cSantirezReturns a string that is the concatenation of <code>n</code> copies of 690221d3294cSantirezthe string <code>s</code>. 690321d3294cSantirez 690421d3294cSantirez 690521d3294cSantirez 690621d3294cSantirez 690721d3294cSantirez<p> 690821d3294cSantirez<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> 690921d3294cSantirezReturns a string that is the string <code>s</code> reversed. 691021d3294cSantirez 691121d3294cSantirez 691221d3294cSantirez 691321d3294cSantirez 691421d3294cSantirez<p> 691521d3294cSantirez<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> 691621d3294cSantirezReturns the substring of <code>s</code> that 691721d3294cSantirezstarts at <code>i</code> and continues until <code>j</code>; 691821d3294cSantirez<code>i</code> and <code>j</code> can be negative. 691921d3294cSantirezIf <code>j</code> is absent, then it is assumed to be equal to -1 692021d3294cSantirez(which is the same as the string length). 692121d3294cSantirezIn particular, 692221d3294cSantirezthe call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 692321d3294cSantirezwith length <code>j</code>, 692421d3294cSantirezand <code>string.sub(s, -i)</code> returns a suffix of <code>s</code> 692521d3294cSantirezwith length <code>i</code>. 692621d3294cSantirez 692721d3294cSantirez 692821d3294cSantirez 692921d3294cSantirez 693021d3294cSantirez<p> 693121d3294cSantirez<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> 693221d3294cSantirezReceives a string and returns a copy of this string with all 693321d3294cSantirezlowercase letters changed to uppercase. 693421d3294cSantirezAll other characters are left unchanged. 693521d3294cSantirezThe definition of what a lowercase letter is depends on the current locale. 693621d3294cSantirez 693721d3294cSantirez 693821d3294cSantirez 693921d3294cSantirez<h3>5.4.1 - <a name="5.4.1">Patterns</a></h3> 694021d3294cSantirez 694121d3294cSantirez 694221d3294cSantirez<h4>Character Class:</h4><p> 694321d3294cSantirezA <em>character class</em> is used to represent a set of characters. 694421d3294cSantirezThe following combinations are allowed in describing a character class: 694521d3294cSantirez 694621d3294cSantirez<ul> 694721d3294cSantirez 694821d3294cSantirez<li><b><em>x</em>:</b> 694921d3294cSantirez(where <em>x</em> is not one of the <em>magic characters</em> 695021d3294cSantirez<code>^$()%.[]*+-?</code>) 695121d3294cSantirezrepresents the character <em>x</em> itself. 695221d3294cSantirez</li> 695321d3294cSantirez 695421d3294cSantirez<li><b><code>.</code>:</b> (a dot) represents all characters.</li> 695521d3294cSantirez 695621d3294cSantirez<li><b><code>%a</code>:</b> represents all letters.</li> 695721d3294cSantirez 695821d3294cSantirez<li><b><code>%c</code>:</b> represents all control characters.</li> 695921d3294cSantirez 696021d3294cSantirez<li><b><code>%d</code>:</b> represents all digits.</li> 696121d3294cSantirez 696221d3294cSantirez<li><b><code>%l</code>:</b> represents all lowercase letters.</li> 696321d3294cSantirez 696421d3294cSantirez<li><b><code>%p</code>:</b> represents all punctuation characters.</li> 696521d3294cSantirez 696621d3294cSantirez<li><b><code>%s</code>:</b> represents all space characters.</li> 696721d3294cSantirez 696821d3294cSantirez<li><b><code>%u</code>:</b> represents all uppercase letters.</li> 696921d3294cSantirez 697021d3294cSantirez<li><b><code>%w</code>:</b> represents all alphanumeric characters.</li> 697121d3294cSantirez 697221d3294cSantirez<li><b><code>%x</code>:</b> represents all hexadecimal digits.</li> 697321d3294cSantirez 697421d3294cSantirez<li><b><code>%z</code>:</b> represents the character with representation 0.</li> 697521d3294cSantirez 697621d3294cSantirez<li><b><code>%<em>x</em></code>:</b> (where <em>x</em> is any non-alphanumeric character) 697721d3294cSantirezrepresents the character <em>x</em>. 697821d3294cSantirezThis is the standard way to escape the magic characters. 697921d3294cSantirezAny punctuation character (even the non magic) 698021d3294cSantirezcan be preceded by a '<code>%</code>' 698121d3294cSantirezwhen used to represent itself in a pattern. 698221d3294cSantirez</li> 698321d3294cSantirez 698421d3294cSantirez<li><b><code>[<em>set</em>]</code>:</b> 698521d3294cSantirezrepresents the class which is the union of all 698621d3294cSantirezcharacters in <em>set</em>. 698721d3294cSantirezA range of characters can be specified by 698821d3294cSantirezseparating the end characters of the range with a '<code>-</code>'. 698921d3294cSantirezAll classes <code>%</code><em>x</em> described above can also be used as 699021d3294cSantirezcomponents in <em>set</em>. 699121d3294cSantirezAll other characters in <em>set</em> represent themselves. 699221d3294cSantirezFor example, <code>[%w_]</code> (or <code>[_%w]</code>) 699321d3294cSantirezrepresents all alphanumeric characters plus the underscore, 699421d3294cSantirez<code>[0-7]</code> represents the octal digits, 699521d3294cSantirezand <code>[0-7%l%-]</code> represents the octal digits plus 699621d3294cSantirezthe lowercase letters plus the '<code>-</code>' character. 699721d3294cSantirez 699821d3294cSantirez 699921d3294cSantirez<p> 700021d3294cSantirezThe interaction between ranges and classes is not defined. 700121d3294cSantirezTherefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> 700221d3294cSantirezhave no meaning. 700321d3294cSantirez</li> 700421d3294cSantirez 700521d3294cSantirez<li><b><code>[^<em>set</em>]</code>:</b> 700621d3294cSantirezrepresents the complement of <em>set</em>, 700721d3294cSantirezwhere <em>set</em> is interpreted as above. 700821d3294cSantirez</li> 700921d3294cSantirez 701021d3294cSantirez</ul><p> 701121d3294cSantirezFor all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), 701221d3294cSantirezthe corresponding uppercase letter represents the complement of the class. 701321d3294cSantirezFor instance, <code>%S</code> represents all non-space characters. 701421d3294cSantirez 701521d3294cSantirez 701621d3294cSantirez<p> 701721d3294cSantirezThe definitions of letter, space, and other character groups 701821d3294cSantirezdepend on the current locale. 701921d3294cSantirezIn particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. 702021d3294cSantirez 702121d3294cSantirez 702221d3294cSantirez 702321d3294cSantirez 702421d3294cSantirez 702521d3294cSantirez<h4>Pattern Item:</h4><p> 702621d3294cSantirezA <em>pattern item</em> can be 702721d3294cSantirez 702821d3294cSantirez<ul> 702921d3294cSantirez 703021d3294cSantirez<li> 703121d3294cSantireza single character class, 703221d3294cSantirezwhich matches any single character in the class; 703321d3294cSantirez</li> 703421d3294cSantirez 703521d3294cSantirez<li> 703621d3294cSantireza single character class followed by '<code>*</code>', 703721d3294cSantirezwhich matches 0 or more repetitions of characters in the class. 703821d3294cSantirezThese repetition items will always match the longest possible sequence; 703921d3294cSantirez</li> 704021d3294cSantirez 704121d3294cSantirez<li> 704221d3294cSantireza single character class followed by '<code>+</code>', 704321d3294cSantirezwhich matches 1 or more repetitions of characters in the class. 704421d3294cSantirezThese repetition items will always match the longest possible sequence; 704521d3294cSantirez</li> 704621d3294cSantirez 704721d3294cSantirez<li> 704821d3294cSantireza single character class followed by '<code>-</code>', 704921d3294cSantirezwhich also matches 0 or more repetitions of characters in the class. 705021d3294cSantirezUnlike '<code>*</code>', 705121d3294cSantirezthese repetition items will always match the <em>shortest</em> possible sequence; 705221d3294cSantirez</li> 705321d3294cSantirez 705421d3294cSantirez<li> 705521d3294cSantireza single character class followed by '<code>?</code>', 705621d3294cSantirezwhich matches 0 or 1 occurrence of a character in the class; 705721d3294cSantirez</li> 705821d3294cSantirez 705921d3294cSantirez<li> 706021d3294cSantirez<code>%<em>n</em></code>, for <em>n</em> between 1 and 9; 706121d3294cSantirezsuch item matches a substring equal to the <em>n</em>-th captured string 706221d3294cSantirez(see below); 706321d3294cSantirez</li> 706421d3294cSantirez 706521d3294cSantirez<li> 706621d3294cSantirez<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; 706721d3294cSantirezsuch item matches strings that start with <em>x</em>, end with <em>y</em>, 706821d3294cSantirezand where the <em>x</em> and <em>y</em> are <em>balanced</em>. 706921d3294cSantirezThis means that, if one reads the string from left to right, 707021d3294cSantirezcounting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, 707121d3294cSantirezthe ending <em>y</em> is the first <em>y</em> where the count reaches 0. 707221d3294cSantirezFor instance, the item <code>%b()</code> matches expressions with 707321d3294cSantirezbalanced parentheses. 707421d3294cSantirez</li> 707521d3294cSantirez 707621d3294cSantirez</ul> 707721d3294cSantirez 707821d3294cSantirez 707921d3294cSantirez 708021d3294cSantirez 708121d3294cSantirez<h4>Pattern:</h4><p> 708221d3294cSantirezA <em>pattern</em> is a sequence of pattern items. 708321d3294cSantirezA '<code>^</code>' at the beginning of a pattern anchors the match at the 708421d3294cSantirezbeginning of the subject string. 708521d3294cSantirezA '<code>$</code>' at the end of a pattern anchors the match at the 708621d3294cSantirezend of the subject string. 708721d3294cSantirezAt other positions, 708821d3294cSantirez'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. 708921d3294cSantirez 709021d3294cSantirez 709121d3294cSantirez 709221d3294cSantirez 709321d3294cSantirez 709421d3294cSantirez<h4>Captures:</h4><p> 709521d3294cSantirezA pattern can contain sub-patterns enclosed in parentheses; 709621d3294cSantirezthey describe <em>captures</em>. 709721d3294cSantirezWhen a match succeeds, the substrings of the subject string 709821d3294cSantirezthat match captures are stored (<em>captured</em>) for future use. 709921d3294cSantirezCaptures are numbered according to their left parentheses. 710021d3294cSantirezFor instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, 710121d3294cSantirezthe part of the string matching <code>"a*(.)%w(%s*)"</code> is 710221d3294cSantirezstored as the first capture (and therefore has number 1); 710321d3294cSantirezthe character matching "<code>.</code>" is captured with number 2, 710421d3294cSantirezand the part matching "<code>%s*</code>" has number 3. 710521d3294cSantirez 710621d3294cSantirez 710721d3294cSantirez<p> 710821d3294cSantirezAs a special case, the empty capture <code>()</code> captures 710921d3294cSantirezthe current string position (a number). 711021d3294cSantirezFor instance, if we apply the pattern <code>"()aa()"</code> on the 711121d3294cSantirezstring <code>"flaaap"</code>, there will be two captures: 3 and 5. 711221d3294cSantirez 711321d3294cSantirez 711421d3294cSantirez<p> 711521d3294cSantirezA pattern cannot contain embedded zeros. Use <code>%z</code> instead. 711621d3294cSantirez 711721d3294cSantirez 711821d3294cSantirez 711921d3294cSantirez 712021d3294cSantirez 712121d3294cSantirez 712221d3294cSantirez 712321d3294cSantirez 712421d3294cSantirez 712521d3294cSantirez 712621d3294cSantirez 712721d3294cSantirez<h2>5.5 - <a name="5.5">Table Manipulation</a></h2><p> 712821d3294cSantirezThis library provides generic functions for table manipulation. 712921d3294cSantirezIt provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. 713021d3294cSantirez 713121d3294cSantirez 713221d3294cSantirez<p> 713321d3294cSantirezMost functions in the table library assume that the table 713421d3294cSantirezrepresents an array or a list. 713521d3294cSantirezFor these functions, when we talk about the "length" of a table 713621d3294cSantirezwe mean the result of the length operator. 713721d3294cSantirez 713821d3294cSantirez 713921d3294cSantirez<p> 714021d3294cSantirez<hr><h3><a name="pdf-table.concat"><code>table.concat (table [, sep [, i [, j]]])</code></a></h3> 714121d3294cSantirezGiven an array where all elements are strings or numbers, 714221d3294cSantirezreturns <code>table[i]..sep..table[i+1] ··· sep..table[j]</code>. 714321d3294cSantirezThe default value for <code>sep</code> is the empty string, 714421d3294cSantirezthe default for <code>i</code> is 1, 714521d3294cSantirezand the default for <code>j</code> is the length of the table. 714621d3294cSantirezIf <code>i</code> is greater than <code>j</code>, returns the empty string. 714721d3294cSantirez 714821d3294cSantirez 714921d3294cSantirez 715021d3294cSantirez 715121d3294cSantirez<p> 715221d3294cSantirez<hr><h3><a name="pdf-table.insert"><code>table.insert (table, [pos,] value)</code></a></h3> 715321d3294cSantirez 715421d3294cSantirez 715521d3294cSantirez<p> 715621d3294cSantirezInserts element <code>value</code> at position <code>pos</code> in <code>table</code>, 715721d3294cSantirezshifting up other elements to open space, if necessary. 715821d3294cSantirezThe default value for <code>pos</code> is <code>n+1</code>, 715921d3294cSantirezwhere <code>n</code> is the length of the table (see <a href="#2.5.5">§2.5.5</a>), 716021d3294cSantirezso that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end 716121d3294cSantirezof table <code>t</code>. 716221d3294cSantirez 716321d3294cSantirez 716421d3294cSantirez 716521d3294cSantirez 716621d3294cSantirez<p> 716721d3294cSantirez<hr><h3><a name="pdf-table.maxn"><code>table.maxn (table)</code></a></h3> 716821d3294cSantirez 716921d3294cSantirez 717021d3294cSantirez<p> 717121d3294cSantirezReturns the largest positive numerical index of the given table, 717221d3294cSantirezor zero if the table has no positive numerical indices. 717321d3294cSantirez(To do its job this function does a linear traversal of 717421d3294cSantirezthe whole table.) 717521d3294cSantirez 717621d3294cSantirez 717721d3294cSantirez 717821d3294cSantirez 717921d3294cSantirez<p> 718021d3294cSantirez<hr><h3><a name="pdf-table.remove"><code>table.remove (table [, pos])</code></a></h3> 718121d3294cSantirez 718221d3294cSantirez 718321d3294cSantirez<p> 718421d3294cSantirezRemoves from <code>table</code> the element at position <code>pos</code>, 718521d3294cSantirezshifting down other elements to close the space, if necessary. 718621d3294cSantirezReturns the value of the removed element. 718721d3294cSantirezThe default value for <code>pos</code> is <code>n</code>, 718821d3294cSantirezwhere <code>n</code> is the length of the table, 718921d3294cSantirezso that a call <code>table.remove(t)</code> removes the last element 719021d3294cSantirezof table <code>t</code>. 719121d3294cSantirez 719221d3294cSantirez 719321d3294cSantirez 719421d3294cSantirez 719521d3294cSantirez<p> 719621d3294cSantirez<hr><h3><a name="pdf-table.sort"><code>table.sort (table [, comp])</code></a></h3> 719721d3294cSantirezSorts table elements in a given order, <em>in-place</em>, 719821d3294cSantirezfrom <code>table[1]</code> to <code>table[n]</code>, 719921d3294cSantirezwhere <code>n</code> is the length of the table. 720021d3294cSantirezIf <code>comp</code> is given, 720121d3294cSantirezthen it must be a function that receives two table elements, 720221d3294cSantirezand returns true 720321d3294cSantirezwhen the first is less than the second 720421d3294cSantirez(so that <code>not comp(a[i+1],a[i])</code> will be true after the sort). 720521d3294cSantirezIf <code>comp</code> is not given, 720621d3294cSantirezthen the standard Lua operator <code><</code> is used instead. 720721d3294cSantirez 720821d3294cSantirez 720921d3294cSantirez<p> 721021d3294cSantirezThe sort algorithm is not stable; 721121d3294cSantirezthat is, elements considered equal by the given order 721221d3294cSantirezmay have their relative positions changed by the sort. 721321d3294cSantirez 721421d3294cSantirez 721521d3294cSantirez 721621d3294cSantirez 721721d3294cSantirez 721821d3294cSantirez 721921d3294cSantirez 722021d3294cSantirez<h2>5.6 - <a name="5.6">Mathematical Functions</a></h2> 722121d3294cSantirez 722221d3294cSantirez<p> 722321d3294cSantirezThis library is an interface to the standard C math library. 722421d3294cSantirezIt provides all its functions inside the table <a name="pdf-math"><code>math</code></a>. 722521d3294cSantirez 722621d3294cSantirez 722721d3294cSantirez<p> 722821d3294cSantirez<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> 722921d3294cSantirez 723021d3294cSantirez 723121d3294cSantirez<p> 723221d3294cSantirezReturns the absolute value of <code>x</code>. 723321d3294cSantirez 723421d3294cSantirez 723521d3294cSantirez 723621d3294cSantirez 723721d3294cSantirez<p> 723821d3294cSantirez<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> 723921d3294cSantirez 724021d3294cSantirez 724121d3294cSantirez<p> 724221d3294cSantirezReturns the arc cosine of <code>x</code> (in radians). 724321d3294cSantirez 724421d3294cSantirez 724521d3294cSantirez 724621d3294cSantirez 724721d3294cSantirez<p> 724821d3294cSantirez<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> 724921d3294cSantirez 725021d3294cSantirez 725121d3294cSantirez<p> 725221d3294cSantirezReturns the arc sine of <code>x</code> (in radians). 725321d3294cSantirez 725421d3294cSantirez 725521d3294cSantirez 725621d3294cSantirez 725721d3294cSantirez<p> 725821d3294cSantirez<hr><h3><a name="pdf-math.atan"><code>math.atan (x)</code></a></h3> 725921d3294cSantirez 726021d3294cSantirez 726121d3294cSantirez<p> 726221d3294cSantirezReturns the arc tangent of <code>x</code> (in radians). 726321d3294cSantirez 726421d3294cSantirez 726521d3294cSantirez 726621d3294cSantirez 726721d3294cSantirez<p> 726821d3294cSantirez<hr><h3><a name="pdf-math.atan2"><code>math.atan2 (y, x)</code></a></h3> 726921d3294cSantirez 727021d3294cSantirez 727121d3294cSantirez<p> 727221d3294cSantirezReturns the arc tangent of <code>y/x</code> (in radians), 727321d3294cSantirezbut uses the signs of both parameters to find the 727421d3294cSantirezquadrant of the result. 727521d3294cSantirez(It also handles correctly the case of <code>x</code> being zero.) 727621d3294cSantirez 727721d3294cSantirez 727821d3294cSantirez 727921d3294cSantirez 728021d3294cSantirez<p> 728121d3294cSantirez<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> 728221d3294cSantirez 728321d3294cSantirez 728421d3294cSantirez<p> 728521d3294cSantirezReturns the smallest integer larger than or equal to <code>x</code>. 728621d3294cSantirez 728721d3294cSantirez 728821d3294cSantirez 728921d3294cSantirez 729021d3294cSantirez<p> 729121d3294cSantirez<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> 729221d3294cSantirez 729321d3294cSantirez 729421d3294cSantirez<p> 729521d3294cSantirezReturns the cosine of <code>x</code> (assumed to be in radians). 729621d3294cSantirez 729721d3294cSantirez 729821d3294cSantirez 729921d3294cSantirez 730021d3294cSantirez<p> 730121d3294cSantirez<hr><h3><a name="pdf-math.cosh"><code>math.cosh (x)</code></a></h3> 730221d3294cSantirez 730321d3294cSantirez 730421d3294cSantirez<p> 730521d3294cSantirezReturns the hyperbolic cosine of <code>x</code>. 730621d3294cSantirez 730721d3294cSantirez 730821d3294cSantirez 730921d3294cSantirez 731021d3294cSantirez<p> 731121d3294cSantirez<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> 731221d3294cSantirez 731321d3294cSantirez 731421d3294cSantirez<p> 731521d3294cSantirezReturns the angle <code>x</code> (given in radians) in degrees. 731621d3294cSantirez 731721d3294cSantirez 731821d3294cSantirez 731921d3294cSantirez 732021d3294cSantirez<p> 732121d3294cSantirez<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> 732221d3294cSantirez 732321d3294cSantirez 732421d3294cSantirez<p> 732521d3294cSantirezReturns the value <em>e<sup>x</sup></em>. 732621d3294cSantirez 732721d3294cSantirez 732821d3294cSantirez 732921d3294cSantirez 733021d3294cSantirez<p> 733121d3294cSantirez<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> 733221d3294cSantirez 733321d3294cSantirez 733421d3294cSantirez<p> 733521d3294cSantirezReturns the largest integer smaller than or equal to <code>x</code>. 733621d3294cSantirez 733721d3294cSantirez 733821d3294cSantirez 733921d3294cSantirez 734021d3294cSantirez<p> 734121d3294cSantirez<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> 734221d3294cSantirez 734321d3294cSantirez 734421d3294cSantirez<p> 734521d3294cSantirezReturns the remainder of the division of <code>x</code> by <code>y</code> 734621d3294cSantirezthat rounds the quotient towards zero. 734721d3294cSantirez 734821d3294cSantirez 734921d3294cSantirez 735021d3294cSantirez 735121d3294cSantirez<p> 735221d3294cSantirez<hr><h3><a name="pdf-math.frexp"><code>math.frexp (x)</code></a></h3> 735321d3294cSantirez 735421d3294cSantirez 735521d3294cSantirez<p> 735621d3294cSantirezReturns <code>m</code> and <code>e</code> such that <em>x = m2<sup>e</sup></em>, 735721d3294cSantirez<code>e</code> is an integer and the absolute value of <code>m</code> is 735821d3294cSantirezin the range <em>[0.5, 1)</em> 735921d3294cSantirez(or zero when <code>x</code> is zero). 736021d3294cSantirez 736121d3294cSantirez 736221d3294cSantirez 736321d3294cSantirez 736421d3294cSantirez<p> 736521d3294cSantirez<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> 736621d3294cSantirez 736721d3294cSantirez 736821d3294cSantirez<p> 736921d3294cSantirezThe value <code>HUGE_VAL</code>, 737021d3294cSantireza value larger than or equal to any other numerical value. 737121d3294cSantirez 737221d3294cSantirez 737321d3294cSantirez 737421d3294cSantirez 737521d3294cSantirez<p> 737621d3294cSantirez<hr><h3><a name="pdf-math.ldexp"><code>math.ldexp (m, e)</code></a></h3> 737721d3294cSantirez 737821d3294cSantirez 737921d3294cSantirez<p> 738021d3294cSantirezReturns <em>m2<sup>e</sup></em> (<code>e</code> should be an integer). 738121d3294cSantirez 738221d3294cSantirez 738321d3294cSantirez 738421d3294cSantirez 738521d3294cSantirez<p> 738621d3294cSantirez<hr><h3><a name="pdf-math.log"><code>math.log (x)</code></a></h3> 738721d3294cSantirez 738821d3294cSantirez 738921d3294cSantirez<p> 739021d3294cSantirezReturns the natural logarithm of <code>x</code>. 739121d3294cSantirez 739221d3294cSantirez 739321d3294cSantirez 739421d3294cSantirez 739521d3294cSantirez<p> 739621d3294cSantirez<hr><h3><a name="pdf-math.log10"><code>math.log10 (x)</code></a></h3> 739721d3294cSantirez 739821d3294cSantirez 739921d3294cSantirez<p> 740021d3294cSantirezReturns the base-10 logarithm of <code>x</code>. 740121d3294cSantirez 740221d3294cSantirez 740321d3294cSantirez 740421d3294cSantirez 740521d3294cSantirez<p> 740621d3294cSantirez<hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> 740721d3294cSantirez 740821d3294cSantirez 740921d3294cSantirez<p> 741021d3294cSantirezReturns the maximum value among its arguments. 741121d3294cSantirez 741221d3294cSantirez 741321d3294cSantirez 741421d3294cSantirez 741521d3294cSantirez<p> 741621d3294cSantirez<hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> 741721d3294cSantirez 741821d3294cSantirez 741921d3294cSantirez<p> 742021d3294cSantirezReturns the minimum value among its arguments. 742121d3294cSantirez 742221d3294cSantirez 742321d3294cSantirez 742421d3294cSantirez 742521d3294cSantirez<p> 742621d3294cSantirez<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> 742721d3294cSantirez 742821d3294cSantirez 742921d3294cSantirez<p> 743021d3294cSantirezReturns two numbers, 743121d3294cSantirezthe integral part of <code>x</code> and the fractional part of <code>x</code>. 743221d3294cSantirez 743321d3294cSantirez 743421d3294cSantirez 743521d3294cSantirez 743621d3294cSantirez<p> 743721d3294cSantirez<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> 743821d3294cSantirez 743921d3294cSantirez 744021d3294cSantirez<p> 744121d3294cSantirezThe value of <em>pi</em>. 744221d3294cSantirez 744321d3294cSantirez 744421d3294cSantirez 744521d3294cSantirez 744621d3294cSantirez<p> 744721d3294cSantirez<hr><h3><a name="pdf-math.pow"><code>math.pow (x, y)</code></a></h3> 744821d3294cSantirez 744921d3294cSantirez 745021d3294cSantirez<p> 745121d3294cSantirezReturns <em>x<sup>y</sup></em>. 745221d3294cSantirez(You can also use the expression <code>x^y</code> to compute this value.) 745321d3294cSantirez 745421d3294cSantirez 745521d3294cSantirez 745621d3294cSantirez 745721d3294cSantirez<p> 745821d3294cSantirez<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> 745921d3294cSantirez 746021d3294cSantirez 746121d3294cSantirez<p> 746221d3294cSantirezReturns the angle <code>x</code> (given in degrees) in radians. 746321d3294cSantirez 746421d3294cSantirez 746521d3294cSantirez 746621d3294cSantirez 746721d3294cSantirez<p> 746821d3294cSantirez<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> 746921d3294cSantirez 747021d3294cSantirez 747121d3294cSantirez<p> 747221d3294cSantirezThis function is an interface to the simple 747321d3294cSantirezpseudo-random generator function <code>rand</code> provided by ANSI C. 747421d3294cSantirez(No guarantees can be given for its statistical properties.) 747521d3294cSantirez 747621d3294cSantirez 747721d3294cSantirez<p> 747821d3294cSantirezWhen called without arguments, 747921d3294cSantirezreturns a uniform pseudo-random real number 748021d3294cSantirezin the range <em>[0,1)</em>. 748121d3294cSantirezWhen called with an integer number <code>m</code>, 748221d3294cSantirez<code>math.random</code> returns 748321d3294cSantireza uniform pseudo-random integer in the range <em>[1, m]</em>. 748421d3294cSantirezWhen called with two integer numbers <code>m</code> and <code>n</code>, 748521d3294cSantirez<code>math.random</code> returns a uniform pseudo-random 748621d3294cSantirezinteger in the range <em>[m, n]</em>. 748721d3294cSantirez 748821d3294cSantirez 748921d3294cSantirez 749021d3294cSantirez 749121d3294cSantirez<p> 749221d3294cSantirez<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3> 749321d3294cSantirez 749421d3294cSantirez 749521d3294cSantirez<p> 749621d3294cSantirezSets <code>x</code> as the "seed" 749721d3294cSantirezfor the pseudo-random generator: 749821d3294cSantirezequal seeds produce equal sequences of numbers. 749921d3294cSantirez 750021d3294cSantirez 750121d3294cSantirez 750221d3294cSantirez 750321d3294cSantirez<p> 750421d3294cSantirez<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> 750521d3294cSantirez 750621d3294cSantirez 750721d3294cSantirez<p> 750821d3294cSantirezReturns the sine of <code>x</code> (assumed to be in radians). 750921d3294cSantirez 751021d3294cSantirez 751121d3294cSantirez 751221d3294cSantirez 751321d3294cSantirez<p> 751421d3294cSantirez<hr><h3><a name="pdf-math.sinh"><code>math.sinh (x)</code></a></h3> 751521d3294cSantirez 751621d3294cSantirez 751721d3294cSantirez<p> 751821d3294cSantirezReturns the hyperbolic sine of <code>x</code>. 751921d3294cSantirez 752021d3294cSantirez 752121d3294cSantirez 752221d3294cSantirez 752321d3294cSantirez<p> 752421d3294cSantirez<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> 752521d3294cSantirez 752621d3294cSantirez 752721d3294cSantirez<p> 752821d3294cSantirezReturns the square root of <code>x</code>. 752921d3294cSantirez(You can also use the expression <code>x^0.5</code> to compute this value.) 753021d3294cSantirez 753121d3294cSantirez 753221d3294cSantirez 753321d3294cSantirez 753421d3294cSantirez<p> 753521d3294cSantirez<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> 753621d3294cSantirez 753721d3294cSantirez 753821d3294cSantirez<p> 753921d3294cSantirezReturns the tangent of <code>x</code> (assumed to be in radians). 754021d3294cSantirez 754121d3294cSantirez 754221d3294cSantirez 754321d3294cSantirez 754421d3294cSantirez<p> 754521d3294cSantirez<hr><h3><a name="pdf-math.tanh"><code>math.tanh (x)</code></a></h3> 754621d3294cSantirez 754721d3294cSantirez 754821d3294cSantirez<p> 754921d3294cSantirezReturns the hyperbolic tangent of <code>x</code>. 755021d3294cSantirez 755121d3294cSantirez 755221d3294cSantirez 755321d3294cSantirez 755421d3294cSantirez 755521d3294cSantirez 755621d3294cSantirez 755721d3294cSantirez<h2>5.7 - <a name="5.7">Input and Output Facilities</a></h2> 755821d3294cSantirez 755921d3294cSantirez<p> 756021d3294cSantirezThe I/O library provides two different styles for file manipulation. 756121d3294cSantirezThe first one uses implicit file descriptors; 756221d3294cSantirezthat is, there are operations to set a default input file and a 756321d3294cSantirezdefault output file, 756421d3294cSantirezand all input/output operations are over these default files. 756521d3294cSantirezThe second style uses explicit file descriptors. 756621d3294cSantirez 756721d3294cSantirez 756821d3294cSantirez<p> 756921d3294cSantirezWhen using implicit file descriptors, 757021d3294cSantirezall operations are supplied by table <a name="pdf-io"><code>io</code></a>. 757121d3294cSantirezWhen using explicit file descriptors, 757221d3294cSantirezthe operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file descriptor 757321d3294cSantirezand then all operations are supplied as methods of the file descriptor. 757421d3294cSantirez 757521d3294cSantirez 757621d3294cSantirez<p> 757721d3294cSantirezThe table <code>io</code> also provides 757821d3294cSantirezthree predefined file descriptors with their usual meanings from C: 757921d3294cSantirez<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>. 758021d3294cSantirezThe I/O library never closes these files. 758121d3294cSantirez 758221d3294cSantirez 758321d3294cSantirez<p> 758421d3294cSantirezUnless otherwise stated, 758521d3294cSantirezall I/O functions return <b>nil</b> on failure 758621d3294cSantirez(plus an error message as a second result and 758721d3294cSantireza system-dependent error code as a third result) 758821d3294cSantirezand some value different from <b>nil</b> on success. 758921d3294cSantirez 759021d3294cSantirez 759121d3294cSantirez<p> 759221d3294cSantirez<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> 759321d3294cSantirez 759421d3294cSantirez 759521d3294cSantirez<p> 759621d3294cSantirezEquivalent to <code>file:close()</code>. 759721d3294cSantirezWithout a <code>file</code>, closes the default output file. 759821d3294cSantirez 759921d3294cSantirez 760021d3294cSantirez 760121d3294cSantirez 760221d3294cSantirez<p> 760321d3294cSantirez<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> 760421d3294cSantirez 760521d3294cSantirez 760621d3294cSantirez<p> 760721d3294cSantirezEquivalent to <code>file:flush</code> over the default output file. 760821d3294cSantirez 760921d3294cSantirez 761021d3294cSantirez 761121d3294cSantirez 761221d3294cSantirez<p> 761321d3294cSantirez<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> 761421d3294cSantirez 761521d3294cSantirez 761621d3294cSantirez<p> 761721d3294cSantirezWhen called with a file name, it opens the named file (in text mode), 761821d3294cSantirezand sets its handle as the default input file. 761921d3294cSantirezWhen called with a file handle, 762021d3294cSantirezit simply sets this file handle as the default input file. 762121d3294cSantirezWhen called without parameters, 762221d3294cSantirezit returns the current default input file. 762321d3294cSantirez 762421d3294cSantirez 762521d3294cSantirez<p> 762621d3294cSantirezIn case of errors this function raises the error, 762721d3294cSantirezinstead of returning an error code. 762821d3294cSantirez 762921d3294cSantirez 763021d3294cSantirez 763121d3294cSantirez 763221d3294cSantirez<p> 763321d3294cSantirez<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename])</code></a></h3> 763421d3294cSantirez 763521d3294cSantirez 763621d3294cSantirez<p> 763721d3294cSantirezOpens the given file name in read mode 763821d3294cSantirezand returns an iterator function that, 763921d3294cSantirezeach time it is called, 764021d3294cSantirezreturns a new line from the file. 764121d3294cSantirezTherefore, the construction 764221d3294cSantirez 764321d3294cSantirez<pre> 764421d3294cSantirez for line in io.lines(filename) do <em>body</em> end 764521d3294cSantirez</pre><p> 764621d3294cSantirezwill iterate over all lines of the file. 764721d3294cSantirezWhen the iterator function detects the end of file, 764821d3294cSantirezit returns <b>nil</b> (to finish the loop) and automatically closes the file. 764921d3294cSantirez 765021d3294cSantirez 765121d3294cSantirez<p> 765221d3294cSantirezThe call <code>io.lines()</code> (with no file name) is equivalent 765321d3294cSantirezto <code>io.input():lines()</code>; 765421d3294cSantirezthat is, it iterates over the lines of the default input file. 765521d3294cSantirezIn this case it does not close the file when the loop ends. 765621d3294cSantirez 765721d3294cSantirez 765821d3294cSantirez 765921d3294cSantirez 766021d3294cSantirez<p> 766121d3294cSantirez<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> 766221d3294cSantirez 766321d3294cSantirez 766421d3294cSantirez<p> 766521d3294cSantirezThis function opens a file, 766621d3294cSantirezin the mode specified in the string <code>mode</code>. 766721d3294cSantirezIt returns a new file handle, 766821d3294cSantirezor, in case of errors, <b>nil</b> plus an error message. 766921d3294cSantirez 767021d3294cSantirez 767121d3294cSantirez<p> 767221d3294cSantirezThe <code>mode</code> string can be any of the following: 767321d3294cSantirez 767421d3294cSantirez<ul> 767521d3294cSantirez<li><b>"r":</b> read mode (the default);</li> 767621d3294cSantirez<li><b>"w":</b> write mode;</li> 767721d3294cSantirez<li><b>"a":</b> append mode;</li> 767821d3294cSantirez<li><b>"r+":</b> update mode, all previous data is preserved;</li> 767921d3294cSantirez<li><b>"w+":</b> update mode, all previous data is erased;</li> 768021d3294cSantirez<li><b>"a+":</b> append update mode, previous data is preserved, 768121d3294cSantirez writing is only allowed at the end of file.</li> 768221d3294cSantirez</ul><p> 768321d3294cSantirezThe <code>mode</code> string can also have a '<code>b</code>' at the end, 768421d3294cSantirezwhich is needed in some systems to open the file in binary mode. 768521d3294cSantirezThis string is exactly what is used in the 768621d3294cSantirezstandard C function <code>fopen</code>. 768721d3294cSantirez 768821d3294cSantirez 768921d3294cSantirez 769021d3294cSantirez 769121d3294cSantirez<p> 769221d3294cSantirez<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> 769321d3294cSantirez 769421d3294cSantirez 769521d3294cSantirez<p> 769621d3294cSantirezSimilar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. 769721d3294cSantirez 769821d3294cSantirez 769921d3294cSantirez 770021d3294cSantirez 770121d3294cSantirez<p> 770221d3294cSantirez<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> 770321d3294cSantirez 770421d3294cSantirez 770521d3294cSantirez<p> 770621d3294cSantirezStarts program <code>prog</code> in a separated process and returns 770721d3294cSantireza file handle that you can use to read data from this program 770821d3294cSantirez(if <code>mode</code> is <code>"r"</code>, the default) 770921d3294cSantirezor to write data to this program 771021d3294cSantirez(if <code>mode</code> is <code>"w"</code>). 771121d3294cSantirez 771221d3294cSantirez 771321d3294cSantirez<p> 771421d3294cSantirezThis function is system dependent and is not available 771521d3294cSantirezon all platforms. 771621d3294cSantirez 771721d3294cSantirez 771821d3294cSantirez 771921d3294cSantirez 772021d3294cSantirez<p> 772121d3294cSantirez<hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> 772221d3294cSantirez 772321d3294cSantirez 772421d3294cSantirez<p> 772521d3294cSantirezEquivalent to <code>io.input():read</code>. 772621d3294cSantirez 772721d3294cSantirez 772821d3294cSantirez 772921d3294cSantirez 773021d3294cSantirez<p> 773121d3294cSantirez<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> 773221d3294cSantirez 773321d3294cSantirez 773421d3294cSantirez<p> 773521d3294cSantirezReturns a handle for a temporary file. 773621d3294cSantirezThis file is opened in update mode 773721d3294cSantirezand it is automatically removed when the program ends. 773821d3294cSantirez 773921d3294cSantirez 774021d3294cSantirez 774121d3294cSantirez 774221d3294cSantirez<p> 774321d3294cSantirez<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> 774421d3294cSantirez 774521d3294cSantirez 774621d3294cSantirez<p> 774721d3294cSantirezChecks whether <code>obj</code> is a valid file handle. 774821d3294cSantirezReturns the string <code>"file"</code> if <code>obj</code> is an open file handle, 774921d3294cSantirez<code>"closed file"</code> if <code>obj</code> is a closed file handle, 775021d3294cSantirezor <b>nil</b> if <code>obj</code> is not a file handle. 775121d3294cSantirez 775221d3294cSantirez 775321d3294cSantirez 775421d3294cSantirez 775521d3294cSantirez<p> 775621d3294cSantirez<hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> 775721d3294cSantirez 775821d3294cSantirez 775921d3294cSantirez<p> 776021d3294cSantirezEquivalent to <code>io.output():write</code>. 776121d3294cSantirez 776221d3294cSantirez 776321d3294cSantirez 776421d3294cSantirez 776521d3294cSantirez<p> 776621d3294cSantirez<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> 776721d3294cSantirez 776821d3294cSantirez 776921d3294cSantirez<p> 777021d3294cSantirezCloses <code>file</code>. 777121d3294cSantirezNote that files are automatically closed when 777221d3294cSantireztheir handles are garbage collected, 777321d3294cSantirezbut that takes an unpredictable amount of time to happen. 777421d3294cSantirez 777521d3294cSantirez 777621d3294cSantirez 777721d3294cSantirez 777821d3294cSantirez<p> 777921d3294cSantirez<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> 778021d3294cSantirez 778121d3294cSantirez 778221d3294cSantirez<p> 778321d3294cSantirezSaves any written data to <code>file</code>. 778421d3294cSantirez 778521d3294cSantirez 778621d3294cSantirez 778721d3294cSantirez 778821d3294cSantirez<p> 778921d3294cSantirez<hr><h3><a name="pdf-file:lines"><code>file:lines ()</code></a></h3> 779021d3294cSantirez 779121d3294cSantirez 779221d3294cSantirez<p> 779321d3294cSantirezReturns an iterator function that, 779421d3294cSantirezeach time it is called, 779521d3294cSantirezreturns a new line from the file. 779621d3294cSantirezTherefore, the construction 779721d3294cSantirez 779821d3294cSantirez<pre> 779921d3294cSantirez for line in file:lines() do <em>body</em> end 780021d3294cSantirez</pre><p> 780121d3294cSantirezwill iterate over all lines of the file. 780221d3294cSantirez(Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file 780321d3294cSantirezwhen the loop ends.) 780421d3294cSantirez 780521d3294cSantirez 780621d3294cSantirez 780721d3294cSantirez 780821d3294cSantirez<p> 780921d3294cSantirez<hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> 781021d3294cSantirez 781121d3294cSantirez 781221d3294cSantirez<p> 781321d3294cSantirezReads the file <code>file</code>, 781421d3294cSantirezaccording to the given formats, which specify what to read. 781521d3294cSantirezFor each format, 781621d3294cSantirezthe function returns a string (or a number) with the characters read, 781721d3294cSantirezor <b>nil</b> if it cannot read data with the specified format. 781821d3294cSantirezWhen called without formats, 781921d3294cSantirezit uses a default format that reads the entire next line 782021d3294cSantirez(see below). 782121d3294cSantirez 782221d3294cSantirez 782321d3294cSantirez<p> 782421d3294cSantirezThe available formats are 782521d3294cSantirez 782621d3294cSantirez<ul> 782721d3294cSantirez 782821d3294cSantirez<li><b>"*n":</b> 782921d3294cSantirezreads a number; 783021d3294cSantirezthis is the only format that returns a number instead of a string. 783121d3294cSantirez</li> 783221d3294cSantirez 783321d3294cSantirez<li><b>"*a":</b> 783421d3294cSantirezreads the whole file, starting at the current position. 783521d3294cSantirezOn end of file, it returns the empty string. 783621d3294cSantirez</li> 783721d3294cSantirez 783821d3294cSantirez<li><b>"*l":</b> 783921d3294cSantirezreads the next line (skipping the end of line), 784021d3294cSantirezreturning <b>nil</b> on end of file. 784121d3294cSantirezThis is the default format. 784221d3294cSantirez</li> 784321d3294cSantirez 784421d3294cSantirez<li><b><em>number</em>:</b> 784521d3294cSantirezreads a string with up to this number of characters, 784621d3294cSantirezreturning <b>nil</b> on end of file. 784721d3294cSantirezIf number is zero, 784821d3294cSantirezit reads nothing and returns an empty string, 784921d3294cSantirezor <b>nil</b> on end of file. 785021d3294cSantirez</li> 785121d3294cSantirez 785221d3294cSantirez</ul> 785321d3294cSantirez 785421d3294cSantirez 785521d3294cSantirez 785621d3294cSantirez<p> 785721d3294cSantirez<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence] [, offset])</code></a></h3> 785821d3294cSantirez 785921d3294cSantirez 786021d3294cSantirez<p> 786121d3294cSantirezSets and gets the file position, 786221d3294cSantirezmeasured from the beginning of the file, 786321d3294cSantirezto the position given by <code>offset</code> plus a base 786421d3294cSantirezspecified by the string <code>whence</code>, as follows: 786521d3294cSantirez 786621d3294cSantirez<ul> 786721d3294cSantirez<li><b>"set":</b> base is position 0 (beginning of the file);</li> 786821d3294cSantirez<li><b>"cur":</b> base is current position;</li> 786921d3294cSantirez<li><b>"end":</b> base is end of file;</li> 787021d3294cSantirez</ul><p> 787121d3294cSantirezIn case of success, function <code>seek</code> returns the final file position, 787221d3294cSantirezmeasured in bytes from the beginning of the file. 787321d3294cSantirezIf this function fails, it returns <b>nil</b>, 787421d3294cSantirezplus a string describing the error. 787521d3294cSantirez 787621d3294cSantirez 787721d3294cSantirez<p> 787821d3294cSantirezThe default value for <code>whence</code> is <code>"cur"</code>, 787921d3294cSantirezand for <code>offset</code> is 0. 788021d3294cSantirezTherefore, the call <code>file:seek()</code> returns the current 788121d3294cSantirezfile position, without changing it; 788221d3294cSantirezthe call <code>file:seek("set")</code> sets the position to the 788321d3294cSantirezbeginning of the file (and returns 0); 788421d3294cSantirezand the call <code>file:seek("end")</code> sets the position to the 788521d3294cSantirezend of the file, and returns its size. 788621d3294cSantirez 788721d3294cSantirez 788821d3294cSantirez 788921d3294cSantirez 789021d3294cSantirez<p> 789121d3294cSantirez<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> 789221d3294cSantirez 789321d3294cSantirez 789421d3294cSantirez<p> 789521d3294cSantirezSets the buffering mode for an output file. 789621d3294cSantirezThere are three available modes: 789721d3294cSantirez 789821d3294cSantirez<ul> 789921d3294cSantirez 790021d3294cSantirez<li><b>"no":</b> 790121d3294cSantirezno buffering; the result of any output operation appears immediately. 790221d3294cSantirez</li> 790321d3294cSantirez 790421d3294cSantirez<li><b>"full":</b> 790521d3294cSantirezfull buffering; output operation is performed only 790621d3294cSantirezwhen the buffer is full (or when you explicitly <code>flush</code> the file 790721d3294cSantirez(see <a href="#pdf-io.flush"><code>io.flush</code></a>)). 790821d3294cSantirez</li> 790921d3294cSantirez 791021d3294cSantirez<li><b>"line":</b> 791121d3294cSantirezline buffering; output is buffered until a newline is output 791221d3294cSantirezor there is any input from some special files 791321d3294cSantirez(such as a terminal device). 791421d3294cSantirez</li> 791521d3294cSantirez 791621d3294cSantirez</ul><p> 791721d3294cSantirezFor the last two cases, <code>size</code> 791821d3294cSantirezspecifies the size of the buffer, in bytes. 791921d3294cSantirezThe default is an appropriate size. 792021d3294cSantirez 792121d3294cSantirez 792221d3294cSantirez 792321d3294cSantirez 792421d3294cSantirez<p> 792521d3294cSantirez<hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> 792621d3294cSantirez 792721d3294cSantirez 792821d3294cSantirez<p> 792921d3294cSantirezWrites the value of each of its arguments to 793021d3294cSantirezthe <code>file</code>. 793121d3294cSantirezThe arguments must be strings or numbers. 793221d3294cSantirezTo write other values, 793321d3294cSantirezuse <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.format"><code>string.format</code></a> before <code>write</code>. 793421d3294cSantirez 793521d3294cSantirez 793621d3294cSantirez 793721d3294cSantirez 793821d3294cSantirez 793921d3294cSantirez 794021d3294cSantirez 794121d3294cSantirez<h2>5.8 - <a name="5.8">Operating System Facilities</a></h2> 794221d3294cSantirez 794321d3294cSantirez<p> 794421d3294cSantirezThis library is implemented through table <a name="pdf-os"><code>os</code></a>. 794521d3294cSantirez 794621d3294cSantirez 794721d3294cSantirez<p> 794821d3294cSantirez<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> 794921d3294cSantirez 795021d3294cSantirez 795121d3294cSantirez<p> 795221d3294cSantirezReturns an approximation of the amount in seconds of CPU time 795321d3294cSantirezused by the program. 795421d3294cSantirez 795521d3294cSantirez 795621d3294cSantirez 795721d3294cSantirez 795821d3294cSantirez<p> 795921d3294cSantirez<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> 796021d3294cSantirez 796121d3294cSantirez 796221d3294cSantirez<p> 796321d3294cSantirezReturns a string or a table containing date and time, 796421d3294cSantirezformatted according to the given string <code>format</code>. 796521d3294cSantirez 796621d3294cSantirez 796721d3294cSantirez<p> 796821d3294cSantirezIf the <code>time</code> argument is present, 796921d3294cSantirezthis is the time to be formatted 797021d3294cSantirez(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). 797121d3294cSantirezOtherwise, <code>date</code> formats the current time. 797221d3294cSantirez 797321d3294cSantirez 797421d3294cSantirez<p> 797521d3294cSantirezIf <code>format</code> starts with '<code>!</code>', 797621d3294cSantirezthen the date is formatted in Coordinated Universal Time. 797721d3294cSantirezAfter this optional character, 797821d3294cSantirezif <code>format</code> is the string "<code>*t</code>", 797921d3294cSantirezthen <code>date</code> returns a table with the following fields: 798021d3294cSantirez<code>year</code> (four digits), <code>month</code> (1--12), <code>day</code> (1--31), 798121d3294cSantirez<code>hour</code> (0--23), <code>min</code> (0--59), <code>sec</code> (0--61), 798221d3294cSantirez<code>wday</code> (weekday, Sunday is 1), 798321d3294cSantirez<code>yday</code> (day of the year), 798421d3294cSantirezand <code>isdst</code> (daylight saving flag, a boolean). 798521d3294cSantirez 798621d3294cSantirez 798721d3294cSantirez<p> 798821d3294cSantirezIf <code>format</code> is not "<code>*t</code>", 798921d3294cSantirezthen <code>date</code> returns the date as a string, 799021d3294cSantirezformatted according to the same rules as the C function <code>strftime</code>. 799121d3294cSantirez 799221d3294cSantirez 799321d3294cSantirez<p> 799421d3294cSantirezWhen called without arguments, 799521d3294cSantirez<code>date</code> returns a reasonable date and time representation that depends on 799621d3294cSantirezthe host system and on the current locale 799721d3294cSantirez(that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>). 799821d3294cSantirez 799921d3294cSantirez 800021d3294cSantirez 800121d3294cSantirez 800221d3294cSantirez<p> 800321d3294cSantirez<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> 800421d3294cSantirez 800521d3294cSantirez 800621d3294cSantirez<p> 800721d3294cSantirezReturns the number of seconds from time <code>t1</code> to time <code>t2</code>. 800821d3294cSantirezIn POSIX, Windows, and some other systems, 800921d3294cSantirezthis value is exactly <code>t2</code><em>-</em><code>t1</code>. 801021d3294cSantirez 801121d3294cSantirez 801221d3294cSantirez 801321d3294cSantirez 801421d3294cSantirez<p> 801521d3294cSantirez<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> 801621d3294cSantirez 801721d3294cSantirez 801821d3294cSantirez<p> 801921d3294cSantirezThis function is equivalent to the C function <code>system</code>. 802021d3294cSantirezIt passes <code>command</code> to be executed by an operating system shell. 802121d3294cSantirezIt returns a status code, which is system-dependent. 802221d3294cSantirezIf <code>command</code> is absent, then it returns nonzero if a shell is available 802321d3294cSantirezand zero otherwise. 802421d3294cSantirez 802521d3294cSantirez 802621d3294cSantirez 802721d3294cSantirez 802821d3294cSantirez<p> 802921d3294cSantirez<hr><h3><a name="pdf-os.exit"><code>os.exit ([code])</code></a></h3> 803021d3294cSantirez 803121d3294cSantirez 803221d3294cSantirez<p> 803321d3294cSantirezCalls the C function <code>exit</code>, 803421d3294cSantirezwith an optional <code>code</code>, 803521d3294cSantirezto terminate the host program. 803621d3294cSantirezThe default value for <code>code</code> is the success code. 803721d3294cSantirez 803821d3294cSantirez 803921d3294cSantirez 804021d3294cSantirez 804121d3294cSantirez<p> 804221d3294cSantirez<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> 804321d3294cSantirez 804421d3294cSantirez 804521d3294cSantirez<p> 804621d3294cSantirezReturns the value of the process environment variable <code>varname</code>, 804721d3294cSantirezor <b>nil</b> if the variable is not defined. 804821d3294cSantirez 804921d3294cSantirez 805021d3294cSantirez 805121d3294cSantirez 805221d3294cSantirez<p> 805321d3294cSantirez<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> 805421d3294cSantirez 805521d3294cSantirez 805621d3294cSantirez<p> 805721d3294cSantirezDeletes the file or directory with the given name. 805821d3294cSantirezDirectories must be empty to be removed. 805921d3294cSantirezIf this function fails, it returns <b>nil</b>, 806021d3294cSantirezplus a string describing the error. 806121d3294cSantirez 806221d3294cSantirez 806321d3294cSantirez 806421d3294cSantirez 806521d3294cSantirez<p> 806621d3294cSantirez<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> 806721d3294cSantirez 806821d3294cSantirez 806921d3294cSantirez<p> 807021d3294cSantirezRenames file or directory named <code>oldname</code> to <code>newname</code>. 807121d3294cSantirezIf this function fails, it returns <b>nil</b>, 807221d3294cSantirezplus a string describing the error. 807321d3294cSantirez 807421d3294cSantirez 807521d3294cSantirez 807621d3294cSantirez 807721d3294cSantirez<p> 807821d3294cSantirez<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> 807921d3294cSantirez 808021d3294cSantirez 808121d3294cSantirez<p> 808221d3294cSantirezSets the current locale of the program. 808321d3294cSantirez<code>locale</code> is a string specifying a locale; 808421d3294cSantirez<code>category</code> is an optional string describing which category to change: 808521d3294cSantirez<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, 808621d3294cSantirez<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; 808721d3294cSantirezthe default category is <code>"all"</code>. 808821d3294cSantirezThe function returns the name of the new locale, 808921d3294cSantirezor <b>nil</b> if the request cannot be honored. 809021d3294cSantirez 809121d3294cSantirez 809221d3294cSantirez<p> 809321d3294cSantirezIf <code>locale</code> is the empty string, 809421d3294cSantirezthe current locale is set to an implementation-defined native locale. 809521d3294cSantirezIf <code>locale</code> is the string "<code>C</code>", 809621d3294cSantirezthe current locale is set to the standard C locale. 809721d3294cSantirez 809821d3294cSantirez 809921d3294cSantirez<p> 810021d3294cSantirezWhen called with <b>nil</b> as the first argument, 810121d3294cSantirezthis function only returns the name of the current locale 810221d3294cSantirezfor the given category. 810321d3294cSantirez 810421d3294cSantirez 810521d3294cSantirez 810621d3294cSantirez 810721d3294cSantirez<p> 810821d3294cSantirez<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> 810921d3294cSantirez 811021d3294cSantirez 811121d3294cSantirez<p> 811221d3294cSantirezReturns the current time when called without arguments, 811321d3294cSantirezor a time representing the date and time specified by the given table. 811421d3294cSantirezThis table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, 811521d3294cSantirezand may have fields <code>hour</code>, <code>min</code>, <code>sec</code>, and <code>isdst</code> 811621d3294cSantirez(for a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function). 811721d3294cSantirez 811821d3294cSantirez 811921d3294cSantirez<p> 812021d3294cSantirezThe returned value is a number, whose meaning depends on your system. 812121d3294cSantirezIn POSIX, Windows, and some other systems, this number counts the number 812221d3294cSantirezof seconds since some given start time (the "epoch"). 812321d3294cSantirezIn other systems, the meaning is not specified, 812421d3294cSantirezand the number returned by <code>time</code> can be used only as an argument to 812521d3294cSantirez<code>date</code> and <code>difftime</code>. 812621d3294cSantirez 812721d3294cSantirez 812821d3294cSantirez 812921d3294cSantirez 813021d3294cSantirez<p> 813121d3294cSantirez<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> 813221d3294cSantirez 813321d3294cSantirez 813421d3294cSantirez<p> 813521d3294cSantirezReturns a string with a file name that can 813621d3294cSantirezbe used for a temporary file. 813721d3294cSantirezThe file must be explicitly opened before its use 813821d3294cSantirezand explicitly removed when no longer needed. 813921d3294cSantirez 814021d3294cSantirez 814121d3294cSantirez<p> 814221d3294cSantirezOn some systems (POSIX), 814321d3294cSantirezthis function also creates a file with that name, 814421d3294cSantirezto avoid security risks. 814521d3294cSantirez(Someone else might create the file with wrong permissions 814621d3294cSantirezin the time between getting the name and creating the file.) 814721d3294cSantirezYou still have to open the file to use it 814821d3294cSantirezand to remove it (even if you do not use it). 814921d3294cSantirez 815021d3294cSantirez 815121d3294cSantirez<p> 815221d3294cSantirezWhen possible, 815321d3294cSantirezyou may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, 815421d3294cSantirezwhich automatically removes the file when the program ends. 815521d3294cSantirez 815621d3294cSantirez 815721d3294cSantirez 815821d3294cSantirez 815921d3294cSantirez 816021d3294cSantirez 816121d3294cSantirez 816221d3294cSantirez<h2>5.9 - <a name="5.9">The Debug Library</a></h2> 816321d3294cSantirez 816421d3294cSantirez<p> 816521d3294cSantirezThis library provides 816621d3294cSantirezthe functionality of the debug interface to Lua programs. 816721d3294cSantirezYou should exert care when using this library. 816821d3294cSantirezThe functions provided here should be used exclusively for debugging 816921d3294cSantirezand similar tasks, such as profiling. 817021d3294cSantirezPlease resist the temptation to use them as a 817121d3294cSantirezusual programming tool: 817221d3294cSantirezthey can be very slow. 817321d3294cSantirezMoreover, several of these functions 817421d3294cSantirezviolate some assumptions about Lua code 817521d3294cSantirez(e.g., that variables local to a function 817621d3294cSantirezcannot be accessed from outside or 817721d3294cSantirezthat userdata metatables cannot be changed by Lua code) 817821d3294cSantirezand therefore can compromise otherwise secure code. 817921d3294cSantirez 818021d3294cSantirez 818121d3294cSantirez<p> 818221d3294cSantirezAll functions in this library are provided 818321d3294cSantirezinside the <a name="pdf-debug"><code>debug</code></a> table. 818421d3294cSantirezAll functions that operate over a thread 818521d3294cSantirezhave an optional first argument which is the 818621d3294cSantirezthread to operate over. 818721d3294cSantirezThe default is always the current thread. 818821d3294cSantirez 818921d3294cSantirez 819021d3294cSantirez<p> 819121d3294cSantirez<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> 819221d3294cSantirez 819321d3294cSantirez 819421d3294cSantirez<p> 819521d3294cSantirezEnters an interactive mode with the user, 819621d3294cSantirezrunning each string that the user enters. 819721d3294cSantirezUsing simple commands and other debug facilities, 819821d3294cSantirezthe user can inspect global and local variables, 819921d3294cSantirezchange their values, evaluate expressions, and so on. 820021d3294cSantirezA line containing only the word <code>cont</code> finishes this function, 820121d3294cSantirezso that the caller continues its execution. 820221d3294cSantirez 820321d3294cSantirez 820421d3294cSantirez<p> 820521d3294cSantirezNote that commands for <code>debug.debug</code> are not lexically nested 820621d3294cSantirezwithin any function, and so have no direct access to local variables. 820721d3294cSantirez 820821d3294cSantirez 820921d3294cSantirez 821021d3294cSantirez 821121d3294cSantirez<p> 821221d3294cSantirez<hr><h3><a name="pdf-debug.getfenv"><code>debug.getfenv (o)</code></a></h3> 821321d3294cSantirezReturns the environment of object <code>o</code>. 821421d3294cSantirez 821521d3294cSantirez 821621d3294cSantirez 821721d3294cSantirez 821821d3294cSantirez<p> 821921d3294cSantirez<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> 822021d3294cSantirez 822121d3294cSantirez 822221d3294cSantirez<p> 822321d3294cSantirezReturns the current hook settings of the thread, as three values: 822421d3294cSantirezthe current hook function, the current hook mask, 822521d3294cSantirezand the current hook count 822621d3294cSantirez(as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). 822721d3294cSantirez 822821d3294cSantirez 822921d3294cSantirez 823021d3294cSantirez 823121d3294cSantirez<p> 823221d3294cSantirez<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] function [, what])</code></a></h3> 823321d3294cSantirez 823421d3294cSantirez 823521d3294cSantirez<p> 823621d3294cSantirezReturns a table with information about a function. 823721d3294cSantirezYou can give the function directly, 823821d3294cSantirezor you can give a number as the value of <code>function</code>, 823921d3294cSantirezwhich means the function running at level <code>function</code> of the call stack 824021d3294cSantirezof the given thread: 824121d3294cSantirezlevel 0 is the current function (<code>getinfo</code> itself); 824221d3294cSantirezlevel 1 is the function that called <code>getinfo</code>; 824321d3294cSantirezand so on. 824421d3294cSantirezIf <code>function</code> is a number larger than the number of active functions, 824521d3294cSantirezthen <code>getinfo</code> returns <b>nil</b>. 824621d3294cSantirez 824721d3294cSantirez 824821d3294cSantirez<p> 824921d3294cSantirezThe returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, 825021d3294cSantirezwith the string <code>what</code> describing which fields to fill in. 825121d3294cSantirezThe default for <code>what</code> is to get all information available, 825221d3294cSantirezexcept the table of valid lines. 825321d3294cSantirezIf present, 825421d3294cSantirezthe option '<code>f</code>' 825521d3294cSantirezadds a field named <code>func</code> with the function itself. 825621d3294cSantirezIf present, 825721d3294cSantirezthe option '<code>L</code>' 825821d3294cSantirezadds a field named <code>activelines</code> with the table of 825921d3294cSantirezvalid lines. 826021d3294cSantirez 826121d3294cSantirez 826221d3294cSantirez<p> 826321d3294cSantirezFor instance, the expression <code>debug.getinfo(1,"n").name</code> returns 826421d3294cSantireza table with a name for the current function, 826521d3294cSantirezif a reasonable name can be found, 826621d3294cSantirezand the expression <code>debug.getinfo(print)</code> 826721d3294cSantirezreturns a table with all available information 826821d3294cSantirezabout the <a href="#pdf-print"><code>print</code></a> function. 826921d3294cSantirez 827021d3294cSantirez 827121d3294cSantirez 827221d3294cSantirez 827321d3294cSantirez<p> 827421d3294cSantirez<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] level, local)</code></a></h3> 827521d3294cSantirez 827621d3294cSantirez 827721d3294cSantirez<p> 827821d3294cSantirezThis function returns the name and the value of the local variable 827921d3294cSantirezwith index <code>local</code> of the function at level <code>level</code> of the stack. 828021d3294cSantirez(The first parameter or local variable has index 1, and so on, 828121d3294cSantirezuntil the last active local variable.) 828221d3294cSantirezThe function returns <b>nil</b> if there is no local 828321d3294cSantirezvariable with the given index, 828421d3294cSantirezand raises an error when called with a <code>level</code> out of range. 828521d3294cSantirez(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) 828621d3294cSantirez 828721d3294cSantirez 828821d3294cSantirez<p> 828921d3294cSantirezVariable names starting with '<code>(</code>' (open parentheses) 829021d3294cSantirezrepresent internal variables 829121d3294cSantirez(loop control variables, temporaries, and C function locals). 829221d3294cSantirez 829321d3294cSantirez 829421d3294cSantirez 829521d3294cSantirez 829621d3294cSantirez<p> 829721d3294cSantirez<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (object)</code></a></h3> 829821d3294cSantirez 829921d3294cSantirez 830021d3294cSantirez<p> 830121d3294cSantirezReturns the metatable of the given <code>object</code> 830221d3294cSantirezor <b>nil</b> if it does not have a metatable. 830321d3294cSantirez 830421d3294cSantirez 830521d3294cSantirez 830621d3294cSantirez 830721d3294cSantirez<p> 830821d3294cSantirez<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> 830921d3294cSantirez 831021d3294cSantirez 831121d3294cSantirez<p> 831221d3294cSantirezReturns the registry table (see <a href="#3.5">§3.5</a>). 831321d3294cSantirez 831421d3294cSantirez 831521d3294cSantirez 831621d3294cSantirez 831721d3294cSantirez<p> 831821d3294cSantirez<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (func, up)</code></a></h3> 831921d3294cSantirez 832021d3294cSantirez 832121d3294cSantirez<p> 832221d3294cSantirezThis function returns the name and the value of the upvalue 832321d3294cSantirezwith index <code>up</code> of the function <code>func</code>. 832421d3294cSantirezThe function returns <b>nil</b> if there is no upvalue with the given index. 832521d3294cSantirez 832621d3294cSantirez 832721d3294cSantirez 832821d3294cSantirez 832921d3294cSantirez<p> 833021d3294cSantirez<hr><h3><a name="pdf-debug.setfenv"><code>debug.setfenv (object, table)</code></a></h3> 833121d3294cSantirez 833221d3294cSantirez 833321d3294cSantirez<p> 833421d3294cSantirezSets the environment of the given <code>object</code> to the given <code>table</code>. 833521d3294cSantirezReturns <code>object</code>. 833621d3294cSantirez 833721d3294cSantirez 833821d3294cSantirez 833921d3294cSantirez 834021d3294cSantirez<p> 834121d3294cSantirez<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> 834221d3294cSantirez 834321d3294cSantirez 834421d3294cSantirez<p> 834521d3294cSantirezSets the given function as a hook. 834621d3294cSantirezThe string <code>mask</code> and the number <code>count</code> describe 834721d3294cSantirezwhen the hook will be called. 834821d3294cSantirezThe string mask may have the following characters, 834921d3294cSantirezwith the given meaning: 835021d3294cSantirez 835121d3294cSantirez<ul> 835221d3294cSantirez<li><b><code>"c"</code>:</b> the hook is called every time Lua calls a function;</li> 835321d3294cSantirez<li><b><code>"r"</code>:</b> the hook is called every time Lua returns from a function;</li> 835421d3294cSantirez<li><b><code>"l"</code>:</b> the hook is called every time Lua enters a new line of code.</li> 835521d3294cSantirez</ul><p> 835621d3294cSantirezWith a <code>count</code> different from zero, 835721d3294cSantirezthe hook is called after every <code>count</code> instructions. 835821d3294cSantirez 835921d3294cSantirez 836021d3294cSantirez<p> 836121d3294cSantirezWhen called without arguments, 836221d3294cSantirez<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. 836321d3294cSantirez 836421d3294cSantirez 836521d3294cSantirez<p> 836621d3294cSantirezWhen the hook is called, its first parameter is a string 836721d3294cSantirezdescribing the event that has triggered its call: 836821d3294cSantirez<code>"call"</code>, <code>"return"</code> (or <code>"tail return"</code>, 836921d3294cSantirezwhen simulating a return from a tail call), 837021d3294cSantirez<code>"line"</code>, and <code>"count"</code>. 837121d3294cSantirezFor line events, 837221d3294cSantirezthe hook also gets the new line number as its second parameter. 837321d3294cSantirezInside a hook, 837421d3294cSantirezyou can call <code>getinfo</code> with level 2 to get more information about 837521d3294cSantirezthe running function 837621d3294cSantirez(level 0 is the <code>getinfo</code> function, 837721d3294cSantirezand level 1 is the hook function), 837821d3294cSantirezunless the event is <code>"tail return"</code>. 837921d3294cSantirezIn this case, Lua is only simulating the return, 838021d3294cSantirezand a call to <code>getinfo</code> will return invalid data. 838121d3294cSantirez 838221d3294cSantirez 838321d3294cSantirez 838421d3294cSantirez 838521d3294cSantirez<p> 838621d3294cSantirez<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> 838721d3294cSantirez 838821d3294cSantirez 838921d3294cSantirez<p> 839021d3294cSantirezThis function assigns the value <code>value</code> to the local variable 839121d3294cSantirezwith index <code>local</code> of the function at level <code>level</code> of the stack. 839221d3294cSantirezThe function returns <b>nil</b> if there is no local 839321d3294cSantirezvariable with the given index, 839421d3294cSantirezand raises an error when called with a <code>level</code> out of range. 839521d3294cSantirez(You can call <code>getinfo</code> to check whether the level is valid.) 839621d3294cSantirezOtherwise, it returns the name of the local variable. 839721d3294cSantirez 839821d3294cSantirez 839921d3294cSantirez 840021d3294cSantirez 840121d3294cSantirez<p> 840221d3294cSantirez<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (object, table)</code></a></h3> 840321d3294cSantirez 840421d3294cSantirez 840521d3294cSantirez<p> 840621d3294cSantirezSets the metatable for the given <code>object</code> to the given <code>table</code> 840721d3294cSantirez(which can be <b>nil</b>). 840821d3294cSantirez 840921d3294cSantirez 841021d3294cSantirez 841121d3294cSantirez 841221d3294cSantirez<p> 841321d3294cSantirez<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (func, up, value)</code></a></h3> 841421d3294cSantirez 841521d3294cSantirez 841621d3294cSantirez<p> 841721d3294cSantirezThis function assigns the value <code>value</code> to the upvalue 841821d3294cSantirezwith index <code>up</code> of the function <code>func</code>. 841921d3294cSantirezThe function returns <b>nil</b> if there is no upvalue 842021d3294cSantirezwith the given index. 842121d3294cSantirezOtherwise, it returns the name of the upvalue. 842221d3294cSantirez 842321d3294cSantirez 842421d3294cSantirez 842521d3294cSantirez 842621d3294cSantirez<p> 8427*214adc50Santirez<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> 842821d3294cSantirez 842921d3294cSantirez 843021d3294cSantirez<p> 843121d3294cSantirezReturns a string with a traceback of the call stack. 843221d3294cSantirezAn optional <code>message</code> string is appended 843321d3294cSantirezat the beginning of the traceback. 843421d3294cSantirezAn optional <code>level</code> number tells at which level 843521d3294cSantirezto start the traceback 843621d3294cSantirez(default is 1, the function calling <code>traceback</code>). 843721d3294cSantirez 843821d3294cSantirez 843921d3294cSantirez 844021d3294cSantirez 844121d3294cSantirez 844221d3294cSantirez 844321d3294cSantirez 844421d3294cSantirez<h1>6 - <a name="6">Lua Stand-alone</a></h1> 844521d3294cSantirez 844621d3294cSantirez<p> 844721d3294cSantirezAlthough Lua has been designed as an extension language, 844821d3294cSantirezto be embedded in a host C program, 844921d3294cSantirezit is also frequently used as a stand-alone language. 845021d3294cSantirezAn interpreter for Lua as a stand-alone language, 845121d3294cSantirezcalled simply <code>lua</code>, 845221d3294cSantirezis provided with the standard distribution. 845321d3294cSantirezThe stand-alone interpreter includes 845421d3294cSantirezall standard libraries, including the debug library. 845521d3294cSantirezIts usage is: 845621d3294cSantirez 845721d3294cSantirez<pre> 845821d3294cSantirez lua [options] [script [args]] 845921d3294cSantirez</pre><p> 846021d3294cSantirezThe options are: 846121d3294cSantirez 846221d3294cSantirez<ul> 846321d3294cSantirez<li><b><code>-e <em>stat</em></code>:</b> executes string <em>stat</em>;</li> 846421d3294cSantirez<li><b><code>-l <em>mod</em></code>:</b> "requires" <em>mod</em>;</li> 846521d3294cSantirez<li><b><code>-i</code>:</b> enters interactive mode after running <em>script</em>;</li> 846621d3294cSantirez<li><b><code>-v</code>:</b> prints version information;</li> 846721d3294cSantirez<li><b><code>--</code>:</b> stops handling options;</li> 846821d3294cSantirez<li><b><code>-</code>:</b> executes <code>stdin</code> as a file and stops handling options.</li> 846921d3294cSantirez</ul><p> 847021d3294cSantirezAfter handling its options, <code>lua</code> runs the given <em>script</em>, 847121d3294cSantirezpassing to it the given <em>args</em> as string arguments. 847221d3294cSantirezWhen called without arguments, 847321d3294cSantirez<code>lua</code> behaves as <code>lua -v -i</code> 847421d3294cSantirezwhen the standard input (<code>stdin</code>) is a terminal, 847521d3294cSantirezand as <code>lua -</code> otherwise. 847621d3294cSantirez 847721d3294cSantirez 847821d3294cSantirez<p> 847921d3294cSantirezBefore running any argument, 848021d3294cSantirezthe interpreter checks for an environment variable <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a>. 848121d3294cSantirezIf its format is <code>@<em>filename</em></code>, 848221d3294cSantirezthen <code>lua</code> executes the file. 848321d3294cSantirezOtherwise, <code>lua</code> executes the string itself. 848421d3294cSantirez 848521d3294cSantirez 848621d3294cSantirez<p> 848721d3294cSantirezAll options are handled in order, except <code>-i</code>. 848821d3294cSantirezFor instance, an invocation like 848921d3294cSantirez 849021d3294cSantirez<pre> 849121d3294cSantirez $ lua -e'a=1' -e 'print(a)' script.lua 849221d3294cSantirez</pre><p> 849321d3294cSantirezwill first set <code>a</code> to 1, then print the value of <code>a</code> (which is '<code>1</code>'), 849421d3294cSantirezand finally run the file <code>script.lua</code> with no arguments. 849521d3294cSantirez(Here <code>$</code> is the shell prompt. Your prompt may be different.) 849621d3294cSantirez 849721d3294cSantirez 849821d3294cSantirez<p> 849921d3294cSantirezBefore starting to run the script, 850021d3294cSantirez<code>lua</code> collects all arguments in the command line 850121d3294cSantirezin a global table called <code>arg</code>. 850221d3294cSantirezThe script name is stored at index 0, 850321d3294cSantirezthe first argument after the script name goes to index 1, 850421d3294cSantirezand so on. 850521d3294cSantirezAny arguments before the script name 850621d3294cSantirez(that is, the interpreter name plus the options) 850721d3294cSantirezgo to negative indices. 850821d3294cSantirezFor instance, in the call 850921d3294cSantirez 851021d3294cSantirez<pre> 851121d3294cSantirez $ lua -la b.lua t1 t2 851221d3294cSantirez</pre><p> 851321d3294cSantirezthe interpreter first runs the file <code>a.lua</code>, 851421d3294cSantirezthen creates a table 851521d3294cSantirez 851621d3294cSantirez<pre> 851721d3294cSantirez arg = { [-2] = "lua", [-1] = "-la", 851821d3294cSantirez [0] = "b.lua", 851921d3294cSantirez [1] = "t1", [2] = "t2" } 852021d3294cSantirez</pre><p> 852121d3294cSantirezand finally runs the file <code>b.lua</code>. 852221d3294cSantirezThe script is called with <code>arg[1]</code>, <code>arg[2]</code>, ··· 852321d3294cSantirezas arguments; 852421d3294cSantirezit can also access these arguments with the vararg expression '<code>...</code>'. 852521d3294cSantirez 852621d3294cSantirez 852721d3294cSantirez<p> 852821d3294cSantirezIn interactive mode, 852921d3294cSantirezif you write an incomplete statement, 853021d3294cSantirezthe interpreter waits for its completion 853121d3294cSantirezby issuing a different prompt. 853221d3294cSantirez 853321d3294cSantirez 853421d3294cSantirez<p> 853521d3294cSantirezIf the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, 853621d3294cSantirezthen its value is used as the prompt. 853721d3294cSantirezSimilarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, 853821d3294cSantirezits value is used as the secondary prompt 853921d3294cSantirez(issued during incomplete statements). 854021d3294cSantirezTherefore, both prompts can be changed directly on the command line 854121d3294cSantirezor in any Lua programs by assigning to <code>_PROMPT</code>. 854221d3294cSantirezSee the next example: 854321d3294cSantirez 854421d3294cSantirez<pre> 854521d3294cSantirez $ lua -e"_PROMPT='myprompt> '" -i 854621d3294cSantirez</pre><p> 854721d3294cSantirez(The outer pair of quotes is for the shell, 854821d3294cSantirezthe inner pair is for Lua.) 854921d3294cSantirezNote the use of <code>-i</code> to enter interactive mode; 855021d3294cSantirezotherwise, 855121d3294cSantirezthe program would just end silently 855221d3294cSantirezright after the assignment to <code>_PROMPT</code>. 855321d3294cSantirez 855421d3294cSantirez 855521d3294cSantirez<p> 855621d3294cSantirezTo allow the use of Lua as a 855721d3294cSantirezscript interpreter in Unix systems, 855821d3294cSantirezthe stand-alone interpreter skips 855921d3294cSantirezthe first line of a chunk if it starts with <code>#</code>. 856021d3294cSantirezTherefore, Lua scripts can be made into executable programs 856121d3294cSantirezby using <code>chmod +x</code> and the <code>#!</code> form, 856221d3294cSantirezas in 856321d3294cSantirez 856421d3294cSantirez<pre> 856521d3294cSantirez #!/usr/local/bin/lua 856621d3294cSantirez</pre><p> 856721d3294cSantirez(Of course, 856821d3294cSantirezthe location of the Lua interpreter may be different in your machine. 856921d3294cSantirezIf <code>lua</code> is in your <code>PATH</code>, 857021d3294cSantirezthen 857121d3294cSantirez 857221d3294cSantirez<pre> 857321d3294cSantirez #!/usr/bin/env lua 857421d3294cSantirez</pre><p> 857521d3294cSantirezis a more portable solution.) 857621d3294cSantirez 857721d3294cSantirez 857821d3294cSantirez 857921d3294cSantirez<h1>7 - <a name="7">Incompatibilities with the Previous Version</a></h1> 858021d3294cSantirez 858121d3294cSantirez<p> 858221d3294cSantirezHere we list the incompatibilities that you may find when moving a program 858321d3294cSantirezfrom Lua 5.0 to Lua 5.1. 858421d3294cSantirezYou can avoid most of the incompatibilities compiling Lua with 858521d3294cSantirezappropriate options (see file <code>luaconf.h</code>). 858621d3294cSantirezHowever, 858721d3294cSantirezall these compatibility options will be removed in the next version of Lua. 858821d3294cSantirez 858921d3294cSantirez 859021d3294cSantirez 859121d3294cSantirez<h2>7.1 - <a name="7.1">Changes in the Language</a></h2> 859221d3294cSantirez<ul> 859321d3294cSantirez 859421d3294cSantirez<li> 859521d3294cSantirezThe vararg system changed from the pseudo-argument <code>arg</code> with a 859621d3294cSantireztable with the extra arguments to the vararg expression. 859721d3294cSantirez(See compile-time option <code>LUA_COMPAT_VARARG</code> in <code>luaconf.h</code>.) 859821d3294cSantirez</li> 859921d3294cSantirez 860021d3294cSantirez<li> 860121d3294cSantirezThere was a subtle change in the scope of the implicit 860221d3294cSantirezvariables of the <b>for</b> statement and for the <b>repeat</b> statement. 860321d3294cSantirez</li> 860421d3294cSantirez 860521d3294cSantirez<li> 860621d3294cSantirezThe long string/long comment syntax (<code>[[<em>string</em>]]</code>) 860721d3294cSantirezdoes not allow nesting. 860821d3294cSantirezYou can use the new syntax (<code>[=[<em>string</em>]=]</code>) in these cases. 860921d3294cSantirez(See compile-time option <code>LUA_COMPAT_LSTR</code> in <code>luaconf.h</code>.) 861021d3294cSantirez</li> 861121d3294cSantirez 861221d3294cSantirez</ul> 861321d3294cSantirez 861421d3294cSantirez 861521d3294cSantirez 861621d3294cSantirez 861721d3294cSantirez<h2>7.2 - <a name="7.2">Changes in the Libraries</a></h2> 861821d3294cSantirez<ul> 861921d3294cSantirez 862021d3294cSantirez<li> 862121d3294cSantirezFunction <code>string.gfind</code> was renamed <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>. 862221d3294cSantirez(See compile-time option <code>LUA_COMPAT_GFIND</code> in <code>luaconf.h</code>.) 862321d3294cSantirez</li> 862421d3294cSantirez 862521d3294cSantirez<li> 862621d3294cSantirezWhen <a href="#pdf-string.gsub"><code>string.gsub</code></a> is called with a function as its 862721d3294cSantirezthird argument, 862821d3294cSantirezwhenever this function returns <b>nil</b> or <b>false</b> the 862921d3294cSantirezreplacement string is the whole match, 863021d3294cSantirezinstead of the empty string. 863121d3294cSantirez</li> 863221d3294cSantirez 863321d3294cSantirez<li> 863421d3294cSantirezFunction <code>table.setn</code> was deprecated. 863521d3294cSantirezFunction <code>table.getn</code> corresponds 863621d3294cSantirezto the new length operator (<code>#</code>); 863721d3294cSantirezuse the operator instead of the function. 863821d3294cSantirez(See compile-time option <code>LUA_COMPAT_GETN</code> in <code>luaconf.h</code>.) 863921d3294cSantirez</li> 864021d3294cSantirez 864121d3294cSantirez<li> 864221d3294cSantirezFunction <code>loadlib</code> was renamed <a href="#pdf-package.loadlib"><code>package.loadlib</code></a>. 864321d3294cSantirez(See compile-time option <code>LUA_COMPAT_LOADLIB</code> in <code>luaconf.h</code>.) 864421d3294cSantirez</li> 864521d3294cSantirez 864621d3294cSantirez<li> 864721d3294cSantirezFunction <code>math.mod</code> was renamed <a href="#pdf-math.fmod"><code>math.fmod</code></a>. 864821d3294cSantirez(See compile-time option <code>LUA_COMPAT_MOD</code> in <code>luaconf.h</code>.) 864921d3294cSantirez</li> 865021d3294cSantirez 865121d3294cSantirez<li> 865221d3294cSantirezFunctions <code>table.foreach</code> and <code>table.foreachi</code> are deprecated. 865321d3294cSantirezYou can use a for loop with <code>pairs</code> or <code>ipairs</code> instead. 865421d3294cSantirez</li> 865521d3294cSantirez 865621d3294cSantirez<li> 865721d3294cSantirezThere were substantial changes in function <a href="#pdf-require"><code>require</code></a> due to 865821d3294cSantirezthe new module system. 865921d3294cSantirezHowever, the new behavior is mostly compatible with the old, 866021d3294cSantirezbut <code>require</code> gets the path from <a href="#pdf-package.path"><code>package.path</code></a> instead 866121d3294cSantirezof from <code>LUA_PATH</code>. 866221d3294cSantirez</li> 866321d3294cSantirez 866421d3294cSantirez<li> 866521d3294cSantirezFunction <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> has different arguments. 866621d3294cSantirezFunction <code>gcinfo</code> is deprecated; 866721d3294cSantirezuse <code>collectgarbage("count")</code> instead. 866821d3294cSantirez</li> 866921d3294cSantirez 867021d3294cSantirez</ul> 867121d3294cSantirez 867221d3294cSantirez 867321d3294cSantirez 867421d3294cSantirez 867521d3294cSantirez<h2>7.3 - <a name="7.3">Changes in the API</a></h2> 867621d3294cSantirez<ul> 867721d3294cSantirez 867821d3294cSantirez<li> 867921d3294cSantirezThe <code>luaopen_*</code> functions (to open libraries) 868021d3294cSantirezcannot be called directly, 868121d3294cSantirezlike a regular C function. 868221d3294cSantirezThey must be called through Lua, 868321d3294cSantirezlike a Lua function. 868421d3294cSantirez</li> 868521d3294cSantirez 868621d3294cSantirez<li> 868721d3294cSantirezFunction <code>lua_open</code> was replaced by <a href="#lua_newstate"><code>lua_newstate</code></a> to 868821d3294cSantirezallow the user to set a memory-allocation function. 868921d3294cSantirezYou can use <a href="#luaL_newstate"><code>luaL_newstate</code></a> from the standard library to 869021d3294cSantirezcreate a state with a standard allocation function 869121d3294cSantirez(based on <code>realloc</code>). 869221d3294cSantirez</li> 869321d3294cSantirez 869421d3294cSantirez<li> 869521d3294cSantirezFunctions <code>luaL_getn</code> and <code>luaL_setn</code> 869621d3294cSantirez(from the auxiliary library) are deprecated. 869721d3294cSantirezUse <a href="#lua_objlen"><code>lua_objlen</code></a> instead of <code>luaL_getn</code> 869821d3294cSantirezand nothing instead of <code>luaL_setn</code>. 869921d3294cSantirez</li> 870021d3294cSantirez 870121d3294cSantirez<li> 870221d3294cSantirezFunction <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><code>luaL_register</code></a>. 870321d3294cSantirez</li> 870421d3294cSantirez 870521d3294cSantirez<li> 870621d3294cSantirezFunction <code>luaL_checkudata</code> now throws an error when the given value 870721d3294cSantirezis not a userdata of the expected type. 870821d3294cSantirez(In Lua 5.0 it returned <code>NULL</code>.) 870921d3294cSantirez</li> 871021d3294cSantirez 871121d3294cSantirez</ul> 871221d3294cSantirez 871321d3294cSantirez 871421d3294cSantirez 871521d3294cSantirez 871621d3294cSantirez<h1>8 - <a name="8">The Complete Syntax of Lua</a></h1> 871721d3294cSantirez 871821d3294cSantirez<p> 871921d3294cSantirezHere is the complete syntax of Lua in extended BNF. 872021d3294cSantirez(It does not describe operator precedences.) 872121d3294cSantirez 872221d3294cSantirez 872321d3294cSantirez 872421d3294cSantirez 872521d3294cSantirez<pre> 872621d3294cSantirez 872721d3294cSantirez chunk ::= {stat [`<b>;</b>´]} [laststat [`<b>;</b>´]] 872821d3294cSantirez 872921d3294cSantirez block ::= chunk 873021d3294cSantirez 873121d3294cSantirez stat ::= varlist `<b>=</b>´ explist | 873221d3294cSantirez functioncall | 873321d3294cSantirez <b>do</b> block <b>end</b> | 873421d3294cSantirez <b>while</b> exp <b>do</b> block <b>end</b> | 873521d3294cSantirez <b>repeat</b> block <b>until</b> exp | 873621d3294cSantirez <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 873721d3294cSantirez <b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b> | 873821d3294cSantirez <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 873921d3294cSantirez <b>function</b> funcname funcbody | 874021d3294cSantirez <b>local</b> <b>function</b> Name funcbody | 874121d3294cSantirez <b>local</b> namelist [`<b>=</b>´ explist] 874221d3294cSantirez 874321d3294cSantirez laststat ::= <b>return</b> [explist] | <b>break</b> 874421d3294cSantirez 874521d3294cSantirez funcname ::= Name {`<b>.</b>´ Name} [`<b>:</b>´ Name] 874621d3294cSantirez 874721d3294cSantirez varlist ::= var {`<b>,</b>´ var} 874821d3294cSantirez 874921d3294cSantirez var ::= Name | prefixexp `<b>[</b>´ exp `<b>]</b>´ | prefixexp `<b>.</b>´ Name 875021d3294cSantirez 875121d3294cSantirez namelist ::= Name {`<b>,</b>´ Name} 875221d3294cSantirez 875321d3294cSantirez explist ::= {exp `<b>,</b>´} exp 875421d3294cSantirez 875521d3294cSantirez exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Number | String | `<b>...</b>´ | function | 875621d3294cSantirez prefixexp | tableconstructor | exp binop exp | unop exp 875721d3294cSantirez 875821d3294cSantirez prefixexp ::= var | functioncall | `<b>(</b>´ exp `<b>)</b>´ 875921d3294cSantirez 876021d3294cSantirez functioncall ::= prefixexp args | prefixexp `<b>:</b>´ Name args 876121d3294cSantirez 876221d3294cSantirez args ::= `<b>(</b>´ [explist] `<b>)</b>´ | tableconstructor | String 876321d3294cSantirez 876421d3294cSantirez function ::= <b>function</b> funcbody 876521d3294cSantirez 876621d3294cSantirez funcbody ::= `<b>(</b>´ [parlist] `<b>)</b>´ block <b>end</b> 876721d3294cSantirez 876821d3294cSantirez parlist ::= namelist [`<b>,</b>´ `<b>...</b>´] | `<b>...</b>´ 876921d3294cSantirez 877021d3294cSantirez tableconstructor ::= `<b>{</b>´ [fieldlist] `<b>}</b>´ 877121d3294cSantirez 877221d3294cSantirez fieldlist ::= field {fieldsep field} [fieldsep] 877321d3294cSantirez 877421d3294cSantirez field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp 877521d3294cSantirez 877621d3294cSantirez fieldsep ::= `<b>,</b>´ | `<b>;</b>´ 877721d3294cSantirez 877821d3294cSantirez binop ::= `<b>+</b>´ | `<b>-</b>´ | `<b>*</b>´ | `<b>/</b>´ | `<b>^</b>´ | `<b>%</b>´ | `<b>..</b>´ | 877921d3294cSantirez `<b><</b>´ | `<b><=</b>´ | `<b>></b>´ | `<b>>=</b>´ | `<b>==</b>´ | `<b>~=</b>´ | 878021d3294cSantirez <b>and</b> | <b>or</b> 878121d3294cSantirez 878221d3294cSantirez unop ::= `<b>-</b>´ | <b>not</b> | `<b>#</b>´ 878321d3294cSantirez 878421d3294cSantirez</pre> 878521d3294cSantirez 878621d3294cSantirez<p> 878721d3294cSantirez 878821d3294cSantirez 878921d3294cSantirez 879021d3294cSantirez 879121d3294cSantirez 879221d3294cSantirez 879321d3294cSantirez 879421d3294cSantirez<HR> 8795*214adc50Santirez<SMALL CLASS="footer"> 879621d3294cSantirezLast update: 8797*214adc50SantirezMon Feb 13 18:54:19 BRST 2012 879821d3294cSantirez</SMALL> 879921d3294cSantirez<!-- 8800*214adc50SantirezLast change: revised for Lua 5.1.5 880121d3294cSantirez--> 880221d3294cSantirez 880321d3294cSantirez</body></html> 880421d3294cSantirez 8805
